在构建 MuseTalk 实时语音系统 的过程中，我们遇到了一个困扰多日的部署难题。系统架构如下：

  • 前端页面部署在 runpod 提供的 Linux 云服务器；

  • WebRTC 信令服务器同样运行在这台云服务器上；

  • 后端音视频WebRTC 推流与 AI 推理服务运行在一台安装 Docker Desktop 的 Windows 主机中。

在这一架构下，信令交换完全正常，但 WebRTC 始终卡在 ICE 候选协商的“最后一步”，连接状态从 checking 直接进入 failed，无法进入 connected。

经过多轮排查，我们最终定位到问题根因，并通过调整部署方式彻底解决了这一问题。

问题核心：ICE 停留在 checking → failed

WebRTC 的信令流程完整走通：
createOffer → createAnswer → ICE Candidate 交换均无异常。

但 ICE 连接状态始终停留在：

iceConnectionState: checking → failed

这表明双方候选地址的网络层协商失败，P2P 通道无法建立。

根因分析：Windows + Docker Desktop 网络限制

1. Docker Desktop NAT 网络导致候选地址不可达

在 Windows 环境中运行的 Docker Desktop 默认使用 NAT 桥接网络（例如 172.17.0.X 段）。由此产生几个问题：

  • 容器内 WebRTC 模块暴露的候选地址为私有 IP，外部无法访问；

  • 端口映射（如 -p 40010:8812）仅适用于 TCP，不满足 WebRTC 的 UDP 动态端口需求；

  • Windows 环境下 Docker Desktop 不支持 --network host，容器无法直接共享宿主机网络栈。

结论：在 Docker Desktop 环境中运行的 WebRTC 容器，候选地址始终不可达，ICE 无法打通。

2. 仅使用 Google STUN，未配置 TURN 中继

当前的 ICE 服务器配置为：

iceServers: [
  { urls: "stun:stun.l.google.com:19302" }
]

STUN 服务器只能帮助节点获知自身的公网 IP，但不能提供中继服务。由于：

  • 一端位于云服务器（可能是对称 NAT）；

  • 一端运行在 NAT 内部的 Windows Docker 容器；

STUN 穿透失败是大概率事件。在没有 TURN 中继的情况下，候选协商自然会失败。

环境搭建步骤

Step 1. 安装 WSL2 + Ubuntu

在 PowerShell 或 CMD 执行：

wsl --install
wsl --install -d Ubuntu

安装完成后，重启系统并进入 Ubuntu 终端。

Step 2. 安装 Docker CE

进入 Ubuntu，运行：

# 使用 Aliyun 镜像加速
sudo curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

# 启动 Docker 服务
sudo service docker start

验证安装：

docker version
docker run hello-world

Step 3. （可选）配置 GPU 支持

# 添加 NVIDIA GPG key
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

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

sudo systemctl restart docker

测试 GPU 是否可用：

docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

Step 4. 拉取并运行容器

# 拉取镜像
sudo docker pull docker.io/xxx/musetalk:v2.0.1

# 使用 host 网络运行容器
sudo docker run --gpus all --network host xxx/musetalk:v2.0.1

关键点在于 --network host，这允许容器直接使用宿主网络，暴露真实公网 IP 与 UDP 端口。

调试与维护命令

进入容器：

sudo docker exec -it <container_id> bash

安装工具（可选）：

apt-get update && apt-get install -y nano vim

查看容器日志：

sudo docker logs -f <container_id>

该命令可实时查看 WebRTC 信令交换、候选协商等日志，方便调试。

原理解析：为什么 WSL2 + --network host 有效？

  1. 避免 NAT 网络隔离
    Docker Desktop 容器生成的候选地址为私有 IP，前端无法访问。WSL2 + host 网络让容器直接使用宿主网络，候选地址即为真实公网地址。

  2. 暴露真实 IP 与端口
    在 --network host 模式下，STUN 服务器能返回容器的真实公网地址，候选可达。

  3. 支持 UDP 与动态端口
    WebRTC 媒体通道使用 UDP 且端口随机，host 网络无需额外映射即可工作。

  4. 与 STUN 配合完成协商
    有效候选被成功交换后，ICE 状态顺利进入 connected，P2P 通道建立。

总结

Docker Desktop 在 Windows 环境下的 NAT 网络模型，无法满足 WebRTC 的候选地址可达性和 UDP 通道要求，是 ICE 连接失败的根本原因。通过 WSL2 + Docker CE + --network host，容器能够共享宿主网络，暴露真实公网 IP 和 UDP 端口，从而成功打通 ICE 协商，完成 WebRTC 建连。

这一经验不仅适用于 MuseTalk，也对所有需要 WebRTC 容器化部署 的场景具有参考价值。如果未来需要进一步提升稳定性，可以考虑部署 TURN 服务器作为备选方案。