3分钟解决HeyGem.ai Docker部署90%问题：从踩坑到上线全指南

你还在为HeyGem.ai项目的Docker部署头疼吗？服务启动失败、镜像拉取超时、GPU资源无法调用？本文汇总开发者最常遇到的部署难题，结合官方配置文件与实战经验，提供可直接操作的解决方案，让你快速完成本地AI模型服务搭建。

环境准备与配置检查

部署前需确认系统满足基础要求：NVIDIA显卡（显存≥8GB）、Docker Engine 20.10+、nvidia-docker工具包。通过以下命令验证环境：

docker --version && nvidia-smi

项目提供多平台Docker配置文件，Linux用户优先使用deploy/docker-compose-linux.yml，Windows用户使用deploy/docker-compose.yml。配置文件采用三服务架构：

• duix-avatar-tts：语音合成服务
• duix-avatar-asr：语音识别服务
• duix-avatar-gen-video：视频生成主服务

服务间通过ai_network桥接网络通信，需确保端口8383/10095/18180未被占用。

镜像拉取失败解决方案

现象：执行docker-compose up -d时出现超时错误，提示无法连接registry-1.docker.io

解决方案：

1. 配置国内Docker镜像源，编辑/etc/docker/daemon.json：

{
  "registry-mirrors": [
    "https://docker.zhai.cm",
    "https://atomhub.openatom.cn",
    "https://docker.m.daocloud.io"
  ]
}

2. 重启Docker服务使配置生效：

sudo systemctl daemon-reload && sudo systemctl restart docker

完整配置示例可参考doc/常见问题.md中的国内镜像配置方案

服务启动异常排查流程

步骤1：检查服务运行状态 执行docker-compose ps查看三个服务是否均为"Up"状态。若出现"Restarting"或"Exit"状态，通过日志定位问题：

docker logs duix-avatar-gen-video --tail 50

步骤2：GPU资源配置验证 确保docker-compose文件中正确配置GPU资源，Linux环境示例：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

配置文件路径：deploy/docker-compose-linux.yml

步骤3：存储路径权限设置 服务需要读写本地数据目录，Windows环境默认路径：

volumes:
  - d:/duix_avatar_data/face2face:/code/data

Linux环境需修改为用户可访问路径：

volumes:
  - ~/duix_avatar_data/face2face:/code/data

常见错误案例与修复方案

案例1：ASR服务连接拒绝

错误日志：ConnectionRefusedError: [Errno 111] Connection refused

原因：语音识别服务启动较慢（约3-5分钟），需等待服务初始化完成。16GB内存环境可能因资源不足导致启动失败。

解决方案：

1. 增加系统交换分区：

sudo fallocate -l 8G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

2. 调整服务启动顺序，在docker-compose.yml中添加依赖关系：

depends_on:
  - duix-avatar-asr

案例2：CUDA内存分配失败

错误特征：视频生成服务频繁重启，日志含CUDA out of memory

修复方案：修改环境变量限制内存分配粒度：

environment:
  - PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

配置位置：deploy/docker-compose.yml#L49

部署验证与功能测试

服务正常启动后，访问http://localhost:8383验证API可用性。通过客户端工具发送测试请求：

curl -X POST http://localhost:8383/api/generate -d '{"text":"Hello World"}'

若返回视频生成任务ID，表明部署成功。完整API文档可参考src/main/api/目录下的接口定义文件。

性能优化建议

1. 资源调配：在docker-compose.yml中调整shm_size参数（建议设置为8G）：

shm_size: '8g'

2. 服务瘦身：使用轻量配置文件减少资源占用：

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

3. 定期更新：通过以下命令获取最新镜像：

docker-compose pull && docker-compose up -d

总结与后续维护

HeyGem.ai的Docker部署核心在于正确配置GPU资源、网络和存储路径。遇到问题时，优先查阅doc/常见问题.md和服务日志。社区活跃期（前3个月）建议每周更新一次镜像以获取最新修复。

项目许可协议：[Duix.Avatar model community Licensing Agreement_zh.pdf](https://gitcode.com/GitHub_Trending/he/HeyGem.ai/blob/9e0f12debda413540bbb9d0d6d8f8d10c575a53b/Duix.Avatar model community Licensing Agreement_zh.pdf?utm_source=gitcode_repo_files)

部署过程中遇到的新问题，可通过项目Issue系统反馈，维护团队通常会在48小时内响应。下期将带来"模型自定义训练全流程"，敬请关注。