搭建本地Ray集群时出现GrpcUnavailable错误求助

核心问题分析 #

你遇到的GrpcUnavailable错误，本质是WSL2实例的网络映射问题——虽然手动转发了端口，但Ray节点间通信需要的所有内部端口可能未正确暴露，或者WSL2的实际绑定地址不是外部可访问IP，导致节点间gRPC通信链路断裂。

分步解决方案 #

1. 修正头节点启动的--node-ip-address参数 #

WSL2默认使用内部虚拟IP，即使转发了端口，Ray头节点仍可能绑定到该内部IP，导致外部节点无法通过MY_IP访问服务。启动头节点时必须指定Windows主机的对外可访问IP（或WSL2桥接模式下的桥接IP）：

ray start --head --port 6379 --ray-client-server-port 10001 --redis-shard-ports 20000,20001,20002,20003,20004 --dashboard-port 8265 --node-manager-port 6380 --object-manager-port 6381 --worker-port-list=10000,10002,10003,10004 --dashboard-host 0.0.0.0 --node-ip-address=你的Windows主机局域网IP

替换你的Windows主机局域网IP为实际地址（如192.168.x.x），可通过Windows cmd的ipconfig或WSL2内的hostname -I获取。

2. 全端口连通性验证 #

在外部节点（Windows/Ubuntu）上用nc或telnet测试所有Ray依赖端口的连通性：

# 测试Redis主端口
nc -zv 头节点IP 6379
# 测试节点管理器端口
nc -zv 头节点IP 6380
# 测试对象管理器端口
nc -zv 头节点IP 6381
# 测试Redis分片端口（逐个验证）
nc -zv 头节点IP 20000
# 测试Ray客户端端口
nc -zv 头节点IP 10001
# 测试worker端口（逐个验证）
nc -zv 头节点IP 10000

若端口不通，针对性排查：

• Windows防火墙是否添加了对应端口的入站允许规则
• WSL2端口转发是否生效：Windows cmd执行netsh interface portproxy show all查看转发条目
• 头节点Linux防火墙（如ufw）是否开放端口：sudo ufw allow 6379/tcp，逐个添加所有需要的端口

3. 规范外部节点启动参数 #

外部节点启动时，除指定--address，额外添加--node-ip-address绑定自身对外可访问IP，避免Ray自动绑定回环地址：

ray start --address='头节点IP:6379' --node-ip-address=当前节点局域网IP

4. 版本兼容性调整（可选） #

Ray 1.13.0在WSL2环境下存在已知网络兼容性问题，可尝试升级到1.15+稳定版或降级到1.12.1版本：

# 升级到最新稳定版
pip install -U ray
# 或降级到1.12.1
pip install ray==1.12.1

5. 日志定位具体故障端口 #

若以上步骤无效，查看头节点GCS日志定位具体失败的RPC端口：

tail -f /tmp/ray/session_latest/logs/gcs_server.out

日志会明确显示哪个RPC调用失败，对应到具体端口后再针对性排查转发和防火墙规则。

内容的提问来源于stack exchange，提问作者Marcos Heidemann