【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 平台、后台运营系统等，快速完成从通用框架到业务系统的转化。

总结

项目提供了高度模块化的架构设计，支持灵活部署与多场景应用。后端整合了 Celery、ASGI、Redis 等核心组件，前端基于 Vue3 与 Element Plus 构建，具备良好的用户交互体验。整体设计注重代码解耦与可维护性，便于快速开发和功能拓展。

未来可拓展方向包括多租户逻辑优化、更细粒度的权限控制、数据可视化集成，以及基于微服务的架构重构，以满足更复杂的企业级业务需求。通过持续优化与社区协作，该项目可作为现代全栈项目的高效起点。