PyTorch多机训练必须显式设置MASTER_ADDR和MASTER_PORT，因为init_process_group不自动发现主节点地址与端口，所有机器需能双向访问该地址端口且由rank 0监听，否则初始化卡住或报连接错误。
PyTorch多机训练为什么必须显式设置 MASTER_ADDR 和 MASTER_PORT
因为 torch.distributed.init_process_group() 默认不自动发现主节点地址和端口，跨机器通信必须明确知道谁是 rank 0（即 MASTER_ADDR）以及用哪个端口建立初始 TCP 连接（即 MASTER_PORT）。没设或设错会导致所有 worker 卡在初始化、报 ConnectionRefusedError 或超时退出。
常见错误现象：
-
RuntimeError: Address already in use—— 端口被占，但脚本没做冲突检测 -
Connection timed out——MASTER_ADDR写成本机127.0.0.1或内网不可达地址 - 某台机器能连上，另一台连不上 —— 防火墙/安全组只放行了部分 IP 的
MASTER_PORT
关键点：所有机器必须能双向访问 MASTER_ADDR:MASTER_PORT，且该端口在 master 节点上处于监听状态（由 rank 0 进程主动 bind）。
怎么安全地动态探测可用端口（避免硬编码）
不能靠“试几个固定端口”应付，尤其在集群调度环境（如 Slurm、Kubernetes）中，端口竞争高。推荐在 master 节点（rank 0）启动前用 Python 自建探测逻辑，绑定成功后广播给其他 rank。
立即学习“Python免费学习笔记（深入）”；
实操建议：
- 用
socket.socket().bind(("", 0))让系统分配临时端口，再用.getsockname()[1]拿到实际端口号 - 务必在
rank == 0时执行，并通过文件或环境变量同步给其他 rank（别用 print + 手动复制） - 避免用
random.randint(20000, 65535)—— 概率撞上已占端口，且无法保证原子性
示例（master 节点 rank 0 启动前）：
import socket
import os
<p>def find_free_port():
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
s.bind(("", 0))
s.listen(1)
return s.getsockname()[1]</p><p>if int(os.environ["RANK"]) == 0:
port = find_free_port()</p><h1>写入共享路径，如 NFS 或 /tmp（需所有节点可读）</h1><pre class="brush:php;toolbar:false;">with open("/tmp/dist_port", "w") as f:
f.write(str(port))
os.environ["MASTER_PORT"] = str(port)else:
等待 master 写完
while not os.path.exists("/tmp/dist_port"):
time.sleep(0.1)
with open("/tmp/dist_port") as f:
os.environ["MASTER_PORT"] = f.read().strip()
MASTER_ADDR 应该填什么 —— 不是本机 IP，而是所有节点都能路由到的 master 主机名/IP
填错 MASTER_ADDR 是多机失败最常见原因。它不是当前机器的 IP，而是 rank 0 所在机器对外暴露的、其余 worker 能直接 telnet MASTER_ADDR MASTER_PORT 通的地址。
使用场景判断：
- 物理机集群：填 master 节点的**真实内网 IP**（如
192.168.1.10），不是127.0.0.1，也不是公网 IP（除非所有 worker 也走公网） - Kubernetes：填 headless service 的 DNS 名（如
pytorch-master.default.svc.cluster.local），或 service ClusterIP（需确保 network policy 允许 pod 间通信） - Slurm：用
scontrol show hostnames $SLURM_NODELIST | head -n1获取首节点 hostname，再host -i查对应 IP
验证方式（在任意 worker 节点执行）：
nc -zv $MASTER_ADDR $MASTER_PORT # 必须返回 succeeded，否则 init_process_group 必败
为什么不能依赖 os.environ.get("MASTER_PORT") 就直接用
因为 PyTorch 的 NCCL 后端对 MASTER_PORT 做了隐式字符串转整数处理，但如果环境变量是空字符串、非数字或带空格，会静默 fallback 到默认端口 29500 —— 导致你自以为用了动态端口，其实全在用 29500，然后撞车。
实操建议：
- 在调用
init_process_group前，强制校验并转换：int(os.environ["MASTER_PORT"])，加 try/except 报明确错误 - 不要在不同 rank 上分别探测端口 —— 只有 rank 0 探测并分发，否则各探各的，连接对不上
- NCCL 对端口敏感：即使端口空闲，若被占用过又快速释放（TIME_WAIT），仍可能触发
Address already in use；建议探测时加s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
端口和地址本身不难，难的是所有节点视角一致、网络可达、状态同步及时。少一个环节，init_process_group 就卡住不动，连日志都不打。
