271 lines
10 KiB
Markdown
271 lines
10 KiB
Markdown
# ViGent2 后端开发指南
|
||
|
||
本文档提供后端架构概览与接口规范。开发规范与分层约定见 `Docs/BACKEND_DEV.md`。
|
||
|
||
---
|
||
|
||
## 🏗️ 架构概览
|
||
|
||
后端采用 **FastAPI** 框架，基于 Python 3.10+ 构建，主要负责业务逻辑处理、AI 任务调度以及与各微服务组件的交互。
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
backend/
|
||
├── app/
|
||
│ ├── core/ # 核心配置 (config.py, security.py, response.py)
|
||
│ ├── modules/ # 业务模块 (router/service/workflow/schemas)
|
||
│ │ ├── videos/ # 视频生成任务（router/schemas/service/workflow）
|
||
│ │ ├── materials/ # 素材管理（router/schemas/service）
|
||
│ │ ├── publish/ # 多平台发布
|
||
│ │ ├── auth/ # 认证与会话
|
||
│ │ ├── ai/ # AI 功能（标题标签生成、多语言翻译）
|
||
│ │ ├── assets/ # 静态资源（字体/样式/BGM）
|
||
│ │ ├── ref_audios/ # 声音克隆参考音频（router/schemas/service）
|
||
│ │ ├── generated_audios/ # 预生成配音管理（router/schemas/service）
|
||
│ │ ├── login_helper/ # 扫码登录辅助
|
||
│ │ ├── tools/ # 工具接口（router/schemas/service）
|
||
│ │ ├── payment/ # 支付宝付费开通（router/schemas/service）
|
||
│ │ └── admin/ # 管理员功能
|
||
│ ├── repositories/ # Supabase 数据访问
|
||
│ ├── services/ # 外部服务集成 (TTS/Remotion/Storage/Uploader 等)
|
||
│ └── tests/ # 单元测试与集成测试
|
||
├── scripts/ # 运维脚本 (watchdog.py, init_db.py)
|
||
├── assets/ # 资源库 (fonts, bgm, styles)
|
||
├── user_data/ # 用户隔离数据 (Cookie 等)
|
||
└── requirements.txt # 依赖清单
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API 接口规范
|
||
|
||
后端服务默认运行在 `8006` 端口。
|
||
|
||
- **文档地址**: `http://localhost:8006/docs` (Swagger UI)
|
||
- **认证方式**: HttpOnly Cookie (JWT)
|
||
|
||
### 核心模块
|
||
|
||
1. **认证 (Auth)**
|
||
* `POST /api/auth/login`: 用户登录 (手机号)
|
||
* `POST /api/auth/register`: 用户注册
|
||
* `GET /api/auth/me`: 获取当前用户信息
|
||
|
||
> 授权有效期策略：在登录与受保护接口鉴权时，后端会检查 `users.expires_at`。账号到期会自动停用 (`is_active=false`) 并清理 session，返回 `403: 会员已到期，请续费`。
|
||
|
||
2. **视频生成 (Videos)**
|
||
* `POST /api/videos/generate`: 提交生成任务
|
||
* `GET /api/videos/tasks/{task_id}`: 查询单个任务状态
|
||
* `GET /api/videos/tasks`: 获取用户所有任务列表
|
||
* `GET /api/videos/generated`: 获取历史视频列表
|
||
* `DELETE /api/videos/generated/{video_id}`: 删除历史视频
|
||
|
||
3. **素材管理 (Materials)**
|
||
* `POST /api/materials`: 上传素材
|
||
* `GET /api/materials`: 获取素材列表
|
||
* `PUT /api/materials/{material_id}`: 重命名素材
|
||
|
||
4. **社交发布 (Publish)**
|
||
* `POST /api/publish`: 发布视频到 抖音/微信视频号/B站/小红书
|
||
* `POST /api/publish/login`: 扫码登录平台
|
||
* `GET /api/publish/login/status`: 查询登录状态（含刷脸验证二维码）
|
||
* `GET /api/publish/accounts`: 获取已登录账号列表
|
||
|
||
> 提示：视频号/抖音发布建议使用 headful + xvfb-run 运行后端。
|
||
|
||
5. **资源库 (Assets)**
|
||
* `GET /api/assets/subtitle-styles`: 字幕样式列表
|
||
* `GET /api/assets/title-styles`: 标题样式列表
|
||
* `GET /api/assets/bgm`: 背景音乐列表
|
||
|
||
6. **声音克隆 (Ref Audios)**
|
||
* `POST /api/ref-audios`: 上传参考音频 (multipart/form-data，自动 Whisper 转写 ref_text)
|
||
* `GET /api/ref-audios`: 获取参考音频列表
|
||
* `PUT /api/ref-audios/{id}`: 重命名参考音频
|
||
* `DELETE /api/ref-audios/{id}`: 删除参考音频
|
||
* `POST /api/ref-audios/{id}/retranscribe`: 重新识别参考音频文字（Whisper 转写 + 超 10s 自动截取）
|
||
|
||
7. **AI 功能 (AI)**
|
||
* `POST /api/ai/generate-meta`: AI 生成标题和标签
|
||
* `POST /api/ai/translate`: AI 多语言翻译（支持 9 种目标语言）
|
||
|
||
8. **预生成配音 (Generated Audios)**
|
||
* `POST /api/generated-audios/generate`: 异步生成配音（返回 task_id）
|
||
* `GET /api/generated-audios/tasks/{task_id}`: 轮询生成进度
|
||
* `GET /api/generated-audios`: 列出用户所有配音
|
||
* `DELETE /api/generated-audios/{audio_id}`: 删除配音
|
||
* `PUT /api/generated-audios/{audio_id}`: 重命名配音
|
||
|
||
9. **工具 (Tools)**
|
||
* `POST /api/tools/extract-script`: 从视频链接提取文案
|
||
|
||
10. **健康检查**
|
||
* `GET /api/lipsync/health`: 唇形同步服务健康状态（含 LatentSync + MuseTalk + 混合路由阈值）
|
||
* `GET /api/voiceclone/health`: CosyVoice 3.0 服务健康状态
|
||
|
||
11. **支付 (Payment)**
|
||
* `POST /api/payment/create-order`: 创建支付宝电脑网站支付订单（需 payment_token）
|
||
* `POST /api/payment/notify`: 支付宝异步通知回调（返回纯文本 success/fail）
|
||
* `GET /api/payment/status/{out_trade_no}`: 查询订单支付状态（前端轮询）
|
||
|
||
> 登录时若账号未激活或已过期，返回 403 + `payment_token`，前端跳转 `/pay` 页面完成付费。详见 [支付宝部署指南](ALIPAY_DEPLOY.md)。
|
||
|
||
### 统一响应结构
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "ok",
|
||
"data": { },
|
||
"code": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎛️ 视频生成扩展参数
|
||
|
||
`POST /api/videos/generate` 支持以下可选字段：
|
||
|
||
- `material_path`: 视频素材路径（单素材模式）
|
||
- `material_paths`: 多素材路径数组（多机位模式，≥2 个素材时按句子自动切换）
|
||
- `tts_mode`: TTS 模式 (`edgetts` / `voiceclone`)
|
||
- `voice`: EdgeTTS 音色 ID（edgetts 模式）
|
||
- `ref_audio_id` / `ref_text`: 参考音频 ID 与文本（voiceclone 模式）
|
||
- `generated_audio_id`: 预生成配音 ID（存在时跳过内联 TTS，使用已生成的配音文件）
|
||
- `speed`: 语速（声音克隆模式，默认 1.0，范围 0.8-1.2）
|
||
- `custom_assignments`: 自定义素材分配数组（每项含 `material_path` / `start` / `end` / `source_start` / `source_end?`），存在时优先按时间轴可见段生成
|
||
- `output_aspect_ratio`: 输出画面比例（`9:16` 或 `16:9`，默认 `9:16`）
|
||
- `language`: TTS 语言（默认自动检测，声音克隆时透传给 CosyVoice 3.0）
|
||
- `title`: 片头标题文字
|
||
- `title_display_mode`: 标题显示模式（`short` / `persistent`，默认 `short`）
|
||
- `title_duration`: 标题显示时长（秒，默认 `4.0`；`short` 模式生效）
|
||
- `subtitle_style_id`: 字幕样式 ID
|
||
- `title_style_id`: 标题样式 ID
|
||
- `subtitle_font_size`: 字幕字号（覆盖样式默认值）
|
||
- `title_font_size`: 标题字号（覆盖样式默认值）
|
||
- `title_top_margin`: 标题距顶部像素
|
||
- `secondary_title`: 片头副标题文字（可选，限 20 字，仅视频画面显示）
|
||
- `secondary_title_style_id`: 副标题样式 ID
|
||
- `secondary_title_font_size`: 副标题字号
|
||
- `secondary_title_top_margin`: 副标题距主标题间距
|
||
- `subtitle_bottom_margin`: 字幕距底部像素
|
||
- `enable_subtitles`: 是否启用字幕
|
||
- `bgm_id`: 背景音乐 ID
|
||
- `bgm_volume`: 背景音乐音量（0-1，默认 0.2）
|
||
|
||
### 多素材稳定性说明
|
||
|
||
- 多素材片段在拼接前统一重编码，并强制 `25fps + CFR`，减少段边界时间基不一致导致的画面卡顿。
|
||
- concat 流程启用 `+genpts` 重建时间戳，提升拼接后时间轴连续性。
|
||
- 对带旋转元数据的 MOV 素材会先做方向归一化，再进入分辨率判断和后续流程。
|
||
|
||
## 📦 资源库与静态资源
|
||
|
||
- 本地资源目录：`backend/assets/{fonts,bgm,styles}`
|
||
- 静态访问路径：`/assets`（用于前端样式预览与背景音乐试听）
|
||
|
||
## 🎵 背景音乐混音策略
|
||
|
||
- 混音发生在 **唇形对齐之后**，避免影响字幕/口型时间轴。
|
||
- 使用 FFmpeg `amix`，禁用归一化以保持配音音量稳定。
|
||
|
||
## 🛠️ 开发环境搭建
|
||
|
||
### 1. 虚拟环境
|
||
|
||
```bash
|
||
cd backend
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/macOS
|
||
# .\venv\Scripts\activate # Windows
|
||
```
|
||
|
||
### 2. 依赖安装
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 环境变量配置
|
||
|
||
复制 `.env.example` 到 `.env` 并配置必要的 Key：
|
||
|
||
```ini
|
||
# Supabase
|
||
SUPABASE_URL=http://localhost:8008
|
||
SUPABASE_KEY=your_service_role_key
|
||
|
||
# GLM API (用于 AI 标题生成)
|
||
GLM_API_KEY=your_glm_api_key
|
||
|
||
# LatentSync 配置
|
||
LATENTSYNC_GPU_ID=1
|
||
|
||
# MuseTalk 配置 (长视频唇形同步)
|
||
MUSETALK_GPU_ID=0
|
||
MUSETALK_API_URL=http://localhost:8011
|
||
MUSETALK_BATCH_SIZE=32
|
||
LIPSYNC_DURATION_THRESHOLD=120
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
**开发模式 (热重载)**:
|
||
```bash
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🧩 服务集成指南
|
||
|
||
### 集成新模型
|
||
|
||
如果需要集成新的 AI 模型 (例如新的 TTS 引擎)：
|
||
|
||
1. 在 `app/services/` 下创建新的 Service 类 (如 `NewTTSService`)。
|
||
2. 实现 `generate` 方法，可以使用 subprocess 调用，也可以是 HTTP 请求。
|
||
3. **重要**: 如果模型占用 GPU，请务必使用 `asyncio.Lock` 进行并发控制，防止 OOM。
|
||
4. 在 `app/modules/` 下创建对应模块，添加 router/service/schemas，并在 `main.py` 注册路由。
|
||
|
||
### 唇形同步混合路由
|
||
|
||
`lipsync_service.py` 实现了 LatentSync + MuseTalk 混合路由：
|
||
- 短视频 (<`LIPSYNC_DURATION_THRESHOLD`s) → LatentSync 1.6 (GPU1, 端口 8007)
|
||
- 长视频 (>=阈值) → MuseTalk 1.5 (GPU0, 端口 8011)
|
||
- MuseTalk 不可用时自动回退到 LatentSync
|
||
- 路由逻辑对 workflow 完全透明
|
||
|
||
### 添加定时任务
|
||
|
||
目前推荐使用 **APScheduler** 或 **Crontab** 来管理定时任务。
|
||
社交媒体的定时发布功能目前依赖 `playwright` 的延迟执行，未来计划迁移到 Celery 队列。
|
||
|
||
---
|
||
|
||
## 🛡️ 错误处理
|
||
|
||
全项目统一使用 `Loguru` 进行日志记录。
|
||
|
||
```python
|
||
from loguru import logger
|
||
|
||
try:
|
||
# 业务逻辑
|
||
except Exception as e:
|
||
logger.error(f"操作失败: {str(e)}")
|
||
raise HTTPException(status_code=500, detail="服务器内部错误")
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
运行测试套件：
|
||
|
||
```bash
|
||
pytest
|
||
```
|