Python Web 开发平台：FastAPI 与 Django 双后端架构方案

前端技术

• 核心框架: 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 管理脚本
├── backend-fastapi/         # FastAPI 后端（可选）
│   ├── app/                 # 核心应用模块
│   ├── core/                # 核心业务模块
│   ├── scheduler/           # 定时任务模块
│   ├── scripts/             # 工具脚本
│   ├── alembic/             # 数据库迁移
│   ├── env/                 # 环境配置
│   ├── requirements.txt     # Python 依赖
│   └── main.py              # 应用入口
└── 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: Django 后端（推荐用于生产环境）

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.example .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

选项 2: FastAPI 后端（推荐用于高性能场景）

1. 进入 FastAPI 目录

cd zq-platform/backend-fastapi

2. 创建虚拟环境

conda create -n zq-fastapi python=3.12
conda activate zq-fastapi

3. 安装依赖

pip install -r requirements.txt

4. 配置环境变量

cp env/example.env env/dev.env

编辑 env/dev.env 配置数据库连接。

5. 数据库迁移

alembic revision --autogenerate -m "init tables"
alembic upgrade head
# 导入初始数据（可选）
python scripts/loaddata.py db_init.json

6. 启动服务

python main.py
# 或 uvicorn main:app --reload --host 0.0.0.0 --port 8000

7. 访问 API 文档

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

前端安装

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 文档

Django 后端

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

FastAPI 后端

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/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 的组件库