ai-agent-admin/README.zh-CN.md

zq-platform(芷青开发平台)

English | 简体中文

一个现代化的企业级后台管理系统，基于 Django + Vue3 + Element Plus 构建

演示链接

https://django-ninja.zq-platform.cn

📖 项目简介

zq-platform 是一个功能完善的企业级后台管理系统解决方案，采用前后端分离架构。后端使用 Django 5.2 + Django Ninja 构建高性能 RESTful API，前端基于 Vue 3 + Vben Admin + Element Plus 打造现代化的管理界面。

✨ 核心特性

• 🎯 完整的 RBAC 权限系统 - 用户、角色、权限、部门、岗位多维度权限控制
• 🔐 JWT 认证机制 - 安全的 Token 认证，支持 Access Token 和 Refresh Token
• 📊 系统监控 - 服务器监控、Redis 监控、数据库监控，实时掌握系统状态
• 📁 文件管理 - 完善的文件上传、下载、预览功能
• 📝 操作日志 - 详细的登录日志和操作审计
• 🗂️ 数据字典 - 灵活的字典管理，支持多级分类
• ⏰ 任务调度 - 基于 APScheduler 的定时任务管理
• 🔌 WebSocket 支持 - 实时通信能力
• 🌐 多数据库支持 - MySQL、PostgreSQL、SQL Server、SQLite
• 🎨 现代化 UI - 响应式设计，支持暗黑模式
• 📦 Monorepo 架构 - 基于 pnpm workspace 的前端工程化方案

🏗️ 技术栈

后端技术

• 核心框架: Django 5.2.7
• API 框架: Django Ninja 1.4.5 (高性能 API 框架)
• 认证: PyJWT 2.8.0
• 异步任务: Celery 5.4.0 + Django Celery Beat
• 任务调度: APScheduler 3.10.4
• 缓存: Redis + django-redis
• WebSocket: Django Channels 4.2
• 数据库驱动: psycopg2-binary, pymysql, pyodbc
• 服务器: Uvicorn 0.38.0 / Gunicorn 23.0.0
• 其他: openpyxl, geoip2, psutil, cryptography

前端技术

• 核心框架: Vue 3.x
• 构建工具: Vite 5.x
• UI 组件库: Element Plus
• 状态管理: Pinia
• 路由: Vue Router
• HTTP 客户端: Axios
• 工具库: VueUse, dayjs, lodash-es
• 代码规范: ESLint, Prettier, Stylelint
• 包管理: pnpm 10.14.0
• Monorepo: Turbo

📁 项目结构

zq-platform/
├── backend-django/          # Django 后端
│   ├── application/         # 项目配置
│   ├── core/               # 核心业务模块
│   │   ├── auth/           # 认证授权
│   │   ├── user/           # 用户管理
│   │   ├── role/           # 角色管理
│   │   ├── permission/     # 权限管理
│   │   ├── dept/           # 部门管理
│   │   ├── post/           # 岗位管理
│   │   ├── menu/           # 菜单管理
│   │   ├── dict/           # 字典管理
│   │   ├── login_log/      # 登录日志
│   │   ├── file_manager/   # 文件管理
│   │   ├── server_monitor/ # 服务器监控
│   │   ├── redis_monitor/  # Redis 监控
│   │   ├── redis_manager/  # Redis 管理
│   │   ├── database_monitor/ # 数据库监控
│   │   └── database_manager/ # 数据库管理
│   ├── scheduler/          # 任务调度模块
│   ├── common/             # 公共模块
│   ├── env/                # 环境配置
│   ├── requirements.txt    # Python 依赖
│   └── manage.py          # Django 管理脚本
│
└── web/                    # Vue 前端 (Monorepo)
    ├── apps/
    │   └── web-ele/        # Element Plus 版本主应用
    │       ├── src/
    │       │   ├── api/    # API 接口
    │       │   ├── views/  # 页面组件
    │       │   ├── router/ # 路由配置
    │       │   └── store/  # 状态管理
    │       └── package.json
    ├── packages/           # 共享包
    │   ├── @core/          # 核心包
    │   ├── effects/        # 副作用包
    │   ├── hooks/          # Hooks
    │   ├── icons/          # 图标
    │   ├── locales/        # 国际化
    │   ├── stores/         # 状态管理
    │   └── utils/          # 工具函数
    ├── internal/           # 内部工具
    └── package.json        # 根配置

🚀 快速开始

环境要求

• 后端

  • Python >= 3.10
  • MySQL >= 5.7 / PostgreSQL >= 12 / SQL Server / SQLite
  • Redis >= 5.0

• 前端

  • Node.js >= 20.10.0
  • pnpm >= 9.12.0

后端安装

1. 克隆项目

git clone https://github.com/jiangzhikj/zq-platform.git
cd zq-platform/backend-django

2. 创建虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

3. 安装依赖

pip install -r requirements.txt

4. 配置环境变量

cp env
# 编辑 .env 文件，配置数据库、Redis、JWT 密钥等

主要配置项：

# JWT 密钥
JWT_ACCESS_SECRET_KEY=your-jwt-access-secret
JWT_REFRESH_SECRET_KEY=your-jwt-refresh-secret

# 数据库配置
DATABASE_TYPE=MYSQL  # MYSQL/POSTGRESQL/SQLSERVER/SQLITE3
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=password
DATABASE_NAME=zq_admin

# Redis 配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=2

5. 数据库迁移

python manage.py makemigrations core scheduler
python manage.py migrate

6. 初始化数据

python manage.py loaddata db_init.json

7. 启动服务

# 开发环境
python manage.py runserver 0.0.0.0:8000

8. 启动任务调度器（可选）

# 生产环境
python start_scheduler.py

前端安装

1. 进入前端目录

cd zq-platform/web

2. 安装依赖

pnpm install

3. 配置环境变量

cd apps/web-ele
cp .env.development .env
# 编辑 .env 文件，配置后端 API 地址

4. 启动开发服务器

# 在 web 根目录下
pnpm dev

5. 构建生产版本

pnpm build:ele

📝 默认账号

初始化数据后，可使用以下账号登录：

• 账号: superadmin
• 密码: 请查看 123456 或联系管理员

🔧 主要功能模块

系统管理

• 用户管理: 用户的增删改查、密码重置、状态管理
• 角色管理: 角色权限分配、数据权限控制
• 权限管理: 接口权限、按钮权限细粒度控制
• 部门管理: 树形部门结构管理
• 岗位管理: 岗位信息维护
• 菜单管理: 动态菜单配置、路由管理
• 字典管理: 系统字典维护

系统监控

• 服务器监控: CPU、内存、磁盘、网络实时监控
• Redis 监控: Redis 性能指标、键值管理
• 数据库监控: 数据库连接、性能监控
• 登录日志: 用户登录记录、IP 地理位置

任务调度

• 定时任务: Cron 表达式配置
• 任务日志: 执行历史、结果查看
• 任务管理: 启动、停止、立即执行

文件管理

• 文件上传: 支持多文件上传
• 文件预览: 图片、文档在线预览
• 文件下载: 批量下载功能

🔐 API 文档

后端启动后，访问以下地址查看 API 文档：

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

🛠️ 开发指南

后端开发

1. 添加新模块

   • 在 core/ 或创建新 app
   • 定义 models、schemas、services、api
   • 在 router 中注册路由

2. API 开发规范

   • 使用 Django Ninja 装饰器
   • 统一返回格式
   • 异常处理
   • 权限验证

前端开发

1. 添加新页面

   • 在 src/views/ 创建页面组件
   • 在 src/router/routes/modules/ 添加路由
   • 在 src/api/ 添加接口定义

2. 组件开发规范

   • 使用 Element Plus 组件
   • 优先使用 Tailwind CSS
   • 支持暗黑模式
   • 图标从 @vben/icons 导入

📦 部署

1. 后端部署

   • 使用 Gunicorn + Nginx
   • 配置 Supervisor 进程守护
   • 配置 SSL 证书

2. 前端部署

   • 执行 pnpm build 构建
   • 将 dist 目录部署到 Nginx
   • 配置反向代理

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

🙏 致谢

• Django - 强大的 Python Web 框架
• Django Ninja - 快速的 Django REST 框架
• Vue Vben Admin - 优秀的 Vue3 后台管理模板
• Element Plus - 基于 Vue 3 的组件库

📞 联系方式

如有问题或建议，请通过以下方式联系：

• Issue: GitHub Issues
• Email: jiangzhikj@outlook.com

---

Made with ❤️ by ZQ Team