Ubuntu 上 Zookeeper 客户端连不上的排查与修复
一 快速自检
- 确认服务已启动并处于可用状态：执行zkServer.sh status；若未启动，先执行zkServer.sh start。
- 直接用 CLI 测试本机连通：执行zkCli.sh -server 127.0.0.1:2181；若本机可连而远程不行，多半是网络或访问策略问题。
- 核对客户端连接串：connectString 需写成host:port列表（如192.168.1.10:2181,192.168.1.11:2181），端口通常为2181。
- 若看到“Will not attempt to authenticate using SASL (unknown error)”，常见原因为服务未就绪或防火墙阻断，先确保服务已启动再处理防火墙。
二 网络与防火墙排查
- 测试端口连通：在客户端执行telnet zookeeper-ip 2181或nc -vz zookeeper-ip 2181；连不通说明网络或策略层面被阻断。
- Ubuntu 常见防火墙：
- 使用 UFW：放行端口sudo ufw allow 2181/tcp，或临时关闭sudo ufw disable做验证（验证后请恢复策略）。
- 使用 firewalld：放行端口sudo firewall-cmd --add-port=2181/tcp --permanent && sudo firewall-cmd --reload。
- 云环境需同时检查安全组/NACL是否放行2181/tcp。
- 若端口不通，进一步确认服务是否监听在0.0.0.0:2181而非仅127.0.0.1（见下一节配置核对）。
三 配置与版本核对
- 服务端配置 zoo.cfg：
- 确认clientPort=2181；集群需正确配置server.X=HOST:PORT；
- 检查dataDir存在且可写；
- 集群节点需有对应的myid文件，且内容与 server.X 的 X 一致。
- 端口占用：检查2181是否被其他进程占用，必要时更换端口或释放占用进程后重启。
- 客户端侧：
- 连接串与端口必须与服务端一致；
- 适当增加连接/会话超时与重试；
- 确保客户端与服务端版本兼容，避免协议/特性不匹配。
- 常见错误码速查：
- ConnectionLoss/110 连接超时：网络抖动或服务繁忙，检查网络、负载并适当增大超时；
- SessionExpired/105 会话过期：会话未及时保活或超时设置过短，重建会话并优化心跳/超时；
- AuthFailed/103 无权限：检查 ACL/SASL 凭证与权限配置。
四 日志定位与常见错误场景
- 查看服务端日志：安装目录下的logs/或系统目录/var/log/zookeeper/，从异常堆栈与时间点定位是网络、配置、权限还是资源问题。
- 常见场景与对策：
- 报错“Connection refused”或 CLI 长时间卡顿：多为服务未启动、配置错误或端口未监听；用zkServer.sh status确认状态，核对zoo.cfg与myid，检查2181是否被占用并重启服务。
- 远程连不通但本机可连：优先排查防火墙/安全组与监听地址（是否仅绑定127.0.0.1），必要时改为0.0.0.0并重启。
- 出现“Will not attempt to authenticate using SASL (unknown error)”：先确保服务已启动，再处理SASL/防火墙相关问题。
- SESSIONEXPIRED：客户端需重建 Zookeeper 实例并重新注册临时节点与 Watcher。
- 版本不一致导致握手/协议异常：统一客户端/服务端版本后复测。
五 一键排查命令清单
- 服务端状态与启停：
- zkServer.sh status
- zkServer.sh start
- 本机直连测试：
- zkCli.sh -server 127.0.0.1:2181
- 端口与监听：
- netstat -tulpen | grep 2181（应看到0.0.0.0:2181或指定内网 IP 的监听）
- 连通性测试：
- telnet zookeeper-ip 2181 或 nc -vz zookeeper-ip 2181
- Ubuntu 防火墙：
- UFW：sudo ufw allow 2181/tcp；临时关闭：sudo ufw disable
- firewalld：sudo firewall-cmd --add-port=2181/tcp --permanent && sudo firewall-cmd --reload
- 日志路径：
- 安装目录logs/ 或 /var/log/zookeeper/
