285 lines
20 KiB
Markdown
285 lines
20 KiB
Markdown
<h1 align="center">DjangoAdmin 数据中台解决方案（Tornado + ElementPlus 版本）</h1>
|
||
|
||
<p align="center"><img src="./static/image/logo.png" alt="DjangoAdmin Logo" width="200" height="200" /></p>
|
||
|
||
## 📚 项目介绍
|
||
|
||
DjangoAdmin 数据中台解决方案是一套面向企业级应用场景的一站式敏捷开发平台。后端以 Python + Tornado 为核心，前端采用 Vue3 + TypeScript + ElementPlus + Vite 构建，并通过 Vue Router 与 Pinia 实现路由和状态管理。全栈技术体系成熟稳定，可快速支撑中后台管理系统、数据中台、业务运营平台等多类项目落地。
|
||
|
||
框架以“简化开发、提升效率”为设计初衷，自研了一套个性化、可插拔的组件式开发体系，涵盖单图上传、多图上传、下拉选择、开关按钮、单选按钮、多选按钮等常用交互组件。开发者只需按需组合，即可完成业务页面搭建，真正实现低代码开发。
|
||
|
||
在工程化层面，框架内置代码生成器，可根据数据库表结构自动生成完整的 CRUD 模块，包括后端代码、前端页面以及菜单权限记录，将重复性的增删改查工作一键自动化，让开发者能够将精力聚焦于核心业务逻辑与差异化功能。
|
||
|
||
在架构层面，框架采用前后端分离设计：后端提供标准 API，前端独立部署并支持多端适配。权限体系基于 RBAC 模型构建，覆盖菜单权限、按钮权限、数据权限三级控制；认证采用 JWT 无状态方案，使前后端协作更加高效顺畅。代码分层清晰、职责明确，配合完善的开发规范与工具链，为团队协作与长期维护提供坚实保障。
|
||
|
||
## 🍻 项目特点
|
||
|
||
- **高性能异步**：基于 Tornado 非阻塞 I/O 事件循环，单进程高并发，性能卓越
|
||
- **模块化、松耦合**：每个业务模块独立封装，互不干扰，支持按需加载
|
||
- **模块丰富、开箱即用**：内置用户、角色、菜单、部门、字典、日志等十余个基础模块
|
||
- **前后端分离**：前后端独立开发与部署，接口规范统一，支持多端适配
|
||
- **权限体系完善**：基于 RBAC 模型，支持菜单权限、按钮权限二级控制
|
||
- **认证安全可靠**：采用无状态认证方案，支持令牌刷新与黑名单，适配分布式场景
|
||
- **统一响应规范**：接口返回格式统一，前后端协作更高效
|
||
- **跨库数据迁移**：内置数据迁移脚本，支持 MySQL 到其他数据库的结构 + 数据全量迁移
|
||
- **完善的数据验证**：请求参数自动校验，错误信息自动格式化
|
||
- **完善的本地中文化支持**：错误提示、表单验证、操作日志全面中文化
|
||
- **设计为团队及企业使用**：规范统一，便于多人协作与长期维护
|
||
|
||
## 🍪 内置模块
|
||
|
||
- 用户管理：维护管理系统的用户，常规信息的维护与账号设置
|
||
- 角色管理：角色菜单管理与权限分配，设置角色所拥有的菜单权限
|
||
- 菜单管理：配置系统菜单、操作权限、按钮权限标识，支持动态路由生成
|
||
- 职级管理：主要管理用户的职级信息
|
||
- 岗位管理：主要管理用户担任的职务
|
||
- 部门管理：配置系统组织机构，树结构展现支持数据权限
|
||
- 字典管理：对系统中常用的较为固定的数据进行统一维护
|
||
- 字典项管理：字典数据的明细项管理
|
||
- 配置管理：对系统的常规配置信息进行维护，网站配置管理功能统一维护
|
||
- 配置项管理：配置数据的明细项管理
|
||
- 通知公告：系统通知公告信息发布维护
|
||
- 文章管理：文章分类与内容管理
|
||
- 城市管理：城市数据维护，支持树形层级结构
|
||
- 友情链接：友情链接管理
|
||
- 参数管理：系统参数配置管理
|
||
- 文件模板：文件模板管理与导出
|
||
- 操作日志：记录用户关键操作，支持日志查询与审计
|
||
- 登录日志：记录用户登录信息，支持 IP 归属地解析
|
||
- 定时任务：基于 APScheduler 的任务调度，支持任务管理与执行日志
|
||
- 文件上传：通用文件上传接口
|
||
- 代码生成器：根据数据库表结构自动生成前后端模块代码
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- **Python** >= 3.12
|
||
- **Node.js** >= 22（前端项目）
|
||
- **pnpm** >= 7（前端项目）
|
||
- **MySQL** >= 8.0（默认，可切换其他数据库）
|
||
- **Redis** >= 6.0
|
||
|
||
## 🗄️ 数据库支持
|
||
|
||
框架默认支持 **MySQL** 数据库，同时也支持多种数据库，可根据实际业务场景灵活切换。
|
||
|
||
| 数据库 | 驱动 | DB_DRIVER 值 | 支持情况 |
|
||
| --- | --- | --- | --- |
|
||
| MySQL | PyMySQL 1.2.0 | `mysql`（默认） | ✅ 默认支持 |
|
||
| PostgreSQL | psycopg[binary] 3.x | `postgresql` | ✅ 支持 |
|
||
| SQL Server | pymssql 2.3.x | `mssql` | ✅ 支持 |
|
||
| SQLite | Python 内置 | `sqlite` | ✅ 支持 |
|
||
| Oracle | oracledb 2.x | `oracle` | ✅ 支持 |
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
├── app.py # 应用启动入口（python app.py）
|
||
├── generator.py # 代码生成器 CLI 入口
|
||
├── config.json # 代码生成器配置
|
||
├── pyproject.toml # Poetry 项目配置（依赖来源）
|
||
├── poetry.lock # 依赖锁定文件
|
||
├── requirements.txt # Python 依赖清单（纯文本备选）
|
||
├── alembic.ini # Alembic 迁移配置
|
||
├── Makefile # 常用命令快捷入口
|
||
├── Dockerfile # 镜像构建
|
||
├── docker-compose.yml # Docker 编排
|
||
├── .env # 环境变量配置
|
||
├── .env.example # 环境变量示例
|
||
├── src/ # 后端源码目录
|
||
│ ├── app.py # 应用工厂（create_app）
|
||
│ ├── bootstrap.py # 启动引导（参数解析、信号处理）
|
||
│ ├── api/ # API 路由层
|
||
│ │ └── v1/
|
||
│ │ ├── router.py # 路由集中注册（build_routes）
|
||
│ │ ├── auth.py # 登录/登出/验证码/令牌刷新
|
||
│ │ ├── user.py # 用户管理
|
||
│ │ ├── user_role.py # 用户角色分配
|
||
│ │ ├── role.py # 角色管理
|
||
│ │ ├── role_menu.py # 角色菜单分配
|
||
│ │ ├── menu.py # 菜单管理
|
||
│ │ ├── dept.py # 部门管理
|
||
│ │ ├── level.py # 职级管理
|
||
│ │ ├── position.py # 岗位管理
|
||
│ │ ├── dict.py # 字典管理
|
||
│ │ ├── dict_item.py # 字典项管理
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── config_item.py # 配置项管理
|
||
│ │ ├── notice.py # 通知公告
|
||
│ │ ├── article.py # 文章管理
|
||
│ │ ├── category.py # 分类管理
|
||
│ │ ├── city.py # 城市管理
|
||
│ │ ├── link.py # 友情链接
|
||
│ │ ├── param.py # 参数管理
|
||
│ │ ├── job.py # 定时任务
|
||
│ │ ├── job_log.py # 任务日志
|
||
│ │ ├── file_template.py # 文件模板
|
||
│ │ ├── login_log.py # 登录日志
|
||
│ │ ├── operation_log.py # 操作日志
|
||
│ │ ├── upload.py # 文件上传
|
||
│ │ ├── index.py # 首页菜单/用户信息
|
||
│ │ └── generator.py # 代码生成器 API
|
||
│ ├── core/ # 核心基础设施
|
||
│ │ ├── base_handler.py # 请求处理器基类（认证、异常、会话回收）
|
||
│ │ ├── base_model.py # 数据模型基类（审计字段、to_dict）
|
||
│ │ ├── base_repository.py # 仓储基类（CRUD、分页、软删除）
|
||
│ │ ├── base_schema.py # Pydantic Schema 基类
|
||
│ │ ├── base_service.py # 服务基类（模板方法 CRUD）
|
||
│ │ ├── context.py # 请求级上下文（current_user_id 等 contextvars）
|
||
│ │ ├── database.py # 数据库引擎/会话管理（读写分离）
|
||
│ │ ├── redis.py # Redis 客户端封装
|
||
│ │ ├── jwt.py # JWT 签发/解析/黑名单/刷新
|
||
│ │ ├── password.py # 双盐 bcrypt 密码加密
|
||
│ │ ├── response.py # 统一响应封装（R.ok/R.failed）
|
||
│ │ ├── exceptions.py # 自定义异常体系
|
||
│ │ ├── logger.py # 结构化日志配置
|
||
│ │ ├── metrics.py # 指标采集
|
||
│ │ └── tracer.py # 链路追踪
|
||
│ ├── config/ # 配置模块（Pydantic Settings）
|
||
│ │ ├── app.py # 应用配置（TORNADO_DEMO 等）
|
||
│ │ ├── database.py # 数据库配置
|
||
│ │ ├── redis.py # Redis 配置
|
||
│ │ ├── auth.py # 认证配置（JWT）
|
||
│ │ ├── captcha.py # 验证码配置
|
||
│ │ ├── email.py # 邮件配置
|
||
│ │ └── logging.py # 日志配置
|
||
│ ├── constants/ # 常量定义
|
||
│ │ └── __init__.py # 通用常量与提示文案
|
||
│ ├── common/ # 公共组件
|
||
│ │ ├── middleware/ # 中间件/装饰器
|
||
│ │ │ ├── authentication.py # JWT 认证（login_required）
|
||
│ │ │ ├── cors.py # 跨域处理
|
||
│ │ │ ├── access_decorators.py # 权限校验 + 演示模式拦截
|
||
│ │ │ ├── operation_log.py # 操作日志装饰器
|
||
│ │ │ ├── login_log.py # 登录日志装饰器
|
||
│ │ │ ├── trace_id.py # 链路追踪 ID 注入
|
||
│ │ │ └── metrics.py # 请求指标中间件
|
||
│ │ ├── permission.py # 跨模块权限解析（Redis 缓存）
|
||
│ │ └── utils/ # 工具函数
|
||
│ │ ├── crypto.py # 密码加密门面
|
||
│ │ ├── captcha.py # 验证码生成与验证
|
||
│ │ ├── file.py # 文件操作（mkdir、魔术字节校验）
|
||
│ │ ├── rich_text.py # 富文本处理（XSS 清洗、路径穿越防护）
|
||
│ │ ├── ip.py # 客户端 IP 获取（代理透传）
|
||
│ │ ├── ip2region.py # IP 归属地离线查询
|
||
│ │ ├── dict_util.py # 字典 Redis 缓存读取
|
||
│ │ ├── helpers.py # 通用辅助（UA 解析、参数脱敏）
|
||
│ │ └── validators.py # 通用校验器
|
||
│ ├── modules/ # 业务模块（每个模块 5 文件）
|
||
│ │ ├── auth/ # 认证模块（登录/登出/验证码/令牌刷新）
|
||
│ │ ├── user/ # 用户管理
|
||
│ │ ├── user_role/ # 用户角色关联
|
||
│ │ ├── role/ # 角色管理
|
||
│ │ ├── role_menu/ # 角色菜单关联
|
||
│ │ ├── menu/ # 菜单管理（动态路由 + 权限节点）
|
||
│ │ ├── dept/ # 部门管理
|
||
│ │ ├── level/ # 职级管理
|
||
│ │ ├── position/ # 岗位管理
|
||
│ │ ├── dictionary/ # 字典模块
|
||
│ │ │ ├── dict/ # 字典管理
|
||
│ │ │ └── dict_item/ # 字典项管理
|
||
│ │ ├── configuration/ # 配置模块
|
||
│ │ │ ├── config/ # 配置管理
|
||
│ │ │ └── config_item/ # 配置项管理
|
||
│ │ ├── notice/ # 通知公告
|
||
│ │ ├── article/ # 文章管理
|
||
│ │ ├── category/ # 分类管理
|
||
│ │ ├── city/ # 城市管理（树形结构）
|
||
│ │ ├── link/ # 友情链接
|
||
│ │ ├── param/ # 参数管理
|
||
│ │ ├── file_template/ # 文件模板
|
||
│ │ ├── job/ # 定时任务（APScheduler）
|
||
│ │ ├── job_log/ # 任务执行日志
|
||
│ │ ├── login_log/ # 登录日志（IP 归属地解析）
|
||
│ │ ├── operation_log/ # 操作日志（审计追踪）
|
||
│ │ ├── upload/ # 文件上传
|
||
│ │ ├── generator/ # 代码生成器
|
||
│ │ └── example/ # 示例模块（开发参考）
|
||
│ └── extensions/ # 扩展（可选组件）
|
||
│ ├── sqlalchemy.py # SQLAlchemy 单例导出
|
||
│ ├── redis.py # Redis 单例导出
|
||
│ ├── swagger.py # Swagger（占位）
|
||
│ └── sentry.py # Sentry（占位）
|
||
├── scripts/ # 运维脚本
|
||
│ ├── seed_dict.py # 业务字典初始化（幂等）
|
||
│ ├── seed.py # 通用数据填充
|
||
│ ├── init_db.py # 数据库初始化
|
||
│ ├── migrate_db.py # 跨库数据迁移工具（MySQL→PG/MSSQL/SQLite/Oracle）
|
||
│ ├── migrate.py # 迁移辅助
|
||
│ ├── deploy.py # 部署脚本
|
||
│ ├── health_check.py # 健康检查
|
||
│ └── deploy.py # 部署脚本
|
||
├── tests/ # 测试目录
|
||
│ ├── unit/ # 单元测试
|
||
│ │ ├── core/ # 核心模块测试（jwt、crypto、response、base_service、repository）
|
||
│ │ └── modules/ # 业务模块测试（schema、scheduler）
|
||
│ ├── integration/ # 集成测试（需 MySQL + Redis）
|
||
│ │ ├── test_api.py # API 接口测试
|
||
│ │ ├── test_database.py # 数据库连接测试
|
||
│ │ └── test_redis.py # Redis 连接测试
|
||
│ └── fixtures/ # 测试夹具
|
||
│ └── factories.py # 测试数据工厂
|
||
├── alembic/ # Alembic 数据库迁移
|
||
│ └── versions/ # 迁移版本文件
|
||
└── document/ # 项目文档
|
||
├── mysql/ # MySQL 初始化 SQL
|
||
├── postgresql/ # PostgreSQL 初始化 SQL
|
||
├── sqlserver/ # SQL Server 初始化 SQL
|
||
├── sqlite/ # SQLite 初始化 SQL
|
||
└── sql/ # 通用 SQL 脚本
|
||
```
|
||
|
||
## 👷 软件信息
|
||
|
||
- 软件名称：DjangoAdmin 敏捷开发框架 Tornado + ElementPlus 版本
|
||
- 软件作者：@小蚂蚁云 团队荣誉出品
|
||
- 软件出处：小蚂蚁云团队
|
||
- 软件协议：Apache-2.0
|
||
- 官网网址：<https://www.djangoadmin.cn>
|
||
- 文档网址：<http://docs.tornado.elevue.djangoadmin.cn>
|
||
- 演示地址：<http://manage.tornado.elevue.djangoadmin.cn>
|
||
|
||
## 📌 版本说明
|
||
|
||
| 版本名称 | 版本说明 | 版本地址 |
|
||
| --- | --- | --- |
|
||
| Django + Layui 混编版 | 采用 Django、Layui 等框架研发 | <https://gitee.com/djangoadmin/DjangoAdmin_Django_Layui> |
|
||
| Flask + Layui 混编版 | 采用 Flask、Layui 等框架研发 | <https://gitee.com/djangoadmin/DjangoAdmin_Flask_Layui> |
|
||
| FastAPI + Layui 混编版 | 采用 FastAPI、Layui 等框架研发 | <https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_Layui> |
|
||
| Tornado + Layui 混编版 | 采用 Tornado、Layui 等框架研发 | <https://gitee.com/djangoadmin/DjangoAdmin_Tornado_Layui> |
|
||
| Django + EleVue 前后端分离版 | 采用 Django、Vue3、TypeScript、ElementPlus 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue> |
|
||
| Flask + EleVue 前后端分离版 | 采用 Flask、Vue3、TypeScript、ElementPlus 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue> |
|
||
| FastAPI + EleVue 前后端分离版 | 采用 FastAPI、Vue3、TypeScript、ElementPlus 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue> |
|
||
| Tornado + EleVue 前后端分离版 | 采用 Tornado、Vue3、TypeScript、ElementPlus 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Tornado_EleVue> |
|
||
| Django + AntdVue 前后端分离版 | 采用 Django、Vue3、AntDesign 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Django_AntdVue> |
|
||
| Flask + AntdVue 前后端分离版 | 采用 Flask、Vue3、AntDesign 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue> |
|
||
| FastAPI + AntdVue 前后端分离版 | 采用 FastAPI、Vue3、AntDesign 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_AntdVue> |
|
||
| Tornado + AntdVue 前后端分离版 | 采用 Tornado、Vue3、AntDesign 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Tornado_AntdVue> |
|
||
| Django + NaiveUI 前后端分离版 | 采用 Django、Vue3、TypeScript、NaiveUI 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveUI> |
|
||
| Flask + NaiveUI 前后端分离版 | 采用 Flask、Vue3、TypeScript、NaiveUI 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveUI> |
|
||
| FastAPI + NaiveUI 前后端分离版 | 采用 FastAPI、Vue3、TypeScript、NaiveUI 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_NaiveUI> |
|
||
| Tornado + NaiveUI 前后端分离版 | 采用 Tornado、Vue3、TypeScript、NaiveUI 等框架研发前后端分离版本 | <https://gitee.com/djangoadmin/DjangoAdmin_Tornado_NaiveUI> |
|
||
|
||
## 🔧 模块展示
|
||
|
||
| | |
|
||
| --- | --- |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|  |  |
|
||
|
||
## ✨ 特别鸣谢
|
||
|
||
感谢 [Tornado](https://www.tornadoweb.org/)、[SQLAlchemy](https://www.sqlalchemy.org/)、[Vue](https://cn.vuejs.org/)、[ElementPlus](https://element-plus.org/)、[Pydantic](https://docs.pydantic.dev/) 等优秀开源项目。 |