Originals/ViGent2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 42 Wiki Activity
Files
96a298e51c36865144c9c1bcf17495e93a38fa2a
ViGent2/Docs/DEPLOY_MANUAL.md
Kevin Wong e33dfc3031 更新
2026-02-10 13:31:29 +08:00

16 KiB
Raw Blame History

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: 环境检查

# 检查 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

如果缺少依赖:

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: 创建目录结构

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

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

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

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

请参考详细的独立部署指南： LatentSync 部署指南

该指南包含以下关键步骤，请务必严格按照文档操作：

  1. 创建独立的 latentsync Conda 环境
  2. 安装 PyTorch 2.5.1 和相关依赖
  3. 下载模型权重 (HuggingFace CLI)
  4. 复制核心推理代码
  5. 验证推理脚本

验证 LatentSync 部署:

cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync
conda activate latentsync
python -m scripts.server  # 测试能否启动，Ctrl+C 退出

步骤 4: 安装后端依赖

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 认证、管理员后台

请参考独立的认证系统部署指南： 用户认证系统部署指南

步骤 6: 配置 Supabase RLS 策略 (重要)

⚠️ 注意：为了支持前端直传文件，必须配置存储桶的行级安全策略 (RLS)。

  1. 确保 Supabase 容器正在运行 (docker ps).
  2. 将项目根目录下的 supabase_rls.sql (如果有) 或以下 SQL 内容在数据库中执行。
  3. 执行命令: 
    # 进入后端目录
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: 配置环境变量

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: 安装前端依赖

cd /home/rongye/ProgramFiles/ViGent2/frontend

# 安装依赖
npm install

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

步骤 9: 测试运行

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

启动后端 (终端 1)

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

推荐使用项目脚本启动后端（已内置 xvfb + headful 发布环境）：

cd /home/rongye/ProgramFiles/ViGent2
./run_backend.sh  # 默认 8006，可用 PORT 覆盖

启动前端 (终端 2)

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

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

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:
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
  1. 使用 pm2 启动:
pm2 start ./run_backend.sh --name vigent2-backend

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

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

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 路径):
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
  1. 使用 pm2 启动:
pm2 start ./run_latentsync.sh --name vigent2-latentsync

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

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

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

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

  2. 使用 pm2 启动:

cd /home/rongye/ProgramFiles/ViGent2
pm2 start ./run_qwen_tts.sh --name vigent2-qwen-tts
pm2 save
  1. 验证服务:
# 检查健康状态
curl http://localhost:8009/health

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

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

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

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

pm2 save
pm2 startup

pm2 常用命令

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):

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 (视频渲染) 组件。

详细步骤请参考：字幕功能部署指南

简要步骤：

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

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

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

  1. 安装核心依赖:

    cd /home/rongye/ProgramFiles/ViGent2/backend
source venv/bin/activate
pip install yt-dlp zai-sdk

  2. 配置 AI 洗稿 (GLM): 确保 .env 中已配置 GLM_API_KEY:

    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 错误的核心原因。

关键配置项：

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 不可用

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

端口被占用

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

查看日志

# 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 服务： 
    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 模型加速
Reference in New Issue View Git Blame Copy Permalink