1

DEPLOYMENT.md

@@ -4,20 +4,23 @@
 
 ```
 video_item/
-├── video-gen-api/          # 后端 (Python FastAPI)
-├── video-gen-app/          # 前台 (React + Vite)
-├── video-gen-admin/        # 后台管理 (React + Vite)
+├── 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)
 └── DEPLOYMENT.md           # 本文档
 ```
 
+---
+
 ## 一、环境要求
 
-| 组件 | 版本要求 |
-|------|---------|
-| Python | >= 3.10 |
-| Node.js | >= 18 |
-| PostgreSQL | >= 14 |
-| Redis | >= 6 (可选) |
+| 组件 | 版本要求 | 说明 |
+|------|---------|------|
+| Python | >= 3.10 | 推荐 3.12 |
+| Node.js | >= 18 | 推荐 20+ |
+| PostgreSQL | >= 14 | 推荐 16 |
+| Redis | >= 6 | 可选，推荐用于限流/验证码/Celery |
+| FFmpeg | 任意 | 可选，用于视频封面截帧 |
 
 ---
 
@@ -35,10 +38,14 @@ python -m venv .venv
 # Linux/Mac
 source .venv/bin/activate
 
-# 安装依赖 (生产环境带 PostgreSQL 支持)
+# 安装基础依赖 + PostgreSQL 驱动
 pip install -e ".[pg]"
-# 如需 Redis 支持
+
+# 如需 Redis 支持（限流、验证码、Celery）
 pip install -e ".[pg,redis]"
+
+# 如需 Celery 异步任务（ChatAPI 生成流水线）
+pip install -e ".[pg,redis,celery]"
 ```
 
 ### 2. 配置环境变量
@@ -50,38 +57,63 @@ cp .env.example .env
 ```
 
 ```ini
-# App
+# ── 基础配置 ──
 APP_NAME=VideoGen API
 DEBUG=false
 SECRET_KEY=改成一个随机的长字符串
 
-# Database - PostgreSQL
+# ── 数据库 ──
 DATABASE_URL=postgresql+asyncpg://用户名:密码@localhost:5432/videogen
 
-# Redis (可选，不填则禁用)
+# ── Redis（可选，留空则禁用限流和验证码） ──
 REDIS_URL=redis://localhost:6379/0
 
-# JWT
+# ── JWT ──
 JWT_ALGORITHM=HS256
-JWT_EXPIRE_MINUTES=1440
+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 提示词优化 (通过后台模型配置管理，此处为 fallback)
+# ── LLM 提示词优化 ──
 LLM_MOCK=false
 
-# 加密 (32字节 base64)
+# ── 前后端通信加密（32字节 base64，留空则禁用） ──
 ENCRYPTION_KEY=你的32字节base64密钥
 
-# 存储
+# ── 存储路径 ──
 STORAGE_TYPE=local
-STORAGE_LOCAL_PATH=./storage/videos
+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://你的域名
+
+# ── 短信（火山引擎 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
+
+# ── Celery（可选，留空则禁用 ChatAPI 异步流水线） ──
+CELERY_BROKER_URL=redis://localhost:6379/5
+CELERY_RESULT_BACKEND=redis://localhost:6379/6
+
+# ── FFmpeg（留空自动从 PATH 查找） ──
+FFMPEG_BIN=/usr/bin/ffmpeg
 ```
 
 ### 3. 初始化数据库
@@ -90,20 +122,21 @@ CORS_ORIGINS=["https://你的前台域名.com", "https://你的后台域名.com"
 # 创建 PostgreSQL 数据库
 psql -U postgres -c "CREATE DATABASE videogen OWNER videogen;"
 
-# 启动后端，自动建表和种子数据
+# 启动后端（首次启动自动建表 + 填充种子数据）
 python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
 ```
 
-首次启动会自动：
-- 创建所有数据表
-- 创建管理员账号: `admin` / `admin123`
-- 创建演示用户: `demo` / `demo123`
-- 填充系统配置、菜单、充值套餐等初始数据
-- 行业需要在后台手动添加
+首次启动会自动完成：
+- 创建所有数据表（23 个 model）
+- 创建管理员账号：`admin` / `123456`
+- 创建演示用户：`demo` / `123456`（手机号 `13888888888`）
+- 填充系统配置、视频引擎（Seedance 2.0 / 2.0 fast）、图片引擎（Seedream 5.0）、模型配置、积分比例、菜单配置、充值套餐（4 档）、行业配置
+
+**首次部署后务必修改默认密码。**
 
 ### 4. 数据库迁移 (Alembic)
 
-项目使用 Alembic 管理数据库结构变更。
+项目使用 Alembic 管理数据库结构变更，`env.py` 已导入全部 20 个 model。
 
 ```bash
 cd video-gen-api
@@ -119,6 +152,9 @@ python -m alembic current
 
 # 查看迁移历史
 python -m alembic history
+
+# 回滚一步
+python -m alembic downgrade -1
 ```
 
 **部署流程：** 拉取代码后先执行 `alembic upgrade head`，再重启后端服务。
@@ -128,13 +164,13 @@ python -m alembic history
 ### 5. 生产运行
 
 ```bash
-# 方式一：直接运行
+# 方式一：直接运行（推荐 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`:
+**systemd 服务文件** `/etc/systemd/system/videogen-api.service`：
 
 ```ini
 [Unit]
@@ -160,7 +196,58 @@ sudo systemctl enable videogen-api
 sudo systemctl start videogen-api
 ```
 
-### 6. Nginx 反向代理
+### 6. Celery Worker（可选）
+
+ChatAPI 异步生成流水线需要 Celery Worker。需要 Redis 作为 Broker。
+
+```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
+```
+
+**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,default
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 7. Docker 部署（可选）
+
+项目提供 `Dockerfile` 和 `docker-compose.yml`，一键启动完整环境：
+
+```bash
+cd video-gen-api
+
+# 注意：Dockerfile 默认只装基础依赖，需修改为安装 pg+redis+celery
+# 将 Dockerfile 中的 RUN pip install --no-cache-dir . 改为：
+# 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 {
@@ -181,7 +268,7 @@ server {
 
     # 静态文件 (上传的视频/图片)
     location /uploads/ {
-        alias /opt/video-gen-api/uploads/;
+        alias /opt/video-gen-api/storage/uploads/;
         expires 7d;
     }
 }
@@ -198,10 +285,12 @@ cd video-gen-app
 
 npm install
 
-# 配置 API 地址
-# 创建 .env.production
+# 配置 API 地址（创建 .env.production）
 echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production
 
+# 如需前后端加密通信
+echo "VITE_ENCRYPTION_KEY=与后端ENCRYPTION_KEY相同" >> .env.production
+
 # 构建
 npm run build
 ```
@@ -244,6 +333,9 @@ npm install
 # 配置 API 地址
 echo "VITE_API_BASE=https://api.yourdomain.com" > .env.production
 
+# 如需前后端加密通信
+echo "VITE_ENCRYPTION_KEY=与后端ENCRYPTION_KEY相同" >> .env.production
+
 # 构建
 npm run build
 ```
@@ -289,7 +381,7 @@ server {
     }
 
     location /uploads/ {
-        alias /opt/video-gen-api/uploads/;
+        alias /opt/video-gen-api/storage/uploads/;
         expires 7d;
     }
 }
@@ -344,14 +436,63 @@ sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain
 
 | 角色 | 用户名 | 手机号 | 密码 | 积分 |
 |------|--------|--------|------|------|
-| 管理员 | admin | 13800000000 | admin123 | 10000 |
-| 演示用户 | demo | 13800000001 | demo123 | 2680 |
+| 管理员 | admin | 13800000000 | 123456 | 10000 |
+| 演示用户 | demo | 13888888888 | 123456 | 2680 |
 
 **首次部署后务必修改默认密码。**
 
 ---
 
-## 八、目录结构 (部署后)
+## 八、架构说明
+
+### 异步任务处理
+
+系统有两套异步任务机制：
+
+| 机制 | 说明 | 依赖 |
+|------|------|------|
+| 内置 TaskQueue | asyncio 实现，运行在 uvicorn 进程内，轮询视频/图片生成状态 | 无额外依赖 |
+| Celery Worker | 处理 ChatAPI 异步生成流水线，3 个队列分优先级 | Redis 作为 Broker |
+
+### 中间件栈（从外到内）
+
+1. `RequestLoggingMiddleware` — 请求/响应日志记录
+2. `AntiCrawlerMiddleware` — 反爬虫（拦截空 UA 和常见 bot）
+3. `RateLimitMiddleware` — 滑动窗口限流（Redis 支撑）
+4. `RequestEncryptMiddleware` — AES-256-GCM 请求/响应加密
+5. `CORSMiddleware` — 跨域
+
+### 日志系统
+
+| 日志类型 | 目录 | 控制方式 |
+|---------|------|---------|
+| 请求/响应日志 | `log/RequestResponse/{日期}.log` | 始终开启 |
+| AI 模型日志 | `log/AiModel/{日期}.log` | `AI_LOG_ENABLED` 环境变量 |
+| Python 控制台日志 | stderr | `DEBUG=true` 时输出 INFO，否则 WARNING |
+
+文件日志使用 AES-CBC 加密存储，解密工具：`/internal/decrypt-data` 端点。
+
+### 存储路径
+
+| 路径 | 用途 |
+|------|------|
+| `storage/generate/videos/` | 生成的视频文件 |
+| `storage/generate/images/` | 生成的图片文件 |
+| `storage/generate/covers/` | 视频封面缩略图 |
+| `storage/uploads/` | 用户上传的原始文件 |
+
+### 外部服务依赖
+
+| 服务 | 用途 | 是否必须 |
+|------|------|---------|
+| 火山引擎 Ark | 视频生成（Seedance 2.0）、图片生成（Seedream 5.0）、LLM | 是 |
+| 火山引擎短信 | 短信验证码 | 否（可 mock） |
+| 微信支付 / 支付宝 | 充值支付 | 否（可 mock，未完整实现） |
+| FFmpeg | 视频封面截帧 | 否（留空自动查找） |
+
+---
+
+## 九、目录结构 (部署后)
 
 ```
 /opt/
@@ -359,15 +500,23 @@ sudo certbot --nginx -d yourdomain.com -d admin.yourdomain.com -d api.yourdomain
 │   ├── .env                            # 环境变量
 │   ├── .venv/                          # Python 虚拟环境
 │   ├── app/                            # 应用代码
-│   ├── uploads/                # 上传文件
-│   └── storage/videos/         # 生成的视频
+│   ├── alembic/                        # 数据库迁移文件
+│   ├── storage/
+│   │   ├── generate/
+│   │   │   ├── videos/                 # 生成的视频
+│   │   │   ├── images/                 # 生成的图片
+│   │   │   └── covers/                 # 视频封面
+│   │   └── uploads/                    # 用户上传
+│   └── log/
+│       ├── AiModel/                    # AI 模型请求日志（加密）
+│       └── RequestResponse/            # 请求响应日志（加密）
 ├── video-gen-app/dist/                 # 前台构建产物
 └── video-gen-admin/dist/               # 后台构建产物
 ```
 
 ---
 
-## 九、常用运维命令
+## 十、常用运维命令
 
 ```bash
 # 查看后端日志
@@ -376,6 +525,9 @@ 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
@@ -385,4 +537,10 @@ 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 "描述"
 ```