ViGent2/Docs/DevLogs/Day1.md

Day 1 - ViGent 数字人口播系统开发

日期：2026-01-13
开发环境：Windows 11 (本地开发) / Ubuntu 24.04 (服务器部署)
目标平台：Dell PowerEdge R730 (2× RTX 3090 24GB)

---

🎯 今日目标

搭建数字人口播视频生成系统的完整框架，包括：

1. 后端 API (FastAPI)
2. 前端 UI (Next.js)
3. 视频生成流程 (TTS + FFmpeg)
4. 社交媒体发布功能

---

📦 项目初始化

后端项目结构

backend/
├── app/
│   ├── api/              # API 路由
│   │   ├── materials.py  # 素材管理
│   │   ├── videos.py     # 视频生成
│   │   └── publish.py    # 社交发布
│   ├── services/         # 核心服务
│   │   ├── tts_service.py      # EdgeTTS 配音
│   │   ├── video_service.py    # FFmpeg 视频合成
│   │   ├── lipsync_service.py  # MuseTalk 唇形同步
│   │   └── publish_service.py  # Playwright 自动发布
│   └── core/
│       └── config.py     # 配置管理
├── requirements.txt
└── .env.example

前端项目

• 使用 Next.js 14 + TypeScript + Tailwind CSS
• 主页面: 视频生成界面
• 发布页面: /publish 多平台发布管理

---

🔧 TTS + 视频合成

EdgeTTS 集成

• 使用 edge-tts 库实现免费中文语音合成
• 支持多种音色: 云溪、云健、云扬、晓晓、晓伊

FFmpeg 视频合成

# 核心命令
ffmpeg -i video.mp4 -i audio.mp3 -c:v copy -c:a aac -map 0:v -map 1:a output.mp4

🐛 Bug 修复: asyncio subprocess 问题

问题：在 FastAPI BackgroundTasks 中调用 asyncio.create_subprocess_exec 导致 NotImplementedError

原因：BackgroundTasks 运行在非 asyncio 上下文中

修复：将 _run_ffmpeg 和 _get_duration 改为使用同步 subprocess.run

# 修复前
result = await asyncio.create_subprocess_exec(...)

# 修复后
result = subprocess.run(cmd, shell=True, capture_output=True, text=True, encoding='utf-8')

状态：✅ 已修复，视频生成成功

---

🎬 MuseTalk 唇形同步集成

架构设计

• GPU0: 其他服务
• GPU1: MuseTalk 唇形同步

代码实现

• lipsync_service.py 支持本地模式和远程 API 模式
• 通过 CUDA_VISIBLE_DEVICES=1 指定使用 GPU1
• 如未配置，自动跳过唇形同步

---

📱 社交媒体发布

支持平台

平台	状态
抖音	✅ 框架完成
小红书	✅ 框架完成
微信视频号	✅ 框架完成
快手	✅ 框架完成
B站	✅ 框架完成

技术方案

• 使用 Playwright 进行浏览器自动化
• Cookie 管理实现免登录发布
• 前端提供账号管理和一键发布 UI

---

📚 文档产出

文件	说明
README.md	项目说明
DEPLOY_MANUAL.md	手动部署指南
deploy.sh	一键部署脚本
.env.example	环境配置模板

---

✅ 今日完成

1. ✅ FastAPI 后端框架搭建
2. ✅ EdgeTTS 语音合成服务
3. ✅ FFmpeg 视频合成服务
4. ✅ MuseTalk 唇形同步集成 (代码层面)
5. ✅ Next.js 前端 UI (视频生成 + 发布管理)
6. ✅ Playwright 社交媒体发布服务
7. ✅ 端到端视频生成测试通过
8. ✅ 服务器部署文档编写

---

下午调试记录 (Afternoon Debugging Session)

1. 前端 "Undefined" 错误

• 现象：视频生成失败，弹窗显示 "undefined"。
• 原因：
  1. 后端 videos.py 在异常捕获时未设置 message 字段，前端无法获取错误信息。
  2. 路径解析逻辑错误导致文件未找到。
• 修复：
  • 后端补充 tasks[task_id]["message"] 字段。
  • 修复 pathlib.Path 引用缺失。

2. 路径解析问题

• 现象：本地测试时无法找到素材文件。
• 原因：Windows 本地路径 (d:\...) 与相对路径混合使用，且 BASE_DIR 指向了错误的父级目录。
• 修复：
  • materials.py 所有返回路径改为相对路径 (uploads/materials/xxx)。
  • videos.py 增加智能路径解析：非绝对路径自动拼接 BASE_DIR。
  • config.py 调整 BASE_DIR 指向项目根目录。

3. 语法错误修复

• 现象：page.tsx 出现 Parsing ecmascript source code failed。
• 原因：调试代码逻辑错误地插入到了 JSX渲染块中。
• 修复：完全重写 page.tsx，规范化代码结构，增加 "Raw Response" 调试面板。

4. 本地 Fallback 逻辑验证

• 现象：进度条从 5% 直接跳到 100%。
• 原因：本地 MuseTalk 未启用，系统触发 fallback 逻辑（仅复制文件）。
• 验证：符合预期行为，确保了无 GPU 环境下的流程连通性。

---

📋 明日计划

1. 在服务器上部署系统
2. 下载 MuseTalk 模型权重
3. 测试完整唇形同步流程
4. 优化前端 UI 交互体验