服务注册与分布式协调 / 系统课时
排查成员地址与端口不一致
排查成员地址与端口不一致
成员已经写进动态配置,却迟迟不能完成选举、同步或客户端连接,最常见原因之一就是地址与端口对不上。本节给出一条从动态配置到实际监听、名称解析和防火墙的核对路径,专门定位 quorum、election 与 client 端口互换、旧地址残留和解析不一致。
学习目标
- 能区分 quorum、election、client 三类地址与端口的职责
- 能按“配置 → 解析 → 监听 → 连通性 → 防火墙”顺序定位成员通信故障
- 能根据症状判断端口互换、旧地址残留或 DNS 解析不一致,并完成修复验证
先把三类通信端点对齐
典型成员配置形如 server.3=zk3.example.com:2888:3888:participant;2181。其中 2888 是 Learner 与 Leader 建立 quorum 连接所用端口,3888 用于 Leader 选举,;2181 则是客户端连接端口。三者职责不同,端口互换时进程可能仍能启动,但集群行为会异常。

排查时不要只看“端口是否开放”,而要确认正确进程是否在正确地址上使用正确端口,并且其他节点解析到的也是同一个地址。尤其是 quorum 端口要结合节点角色判断:Leader 负责接受 Learner 连接,Follower 更重要的是能连到 Leader 的 quorum 端口。
从动态配置确认声明值
先读取集群当前生效的动态配置,避免拿旧的 zoo.cfg.dynamic.* 或运维文档做判断。
zkCli.sh -server 127.0.0.1:2181 <<'EOF'
config
quit
EOF预期输出
server.1=zk1.example.com:2888:3888:participant;2181
server.2=zk2.example.com:2888:3888:participant;2181
server.3=zk3.example.com:2888:3888:participant;2181
version=<CONFIG_VERSION>重点逐项核对主机名、quorum 端口、election 端口和 client 端口。若刚做过迁移,还要搜索旧 IP 或旧主机名是否残留在实际动态配置文件中。
grep -nE 'old-zk-host|10\.0\.0\.15' <PATH_TO_DYNAMIC_CONFIG>预期结果有两种:无输出表示未命中;若仍有残留,会返回对应行号,例如:
3:server.3=10.0.0.15:2888:3888:participant;2181<PATH_TO_DYNAMIC_CONFIG> 需要替换为实际动态配置文件路径。
核对解析、角色与套接字
在每台成员机上确认同一个主机名解析到一致地址。下面以 zk3.example.com 为例:
getent hosts zk3.example.com预期输出
10.0.0.23 zk3.example.com如果不同节点解析出不同 IP,配置文本即使完全一致,也可能让节点连接到不同目标。随后在各节点本机执行状态检查,先确认谁是 Leader、谁是 Follower:
zkServer.sh status预期输出中的关键字段类似:
Using config: <PATH_TO_ZOO_CFG>
Mode: follower<PATH_TO_ZOO_CFG> 和角色以实际环境为准。知道角色后再看套接字:Leader 应能接受 Learner 对其 quorum 端口的连接;Follower 则通常会存在到 Leader quorum 端口的已建立连接。client 端口应由提供客户端服务的节点监听,election 端口则要与配置一致。
ss -lntp | grep -E ':(2181|2888|3888)\b'
ss -ntp | grep ':2888'在一个健康的 Follower 上,预期结果至少能看到 client/election 相关监听,以及到 Leader quorum 端口的连接;示例中的地址、PID 和文件描述符会随环境变化:
LISTEN 0 50 0.0.0.0:2181 0.0.0.0:* users:(("java",pid=<PID>,fd=<FD>))
LISTEN 0 50 0.0.0.0:3888 0.0.0.0:* users:(("java",pid=<PID>,fd=<FD>))
ESTAB 0 0 10.0.0.23:<EPHEMERAL_PORT> 10.0.0.21:2888 users:(("java",pid=<PID>,fd=<FD>))实际监听地址可能是具体 IP、IPv6 地址或 0.0.0.0。如果当前节点是 Leader,则还应重点确认它在自身 quorum 地址对应的 2888 上接受 Learner 连接。
从对端验证网络与防火墙
先确定当前 Leader,例如它是 zk1.example.com。从其他 ZooKeeper 成员测试 Leader 的 quorum 端口,并测试目标成员的 election 端口:
nc -vz zk1.example.com 2888
nc -vz zk3.example.com 3888预期输出
Connection to zk1.example.com 2888 port [tcp/*] succeeded!
Connection to zk3.example.com 3888 port [tcp/*] succeeded!如果 Leader 的 2888 不通,优先检查 Leader 实际监听地址、防火墙与动态配置;如果某成员的 3888 不通,则重点检查选举地址、端口互换和节点间防火墙规则。不要用“任意 Follower 的 2888 必须可连接”作为健康标准,因为 quorum 连接的监听与节点角色有关。
再从客户端所在网络验证 client 端口:
nc -vz zk3.example.com 2181预期输出
Connection to zk3.example.com 2181 port [tcp/*] succeeded!成员间通信正常但 2181 不通,通常表现为客户端不可达;反过来,2181 正常也不能证明 2888、3888 的集群通信正常。
按症状修复并闭环
如果集群反复选举、迟迟没有稳定 Leader,优先核对 election 地址与 3888;如果已有 Leader,但某个 Follower 长时间无法同步或加入,优先核对它到 Leader quorum 地址与 2888 的链路;如果集群内部正常但业务连接失败,则重点检查 client 地址、2181 和客户端侧网络。
端口互换的典型特征是声明值与实际通信角色对不上;旧地址残留常表现为迁移后的特定成员持续不可达;解析不一致则常表现为“某些节点能连、某些节点不能连”,并且不同机器上的 getent hosts 结果不同。
修正动态配置、DNS 或防火墙后,再次读取配置并检查本机角色:
zkCli.sh -server zk1.example.com:2181 <<'EOF'
config
quit
EOF
zkServer.sh status预期输出应同时体现新端点已经生效,并且节点已经回到稳定角色:
server.1=zk1.example.com:2888:3888:participant;2181
server.2=zk2.example.com:2888:3888:participant;2181
server.3=zk3.example.com:2888:3888:participant;2181
version=<CONFIG_VERSION>
Mode: follower实际角色可能是 leader 或 follower。最终验收标准不是“端口看起来都开着”,而是动态配置、名称解析、节点角色、实际套接字、成员间连通性和客户端可达性彼此一致。