Django 后端服务模板

基于 Django 5 + DRF + SimpleJWT + MySQL 的开箱即用后端模板，内置用户体系、Apple 登录、版本管理、动态配置等常用模块，配套 Docker 一键部署。

技术栈

类别	选型	说明
Web 框架	Django 5.2	含 admin 后台
API 框架	Django REST Framework 3.16	ViewSet + Serializer
认证	djangorestframework-simplejwt 5.5	JWT access/refresh
数据库	MySQL 8.0	PyMySQL 驱动，utf8mb4
配置管理	django-environ	环境变量驱动，支持 .env
API 文档	drf-yasg	Swagger UI
跨域	django-cors-headers	可配置白名单
过滤	django-filter	列表接口过滤/搜索/排序
静态文件	WhiteNoise	生产环境直接由应用托管
AI 能力	openai SDK	默认对接豆包（火山引擎 Ark）
部署	Docker + Nginx + Gunicorn	三容器编排

目录结构

server_template/
├── apps/                       # 业务应用模块
│   ├── user/                   # 用户模块（登录、Apple 登录）
│   │   ├── models.py           # User
│   │   ├── views.py            # UserViewSet
│   │   ├── serializers.py      # 登录、Apple 登录、Token 刷新序列化
│   │   └── admin.py            # 后台管理
│   └── setting/                # 系统设置模块（版本检查、动态配置）
│       ├── models.py           # AppVersion / DynamicConfig
│       └── views.py            # 版本检查、动态配置接口
├── configurations/             # 配置文件目录
│   ├── .env.example            # 环境变量模板（拷贝后改为 .env）
│   ├── Dockerfile              # 应用镜像构建
│   ├── docker-compose.yml      # 三容器编排（nginx + mysql + web）
│   ├── nginx.development.conf  # 开发环境 Nginx 配置
│   ├── nginx.production.conf   # 生产环境 Nginx 配置
│   └── requirements.txt        # Python 依赖
├── django_server/              # Django 项目主配置
│   ├── settings.py             # 全局配置（环境变量读取）
│   ├── urls.py                 # URL 路由总入口
│   ├── wsgi.py / asgi.py       # 部署入口
│   └── management/             # 自定义 management commands（按需扩展）
├── managers/                   # 业务管理器
│   └── apple_login.py          # Apple 登录管理器
├── models/                     # 公共模型基类
│   ├── base_model.py           # BaseModel（create_time/update_time/is_delete）
│   └── pagination.py           # 统一分页类（limit/offset）
├── utils/                      # 工具类
│   ├── response.py             # 统一响应格式 ResponseUtil
│   ├── authentication.py       # 可选 JWT 认证（支持匿名访问公开接口）
│   ├── exception_handler.py    # 统一异常处理
│   ├── base_views.py           # BaseModelViewSet（通用 CRUD）
│   ├── common.py               # 通用工具方法
│   └── aigc.py                 # AIGC 能力封装（豆包）
├── scripts/                    # 运维脚本
│   ├── docker-start.sh         # Docker 一键启动（含环境切换）
│   └── docker-stop.sh          # Docker 停止
├── manage.py                   # Django 管理入口
└── README.md                   # 本文件

快速开始

1. 准备环境

# Python 3.10+（推荐使用 pyenv 管理版本）
python --version

# MySQL 8.0（本地开发可用 Docker 单独起一个，或用项目自带 compose）

2. 安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -r configurations/requirements.txt

3. 配置环境变量

# 复制配置模板
cp configurations/.env.example configurations/.env

# 编辑 .env，填写以下必需项：
#   SECRET_KEY         - 生成方式见 .env.example 注释
#   DB_*               - 数据库连接信息
#   MYSQL_ROOT_PASSWORD - Docker MySQL root 密码

4. 初始化数据库

# 执行数据库迁移
python manage.py migrate

# 创建超级管理员
python manage.py createsuperuser

# 收集静态文件（生产环境）
python manage.py collectstatic --noinput

5. 启动开发服务器

python manage.py runserver 0.0.0.0:8000

访问地址：

• API 服务：http://localhost:8000/api/
• API 文档：http://localhost:8000/api/docs/
• 管理后台：http://localhost:8000/api/admin/

Docker 部署

项目提供完整的三容器编排（nginx + mysql + web），支持三种环境切换：

# 一键启动（交互式选择环境：local / development / production）
bash scripts/docker-start.sh

# 停止服务
bash scripts/docker-stop.sh

启动脚本会自动：

1. 读取选定的环境模板（.env.local / .env.development / .env.production）覆盖到 .env
2. 构建并启动容器
3. 执行 migrate 和 collectstatic
4. 输出访问地址和常用命令

注意：使用前请先基于 .env.example 创建对应的环境配置文件（如 .env.development），并填入真实值。

核心功能模块

用户模块 (apps/user)

• 账号登录：支持用户名 / 手机号登录，返回 JWT access + refresh token
• Apple 登录：支持 identity_token 直传或 authorization_code 后端换 token
• Token 刷新：refresh token 轮转机制
• 强制下线：通过 token_key 比对实现单点登录控制

系统设置模块 (apps/setting)

• 版本检查：客户端上报版本，服务端返回是否有更新及强制更新状态
• 最新版本：按平台获取最新可用版本
• 动态配置：Banner、活动、系统设置等动态内容管理，支持时间窗口控制

公共基础设施

• 统一响应格式：{code, message, data}
• 统一异常处理：认证失败、权限不足、404 等自动包装为统一格式
• 可选 JWT 认证：公开接口可匿名访问，携带 token 则自动认证
• 软删除：BaseModel 提供 is_delete 字段，删除操作为软删除
• 分页：统一 limit/offset 分页，最大 200 条

接口路由

方法	路径	说明	权限
POST	/api/user/users/login/	用户登录	公开
POST	/api/user/users/apple_login/	Apple 登录	公开
POST	/api/user/users/refresh_token/	刷新 token	公开
GET	/api/user/users/me/	当前用户信息	需登录
POST	/api/setting/versions/check/	版本检查	公开
GET	/api/setting/versions/latest/	最新版本	公开
GET	/api/setting/configs/get_by_type/	按类型获取配置	公开

基于本模板创建新项目

1. 拷贝模板：cp -r server_template/ my_project/
2. 全局替换命名（按需）：
   • app_ → your_project_（数据库表名前缀，见于各 models.py 的 db_table）
   • app_server → your_project_server（Docker compose 项目名，见于 scripts/）
   • app_nginx / app_mysql / app_web → your_project_*（容器名，见于 docker-compose.yml）
   • Project API → Your Project API（API 文档标题，见于 urls.py）
3. 配置环境变量：cp configurations/.env.example configurations/.env 并填写
4. 初始化数据库：python manage.py migrate && python manage.py createsuperuser
5. 按需启用功能：
   • Apple 登录：在 .env 配置 APPLE_* 变量，放置 AuthKey_<KEY_ID>.p8 私钥
   • AI 能力：在 .env 配置 DOUBAO_ARK_API_KEY
6. 新建业务 App：python manage.py startapp <name> apps/<name>，并在 settings.py 的 INSTALLED_APPS 注册

安全注意事项

• 密钥管理：SECRET_KEY、数据库密码、API Key 等敏感信息只放在 .env（已被 gitignore），切勿硬编码到代码
• 生产配置：生产环境必须 DEBUG=False，ALLOWED_HOSTS 填实际域名，CORS_ALLOW_ALL_ORIGINS=False
• 私钥文件：Apple 私钥 .p8 文件已被 gitignore，确保不提交
• 依赖更新：定期更新 requirements.txt 中的依赖，关注安全公告