Originals/ViGent2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 51 Wiki Activity
Files
71b45852bf85ed121c4cb4faee7abe03e50f6308
ViGent2/Docs/BACKEND_README.md
Kevin Wong 71b45852bf 更新
2026-03-04 17:35:59 +08:00

12 KiB
Raw Blame History

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: 会员已到期，请续费。

  1. 视频生成 (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；存在删除失败会返回错误并提示重试。

  1. 素材管理 (Materials)

    • POST /api/materials: 上传素材
    • GET /api/materials: 获取素材列表
    • PUT /api/materials/{material_id}: 重命名素材
    • GET /api/materials/stream/{material_id}: 同源流式返回素材文件（用于前端 canvas 截帧，避免跨域 CORS taint；服务端会拒绝 .. 路径）

  2. 社交发布 (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。

  1. 资源库 (Assets)

    • GET /api/assets/subtitle-styles: 字幕样式列表
    • GET /api/assets/title-styles: 标题样式列表
    • GET /api/assets/bgm: 背景音乐列表

  2. 声音克隆 (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 自动截取）

  3. AI 功能 (AI)

    • POST /api/ai/generate-meta: AI 生成标题和标签（需登录）
    • POST /api/ai/translate: AI 多语言翻译（支持 9 种目标语言，需登录）
    • POST /api/ai/rewrite: AI 改写文案（需登录）

  4. 预生成配音 (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}: 重命名配音

  5. 工具 (Tools)

    • POST /api/tools/extract-script: 从视频链接提取文案（需登录）

  6. 健康检查

    • GET /api/videos/lipsync/health: 唇形同步服务健康状态（含 LatentSync + MuseTalk + 混合路由阈值）
    • GET /api/videos/voiceclone/health: CosyVoice 3.0 服务健康状态

  7. 支付 (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 页面完成付费。详见 支付宝部署指南。

安全基线（生产环境）

  • 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。

统一响应结构

{
  "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. 虚拟环境

cd backend
python -m venv venv
source venv/bin/activate  # Linux/macOS
# .\venv\Scripts\activate # Windows

2. 依赖安装

pip install -r requirements.txt

3. 环境变量配置

当前仓库使用 backend/.env 作为运行配置基准；请按你的环境替换敏感值并核对以下关键项（生产环境请勿提交真实密钥）：

# 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. 启动服务

开发模式 (热重载):

uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload

🧩 开发约定与测试

  • 新增模块、分层职责、统一响应、错误处理与调试规范请查看 Docs/BACKEND_DEV.md。
  • 建议在核心流程变更后做基础冒烟：登录、视频生成、发布。
  • 测试命令：
pytest
Reference in New Issue View Git Blame Copy Permalink