Originals/ViGent2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 42 Wiki Activity

更新

Browse Source
This commit is contained in:
Kevin Wong
2026-02-08 16:23:39 +08:00
parent 1a291a03b8
commit ee342cc40f
24 changed files with 1414 additions and 1082 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
Docs/BACKEND_DEV.md
View File

@@ -29,15 +29,27 @@ backend/
├── app/
│ ├── core/ # config、deps、security、response
│ ├── modules/ # 业务模块（路由 + 逻辑）
│ │ ├── videos/
│ │ ├── materials/
│ │ ├── publish/
│ │ ├── auth/
│ │ └── ...
│ │ ├── videos/ # 视频生成任务
│ │ ├── materials/ # 素材管理
│ │ ├── publish/ # 多平台发布
│ │ ├── auth/ # 认证与会话
│ │ ├── ai/ # AI 功能（标题标签生成等）
│ │ ├── assets/ # 静态资源（字体/样式/BGM）
│ │ ├── ref_audios/ # 声音克隆参考音频
│ │ ├── login_helper/ # 扫码登录辅助
│ │ ├── tools/ # 工具接口
│ │ └── admin/ # 管理员功能
│ ├── repositories/ # Supabase 数据访问
│ ├── services/ # 外部服务集成
│ │ ├── uploader/ # 平台发布器（douyin/weixin）
│ │ ├── qr_login_service.py
│ │ ├── publish_service.py
│ │ ├── remotion_service.py
│ │ ├── storage.py
│ │ └── ...
│ └── tests/
├── assets/ # 字体 / 样式 / bgm
├── user_data/ # 用户隔离数据（Cookie 等）
├── scripts/
└── requirements.txt
```
@@ -84,6 +96,21 @@ backend/
- 所有文件上传/下载/删除/移动通过 `services/storage.py`。
- 需要重命名时使用 `move_file`，避免直接读写 Storage。
### Cookie 存储（用户隔离）
多平台扫码登录产生的 Cookie 按用户隔离存储：
```
backend/user_data/{user_uuid}/cookies/
├── douyin_cookies.json
├── weixin_cookies.json
└── ...
```
- `publish_service.py` 中通过 `_get_cookies_dir(user_id)` / `_get_cookie_path(user_id, platform)` 定位
- 会话 key 格式：`"{user_id}_{platform}"`，确保多用户并发登录互不干扰
- 登录成功后 Cookie 自动保存到对应路径，发布时自动加载
---
## 7. 代码约定
@@ -110,13 +137,22 @@ backend/
- `REDIS_URL`
- `GLM_API_KEY`
- `LATENTSYNC_*`
- `CORS_ORIGINS` (CORS 白名单，默认 *)
### 微信视频号
- `WEIXIN_HEADLESS_MODE` (headful/headless-new)
- `WEIXIN_CHROME_PATH` / `WEIXIN_BROWSER_CHANNEL`
- `WEIXIN_USER_AGENT` / `WEIXIN_LOCALE` / `WEIXIN_TIMEZONE_ID`
- `WEIXIN_FORCE_SWIFTSHADER`
- `WEIXIN_TRANSCODE_MODE` (reencode/faststart/off)
- `CORS_ORIGINS` (CORS 白名单，默认 *)
- `SUPABASE_STORAGE_LOCAL_PATH` (本地存储路径)
### 抖音
- `DOUYIN_HEADLESS_MODE` (headful/headless-new，默认 headless-new)
- `DOUYIN_CHROME_PATH` / `DOUYIN_BROWSER_CHANNEL`
- `DOUYIN_USER_AGENT` (默认 Chrome/144)
- `DOUYIN_LOCALE` / `DOUYIN_TIMEZONE_ID`
- `DOUYIN_FORCE_SWIFTSHADER`
- `DOUYIN_DEBUG_ARTIFACTS` / `DOUYIN_RECORD_VIDEO` / `DOUYIN_KEEP_SUCCESS_VIDEO`
- `DOUYIN_COOKIE` (抖音视频下载 Cookie)
---

46
Docs/BACKEND_README.md
View File

@@ -15,11 +15,22 @@ backend/
├── app/
│ ├── core/ # 核心配置 (config.py, security.py, response.py)
│ ├── modules/ # 业务模块 (router/service/workflow/schemas)
│ │ ├── videos/ # 视频生成任务
│ │ ├── materials/ # 素材管理
│ │ ├── publish/ # 多平台发布
│ │ ├── auth/ # 认证与会话
│ │ ├── ai/ # AI 功能（标题标签生成）
│ │ ├── assets/ # 静态资源（字体/样式/BGM）
│ │ ├── ref_audios/ # 声音克隆参考音频
│ │ ├── login_helper/ # 扫码登录辅助
│ │ ├── tools/ # 工具接口（文案提取等）
│ │ └── admin/ # 管理员功能
│ ├── repositories/ # Supabase 数据访问
│ ├── services/ # 外部服务集成 (TTS/Remotion/Storage 等)
│ ├── services/ # 外部服务集成 (TTS/Remotion/Storage/Uploader 等)
│ └── tests/ # 单元测试与集成测试
├── scripts/ # 运维脚本 (watchdog.py, init_db.py)
├── assets/ # 资源库 (fonts, bgm, styles)
├── user_data/ # 用户隔离数据 (Cookie 等)
└── requirements.txt # 依赖清单
```
@@ -41,12 +52,11 @@ backend/
2. **视频生成 (Videos)**
* `POST /api/videos/generate`: 提交生成任务
* `GET /api/videos/tasks/{task_id}`: 查询任务状态
* `GET /api/videos/tasks/{task_id}`: 查询单个任务状态
* `GET /api/videos/tasks`: 获取用户所有任务列表
* `GET /api/videos/generated`: 获取历史视频列表
* `DELETE /api/videos/generated/{video_id}`: 删除历史视频
> **修正 (16:20)**：任务查询与历史列表接口已更新为 `/api/videos/tasks/{task_id}` 与 `/api/videos/generated`。
3. **素材管理 (Materials)**
* `POST /api/materials`: 上传素材
* `GET /api/materials`: 获取素材列表
@@ -54,14 +64,33 @@ backend/
4. **社交发布 (Publish)**
* `POST /api/publish`: 发布视频到 抖音/微信视频号/B站/小红书
* `POST /api/publish/login`: 扫码登录平台
* `GET /api/publish/login/status`: 查询登录状态（含刷脸验证二维码）
* `GET /api/publish/accounts`: 获取已登录账号列表
> 提示：视频号发布建议使用 headful + xvfb-run 运行后端，避免 headless 解码失败。
> 提示：视频号/抖音发布建议使用 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)
* `GET /api/ref-audios`: 获取参考音频列表
* `PUT /api/ref-audios/{id}`: 重命名参考音频
* `DELETE /api/ref-audios/{id}`: 删除参考音频
7. **AI 功能 (AI)**
* `POST /api/ai/generate-meta`: AI 生成标题和标签
8. **工具 (Tools)**
* `POST /api/tools/extract-script`: 从视频链接提取文案
9. **健康检查**
* `GET /api/lipsync/health`: LatentSync 服务健康状态
* `GET /api/voiceclone/health`: Qwen3-TTS 服务健康状态
### 统一响应结构
```json
@@ -79,10 +108,17 @@ backend/
`POST /api/videos/generate` 支持以下可选字段：
- `tts_mode`: TTS 模式 (`edgetts` / `voiceclone`)
- `voice`: EdgeTTS 音色 ID（edgetts 模式）
- `ref_audio_id` / `ref_text`: 参考音频 ID 与文本（voiceclone 模式）
- `title`: 片头标题文字
- `subtitle_style_id`: 字幕样式 ID
- `title_style_id`: 标题样式 ID
- `subtitle_font_size`: 字幕字号（覆盖样式默认值）
- `title_font_size`: 标题字号（覆盖样式默认值）
- `title_top_margin`: 标题距顶部像素
- `subtitle_bottom_margin`: 字幕距底部像素
- `enable_subtitles`: 是否启用字幕
- `bgm_id`: 背景音乐 ID
- `bgm_volume`: 背景音乐音量（0-1，默认 0.2）

22
Docs/DEPLOY_MANUAL.md
View File

@@ -115,6 +115,16 @@ playwright install chromium
```
> 提示：视频号发布建议使用系统 Chrome + xvfb-run（避免 headless 解码失败）。
> 抖音发布同样建议 headful 模式 (`DOUYIN_HEADLESS_MODE=headful`)。
### 扫码登录注意事项
- **Cookie 按用户隔离**：每个用户的 Cookie 存储在 `backend/user_data/{uuid}/cookies/` 目录下，多用户并发登录互不干扰。
- **抖音 QR 登录关键教训**：
- 扫码后绝对**不能重新加载 QR 页面**，否则会销毁会话 token
- 使用**新标签页**检测登录完成状态（检查 URL 包含 `creator-micro` + session cookies 存在）
- 抖音可能弹出**刷脸验证**，后端会自动提取验证二维码返回给前端展示
- **微信视频号发布**：标题、描述、标签统一写入"视频描述"字段
---
@@ -189,8 +199,17 @@ cp .env.example .env
| `WEIXIN_TIMEZONE_ID` | Asia/Shanghai | 视频号时区 |
| `WEIXIN_FORCE_SWIFTSHADER` | true | 强制软件 WebGL，避免 context lost |
| `WEIXIN_TRANSCODE_MODE` | reencode | 上传前转码 (reencode/faststart/off) |
| `DOUYIN_HEADLESS_MODE` | headless-new | 抖音 Playwright 模式 (headful/headless-new) |
| `DOUYIN_CHROME_PATH` | `/usr/bin/google-chrome` | 抖音 Chrome 路径 |
| `DOUYIN_BROWSER_CHANNEL` | | 抖音 Chromium 通道 (可选) |
| `DOUYIN_USER_AGENT` | Chrome/144 UA | 抖音浏览器指纹 UA |
| `DOUYIN_LOCALE` | zh-CN | 抖音语言环境 |
| `DOUYIN_TIMEZONE_ID` | Asia/Shanghai | 抖音时区 |
| `DOUYIN_FORCE_SWIFTSHADER` | true | 强制软件 WebGL |
| `DOUYIN_DEBUG_ARTIFACTS` | false | 保留调试截图 |
| `DOUYIN_RECORD_VIDEO` | false | 录制浏览器操作视频 |
| `DOUYIN_KEEP_SUCCESS_VIDEO` | false | 成功后保留录屏 |
| `CORS_ORIGINS` | `*` | CORS 允许源 (生产环境建议白名单) |
| `SUPABASE_STORAGE_LOCAL_PATH` | 默认路径 | Supabase 本地存储路径 |
| `DOUYIN_COOKIE` | 空 | 抖音视频下载 Cookie (文案提取功能) |
---
@@ -265,6 +284,7 @@ cat > run_backend.sh << 'EOF'
set -e
BASE_DIR="$(cd "$(dirname "$0")" && pwd)"
export WEIXIN_HEADLESS_MODE=headful
export DOUYIN_HEADLESS_MODE=headful
export WEIXIN_DEBUG_ARTIFACTS=false
export WEIXIN_RECORD_VIDEO=false
export DOUYIN_DEBUG_ARTIFACTS=false

19
Docs/DevLogs/Day20.md
View File

@@ -65,6 +65,15 @@ pm2 restart vigent2-latentsync
# Remotion 已自动编译
```
### 🎨 交互与体验优化 (17:00)
- [x] **UX-1**: PublishPage 图片加载优化 (`<img>` → `next/image`)
- [x] **UX-2**: 按钮 Loading 状态统一 (提取脚本弹窗 + 发布页)
- [x] **UX-3**: 骨架屏加载优化 (发布页加载中状态)
- [x] **UX-4**: 全局快捷键支持 (ESC 关闭弹窗, Enter 确认)
- [x] **UX-5**: 移除全局 GlobalTaskIndicator (视觉降噪)
- [x] **UX-6**: 视频生成完成自动刷新列表并选中最新
### 🐛 缺陷修复与回归治理 (17:30)
#### 严重缺陷修复
@@ -85,6 +94,10 @@ pm2 restart vigent2-latentsync
- *原因*: 重构移除旧逻辑后，新用户或无缓存用户进入页面无默认选中。
- *修复*: 在 `isRestored` 且无选中时，增加兜底逻辑自动选中列表第一项。
- [x] **REF-1**: 持久化逻辑全站收敛
- *优化*: 清理 `useBgm`, `useGeneratedVideos`, `useTitleSubtitleStyles` 中的冗余 `localStorage` 读取。
- *优化*: 修复 `useMaterials` 中的闭包陷阱（使用函数式更新），防止覆盖已恢复的状态。
- [x] **REG-3**: 素材选择持久化失效 (闭包陷阱)
- *原因*: `useMaterials` 加载回调中捕获了旧的 `selectedMaterial` 状态，覆盖了已恢复的值。
- *修复*: 改为函数式状态更新 (`setState(prev => ...)`)，确保基于最新状态判断。
- [x] **REF-1**: 持久化逻辑全站收敛与排查
- *优化*: 清理 `useBgm`, `useGeneratedVideos`, `useTitleSubtitleStyles` 中的冗余 `localStorage` 读取，统一由 `useHomePersistence` 管理。
- *排查*: 深度排查 `useRefAudios`, `useTitleSubtitleStyles` 等模块，确认逻辑健壮，无类似回归风险。

156
Docs/DevLogs/Day21.md
View File

@@ -90,3 +90,159 @@ await api.post('/api/publish', { video_path: video.path, ... });
pm2 restart vigent2-backend # Remotion 容错
npm run build && pm2 restart vigent2-frontend # 前端持久化修复
```
---
## 🎨 浮动样式预览窗口优化 (Day 21)
### 概述
标题与字幕面板中的预览区域原本是内联折叠的，展开后调节下方滑块时看不到预览效果。改为 `position: fixed` 浮动窗口，固定在视口左上角，滚动页面时预览始终可见，边调边看。
### 已完成优化
#### 1. 新建浮动预览组件 `FloatingStylePreview.tsx`
- `createPortal(jsx, document.body)` 渲染到 body 层级，脱离面板 DOM 树
- `position: fixed` + 左上角固定定位，滚动时不移动
- `z-index: 150`（低于 VideoPreviewModal 的 200）
- 顶部标题栏 + X 关闭按钮，ESC 键关闭
- 桌面端固定宽度 280px，移动端自适应（最大 360px）
- `previewScale = windowWidth / previewBaseWidth` 自行计算缩放
- `maxHeight: calc(100dvh - 32px)` 防止超出视口
#### 2. 修改 `TitleSubtitlePanel.tsx`
- 删除内联预览区域（`ref={previewContainerRef}` 整块 JSX）
- 条件渲染 `<FloatingStylePreview />`，按钮文本保持"预览样式"/"收起预览"
- 移除 `previewScale`、`previewAspectRatio`、`previewContainerRef` props
- 保留 `previewBaseWidth/Height`（浮动窗口需要原始尺寸计算 scale）
#### 3. 清理 `useHomeController.ts`
- 移除 `previewContainerWidth` 状态
- 移除 `titlePreviewContainerRef` ref
- 移除 ResizeObserver useEffect（浮动窗口自管尺寸，不再需要）
#### 4. 简化 `HomePage.tsx` 传参
- 移除 `previewContainerWidth`、`titlePreviewContainerRef` 解构
- 移除 `previewScale`、`previewAspectRatio`、`previewContainerRef` prop 传递
#### 5. 移动端适配
- `ScriptEditor.tsx`：标题行改为 `flex-wrap`，"AI生成标题标签"按钮不再溢出
- 预览默认比例从 1280×720 (16:9) 改为 1080×1920 (9:16)，符合抖音竖屏视频
### 涉及文件汇总
| 文件 | 变更 |
|------|------|
| `frontend/src/features/home/ui/FloatingStylePreview.tsx` | **新建** 浮动预览组件 |
| `frontend/src/features/home/ui/TitleSubtitlePanel.tsx` | 移除内联预览，渲染浮动组件 |
| `frontend/src/features/home/model/useHomeController.ts` | 移除 preview 容器相关状态和 ResizeObserver |
| `frontend/src/features/home/ui/HomePage.tsx` | 简化 props 传递，默认比例改 9:16 |
| `frontend/src/features/home/ui/ScriptEditor.tsx` | 移动端按钮换行适配 |
### 重启要求
```bash
npm run build && pm2 restart vigent2-frontend
```
---
## 🔧 多平台发布体系重构：用户隔离与抖音刷脸验证 (Day 21)
### 概述
重构发布系统的两大核心问题：① 多用户场景下 Cookie/会话缺乏隔离，② 抖音登录新增刷脸验证步骤无法处理。同时修复了平台配置混用和微信视频号发布流程问题。
---
### 一、平台配置独立化
#### 问题
所有平台（抖音、微信、B站、小红书）共用 WEIXIN_* 配置，导致 User-Agent、Headless 模式等设置不匹配。
#### 修复 — `config.py`
- 新增 `DOUYIN_*` 独立配置项：`DOUYIN_HEADLESS_MODE`、`DOUYIN_USER_AGENT`（Chrome/144）、`DOUYIN_LOCALE`、`DOUYIN_TIMEZONE_ID`、`DOUYIN_CHROME_PATH`、`DOUYIN_FORCE_SWIFTSHADER`、调试开关等
- 微信保持已有 `WEIXIN_*` 配置
- B站/小红书使用通用默认值
#### 修复 — `qr_login_service.py` 平台配置映射
```python
# 之前：所有平台都用 WEIXIN 设置
# 之后：每个平台独立配置
PLATFORM_CONFIGS = {
"douyin": { headless, user_agent, locale, timezone... },
"weixin": { headless, user_agent, locale, timezone... },
"bilibili": { 通用配置 },
"xiaohongshu": { 通用配置 },
}
```
---
### 二、用户隔离的 Cookie 管理
#### 问题
多用户共享同一套 Cookie 文件，用户 A 的登录态可能被用户 B 覆盖。
#### 修复 — `publish_service.py`
- `_get_cookies_dir(user_id)` → `backend/user_data/{uuid}/cookies/`
- `_get_cookie_path(user_id, platform)` → 按用户+平台返回独立 Cookie 文件路径
- `_get_session_key(user_id, platform)` → `"{user_id}_{platform}"` 格式的会话 key
- 登录/发布流程全链路传入 `user_id`，清理残留会话避免干扰
---
### 三、抖音刷脸验证二维码
#### 问题
抖音扫码登录后可能弹出刷脸验证窗口，内含新的二维码需要用户再次扫描，前端无法感知和展示。
#### 修复 — 后端 `qr_login_service.py`
- 扩展 QR 选择器：支持跨 iframe 搜索二维码元素
- 抖音 API 拦截：监听 `check_qrconnect` 响应，检测 `redirect_url`
- 检测 "完成验证" / "请前往APP完成验证" 文案
- 在验证弹窗内找到正方形二维码（排除头像），截图返回给前端
- API 确认后直接导航到 redirect_url（不重新加载 QR 页，避免销毁会话）
#### 修复 — 后端 `publish_service.py`
- `get_login_session_status()` 新增 `face_verify_qr` 字段返回
- 登录成功且 Cookie 保存后自动清理会话
#### 修复 — 前端
- `usePublishController.ts`：新增 `faceVerifyQr` 状态，轮询时获取 `face_verify_qr` 字段
- `PublishPage.tsx`：QR 弹窗优先展示刷脸验证二维码，附提示文案
```tsx
{faceVerifyQr ? (
<>
<Image src={`data:image/png;base64,${faceVerifyQr}`} />
<p>需要身份验证，请用抖音APP扫描上方二维码完成刷脸验证</p>
</>
) : /* 普通登录二维码 */ }
```
---
### 四、微信视频号发布流程优化
#### 修复 — `weixin_uploader.py`
- 添加 `user_id` 参数支持，发布截图目录隔离
- 新增 `post_create` API 响应监听，精准判断发布成功
- 发布结果判定：URL 离开创建页 或 API 确认提交 → 视为成功
- 标题/标签处理改为统一写入"视频描述"字段（不再单独填写 title/tags）
---
### 涉及文件汇总
| 文件 | 变更 |
|------|------|
| `backend/app/core/config.py` | 新增 DOUYIN_* 独立配置项 |
| `backend/app/services/qr_login_service.py` | 平台配置拆分、刷脸验证二维码、跨 iframe 选择器 |
| `backend/app/services/publish_service.py` | 用户隔离 Cookie 管理、刷脸验证状态返回 |
| `backend/app/services/uploader/weixin_uploader.py` | user_id 支持、post_create API 监听、描述字段合并 |
| `frontend/src/features/publish/model/usePublishController.ts` | faceVerifyQr 状态 |
| `frontend/src/features/publish/ui/PublishPage.tsx` | 刷脸验证二维码展示 |
### 重启要求
```bash
pm2 restart vigent2-backend # 发布服务 + QR登录
npm run build && pm2 restart vigent2-frontend # 刷脸验证UI
```

71
Docs/Doc_Rules.md
View File

@@ -31,8 +31,6 @@
| ⚡ **Med** | `Docs/FRONTEND_DEV.md` | **(前端规范)** API封装、日期格式化、新页面规范 |
| ⚡ **Med** | `Docs/FRONTEND_README.md` | **(前端文档)** 功能说明、页面变更 |
| 🧊 **Low** | `Docs/*_DEPLOY.md` | **(子系统部署)** LatentSync/Qwen3/字幕等独立部署文档 |
| 🧊 **Low** | `Docs/implementation_plan.md` | **(实施计划)** 核对计划与实际实现的差异 |
| 🧊 **Low** | `Docs/architecture_plan.md` | **(前端架构)** 拆分计划与阶段目标 |
---
@@ -97,7 +95,7 @@
### 必须执行的检查步骤
**1. 快速浏览全文**（使用 `view_file` 或 `grep_search`）
**1. 快速浏览全文**（使用 `Read` 或 `Grep`）
```markdown
# 检查是否存在：
- 同主题的旧章节？
@@ -144,66 +142,41 @@
> **核心原则**：使用正确的工具，避免字符编码问题
### ✅ 推荐工具：apply_patch
### ✅ 推荐工具：Edit / Read / Grep
**使用场景**：
- 追加新章节到文件末尾
- 修改/替换现有章节内容
- 更新状态标记（🔄 → ✅）
- 修正错误内容
**优势**：
- ✅ 自动处理字符编码（Windows CRLF）
- ✅ 精确替换，不会误删其他内容
- ✅ 有错误提示，方便调试
- `Read`：更新前先查看文件当前内容
- `Edit`：精确替换现有内容、追加新章节
- `Grep`：搜索文件中是否已有相关章节
- `Write`：创建新文件（如 Day{N+1}.md）
**注意事项**：
```markdown
1. **必须精确匹配**：TargetContent 必须与文件完全一致
2. **处理换行符**：文件使用 \r\n，不要漏掉 \r
3. **合理范围**：StartLine/EndLine 应覆盖目标内容
4. **先读后写**：编辑前先 view_file 确认内容
1. **先读后写**：编辑前先用 Read 确认内容
2. **精确匹配**：Edit 的 old_string 必须与文件内容完全一致
3. **避免重复**：编辑前用 Grep 检查是否已存在同主题章节
```
### ❌ 禁止使用：命令行工具
### ❌ 禁止使用：命令行工具修改文档
**禁止场景**：
- ❌ 使用 `echo >>` 追加内容（编码问题）
- ❌ 使用 PowerShell 直接修改文档（破坏格式）
- ❌ 使用 sed/awk 等命令行工具
- ❌ 使用 `echo >>` 追加内容
- ❌ 使用 `sed` / `awk` 修改文档
- ❌ 使用 `cat <<EOF` 写入内容
**原因**：
- 容易破坏 UTF-8 编码
- Windows CRLF vs Unix LF 混乱
- 容易破坏 UTF-8 编码和中文字符
- 难以追踪修改，容易出错
**唯一例外**：简单的全局文本替换（如批量更新日期），且必须使用 `-NoNewline` 参数
- 无法精确匹配替换位置
### 📝 最佳实践示例
**追加新章节**：
```diff
*** Begin Patch
*** Update File: Docs/DevLogs/DayN.md
@@
## 🔗 相关文档
...
---
**追加新章节**：使用 `Edit` 工具，`old_string` 匹配文件末尾内容，`new_string` 包含原内容 + 新章节。
## 🆕 新章节
内容...
*** End Patch
```
**修改现有内容**：
```diff
*** Begin Patch
*** Update File: Docs/DevLogs/DayN.md
@@
-**状态**：🔄 待修复
+**状态**：✅ 已修复
*** End Patch
**修改现有内容**：使用 `Edit` 工具精确替换。
```markdown
old_string: "**状态**：🔄 待修复"
new_string: "**状态**：✅ 已修复"
```
@@ -219,8 +192,6 @@ ViGent2/Docs/
├── BACKEND_README.md # 后端功能文档
├── FRONTEND_DEV.md # 前端开发规范
├── FRONTEND_README.md # 前端功能文档
├── architecture_plan.md # 前端拆分计划
├── implementation_plan.md # 实施计划
├── DEPLOY_MANUAL.md # 部署手册
├── SUPABASE_DEPLOY.md # Supabase 部署文档
├── LatentSync_DEPLOY.md # LatentSync 部署文档
@@ -325,4 +296,4 @@ ViGent2/Docs/
---
**最后更新**：2026-02-07
**最后更新**：2026-02-08

84
Docs/FRONTEND_DEV.md
View File

@@ -2,22 +2,65 @@
## 目录结构
采用轻量 FSD（Feature-Sliced Design）结构：
```
frontend/src/
├── app/ # Next.js App Router 页面
│ ├── page.tsx # 首页（视频生成）
│ ├── publish/ # 发布页面
│ ├── admin/ # 管理员页面
│ ├── login/ # 登录页面
│ └── register/ # 注册页面
├── components/ # 可复用组件
│ ├── home/ # 首页拆分组件
│ └── ...
├── lib/ # 公共工具函数
│ ├── axios.ts # Axios 实例（含 401/403 拦截器）
│ ├── auth.ts # 认证相关函数（统一使用 axios）
│ └── media.ts # API Base / URL / 日期等通用工具
└── proxy.ts # 路由代理（原 middleware）
├── app/ # Next.js App Router 页面入口
│ ├── page.tsx # 首页（视频生成）
│ ├── publish/ # 发布管理页
│ ├── admin/ # 管理员页面
│ ├── login/ # 登录
│ └── register/ # 注册
├── features/ # 功能模块（按业务拆分）
│ ├── home/
│ │ ├── model/ # 业务逻辑 hooks
│ │ │ ├── useHomeController.ts # 主控制器
│ │ │ ├── useHomePersistence.ts # 持久化管理
│ │ │ ├── useBgm.ts
│ │ │ ├── useGeneratedVideos.ts
│ │ │ ├── useMaterials.ts
│ │ │ ├── useMediaPlayers.ts
│ │ │ ├── useRefAudios.ts
│ │ │ └── useTitleSubtitleStyles.ts
│ │ └── ui/ # UI 组件（纯 props + 回调）
│ │ ├── HomePage.tsx
│ │ ├── HomeHeader.tsx
│ │ ├── MaterialSelector.tsx
│ │ ├── ScriptEditor.tsx
│ │ ├── TitleSubtitlePanel.tsx
│ │ ├── FloatingStylePreview.tsx
│ │ ├── VoiceSelector.tsx
│ │ ├── RefAudioPanel.tsx
│ │ ├── BgmPanel.tsx
│ │ ├── GenerateActionBar.tsx
│ │ ├── PreviewPanel.tsx
│ │ └── HistoryList.tsx
│ └── publish/
│ ├── model/
│ │ └── usePublishController.ts
│ └── ui/
│ └── PublishPage.tsx
├── shared/ # 跨功能共享
│ ├── api/
│ │ ├── axios.ts # Axios 实例（含 401/403 拦截器）
│ │ └── types.ts # 统一响应类型
│ ├── lib/
│ │ ├── media.ts # API Base / URL / 日期等通用工具
│ │ ├── auth.ts # 认证相关函数
│ │ └── title.ts # 标题输入处理
│ ├── hooks/
│ │ ├── useTitleInput.ts
│ │ └── usePublishPrefetch.ts
│ ├── types/
│ │ ├── user.ts # User 类型定义
│ │ └── publish.ts # 发布相关类型
│ └── contexts/ # 已迁移的 Context
├── contexts/ # 全局 Context（Auth、Task）
├── components/ # 遗留通用组件
│ ├── VideoPreviewModal.tsx
│ └── ScriptExtractionModal.tsx
└── proxy.ts # Next.js middleware（路由保护）
```
---
@@ -228,10 +271,15 @@ import { formatDate } from '@/shared/lib/media';
## 轻量 FSD 结构
- `app/`：页面入口，保持轻量
- `features/*/model`：业务逻辑与状态 (hooks)
- `features/*/ui`：功能 UI 组件
- `shared/`：通用工具、通用 hooks、API 实例
- `app/`：页面入口，保持轻量，只做组合与布局
- `features/*/model`：业务逻辑与状态（Controller Hook + 子 Hook）
- `features/*/ui`：功能 UI 组件（纯 props + 回调，不直接发 API）
- `shared/api`：Axios 实例与统一响应类型
- `shared/lib`：通用工具函数（media.ts / auth.ts / title.ts）
- `shared/hooks`：跨功能通用 hooks
- `shared/types`：跨功能实体类型（User / PublishVideo 等）
- `contexts/`：全局 Context（AuthContext / TaskContext）
- `components/`：遗留通用组件（VideoPreviewModal 等）
## 类型定义规范

427
Docs/implementation_plan.md
View File

@@ -1,427 +0,0 @@
# 数字人口播视频生成系统 - 实现计划
## 项目目标
构建一个开源的数字人口播视频生成系统，功能包括：
- 上传静态人物视频 → 生成口播视频（唇形同步）
- TTS 配音或声音克隆
- 字幕自动生成与渲染
- AI 自动生成标题与标签
- 一键发布到多个社交平台
---
## 技术架构
```
┌─────────────────────────────────────────────────────────┐
│ 前端 (Next.js) │
│ 素材管理 | 视频生成 | 发布管理 | 任务状态 │
└─────────────────────────────────────────────────────────┘
│ REST API
▼
┌─────────────────────────────────────────────────────────┐
│ 后端 (FastAPI) │
├─────────────────────────────────────────────────────────┤
│ 异步任务队列 (asyncio) │
│ ├── 视频生成任务 │
│ ├── TTS 配音任务 │
│ └── 自动发布任务 │
└─────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│LatentSync│ │ FFmpeg │ │Playwright│
│ 唇形同步 │ │ 视频合成 │ │ 自动发布 │
└──────────┘ └──────────┘ └──────────┘
```
---
## 技术选型
| 模块 | 技术选择 | 备选方案 |
|------|----------|----------|
| **前端框架** | Next.js 16 | Vue 3 + Vite |
| **UI 组件库** | TailwindCSS (自定义组件) | Ant Design |
| **后端框架** | FastAPI | Flask |
| **任务队列** | FastAPI BackgroundTasks (asyncio) | Celery + Redis |
| **唇形同步** | **LatentSync 1.6** | MuseTalk / Wav2Lip |
| **TTS 配音** | EdgeTTS | CosyVoice |
| **声音克隆** | **Qwen3-TTS 1.7B** ✅ | GPT-SoVITS |
| **视频处理** | FFmpeg | MoviePy |
| **自动发布** | Playwright | 自行实现 |
| **数据库** | Supabase (PostgreSQL) | MySQL |
| **文件存储** | Supabase Storage | 阿里云 OSS |
> **修正 (18:10)**：当前实现采用 Next.js 16、FastAPI BackgroundTasks 与 Supabase Storage/Auth，自动发布基于 Playwright。
---
## ✅ 现状补充 (Day 17)
- 前端已拆分为组件化结构（`features/home/ui/`），主页面逻辑集中。
- 通用工具 `media.ts` 统一处理 API Base / 资源 URL / 日期格式化。
- 作品预览弹窗统一样式，并支持素材/发布预览复用。
- 标题/字幕预览按素材分辨率缩放，效果更接近成片。
---
## 分阶段实施计划
### 阶段一：核心功能验证 (MVP)
> **目标**：验证 LatentSync + EdgeTTS 效果，跑通端到端流程
#### 1.1 环境搭建
参考 `models/LatentSync/DEPLOY.md` 完成 LatentSync 环境与权重部署。
#### 1.2 集成 EdgeTTS
```python
# tts_engine.py
import edge_tts
import asyncio
async def text_to_speech(text: str, voice: str = "zh-CN-YunxiNeural", output_path: str = "output.mp3"):
communicate = edge_tts.Communicate(text, voice)
await communicate.save(output_path)
return output_path
```
#### 1.3 端到端测试脚本
```python
# test_pipeline.py
"""
1. 文案 → EdgeTTS → 音频
2. 静态视频 + 音频 → LatentSync → 口播视频
3. 添加字幕 → FFmpeg → 最终视频
"""
```
#### 1.4 验证标准
- [ ] LatentSync 能正常推理
- [ ] 唇形与音频同步率 > 90%
- [ ] 单个视频生成时间 < 2 分钟
---
### 阶段二：后端 API 开发
> **目标**：将核心功能封装为 API，支持异步任务
#### 2.1 项目结构
```
backend/
├── app/
│ ├── main.py # FastAPI 入口
│ ├── api/
│ │ ├── videos.py # 视频生成 API
│ │ ├── materials.py # 素材管理 API
│ │ └── publish.py # 发布管理 API
│ ├── services/
│ │ ├── tts_service.py # TTS 服务
│ │ ├── lipsync_service.py # 唇形同步服务
│ │ └── video_service.py # 视频合成服务
│ ├── tasks/
│ │ └── celery_tasks.py # Celery 异步任务
│ ├── models/
│ │ └── schemas.py # Pydantic 模型
│ └── core/
│ └── config.py # 配置管理
├── requirements.txt
└── docker-compose.yml # Redis + API
```
#### 2.2 核心 API 设计
| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/materials` | POST | 上传视频素材 | ✅ |
| `/api/materials` | GET | 获取素材列表 | ✅ |
| `/api/videos/generate` | POST | 创建视频生成任务 | ✅ |
| `/api/videos/tasks/{id}` | GET | 查询任务状态 | ✅ |
| `/api/videos/generated` | GET | 获取历史作品列表 | ✅ |
| `/api/publish` | POST | 发布到社交平台 | ✅ |
#### 2.3 BackgroundTasks 任务定义
```python
# app/api/videos.py
background_tasks.add_task(_process_video_generation, task_id, req, user_id)
```
---
### 阶段三：前端 Web UI
> **目标**：提供用户友好的操作界面
#### 3.1 页面设计
| 页面 | 功能 |
|------|------|
| **素材库** | 上传/管理多场景视频素材 |
| **生成视频** | 输入文案、选择素材、生成预览 |
| **任务中心** | 查看生成进度、下载视频 |
| **发布管理** | 绑定平台、一键发布、定时发布 |
#### 3.2 技术实现
```bash
# 创建 Next.js 项目
npx create-next-app@latest frontend --typescript --tailwind --app
# 安装依赖
cd frontend
npm install axios swr
```
---
### 阶段四：社交媒体发布
> **目标**：集成 social-auto-upload，支持多平台发布
#### 4.1 复用 social-auto-upload
```bash
# 复制模块
cp -r SuperIPAgent/social-auto-upload backend/social_upload
```
#### 4.2 Cookie 管理
```python
# 用户通过浏览器登录 → 保存 Cookie → 后续自动发布
```
#### 4.3 支持平台
- 抖音
- 小红书
- 微信视频号
- 快手
---
### 阶段五：优化与扩展
| 功能 | 实现方式 |
|------|----------|
| **声音克隆** | 集成 GPT-SoVITS，用自己的声音 |
| **AI 标题/标签生成** | 调用大模型 API 自动生成标题与标签 ✅ |
| **批量生成** | 上传 Excel/CSV，批量生成视频 |
| **字幕编辑器** | 可视化调整字幕样式、位置 |
| **Docker 部署** | 一键部署到云服务器 | ✅ |
---
### 阶段六：MuseTalk 服务器部署 (Day 2-3) ✅
> **目标**：在双显卡服务器上部署 MuseTalk 环境
- [x] Conda 环境配置 (musetalk)
- [x] 模型权重下载 (~7GB)
- [x] Subprocess 调用方式实现
- [x] 健康检查功能
### 阶段七：MuseTalk 完整修复 (Day 4) ✅
> **目标**：解决推理脚本的各种兼容性问题
- [x] 权重检测路径修复 (软链接)
- [x] 音视频长度不匹配修复
- [x] 推理脚本错误日志增强
- [x] 视频合成 MP4 生成验证
### 阶段八：前端功能增强 (Day 5) ✅
> **目标**：提升用户体验
- [x] Web 视频上传功能
- [x] 上传进度显示
- [x] 自动刷新素材列表
### 阶段九：唇形同步模型升级 (Day 6) ✅
> **目标**：从 MuseTalk 迁移到 LatentSync 1.6
- [x] MuseTalk → LatentSync 1.6 迁移
- [x] 后端代码适配 (config.py, lipsync_service.py)
- [x] Latent Diffusion 架构 (512x512 高清)
- [x] 服务器端到端验证
### 阶段十：性能优化 (Day 6) ✅
> **目标**：提升系统响应速度和稳定性
- [x] 视频预压缩优化 (1080p → 720p 自动适配)
- [x] 进度更新细化 (实时反馈)
- [x] **常驻模型服务** (Persistent Server, 0s 加载)
- [x] **GPU 并发控制** (串行队列防崩溃)
### 阶段十一：社交媒体发布完善 (Day 7) ✅
> **目标**：实现全自动扫码登录和多平台发布
- [x] QR码自动登录 (Playwright headless + Stealth)
- [x] 多平台上传器架构 (B站/抖音/小红书)
- [x] Cookie 自动管理
- [x] 定时发布功能
### 阶段十二：用户体验优化 (Day 8) ✅
> **目标**：提升文件管理和历史记录功能
- [x] 文件名保留 (时间戳前缀 + 原始名称)
- [x] 视频持久化 (历史视频列表 API)
- [x] 素材/视频删除功能
### 阶段十三：发布模块优化 (Day 9) ✅
> **目标**：代码质量优化 + 发布功能验证
- [x] B站/抖音登录+发布验证通过
- [x] 资源清理保障 (try-finally)
- [x] 超时保护 (消除无限循环)
- [x] 完整类型提示
### 阶段十四：用户认证系统 (Day 9) ✅
> **目标**：实现安全、隔离的多用户认证体系
- [x] Supabase 云数据库集成 (本地自托管)
- [x] JWT + HttpOnly Cookie 认证架构
- [x] 用户表与权限表设计 (RLS 准备)
- [x] 认证部署文档 (Docs/SUPABASE_DEPLOY.md)
### 阶段十五：部署稳定性优化 (Day 9) ✅
> **目标**：确保生产环境服务长期稳定
- [x] 依赖冲突修复 (bcrypt)
- [x] 前端构建修复 (Production Build)
- [x] PM2 进程守护配置
- [x] 部署手册更新 (Docs/DEPLOY_MANUAL.md)
### 阶段十六：HTTPS 全栈部署 (Day 10) ✅
> **目标**：实现安全的公网 HTTPS 访问
- [x] 阿里云 Nginx 反向代理配置
- [x] Let's Encrypt SSL 证书集成
- [x] Supabase 自托管部署 (Docker)
- [x] 端口冲突解决 (3003/8008/8444)
- [x] Basic Auth 管理后台保护
### 阶段十七：声音克隆功能集成 (Day 13) ✅
> **目标**：实现用户自定义声音克隆能力
- [x] Qwen3-TTS HTTP 服务 (独立 FastAPI，端口 8009)
- [x] 声音克隆服务封装 (voice_clone_service.py)
- [x] 参考音频管理 API (上传/列表/删除)
- [x] 前端 TTS 模式选择 UI
- [x] Supabase ref-audios Bucket 配置
- [x] 端到端测试验证
### 阶段十八：手机号登录迁移 (Day 15) ✅
> **目标**：将认证系统从邮箱迁移到手机号
- [x] 数据库 Schema 迁移 (email → phone)
- [x] 后端 API 适配 (auth.py/admin.py)
- [x] 11位手机号校验 (正则验证)
- [x] 修改密码功能 (/api/auth/change-password)
- [x] 账户设置下拉菜单 (修改密码 + 有效期显示 + 退出)
- [x] 前端登录/注册页面更新
- [x] 数据库迁移脚本 (migrate_to_phone.sql)
### 阶段十九：深度性能优化与服务守护 (Day 16) ✅
> **目标**：提升系统响应速度与服务稳定性
- [x] Flash Attention 2 集成 (Qwen3-TTS 加速 5x)
- [x] LatentSync 性能调优 (OMP 线程限制 + 原生 Flash Attn)
- [x] Watchdog 服务守护 (自动重启僵死服务)
- [x] 文档体系更新 (部署手册与运维指南)
---
## 项目目录结构 (最终)
---
## 开发时间估算
| 阶段 | 预计时间 | 说明 |
|------|----------|------|
| 阶段一 | 2-3 天 | 环境搭建 + 效果验证 |
| 阶段二 | 3-4 天 | 后端 API 开发 |
| 阶段三 | 3-4 天 | 前端 UI 开发 |
| 阶段四 | 2 天 | 社交发布集成 |
| 阶段五 | 按需 | 持续优化 |
**总计**：约 10-13 天可完成 MVP
---
### 阶段二十：代码质量与安全优化 (Day 20) ✅
> **目标**：全面提升代码健壮性、安全性与配置灵活性
- [x] **安全性修复**：硬编码 Cookie/Key 移除，ffprobe 安全调用，日志脱敏
- [x] **配置化改造**：存储路径、CORS、录屏开关全面环境变量化
- [x] **性能优化**：API 异步改造 (httpx/asyncio)，大文件流式上传
- [x] **构建优化**：Remotion 预编译，统一启动脚本 `run_backend.sh`
---
## 验证计划
### 阶段一验证
1. 运行 `test_pipeline.py` 脚本
2. 检查生成视频的唇形同步效果
3. 确认音画同步
### 阶段二验证
1. 使用 Postman/curl 测试所有 API 端点
2. 验证任务队列正常工作
3. 检查视频生成完整流程
### 阶段三验证
1. 在浏览器中完成完整操作流程
2. 验证上传、生成、下载功能
3. 检查响应式布局
### 阶段四验证
1. 发布一个测试视频到抖音
2. 验证定时发布功能
3. 检查发布状态同步
---
## 硬件要求
| 配置 | 最低要求 | 推荐配置 |
|------|----------|----------|
| **GPU** | NVIDIA GTX 1060 6GB | RTX 3060 12GB+ |
| **内存** | 16GB | 32GB |
| **存储** | 100GB SSD | 500GB SSD |
| **CUDA** | 11.7+ | 12.0+ |
---
## 下一步行动
1. **确认你的 GPU 配置** - MuseTalk 需要 NVIDIA GPU
2. **选择开发起点** - 从阶段一开始验证效果
3. **确定项目位置** - 在哪个目录创建项目
---
> [!IMPORTANT]
> 请确认以上计划是否符合你的需求，有任何需要调整的地方请告诉我。