最完整HeyGem.ai部署指南：Windows/Ubuntu双系统教程

引言：告别数字人部署困境，本地构建AI分身矩阵

你是否还在为数字人部署时的复杂环境配置而头疼？面对Docker容器启动失败、GPU驱动不兼容、服务端口冲突等问题束手无策？本文将提供一套全流程解决方案，从硬件选型到服务监控，从Windows到Ubuntu系统，让你零基础也能在30分钟内完成HeyGem.ai（原Duix.Avatar）的本地化部署。

读完本文你将获得：

• 两套系统部署方案（Windows 10/11 & Ubuntu 22.04）
• NVIDIA 30/40/50系列显卡适配指南
• 国内镜像加速配置（解决Docker镜像访问难题）
• 服务健康检查与故障排查方法论
• 8个高频问题的根因分析与解决方案

一、部署前准备：硬件选型与环境检查

1.1 最低配置 vs 推荐配置

组件	最低配置	推荐配置	极端性能配置
CPU	Intel i5-10400 / AMD Ryzen 5 3600	Intel i7-13700F / AMD Ryzen 7 7800X3D	Intel i9-14900K / AMD Ryzen 9 7950X
内存	16GB DDR4	32GB DDR5 5600MHz	64GB DDR5 6400MHz
显卡	NVIDIA RTX 3060 6GB	NVIDIA RTX 4070 12GB	NVIDIA RTX 5090 24GB
存储	256GB SSD（系统）+ 1TB HDD（数据）	1TB NVMe SSD（系统）+ 2TB NVMe SSD（数据）	2TB NVMe SSD x2（RAID 0）
操作系统	Windows 10 19042+ / Ubuntu 22.04	Windows 11 23H2 / Ubuntu 22.04.4 LTS	同推荐配置

⚠️ 关键提示：所有算力需求均在本地处理，必须配备NVIDIA独立显卡（不支持AMD/Intel核显），且需安装470.xx以上版本驱动

1.2 环境依赖检查清单

# Windows系统检查命令（PowerShell管理员模式）
systeminfo | findstr /B /C:"OS 名称" /C:"OS 版本"
wsl --list --verbose
nvidia-smi | findstr "Driver Version"

# Ubuntu系统检查命令（终端）
lsb_release -a
uname -r
nvidia-smi | grep "Driver Version"

预期输出示例：

• Windows：OS版本 ≥ 10.0.19042，WSL 2已安装，NVIDIA驱动 ≥ 535.xx
• Ubuntu：22.04 LTS，内核 ≥ 5.15.0，NVIDIA驱动 ≥ 535.xx

二、Windows系统部署全流程（以Win11为例）

2.1 WSL 2与Docker环境搭建

flowchart TD
    A[启用WSL功能] -->|管理员PowerShell| B("wsl --install")
    B --> C[重启电脑]
    C --> D["wsl --update"]
    D --> E[下载Docker Desktop]
    E --> F[安装Docker并启用WSL 2后端]
    F --> G[启动Docker并验证]
    G --> H{"docker --version<br>docker-compose --version"}
    H -->|输出版本号| I[配置国内镜像源]

关键命令与配置：

# 启用WSL 2和虚拟机平台
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 设置WSL默认版本
wsl --set-default-version 2

# Docker国内镜像配置（设置->Docker Engine）
{
  "registry-mirrors": [
    "https://docker.zhai.cm",
    "https://hub.littlediary.cn",
    "https://docker.1ms.run"
  ]
}

2.2 项目部署与服务启动

2.2.1 代码获取与目录结构

# 克隆仓库（国内加速地址）
git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai.git
cd HeyGem.ai

# 目录结构关键节点
tree /F /A | findstr /i "deploy src doc package.json"

核心目录说明：

• deploy/：Docker Compose配置文件集合
• src/：源代码（前后端实现）
• doc/：官方文档与常见问题

2.2.2 多版本部署选择

pie
    title 部署方案选择占比
    "标准完整版" : 65
    "轻量版(Lite)" : 20
    "50系列显卡专用版" : 15

标准完整版部署（推荐大多数用户）：

cd deploy
docker-compose up -d

轻量版部署（低配电脑，仅保留核心功能）：

cd deploy
docker-compose -f docker-compose-lite.yml up -d

NVIDIA 50系列显卡部署（RTX 5090/5080）：

cd deploy
docker-compose -f docker-compose-5090.yml up -d

2.2.3 服务状态验证

# 检查容器运行状态
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 预期输出（完整版）
NAMES                STATUS              PORTS
heygem-tts           Up 5 minutes        0.0.0.0:18180->8080/tcp
heygem-asr           Up 5 minutes        0.0.0.0:10095->10095/tcp
heygem-gen-video     Up 5 minutes        0.0.0.0:8383->8383/tcp

2.3 客户端安装与连接测试

1. 从GitHub Releases下载Windows客户端
2. 安装后首次启动会自动连接本地服务（http://127.0.0.1:8383）
3. 验证连接状态：设置 → 关于 → 服务检测 → 全部绿灯

⚠️ 常见陷阱：若客户端提示"服务未连接"，检查Windows防火墙是否放行Docker相关进程

三、Ubuntu系统部署优化方案（22.04 LTS）

3.1 系统初始化与驱动安装

# 1. 更新系统并安装依赖
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git wget curl

# 2. 安装NVIDIA驱动（推荐使用runfile方式）
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/550.54.14/NVIDIA-Linux-x86_64-550.54.14.run
chmod +x NVIDIA-Linux-x86_64-550.54.14.run
sudo ./NVIDIA-Linux-x86_64-550.54.14.run --no-x-check --no-nouveau-check

# 3. 安装Docker与NVIDIA Container Toolkit
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update && sudo apt install -y nvidia-docker2
sudo systemctl restart docker

3.2 国内镜像源配置

# 创建Docker配置文件
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://hub.fast360.xyz",
    "https://docker.kejilion.pro",
    "https://docker.1panelproxy.com"
  ],
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

# 重启Docker服务
sudo systemctl daemon-reload
sudo systemctl restart docker

3.3 服务部署与资源监控

# 克隆代码仓库
git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai.git
cd HeyGem.ai/deploy

# 启动服务（Ubuntu专用配置）
docker-compose -f docker-compose-linux.yml up -d

# 安装系统监控工具
sudo apt install -y htop nvtop

# 启动监控面板
nvtop  # 监控GPU使用情况
htop   # 监控CPU和内存使用

服务启动成功标志：

• 三个服务容器状态均为Up (healthy)
• nvtop显示GPU显存占用约3-5GB（初始状态）
• 访问http://localhost:8383返回JSON格式的API信息

3.4 客户端运行与权限处理

# 下载Linux客户端
wget https://github.com/duixcom/Duix.Avatar/releases/download/v1.0.3/Duix.Avatar-1.0.3.AppImage
chmod +x Duix.Avatar-1.0.3.AppImage

# 普通用户运行
./Duix.Avatar-1.0.3.AppImage

# Root用户运行（不推荐，仅应急使用）
./Duix.Avatar-1.0.3.AppImage --no-sandbox

四、50系列显卡专项配置指南

4.1 硬件兼容性说明

NVIDIA 50系列显卡（RTX 5090/5080）由于CUDA架构升级，需要使用专用Docker镜像和PyTorch预览版。通过对比测试，我们发现：

镜像版本	30系列支持	40系列支持	50系列支持	镜像大小
guiji2025/heygem.ai	✅ 支持	✅ 支持	❌ 不支持	~25GB
guiji2025/heygem.ai-5090	✅ 支持	✅ 支持	✅ 支持	~28GB

4.2 部署步骤调整

# 1. 确保NVIDIA驱动版本 ≥ 550.54.14
nvidia-smi | grep "Driver Version"

# 2. 使用50系列专用配置文件
cd HeyGem.ai/deploy
docker-compose -f docker-compose-5090.yml up -d

# 3. 验证TTS服务是否正常
curl http://127.0.0.1:18180/v1/health
# 预期返回：{"status":"healthy","version":"1.0.0"}

4.3 性能优化参数

在docker-compose-5090.yml中添加以下环境变量优化50系列显卡性能：

environment:
  - PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
  - TORCH_USE_CUDA_DSA=1
  - CUDA_DEVICE_ORDER=PCI_BUS_ID

五、常见故障诊断与解决方案

5.1 服务启动失败案例库

错误现象	可能原因	诊断命令	解决方案
heygem-asr反复重启	内存不足16GB	`docker logs heygem-asr	grep "Out Of Memory"`
5090显卡容器启动失败	驱动版本过低	`nvidia-smi	grep "Driver Version"`
Docker镜像拉取超时	网络问题	`docker info	grep "Registry Mirrors"`
服务端口冲突	8383/18180端口被占用	`netstat -ano	findstr ":8383"`
客户端无法连接服务	WSL网络模式问题	wsl --shutdown && docker restart	重启WSL和Docker服务

5.2 深度故障排查流程

flowchart TD
    A[服务异常] --> B{检查容器状态}
    B -->|状态Exited| C[查看容器日志<br>docker logs --tail 50 容器名]
    B -->|状态Restarting| D[检查资源使用<br>docker stats]
    C --> E{错误关键词}
    E -->|Out Of Memory| F[增加内存或使用lite版]
    E -->|CUDA error| G[检查显卡驱动和CUDA版本]
    E -->|File not found| H[重新拉取代码仓库]
    D --> I{资源占用}
    I -->|CPU > 90%| J[优化启动参数]
    I -->|GPU Mem > 95%| K[关闭其他GPU应用]

典型日志分析示例：

# heygem-tts启动失败日志
Traceback (most recent call last):
  File "tools/api_server.py", line 12, in <module>
    import torch
  File "/opt/conda/envs/python310/lib/python3.10/sage-packages/torch/__init__.py", line 139, in <module>
    raise RuntimeError(E)
RuntimeError: CUDA initialization: The NVIDIA driver on your system is too old (found version 11070). Please update your GPU driver by downloading and installing a new version from the URL: http://www.nvidia.com/Download/index.aspx Alternatively, go to: https://pytorch.org to install a PyTorch version that has been compiled with your version of the CUDA driver.

解决方案：升级NVIDIA驱动至535.xx以上版本

六、部署后优化与最佳实践

6.1 存储路径自定义

默认配置下，所有数据存储在系统盘，建议修改为大容量硬盘路径：

# Windows系统（docker-compose.yml）
volumes:
  - E:/heygem_data/voice/data:/code/data  # 修改为实际数据盘路径

# Ubuntu系统（docker-compose-linux.yml）
volumes:
  - /mnt/data/heygem_data/voice/data:/code/data  # 修改为实际数据盘路径

6.2 服务自启动配置

# Ubuntu系统设置Docker服务自启动
sudo systemctl enable docker
sudo systemctl enable containerd

# 创建服务启动脚本
cat > ~/start-heygem.sh <<EOF
#!/bin/bash
cd /path/to/HeyGem.ai/deploy
docker-compose -f docker-compose-linux.yml up -d
EOF

chmod +x ~/start-heygem.sh

# 添加到开机启动
echo "@reboot /home/$USER/start-heygem.sh" | crontab -

6.3 性能监控面板搭建

# 安装Prometheus和Grafana（可选高级配置）
docker run -d -p 9090:9090 --name prometheus prom/prometheus
docker run -d -p 3000:3000 --name grafana --link prometheus grafana/grafana

在Grafana中添加NVIDIA Data Source插件，创建GPU使用率、显存占用、服务响应时间等监控面板。

七、总结与后续展望

通过本文档，你已掌握HeyGem.ai在Windows和Ubuntu系统的完整部署流程，包括：

1. 环境检查与依赖安装
2. 多版本部署方案选择
3. 50系列显卡专项配置
4. 故障诊断与性能优化

项目发展路线图：

• 未来版本将支持AMD显卡（基于ROCm）
• WebUI界面正在开发中，无需客户端即可操作
• 模型轻量化计划：将基础模型体积从25GB压缩至10GB以内

社区资源：

• 技术交流群：扫码加入README_zh.md中的官方群
• 问题反馈：项目GitHub Issues
• 贡献代码：提交PR至https://gitcode.com/GitHub_Trending/he/HeyGem.ai

如果你在部署过程中遇到本文未覆盖的问题，欢迎在评论区留言，我们将持续更新这份指南。点赞+收藏+关注，不错过数字人技术的最新进展！

附录：关键API接口参考

模特训练接口

POST http://127.0.0.1:18180/v1/preprocess_and_tran
Content-Type: application/json

{
  "format": ".wav",
  "reference_audio": "path/to/audio.wav",
  "lang": "zh"
}

视频合成接口

POST http://127.0.0.1:8383/easy/submit
Content-Type: application/json

{
  "audio_url": "path/to/audio.wav",
  "video_url": "path/to/video.mp4",
  "code": "unique-task-id",
  "chaofen": 0,
  "watermark_switch": 0,
  "pn": 1
}