MACA 环境下 torchrun 端口绑定问题报告

环境信息

| 组件 | 版本/信息 |
| --------- | ------------------------------------------------------------ |
| 基础镜像 | cr.metax-tech.com/public-ai-release/maca/deepspeed:0.16.5-maca.ai3.2.1.5-torch2.6-py312-ubuntu22.04-amd64 |
| MACA 版本 | 3.2.1 (/opt/maca-3.2.1) |
| PyTorch | 2.6 |
| Python | 3.12 |
| DeepSpeed | 0.16.5 |
| 硬件 | 8x MetaX MXC500 GPU (64GB each) |
| 操作系统 | Ubuntu 22.04 |

问题描述

在 Docker 容器中使用 torchrun 启动多 GPU 分布式训练时，所有 worker 进程在 rendezvous 阶段报告 EADDRINUSE 错误，即使指定的端口实际上并未被占用。

复现步骤

启动 Docker 容器（使用 --network host 或默认桥接网络均可复现）
运行以下命令启动 8-GPU 训练：

torchrun --nproc_per_node=8 --master_port=29500 \
    -m llamafactory.cli train /tmp/train_config.yaml

错误日志

RuntimeError: The server socket has failed to listen on any local network address.
    port: 29500
    useIpv6: 0
    code: -98
    name: EADDRINUSE
    message: address already in use

完整堆栈：

Traceback (most recent call last):
  File "/opt/conda/lib/python3.12/site-packages/torch/distributed/elastic/rendezvous/c10d_rendezvous_backend.py", line 79, in _create_tcp_store
    store = TCPStore(
  ...
torch.distributed.elastic.multiprocessing.errors.ChildFailedError:
============================================================
llamafactory.cli FAILED
------------------------------------------------------------
Failures:
  <NO_OTHER_FAILURES>
------------------------------------------------------------
Root Cause (first observed failure):
  rank: 5 (local_rank: 5)
  error_file: /tmp/torchelastic_xxx/xxx/attempt_0/5/error.json
  exitcode: 1
  ...
============================================================

关键观察

端口实际未被占用：在宿主机上使用 ss -tlnp | grep 29500 和 lsof -i :29500 均未发现任何进程监听该端口
多端口测试均失败：尝试了 29500、29600、30028、39500 等多个端口，均报告相同错误
不同网络模式均失败：
--network host 模式：失败
默认桥接网络模式：失败
错误发生在多个 rank：不同运行中，首次失败的 rank 不固定（观察到 rank 1, 2, 5, 6 等）
对比测试：
❌ torchrun --nproc_per_node=8 → 失败 (EADDRINUSE)
✅ FORCE_TORCHRUN=1 llamafactory-cli train → 成功
✅ 单 GPU 训练 → 成功

工作绕过方案

使用 LLaMA-Factory 内置的 FORCE_TORCHRUN 环境变量替代直接调用 torchrun：

export FORCE_TORCHRUN=1
export NNODES=1
export RANK=0
export MASTER_ADDR=127.0.0.1
export MASTER_PORT=29500
llamafactory-cli train /tmp/train_config.yaml

此方式可正常完成 8-GPU 分布式训练。

可能原因推测

MACA/MXCCL 与 PyTorch TCPStore 的兼容性问题：可能在初始化 NCCL backend 时，MXCCL 驱动层与 TCPStore 的端口绑定逻辑存在冲突
多进程启动时序问题：torchrun 的 elastic agent 在快速启动多个 worker 时，可能因 MACA 环境的特殊初始化导致端口状态检测异常
Socket 资源释放延迟：MACA 驱动可能导致 socket 资源释放存在延迟，使得后续进程误判端口状态

建议排查方向

检查 MXCCL 初始化过程中是否有预占用端口的行为
对比原生 CUDA 环境下 torchrun 的行为差异
检查 /opt/maca/lib/libmxccl_21605plugin.so 加载时的网络相关操作