Zookeeper节点故障排查在Ubuntu上的方法

Ubuntu上Zookeeper节点故障排查步骤

一 快速判定与恢复

• 查看进程是否存活：运行jps，确认存在QuorumPeerMain进程；若不存在，说明进程未起来或异常退出。
• 前台启动以获取实时日志：在**$ZOOKEEPER_HOME/bin执行./zkServer.sh start-foreground**，可直接看到启动期异常。
• 查看服务状态：执行**./zkServer.sh status**，正常应返回Mode: leader或Mode: follower；若返回Error contacting service. It is probably not running.，多为进程未启动、配置/网络异常或权限问题。
• 启停与重启：使用**./zkServer.sh start|stop**；必要时用**kill **结束僵尸进程后再启动。
• 日志定位：检查**$ZOOKEEPER_HOME/logs/*.out与dataDir/zookeeper.out**（或配置的日志路径），优先从异常栈和“Address already in use”“myid”“Cannot open channel to X”等关键词入手。

二 配置与身份校验

• 核对zoo.cfg关键项：
  • clientPort（默认2181）是否被占用或被改动；
  • dataDir目录是否存在且可写；
  • server.X=host:peerPort:electionPort列表是否完整、主机名/IP是否可达；
  • 如自定义了日志目录，确认已mkdir -p创建。
• 校验myid文件：
  • 位置必须在dataDir下，文件名固定为myid；
  • 内容为该节点的唯一编号（1、2、3…），与server.X的序号一一对应；
  • 权限正确，避免被其他用户覆盖。
• 主机名解析：确保**/etc/hosts**或DNS可正确解析集群各节点的主机名与IP，避免因解析错误导致无法建立集群连接。

三 网络连通性与防火墙

• 连通性测试：
  • ping <zk_ip> 检查节点可达；
  • telnet <zk_ip> 2181 或 nc -vz <zk_ip> 2181 验证clientPort是否开放并监听；
  • 跨机房/跨网段可用**mtr <zk_ip>**做持续链路诊断。
• Ubuntu防火墙：
  • 查看状态：sudo ufw status；
  • 临时放行：sudo ufw allow 2181/tcp；如部署了内部四层端口（如2888/3888），一并放行；
  • 生产环境建议基于白名单精细化放行，而非直接关闭。
• 其他节点防火墙：若集群跨主机，确保对端节点同样放行相关端口。

四 常见故障与修复对照表

五 一键排查脚本示例

#!/usr/bin/env bash
set -e

export ZK_HOME=/usr/local/zookeeper
export PATH=$PATH:$ZK_HOME/bin

echo "=== 1) 进程与端口 ==="
jps -l | grep QuorumPeerMain || echo "QuorumPeerMain not found"
ss -ltnp | grep ':2181\|:2888\|:3888' || echo "No ZK ports listening"

echo "=== 2) 服务状态 ==="
$ZK_HOME/bin/zkServer.sh status || true

echo "=== 3) 配置与myid ==="
grep -E '^(clientPort|dataDir|server\.)' $ZK_HOME/conf/zoo.cfg || true
DATA_DIR=$(grep '^dataDir=' $ZK_HOME/conf/zoo.cfg | cut -d= -f2)
[ -f "$DATA_DIR/myid" ] && echo "myid=$(cat $DATA_DIR/myid)" || echo "myid missing in $DATA_DIR"

echo "=== 4) 防火墙 ==="
sudo ufw status || true

echo "=== 5) 最近日志 ==="
tail -n50 $ZK_HOME/logs/*.out 2>/dev/null || tail -n50 "$DATA_DIR/zookeeper.out" 2>/dev/null || echo "No log found"

将脚本保存为zk-check.sh，执行bash zk-check.sh即可快速获取进程、端口、配置、防火墙与日志的关键信息，便于定位问题。