Ubuntu 上 Zookeeper 故障排查方法
一 快速定位流程
- 确认进程是否真实存在：运行 jps，应能看到 QuorumPeerMain；若没有，说明进程未起来或启动即退出。随后查看 bin/zookeeper.out 与 logs/ 下的日志文件，获取标准输出与错误堆栈。若仅显示 “Starting …” 但 status 报错，多半是启动失败但未将错误打印到控制台。必要时用前台启动：./zkServer.sh start-foreground，可直接看到初始化异常。最后用 zkServer.sh status 校验角色（leader/follower/standalone）与运行状态。
二 常见故障与修复要点
- Java 与环境变量问题：报 “nohup: failed to run command ‘java’: No such file or directory” 表示 JAVA_HOME 未设置或 java 不在 PATH；安装 JDK 并正确导出 JAVA_HOME/bin。某些 OpenJDK 9 环境可能出现 “Config file not found: …/management.properties”，可在 $JAVA_HOME/conf 创建指向 lib 的软链接：ln -s lib conf。
- 配置与目录问题：报 “Invalid config, exiting abnormally” 常见于 zoo.cfg 配置错误或 dataDir/dataLogDir 目录不存在；需先创建目录（如 /var/lib/zookeeper, /var/log/zookeeper），并确保配置项拼写与路径正确。
- 端口冲突：出现 java.net.BindException: 地址已在使用，说明 clientPort（默认 2181）被占用；用 netstat -lnp | grep 2181 查占用进程并释放，或在 zoo.cfg 中改为未冲突端口。
- 集群身份与网络：myid 缺失或值不匹配会导致无法加入集群；各节点 dataDir/myid 必须唯一且与 server.X 对应。主机名解析错误、端口未放行也会导致 status 报错或节点间不通；核对 /etc/hosts、使用 ufw status 检查防火墙，必要时临时放行或关闭防火墙测试。
- 版本与包完整性：启动报 “Could not find or load main class org.apache.zookeeper.server.quorum.QuorumPeerMain” 多与下载包不完整或版本问题有关；请使用官方发布的二进制包（含 lib/ 与脚本），必要时回退到稳定版本（如 3.4.x）验证。
三 日志与数据目录检查
- 日志位置与内容：标准输出与错误通常写入 bin/zookeeper.out；运行期日志由 log4j 管理，可通过 conf/log4j.properties 调整级别与滚动策略。为提升性能与便于维护，建议在 zoo.cfg 中设置 dataLogDir 将事务日志与快照分离，并配置自动清理：autopurge.snapRetainCount、autopurge.purgeInterval。
- 事务日志与快照：事务日志位于 dataLogDir，快照位于 dataDir/version-2/，文件名含 ZXID。可用工具解析快照查看节点与 Session：java -cp $ZK_HOME/lib/slf4j-api-.jar:$ZK_HOME/zookeeper-.jar org.apache.zookeeper.server.SnapshotFormatter ./version-2/snapshot.xxx > snapshot.txt；解析事务日志可用 LogFormatter（类路径同上）。这有助于定位数据不一致或异常会话等问题。
四 集群一致性快速校验
- 角色与连通性：在各节点执行 zkServer.sh status，确认存在 leader 与若干 follower；若某节点长期 looking，检查其对其他节点的 server.X 地址与端口（默认 2888/3888）是否可达、防火墙是否放行、主机名解析是否正确。
- 配置与身份复核：逐节点核对 zoo.cfg 的 server.X 列表、myid 唯一且匹配；确保 dataDir/dataLogDir 权限正确且磁盘空间充足。必要时清理异常残留数据（先备份），再按顺序重启各节点。
