Ubuntu上Zookeeper故障排查实操手册
一、快速定位流程
- 服务状态与进程
- 查看状态：执行zkServer.sh status；前台运行便于实时日志：zkServer.sh start-foreground。
- 进程校验：执行jps，确认存在QuorumPeerMain进程；若状态异常或无该进程，多半未真正启动或启动失败。
- 端口与连通性
- 端口占用：执行sudo netstat -lnp | grep 2181（或netstat -ano | grep 2181）检查clientPort=2181是否被占用；若冲突，释放端口或修改zoo.cfg中的端口。
- 连通性：从客户端执行telnet 2181或nc -vz 2181验证网络可达；不通时优先排查网络与防火墙策略。
- 配置与身份
- 核对zoo.cfg中的server.X列表、clientPort、数据目录等；确保各节点myid唯一且与server.X编号一致；必要时用主机IP替代易变主机名以减少解析问题。
- 日志与目录
- 查看安装目录logs/下的日志（常见为.out或按日期滚动的日志），优先从异常栈定位根因；若配置了dataDir/dataLogDir，确认目录存在且权限正确。
二、高频故障与修复对照表
| 症状 |
快速检查 |
修复建议 |
| 启动输出“STARTED”，但zkServer.sh status报“Error contacting service. It is probably not running.” |
jps是否无QuorumPeerMain；端口是否被占用；myid是否缺失或编号不匹配；zoo.cfg中主机名/IP是否正确；/etc/hosts是否映射错误；防火墙是否阻断 |
创建缺失目录（如dataDir、日志目录）；修正myid为唯一编号；修正主机名/IP或完善**/etc/hosts**；释放或更换2181端口；按需开启防火墙放行或临时关闭验证；前台启动观察异常 |
| java.net.BindException: 地址已在使用 |
netstat确认占用进程 |
kill占用进程或调整clientPort；重启服务 |
| 客户端连接超时/拒绝 |
telnet/nc到2181是否通；server端监听地址是否仅绑定127.0.0.1 |
开放防火墙端口（见下节）；确认zoo.cfg中监听地址与客户端访问地址一致 |
| 集群无法形成多数派/选主异常 |
各节点myid唯一且配置一致；server列表完整；网络互通 |
修正myid与server.X对应关系；修复网络/防火墙；必要时按序重启各节点 |
| 容器状态反复Restarting |
docker ps/日志 |
执行**docker logs <容器名>**定位容器内启动失败原因，按日志修复配置或资源问题 |
以上症状与处理要点覆盖了端口占用、配置与身份、防火墙/网络、日志定位等常见场景，可据此逐项排查与修复。
三、Ubuntu防火墙与端口放行
- 查看状态：sudo ufw status
- 临时放行Zookeeper端口（示例为2181）：sudo ufw allow 2181/tcp
- 如需持久化策略，可结合应用与运维策略设置来源网段白名单，避免直接关闭防火墙
- 验证：从外部主机执行telnet 2181或nc -vz 2181确认连通性恢复
四、日志与关键文件定位
- 日志位置：安装目录下的logs/，常见为zookeeper.out或按日期命名的日志文件；前台启动可即时看到异常堆栈与启动流程信息。
- 配置核对：zoo.cfg中的clientPort、server.X=host:peerPort:electionPort、dataDir、dataLogDir等；确保目录存在且Zookeeper运行用户具备读写权限。
- 身份文件：dataDir/myid必须存在且内容为该节点在server.X中的唯一编号（如1、2、3），否则会导致无法加入集群或选主异常。
五、客户端常见错误码与处理
- SessionExpired：会话超时，检查网络稳定性、服务器负载与客户端超时配置，必要时重建会话并优化超时参数
- ConnectionLoss/ServerNotResponding：网络或服务器不可用，核查服务器状态、网络与防火墙策略，适当增大客户端超时
- NodeExists/NoNode：路径已存在或不存在，创建前先判断或按需删除/重建，避免重复创建
- BadVersion：版本冲突，基于最新数据版本执行操作
- AuthFailed：权限不足，检查ACL与凭证配置
- Unimplemented：客户端与服务端版本不兼容，统一版本或调整操作兼容性
- 建议同时关注服务端日志与客户端错误码，结合网络抓包与监控指标进行根因分析
