mz/video-gen
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加架构md跟使用md优化

Browse Source
This commit is contained in:
root
2026-07-11 09:17:07 +08:00
parent 8641d507e6
commit 111c74c7c6
2 changed files with 1047 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEPLOYMENT.md
+245 -70
View File
@@ -5,11 +5,13 @@
```
video_item/
├── video-gen-api/ # 后端 (Python FastAPI + SQLAlchemy + Alembic)
├── video-gen-app/ # 前台 (React 19 + Vite 8 + Ant Design 6 + Tailwind)
├── video-gen-admin/ # 后台管理 (React 19 + Vite 8 + Ant Design 6)
├── video-gen-app/ # 前台/用户端 (React 19 + Vite 8 + Ant Design 6)
├── video-gen-admin/ # 后台管理端 (React 19 + Vite 8 + Ant Design 6)
└── DEPLOYMENT.md # 本文档
```
**三个前端/后端的关系:** `video-gen-app` (用户前台) 和 `video-gen-admin` (管理后台) 都连接同一个 `video-gen-api` 后端。
---
## 一、环境要求
@@ -18,14 +20,13 @@ video_item/
|------|---------|------|
| Python | >= 3.10 | 推荐 3.12 |
| Node.js | >= 18 | 推荐 20+ |
| PostgreSQL | >= 14 | 推荐 16 |
| Redis | >= 6 | 可选，推荐用于限流/验证码/Celery |
| FFmpeg | 任意 | 可选，用于视频封面截帧 |
| alipay-sdk-python | >=3.7.1160 | 可选，用于支付 |
| wechatpayv3 | >=2.0.2 | 可选，用于支付 |
| volcengine-python-sdk | >=1.1.0 | 可选，用于视频生成 |
| PostgreSQL | >= 14 | 推荐 16；**必须** |
| Redis | >= 6 | 推荐用于: 限流/验证码/Celery/任务状态 |
| FFmpeg | 任意 | 用于视频封面截帧，留空时从 PATH 自动查找 |
| ca-certificates | 任意 | **必须**，HTTPS 请求需要（新服务器/容器常缺） |
| alipay-sdk-python | >=3.7.1160 | 可选，支付宝支付 |
| wechatpayv3 | >=2.0.2 | 可选，微信支付 |
| volcengine-python-sdk | >=1.1.0 | 可选，视频生成/短信 |
---
@@ -34,7 +35,7 @@ video_item/
### 1. 安装依赖
```bash
# ⚠️ 新服务器/容器必须先装 CA 证书，否则 HTTPS 请求（支付宝/火山等）全部失败
# ⚠️ 新服务器/容器必须先装 CA 证书，否则 HTTPS（支付宝/火山等）全部失败
# CentOS/RHEL
sudo yum install -y ca-certificates
# Ubuntu/Debian
@@ -49,7 +50,10 @@ python -m venv .venv
# Linux/Mac
source .venv/bin/activate
# 安装基础依赖 + PostgreSQL 驱动
# 安装基础依赖
pip install -e .
# 安装 PostgreSQL 驱动（生产环境必须）
pip install -e ".[pg]"
# 如需 Redis 支持（限流、验证码、Celery）
@@ -58,21 +62,19 @@ pip install -e ".[pg,redis]"
# 如需 Celery 异步任务（ChatAPI 生成流水线）
pip install -e ".[pg,redis,celery]"
#安装阿里支付sdk
# 如需支付宝
pip install -e ".[pg,redis,celery,alipay]"
# 安装微信支付sdk
pip install -e ".[pg,redis,celery,alipay,wechatpayv3]"
#安装火山sdk
pip install -e ".[pg,redis,celery,alipay,wechatpayv3,volc]"
# 如需微信支付
pip install -e ".[pg,redis,celery,alipay,wxpay]"
# 如需火山引擎 SDK（短信等）
pip install -e ".[pg,redis,celery,alipay,wxpay,volc]"
```
### 2. 配置环境变量
复制 `.env.example` 为 `.env`，修改以下关键配置：
复制 `.env.example` 为 `.env`，修改关键配置：
```bash
cp .env.example .env
@@ -81,13 +83,14 @@ cp .env.example .env
```ini
# ── 基础配置 ──
APP_NAME=VideoGen API
APP_VERSION=1.0.0
DEBUG=false
SECRET_KEY=改成一个随机的长字符串
SECRET_KEY=改成一个随机的长字符串（JWT 签名密钥）
# ── 数据库 ──
# ── 数据库（必须） ──
DATABASE_URL=postgresql+asyncpg://用户名:密码@localhost:5432/videogen
# ── Redis（可选，留空则禁用限流和验证码） ──
# ── Redis（可选，留空则禁用限流/验证码/Celery） ──
REDIS_URL=redis://localhost:6379/0
# ── JWT ──
@@ -101,24 +104,30 @@ SEEDANCE_API_BASE=https://ark.cn-beijing.volces.com/api/v3
SEEDANCE_CALLBACK_URL=https://你的域名/api/generation-records/callback
# ── LLM 提示词优化 ──
LLM_MOCK=false
LLM_API_BASE=https://api.openai.com/v1
LLM_API_KEY=
LLM_MODEL=gpt-4o
LLM_MOCK=true # true=使用 mock 响应，不调用真实 LLM
# ── 前后端通信加密（32字节 base64，留空则禁用） ──
ENCRYPTION_KEY=你的32字节base64密钥
# ── 存储路径 ──
# ── 存储路径（本地存储） ──
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=./storage/generate/videos
STORAGE_IMAGE_LOCAL_PATH=./storage/generate/images
STORAGE_VIDEO_COVER_LOCAL_PATH=./storage/generate/covers
UPLOAD_LOCAL_PATH=./storage/uploads
# ── 跨域（生产环境务必限制域名） ──
# ── 跨域（生产环境务必限制域名，默认 ["*"] 允许所有） ──
CORS_ORIGINS=["https://你的前台域名.com", "https://你的后台域名.com"]
# ── 回调基础地址 ──
BASE_URL=https://你的域名
# ── 验证码 ──
CAPTCHA_ENABLED=true
# ── 短信（火山引擎 SDK，SMS_MOCK=false 时生效） ──
SMS_MOCK=true
VOLC_SMS_ACCESS_KEY_ID=
@@ -129,6 +138,12 @@ VOLC_SMS_SIGN=短信签名
# ── 支付（PAYMENT_MOCK=false 时生效） ──
PAYMENT_MOCK=true
WECHAT_MCH_ID=
WECHAT_API_KEY=
ALIPAY_APP_ID=
ALIPAY_PRIVATE_KEY=
ALIPAY_PUBLIC_KEY=
ALIPAY_NOTIFY_URL=
# ── Celery（可选，留空则禁用 ChatAPI 异步流水线） ──
CELERY_BROKER_URL=redis://localhost:6379/5
@@ -138,27 +153,30 @@ CELERY_RESULT_BACKEND=redis://localhost:6379/6
FFMPEG_BIN=/usr/bin/ffmpeg
```
> **关于 ENCRYPTION_KEY 的生成:** 需要 32 字节（256 位）的 base64 编码字符串。生成方式：`openssl rand -base64 32`。前后端必须使用**完全相同**的密钥。
### 3. 初始化数据库
```bash
# 创建 PostgreSQL 数据库
psql -U postgres -c "CREATE DATABASE videogen OWNER videogen;"
# 启动后端（首次启动自动建表 + 填充种子数据）
# 启动后端（首次启动自动建表）
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```
首次启动会自动完成：
- 创建所有数据表（23 个 model）
- 创建管理员账号：`admin` / `123456`
- 创建演示用户：`demo` / `123456`（手机号 `13888888888`）
- 填充系统配置、视频引擎（Seedance 2.0 / 2.0 fast）、图片引擎（Seedream 5.0）、模型配置、积分比例、菜单配置、充值套餐（4 档）、行业配置
首次启动时会**自动创建所有数据表**（41 个 model）。
**首次部署后务必修改默认密码。**
> ⚠️ **关于种子数据:** 代码中包含 `_seed_data()` 函数（创建管理员/演示用户、系统配置、引擎配置等），但当前在 `main.py` 中被**注释掉了**（`# await _seed_data()`）。因此首次启动**不会**自动创建管理员账号。
>
> **如果你需要种子数据，**有以下选择：
> 1. 在 `main.py` 中取消注释 `# await _seed_data()` 后重启
> 2. 手动通过 API 或数据库脚本创建管理员账号
> 3. 自行编写独立的种子脚本调用 `_seed_data()`
### 4. 数据库迁移 (Alembic)
项目使用 Alembic 管理数据库结构变更，`env.py` 已导入全部 20 个 model。
项目使用 Alembic 管理数据库结构变更。
```bash
cd video-gen-api
@@ -179,17 +197,13 @@ python -m alembic history
python -m alembic downgrade -1
```
**部署流程：** 拉取代码后先执行 `alembic upgrade head`，再重启后端服务。
**新增 model 时：** 需要在 `alembic/env.py` 中添加对应的 import。
**部署流程:** 拉取代码后先执行 `alembic upgrade head`，再重启后端服务。
### 5. 生产运行
```bash
# 方式一：直接运行（推荐 4 workers）
# 直接运行（推荐 4 workers）
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
# 方式二：使用 systemd (Linux)
```
**systemd 服务文件** `/etc/systemd/system/videogen-api.service`：
@@ -220,11 +234,22 @@ sudo systemctl start videogen-api
### 6. Celery Worker（可选）
ChatAPI 异步生成流水线需要 Celery Worker。需要 Redis 作为 Broker。
ChatAPI 异步生成流水线需要 Celery Worker，依赖 Redis 作为 Broker。
Celery 使用 **6 个队列**，按功能分离：
| 队列 | 用途 |
|------|------|
| `gen_chatapi_create` | ChatAPI 生成任务创建（含爆款开头/拆镜复刻的提词步骤） |
| `gen_provider_poll` | 轮询火山引擎生成状态 |
| `gen_result_download` | 下载生成的视频/图片结果 |
| `gen_recovery` | 容灾恢复任务（统一队列，避免占用业务 worker） |
| `gen_private_portrait` | 真人素材认证与同步 |
| `default` | 默认队列（用户 OAuth、清理任务等） |
```bash
# 启动 Worker（处理 3 个队列：gen_chatapi_create, gen_provider_poll, gen_result_download）
celery -A app.tasks.celery_app worker -l info -Q gen_chatapi_create,gen_provider_poll,gen_result_download,default
# 启动 Worker（消费所有队列）
celery -A app.tasks.celery_app worker -l info -Q gen_chatapi_create,gen_provider_poll,gen_result_download,gen_recovery,gen_private_portrait,default
```
**systemd 服务文件** `/etc/systemd/system/videogen-worker.service`：
@@ -239,7 +264,7 @@ Type=simple
User=www-data
WorkingDirectory=/opt/video-gen-api
Environment=PATH=/opt/video-gen-api/.venv/bin
ExecStart=/opt/video-gen-api/.venv/bin/celery -A app.tasks.celery_app worker -l info -Q gen_chatapi_create,gen_provider_poll,gen_result_download,default
ExecStart=/opt/video-gen-api/.venv/bin/celery -A app.tasks.celery_app worker -l info -Q gen_chatapi_create,gen_provider_poll,gen_result_download,gen_recovery,gen_private_portrait,default
Restart=always
RestartSec=5
@@ -249,23 +274,25 @@ WantedBy=multi-user.target
### 7. Docker 部署（可选）
项目提供 `Dockerfile` 和 `docker-compose.yml`，一键启动完整环境：
项目提供 `Dockerfile` 和 `docker-compose.yml`。
> ⚠️ **注意:** 默认 `Dockerfile` 只安装基础依赖（`pip install .`），生产使用需改为 `".[pg,redis,celery]"`。
```bash
cd video-gen-api
# 注意：Dockerfile 默认只装基础依赖，需修改为安装 pg+redis+celery
# 将 Dockerfile 中的 RUN pip install --no-cache-dir . 改为：
# 使用前需修改 Dockerfile 第 6 行为:
# RUN pip install --no-cache-dir ".[pg,redis,celery]"
docker compose up -d
```
启动的服务：
| 服务 | 端口 | 说明 |
|------|------|------|
| api | 8000 | FastAPI 应用（带 `--reload`，开发模式） |
| worker | - | Celery Worker |
| api | 8000 | FastAPI 应用（`--reload` 开发模式） |
| worker | - | Celery Worker（消费所有队列） |
| postgres | 5432 | PostgreSQL 16 |
| redis | 6379 | Redis 7 |
@@ -276,7 +303,7 @@ server {
listen 80;
server_name api.yourdomain.com;
# 上传文件大小限制
# 上传文件大小限制（视频上传需要较大值）
client_max_body_size 100M;
location / {
@@ -300,6 +327,8 @@ server {
## 三、前台部署 (video-gen-app)
用户前台，面向最终用户。
### 1. 安装依赖 & 构建
```bash
@@ -310,8 +339,8 @@ npm install
# 配置 API 地址（创建 .env.production）
echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production
# 如需前后端加密通信
echo "VITE_ENCRYPTION_KEY=与后端ENCRYPTION_KEY相同" >> .env.production
# 如需前后端加密通信（与后端 ENCRYPTION_KEY 相同）
echo "VITE_ENCRYPTION_KEY=密钥" >> .env.production
# 构建
npm run build
@@ -319,7 +348,15 @@ npm run build
构建产物在 `dist/` 目录。
### 2. Nginx 配置
### 2. 前端环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VITE_API_BASE` | 后端 API 地址 | `http://localhost:8000` |
| `VITE_USE_MOCK` | 是否使用 mock 数据（无需后端） | `false` |
| `VITE_ENCRYPTION_KEY` | 前后端通信加密密钥（需与后端一致） | 空（不加密） |
### 3. Nginx 配置
```nginx
server {
@@ -328,12 +365,12 @@ server {
root /opt/video-gen-app/dist;
index index.html;
# SPA 路由
# SPA 路由：所有页面请求回退到 index.html
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存
# 静态资源缓存（带 hash 的文件名可长期缓存）
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
@@ -345,6 +382,8 @@ server {
## 四、后台管理部署 (video-gen-admin)
管理员后台，面向运营/管理人员。
### 1. 安装依赖 & 构建
```bash
@@ -356,13 +395,21 @@ npm install
echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production
# 如需前后端加密通信
echo "VITE_ENCRYPTION_KEY=与后端ENCRYPTION_KEY相同" >> .env.production
echo "VITE_ENCRYPTION_KEY=密钥" >> .env.production
# 构建
npm run build
```
### 2. Nginx 配置
### 2. 后台环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VITE_API_BASE` | 后端 API 地址 | `http://localhost:8000` |
| `VITE_USE_MOCK` | 是否使用 mock 数据 | `false` |
| `VITE_ENCRYPTION_KEY` | 前后端通信加密密钥 | 空（不加密） |
### 3. Nginx 配置
```nginx
server {
@@ -456,6 +503,8 @@ sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain
## 七、默认账号
> ⚠️ 默认账号仅在种子数据被执行后存在（见第三节第 3 点说明）。
| 角色 | 用户名 | 手机号 | 密码 | 积分 |
|------|--------|--------|------|------|
| 管理员 | admin | 13800000000 | 123456 | 10000 |
@@ -467,32 +516,84 @@ sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain
## 八、架构说明
### 异步任务处理
### 后端启动时的后台任务
系统有两套异步任务机制：
后端启动时（`lifespan`）会自动启动以下**进程内**后台任务：
| 机制 | 说明 | 依赖 |
|------|------|------|
| 内置 TaskQueue | asyncio 实现，运行在 uvicorn 进程内，轮询视频/图片生成状态 | 无额外依赖 |
| Celery Worker | 处理 ChatAPI 异步生成流水线，3 个队列分优先级 | Redis 作为 Broker |
| 任务 | 说明 |
|------|------|
| `task_queue` (video_queue) | 内置 asyncio 任务队列，轮询视频/图片生成状态 |
| `upload_queue` | 上传任务队列 |
| `material_consumption_queue` | 素材消耗队列 |
| `token_refresh_scheduler` | 每 5 分钟检查并刷新即将过期的 token |
| `poll_pre_test_results` | 每分钟轮询前测结果 |
| `schedule_daily_sync` | 每天 9 点自动同步素材消耗 |
| `_order_expiry_loop` | 每分钟同步待支付订单状态 + 自动过期订单 |
### 中间件栈（从外到内）
加上 **Celery Worker**（可选，处理 ChatAPI 异步流水线）。
### 中间件栈（从外到内，即请求到达的顺序）
1. `RequestLoggingMiddleware` — 请求/响应日志记录
2. `AntiCrawlerMiddleware` — 反爬虫（拦截空 UA 和常见 bot）
3. `RateLimitMiddleware` — 滑动窗口限流（Redis 支撑）
4. `RequestEncryptMiddleware` — AES-256-GCM 请求/响应加密
5. `CORSMiddleware` — 跨域
5. `CORSMiddleware` — 跨域（expose `X-Encrypted` 响应头）
### 日志系统
### 前后端通信加密
| 日志类型 | 目录 | 控制方式 |
**机制:** AES-256-GCM 对称加密，前后端共享同一个 `ENCRYPTION_KEY`。使用 Web Crypto API（前端）和 `cryptography` 库（后端）。
**生效条件:** 同时满足以下两个条件才启用加密：
- 后端 `.env` 中 `ENCRYPTION_KEY` 非空
- 前端 `.env` 中 `VITE_ENCRYPTION_KEY` 非空
- 运行在安全上下文（HTTPS 或 localhost）
**加密范围:**
| 请求类型 | 请求体 | 响应体 |
|---------|--------|--------|
| GET（无 body） | 不加密（无内容） | **加密** |
| POST/PUT/DELETE（有 body） | **加密** | **加密** |
**工作流:**
1. 前端发送 POST 请求时，将 JSON 请求体加密为 `{ data: "<密文>" }`，并加 `X-Encrypted: true` 请求头
2. 后端中间件检测到 `X-Encrypted: true` 时解密请求体，处理完后加密响应体
3. 支付回调接口（`/payments/alipay/callback`, `/payments/wechat/callback`）白名单跳过加密
> **GET 请求注意:** GET 没有请求体，但响应仍会被加密。前端会自动检测并解密。
### 文件日志加密（独立机制）
与通信加密不同，**文件日志存储**使用另一套独立的 AES-CBC-256 加密：
| 日志类型 | 目录 | 加密方式 |
|---------|------|---------|
| 请求/响应日志 | `log/RequestResponse/{日期}.log` | 始终开启 |
| AI 模型日志 | `log/AiModel/{日期}.log` | `AI_LOG_ENABLED` 环境变量 |
| Python 控制台日志 | stderr | `DEBUG=true` 时输出 INFO，否则 WARNING |
| 请求/响应日志 | `log/RequestResponse/{日期}.log` | AES-CBC-256，密钥硬编码 |
| AI 模型日志 | `log/AiModel/{日期}.log` | AES-CBC-256，密钥硬编码 |
文件日志使用 AES-CBC 加密存储，解密工具：`/internal/decrypt-data` 端点。
日志加密密钥与 `ENCRYPTION_KEY` 无关，是代码中硬编码的值。解密工具：`/internal/decrypt-data` 页面。
### 内部管理端点
| 端点 | 用途 |
|------|------|
| `/internal/` | 后端入口导航页 |
| `/internal/health` | 健康检查 (`{"status": "ok"}`) |
| `/internal/status` | 服务状态监控页 (Celery/Redis 连接状态) |
| `/internal/decrypt-data` | 日志数据解密工具（AES-CBC） |
| `/internal/api-docs` | Swagger API 文档 |
| `/internal/api-redoc` | ReDoc API 文档 |
| `/uploads/` | 用户上传的静态文件（挂载为静态目录） |
| `/api/decrypt` | 解密接口（POST，供解密工具调用） |
### 前端 Mock 模式
前端支持 Mock 数据模式，无需后端即可开发：
- 设置 `VITE_USE_MOCK=true` 时，所有 API 调用返回本地假数据
- 适用场景：纯前端开发、演示、无后端环境
- 注意：mock 模式下仍会调用部分真实 API（如站点信息、验证码）
### 存储路径
@@ -522,6 +623,15 @@ sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain
│ ├── .env # 环境变量
│ ├── .venv/ # Python 虚拟环境
│ ├── app/ # 应用代码
│ │ ├── api/ # API 路由
│ │ │ ├── v1/ # v1 版本接口（前端用户端 + 部分管理接口）
│ │ │ └── admin/ # 管理端接口
│ │ ├── middleware/ # 中间件
│ │ ├── models/ # 数据模型 (41 个)
│ │ ├── services/ # 业务服务
│ │ ├── tasks/ # Celery 任务
│ │ ├── enums/ # 枚举定义
│ │ └── utils/ # 工具函数
│ ├── alembic/ # 数据库迁移文件
│ ├── storage/
│ │ ├── generate/
@@ -565,4 +675,69 @@ cd /opt/video-gen-api && python -m alembic upgrade head
# 生成迁移文件
cd /opt/video-gen-api && python -m alembic revision --autogenerate -m "描述"
# 查看 Celery 活动任务
celery -A app.tasks.celery_app inspect active
```
---
## 十一、环境变量完整参考
### 后端 (video-gen-api/.env)
| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `SECRET_KEY` | **是** | `change-me` | JWT 签名密钥 |
| `DATABASE_URL` | **是** | sqlite | PostgreSQL 连接串 |
| `REDIS_URL` | 否 | 空 | Redis 连接串，留空禁用限流/验证码 |
| `JWT_EXPIRE_MINUTES` | 否 | 1440 | Token 有效期（分钟） |
| `JWT_EXPIRE_REMEMBER_MINUTES` | 否 | 10080 | 记住登录 Token 有效期 |
| `SEEDANCE_API_KEY` | **是** | 空 | 火山引擎 API Key |
| `SEEDANCE_API_BASE` | 否 | 火山地址 | API 基础 URL |
| `SEEDANCE_CALLBACK_URL` | 否 | 空 | 生成结果回调 URL |
| `LLM_API_BASE` | 否 | OpenAI | LLM API 地址 |
| `LLM_API_KEY` | 否 | 空 | LLM API Key |
| `LLM_MODEL` | 否 | gpt-4o | LLM 模型名称 |
| `LLM_MOCK` | 否 | true | 是否 mock LLM 响应 |
| `ENCRYPTION_KEY` | 否 | 占位符 | 前后端通信加密密钥 |
| `SMS_MOCK` | 否 | true | 是否 mock 短信 |
| `PAYMENT_MOCK` | 否 | false | 是否 mock 支付 |
| `CORS_ORIGINS` | 否 | `["*"]` | 允许的跨域来源 |
| `BASE_URL` | 否 | 测试地址 | 站点基础 URL，用于回调拼接 |
| `STORAGE_TYPE` | 否 | local | 存储类型 |
| `UPLOAD_LOCAL_PATH` | 否 | `./storage/uploads` | 上传文件存储路径 |
| `FFMPEG_BIN` | 否 | 空 | FFmpeg 路径（留空自动查找） |
| `CAPTCHA_ENABLED` | 否 | true | 是否启用验证码 |
| `CELERY_BROKER_URL` | 否 | 空 | Celery Broker（留空禁用 Celery） |
| `CELERY_RESULT_BACKEND` | 否 | 空 | Celery 结果后端 |
| `RATE_LIMIT_ENABLED` | 否 | true | 是否启用限流 |
### 前台 (video-gen-app/.env.production)
| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `VITE_API_BASE` | **是** | localhost:8000 | 后端 API 地址 |
| `VITE_USE_MOCK` | 否 | false | 是否使用 mock 数据 |
| `VITE_ENCRYPTION_KEY` | 否 | 空 | 通信加密密钥（与后端一致） |
### 后台管理 (video-gen-admin/.env.production)
同前台。
---
## 十二、故障排查
| 现象 | 可能原因 | 解决方案 |
|------|---------|---------|
| 前端登录后 401 | Token 过期或 SECRET_KEY 不一致 | 检查后端 `SECRET_KEY` 是否变更 |
| 上传文件失败 413 | Nginx 上传大小限制 | 增大 `client_max_body_size` |
| 加密请求报错"解密失败" | 前后端密钥不一致 | 确保 `VITE_ENCRYPTION_KEY` = 后端 `ENCRYPTION_KEY` |
| 非 HTTPS 环境加密无效 | Web Crypto API 需要安全上下文 | 本地开发用 localhost，生产用 HTTPS |
| Celery 任务不执行 | Redis 未启动或地址错误 | 检查 `CELERY_BROKER_URL` 和 Redis |
| 限流不生效 | Redis 未配置 | 检查 `REDIS_URL` |
| 短信发送失败 | 火山配置缺失或 `SMS_MOCK=true` | 填入 `VOLC_SMS_*` 变量并设 `SMS_MOCK=false` |
| 视频封面无法生成 | FFmpeg 未安装 | 安装 FFmpeg 或设置 `FFMPEG_BIN` |
| HTTPS 请求支付宝/火山失败 | 缺少 CA 证书 | 安装 `ca-certificates` |
| 数据库迁移失败 | Model 定义与迁移不一致 | 重新生成迁移文件后执行 |