From 3a661afaa50b65f6be561a50a8428c59ca287209 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Fri, 3 Jul 2026 17:53:49 +0800
Subject: [PATCH] docs: add t-403 deployment guide

---
 .env.example                |  14 ++
 README.md                   |   2 +-
 config/settings.py          |  28 +++-
 docs/00-ai-start-here.md    |   4 +-
 docs/03-tech-stack.md       |   7 +-
 docs/04-architecture.md     |   2 +-
 docs/06-tasks.md            |   2 +-
 docs/README.md              |   1 +
 docs/current-state.md       |  32 ++--
 docs/deployment.md          | 302 ++++++++++++++++++++++++++++++++++++
 docs/env.md                 |  28 +++-
 docs/project-brief.md       |   5 +-
 docs/project-onepager.md    |   2 +-
 progress.md                 |  28 ++++
 requirements-production.txt |   4 +
 15 files changed, 436 insertions(+), 25 deletions(-)
 create mode 100644 docs/deployment.md
 create mode 100644 requirements-production.txt

diff --git a/.env.example b/.env.example
index 2d71901..66f6d9b 100644
--- a/.env.example
+++ b/.env.example
@@ -2,9 +2,23 @@
 DJANGO_SECRET_KEY=change-me-generate-a-random-secret
 DJANGO_DEBUG=true
 DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost,testserver
+DJANGO_CSRF_TRUSTED_ORIGINS=
 DJANGO_TIME_ZONE=Asia/Shanghai
 DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
 DJANGO_DEFAULT_FROM_EMAIL=noreply@cmhub.local
+DJANGO_SESSION_COOKIE_SECURE=false
+DJANGO_CSRF_COOKIE_SECURE=false
+DJANGO_SECURE_SSL_REDIRECT=false
+DJANGO_SECURE_HSTS_SECONDS=0
+DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS=false
+DJANGO_SECURE_HSTS_PRELOAD=false
+DJANGO_SECURE_PROXY_SSL_HEADER=false
+
+# Static and shared cache
+STATIC_URL=/static/
+STATIC_ROOT=D:\chengma\cmhub\staticfiles
+DJANGO_CACHE_BACKEND=django.core.cache.backends.locmem.LocMemCache
+DJANGO_CACHE_LOCATION=cmhub-local-cache
 
 # MySQL 8.4
 MYSQL_HOST=127.0.0.1
diff --git a/README.md b/README.md
index 7f5b355..ef9efcf 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR
 
 ## 当前状态
 
-Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善与 T-402 MVP 完整验收：用户可通过 allauth 自助注册、邮箱验证、登录、登出，扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录与分页消费记录；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水和调用记录，并通过计费层带原因手工调点。下一步进入 T-403 部署 / 运行文档。详见 [`docs/current-state.md`](docs/current-state.md)。
+Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档：用户可通过 allauth 自助注册、邮箱验证、登录、登出，扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录与分页消费记录；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水和调用记录，并通过计费层带原因手工调点；生产部署按 `docs/deployment.md` 执行。计划内 MVP 任务已完成，下一步是按部署文档上 VPS 配置真实邮件、支付、AI 模型和图片真实耗时验证。详见 [`docs/current-state.md`](docs/current-state.md)。
 
 > ⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 [`docs/05-coding-rules.md`](docs/05-coding-rules.md) 第 8 节与 [`docs/04-architecture.md`](docs/04-architecture.md) 第四节计费时序。
 
diff --git a/config/settings.py b/config/settings.py
index 68495a4..db902c9 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -94,6 +94,21 @@ ALIPAY_NOTIFY_URL = os.environ.get("ALIPAY_NOTIFY_URL", "")
 ALIPAY_DEBUG = env_bool("ALIPAY_DEBUG", False)
 
 ALLOWED_HOSTS = env_list("DJANGO_ALLOWED_HOSTS", "127.0.0.1,localhost,testserver")
+CSRF_TRUSTED_ORIGINS = env_list("DJANGO_CSRF_TRUSTED_ORIGINS", "")
+SESSION_COOKIE_SECURE = env_bool("DJANGO_SESSION_COOKIE_SECURE", not DEBUG)
+CSRF_COOKIE_SECURE = env_bool("DJANGO_CSRF_COOKIE_SECURE", not DEBUG)
+SECURE_SSL_REDIRECT = env_bool("DJANGO_SECURE_SSL_REDIRECT", False)
+SECURE_HSTS_SECONDS = env_int("DJANGO_SECURE_HSTS_SECONDS", 0)
+SECURE_HSTS_INCLUDE_SUBDOMAINS = env_bool(
+    "DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS",
+    False,
+)
+SECURE_HSTS_PRELOAD = env_bool("DJANGO_SECURE_HSTS_PRELOAD", False)
+SECURE_PROXY_SSL_HEADER = (
+    ("HTTP_X_FORWARDED_PROTO", "https")
+    if env_bool("DJANGO_SECURE_PROXY_SSL_HEADER", False)
+    else None
+)
 
 API_GENERATE_THROTTLE_RATE = os.environ.get("API_GENERATE_THROTTLE_RATE", "60/min")
 API_AUTH_FAILURE_THROTTLE_RATE = os.environ.get("API_AUTH_FAILURE_THROTTLE_RATE", "30/min")
@@ -207,6 +222,16 @@ DATABASES = {
     }
 }
 
+CACHES = {
+    "default": {
+        "BACKEND": os.environ.get(
+            "DJANGO_CACHE_BACKEND",
+            "django.core.cache.backends.locmem.LocMemCache",
+        ),
+        "LOCATION": os.environ.get("DJANGO_CACHE_LOCATION", "cmhub-local-cache"),
+    }
+}
+
 
 # Password validation
 # https://docs.djangoproject.com/en/5.2/ref/settings/#auth-password-validators
@@ -242,7 +267,8 @@ USE_TZ = True
 # Static files (CSS, JavaScript, Images)
 # https://docs.djangoproject.com/en/5.2/howto/static-files/
 
-STATIC_URL = 'static/'
+STATIC_URL = os.environ.get("STATIC_URL", "/static/")
+STATIC_ROOT = os.environ.get("STATIC_ROOT", str(BASE_DIR / "staticfiles"))
 
 MEDIA_ROOT = os.environ.get("MEDIA_ROOT", str(BASE_DIR / "media"))
 MEDIA_URL = os.environ.get("MEDIA_URL", "/media/")
diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md
index 678bcf4..4e8b642 100644
--- a/docs/00-ai-start-here.md
+++ b/docs/00-ai-start-here.md
@@ -38,7 +38,7 @@
 
 ## 当前阶段
 
-当前项目处于：**Phase 5 后台与发布**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善与 T-402 MVP 完整验收。下一步进入 T-403 部署 / 运行文档。
+当前项目处于：**Phase 5 后台与发布已完成计划内任务**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档。下一步是按 `deployment.md` 在 VPS 上配置真实邮件、支付、AI 模型和图片真实耗时验证，或从 Backlog 重新规划后续任务。
 
 优先路径：
 
@@ -47,7 +47,7 @@
 3. Phase 2：计费核心 —— T-201/T-202/T-203 已完成 UserWallet/ApiKey/PointsLedger/CallRecord、计费规则、汇率、计费计算、并发安全扣点与失败退点。
 4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
 5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。
-6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP 已完成；下一步 T-403 部署 / 运行文档。
+6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP、T-403 部署 / 运行文档已完成；计划内 MVP 任务已收尾。
 
 ## 领取任务规则
 
diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md
index 72b8c9c..b47afc4 100644
--- a/docs/03-tech-stack.md
+++ b/docs/03-tech-stack.md
@@ -24,7 +24,7 @@
 | 充值对接 | 自助扫码：微信 V3 native + 支付宝当面付；下单取二维码 + 服务端回调（验签 + 幂等） | 已定 | T-304/T-305 已落地回调、扫码下单、状态轮询、HMAC mock 联调与 SDK 模式入口；生产需安装并配置 `wechatpayv3` / `python-alipay-sdk` 与真实商户密钥/证书 |
 | 生成返回方式 | 同步 HTTP（无任务队列） | 已定 | MVP 简化；图片接口需调大网关/服务超时 |
 | 任务队列 | 暂不引入（Celery/RQ） | 待定 | V2 异步化时再评估 |
-| 部署方式 | Docker + Gunicorn(gthread) + Nginx，单体 | 待定 | MVP 先 `runserver`；生产 Nginx 按路径把 `/api/generate/*`（图片长请求）与用户端页面**分流到不同 gunicorn/worker 池**，避免图片阻塞拖慢页面（见 `04-architecture.md` 5.1） |
+| 部署方式 | VPS / 宝塔 + Nginx + Gunicorn(gthread) + systemd，Django 单体 | 已定（MVP） | 生产按 `deployment.md` 执行；Nginx 按路径把 `/api/v1/generate/*`（图片长请求）分流到独立 Gunicorn 池，用户端 / admin / 余额 / 充值走普通池；`/static/` 托管 `STATIC_ROOT`，`/media/` 托管本地媒体或后续换对象存储；DRF 限流生产必须使用共享 Django cache |
 | 测试 | Django 自带 `manage.py test`（unittest）/ 可选 pytest-django | 已定 | 先用内置 test runner，重点覆盖计费与回调；涉及 `select_for_update` 的并发扣点测试必须在 MySQL 上跑，SQLite 会忽略行锁导致假绿 |
 | 依赖管理 | 系统 Python 3.12 + pip + `requirements.txt` + `pyproject.toml` | 已定 | 不使用虚拟环境；Windows 用 `py -3.12`，Unix/WSL 用 `python3.12`；运行依赖仍由 `requirements.txt` 管理，`pyproject.toml` 只落地 `requires-python` 元数据；init 会显式校验解释器版本在 `>=3.12,<3.14` |
 
@@ -51,12 +51,17 @@
 | --- | --- |
 | 安装依赖（Windows） | `py -3.12 -m pip install -r requirements.txt` |
 | 安装依赖（Unix/WSL） | `python3.12 -m pip install -r requirements.txt` |
+| 安装生产依赖（Linux） | `python3.12 -m pip install -r requirements-production.txt` |
 | 基础检查（Windows） | `py -3.12 manage.py check` |
 | 基础检查（Unix/WSL） | `python3.12 manage.py check` |
 | 测试（Windows） | `py -3.12 manage.py test` |
 | 本地开发（Windows） | `py -3.12 manage.py runserver` |
 | 创建后台管理员 | T-003 后执行 `py -3.12 manage.py createsuperuser` |
 | 数据库迁移 | T-002 接入 MySQL 后执行 `makemigrations` / `migrate` |
+| 生产静态文件收集 | `python3.12 manage.py collectstatic --noinput` |
+| 生产共享 cache 表 | `python3.12 manage.py createcachetable cmhub_cache` |
+| 生产 Gunicorn 普通池 | `gunicorn config.wsgi:application --bind 127.0.0.1:8001 --workers 2 --worker-class gthread --threads 4 --timeout 120` |
+| 生产 Gunicorn 生成池 | `gunicorn config.wsgi:application --bind 127.0.0.1:8002 --workers 1 --worker-class gthread --threads 4 --timeout 360` |
 | 导入 cmbot AI 模型配置 | `py -3.12 manage.py import_ai_models path\to\ai_models.json --create-default-aliases` |
 | AI 生成 smoke（录制标题） | `py -3.12 manage.py smoke_ai_generation title --recorded` |
 | AI 生成 smoke（录制图片） | `py -3.12 manage.py smoke_ai_generation image --recorded` |
diff --git a/docs/04-architecture.md b/docs/04-architecture.md
index 29f8bbe..0a179b9 100644
--- a/docs/04-architecture.md
+++ b/docs/04-architecture.md
@@ -347,7 +347,7 @@ CREATE TABLE call_record (
 | 配置变更审计 | 改密钥/模型/别名映射无痕 | `AiConfigAuditLog` 自动记录后台 create/update/delete；密钥只记录 empty/set 变化，日志只读 |
 | API Key 泄露 | 明文存库一旦泄露全泄 | Key **哈希存储**（sha256），明文只在创建时显示一次，库内存 `key_hash`+`key_prefix`，鉴权做哈希比对 |
 | 注册滥用 | 自助注册被批量刷 | 邮箱验证 + 生成接口限流（DRF throttle）；**注册不送点数**，无免费额度可薅 |
-| Web/API 抢 worker | 图片同步长请求占满 worker、拖慢用户端页面 | 单体下按路径把 `/api/generate/*` 与用户端页面**分流到不同 gunicorn/worker 池**（见 5.1） |
+| Web/API 抢 worker | 图片同步长请求占满 worker、拖慢用户端页面 | 单体下按路径把 `/api/v1/generate/*` 与用户端页面**分流到不同 gunicorn/worker 池**（见 5.1） |
 | 充错账户 | 扫码订单未绑定发起用户 | 订单创建即绑定 `user`；回调按 `order_no` 定位订单→其 user 入账 |
 | SSRF / 任意 URL 下载 | `image_url` 让服务端请求调用方指定地址 | 仅允许公网 http/https；请求前解析 IP 并拒绝内网/回环/链路本地/保留地址；重定向逐跳校验；流式读取并限制大小 |
 
diff --git a/docs/06-tasks.md b/docs/06-tasks.md
index 814d544..fa0b86e 100644
--- a/docs/06-tasks.md
+++ b/docs/06-tasks.md
@@ -73,7 +73,7 @@
 | --- | --- | --- | --- | --- |
 | T-401 | 运营后台完善 | T-302, T-304 | admin 可管理用户/钱包/ApiKey（脱敏）、配规则/汇率、检索充值订单/流水/调用记录；手工调点带原因并经计费层写流水 | DONE |
 | T-402 | 完整验收 MVP | T-401, T-505 | `02-requirements.md` 的 P0 验收全部通过（含用户端注册/充值/API Key/记录） | DONE |
-| T-403 | 部署 / 运行文档 | T-402 | 新环境可按文档运行；明确图片接口超时配置；上线前必须引用一次真实图片生成耗时来设置 Gunicorn `--timeout`、Nginx `proxy_read_timeout`、客户端 read timeout；若尚无真实耗时，部署文档必须显式标注图片同步风险未退，不得声称已验证；生产必须配置真实 `DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL`，否则 allauth 邮箱验证无法发信、用户无法完成登录；**生产静态文件 serving**：T-505 已把 Bootstrap/qrcode 自托管到 `apps/portal/static/`，但 `settings` 目前只有 `STATIC_URL`，`DEBUG=False` 下 Django 不发静态文件——必须配置 `STATIC_ROOT` + `collectstatic` + WhiteNoise 或 Nginx 托管 `/static/`，否则用户端 CSS 错版、充值二维码 404（P2-1 的国内可用性目标在生产失效）；**DRF 限流依赖共享缓存**：多 Gunicorn worker 下默认 `LocMemCache` 是每进程的，会让 `generate`/`api_auth_failure` 限流按 worker 各算一份（实际速率≈worker 数×配置值），部署必须配置 Redis/Memcached 等共享 `CACHES` 后端并在文档说明，否则限流形同虚设 | TODO |
+| T-403 | 部署 / 运行文档 | T-402 | 新环境可按文档运行；明确图片接口超时配置；上线前必须引用一次真实图片生成耗时来设置 Gunicorn `--timeout`、Nginx `proxy_read_timeout`、客户端 read timeout；若尚无真实耗时，部署文档必须显式标注图片同步风险未退，不得声称已验证；生产必须配置真实 `DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL`，否则 allauth 邮箱验证无法发信、用户无法完成登录；**生产静态文件 serving**：T-505 已把 Bootstrap/qrcode 自托管到 `apps/portal/static/`，但 `settings` 目前只有 `STATIC_URL`，`DEBUG=False` 下 Django 不发静态文件——必须配置 `STATIC_ROOT` + `collectstatic` + WhiteNoise 或 Nginx 托管 `/static/`，否则用户端 CSS 错版、充值二维码 404（P2-1 的国内可用性目标在生产失效）；**DRF 限流依赖共享缓存**：多 Gunicorn worker 下默认 `LocMemCache` 是每进程的，会让 `generate`/`api_auth_failure` 限流按 worker 各算一份（实际速率≈worker 数×配置值），部署必须配置 Redis/Memcached 等共享 `CACHES` 后端并在文档说明，否则限流形同虚设 | DONE |
 
 ## 里程碑
 
diff --git a/docs/README.md b/docs/README.md
index 03717ec..603892a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -26,6 +26,7 @@
 - [Phase 3 对外 API 与充值审核](phase-3-review.md)：T-301~305 代码审核结论（鉴权/回调/幂等/入账逐条核对）与优化建议，对应任务 T-306；**P1 提示 `image_url` SSRF 上线前必修**。
 - [Phase 4 用户端审核](phase-4-review.md)：T-501~504 代码审核结论（注册不送点/越权/CSRF/明文只显一次/到账以回调为权威逐条核对）与优化建议（**零 P1**，P2/P3），对应任务 T-505。
 - [MVP 完整验收报告](mvp-acceptance.md)：T-402 对 `02-requirements.md` P0 验收项的逐项结论、测试证据和已知限制。
+- [部署 / 运行文档](deployment.md)：T-403 生产部署步骤、宝塔 / Nginx / Gunicorn 配置、静态文件、共享 cache、图片超时与上线检查。
 - [API 合约](api.md)：对外接口、支付回调、AI 调用模块合约、错误码。
 - [路由与页面结构](routes.md)：API 路由与 django-admin 后台职责。
 - [环境变量与配置](env.md)：Django、数据库、AI 密钥加密、支付、对象存储等配置项。
diff --git a/docs/current-state.md b/docs/current-state.md
index 80bd476..cccd693 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -12,26 +12,26 @@
 ## 当前快照
 
 - 日期：2026-07-03
-- 阶段：Phase 5 后台与发布；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善与 T-402 MVP 完整验收已完成，下一步 T-403 部署 / 运行文档
-- 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + django-allauth 65.18.0 + PyMySQL 1.1.3 + cryptography 46.0.7 + requests 2.34.2 + django-admin；MySQL 8.4 已接入 settings，并支持 `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT`；用户端已用 Django 模板 SSR + Bootstrap + allauth 落地注册登录；详见 `03-tech-stack.md`
-- 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `AiModel` / `ModelAlias`、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey`、`PointsLedger` / `CallRecord`、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate`、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services`，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call`，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView`；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder`、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more`；T-305 已新增 `create_recharge_order()`、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`；T-306 已新增 `apps.api.throttles`、`apps.api.exceptions`、`REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、`image_url` SSRF 防护与响应大小上限、充值单笔金额上限；T-501 已接入 allauth，新增 portal 路由、注册适配器、登录/注册/登出模板和最小 dashboard，注册成功创建 0 点钱包且不写赠点流水；T-502 已新增 `/apikeys`、API Key 创建表单、列表页和删除（吊销）动作，生成后明文只显示一次，列表只显示 prefix；T-503 已扩展 `/dashboard` 为个人中心汇总，并新增 `/records/recharge` 充值记录与 `/records/usage` 消费记录，只读展示当前用户数据；T-504 已新增 `/recharge` 页面、`RechargeCreateForm`、充值导航入口和轮询脚本，页面创建 pending 订单、展示二维码票据、轮询 `/api/v1/recharge/status`，订单 paid 后刷新余额；T-505 已把 Bootstrap 5 CSS 与 qrcode.js vendoring 到 `apps/portal/static/portal/vendor/`，页面不再依赖 jsdelivr，并把充值记录 / 消费记录改为 Django `Paginator` 分页；T-401 已新增 `adjust_wallet_points()` 手工调点服务、钱包 admin 专用调点表单与模板，后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录，流水/订单/调用记录保持只读；T-402 已新增 `docs/mvp-acceptance.md`，按 P0 验收矩阵记录 MVP 完整验收结论、测试证据和已知限制
-- 测试：T-402 已验证：`./init.ps1` 开工前通过；`py -3.12 manage.py test --noinput --keepdb --verbosity 2` 发现 119 tests，已运行 98 tests 后远程 MySQL 在 `apps.portal.tests.PortalAccountFlowTests.setUpClass` 阶段连接重置，已通过用例无断言失败；随后拆分运行同一 119 条测试全部通过：`apps.portal` 21 tests OK、`apps.ai` 26 tests OK、`apps.api` 39 tests OK、`apps.billing apps.users` 33 tests OK；`py -3.12 manage.py smoke_ai_generation title --recorded` 与 `image --recorded` 均通过；`py -3.12 manage.py check` 通过；`py -3.12 manage.py makemigrations --check --dry-run` 无变化；`py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1` 找到两个本地 static 文件；`py -3.12 -m compileall apps config` 通过；`git diff --check` 通过（仅 Windows CRLF 提示）。测试/迁移阶段仍有 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的 `models.W036` 警告；本项目用户账本邮箱唯一性由 `user.email` 唯一约束承担。
+- 阶段：Phase 5 后台与发布；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档已完成；计划内 MVP 任务暂无下一个 `TODO`
+- 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + django-allauth 65.18.0 + PyMySQL 1.1.3 + cryptography 46.0.7 + requests 2.34.2 + django-admin；MySQL 8.4 已接入 settings，并支持 `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT`；用户端已用 Django 模板 SSR + Bootstrap + allauth 落地注册登录；生产部署口径为 VPS / 宝塔 + Nginx + Gunicorn(gthread) + systemd；详见 `03-tech-stack.md` 与 `deployment.md`
+- 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `AiModel` / `ModelAlias`、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey`、`PointsLedger` / `CallRecord`、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate`、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services`，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call`，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView`；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder`、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more`；T-305 已新增 `create_recharge_order()`、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`；T-306 已新增 `apps.api.throttles`、`apps.api.exceptions`、`REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、`image_url` SSRF 防护与响应大小上限、充值单笔金额上限；T-501 已接入 allauth，新增 portal 路由、注册适配器、登录/注册/登出模板和最小 dashboard，注册成功创建 0 点钱包且不写赠点流水；T-502 已新增 `/apikeys`、API Key 创建表单、列表页和删除（吊销）动作，生成后明文只显示一次，列表只显示 prefix；T-503 已扩展 `/dashboard` 为个人中心汇总，并新增 `/records/recharge` 充值记录与 `/records/usage` 消费记录，只读展示当前用户数据；T-504 已新增 `/recharge` 页面、`RechargeCreateForm`、充值导航入口和轮询脚本，页面创建 pending 订单、展示二维码票据、轮询 `/api/v1/recharge/status`，订单 paid 后刷新余额；T-505 已把 Bootstrap 5 CSS 与 qrcode.js vendoring 到 `apps/portal/static/portal/vendor/`，页面不再依赖 jsdelivr，并把充值记录 / 消费记录改为 Django `Paginator` 分页；T-401 已新增 `adjust_wallet_points()` 手工调点服务、钱包 admin 专用调点表单与模板，后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录，流水/订单/调用记录保持只读；T-402 已新增 `docs/mvp-acceptance.md`，按 P0 验收矩阵记录 MVP 完整验收结论、测试证据和已知限制；T-403 已新增 `docs/deployment.md` 与 `requirements-production.txt`，并在 settings 中补齐 `STATIC_ROOT`、`CSRF_TRUSTED_ORIGINS`、共享 `CACHES`、HTTPS cookie、proxy SSL 与 HSTS 环境变量支持
+- 测试：T-403 已验证：`./init.ps1` 开工前通过；`py -3.12 manage.py check` 通过；`py -3.12 manage.py makemigrations --check --dry-run` 无变化；`py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1` 找到两个本地 static 文件；`py -3.12 manage.py check --deploy` 在当前开发 `.env` 下仅报预期安全配置警告，临时注入生产型安全环境变量（含 HSTS includeSubDomains/preload）后通过，0 issues；`py -3.12 manage.py collectstatic --dry-run --noinput` 通过，预期收集 169 个 static 文件；`py -3.12 manage.py createcachetable --dry-run cmhub_cache` 通过，输出 MySQL cache 表 DDL；`py -3.12 -m compileall config` 通过；尝试 `py -3.12 manage.py test apps.api --noinput --keepdb --verbosity 2` 时 25 条用例已通过，`GenerateApiTests` 14 条因远程 MySQL 连接重置/事务中断被记 ERROR，随后 `Test-NetConnection 43.128.3.240 -Port 3306` 端口可达，单独重跑 `py -3.12 manage.py test apps.api.tests.GenerateApiTests --noinput --keepdb --verbosity 2` 通过，14 tests OK。测试/迁移阶段仍有 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的 `models.W036` 警告；本项目用户账本邮箱唯一性由 `user.email` 唯一约束承担。
 - 数据：AI 上游调用与模型配置参考 `D:\chengma\cmbot`（`src/services/ai_text_service.py`、`ai_image_service.py`、`config/ai_models.json`）；真实 `ai_models.json` 不提交，需通过 `import_ai_models` 命令加密导入
 - 标准启动路径：Windows 用 `./init.ps1`；Unix/WSL 用 `./init.sh`
 - 标准验证路径：Windows 用 `py -3.12 manage.py check` / `py -3.12 manage.py test`
 - 设计基线：**自助用户端 + 对外 API + 运营后台**三合一单体；用户模型 `User`(auth)/`UserWallet`(点数，锁 wallet 扣点)/`ApiKey`(1:N，哈希存储)；对外两接口 + **能力别名 + Provider 适配器**（可插拔供应商）；自助扫码充值；注册不送点数。详见 `04-architecture.md` 与 2026-06-29 / 2026-07-01 的 `progress.md` 决策
-- 配置基线：运行环境变量集中见 `docs/env.md`；真实密钥/支付凭证不得写入代码或文档样例。allauth 邮箱验证发信由 `DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL` 控制，本地默认 console backend，生产需配置真实邮件服务。充值订单在创建时锁定汇率与预计点数，回调入账使用订单值，不按新汇率重算。支付回调与下单由 `PAYMENT_CALLBACK_MODE` 控制：本地/测试可用 HMAC `mock`，生产应为 `sdk`；二维码本地有效期提示由 `PAYMENT_QR_EXPIRES_MINUTES` 控制。T-306 起对外 API 安全配置包含 `API_GENERATE_THROTTLE_RATE`、`API_AUTH_FAILURE_THROTTLE_RATE`、`IMAGE_URL_MAX_BYTES`、`IMAGE_URL_MAX_REDIRECTS`、`IMAGE_URL_CONNECT_TIMEOUT_SECONDS`、`IMAGE_URL_READ_TIMEOUT_SECONDS`、`RECHARGE_MAX_AMOUNT_CNY`。
-- 当前 blocker：T-306 上线前 SSRF 风险已修复；远程 MySQL 连接仍可能很慢或间歇超时，完整测试需预留较长时间并优先用 `--keepdb` 串行跑，必要时改用更稳定的测试库。微信/支付宝真实商户密钥/证书与生产 SDK 依赖仍待提供/安装；真实 AI 上游 smoke 需要先配置 `AI_KEY_ENCRYPTION_KEY` 并导入 AiModel/ModelAlias。图片同步真实耗时风险仍未退，已登记到 T-403。
+- 配置基线：运行环境变量集中见 `docs/env.md`；真实密钥/支付凭证不得写入代码或文档样例。allauth 邮箱验证发信由 `DJANGO_EMAIL_BACKEND` / `DJANGO_DEFAULT_FROM_EMAIL` 控制，本地默认 console backend，生产需配置真实邮件服务。充值订单在创建时锁定汇率与预计点数，回调入账使用订单值，不按新汇率重算。支付回调与下单由 `PAYMENT_CALLBACK_MODE` 控制：本地/测试可用 HMAC `mock`，生产应为 `sdk`；二维码本地有效期提示由 `PAYMENT_QR_EXPIRES_MINUTES` 控制。T-306 起对外 API 安全配置包含 `API_GENERATE_THROTTLE_RATE`、`API_AUTH_FAILURE_THROTTLE_RATE`、`IMAGE_URL_MAX_BYTES`、`IMAGE_URL_MAX_REDIRECTS`、`IMAGE_URL_CONNECT_TIMEOUT_SECONDS`、`IMAGE_URL_READ_TIMEOUT_SECONDS`、`RECHARGE_MAX_AMOUNT_CNY`。T-403 起生产静态、共享 cache 与 HTTPS 安全配置包含 `STATIC_URL`、`STATIC_ROOT`、`DJANGO_CACHE_BACKEND`、`DJANGO_CACHE_LOCATION`、`DJANGO_CSRF_TRUSTED_ORIGINS`、`DJANGO_SESSION_COOKIE_SECURE`、`DJANGO_CSRF_COOKIE_SECURE`、`DJANGO_SECURE_SSL_REDIRECT`、`DJANGO_SECURE_PROXY_SSL_HEADER`、`DJANGO_SECURE_HSTS_SECONDS`。
+- 当前 blocker：T-306 上线前 SSRF 风险已修复；远程 MySQL 连接仍可能很慢或间歇超时，完整测试需预留较长时间并优先用 `--keepdb` 串行跑，必要时改用更稳定的测试库。微信/支付宝真实商户密钥/证书与生产 SDK 依赖仍待提供/安装；真实 AI 上游 smoke 需要先配置 `AI_KEY_ENCRYPTION_KEY` 并导入 AiModel/ModelAlias。图片同步真实耗时风险仍未退，T-403 已在 `deployment.md` 明确上线前必须记录真实图片 smoke 耗时；未跑通前只能按保守超时内测，不能声称已验证。
 
 ## 当前目录要点
 
 | 路径 | 状态 | 说明 |
 | --- | --- | --- |
-| `docs/` | 已有 | 全套 harness 文档 |
+| `docs/` | 已有 | 全套 harness 文档；T-403 新增 `deployment.md` |
 | `AGENTS.md` / `CLAUDE.md` | 已有 | 仓库级入口 |
 | `progress.md` | 已有 | 执行流水，已记录多轮文档决策；后续任务继续追加 |
 | `init.sh` / `init.ps1` | 已有 | 启动验证入口，已固定系统 Python 3.12 命令，并校验解释器版本 `>=3.12,<3.14` |
-| `requirements.txt` / `pyproject.toml` | 已有 | `requirements.txt` 管运行依赖；`pyproject.toml` 落地 `requires-python`；T-101 新增 `requests`；T-102 使用既有 `cryptography` 做 Fernet 加密；T-501 新增 `django-allauth` |
+| `requirements.txt` / `requirements-production.txt` / `pyproject.toml` | 已有 | `requirements.txt` 管本地/基础运行依赖；`requirements-production.txt` 追加 Linux 生产 Gunicorn；`pyproject.toml` 落地 `requires-python`；T-101 新增 `requests`；T-102 使用既有 `cryptography` 做 Fernet 加密；T-501 新增 `django-allauth` |
 | `config/`（Django 工程） | 已有 | T-001 创建，含 settings / urls / wsgi / asgi |
 | `apps/`（users/portal/billing/ai/api） | 已有 | T-002 创建；`apps/users` 已定义自定义 `User`；T-003 已注册 admin 与 admin smoke test；T-004 已给 `User.email` 加唯一约束；T-101 已新增 `apps/ai/providers`；T-102 已新增 `apps/ai/security.py`、`aliases.py`、`importers.py`、management command 与 `ai.0001_initial` 迁移；T-103 已新增 `apps/ai/audit.py` 与 `ai.0002_aiconfigauditlog` 迁移；T-104/T-105 已新增 `smoke_ai_generation` 录制 title/image smoke 命令；T-201 已在 users 落 `UserWallet` / `ApiKey`，在 billing 落 `PointsLedger` / `CallRecord`；T-202 已在 billing 落 `PricingRule` / `ExchangeRate` 与 `pricing.py`；T-203/T-303/T-304/T-305 已在 `apps/billing/services.py` 落扣点/退点、余额快照、充值入账与充值下单；T-401 已在 `apps/billing/services.py` 落 `adjust_wallet_points()`，在 `apps/users/admin.py` 与 `apps/users/templates/admin/users/userwallet/adjust_points.html` 落钱包手工调点入口；T-304/T-305 已在 `apps/billing/payment_gateways.py` 落回调验签、mock 下单与 SDK 入口；T-301~T-306 已在 api 落鉴权、生成接口编排、序列化器、图片存储、余额查询、充值回调、充值下单/状态查询、`image_url` SSRF 防护、生成/认证限流与统一 429 错误响应；T-501 已在 portal 落 allauth 注册/登录/登出路由、模板、adapter 与 dashboard；T-502 已在 portal 落 `/apikeys`、API Key 创建表单、列表模板与删除（吊销）动作；T-503 已在 portal 落个人中心汇总、充值记录和消费记录页；T-504 已在 portal 落 `/recharge` 充值页、充值表单、二维码票据展示和状态轮询；T-505 已在 portal 落本地 vendor static 与记录分页 |
 | `manage.py` | 已有 | T-001 创建 |
@@ -41,10 +41,10 @@
 
 任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。
 
-- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP。
+- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP；T-403 部署 / 运行文档。
 - 正在进行：无。
 - 当前 blocker：远程 MySQL 连接当前不稳定或很慢，完整测试单次全绿可能需要稳定测试库；支付商户真实密钥/证书与生产 SDK 依赖仍待提供；真实 AI 上游 smoke 仍需配置密钥和模型数据后执行。
-- 下一个可领取任务：**T-403 部署 / 运行文档**。
+- 下一个可领取任务：计划内 MVP 任务暂无 `TODO`；后续需按 `deployment.md` 实际部署，或从 Backlog 重新拆任务。
 
 ## 当前可运行内容
 
@@ -66,6 +66,14 @@ python3.12 manage.py runserver
 python3.12 manage.py import_ai_models path/to/ai_models.json --create-default-aliases
 python3.12 manage.py smoke_ai_generation title --recorded
 python3.12 manage.py smoke_ai_generation image --recorded
+
+# Linux production
+python3.12 -m pip install -r requirements-production.txt
+python3.12 manage.py migrate
+python3.12 manage.py createcachetable cmhub_cache
+python3.12 manage.py collectstatic --noinput
+gunicorn config.wsgi:application --bind 127.0.0.1:8001 --workers 2 --worker-class gthread --threads 4 --timeout 120
+gunicorn config.wsgi:application --bind 127.0.0.1:8002 --workers 1 --worker-class gthread --threads 4 --timeout 360
 ```
 
 当前对外 API：
@@ -90,14 +98,14 @@ python3.12 manage.py smoke_ai_generation image --recorded
 - `GET /records/recharge`
 - `GET /records/usage`
 
-当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email`，`user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias`，`resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog`，admin 保存/删除 `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix；CallRecord 只存 `result_ref`/`result_summary`，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate`：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()`：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer <API_KEY>` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey`，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302 已落地生成接口：请求别名解析后按规则计费，预扣成功才调用 Provider，成功确认调用记录，`AiProviderError` / `AiCapabilityError` 等失败路径会退点；图片结果保存到本地 media 并返回 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回 `user` 与 `points_balance`，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。T-306 已落地对外 API 安全加固：`image_url` 下载在扣点前做协议白名单、公网地址校验、重定向逐跳校验和响应大小上限；DRF 全局默认不再隐式启用 Session/Basic；生成接口按 Key 限流，认证失败按 IP 限流；充值下单有单笔金额上限。T-501 已落地 allauth 注册 / 登录：`ACCOUNT_EMAIL_VERIFICATION="mandatory"`，注册成功创建 0 点钱包、不写点数流水；未验证邮箱不能建立登录 session。T-502 已落地 API Key 自助管理：`/apikeys` 登录访问，生成后完整明文只显示一次，列表只显示 prefix，不显示 hash 或历史明文；删除为吊销 `revoked`，吊销后外部 API 返回 403。T-503 已落地个人中心与记录页：`/dashboard` 展示剩余点数、充值总额、入账点数、净消耗点数和最近记录；`/records/recharge` 展示当前用户充值订单；`/records/usage` 展示当前用户 consume/refund 点数流水并关联调用信息；所有页面均只读且只查本人。T-504 已落地充值页：`/recharge` GET 展示余额、充值表单、当前订单和最近充值，POST 创建 pending 订单并展示二维码票据，浏览器轮询 `/api/v1/recharge/status`，paid 后刷新页面重新读取余额；页面不直接写钱包或流水。T-401 已落地运营后台完善：用户列表显示钱包余额，钱包余额只读且通过专用表单手工调点，调点必须填原因、非 0、不得扣成负数，并经 `adjust_wallet_points()` 锁钱包写 `PointsLedger(adjust)`；API Key admin 只展示 prefix 和 hash 摘要，不回显明文或完整 hash；订单、流水、调用记录继续只读并增强检索。T-402 已完成 MVP P0 验收并新增 `docs/mvp-acceptance.md`。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再通过接口跑真实标题/图片。
+当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email`，`user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias`，`resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog`，admin 保存/删除 `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix；CallRecord 只存 `result_ref`/`result_summary`，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate`：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()`：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer <API_KEY>` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey`，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302 已落地生成接口：请求别名解析后按规则计费，预扣成功才调用 Provider，成功确认调用记录，`AiProviderError` / `AiCapabilityError` 等失败路径会退点；图片结果保存到本地 media 并返回 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回 `user` 与 `points_balance`，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。T-306 已落地对外 API 安全加固：`image_url` 下载在扣点前做协议白名单、公网地址校验、重定向逐跳校验和响应大小上限；DRF 全局默认不再隐式启用 Session/Basic；生成接口按 Key 限流，认证失败按 IP 限流；充值下单有单笔金额上限。T-501 已落地 allauth 注册 / 登录：`ACCOUNT_EMAIL_VERIFICATION="mandatory"`，注册成功创建 0 点钱包、不写点数流水；未验证邮箱不能建立登录 session。T-502 已落地 API Key 自助管理：`/apikeys` 登录访问，生成后完整明文只显示一次，列表只显示 prefix，不显示 hash 或历史明文；删除为吊销 `revoked`，吊销后外部 API 返回 403。T-503 已落地个人中心与记录页：`/dashboard` 展示剩余点数、充值总额、入账点数、净消耗点数和最近记录；`/records/recharge` 展示当前用户充值订单；`/records/usage` 展示当前用户 consume/refund 点数流水并关联调用信息；所有页面均只读且只查本人。T-504 已落地充值页：`/recharge` GET 展示余额、充值表单、当前订单和最近充值，POST 创建 pending 订单并展示二维码票据，浏览器轮询 `/api/v1/recharge/status`，paid 后刷新页面重新读取余额；页面不直接写钱包或流水。T-401 已落地运营后台完善：用户列表显示钱包余额，钱包余额只读且通过专用表单手工调点，调点必须填原因、非 0、不得扣成负数，并经 `adjust_wallet_points()` 锁钱包写 `PointsLedger(adjust)`；API Key admin 只展示 prefix 和 hash 摘要，不回显明文或完整 hash；订单、流水、调用记录继续只读并增强检索。T-402 已完成 MVP P0 验收并新增 `docs/mvp-acceptance.md`。T-403 已完成部署 / 运行文档，生产按 `deployment.md` 执行，并已补 settings 对生产静态目录、共享 cache、CSRF trusted origins、HTTPS cookie/proxy/HSTS 的环境变量支持。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再通过接口跑真实标题/图片并记录图片耗时。
 
 ## 开始编码前检查
 
 1. 读仓库级 `AGENTS.md` / `CLAUDE.md`。
 2. 读 `docs/00-ai-start-here.md`。
 3. 读 `docs/05-coding-rules.md`（尤其第 8 节资金安全）。
-4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务（当前为 T-403）。
+4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务（当前计划内 MVP 任务暂无 `TODO`；继续开发前需先从 Backlog 拆新任务）。
 5. 将该任务状态改为 `DOING`。
 
 ## 维护规则
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..a46ed80
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,302 @@
+# 部署 / 运行文档（T-403）
+
+> 面向 VPS + 宝塔面板 + Nginx + MySQL 8.4 的 MVP 部署说明。本文只写可执行步骤和上线前检查，不保存真实密钥、数据库密码、支付凭证或上游 API Key。
+
+## 一、部署目标
+
+生产形态：
+
+```text
+公网 HTTPS
+  -> 宝塔 / Nginx
+      /static/ -> STATIC_ROOT
+      /media/  -> MEDIA_ROOT（MVP 本地媒体；后续可换对象存储）
+      /api/v1/generate/* -> Gunicorn 长请求池（图片同步，超时更长）
+      其他路径 -> Gunicorn 普通请求池（用户端 / admin / 余额 / 充值）
+  -> cmhub Django 单体
+  -> MySQL 8.4
+  -> Django shared cache（MVP 可用 MySQL DatabaseCache；高并发换 Redis/Memcached）
+```
+
+当前约束：
+
+- 使用系统 Python 3.12，不使用虚拟环境。
+- 图片生成仍是同步接口；真实图片生成耗时尚未在生产链路验证，**上线前必须跑一次真实图片 smoke 并记录耗时**。
+- 真实支付需微信 / 支付宝商户密钥、证书、生产 SDK 与公网回调地址；未配置前只能用 `PAYMENT_CALLBACK_MODE=mock`。
+
+## 二、系统准备
+
+1. 安装系统依赖：
+
+```bash
+python3.12 --version
+python3.12 -m pip --version
+```
+
+2. 准备 MySQL 8.4：
+
+- 使用 cmhub 专用 MySQL 8.4 实例，不复用已有 MySQL 5.7。
+- 默认端口为 `3306`；如果 VPS 上已有 MySQL 占用 3306，则为 cmhub 的 MySQL 8.4 配专用端口，并同步写入 `.env` 的 `MYSQL_PORT`。
+- 数据库字符集使用 `utf8mb4`，表引擎使用 InnoDB。
+
+示例 SQL（密码仅占位）：
+
+```sql
+CREATE DATABASE cmhub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'cmhub'@'%' IDENTIFIED BY 'change-me-strong-password';
+GRANT ALL PRIVILEGES ON cmhub.* TO 'cmhub'@'%';
+FLUSH PRIVILEGES;
+```
+
+3. 拉取代码到生产目录，例如：
+
+```bash
+cd /www/wwwroot
+git clone <your-remote-url> cmhub
+cd /www/wwwroot/cmhub
+```
+
+## 三、安装依赖
+
+生产 Linux 安装运行依赖：
+
+```bash
+python3.12 -m pip install -r requirements-production.txt
+```
+
+如果启用真实支付 SDK，还需按支付 SDK 文档在生产机安装：
+
+```bash
+python3.12 -m pip install wechatpayv3 python-alipay-sdk
+```
+
+如果暂未提供真实商户配置，不安装支付 SDK 也能以 `PAYMENT_CALLBACK_MODE=mock` 运行本地/测试流程。
+
+## 四、配置 `.env`
+
+从样例复制后只在部署机填写真实值：
+
+```bash
+cp .env.example .env
+```
+
+生产关键配置：
+
+```dotenv
+DJANGO_SECRET_KEY=change-me-to-a-long-random-secret
+DJANGO_DEBUG=false
+DJANGO_ALLOWED_HOSTS=cmhub.example.com,127.0.0.1
+DJANGO_CSRF_TRUSTED_ORIGINS=https://cmhub.example.com
+DJANGO_TIME_ZONE=Asia/Shanghai
+
+DJANGO_EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
+DJANGO_DEFAULT_FROM_EMAIL=noreply@cmhub.example.com
+DJANGO_SESSION_COOKIE_SECURE=true
+DJANGO_CSRF_COOKIE_SECURE=true
+DJANGO_SECURE_PROXY_SSL_HEADER=true
+DJANGO_SECURE_SSL_REDIRECT=false
+DJANGO_SECURE_HSTS_SECONDS=0
+
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_DATABASE=cmhub
+MYSQL_USER=cmhub
+MYSQL_PASSWORD=change-me
+MYSQL_CHARSET=utf8mb4
+MYSQL_CONNECT_TIMEOUT=30
+MYSQL_READ_TIMEOUT=120
+MYSQL_WRITE_TIMEOUT=120
+
+STATIC_URL=/static/
+STATIC_ROOT=/www/wwwroot/cmhub/staticfiles
+MEDIA_ROOT=/www/wwwroot/cmhub/media
+MEDIA_URL=/media/
+
+DJANGO_CACHE_BACKEND=django.core.cache.backends.db.DatabaseCache
+DJANGO_CACHE_LOCATION=cmhub_cache
+
+AI_KEY_ENCRYPTION_KEY=base64-fernet-key
+
+PAYMENT_CALLBACK_MODE=sdk
+WECHAT_PAY_NOTIFY_URL=https://cmhub.example.com/api/v1/recharge/callback/wechat
+ALIPAY_NOTIFY_URL=https://cmhub.example.com/api/v1/recharge/callback/alipay
+```
+
+生成 Fernet 主密钥：
+
+```bash
+python3.12 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+注意：
+
+- `AI_KEY_ENCRYPTION_KEY` 生产不可随意更换；更换会导致已加密的 `AiModel.api_key_encrypted` 无法解密。
+- 生产必须配置真实邮件服务，否则 allauth 邮箱验证邮件发不出，用户无法完成注册登录。
+- `PAYMENT_CALLBACK_MODE=sdk` 必须配齐微信 / 支付宝商户配置；未配齐时先保持 `mock`。
+- 宝塔 / Nginx 已强制 HTTPS 时，`DJANGO_SECURE_SSL_REDIRECT=false` 即可；全站 HTTPS 稳定后再把 `DJANGO_SECURE_HSTS_SECONDS` 调大，避免 HSTS 误锁域名。
+
+## 五、初始化数据库与静态文件
+
+```bash
+python3.12 manage.py check
+python3.12 manage.py migrate
+python3.12 manage.py createcachetable cmhub_cache
+python3.12 manage.py collectstatic --noinput
+python3.12 manage.py createsuperuser
+```
+
+如果后续改用 Redis / Memcached，则把 `DJANGO_CACHE_BACKEND` / `DJANGO_CACHE_LOCATION` 换成对应共享后端配置，并安装对应 Python backend 依赖。多 Gunicorn worker 下不要使用默认 `LocMemCache`，否则生成接口和认证失败限流会按 worker 各算一份。
+
+## 六、导入 AI 模型配置
+
+真实上游调用前：
+
+```bash
+python3.12 manage.py import_ai_models /secure/cmhub/ai_models.json --create-default-aliases
+```
+
+要求：
+
+- `/secure/cmhub/ai_models.json` 不提交到 git。
+- `AiModel.timeout_seconds` 不能继续依赖默认 `0` 口径上线；图片模型必须按真实耗时设置读取超时。
+- 运营后台需配置 `PricingRule` 和 `ExchangeRate`，否则生成和充值会因缺规则被拒绝。
+
+## 七、Gunicorn 运行
+
+建议把同步图片生成分流到独立 Gunicorn 池，避免长请求占满普通页面和 admin 的 worker。
+
+普通请求池示例：
+
+```bash
+gunicorn config.wsgi:application \
+  --bind 127.0.0.1:8001 \
+  --workers 2 \
+  --worker-class gthread \
+  --threads 4 \
+  --timeout 120 \
+  --access-logfile - \
+  --error-logfile -
+```
+
+生成长请求池示例：
+
+```bash
+gunicorn config.wsgi:application \
+  --bind 127.0.0.1:8002 \
+  --workers 1 \
+  --worker-class gthread \
+  --threads 4 \
+  --timeout 360 \
+  --access-logfile - \
+  --error-logfile -
+```
+
+`--timeout` 必须按真实图片生成耗时校准：`Gunicorn timeout` 应大于 `AiModel.timeout_seconds`，Nginx `proxy_read_timeout` 应大于 Gunicorn timeout，调用方 read timeout 应不小于 Nginx。
+
+systemd 单元可分别命名为 `cmhub-web.service` 和 `cmhub-generate.service`。服务的 `WorkingDirectory` 指向 `/www/wwwroot/cmhub`，`ExecStart` 使用上面的两条 Gunicorn 命令，环境变量由项目根目录 `.env` 在 Django settings 中读取。
+
+## 八、宝塔 / Nginx 配置
+
+宝塔中新建站点并绑定域名和 SSL 后，在站点 Nginx 配置中加入或调整：
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name cmhub.example.com;
+
+    client_max_body_size 25m;
+
+    location /static/ {
+        alias /www/wwwroot/cmhub/staticfiles/;
+        expires 30d;
+        add_header Cache-Control "public";
+    }
+
+    location /media/ {
+        alias /www/wwwroot/cmhub/media/;
+        expires 7d;
+        add_header Cache-Control "public";
+    }
+
+    location /api/v1/generate/ {
+        proxy_pass http://127.0.0.1:8002;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 360s;
+        proxy_read_timeout 360s;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:8001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_connect_timeout 30s;
+        proxy_send_timeout 120s;
+        proxy_read_timeout 120s;
+    }
+}
+```
+
+说明：
+
+- `/static/` 必须指向 `STATIC_ROOT`，否则 Bootstrap/qrcode 本地资源在 `DEBUG=False` 下 404。
+- `/media/` 是 MVP 本地图片结果访问路径；如果改对象存储，应同步更新 `MEDIA_URL` 和存储配置。
+- 宝塔若已在外层配置 HTTP 到 HTTPS 跳转，`DJANGO_SECURE_SSL_REDIRECT=false` 即可；如果由 Django 负责跳转，再设为 `true`。
+
+## 九、上线前验证
+
+基础验证：
+
+```bash
+python3.12 manage.py check
+python3.12 manage.py check --deploy
+python3.12 manage.py makemigrations --check --dry-run
+python3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1
+python3.12 manage.py collectstatic --dry-run --noinput
+```
+
+账务与用户端测试：
+
+```bash
+python3.12 manage.py test apps.billing apps.users --noinput --keepdb --verbosity 2
+python3.12 manage.py test apps.api --noinput --keepdb --verbosity 2
+python3.12 manage.py test apps.portal --noinput --keepdb --verbosity 2
+```
+
+AI smoke：
+
+```bash
+python3.12 manage.py smoke_ai_generation title --recorded
+python3.12 manage.py smoke_ai_generation image --recorded
+python3.12 manage.py smoke_ai_generation title
+python3.12 manage.py smoke_ai_generation image
+```
+
+上线前必须记录真实 `image` smoke 的 `elapsed_ms`，并据此回填：
+
+- 图片 `AiModel.timeout_seconds`
+- Gunicorn 长请求池 `--timeout`
+- Nginx `/api/v1/generate/` 的 `proxy_read_timeout`
+- 接入方客户端 read timeout
+
+如果真实图片 smoke 仍未跑通，只能按保守值（例如 300s~360s）上线内测，并在发布记录中明确“图片同步真实耗时风险未退”，不能声称已验证生产图片链路。
+
+## 十、发布检查清单
+
+- `DJANGO_DEBUG=false`。
+- `DJANGO_SECRET_KEY`、`AI_KEY_ENCRYPTION_KEY`、MySQL 密码、支付密钥均为生产值且未提交。
+- `DJANGO_ALLOWED_HOSTS`、`DJANGO_CSRF_TRUSTED_ORIGINS`、微信 / 支付宝 `notify_url` 使用同一 HTTPS 域名。
+- 邮件后端可发送验证邮件。
+- HTTPS 已由宝塔 / Nginx 强制跳转；如由 Django 强制跳转则设置 `DJANGO_SECURE_SSL_REDIRECT=true`。HSTS 只在确认全站 HTTPS 后启用。
+- `STATIC_ROOT` 已 `collectstatic`，Nginx 可访问 `/static/portal/vendor/bootstrap/bootstrap.min.css` 和 `/static/portal/vendor/qrcode/qrcode.js`。
+- `MEDIA_ROOT` 或对象存储可访问生成图片 URL。
+- `DJANGO_CACHE_BACKEND` 为共享 cache，不是 `LocMemCache`。
+- MySQL 是 8.4 / InnoDB / `utf8mb4`。
+- 真实支付 SDK 与商户配置齐全后，`PAYMENT_CALLBACK_MODE=sdk`。
+- 真实图片生成耗时已记录并用于设置超时链路；若未记录，发布说明必须标注风险。
+- `manage.py check`、迁移、静态文件、关键测试和 smoke 均有记录。
diff --git a/docs/env.md b/docs/env.md
index 5507a15..5142147 100644
--- a/docs/env.md
+++ b/docs/env.md
@@ -21,6 +21,13 @@
 | `DJANGO_TIME_ZONE` | 否 | `Asia/Shanghai` | 默认按中国业务时区 |
 | `DJANGO_EMAIL_BACKEND` | 否 | `django.core.mail.backends.console.EmailBackend` | allauth 注册邮箱验证发信后端；生产应改为真实 SMTP / 邮件服务 |
 | `DJANGO_DEFAULT_FROM_EMAIL` | 生产是 | `noreply@cmhub.example.com` | allauth 邮件默认发件人 |
+| `DJANGO_SESSION_COOKIE_SECURE` | 生产是 | `true` | 生产 HTTPS 下 session cookie 仅允许安全连接传输 |
+| `DJANGO_CSRF_COOKIE_SECURE` | 生产是 | `true` | 生产 HTTPS 下 CSRF cookie 仅允许安全连接传输 |
+| `DJANGO_SECURE_SSL_REDIRECT` | 否 | `false` | 若 Nginx/宝塔已强制 HTTPS，可保持 `false`；若由 Django 强制跳转则设 `true` |
+| `DJANGO_SECURE_HSTS_SECONDS` | 否 | `31536000` | 全站确认只走 HTTPS 后再启用；未确认前保持 `0`，避免 HSTS 误锁域名 |
+| `DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS` | 否 | `false` | 是否把 HSTS 应用于子域名 |
+| `DJANGO_SECURE_HSTS_PRELOAD` | 否 | `false` | 是否声明 HSTS preload；提交 preload 前必须确认全部子域长期 HTTPS |
+| `DJANGO_SECURE_PROXY_SSL_HEADER` | 反代 HTTPS 是 | `true` | Nginx 反代并传 `X-Forwarded-Proto https` 时开启，避免 Django 误判当前请求为 HTTP |
 
 ## 三、数据库配置
 
@@ -64,7 +71,18 @@ AI 上游连接超时与读取超时不走全局环境变量：连接超时由 `
 
 `image_url` 只允许 `http` / `https`，服务端会在请求前解析域名，拒绝私有网段、回环、链路本地、保留地址、组播、未指定地址；重定向后的目标地址也会重复执行同样校验。内网图片不应通过 `image_url` 传入，调用方应改用 `image_base64`。
 
-## 六、支付配置
+## 六、静态文件与限流缓存
+
+| 变量 | 必填 | 示例 | 说明 |
+| --- | --- | --- | --- |
+| `STATIC_URL` | 否 | `/static/` | 静态资源 URL 前缀 |
+| `STATIC_ROOT` | 生产是 | `/www/wwwroot/cmhub/staticfiles` | `collectstatic` 输出目录，Nginx/宝塔需托管此目录 |
+| `DJANGO_CACHE_BACKEND` | 生产是 | `django.core.cache.backends.db.DatabaseCache` | Django cache 后端；开发可用 locmem，生产多 Gunicorn worker 必须用共享后端 |
+| `DJANGO_CACHE_LOCATION` | 生产是 | `cmhub_cache` | cache 位置；DatabaseCache 时为表名，Redis/Memcached 时为连接地址 |
+
+生产限流依赖 Django cache。默认 `LocMemCache` 只适合单进程本地开发；多 worker 部署时每个进程各算一份限流，会放大实际请求速率。MVP 可先用 MySQL 的 `DatabaseCache`，部署时执行 `python3.12 manage.py createcachetable cmhub_cache`；高并发后再换 Redis / Memcached 等共享 cache，并同步安装对应 backend 依赖。
+
+## 七、支付配置
 
 | 变量 | 必填 | 示例 | 说明 |
 | --- | --- | --- | --- |
@@ -95,7 +113,7 @@ AI 上游连接超时与读取超时不走全局环境变量：连接超时由 `
 
 缺少真实商户配置时，充值任务只能使用 mock 支付客户端；mock 必须在代码和测试中标明，不得伪装成真实支付。
 
-## 七、对象存储配置
+## 八、对象存储配置
 
 图片结果默认返回 URL，避免大 base64 进入同步响应体。对象存储选型未最终落地前，可使用本地开发存储，但生产必须给出可公开访问或可签名访问的 URL。
 
@@ -109,11 +127,15 @@ AI 上游连接超时与读取超时不走全局环境变量：连接超时由 `
 | `S3_ACCESS_KEY_ID` | s3 是 | `change-me` | access key |
 | `S3_SECRET_ACCESS_KEY` | s3 是 | `change-me` | secret key |
 
-## 八、上线前检查
+## 九、上线前检查
 
 - `DJANGO_DEBUG=false`。
 - `DJANGO_SECRET_KEY`、`AI_KEY_ENCRYPTION_KEY`、数据库密码、支付密钥均已使用生产值。
 - `ALLOWED_HOSTS`、`CSRF_TRUSTED_ORIGINS`、支付 `notify_url` 使用同一公网域名。
+- `STATIC_ROOT` 已执行 `collectstatic`，Nginx/宝塔已托管 `/static/`；若继续用本地媒体存储，也必须托管 `/media/` 或切换对象存储。
+- `DJANGO_CACHE_BACKEND` 已切到共享后端（如 DatabaseCache / Redis / Memcached），不是默认 `LocMemCache`。
+- 生产 HTTPS 下 `DJANGO_SESSION_COOKIE_SECURE=true`、`DJANGO_CSRF_COOKIE_SECURE=true`，反代场景按需开启 `DJANGO_SECURE_PROXY_SSL_HEADER=true`。
+- 全站 HTTPS 稳定后再设置 `DJANGO_SECURE_HSTS_SECONDS`；未确认子域名 HTTPS 前不要启用 includeSubDomains / preload。
 - MySQL 为 8.4 LTS / InnoDB / `utf8mb4`，不是 SQLite 或已有 MySQL 5.7。
 - `image_url` 下载上限、生成限流、认证失败限流、单笔充值金额上限已按生产容量调整。
 - 图片同步链路的客户端、Nginx、Gunicorn、上游 read timeout 均按最慢图片模型放大到同一量级。
diff --git a/docs/project-brief.md b/docs/project-brief.md
index 57b7cb9..d0db6e7 100644
--- a/docs/project-brief.md
+++ b/docs/project-brief.md
@@ -1,7 +1,7 @@
 # cmhub 项目介绍（给管理层）
 
 > 面向决策与汇报的项目概览。技术细节见同目录架构与需求文档。
-> 日期：2026-07-03 ｜ 阶段：Phase 5 后台与发布（T-402 已完成）
+> 日期：2026-07-03 ｜ 阶段：Phase 5 后台与发布（计划内 MVP 任务已完成）
 
 ## 一句话概括
 
@@ -107,7 +107,8 @@
 - Phase 4 已完成 T-501~T-505：用户端注册 / 登录（allauth）、邮箱验证、登出、API Key 自助管理、个人中心汇总、充值记录、消费记录和充值页已落地；用户可创建充值订单、查看二维码票据并轮询到账；Key 明文只显示一次，库内只保留 hash 和 prefix，删除即吊销；记录页仅见本人数据并支持分页；Bootstrap 与 qrcode.js 已改为本地 static 自托管。
 - Phase 5 已完成 T-401：运营后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录；手工调点必须填写原因，并经计费层锁钱包、写 `adjust` 流水。
 - Phase 5 已完成 T-402：MVP P0 验收通过，注册/充值/API Key/调用/余额/记录/后台/别名映射均有测试证据，详见 `mvp-acceptance.md`。
-- 下一步是 T-403：补部署 / 运行文档，明确生产静态文件 serving、邮件后端、共享缓存限流、图片同步超时和真实商户配置。
+- Phase 5 已完成 T-403：已补部署 / 运行文档，明确宝塔/Nginx/Gunicorn、生产静态与媒体文件、真实邮件后端、共享缓存限流、图片同步超时、真实商户配置和上线检查，详见 `deployment.md`。
+- 下一步是按 `deployment.md` 在 VPS 上配置真实环境，并补跑真实支付和真实 AI 图片耗时验证。
 
 ---
 *更多细节：愿景 `01-vision.md` ｜ 需求与验收 `02-requirements.md` ｜ 架构 `04-architecture.md` ｜ 任务计划 `06-tasks.md`。*
diff --git a/docs/project-onepager.md b/docs/project-onepager.md
index e67d50a..18308bb 100644
--- a/docs/project-onepager.md
+++ b/docs/project-onepager.md
@@ -40,7 +40,7 @@
 
 ## 进度
 
-M1 骨架已完成；M2 已通过录制生成 smoke 验证 AI 调用链路；M3 计费、对外 API、充值闭环与上线前安全加固已完成到 T-306；M4 用户端已完成注册 / 登录、API Key 管理、个人中心 / 记录页、充值页和审核优化；M5 已完成 T-401 运营后台完善与 T-402 MVP 完整验收，下一步做 T-403 部署 / 运行文档。里程碑：M1 骨架可跑 · M2 跑通生成 · M3 计费充值闭环 · M4 用户端可用 · M5 验收上线。
+M1 骨架已完成；M2 已通过录制生成 smoke 验证 AI 调用链路；M3 计费、对外 API、充值闭环与上线前安全加固已完成到 T-306；M4 用户端已完成注册 / 登录、API Key 管理、个人中心 / 记录页、充值页和审核优化；M5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档。下一步是在 VPS 上按部署文档接真实邮件、支付、AI 模型并补真实图片耗时验证。里程碑：M1 骨架可跑 · M2 跑通生成 · M3 计费充值闭环 · M4 用户端可用 · M5 验收上线。
 
 ---
 *详见 `project-brief.md`（完整介绍）。*
diff --git a/progress.md b/progress.md
index 3149af1..040e6c5 100644
--- a/progress.md
+++ b/progress.md
@@ -940,3 +940,31 @@
 - 已知限制：真实微信/支付宝商户凭证和生产 SDK 未接入；真实 AI 上游 smoke 尚未执行；图片同步真实耗时仍未验证，需在 T-403 部署 / 运行文档中明确超时配置和风险口径。
 - 决策：T-402 不改业务代码，仅完成验收、口径修正和文档归档；MVP P0 结论为通过。
 - 下一步：领取 T-403 部署 / 运行文档。
+
+## 2026-07-03 T-403 部署 / 运行文档
+
+- 状态：DONE
+- 变更：
+  - 新增 `docs/deployment.md`：按 VPS / 宝塔 / Nginx / Gunicorn(gthread) / MySQL 8.4 写生产部署步骤，覆盖 `.env`、迁移、`collectstatic`、共享 cache、双 Gunicorn 池、Nginx 分流、上线检查和真实图片耗时验证口径。
+  - 新增 `requirements-production.txt`：Linux 生产运行在基础依赖外追加 Gunicorn，避免 Windows 本地开发强制安装生产 runner。
+  - `config/settings.py`：新增 `STATIC_ROOT`、`STATIC_URL` 环境变量支持；新增 `CSRF_TRUSTED_ORIGINS`；新增 `CACHES` 环境变量配置，生产可用 DatabaseCache / Redis / Memcached 等共享 cache；新增 HTTPS cookie、proxy SSL 与 HSTS 环境变量支持。
+  - `.env.example` / `docs/env.md`：同步新增生产静态、共享 cache、CSRF trusted origins、HTTPS cookie/proxy/HSTS 配置项。
+  - `docs/03-tech-stack.md`：部署方式定为 VPS / 宝塔 + Nginx + Gunicorn(gthread) + systemd，并记录生产安装、cache table、collectstatic 与 Gunicorn 命令。
+  - `docs/04-architecture.md`：修正部署分流路径为实际的 `/api/v1/generate/*`。
+  - 同步更新 `README.md`、`docs/00-ai-start-here.md`、`docs/README.md`、`docs/06-tasks.md`、`docs/current-state.md`、`docs/project-brief.md`、`docs/project-onepager.md`；T-403 标记 DONE，计划内 MVP 任务暂无下一个 TODO。
+- 验证：
+  - `./init.ps1`：开工前通过。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py makemigrations --check --dry-run`：通过，No changes detected。
+  - `py -3.12 manage.py findstatic portal/vendor/bootstrap/bootstrap.min.css portal/vendor/qrcode/qrcode.js --verbosity 1`：通过，两个本地 static 文件均可发现。
+  - `py -3.12 manage.py check --deploy`：当前开发 `.env` 下只报预期安全配置警告；临时注入生产型安全环境变量（含 HSTS includeSubDomains/preload）后通过，0 issues。
+  - `py -3.12 manage.py collectstatic --dry-run --noinput`：通过，预期收集 169 个 static 文件。
+  - `py -3.12 manage.py createcachetable --dry-run cmhub_cache`：通过，输出 MySQL cache 表 DDL。
+  - `py -3.12 -m compileall config`：通过。
+  - 尝试 `py -3.12 manage.py test apps.api --noinput --keepdb --verbosity 2`：未取得单次全绿；25 条用例通过，`GenerateApiTests` 14 条因远程 MySQL `OperationalError 2013` / 连接重置 / 事务中断被记 ERROR。
+  - `Test-NetConnection 43.128.3.240 -Port 3306`：`TcpTestSucceeded=True`。
+  - `py -3.12 manage.py test apps.api.tests.GenerateApiTests --noinput --keepdb --verbosity 2`：通过，14 tests OK。
+- 阻塞：T-403 文档与配置支撑无功能阻塞；完整 API 套件单次运行仍受远程 MySQL 间歇断连影响。
+- 已知限制：真实 AI 上游和真实图片耗时仍未验证，因当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库无真实 AiModel/ModelAlias；真实微信/支付宝商户配置和 SDK 仍待生产环境提供。`deployment.md` 已明确未跑通真实图片 smoke 前不能声称生产图片链路已验证。
+- 决策：生产限流共享 cache 的 MVP 推荐路径先用 Django `DatabaseCache` + MySQL cache 表，不引入 Redis 作为当前代码依赖；高并发后可切换 Redis/Memcached 并安装对应 backend。生产静态资源采用 `STATIC_ROOT + collectstatic + Nginx/宝塔托管`，不在应用内引入 WhiteNoise。
+- 下一步：计划内 MVP 任务已完成；进入 VPS 实际部署、真实邮件/支付/AI 配置和真实图片耗时验证，或从 Backlog 重新拆后续任务。
diff --git a/requirements-production.txt b/requirements-production.txt
new file mode 100644
index 0000000..57ae7ae
--- /dev/null
+++ b/requirements-production.txt
@@ -0,0 +1,4 @@
+-r requirements.txt
+
+# Linux production runtime. Keep Windows development on requirements.txt.
+gunicorn>=23,<24