Duix.Avatar 数字人视频合成部署教程：本地 Docker 一键跑通的完整指南
【免费下载链接】Duix-Avatar🚀 Truly open-source AI avatar(digital human) toolkit for offline video generation and digital human cloning.项目地址: https://gitcode.com/GitHub_Trending/he/Duix-Avatar
Duix.Avatar 是一个开源的数字人视频合成工具：上传一段十几秒的说话视频，它就能克隆出你的形象和声音，之后输入文案就能生成你"出镜"的口播视频。它解决的核心问题是——不想露脸、没有预算请拍摄团队，但仍要产出真人出镜的视频。整条链路全部跑在你自己的电脑上，不依赖任何在线服务。照着本文操作，你能把 Docker 服务端和桌面客户端完整装好，并成功克隆出第一个数字人模特。
先看这里
Duix.Avtar 的部署形态是本地 Docker 服务端 + 桌面客户端：服务端是三个 Docker 容器（ASR、TTS、视频合成），客户端负责上传素材、下发任务，通过127.0.0.1的本地端口调用服务端。没有云服务器参与，你的视频和声音素材不会离开这台机器。首次拉取镜像约消耗 70GB 流量，请连 WiFi 再开始。
环境摸底：硬件不达标就别硬跑
| 项目 | 最低 | 推荐 |
|---|---|---|
| 操作系统 | Windows 10 19042.1526 或更高 | Windows 10/11 64 位，或 Ubuntu 22.04 Desktop |
| 内存 | 16GB（可能起不来，勉强线） | 32GB 及以上 |
| 磁盘 | 存储 Docker 镜像的分区剩余 100GB，另留 30GB 存数据 | 200GB 可用 |
| 显卡 | NVIDIA 独显 + 官方驱动 | RTX 4070 或同级别 |
| 前置组件 | WSL（Windows 装 Docker 需要） | WSL 已更新到最新 |
⚠️ 最容易卡住的点：没有 NVIDIA 显卡或驱动没装好，三个容器一个都起不来。这个项目所有算力都在本地，没有云端兜底，先用
nvidia-smi确认显卡信息能正常输出，再往下走。
准备物清单
- NVIDIA 显卡驱动- 显卡能被 Docker 调用的前提，去 NVIDIA 官网驱动查询页下载
- WSL- Windows 上运行 Docker Desktop 的底层环境
- Docker Desktop- 负责拉取镜像并运行三个服务端容器，去 Docker 官网下载对应系统版本
- 客户端安装包- Duix.Avtar 官方构建的安装包（Windows 为
Duix.Avatar-x.x.x-setup.exe，Linux 为.AppImage），从项目 Releases 页下载
以下部署步骤以 Windows 为主线，Ubuntu 的差异在对应步骤里单独标注。
动手部署
1. 🔧 验证显卡驱动和 WSL 就绪
在终端执行下面的命令，确认显卡驱动和 WSL 都没问题：
nvidia-smi wsl --updatenvidia-smi能打印出显卡型号和驱动版本，wsl --update无报错，这一步就算通过。
- 高频坑：
nvidia-smi提示命令不存在，说明驱动压根没装，先回驱动官网装好再继续，后面所有步骤都会卡在这里。
2. 🔧 拉取项目代码
克隆仓库到本地，得到部署所需的 deploy/docker-compose.yml 等文件：
git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatar完成后你会在本地多出一个Duix-Avatar目录，deploy子目录就是后面所有启动命令的出发点。
- 高频坑：网络中断导致克隆失败，删掉目录重试即可，仓库不大。
3. 🔧 调整 Docker 资源并移动磁盘镜像位置
打开 Docker Desktop，进入 Settings → Resources → Advanced，把磁盘镜像位置（Disk image location）改到剩余空间大于 100GB 的分区，点 Apply & restart 生效：
如果 C 盘空间足够也可以跳过这一步，改完记得分配给 Docker 的内存至少 16GB。
- 高频坑：C 盘剩余不足 100GB 又不改路径，后面拉镜像会直接报磁盘空间错误，提前挪好最省心。
4. 🔧 配置 Docker 镜像加速器
拉取 70GB 镜像前，先给 Docker 配上国内镜像源。进入 Settings → Docker Engine，在 JSON 配置中加入registry-mirrors：
{ "registry-mirrors": [ "https://hub.littlediary.cn", "https://hub.rat.dev", "https://docker.m.daocloud.io", "https://docker.1ms.run" ] }点 Apply & restart 后重新拉取。
- 高频坑：镜像源存活状态随时变化，拉取超时说明该源失效了，去搜索最新的可用源替换即可，这不是你的配置写错了。
5. 🔧 启动三个服务端容器
在deploy目录执行启动命令，首次运行会在后台拉取全部镜像，大约半小时，耐心等：
cd deploy docker-compose up -dDocker 的容器列表里出现Duix.Avatar-asr、Duix.Avatar-tts、Duix.Avatar-gen-video三个服务且状态都是 Running，服务端就算就绪。想要更省资源的 lite 版，改用docker-compose -f docker-compose-lite.yml up -d启动，只有一个容器；Ubuntu 用户改用docker-compose -f docker-compose-linux.yml up -d。
- 高频坑：容器反复重启，九成是显存或内存不足，优先换 lite 版验证环境。
6. 🔧 安装客户端并连上服务端
下载官方构建的客户端安装包：Windows 双击Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 双击.AppImage直接运行，root 用户桌面需追加--no-sandbox参数启动。
启动客户端后它会连接本机127.0.0.1上的服务端，首页能正常加载内容即说明链路打通。
- 高频坑：客户端打开后一片空白或报错，回来看 Docker 里三个容器是否都还在 Running。
跑通确认：三条全过才算部署成功
- 打开客户端，看到首页的"创建视频"和"快速定制"两个卡片，作品列表正常显示，说明客户端与服务端通信正常。
回到 Docker，确认三个容器全部保持 Running，没有反复重启的容器。
做一次真实小测试：进入"快速定制"，上传一段 10 秒左右、本人出镜说话的清晰视频，完成模特创建。训练走完了声音克隆和形象建模全流程，出结果即代表整条链路可用。
以上三条全部通过，才算部署成功。
遇到问题先查这里
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| 容器拉取失败，报 registry-1.docker.io 超时 | 官方源不通或网络不稳定 | 按第 4 步配好镜像加速器，重启后重新docker-compose up -d |
| 服务起不来或反复重启 | 无 NVIDIA 显卡/驱动，或内存不足 | 先跑nvidia-smi；内存紧张改用 lite 版启动 |
| 定制模特报 Connection refused | ASR 服务启动慢，服务端刚起来就连了 | 启动完成后等几分钟再操作，别立刻提交任务 |
| 上传视频无法创建模特 | 视频里没有人声 | 换一段本人在说话的清晰视频，声音克隆必须依赖人声 |
| 端口被占用 | 本机 8383、18180 等端口已被其他程序占用 | 修改 deploy/docker-compose.yml 中对应容器的端口映射 |
日志和状态排查就两条命令，在deploy目录下执行：
docker-compose ps docker-compose logs客户端侧的报错日志可以在客户端设置菜单的"打开日志"里查看，具体排查思路见 doc/常见问题.md。
到这里，服务端三个容器 Running、客户端首页能打开、第一个模特也创建成功了，Duix.Avtar 已经在你电脑上完整跑通。下一步建议直接进首页"创建视频"，输入一段文案，生成你的第一条数字人口播视频；想把它接入自己的系统，README_zh.md 里的开放 API 一节列出了模型训练、音频合成和视频合成的本地接口。
【免费下载链接】Duix-Avatar🚀 Truly open-source AI avatar(digital human) toolkit for offline video generation and digital human cloning.项目地址: https://gitcode.com/GitHub_Trending/he/Duix-Avatar
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
