# ViGent2 后端开发指南 本文档提供后端架构概览、接口说明与运行配置。 ## 📌 文档定位 - 本文档用于说明后端服务能力、接口与部署运行方式（面向使用与联调）。 - 开发规范、分层约束与代码实现习惯请查看 `Docs/BACKEND_DEV.md`。 - 历史变更与里程碑请查看 `Docs/DevLogs/` 与 `Docs/TASK_COMPLETE.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 # 依赖清单 ``` > 详细分层职责（router/service/workflow/repositories）与开发约束请查看 `Docs/BACKEND_DEV.md`。 --- ## 🔌 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/POST /api/videos/voice-preview`: 生成音色试听短音频（返回二进制音频流） * `POST /api/videos/cleanup`: 清理当前用户工作区生成产物（outputs + generated-audios） * `GET /api/videos/tasks/{task_id}`: 查询单个任务状态 * `GET /api/videos/tasks`: 获取用户所有任务列表 * `GET /api/videos/generated`: 获取历史视频列表 * `GET /api/videos/generated/{video_id}/download`: 下载历史视频（`Content-Disposition: attachment`） * `DELETE /api/videos/generated/{video_id}`: 删除历史视频 > `POST /api/videos/cleanup` 采用严格成功语义：仅当目标文件删除全部成功时返回 success；存在删除失败会返回错误并提示重试。 3. **素材管理 (Materials)** * `POST /api/materials`: 上传素材 * `GET /api/materials`: 获取素材列表 * `PUT /api/materials/{material_id}`: 重命名素材 * `GET /api/materials/stream/{material_id}`: 同源流式返回素材文件（用于前端 canvas 截帧，避免跨域 CORS taint；服务端会拒绝 `..` 路径） 4. **社交发布 (Publish)** * `POST /api/publish`: 发布视频到 抖音/微信视频号/B站/小红书 * `POST /api/publish/login/{platform}`: 获取平台二维码并启动扫码登录 * `GET /api/publish/login/status/{platform}`: 轮询登录状态（含抖音刷脸验证二维码） * `POST /api/publish/logout/{platform}`: 注销平台登录（删除 Cookie） * `POST /api/publish/cookies/save/{platform}`: 保存客户端提取的 Cookie * `GET /api/publish/accounts`: 获取已登录账号列表 * `GET /api/publish/screenshot/{filename}`: 获取发布成功截图（需登录） > 提示：视频号/抖音发布建议使用 headful + xvfb-run 运行后端。发布专项实现与部署说明见 `Docs/PUBLISH_DEPLOY.md`。 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 种目标语言，需登录） * `POST /api/ai/rewrite`: AI 改写文案（需登录） 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/videos/lipsync/health`: 唇形同步服务健康状态（含 LatentSync + MuseTalk + 混合路由阈值） * `GET /api/videos/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)。 ### 安全基线（生产环境） - `DEBUG` 必须设为 `false`：认证 Cookie 会带 `Secure`，仅在 HTTPS 下发送。 - `JWT_SECRET_KEY` 必须是强随机值且不能使用默认值；当 `DEBUG=false` 且仍为默认值时，后端会在启动阶段直接拒绝启动。 - 上传体积限制： - `POST /api/materials`：受 `MAX_UPLOAD_SIZE_MB` 限制（默认 500MB） - `POST /api/ref-audios`：5MB - `POST /api/tools/extract-script`：文件上传与 URL 下载结果均限制 500MB - `video_id` 在下载/删除接口使用白名单校验（`^[A-Za-z0-9_-]+$`），非法值直接返回 400。 ### 统一响应结构 ```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`） - `lipsync_model`: 唇形模型路由模式（`default` / `fast` / `advanced`） - `default`: 阈值路由（`LIPSYNC_DURATION_THRESHOLD`） - `fast`: 强制 MuseTalk，不可用时回退 LatentSync - `advanced`: 强制 LatentSync - `language`: TTS 语言区域（默认 `zh-CN`；会映射为 Whisper 的 `zh/en/...` 与 CosyVoice 的 `Chinese/English/Auto`） - `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 素材会先做方向归一化，再进入分辨率判断和后续流程。 - compose 阶段（视频轨+音频轨合并）在**无需循环视频**时使用 `-c:v copy` 流复制；需要循环时才重编码。 - FFmpeg 子进程设有超时保护：`_run_ffmpeg()` 600 秒、`_get_duration()` 30 秒，防止畸形文件导致永久挂起。 ### 全局并发控制 - 视频生成入口使用 `asyncio.Semaphore(2)` 限制最多 2 个任务同时执行，排队中的任务显示"排队中..."状态。 - Redis 任务 key 设有 TTL：创建时 24 小时，completed/failed 状态 2 小时，`list()` 时自动清理过期索引。 ### 字幕时间戳优化 - Whisper 输出经 `smooth_word_timestamps()` 三步平滑：单调递增保证、重叠消除（中点分割）、微小间隙填补（<50ms）。 - 支持 `original_text` 原文节奏映射：原文字符按比例映射到 Whisper 时间戳上，解决 AI 改写/多语言文案与转录不一致问题。 ## 📦 资源库与静态资源 - 本地资源目录：`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. 环境变量配置 当前仓库使用 `backend/.env` 作为运行配置基准；请按你的环境替换敏感值并核对以下关键项（生产环境请勿提交真实密钥）： ```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=100 # MuseTalk 可调参数（示例） MUSETALK_DETECT_EVERY=2 MUSETALK_BLEND_CACHE_EVERY=2 MUSETALK_ENCODE_CRF=14 MUSETALK_ENCODE_PRESET=slow ``` ### 4. 启动服务 **开发模式 (热重载)**: ```bash uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload ``` --- ## 🧩 开发约定与测试 - 新增模块、分层职责、统一响应、错误处理与调试规范请查看 `Docs/BACKEND_DEV.md`。 - 建议在核心流程变更后做基础冒烟：登录、视频生成、发布。 - 测试命令： ```bash pytest ```