368 lines
8.4 KiB
Markdown
368 lines
8.4 KiB
Markdown
# 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
|
||
|
||
# 检查 pm2 (用于服务管理)
|
||
pm2 --version
|
||
```
|
||
|
||
如果缺少依赖:
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install ffmpeg
|
||
|
||
# 安装 pm2
|
||
npm install -g pm2
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 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
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 5: 部署用户认证系统 (Supabase + Auth)
|
||
|
||
> 🔐 **包含**: 登录/注册、Supabase 数据库配置、JWT 认证、管理员后台
|
||
|
||
请参考独立的认证系统部署指南：
|
||
**[用户认证系统部署指南](AUTH_DEPLOY.md)**
|
||
|
||
---
|
||
|
||
## 步骤 6: 配置环境变量
|
||
|
||
```bash
|
||
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 |
|
||
|
||
---
|
||
|
||
## 步骤 7: 安装前端依赖
|
||
|
||
```bash
|
||
cd /home/rongye/ProgramFiles/ViGent2/frontend
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 生产环境构建 (可选)
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 8: 测试运行
|
||
|
||
> 💡 先手动启动测试，确认一切正常后再配置 pm2 常驻服务。
|
||
|
||
### 启动后端 (终端 1)
|
||
|
||
```bash
|
||
cd /home/rongye/ProgramFiles/ViGent2/backend
|
||
source venv/bin/activate
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8006
|
||
```
|
||
|
||
### 启动前端 (终端 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. 上传测试视频，生成口播视频
|
||
|
||
---
|
||
|
||
## 步骤 9: 使用 pm2 管理常驻服务
|
||
|
||
> 推荐使用 pm2 管理所有服务，支持自动重启和日志管理。
|
||
|
||
### 1. 启动后端服务 (FastAPI)
|
||
|
||
建议使用 Shell 脚本启动以避免环境问题。
|
||
|
||
1. 创建启动脚本 `run_backend.sh`:
|
||
```bash
|
||
cat > run_backend.sh << 'EOF'
|
||
#!/bin/bash
|
||
cd /home/rongye/ProgramFiles/ViGent2/backend
|
||
./venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8006
|
||
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. 保存当前列表 (开机自启)
|
||
|
||
```bash
|
||
pm2 save
|
||
pm2 startup
|
||
```
|
||
|
||
### pm2 常用命令
|
||
|
||
```bash
|
||
pm2 status # 查看所有服务状态
|
||
pm2 logs # 查看所有日志
|
||
pm2 logs vigent2-backend # 查看后端日志
|
||
pm2 restart all # 重启所有服务
|
||
pm2 stop vigent2-latentsync # 停止 LatentSync 服务
|
||
pm2 delete all # 删除所有服务
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## 步骤 10: 配置 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;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 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
|
||
```
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# pm2 日志
|
||
pm2 logs vigent2-backend
|
||
pm2 logs vigent2-frontend
|
||
pm2 logs vigent2-latentsync
|
||
```
|
||
|
||
### 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 配音 |
|
||
| `playwright` | 社交媒体自动发布 |
|
||
| `biliup` | B站视频上传 |
|
||
| `loguru` | 日志管理 |
|
||
|
||
### 前端关键依赖
|
||
|
||
| 依赖 | 用途 |
|
||
|------|------|
|
||
| `next` | React 框架 |
|
||
| `swr` | 数据请求与缓存 |
|
||
| `tailwindcss` | CSS 样式 |
|
||
|
||
### LatentSync 关键依赖
|
||
|
||
| 依赖 | 用途 |
|
||
|------|------|
|
||
| `torch` 2.5.1 | PyTorch GPU 推理 |
|
||
| `diffusers` | Latent Diffusion 模型 |
|
||
| `accelerate` | 模型加速 |
|