Duix-Avatar 开源数字人本地部署指南：从克隆代码到跑通第一条口播视频-编程实验室

Duix-Avatar 开源数字人本地部署指南：从克隆代码到跑通第一条口播视频

【免费下载链接】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 是一款完全开源的 AI 数字人工具包：上传一段短视频即可克隆你的形象和声音，再输入文字就能自动生成口播视频，全程本地离线完成。本文带你确认部署条件、跑通 Docker 服务端与客户端、完成首次验证，并处理最常见的启动故障。

🎬 三个真实场景：从个人博主到企业数字员工

自媒体口播博主：你写了文案但不想出镜、不想反复配音。把文案交给克隆好的数字人，直接产出口型匹配的视频。
企业培训与运营团队：需要批量制作产品讲解、制度宣导类视频。同一数字人换文案重复生成，不占拍摄排期。
虚拟主播 / 直播筹备：提前离线生成素材视频，内容数据不经过任何外部服务器，发布前可反复修改。

三者的共同点：形象、声音、文案都在你自己的机器上处理，隐私和数据可控。

📋 部署条件清单：先核对这 6 项

部署前逐项确认，缺一项后续都会卡住：

项目	硬性要求
操作系统	Windows 10（19042 及以上）或 Ubuntu 22.04
显卡	NVIDIA 显卡，且驱动正确安装（全部算力跑在本地 GPU 上）
内存	32G 及以上；16G 可能导致服务启动失败
磁盘	系统盘 100G 以上空闲（存 Docker 镜像，首次下载约 70G）；Windows 另需 D 盘 30G 以上存数字人和作品
软件	Docker（Windows 用 Docker Desktop，Linux 用 docker.io）、Git
驱动验证	终端执行`nvidia-smi`能显示显卡型号和驱动版本

Windows 下 Docker 镜像和数据的存放位置可在 Docker Desktop 设置中调整，确保目标盘空间充足：

⚙️ 四步部署流程：从克隆代码到工作台启动

步骤 1：获取项目代码

做什么：把仓库拉取到本地，进入项目目录。

怎么做：

git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatar

怎样算成功：目录下能看到deploy/、src/、README_zh.md等文件。

步骤 2：准备 Docker 并验证 GPU

做什么：安装并启动 Docker，确认容器能调用显卡。Windows 用 Docker Desktop（基于 WSL）；Ubuntu 执行sudo apt install docker.io docker-compose，并安装 NVIDIA 驱动与 NVIDIA Container Toolkit（它让 Docker 容器可以访问显卡）。

怎么做：在终端执行：

nvidia-smi docker --version

怎样算成功：nvidia-smi输出显卡型号、显存和驱动版本，且无报错。网络环境拉取镜像慢时，可先在 Docker 配置中加入镜像源，见下文故障速查。

步骤 3：启动服务端三个容器

做什么：一键启动语音识别（ASR）、语音合成（TTS）、视频合成三个服务，配置文件位于 deploy/docker-compose.yml。

怎么做：

cd deploy docker-compose up -d

不同环境对应不同配置：Linux 用docker-compose -f docker-compose-linux.yml up -d，RTX 50 系列显卡用docker-compose -f docker-compose-5090.yml up -d，显存吃紧可换轻量版docker-compose -f docker-compose-lite.yml up -d（仅视频合成一个服务）。

怎样算成功：docker ps显示 3 个服务（轻量版 1 个）状态为 Running。首次拉取镜像约 70G，耗时取决于网速，官方提示约半小时。

关键配置项（在 compose 文件中按需调整）：

GPU 资源分配与内存上限
数据挂载路径（数字人、作品、音频的存放目录）
端口映射：视频合成接口 8383、语音服务 18180，客户端通过127.0.0.1调用

步骤 4：安装客户端并连接工作台

做什么：客户端是 Electron 桌面应用，从项目官方构建产物下载对应安装包。Windows 双击Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 下载Duix.Avatar-x.x.x.AppImage直接运行（root 用户需加--no-sandbox参数）。

怎样算成功：客户端打开，弹出用户协议，进入工作台首页。

✅ 验收部署并跑通最小闭环：克隆一个形象，生成一条视频

部署成功的三个标志：

docker ps中三个服务均为 Running；
客户端工作台正常加载，无连接报错；
"My Avatars / My Works" 区域可见（初始为空）。

然后完成一次最小闭环体验：

同意用户协议，进入创作界面。
Create Avatar：上传一段约 10 秒的视频。注意画面里人脸清晰，且必须有人在说话——声音会被用于克隆，静音视频会直接报错。
等待训练完成，数字人形象出现在列表中。
Create Video：选择该数字人，输入文案，提交生成。
任务完成后在作品列表下载视频，检查口型与声音。

从上传素材到成片，全程不需要联网。

🛠️ 三个高频故障：快速速查问答

问：docker-compose up -d拉镜像超时，报net/http: request canceled或context canceled？

定位方法：这是 Docker Hub 官方源连接不稳定的典型表现。打开 Docker Desktop 的 Docker Engine 设置，在 JSON 中加入registry-mirrors镜像源数组（镜像源会随时间失效，自行检索最新可用地址），点 Apply & restart，然后重新执行docker-compose up -d。

问：创建数字人时报错file not exists或Connection refused？

两个独立原因，分别排查：