【Dv3Admin】从零搭建Git项目安装·配置·初始化

项目采用 Django 与 Vue3 技术栈构建，具备强大的后端扩展能力与现代前端交互体验。完整实现了权限管理、任务队列、WebSocket 通信、系统配置等功能，适用于构建中后台管理系统与多租户平台。

本文章内容涵盖环境搭建、虚拟环境配置、前后端部署、项目结构拆解及默认功能演示，适合具备基础 Python 和前端知识的开发者参考使用。

文章目录

项目部署
项目解析
项目应用
总结

项目部署

项目源代码托管在 Gitee 和 GitHub，推荐使用 Gitee 获取。可通过 Git 命令克隆项目：

git clone https://gitee.com/huge-dream/django-vue3-admin.git

克隆完成后，项目包含两个主要目录：backend 为后端代码，web 为前端代码。

环境配置要求

项目运行对环境有明确要求。后端需 Python 3.9 及以上（推荐 3.11），前端依赖 Node.js 16 或更高版本。默认数据库为 SQLite3，推荐使用 MySQL 8.0 或更高版本（最低支持 5.7）。Redis 为可选组件，但建议使用最新版以提升性能。前端兼容主流现代浏览器，如 Chrome、Firefox、Edge 和 Safari，最低支持版本也已明确标注。由于 Vue3 和 Element Plus 的限制，项目不支持 IE11 及以下浏览器。

环境类别	要求	推荐/说明
Python	≥ 3.9	推荐 3.11
Node.js	≥ 16.0	-
数据库	默认使用 SQLite3	推荐 MySQL 8.0（支持 5.7 及以上）
Redis	可选	推荐最新版
浏览器支持	Chrome ≥ 64
	Firefox ≥ 78
	Edge ≥ 79
	Safari ≥ 12
	IE11 及以下	不支持（Vue3 与 Element Plus 限制）

虚拟环境搭建与配置注意事项

使用虚拟环境可以避免系统 Python 环境污染，建议在 backend 目录下创建并激活虚拟环境：

# 创建虚拟环境（以venv为例）
conda create --name py311 python=3.11

# 激活（Windows）
conda activate py311

激活后，使用 pip 安装后端依赖：

pip install -r requirements.txt

创建配置文件：

cp ./conf/env.example.py ./conf/env.py

根据实际情况修改 env.py 中数据库连接信息。使用 MySQL 时，字符集需设置为 utf8mb4。

数据初始化与项目启动

后端数据库准备完成后，执行迁移和初始化命令：

python manage.py makemigrations
python manage.py migrate
python manage.py init
python manage.py init_area

启动后端服务：

python manage.py runserver 0.0.0.0:8000

或者使用 uvicorn 启动 ASGI 服务：

uvicorn application.asgi:application --host 0.0.0.0 --port 8000 --workers 8

前端环境需要安装依赖：

cd web
npm install yarn
yarn install --registry=https://registry.npmmirror.com

开发环境启动：

yarn build

访问地址为：http://localhost:8080

默认管理员账号为：superadmin，密码：admin123456

Docker 用户可选择使用 docker-compose 方式运行，具体命令和配置详见项目说明。适用于一键部署、插件集成及多人协作环境。

项目解析

目录 application

application 下的 Python 文件构成了一个完整的 Django 后端项目骨架，整合了 ASGI 支持、WebSocket 消息中心、Celery 任务队列、多租户配置、系统与字典配置管理等功能模块。整体架构清晰、职责分明，配置灵活，支持插件扩展和中间件扩展，能够适配多种部署场景。

文件名	作用描述
`asgi.py`	ASGI 入口，配置 WebSocket 与 HTTP 路由，通过 `ProtocolTypeRouter` 处理不同协议，整合认证和权限校验。
`celery.py`	配置 Celery，支持普通模式与多租户模式任务管理，定义任务自动重试逻辑和定时任务记录处理。
`dispatch.py`	管理系统字典与配置的初始化、刷新与缓存，支持多租户模式和 Redis 存储，可动态获取字典项和配置项值。
`routing.py`	定义 WebSocket 路由，当前将所有 `ws/<service_uid>/` 请求交给 `MegCenter` 处理。
`settings.py`	项目核心配置文件，包含数据库、缓存、插件、JWT、REST API、日志、跨域、ASGI/WSGI、静态资源等配置。
`urls.py`	URL 路由入口，整合系统 API 接口、文档视图、前端页面服务和初始化调度。
`websocketConfig.py`	WebSocket 消息中心逻辑处理，实现用户登录后的连接管理、消息推送、在线状态反馈、系统通知分发等。
`wsgi.py`	WSGI 入口，用于传统 HTTP 服务部署（如 Gunicorn），与 `asgi.py` 平行存在。

目录 conf

conf 目录下的 env.py 文件用于集中管理项目运行时的核心环境变量配置，主要包括数据库连接、Redis 缓存、功能开关和运行模式。它被 settings.py 引入，以实现配置解耦，提升灵活性与可维护性。项目默认使用 MySQL 数据库，提供了 Redis 缓存支持，并通过开关控制调试模式、验证码认证、登录日志等功能，适合多场景部署和快速环境切换。

配置项分类	变量名	配置说明
数据库	`DATABASE_ENGINE`	数据库引擎（默认使用 MySQL，可切换为 SQLite）
	`DATABASE_NAME`	数据库名称
	`DATABASE_HOST`	数据库地址
	`DATABASE_PORT`	数据库端口（MySQL 默认 3306）
	`DATABASE_USER`	数据库用户名
	`DATABASE_PASSWORD`	数据库密码
Redis	`REDIS_DB`	默认 Redis 数据库索引
	`CELERY_BROKER_DB`	Celery 使用的 Redis 数据库索引
	`REDIS_PASSWORD`	Redis 认证密码
	`REDIS_HOST`	Redis 地址
	`REDIS_URL`	Redis 连接 URI（用于 Celery 或缓存配置）
功能开关	`DEBUG`	是否开启调试模式
	`ENABLE_LOGIN_ANALYSIS_LOG`	是否启用登录详情日志记录
	`LOGIN_NO_CAPTCHA_AUTH`	是否跳过登录验证码（用于测试）
其他	`ALLOWED_HOSTS`	允许的主机列表
	`COLUMN_EXCLUDE_APPS`	在列权限中排除的 App 列表
	`TABLE_PREFIX`	表名前缀（统一管理表结构）

目录 system

根目录（system/）

这一层是系统模块的核心文件集合，负责模型定义、URL 路由注册、后台配置、异步任务调度及信号处理等，是 Django 应用的基本组成部分。

文件名	类型	职责说明
`__init__.py`	初始化文件	标识为 Python 包
`admin.py`	后台注册	注册模型到 Django 后台管理界面
`apps.py`	应用配置	定义 Django App 的元信息和加载方式
`models.py`	数据模型	定义用户、权限、角色等核心模型
`signals.py`	信号处理	监听模型变化并处理，如同步权限
`tasks.py`	异步任务	定义基于 Celery 的任务，如消息通知等
`tests.py`	单元测试	单元测试入口，默认生成
`urls.py`	路由配置	配置模块 API 接口路径

system/fixtures/ 初始化数据目录

该目录下包含系统初始化时所需的静态 JSON 数据，如菜单、角色、用户、系统配置等，适用于部署时的首次数据填充，同时配有加载逻辑脚本。

文件名	类型	职责说明
`initialize.py`	初始化逻辑	加载所有初始 JSON 文件到数据库中
`initSerializer.py`	序列化支持	用于初始化 JSON 数据的序列化器逻辑
`init_*.json`	JSON 数据	包含菜单、角色、用户等静态初始化数据

system/management/commands/ 自定义命令目录

该目录用于定义 Django 可执行的自定义命令，例如 python manage.py init。这些命令用于初始化数据库、导出 JSON 文件、导入区域数据等操作，适合首次部署和测试时快速恢复初始状态。

文件名	类型	职责说明
`init.py`	自定义命令	初始化系统数据的命令（菜单/角色等）
`init_area.py`	自定义命令	导入区域（省市区）相关数据
`generate_init_json.py`	自定义命令	将当前数据库内容导出为 JSON 格式供初始化使用

system/views/ 目录下的文件主要负责处理系统模块中各类资源的接口请求，包含了用户、角色、菜单、字典、登录、日志、配置等后端视图逻辑。每个文件通常对应一个资源或功能的视图集合，基于 Django REST framework 实现。这一层是业务接口的核心，主要处理前端请求并调用模型和序列化器进行响应，所有接口按资源拆分，遵循 REST 风格，便于维护与扩展。

文件名	职责说明
`api_white_list.py`	管理接口白名单列表（不鉴权接口）
`area.py`	区域数据管理，如省市区信息处理
`clause.py`	平台协议视图（如用户协议、隐私政策）
`dept.py`	部门组织结构的增删改查接口
`dictionary.py`	系统字典项配置的接口
`download_center.py`	下载中心相关接口，管理导出文件记录等
`file_list.py`	上传文件的管理接口
`login.py`	登录/登出、验证码、Token 认证相关接口
`login_log.py`	登录日志记录接口
`menu.py`	菜单配置接口（配合权限系统）
`menu_button.py`	菜单下的按钮权限接口（操作级权限）
`menu_field.py`	菜单字段权限接口（字段级权限）
`message_center.py`	消息中心相关接口，如推送消息、读取状态等
`operation_log.py`	操作日志接口，记录用户操作行为
`role.py`	用户角色管理相关接口
`role_menu.py`	角色与菜单的关联接口
`role_menu_button_permission.py`	角色与按钮权限关联接口
`system_config.py`	系统参数配置项接口
`user.py`	用户管理接口（注册、修改、授权等）

这些视图模块与 models.py 中的模型、serializers/ 中的序列化器、urls.py 中的路由配置紧密配合，构成了系统功能完整的 API 层。

目录 utils

utils 目录是整个项目的基础工具库，汇集了与认证、异常处理、权限控制、分页、导入导出、请求响应等相关的通用逻辑模块。它的设计目的是将项目中高度复用的功能集中管理，解耦业务代码，提升可维护性和扩展性。这些工具类和 Mixin 被广泛应用于视图、序列化器、中间件等多个层级，构成系统稳定运行的底层支撑。

文件名	类型	职责说明
`backends.py`	认证工具	自定义用户认证逻辑（如多种登录方式）
`core_initialize.py`	初始化工具	启动时执行基础初始化的相关功能
`crud_mixin.py`	视图辅助	提供增删改查（CRUD）通用逻辑 Mixin
`exception.py`	异常处理	定义统一异常格式和错误响应处理器
`field_permission.py`	权限控制	字段级权限过滤，支持按字段粒度的访问控制
`filters.py`	查询过滤	自定义过滤器，兼容复杂筛选逻辑
`git_utils.py`	系统工具	Git 相关操作工具类（如获取版本信息）
`import_export.py`	导入导出	实现数据导入导出的基础逻辑
`import_export_mixin.py`	导入导出	为视图提供导入导出能力的 Mixin 类
`json_response.py`	响应封装	提供统一格式化的 JSON 响应结构
`middleware.py`	中间件	包含接口健康检测、日志记录等中间件组件
`models.py`	工具模型	定义抽象基础模型，如通用字段封装等
`pagination.py`	分页工具	自定义分页逻辑，支持统一分页格式输出
`permission.py`	权限控制	定义 API 权限策略类（如管理员判断等）
`request_util.py`	请求工具	处理 request 相关通用功能，如 IP 获取等
`serializers.py`	序列化增强	封装通用序列化器基类及转换方法
`string_util.py`	字符串工具	提供文本处理、加密、清洗等常用方法
`swagger.py`	接口文档	自定义接口文档生成方式（drf_yasg）
`validator.py`	校验工具	表单与字段数据验证逻辑封装
`viewset.py`	视图基类	二次封装 DRF 的视图集，加入日志、权限等扩展

项目应用

使用默认提供的账号（用户名：superadmin，密码：admin123456）登录系统后，用户将进入系统的主控制台界面。该界面展示了系统预设的核心功能模块，包括用户管理、角色权限分配、菜单配置、系统参数设置等。通过这些设置，用户可以快速了解系统结构，体验其权限控制、模块化设计和前后端分离的交互方式。

默认账号具备最高权限，可访问所有功能区域，适用于初次部署、系统初始化和权限体系的搭建。开发者可以在此基础上根据实际业务需求扩展模块、调整逻辑或进行深度定制，如构建企业内部管理系统、SaaS 平台、后台运营系统等，快速完成从通用框架到业务系统的转化。

在这里插入图片描述