⚠️ 部署前必须确认的硬性条件

在开始之前，请逐项核对，任何一项不满足都无法成功运行：

  • NVIDIA 显卡（必须）：项目没有纯 CPU 模式，所有 AI 服务都强制要求 NVIDIA GPU 加速。推荐 RTX 4070 或更高；RTX 50 系（如 5090）有专门的优化镜像，30/40 系在 CUDA 12.8 环境下也可使用 5090 方案。
  • 内存 32GB 以上（必须）：官方明确标注 32GB 是“必要”条件，用于视频帧缓冲。
  • C 盘剩余空间 >100GB：用于存放 Docker 镜像。如果 C 盘空间不足，需要在 Docker 设置里把“Disk image location”改到其他盘。
  • D 盘剩余空间 >30GB：用于存放数字人模型、作品等数据。Windows 用户如果没有 D 盘，需要用 subst 命令临时挂载一个虚拟盘符。
  • 网络流量约 70GB：完整版镜像拉取会消耗大量流量，建议使用 WiFi。

🖥️ 方式一：Windows 部署（最常用）

Windows 用户需要先安装 WSL2 和 Docker Desktop。

第一步：安装 WSL2 和 Docker Desktop

  1. 以管理员身份打开 PowerShell，运行 wsl --list --verbose 检查 WSL 状态。如果没有安装，运行 wsl --install。
  2. 务必运行 wsl --update 更新内核，以兼容 NVIDIA 容器运行时。
  3. 下载并安装 Docker Desktop for Windows，安装后启动 Docker，接受协议并跳过登录。

第二步：配置 D 盘（如果没有）

如果你没有 D 盘，在 C 盘新建一个文件夹（如 C:\DuixData），然后在命令行执行：

1
subst D: C:\DuixData

注意：这个映射重启后会失效，每次重启电脑后需要重新执行一次。

第三步：启动服务端

进入项目目录，执行 Docker Compose 命令。如果你只有一块显卡，推荐使用“Lite”版本，它只启动视频生成服务，镜像体积更小：

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

如果你需要完整的语音克隆功能，则运行完整版（会拉取约 70GB 的镜像）：

1
docker-compose up -d

等待下载和启动完成（可能半小时以上）。用 docker ps 看到容器处于 Up 状态即表示成功。

第四步：安装客户端

从 GitHub Releases 下载 Duix.Avatar-x.x.x-setup.exe，双击安装，然后启动客户端即可开始制作。

🐧 方式二：Ubuntu 22.04 部署

项目对 Ubuntu 22.04 进行了完整验证，理论上支持其他桌面 Linux，但未经测试。

第一步：安装 Docker 和 NVIDIA 驱动

1
2
3
4
5
6
# 安装 Docker
sudo apt update
sudo apt install docker.io docker-compose

# 安装 NVIDIA 驱动（参考官方文档），然后验证
nvidia-smi  # 能显示显卡信息即成功

第二步：安装 NVIDIA Container Toolkit

这是 Docker 调用 GPU 的必要工具：

1
2
3
4
5
6
7
8
9
10
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
  && curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add - \
  && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置 Docker 使用 NVIDIA runtime 并重启
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

第三步：启动服务端

1
2
cd /deploy
docker-compose -f docker-compose-linux.yml up -d

Linux 版本的数据目录默认使用 ~/duix_avatar_data/，无需 D 盘。

第四步：安装客户端

下载 Linux 版 .AppImage 文件，赋予执行权限后运行。如果你是以 root 用户进入桌面，需要加 --no-sandbox 参数：

1
2
chmod +x Duix.Avatar-x.x.x.AppImage
./Duix.Avatar-x.x.x.AppImage --no-sandbox

🔧 服务端架构与验证

Duix.Avatar 的服务端由三个 Docker 容器组成，分别负责不同任务：

服务 端口 职责
TTS（语音合成） 18180 声音克隆与文字转语音
ASR（语音识别） 10095 音频转文字（Lite 版不包含）
Video Gen（视频生成） 8383 口型同步视频合成

启动后，你可以用 curl 快速验证服务是否正常：

1
curl http://127.0.0.1:8383/easy/query?code=test

💡 几个值得注意的细节

  • RTX 50 系用户：请使用 docker-compose-5090.yml，它基于 CUDA 12.8 和 PyTorch 预览版，也兼容 30/40 系。
  • WSL2 内存限制：如果视频生成时崩溃，可能是 WSL2 默认内存上限太低。可以在用户目录创建 .wslconfig 文件，手动分配更多内存（如 memory=32GB）。
  • API 仅限本地：所有服务绑定在 127.0.0.1，没有任何认证机制，切勿将端口暴露到公网。

你的显卡型号是什么？如果是 40 系或更早，用标准版镜像即可；如果是 50 系，记得换用 5090 专用的 compose 文件，能避开不少兼容性问题。