服务注册与分布式协调 / 系统课时
连接失败排查
连接失败排查
本课建立 ZooKeeper 连接失败的标准定位顺序:先区分拒绝、超时和解析错误,再逐层检查进程、监听地址、DNS、路由、防火墙、端口与客户端配置。完成后,你能用最少命令快速确定故障位于哪一层。
学习目标
- 根据错误类型缩小故障范围
- 按服务端、网络和客户端顺序执行检查
- 使用连接测试与日志完成修复验证
先按现象分类
Connection refused 通常表示目标主机可达,但端口没有进程监听,或防火墙主动拒绝。Connection timed out 更可能是路由、防火墙丢包、安全组或地址错误。UnknownHostException、Name or service not known 则优先检查 DNS 和连接串。
若客户端不断在多个地址之间切换,要逐个检查连接串中的所有节点。只验证一个正常地址,不能证明整个连接串可用。

按顺序执行基础检查
在服务端确认进程、配置和监听端口,在客户端确认 DNS 与 TCP 连通性。下面示例使用变量避免把占位符误当成命令,请替换为实际地址和路径。
HOST=zk-1.example.internal
PORT=2181
CONFIG=/etc/zookeeper/zoo.cfg
systemctl is-active zookeeper
grep -E '^(clientPort|clientPortAddress|secureClientPort)=' "$CONFIG"
ss -lntp | grep ":${PORT} "
getent hosts "$HOST"
nc -vz -w 3 "$HOST" "$PORT"健康情况下,进程为 active,配置端口与监听端口一致,DNS 返回预期 IP,TCP 测试成功。PID、IP 和进程名会因环境不同。
active
clientPort=2181
LISTEN 0 50 0.0.0.0:2181 ...
10.0.1.11 zk-1.example.internal
Connection to zk-1.example.internal 2181 port [tcp/*] succeeded!若 ss 没有结果,检查 ZooKeeper 启动日志、配置文件路径和端口是否被其他进程占用。若服务端监听正常但 nc 超时,从客户端到服务端逐跳检查路由、主机防火墙、云安全组和网络 ACL。
检查配置一致性
客户端连接串应包含正确的主机名、客户端端口和可选 chroot,例如 zk-1:2181,zk-2:2181,zk-3:2181/app。不要把 quorum 通信端口或选举端口当作客户端端口。
服务端若配置 clientPortAddress,必须确认它绑定的是客户端能够访问的接口。容器或多网卡环境还要检查端口映射、服务发现地址和 NAT 后的目标端口。
用 ZooKeeper 客户端验证
TCP 成功只证明三次握手完成,还需要验证 ZooKeeper 协议和会话建立。
/opt/zookeeper/bin/zkCli.sh -server zk-1.example.internal:2181 -timeout 5000预期结果是客户端进入 SyncConnected,随后出现命令提示符。版本不同,启动日志格式可能不同。
WATCHER::
WatchedEvent state:SyncConnected type:None path:null
[zk: zk-1.example.internal:2181(CONNECTED) 0]如果 TCP 成功但会话无法建立,继续检查 TLS、SASL、ACL 认证、服务端连接上限、客户端与服务端协议配置以及服务端异常日志。
修复后的验收
修复后至少从两个真实客户端网络位置测试全部连接串地址,并观察一段时间内是否仍有重连。最后确认节点角色正常,而不是仅看到端口开放或 ruok 返回 imok。
本课总结
- 拒绝、超时和 DNS 错误对应不同的优先排查方向
- 定位顺序应从进程与监听开始,再检查网络和客户端连接串
- TCP 成功后仍要用 ZooKeeper 客户端确认会话与角色正常
下一课预告
下一课将处理连接能够建立但频繁断开的问题,重点分析网络抖动、GC 停顿、线程阻塞和会话超时。