ViGent2/Docs/DEPLOY_MANUAL.md

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

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

如果缺少依赖:

sudo apt update
sudo apt install ffmpeg

# 安装 pm2
npm install -g pm2

---

步骤 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

---

步骤 5: 配置环境变量

cd /home/rongye/ProgramFiles/ViGent2/backend

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

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

配置项	默认值	说明
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

---

步骤 6: 安装前端依赖

cd /home/rongye/ProgramFiles/ViGent2/frontend

# 安装依赖
npm install

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

---

步骤 7: 测试运行

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

启动后端 (终端 1)

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

启动前端 (终端 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. 上传测试视频，生成口播视频

---

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

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

创建 pm2 配置文件

创建 /home/rongye/ProgramFiles/ViGent2/ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: 'vigent2-backend',
      cwd: '/home/rongye/ProgramFiles/ViGent2/backend',
      script: 'venv/bin/uvicorn',
      args: 'app.main:app --host 0.0.0.0 --port 8006',
      interpreter: 'none',
      env: {
        PATH: '/home/rongye/ProgramFiles/ViGent2/backend/venv/bin:' + process.env.PATH
      }
    },
    {
      name: 'vigent2-frontend',
      cwd: '/home/rongye/ProgramFiles/ViGent2/frontend',
      script: 'npm',
      args: 'run start',
      env: {
        PORT: 3002
      }
    },
    {
      name: 'vigent2-latentsync',
      cwd: '/home/rongye/ProgramFiles/ViGent2/models/LatentSync',
      script: 'python',
      args: '-m scripts.server',
      interpreter: '/home/rongye/miniconda3/envs/latentsync/bin/python'
    }
  ]
};

启动服务

cd /home/rongye/ProgramFiles/ViGent2

# 启动所有服务
pm2 start ecosystem.config.js

# 查看状态
pm2 status

# 设置开机自启
pm2 save
pm2 startup  # 按提示执行生成的命令

pm2 常用命令

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

---

故障排除

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

查看日志

# pm2 日志
pm2 logs vigent2-backend
pm2 logs vigent2-frontend
pm2 logs vigent2-latentsync

---

依赖清单

后端关键依赖

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

前端关键依赖

依赖	用途
next	React 框架
swr	数据请求与缓存
tailwindcss	CSS 样式

LatentSync 关键依赖

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