# VideoGen 部署文档

## 项目结构

```
video_item/
├── video-gen-api/          # 后端 (Python FastAPI + SQLAlchemy + Alembic)
├── 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` 后端。

---

## 一、环境要求

| 组件 | 版本要求 | 说明 |
|------|---------|------|
| Python | >= 3.10 | 推荐 3.12 |
| Node.js | >= 18 | 推荐 20+ |
| 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 | 可选，视频生成/短信 |

---

## 二、后端部署 (video-gen-api)

### 1. 安装依赖

```bash
# ⚠️ 新服务器/容器必须先装 CA 证书，否则 HTTPS（支付宝/火山等）全部失败
# CentOS/RHEL
sudo yum install -y ca-certificates
# Ubuntu/Debian
sudo apt-get install -y ca-certificates

cd video-gen-api

# 创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# 安装基础依赖
pip install -e .

# 安装 PostgreSQL 驱动（生产环境必须）
pip install -e ".[pg]"

# 如需 Redis 支持（限流、验证码、Celery）
pip install -e ".[pg,redis]"

# 如需 Celery 异步任务（ChatAPI 生成流水线）
pip install -e ".[pg,redis,celery]"

# 如需支付宝
pip install -e ".[pg,redis,celery,alipay]"

# 如需微信支付
pip install -e ".[pg,redis,celery,alipay,wxpay]"

# 如需火山引擎 SDK（短信等）
pip install -e ".[pg,redis,celery,alipay,wxpay,volc]"
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，修改关键配置：

```bash
cp .env.example .env
```

```ini
# ── 基础配置 ──
APP_NAME=VideoGen API
APP_VERSION=1.0.0
DEBUG=false
SECRET_KEY=改成一个随机的长字符串（JWT 签名密钥）

# ── 数据库（必须） ──
DATABASE_URL=postgresql+asyncpg://用户名:密码@localhost:5432/videogen

# ── Redis（可选，留空则禁用限流/验证码/Celery） ──
REDIS_URL=redis://localhost:6379/0

# ── JWT ──
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440          # 普通登录 24h
JWT_EXPIRE_REMEMBER_MINUTES=10080 # 记住登录 7天

# ── 视频生成（火山引擎 Ark） ──
SEEDANCE_API_KEY=你的API Key
SEEDANCE_API_BASE=https://ark.cn-beijing.volces.com/api/v3
SEEDANCE_CALLBACK_URL=https://你的域名/api/generation-records/callback

# ── LLM 提示词优化 ──
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=
VOLC_SMS_SECRET_ACCESS_KEY=
VOLC_SMS_ACCOUNT=消息组ID
VOLC_SMS_TEMPLATE_ID=模板ID
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
CELERY_RESULT_BACKEND=redis://localhost:6379/6

# ── FFmpeg（留空自动从 PATH 查找） ──
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
```

首次启动时会**自动创建所有数据表**（41 个 model）。

> ⚠️ **关于种子数据:** 代码中包含 `_seed_data()` 函数（创建管理员/演示用户、系统配置、引擎配置等），但当前在 `main.py` 中被**注释掉了**（`# await _seed_data()`）。因此首次启动**不会**自动创建管理员账号。
>
> **如果你需要种子数据，**有以下选择：
> 1. 在 `main.py` 中取消注释 `# await _seed_data()` 后重启
> 2. 手动通过 API 或数据库脚本创建管理员账号
> 3. 自行编写独立的种子脚本调用 `_seed_data()`

### 4. 数据库迁移 (Alembic)

项目使用 Alembic 管理数据库结构变更。

```bash
cd video-gen-api

# 修改 model 后，自动生成迁移文件
python -m alembic revision --autogenerate -m "描述改动内容"

# 执行迁移
python -m alembic upgrade head

# 查看当前版本
python -m alembic current

# 查看迁移历史
python -m alembic history

# 回滚一步
python -m alembic downgrade -1
```

**部署流程:** 拉取代码后先执行 `alembic upgrade head`，再重启后端服务。

### 5. 生产运行

```bash
# 直接运行（推荐 4 workers）
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

**systemd 服务文件** `/etc/systemd/system/videogen-api.service`：

```ini
[Unit]
Description=VideoGen API
After=network.target postgresql.service

[Service]
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/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable videogen-api
sudo systemctl start videogen-api
```

### 6. Celery Worker（可选）

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（消费所有队列）
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`：

```ini
[Unit]
Description=VideoGen Celery Worker
After=network.target redis.service

[Service]
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,gen_recovery,gen_private_portrait,default
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

### 7. Docker 部署（可选）

项目提供 `Dockerfile` 和 `docker-compose.yml`。

> ⚠️ **注意:** 默认 `Dockerfile` 只安装基础依赖（`pip install .`），生产使用需改为 `".[pg,redis,celery]"`。

```bash
cd video-gen-api

# 使用前需修改 Dockerfile 第 6 行为:
# RUN pip install --no-cache-dir ".[pg,redis,celery]"

docker compose up -d
```

启动的服务：

| 服务 | 端口 | 说明 |
|------|------|------|
| api | 8000 | FastAPI 应用（`--reload` 开发模式） |
| worker | - | Celery Worker（消费所有队列） |
| postgres | 5432 | PostgreSQL 16 |
| redis | 6379 | Redis 7 |

### 8. Nginx 反向代理

```nginx
server {
    listen 80;
    server_name api.yourdomain.com;

    # 上传文件大小限制（视频上传需要较大值）
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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 $scheme;
        proxy_read_timeout 300s;
    }

    # 静态文件 (上传的视频/图片)
    location /uploads/ {
        alias /opt/video-gen-api/storage/uploads/;
        expires 7d;
    }
}
```

---

## 三、前台部署 (video-gen-app)

用户前台，面向最终用户。

### 1. 安装依赖 & 构建

```bash
cd video-gen-app

npm install

# 配置 API 地址（创建 .env.production）
echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production

# 如需前后端加密通信（与后端 ENCRYPTION_KEY 相同）
echo "VITE_ENCRYPTION_KEY=密钥" >> .env.production

# 构建
npm run build
```

构建产物在 `dist/` 目录。

### 2. 前端环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VITE_API_BASE` | 后端 API 地址 | `http://localhost:8000` |
| `VITE_USE_MOCK` | 是否使用 mock 数据（无需后端） | `false` |
| `VITE_ENCRYPTION_KEY` | 前后端通信加密密钥（需与后端一致） | 空（不加密） |

### 3. Nginx 配置

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /opt/video-gen-app/dist;
    index index.html;

    # SPA 路由：所有页面请求回退到 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存（带 hash 的文件名可长期缓存）
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

---

## 四、后台管理部署 (video-gen-admin)

管理员后台，面向运营/管理人员。

### 1. 安装依赖 & 构建

```bash
cd video-gen-admin

npm install

# 配置 API 地址
echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production

# 如需前后端加密通信
echo "VITE_ENCRYPTION_KEY=密钥" >> .env.production

# 构建
npm run build
```

### 2. 后台环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VITE_API_BASE` | 后端 API 地址 | `http://localhost:8000` |
| `VITE_USE_MOCK` | 是否使用 mock 数据 | `false` |
| `VITE_ENCRYPTION_KEY` | 前后端通信加密密钥 | 空（不加密） |

### 3. Nginx 配置

```nginx
server {
    listen 80;
    server_name admin.yourdomain.com;
    root /opt/video-gen-admin/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

---

## 五、完整 Nginx 配置示例 (单机部署)

```nginx
# 后端 API
server {
    listen 80;
    server_name api.yourdomain.com;
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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 $scheme;
        proxy_read_timeout 300s;
    }

    location /uploads/ {
        alias /opt/video-gen-api/storage/uploads/;
        expires 7d;
    }
}

# 前台
server {
    listen 80;
    server_name yourdomain.com;
    root /opt/video-gen-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 1y;
    }
}

# 后台管理
server {
    listen 80;
    server_name admin.yourdomain.com;
    root /opt/video-gen-admin/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        expires 1y;
    }
}
```

---

## 六、SSL 配置 (推荐)

使用 Certbot 获取免费证书：

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain.com
```

---

## 七、默认账号

> ⚠️ 默认账号仅在种子数据被执行后存在（见第三节第 3 点说明）。

| 角色 | 用户名 | 手机号 | 密码 | 积分 |
|------|--------|--------|------|------|
| 管理员 | admin | 13800000000 | 123456 | 10000 |
| 演示用户 | demo | 13888888888 | 123456 | 2680 |

**首次部署后务必修改默认密码。**

---

## 八、架构说明

### 后端启动时的后台任务

后端启动时（`lifespan`）会自动启动以下**进程内**后台任务：

| 任务 | 说明 |
|------|------|
| `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` — 跨域（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` | AES-CBC-256，密钥硬编码 |
| AI 模型日志 | `log/AiModel/{日期}.log` | AES-CBC-256，密钥硬编码 |

日志加密密钥与 `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（如站点信息、验证码）

### 存储路径

| 路径 | 用途 |
|------|------|
| `storage/generate/videos/` | 生成的视频文件 |
| `storage/generate/images/` | 生成的图片文件 |
| `storage/generate/covers/` | 视频封面缩略图 |
| `storage/uploads/` | 用户上传的原始文件 |

### 外部服务依赖

| 服务 | 用途 | 是否必须 |
|------|------|---------|
| 火山引擎 Ark | 视频生成（Seedance 2.0）、图片生成（Seedream 5.0）、LLM | 是 |
| 火山引擎短信 | 短信验证码 | 否（可 mock） |
| 微信支付 / 支付宝 | 充值支付 | 否（可 mock，未完整实现） |
| FFmpeg | 视频封面截帧 | 否（留空自动查找） |

---

## 九、目录结构 (部署后)

```
/opt/
├── video-gen-api/                      # 后端
│   ├── .env                            # 环境变量
│   ├── .venv/                          # Python 虚拟环境
│   ├── app/                            # 应用代码
│   │   ├── api/                        # API 路由
│   │   │   ├── v1/                     # v1 版本接口（前端用户端 + 部分管理接口）
│   │   │   └── admin/                  # 管理端接口
│   │   ├── middleware/                 # 中间件
│   │   ├── models/                     # 数据模型 (41 个)
│   │   ├── services/                   # 业务服务
│   │   ├── tasks/                      # Celery 任务
│   │   ├── enums/                      # 枚举定义
│   │   └── utils/                      # 工具函数
│   ├── alembic/                        # 数据库迁移文件
│   ├── storage/
│   │   ├── generate/
│   │   │   ├── videos/                 # 生成的视频
│   │   │   ├── images/                 # 生成的图片
│   │   │   └── covers/                 # 视频封面
│   │   └── uploads/                    # 用户上传
│   └── log/
│       ├── AiModel/                    # AI 模型请求日志（加密）
│       └── RequestResponse/            # 请求响应日志（加密）
├── video-gen-app/dist/                 # 前台构建产物
└── video-gen-admin/dist/               # 后台构建产物
```

---

## 十、常用运维命令

```bash
# 查看后端日志
sudo journalctl -u videogen-api -f

# 重启后端
sudo systemctl restart videogen-api

# 重启 Celery Worker
sudo systemctl restart videogen-worker

# 重新构建前端
cd /opt/video-gen-app && npm run build
cd /opt/video-gen-admin && npm run build

# 数据库备份
pg_dump -U videogen videogen > backup_$(date +%Y%m%d).sql

# 数据库恢复
psql -U videogen videogen < backup_20260512.sql

# 执行数据库迁移
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 定义与迁移不一致 | 重新生成迁移文件后执行 |