xiaoxia-saas/deploy/gpu_worker/README.md

MuseTalk GPU Worker — 部署指南

本目录包含 RTX2060 本地电脑上运行的 GPU Worker 脚本。 Worker 采用 反向轮询模式：主动向 SaaS API 拉取待处理的口型同步任务 → 调用本地 MuseTalk 推理 → 把结果视频回传到 SaaS。不需要内网穿透。

目录文件

文件	作用
gpu_worker.py	Worker 主程序（单文件，零项目代码依赖，仅依赖 requests）
requirements.txt	Python 依赖（只有 requests）
xiaoxia-gpu-worker.service	systemd 服务单元（开机自启、异常自动重启）
.env.example	环境变量样例，复制为 .env 后填入真实值

一、环境准备

1. Python 3.10+（Windows 建议从 python.org 安装；Linux 自带）
2. 本地 MuseTalk 服务 已启动在 http://127.0.0.1:7861，health 接口返回 {"status":"ok","free_vram_mb":...}
3. ffmpeg（可选，用于读取输出视频时长；未装则 duration 报 0，不影响功能）
4. 网络能访问 staging / 生产 API（curl https://staging-api.xiaoxiajianji.com/health 应返回 {"status":"healthy"}）

二、部署步骤（Linux，推荐 systemd）

# 1. 创建部署目录
sudo mkdir -p /opt/xiaoxia-gpu-worker
sudo chown $USER:$USER /opt/xiaoxia-gpu-worker
cd /opt/xiaoxia-gpu-worker

# 2. 拷贝脚本和依赖
cp /path/to/deploy/gpu_worker/{gpu_worker.py,requirements.txt,xiaoxia-gpu-worker.service,.env.example} .
cp .env.example .env
#    编辑 .env，填入 API_BASE_URL 和 GPU_WORKER_TOKEN

# 3. 创建虚拟环境并安装依赖
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

# 4. 前台先跑一次，确认日志正常
./venv/bin/python gpu_worker.py
#    看到 "MuseTalk 健康检查通过" 和 "注册/心跳" 成功即可 Ctrl+C 退出

# 5. 安装 systemd 服务
sudo cp xiaoxia-gpu-worker.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now xiaoxia-gpu-worker

# 6. 查看日志
sudo journalctl -u xiaoxia-gpu-worker -f

三、部署步骤（Windows，快速测试）

:: 创建虚拟环境
python -m venv venv
venv\Scripts\pip install -r requirements.txt

:: 复制并编辑 .env
copy .env.example .env
notepad .env

:: 运行
venv\Scripts\python gpu_worker.py

可在任务计划程序中添加开机启动项：程序选 venv\Scripts\python.exe，参数填 gpu_worker.py，起始目录填脚本所在目录。

四、SaaS 侧配套配置

SaaS 后端部署完成后需配置：

1. 服务端环境变量 GPU_WORKER_TOKEN 设为一个随机强 Token（和 Worker .env 中一致）
2. 数据库已跑迁移 081_add_gpu_lipsync_tasks（自动随 API 启动的 alembic upgrade head 完成）
3. OSS bucket 中 gpu-lipsync/results/ 路径可写（默认 bucket 已配）

五、验证联调

1. Worker 启动后日志看到 注册/心跳 成功
2. 后端调用 GpuLipsyncService.create_task(video_url=..., audio_url=...) 放入一条测试任务
3. Worker 在 5 秒内拉到任务，下载 → 推理 → 上传 → 上报
4. 后端 GET /api/v1/gpu/lipsync/status/{task_id} 返回 status=done，result_url 非空

六、故障排查

现象	可能原因 / 排查
日志 401 Invalid GPU worker token	.env 的 GPU_WORKER_TOKEN 与服务端不一致
日志 MuseTalk 健康检查未通过	本地 MuseTalk 没启动，或端口不是 7861；curl http://127.0.0.1:7861/health 验证
任务长时间不被拉取	Worker 和服务端连不上；检查 API_BASE_URL 是否可达、Token 是否正确
推理后上传 OSS 失败	本地出口网络被防火墙拦截 OSS 域名（oss-cn-hangzhou.aliyuncs.com）
服务端看到任务回退到 pending 重试	Worker 心跳超时（默认 5 分钟）；Worker 进程崩溃或推理卡死超过 5 分钟
日志 MuseTalk 推理超时	视频太长或显存不足；可临时调大 REQUEST_TIMEOUT，或限制输入视频时长

七、安全注意事项

• .env 包含长期 Token，文件权限设为 600（chmod 600 .env）
• Token 泄露要立即在服务端更换 GPU_WORKER_TOKEN 并重启 Worker
• Worker 只需要出站访问 SaaS API 和 OSS，不需要开放任何入站端口