Files

Kevin Wong 1e52346eb4 更新

2026-02-07 14:29:57 +08:00

15 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 部署指南

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

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

验证 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 解码失败）。

可选：AI 标题/标签生成

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

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

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

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

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

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

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

确保 Supabase 容器正在运行 (docker ps).
将项目根目录下的 supabase_rls.sql (如果有) 或以下 SQL 内容在数据库中执行。

执行命令:

# 进入后端目录
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

步骤 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)
`CORS_ORIGINS`	`*`	CORS 允许源 (生产环境建议白名单)
`SUPABASE_STORAGE_LOCAL_PATH`	默认路径	Supabase 本地存储路径
`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

验证

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

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

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

1. 启动后端服务 (FastAPI)

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

创建启动脚本 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 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

使用 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 模型服务

创建启动脚本 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

使用 pm2 启动:

pm2 start ./run_latentsync.sh --name vigent2-latentsync

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

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

安装 HTTP 服务依赖:

conda activate qwen-tts
pip install fastapi uvicorn python-multipart

启动脚本位于项目根目录: run_qwen_tts.sh
使用 pm2 启动:

cd /home/rongye/ProgramFiles/ViGent2
pm2 start ./run_qwen_tts.sh --name vigent2-qwen-tts
pm2 save

验证服务:

# 检查健康状态
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 配置。

前置条件：

已申请 SSL 证书 (如 Let's Encrypt)。
使用 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 (视频渲染) 组件。

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

简要步骤：

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

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

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

安装核心依赖:

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

配置 AI 洗稿 (GLM): 确保 .env 中已配置 GLM_API_KEY:
```
GLM_API_KEY=your_zhipu_api_key
```
验证: 访问 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 时导致瞬时负载过高。

解决：

检查系统负载：top 或 htop
如果不需要实时生成视频，可以暂时停止 LatentSync 服务：
```
pm2 stop vigent2-latentsync
```
确保服务器有足够的 RAM 和 Swap 空间。
代码级优化：已在 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 样式

LatentSync 关键依赖

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

15 KiB Raw Blame History Unescape Escape