# ViGent 手动部署指南

## 服务器信息

| 配置 | 规格 |
|------|------|
| 服务器 | Dell PowerEdge R730 |
| CPU | 2× Intel Xeon E5-2680 v4 (56 线程) |
| 内存 | 192GB DDR4 |
| GPU 0 | NVIDIA RTX 3090 24GB |
| GPU 1 | NVIDIA RTX 3090 24GB (用于 LatentSync) |
| 部署路径 | `/home/rongye/ProgramFiles/ViGent2` |

---

## 步骤 1: 环境检查

```bash
# 检查 GPU
nvidia-smi

# 检查 Python 版本 (需要 3.10+)
python3 --version

# 检查 Node.js 版本 (需要 18+)
node --version

# 检查 FFmpeg
ffmpeg -version

# 检查 Chrome (视频号发布)
google-chrome --version

# 检查 Xvfb
xvfb-run --help

# 检查 pm2 (用于服务管理)
pm2 --version

# 检查 Redis (任务状态存储，推荐)
redis-server --version
```

如果缺少依赖:
```bash
sudo apt update
sudo apt install ffmpeg

# 安装 Xvfb (视频号发布)
sudo apt install xvfb

# 安装 pm2
npm install -g pm2

# 安装 Chrome (视频号发布)
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-linux-signing-keyring.gpg
printf "deb [arch=amd64 signed-by=/usr/share/keyrings/google-linux-signing-keyring.gpg] http://dl.google.com/linux/chrome/deb/ stable main\n" | sudo tee /etc/apt/sources.list.d/google-chrome.list > /dev/null
sudo apt update
sudo apt install -y google-chrome-stable
```

---

## 步骤 2: 创建目录结构

```bash
mkdir -p /home/rongye/ProgramFiles/ViGent2
cd /home/rongye/ProgramFiles/ViGent2
```

将项目文件复制到该目录。

---

## 步骤 3: 部署 AI 模型 (LatentSync 1.6)

> ⚠️ **重要**：LatentSync 需要独立的 Conda 环境和 **~18GB VRAM**。请**不要**直接安装在后端环境中。

请参考详细的独立部署指南：
**[LatentSync 部署指南](../models/LatentSync/DEPLOY.md)**

该指南包含以下关键步骤，请务必严格按照文档操作：
1. 创建独立的 `latentsync` Conda 环境
2. 安装 PyTorch 2.5.1 和相关依赖
3. 下载模型权重 (HuggingFace CLI)
4. 复制核心推理代码
5. 验证推理脚本

**验证 LatentSync 部署**:
```bash
cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync
conda activate latentsync
python -m scripts.server  # 测试能否启动，Ctrl+C 退出
```

---

## 步骤 4: 安装后端依赖

```bash
cd /home/rongye/ProgramFiles/ViGent2/backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装 PyTorch (CUDA 12.1)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装 Python 依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器（社交发布需要）
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 存在）
  - 抖音可能弹出**刷脸验证**，后端会自动提取验证二维码返回给前端展示
- **微信视频号发布**：标题、描述、标签统一写入"视频描述"字段

---

### 可选：AI 标题/标签生成

> ✅ 如需启用“AI 标题/标签生成”功能，请确保后端可访问外网 API。

- 需要可访问 `https://open.bigmodel.cn`
- API Key 配置在 `backend/app/services/glm_service.py`（建议替换为自己的密钥）

---

## 步骤 5: 部署用户认证系统 (Supabase + Auth)

> 🔐 **包含**: 登录/注册、Supabase 数据库配置、JWT 认证、管理员后台

请参考独立的认证系统部署指南：
**[用户认证系统部署指南](AUTH_DEPLOY.md)**

---

## 步骤 6: 配置 Supabase RLS 策略 (重要)
 
 > ⚠️ **注意**：为了支持前端直传文件，必须配置存储桶的行级安全策略 (RLS)。
 
 1. 确保 Supabase 容器正在运行 (`docker ps`).
 2. 将项目根目录下的 `supabase_rls.sql` (如果有) 或以下 SQL 内容在数据库中执行。
 3. **执行命令**:
    ```bash
    # 进入后端目录
    cd /home/rongye/ProgramFiles/ViGent2/backend
    
    # 执行 SQL (允许 anon 角色上传/读取 materials 桶)
    docker exec -i supabase-db psql -U postgres <<EOF
    INSERT INTO storage.buckets (id, name, public) VALUES ('materials', 'materials', true) ON CONFLICT (id) DO NOTHING;
    INSERT INTO storage.buckets (id, name, public) VALUES ('outputs', 'outputs', true) ON CONFLICT (id) DO NOTHING;
    CREATE POLICY "Allow public uploads" ON storage.objects FOR INSERT TO anon WITH CHECK (bucket_id = 'materials');
    CREATE POLICY "Allow public read" ON storage.objects FOR SELECT TO anon USING (bucket_id = 'materials' OR bucket_id = 'outputs');
    EOF
    ```

> **注意**：后端启动时会自动创建额外的存储桶（`ref-audios`、`generated-audios`），无需手动创建。
 
 ---
 
 ## 步骤 7: 配置环境变量


```bash
cd /home/rongye/ProgramFiles/ViGent2/backend

# 复制配置模板
cp .env.example .env
```

> 💡 **说明**：`.env.example` 已包含正确的默认配置，直接复制即可使用。  
> 如需自定义，可编辑 `.env` 修改以下参数：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `SUPABASE_URL` | `http://localhost:8008` | Supabase API 内部地址 |
| `SUPABASE_PUBLIC_URL` | `https://api.hbyrkj.top` | Supabase API 公网地址 (前端访问) |
| `LATENTSYNC_GPU_ID` | 1 | GPU 选择 (0 或 1) |
| `LATENTSYNC_USE_SERVER` | false | 设为 true 以启用常驻服务加速 |
| `LATENTSYNC_INFERENCE_STEPS` | 20 | 推理步数 (20-50) |
| `LATENTSYNC_GUIDANCE_SCALE` | 1.5 | 引导系数 (1.0-3.0) |
| `DEBUG` | true | 生产环境改为 false |
| `REDIS_URL` | `redis://localhost:6379/0` | 任务状态存储（不可用时回退内存） |
| `WEIXIN_HEADLESS_MODE` | headless-new | 视频号 Playwright 模式 (headful/headless-new) |
| `WEIXIN_CHROME_PATH` | `/usr/bin/google-chrome` | 系统 Chrome 路径 |
| `WEIXIN_BROWSER_CHANNEL` |  | Chromium 通道 (可选) |
| `WEIXIN_USER_AGENT` | Chrome 120 UA | 视频号浏览器指纹 UA |
| `WEIXIN_LOCALE` | zh-CN | 视频号语言环境 |
| `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 允许源 (生产环境建议白名单) |
| `DOUYIN_COOKIE` | 空 | 抖音视频下载 Cookie (文案提取功能) |

---

## 步骤 8: 安装前端依赖

```bash
cd /home/rongye/ProgramFiles/ViGent2/frontend

# 安装依赖
npm install

# 生产环境构建 (可选)
npm run build
```

---

## 步骤 9: 测试运行

> 💡 先手动启动测试，确认一切正常后再配置 pm2 常驻服务。

### 启动后端 (终端 1)

```bash
cd /home/rongye/ProgramFiles/ViGent2/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8006
```

推荐使用项目脚本启动后端（已内置 xvfb + headful 发布环境）：
```bash
cd /home/rongye/ProgramFiles/ViGent2
./run_backend.sh  # 默认 8006，可用 PORT 覆盖
```

### 启动前端 (终端 2)

```bash
cd /home/rongye/ProgramFiles/ViGent2/frontend
npm run dev -- -H 0.0.0.0 --port 3002
```

### 启动 LatentSync (终端 3, 可选加速)

```bash
cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync
conda activate latentsync
python -m scripts.server
```
 
### 验证

1. 访问 http://服务器IP:3002 查看前端
2. 访问 http://服务器IP:8006/docs 查看 API 文档
3. 上传测试视频，生成口播视频

---

## 步骤 10: 使用 pm2 管理常驻服务

> 推荐使用 pm2 管理所有服务，支持自动重启和日志管理。

### 1. 启动后端服务 (FastAPI)

建议使用 Shell 脚本启动以避免环境问题。

1. 创建启动脚本 `run_backend.sh`:
```bash
cat > run_backend.sh << 'EOF'
#!/usr/bin/env bash
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
export DOUYIN_RECORD_VIDEO=false
PORT=${PORT:-8006}
cd "$BASE_DIR/backend"
exec xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" \
  ./venv/bin/uvicorn app.main:app --host 0.0.0.0 --port "$PORT"
EOF
chmod +x run_backend.sh
```

2. 使用 pm2 启动:
```bash
pm2 start ./run_backend.sh --name vigent2-backend
```

### 2. 启动前端服务 (Next.js)

⚠️ **注意**：生产模式启动前必须先进行构建。

```bash
cd /home/rongye/ProgramFiles/ViGent2/frontend

# 1. 构建项目 (如果之前没跑过或代码有更新)
npm run build

# 2. 启动服务
pm2 start npm --name vigent2-frontend -- run start -- -p 3002
```

### 3. 启动 LatentSync 模型服务

1. 创建启动脚本 `run_latentsync.sh` (使用你的 conda python 路径):
```bash
cat > run_latentsync.sh << 'EOF'
#!/bin/bash
cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync
# 替换为你的实际 Python 路径
/home/rongye/ProgramFiles/miniconda3/envs/latentsync/bin/python -m scripts.server
EOF
chmod +x run_latentsync.sh
```

2. 使用 pm2 启动:
```bash
pm2 start ./run_latentsync.sh --name vigent2-latentsync
```

### 4. 启动 Qwen3-TTS 声音克隆服务 (可选)

> 如需使用声音克隆功能，需要启动此服务。

1. 安装 HTTP 服务依赖:
```bash
conda activate qwen-tts
pip install fastapi uvicorn python-multipart
```

2. 启动脚本位于项目根目录: `run_qwen_tts.sh`

3. 使用 pm2 启动:
```bash
cd /home/rongye/ProgramFiles/ViGent2
pm2 start ./run_qwen_tts.sh --name vigent2-qwen-tts
pm2 save
```

4. 验证服务:
```bash
# 检查健康状态
curl http://localhost:8009/health
```

### 5. 启动服务看门狗 (Watchdog)

> 🛡️ **推荐**：监控 Qwen-TTS 和 LatentSync 服务健康状态，卡死时自动重启。

```bash
cd /home/rongye/ProgramFiles/ViGent2
pm2 start ./run_watchdog.sh --name vigent2-watchdog
pm2 save
```

### 6. 保存当前列表 (开机自启)

```bash
pm2 save
pm2 startup
```

### pm2 常用命令

```bash
pm2 status                    # 查看所有服务状态
pm2 logs                      # 查看所有日志
pm2 logs vigent2-backend      # 查看后端日志
pm2 logs vigent2-qwen-tts     # 查看 Qwen3-TTS 日志
pm2 restart all               # 重启所有服务
pm2 stop vigent2-latentsync   # 停止 LatentSync 服务
pm2 delete all                # 删除所有服务
```


---

## 步骤 11: 配置 Nginx HTTPS (可选 - 公网访问)

如果您需要通过公网域名 HTTPS 访问 (如 `https://vigent.hbyrkj.top`)，请参考以下 Nginx 配置。

**前置条件**：
1. 已申请 SSL 证书 (如 Let's Encrypt)。
2. 使用 FRP 或其他方式将本地 3002 端口映射到服务器。

**配置示例** (`/etc/nginx/conf.d/vigent.conf`):

```nginx
server {
    listen 80;
    server_name your.domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your.domain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3002;  # 转发给 Next.js 前端
        
        # 必须配置 WebSocket 支持，否则热更和即时通信失效
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---


---

---

## 步骤 13: 部署可选功能 (字幕与文案助手)

本节介绍如何部署逐字高亮字幕、片头标题以及文案提取助手功能。

### 13.1 部署字幕系统 (Subtitle System)

包含 `faster-whisper` (字幕生成) 和 `Remotion` (视频渲染) 组件。

详细步骤请参考：**[字幕功能部署指南](SUBTITLE_DEPLOY.md)**

简要步骤：
1. 安装 Python 依赖: `faster-whisper`
2. 安装 Node.js 依赖: `npm install` (在 `remotion/` 目录)
3. 验证: `npx remotion --version`

### 13.2 部署文案提取助手 (Copywriting Assistant)

支持 B站/抖音/TikTok 视频链接提取文案与 AI 洗稿。

1. **安装核心依赖**:
   ```bash
   cd /home/rongye/ProgramFiles/ViGent2/backend
   source venv/bin/activate
   pip install yt-dlp zai-sdk
   ```

2. **配置 AI 洗稿 (GLM)**:
   确保 `.env` 中已配置 `GLM_API_KEY`:
   ```ini
   GLM_API_KEY=your_zhipu_api_key
   ```

3. **验证**:
   访问 `http://localhost:8006/docs`，测试 `/api/tools/extract-script` 接口。

---

## 步骤 14: 配置阿里云 Nginx 网关 (关键)

> ⚠️ **CRITICAL**: 如果使用 `api.hbyrkj.top` 等域名作为入口，必须在阿里云 (或公网入口) 的 Nginx 配置中解除上传限制。
> **这是导致 500/413 错误的核心原因。**

**关键配置项**：
```nginx
server {
    listen 443 ssl;
    server_name api.hbyrkj.top;
    
    # ... 其他 SSL 配置 ...

    # 允许大文件上传 (0 表示不限制，或设置为 100M, 500M)
    client_max_body_size 0; 

    location / {
        proxy_pass http://127.0.0.1:YOUR_FRP_PORT;
        
        # 延长超时时间
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}
```

**后果**：如果没有这个配置，上传会在 ~1MB 或 ~10MB 时直接断开，报 413 Payload Too Large 或 500/502 错误。

---

## 故障排除


### GPU 不可用

```bash
# 检查 CUDA
nvidia-smi
python3 -c "import torch; print(torch.cuda.is_available())"
```

### 端口被占用

```bash
# 查看端口占用
sudo lsof -i :8006
sudo lsof -i :3002
sudo lsof -i :8007
sudo lsof -i :8009  # Qwen3-TTS
```

### 查看日志

```bash
# pm2 日志
pm2 logs vigent2-backend
pm2 logs vigent2-frontend
pm2 logs vigent2-latentsync
pm2 logs vigent2-qwen-tts
```

### SSH 连接卡顿 / 系统响应慢

**原因**：LatentSync 模型服务启动时会占用大量 I/O 和 CPU 资源，或者模型加载到 GPU 时导致瞬时负载过高。

**解决**：
1. 检查系统负载：`top` 或 `htop`
2. 如果不需要实时生成视频，可以暂时停止 LatentSync 服务：
   ```bash
   pm2 stop vigent2-latentsync
   ```
3. 确保服务器有足够的 RAM 和 Swap 空间。
4. **代码级优化**：已在 `scripts/server.py` 和 `scripts/inference.py` 中强制限制 `OMP_NUM_THREADS=8`，防止 PyTorch 占用所有 CPU 核心导致系统假死。

---

## 依赖清单

### 后端关键依赖

| 依赖 | 用途 |
|------|------|
| `fastapi` | Web API 框架 |
| `uvicorn` | ASGI 服务器 |
| `edge-tts` | 微软 TTS 配音 |
| `httpx` | GLM API HTTP 客户端 |
| `playwright` | 社交媒体自动发布 |
| `biliup` | B站视频上传 |
| `loguru` | 日志管理 |

### 前端关键依赖

| 依赖 | 用途 |
|------|------|
| `next` | React 框架 |
| `swr` | 数据请求与缓存 |
| `tailwindcss` | CSS 样式 |
| `wavesurfer.js` | 音频波形（时间轴编辑器） |

### LatentSync 关键依赖

| 依赖 | 用途 |
|------|------|
| `torch` 2.5.1 | PyTorch GPU 推理 |
| `diffusers` | Latent Diffusion 模型 |
| `accelerate` | 模型加速 |