11.8.4 常见故障类型与排查流程
本节聚焦于 ZooKeeper 运行中高频故障的分类、成因与标准化排查流程，覆盖连接与会话、选举与同步、性能与资源、存储与磁盘、网络与安全等关键维度，帮助运维人员快速定位问题并降低恢复时间。以下补充原理草图、完整命令示例与演练步骤，便于可执行排障。
原理草图（故障定位路径）#
常见故障类型#
- 客户端连接与会话异常：连接超时、Session Expired、Auth failed、SASL 失败、客户端频繁重连。
- 选举与集群稳定性问题：频繁重新选举、Leader 抖动、Follower 反复加入/退出、无法达成法定人数。
- 同步与一致性异常：提案卡住、ZXID 不前进、节点数据不一致、快照与事务日志错配。
- 性能退化：请求延迟升高、吞吐下降、watch 触发风暴、长 GC、磁盘 I/O 饱和。
- 存储与磁盘问题：dataDir/dataLogDir 空间不足、磁盘坏块、fsync 延迟高、日志膨胀。
- 网络与安全问题：端口不可达、丢包高、时钟漂移、ACL 配置错误、证书过期。
- 服务进程异常：OOM、JVM 崩溃、线程阻塞、配置错误导致启动失败。
标准排查流程（含命令）#
- 确认现象与影响范围：收集报错信息、业务影响、发生时间线，区分单点与集群性问题。
- 检查服务状态与集群角色：确认各节点存活、Leader/Follower/Observer 角色及任期变化。
- 核对资源与系统层：CPU/内存/磁盘/网络，重点关注磁盘 I/O 与时钟同步。
- 分析日志与指标：server 日志、GC 日志、事务日志；关键指标如 latency、outstanding、synced_followers。
- 定位故障类型并分支排查：按连接、选举、同步、性能、存储、安全等类别进入专项步骤。
- 制定处置与恢复方案：临时缓解、根因修复、必要时执行重启/下线/滚动恢复。
- 复盘与预防：指标告警完善、参数调优、容量规划与演练。
统一排查命令模板#
# 1) 查看 ZooKeeper 服务状态（systemd）
systemctl status zookeeper
# 2) 通过 4-letter-words 获取角色与指标
echo stat | nc 127.0.0.1 2181
echo mntr | nc 127.0.0.1 2181
echo srvr | nc 127.0.0.1 2181
# 3) 查看日志（示例路径）
tail -n 200 /var/log/zookeeper/zookeeper.log
# 4) 资源与系统层检查
top -b -n 1 | head -n 20
iostat -x 1 3
df -h
df -i
timedatectl status
# 5) 端口连通性
ss -lntp | grep -E '2181|2888|3888'
nc -vz zk1.example.com 2181
故障类型与排查要点#
1) 客户端连接与会话异常#
- 排查要点：客户端与服务端版本兼容、sessionTimeout 设置、网络抖动、连接数上限、ACL/认证。
- 常见日志：Session expired、Auth failed、SASL authentication failed。
- 处置建议：调大 sessionTimeout、启用连接池、修复 ACL、优化网络路径。
示例：抓取会话异常与定位连接数上限
# 查看当前连接数与延迟
echo srvr | nc 127.0.0.1 2181 | egrep 'Connections|Latency'
# 查看是否达到 maxClientCnxns（如配置为 60）
grep -n 'maxClientCnxns' /etc/zookeeper/zoo.cfg
# 预期效果：Connections 接近或超过上限时，客户端频繁重连
修复示例（配置调整）
# /etc/zookeeper/zoo.cfg
# 适度提高单 IP 连接数
maxClientCnxns=200
# 调整客户端超时（单位 ms）
tickTime=2000
initLimit=10
syncLimit=5
2) 选举与集群稳定性问题#
- 排查要点：是否满足法定人数、网络延迟/丢包、磁盘过慢导致心跳超时、时钟漂移。
- 常见日志：LOOKING/LEADING/FOLLOWING 频繁切换、Too many connections。
- 处置建议：稳定网络、限制客户端到 Observer、提升磁盘性能、校准 NTP。
示例：验证法定人数与选举抖动
# 在每台节点执行，查看角色
echo stat | nc 127.0.0.1 2181 | egrep 'Mode|Node count'
# 统计正常存活节点数
for host in zk1 zk2 zk3; do
echo "== $host =="; echo stat | nc $host 2181 | egrep 'Mode|Node count'
done
# 预期效果：三节点集群至少两个可用；Mode 稳定为 leader/follower
NTP 校准示例
timedatectl set-ntp true
chronyc tracking
3) 同步与一致性异常#
- 排查要点：事务日志连续性、快照与日志是否匹配、磁盘损坏、节点时间回退。
- 常见现象：某节点落后严重、proposal 无法提交、数据不一致报警。
- 处置建议：清理异常节点数据并重入集群、避免强制手工修改数据目录。
示例：检查事务日志与快照目录
# 查看数据目录与事务日志目录
grep -E 'dataDir|dataLogDir' /etc/zookeeper/zoo.cfg
# 检查目录可用性
ls -lh /data/zookeeper
ls -lh /data/zookeeper/log
恢复示例（谨慎执行）
# 仅在确认该节点数据异常时执行
systemctl stop zookeeper
# 备份旧数据
mv /data/zookeeper /data/zookeeper.bak.$(date +%F)
mkdir -p /data/zookeeper /data/zookeeper/log
chown -R zookeeper:zookeeper /data/zookeeper
systemctl start zookeeper
# 预期效果：节点重新同步并加入集群
4) 性能退化#
- 排查要点：outstanding 请求数、watcher 数量、慢请求、GC 停顿、磁盘 fsync。
- 常见现象：latency 上升、客户端超时、吞吐骤降。
- 处置建议：分离日志与数据盘、减少 watch 数、优化 JVM/堆大小、启用 SSD。
示例：关键指标与慢请求
# 获取延迟与 outstanding
echo mntr | nc 127.0.0.1 2181 | egrep 'latency|outstanding|watch_count'
# 查看 GC 日志（示例路径）
tail -n 200 /var/log/zookeeper/gc.log
5) 存储与磁盘问题#
- 排查要点：磁盘空间、inode、磁盘延迟、RAID 状态、写入错误。
- 常见日志：No space left on device、fsync timeout。
- 处置建议：扩容或清理、将 dataLogDir 独立至性能盘、设置预警阈值。
示例：磁盘 I/O 与空间检查
df -h /data /data/zookeeper/log
df -i /data
iostat -x 1 3
6) 网络与安全问题#
- 排查要点：端口 2181/2888/3888 连通、TLS/证书、ACL 规则、DNS 解析。
- 常见现象：连接被拒、TLS 握手失败、客户端无法认证。
- 处置建议：修复防火墙策略、更新证书、统一认证配置。
示例：端口与 ACL 验证
# 端口检查
ss -lntp | grep -E '2181|2888|3888'
nc -vz zk1.example.com 2181
# 客户端 ACL 验证（示例使用 digest）
/opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181 <<'EOF'
addauth digest user:pass
getAcl /
EOF
7) 服务进程异常#
- 排查要点：JVM OOM、线程死锁、配置错误、依赖库缺失。
- 常见日志：OutOfMemoryError、StackOverflowError、Invalid config。
- 处置建议：调整堆大小与线程参数、校验配置、回滚变更。
示例：查看 JVM 启动参数与堆配置
ps -ef | grep zookeeper | grep java
grep -n 'Xms\|Xmx' /etc/zookeeper/java.env
# 示例调整
cat >> /etc/zookeeper/java.env <<'EOF'
export JVMFLAGS="-Xms2g -Xmx2g -XX:+UseG1GC"
EOF
systemctl restart zookeeper
快速排查清单#
stat命令确认角色与延迟mntr获取核心指标srvr确认版本与连接数- 检查 dataDir/dataLogDir 的空间与 I/O
- 校准 NTP，保证时钟一致
- 对比变更记录与故障时间线
练习与演练#
-
模拟连接异常
- 操作：将maxClientCnxns临时调小为 5，使用脚本创建 10 个连接。
- 观察：客户端重连、日志中出现 connection dropped。
bash # 简单并发连接测试 for i in {1..10}; do (echo srvr | nc 127.0.0.1 2181 >/dev/null &) done -
模拟磁盘空间不足
- 操作：在dataLogDir写满磁盘。
- 观察：日志出现 No space left on device，mntr中outstanding上升。
- 恢复：清理旧日志并重启。 -
模拟选举抖动
- 操作：短时间内停止两个节点。
- 观察：stat中 Mode 变为 LOOKING，无 Leader。
- 恢复：启动节点，观察恢复为 leader/follower。
处置原则#
优先保证法定人数与集群稳定，其次恢复性能与数据一致性；避免在未确认根因前进行全量重启或数据目录手工操作，所有处置步骤需记录并可回滚。