ZooKeeper 常见问题与故障处理指南

原创于 2025-08-13 09:03:08 发布 · 1.3k 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#zookeeper #分布式 #云原生

分布式理论&实践专栏收录该内容

42 篇文章

订阅专栏

以下是 ZooKeeper 常见问题与故障处理 的系统化、实战级详解，涵盖你提到的五大典型问题，并补充排查方法、解决方案和预防措施，适用于生产环境运维与开发人员参考。

🚨 ZooKeeper 常见问题与故障处理指南

ZooKeeper 作为分布式协调服务，其稳定性直接影响 Kafka、HBase、Dubbo 等上层系统。一旦出现故障，可能导致服务不可用或数据不一致。以下是最常见的六类问题及其应对策略。

1. `SESSION EXPIRED`（会话过期）

🔍 现象

客户端日志出现：

Session expired: sessionId=0x1234567890, closing socket connection

临时节点（Ephemeral Node）被删除。
Watcher 失效，需重新注册。

🧨 根本原因

GC 停顿过长：JVM Full GC 超过 sessionTimeout，导致无法发送心跳。
网络中断：客户端与 ZooKeeper 之间网络闪断。
线程阻塞：客户端处理逻辑耗时过长，未及时处理 ZooKeeper 心跳。
sessionTimeout 设置不合理：太短（如 < 2×tickTime）或太长（> 20×tickTime）。

✅ 解决方案

措施	说明
合理设置 `sessionTimeout`	通常设为 `20000ms ~ 40000ms`，避免过短
优化客户端 GC	减少堆内存（建议 4G~8G），使用 G1GC，避免 Full GC
异步处理业务逻辑	不在 ZooKeeper 回调线程中执行耗时操作
使用 Curator 等高级客户端	自动处理会话重建、临时节点恢复、Watcher 重注册

💡 恢复建议

客户端应实现：
- 会话过期后重建连接
- 重新创建临时节点
- 重新注册所有 Watcher
- 重新订阅事件

⚠️ 注意：ZooKeeper 不会自动恢复临时节点和 Watcher！

2. `CONNECTION LOSS`（连接丢失）

🔍 现象

客户端报错：

Connection loss for /my-path, retrying...

通常是瞬时错误。

🧨 根本原因

网络抖动、ZooKeeper 节点重启、负载过高导致响应超时。
客户端与服务器之间 TCP 连接中断。

✅ 解决方案

措施	说明
启用自动重试机制	使用 Apache Curator 客户端，内置 `ExponentialBackoffRetry` 策略
合理配置重试策略	示例：

RetryPolicy retry = new ExponentialBackoffRetry(1000, 3);
CuratorFramework client = CuratorFrameworkFactory.newClient("zk1:2181", retry);

| 避免频繁重连 | 控制重试次数和间隔，防止雪崩 |

✅ Curator 能自动处理 CONNECTION_LOSS、SESSION_EXPIRED，并重建连接。

3. 磁盘空间不足（Disk Full）

🔍 现象

ZooKeeper 日志报错：

No space left on device
Unable to write transaction log

无法写入事务日志，导致服务不可写甚至崩溃。

🧨 根本原因

事务日志（dataLogDir）和快照（dataDir）持续增长。
未开启自动清理。
日志盘与快照盘未分离，互相占用空间。

✅ 解决方案

措施	说明
立即清理旧文件	手动删除 `dataDir` 和 `dataLogDir` 中过期的 `snapshot.` 和 `log.` 文件
开启自动清理	在 `zoo.cfg` 中配置：

autopurge.snapRetainCount=3
autopurge.purgeInterval=1  # 每小时清理一次

📌 建议：为 dataLogDir 预留至少 50GB 以上空间，避免频繁写满。

4. `Too many connections`（连接数超限）

🔍 现象

ZooKeeper 日志：

Too many connections from /192.168.1.100 - maxClientCnxns=60

新客户端无法连接。

🧨 根本原因

单个客户端 IP 建立了过多连接（如未复用连接、连接泄漏）。
maxClientCnxns 默认为 60，可能不够用。

✅ 解决方案

措施	说明
调大 `maxClientCnxns`	修改 `zoo.cfg`：

maxClientCnxns=200

✅ 推荐：结合 cons 命令分析连接来源，定位问题服务。

5. `Out of Memory`（内存溢出）

🔍 现象

ZooKeeper 进程崩溃，日志出现 java.lang.OutOfMemoryError
GC 日志显示频繁 Full GC

🧨 根本原因

堆内存不足：ZNode 数量过多或单个节点数据过大。
Watcher 过多：大量客户端监听同一路径。
JVM 参数不合理：-Xmx 设置过小或过大（> 8G 易导致 GC 停顿）。

✅ 解决方案

措施	说明
合理设置 JVM 堆大小	建议 `-Xms4g -Xmx8g`，避免过大
启用 G1GC	减少 GC 停顿：

-XX:+UseG1GC -XX:MaxGCPauseMillis=100

📊 关键指标：

ZNode 数量建议 < 500万
Watcher 数量建议 < 100万

6. Leader 频繁选举（Frequent Leader Election）

🔍 现象

日志中频繁出现：

LEADING - LEADER ELECTION TOOK - 1234 MS
FOLLOWING

集群不稳定，写操作失败。

🧨 根本原因

原因	说明
网络不稳定	节点间通信延迟高或丢包
GC 停顿过长	Follower 或 Leader GC 时间 > `syncLimit * tickTime`
磁盘 IO 慢	事务日志写入延迟高（`fsync` 慢）
`syncLimit` 设置过小	无法容忍正常延迟
CPU 资源不足	节点负载过高，处理请求慢

✅ 排查与解决步骤

检查选举日志：
```
grep "LEADER ELECTION" zookeeper.log
```
查看选举耗时：
- 正常应 < 200ms
- 1s 表示严重问题
检查 GC 日志：
- 是否有 Full GC 超过 1s？
- 使用 jstat -gc 监控
检查磁盘性能：
```
iostat -x 1
```
- %util > 90% 表示磁盘瓶颈
- await > 10ms 表示响应慢
调整 syncLimit：
```
syncLimit=10  # 原为 5
```
优化硬件：
- 使用 SSD 存储 dataLogDir
- 独占 CPU 和内存资源

✅ 最佳实践：Leader 选举应极少发生（仅在节点重启或网络分区时）。

🛠️ 故障排查工具汇总

工具	用途
`echo stat \| nc localhost 2181`	查看连接数、延迟、模式
`echo mntr \| nc localhost 2181`	获取监控指标（Prometheus 可采集）
`echo cons \| nc localhost 2181`	查看连接来源
`echo wchc \| nc localhost 2181`	查看 Watch 按 session 分布
`jstat -gc <pid>`	查看 GC 状态
`iostat -x 1`	查看磁盘 I/O
`dmesg` / `journalctl`	查看系统级异常（OOM killer）

✅ 预防性建议（Best Practices）

项目	建议
硬件	独立 SSD 存储事务日志，避免与其他服务共用
JVM	4G~8G 堆 + G1GC，开启 GC 日志
配置	开启 `autopurge`，分离 `dataDir` 和 `dataLogDir`
监控	Prometheus + Grafana + Alertmanager 全覆盖
客户端	使用 Curator，合理设置 `sessionTimeout` 和重试策略
容量规划	ZNode 数 < 500万，连接数 < 1万/节点

📌 总结：ZooKeeper 故障处理口诀

🔎 一看日志：先查 zookeeper.out 和 GC 日志
📊 二看监控：延迟、连接、ZNode、内存、磁盘
🧰 三用命令：stat, mntr, cons, wchc 快速定位
💡 四调参数：tickTime, syncLimit, maxClientCnxns, autopurge
🛡️ 五做预防：自动清理、监控告警、容量评估