项目采用 Django 与 Vue3 技术栈构建具备强大的后端扩展能力与现代前端交互体验。完整实现了权限管理、任务队列、WebSocket 通信、系统配置等功能适用于构建中后台管理系统与多租户平台。本文章内容涵盖环境搭建、虚拟环境配置、前后端部署、项目结构拆解及默认功能演示适合具备基础 Python 和前端知识的开发者参考使用。文章目录项目部署项目解析项目应用总结项目部署项目源代码托管在 Gitee 和 GitHub推荐使用 Gitee 获取。可通过 Git 命令克隆项目gitclone 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.11Node.js≥ 16.0-数据库默认使用 SQLite3推荐 MySQL 8.0支持 5.7 及以上Redis可选推荐最新版浏览器支持Chrome ≥ 64Firefox ≥ 78Edge ≥ 79Safari ≥ 12IE11 及以下不支持Vue3 与 Element Plus 限制虚拟环境搭建与配置注意事项使用虚拟环境可以避免系统 Python 环境污染建议在backend目录下创建并激活虚拟环境# 创建虚拟环境以venv为例conda create--namepy311python3.11# 激活Windowsconda activate py311激活后使用 pip 安装后端依赖pipinstall-rrequirements.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 runserver0.0.0.0:8000或者使用uvicorn启动 ASGI 服务uvicorn application.asgi:application--host0.0.0.0--port8000--workers8前端环境需要安装依赖cdwebnpminstallyarnyarninstall--registryhttps://registry.npmmirror.com开发环境启动yarnbuild访问地址为http://localhost:8080默认管理员账号为superadmin密码admin123456Docker 用户可选择使用docker-compose方式运行具体命令和配置详见项目说明。适用于一键部署、插件集成及多人协作环境。项目解析目录 applicationapplication下的 Python 文件构成了一个完整的 Django 后端项目骨架整合了 ASGI 支持、WebSocket 消息中心、Celery 任务队列、多租户配置、系统与字典配置管理等功能模块。整体架构清晰、职责分明配置灵活支持插件扩展和中间件扩展能够适配多种部署场景。文件名作用描述asgi.pyASGI 入口配置 WebSocket 与 HTTP 路由通过ProtocolTypeRouter处理不同协议整合认证和权限校验。celery.py配置 Celery支持普通模式与多租户模式任务管理定义任务自动重试逻辑和定时任务记录处理。dispatch.py管理系统字典与配置的初始化、刷新与缓存支持多租户模式和 Redis 存储可动态获取字典项和配置项值。routing.py定义 WebSocket 路由当前将所有ws/service_uid/请求交给MegCenter处理。settings.py项目核心配置文件包含数据库、缓存、插件、JWT、REST API、日志、跨域、ASGI/WSGI、静态资源等配置。urls.pyURL 路由入口整合系统 API 接口、文档视图、前端页面服务和初始化调度。websocketConfig.pyWebSocket 消息中心逻辑处理实现用户登录后的连接管理、消息推送、在线状态反馈、系统通知分发等。wsgi.pyWSGI 入口用于传统 HTTP 服务部署如 Gunicorn与asgi.py平行存在。目录 confconf目录下的env.py文件用于集中管理项目运行时的核心环境变量配置主要包括数据库连接、Redis 缓存、功能开关和运行模式。它被settings.py引入以实现配置解耦提升灵活性与可维护性。项目默认使用 MySQL 数据库提供了 Redis 缓存支持并通过开关控制调试模式、验证码认证、登录日志等功能适合多场景部署和快速环境切换。配置项分类变量名配置说明数据库DATABASE_ENGINE数据库引擎默认使用 MySQL可切换为 SQLiteDATABASE_NAME数据库名称DATABASE_HOST数据库地址DATABASE_PORT数据库端口MySQL 默认 3306DATABASE_USER数据库用户名DATABASE_PASSWORD数据库密码RedisREDIS_DB默认 Redis 数据库索引CELERY_BROKER_DBCelery 使用的 Redis 数据库索引REDIS_PASSWORDRedis 认证密码REDIS_HOSTRedis 地址REDIS_URLRedis 连接 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_*.jsonJSON 数据包含菜单、角色、用户等静态初始化数据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 层。目录 utilsutils目录是整个项目的基础工具库汇集了与认证、异常处理、权限控制、分页、导入导出、请求响应等相关的通用逻辑模块。它的设计目的是将项目中高度复用的功能集中管理解耦业务代码提升可维护性和扩展性。这些工具类和 Mixin 被广泛应用于视图、序列化器、中间件等多个层级构成系统稳定运行的底层支撑。文件名类型职责说明backends.py认证工具自定义用户认证逻辑如多种登录方式core_initialize.py初始化工具启动时执行基础初始化的相关功能crud_mixin.py视图辅助提供增删改查CRUD通用逻辑 Mixinexception.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_yasgvalidator.py校验工具表单与字段数据验证逻辑封装viewset.py视图基类二次封装 DRF 的视图集加入日志、权限等扩展项目应用使用默认提供的账号用户名superadmin密码admin123456登录系统后用户将进入系统的主控制台界面。该界面展示了系统预设的核心功能模块包括用户管理、角色权限分配、菜单配置、系统参数设置等。通过这些设置用户可以快速了解系统结构体验其权限控制、模块化设计和前后端分离的交互方式。默认账号具备最高权限可访问所有功能区域适用于初次部署、系统初始化和权限体系的搭建。开发者可以在此基础上根据实际业务需求扩展模块、调整逻辑或进行深度定制如构建企业内部管理系统、SaaS 平台、后台运营系统等快速完成从通用框架到业务系统的转化。总结项目提供了高度模块化的架构设计支持灵活部署与多场景应用。后端整合了 Celery、ASGI、Redis 等核心组件前端基于 Vue3 与 Element Plus 构建具备良好的用户交互体验。整体设计注重代码解耦与可维护性便于快速开发和功能拓展。未来可拓展方向包括多租户逻辑优化、更细粒度的权限控制、数据可视化集成以及基于微服务的架构重构以满足更复杂的企业级业务需求。通过持续优化与社区协作该项目可作为现代全栈项目的高效起点。
