Ubuntu 上 Zookeeper 故障排查步骤
一 快速定位流程
- 查看进程与端口：确认 QuorumPeerMain 是否在运行，以及 clientPort=2181 是否被占用。命令示例：jps | grep QuorumPeerMain；ss -lntp | grep 2181；若占用，kill 对应 PID 或调整 zoo.cfg 的 clientPort。
- 前台启动看实时日志：bin/zkServer.sh start-foreground，能直接看到启动期异常。
- 检查日志文件：优先查看 Zookeeper 安装目录/logs/*.out 与 zookeeper.out，定位配置、权限、类路径等问题。
- 校验配置文件：确认 zoo.cfg 中 dataDir、dataLogDir 指向已存在且可写目录；集群需正确配置 server.X 与 myid。
- 环境与健康检查：确认 JAVA_HOME 与 PATH 正确；Ubuntu 上用 ufw 检查防火墙状态（ufw status），集群需放通 2181/2888/3888 等端口；必要时检查 /etc/hosts 主机名解析。
二 常见故障对照表
| 症状 |
高频原因 |
快速修复 |
| 启动显示 STARTED，但 zkServer.sh status 报 “Error contacting service. It is probably not running.” |
配置目录未创建（dataDir/dataLogDir）；myid 缺失或值不匹配；主机名/端口写错；防火墙阻断；进程未真正起来 |
创建 dataDir/dataLogDir；在 dataDir 写入正确的 myid（与 server.X 一致）；核对 zoo.cfg 的 server 配置与主机名；ufw 放行端口或临时关闭；用 start-foreground 看实时报错 |
| “Starting zookeeper … FAILED TO START” 或 “nohup: failed to run command ‘java’: No such file or directory” |
JAVA_HOME 未设置 或 PATH 无 java；使用了不含二进制文件的安装包（3.5.5+ 需带 bin 的包）；Java 版本不兼容 |
正确设置 JAVA_HOME 与 PATH；下载并使用带 bin 的发行包（apache-zookeeper-x.y.z-bin.tar.gz）；必要时改用 Java 8 稳定版本 |
| “Error: Could not find or load main class org.apache.zookeeper.server.quorum.QuorumPeerMain” |
包不完整（缺少 lib/ 或编译类）；错误地把源码包当二进制包运行 |
使用带 bin 的二进制包；不要混用 3.4.x 与 3.5.x 的目录结构；如仍异常，清理后重装 |
| java.net.BindException: Address already in use |
2181/2888/3888 端口被占用 |
结束占用进程或修改 zoo.cfg 的 clientPort 与会话端口 |
| 集群无法选主或节点异常 |
myid 重复或缺失；server.X 主机名不可达；防火墙未放行 |
确保每个节点 myid 唯一且匹配 server.X；修正主机名/IP；ufw/firewalld 放行相关端口，核对 /etc/hosts 解析 |
三 关键配置与目录检查
- 配置文件要点（示例）：
tickTime=2000
initLimit=10
syncLimit=5
dataDir=/var/lib/zookeeper
dataLogDir=/var/log/zookeeper
clientPort=2181
server.1=host1:2888:3888
server.2=host2:2888:3888
server.3=host3:2888:3888
提示：dataDir 与 dataLogDir 必须存在且可写；伪集群需为不同实例配置不同 clientPort（如 2181/2182/2183）与会话端口（2888/2889/2890、3888/3889/3890）。
- myid 文件：在 dataDir 下创建名为 myid 的文件，内容为该节点的 X（与 server.X 对应），各节点值必须唯一。
- 主机名与解析：确保 /etc/hosts 或 DNS 能正确解析 server.X 的主机名；避免写错主机名导致节点互不可达。
四 服务管理与验证
- 常用命令：
- 启动：bin/zkServer.sh start（前台排错用 start-foreground）
- 状态：bin/zkServer.sh status（集群应显示 leader 或 follower）
- 停止：bin/zkServer.sh stop
- 进程校验：jps | grep QuorumPeerMain 应能看到 QuorumPeerMain；若 status 报错但进程存在，多半是配置/网络/权限问题，回到日志与端口核查。
五 环境与权限要点
- Java 环境：设置全局 JAVA_HOME（如 /usr/lib/jvm/java-8-openjdk-amd64），并确保 PATH 包含 $JAVA_HOME/bin；ZooKeeper 启动脚本依赖 JAVA_HOME。
- 权限与目录：确保运行用户对 dataDir/dataLogDir 有读写权限；必要时使用 chown/chmod 修正属主与权限。
- 防火墙与安全组：Ubuntu 使用 ufw（ufw status/disable/allow）；云环境需放行 2181/2888/3888 等端口，避免集群通信被拦截。
