服务注册与分布式协调 / 技术文章
ZooKeeper 完全指南:从原理架构到实战
1. ZooKeeper 解决什么问题
本文解决 ZooKeeper “为什么能协调分布式系统、如何正确部署、怎样在代码中使用以及出现故障时如何排查”这四类问题。完成阅读后,你将能够判断一个业务是否适合使用 ZooKeeper,独立搭建单机与三节点集群,并完成配置管理、服务注册、分布式锁和运行状态检查。
ZooKeeper 适合保存体积小、读多写少、需要多节点协调的数据,例如:
- 服务实例列表;
- 主节点身份;
- 配置版本;
- 任务归属;
- 分布式锁竞争状态;
- 集群成员在线状态。
ZooKeeper 不适合作为业务数据库、对象存储、消息队列或日志系统。可使用以下标准判断:
| 判断项 | 适合使用 ZooKeeper | 不适合使用 ZooKeeper |
|---|---|---|
| 数据大小 | 单个节点通常为 KB 级 | 图片、文件、大型 JSON |
| 访问方式 | 读多写少、需要事件通知 | 高频写入、批量查询 |
| 一致性诉求 | 选主、锁、成员协调 | 复杂事务和统计分析 |
| 生命周期 | 数据与会话关联 | 数据需要永久归档 |
| 查询能力 | 按路径精确访问 | 条件检索、聚合查询 |
2. 核心概念:znode、会话、版本和 Watch
ZooKeeper 的数据组织形式是一棵树,树上的每个节点称为 znode。znode 同时具有路径、数据、版本、ACL 和时间信息。

常见节点类型如下:
| 节点类型 | 生命周期 | 典型用途 |
|---|---|---|
| 持久节点 | 显式删除前一直存在 | 配置目录、业务根目录 |
| 持久顺序节点 | 持久存在并自动追加序号 | 持久队列、任务排序 |
| 临时节点 | 会话失效后自动删除 | 服务注册、在线状态 |
| 临时顺序节点 | 会话失效后删除并带递增序号 | 分布式锁、选主 |
每次修改 znode 数据,节点的 version 都会递增。客户端可以在更新时携带期望版本,从而实现乐观锁:
- 读取数据和当前版本;
- 根据旧数据计算新值;
- 使用旧版本提交更新;
- 若返回
BadVersion,说明数据已被其他客户端修改; - 重新读取并决定是否重试。
Watch 用于监听节点变化,但普通 Watch 默认只触发一次。收到通知后,客户端必须重新读取节点并重新注册 Watch。
3. 集群架构与多数派机制
ZooKeeper 集群通常包含以下角色:
- Leader:协调写请求,生成事务顺序并发起提交;
- Follower:参与投票、同步事务,也可以处理读请求;
- Observer:同步数据并处理读请求,但不参与多数派投票;
- Client:连接任意可用服务器,在连接中断后尝试其他节点。

写请求的基本流程如下:
- 客户端向当前连接的服务器发送写请求;
- 请求被转发给 Leader;
- Leader 生成事务提议并广播给 Follower;
- 多数投票节点确认后提交事务;
- 集群应用事务并向客户端返回结果。
ZooKeeper 依赖多数派维持服务。对于 N 个投票节点,至少需要 floor(N / 2) + 1 个节点存活。
| 节点数 | 最少存活数 | 可容忍故障数 |
|---|---|---|
| 1 | 1 | 0 |
| 3 | 2 | 1 |
| 4 | 3 | 1 |
| 5 | 3 | 2 |
由此可得明确结论:生产环境优先选择 3 或 5 个投票节点,增加偶数节点通常不会提高容错能力。
4. 一致性边界与客户端判断标准
ZooKeeper 能保证单个客户端请求顺序、写入原子性和已提交事务的可靠性,但不同客户端在极短时间内可能读取到不同进度的数据。
工程中应使用以下判断标准:
- 写请求成功返回:可以认为事务已被多数派接受。
- 发生
ConnectionLoss:不能直接判定写入失败,请求可能已经提交但响应丢失。 - 发生
SessionExpired:旧会话拥有的临时节点和锁资格已经失效。 - 发生
BadVersion:数据被并发修改,应重新读取后再计算。 - 跨客户端要求立即读到最新值:先调用
sync(),再执行读取。 - 会话仍有效但 TCP 连接切换:临时节点不会立即删除。
5. 单机安装与基础验证
以下示例以 ZooKeeper 3.9.5、Ubuntu 和 JDK 17 为例。
安装 Java 和下载工具:
sudo apt-get update
sudo apt-get install -y openjdk-17-jre-headless curl
java -version预期输出的关键内容:
openjdk version "17补丁版本和发行版名称可能不同,但主版本应为 17,命令退出码应为 0。
下载并解压 ZooKeeper:
export ZK_VERSION=3.9.5
export ZK_HOME=/opt/zookeeper
cd /tmp
curl -fLO "https://dlcdn.apache.org/zookeeper/zookeeper-${ZK_VERSION}/apache-zookeeper-${ZK_VERSION}-bin.tar.gz"
sudo mkdir -p "${ZK_HOME}"
sudo tar -xzf "apache-zookeeper-${ZK_VERSION}-bin.tar.gz" --strip-components=1 -C "${ZK_HOME}"
sudo mkdir -p /var/lib/zookeeper
test -x "${ZK_HOME}/bin/zkServer.sh" && echo "ZooKeeper installed"预期输出:
ZooKeeper installed创建单机配置:
sudo tee /opt/zookeeper/conf/zoo.cfg >/dev/null <<'EOF'
tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181
maxClientCnxns=60
autopurge.snapRetainCount=5
autopurge.purgeInterval=24
4lw.commands.whitelist=ruok,srvr,stat,mntr,conf
admin.enableServer=false
EOF该配置的生效行为如下:
- 客户端端口为
2181; - 快照和事务日志保存在
/var/lib/zookeeper; - 每 24 小时执行一次历史文件清理;
- 保留最近 5 组快照;
- 只开放指定的四字命令;
- 关闭未使用的 AdminServer。
验证配置文件:
grep -E '^(tickTime|dataDir|clientPort|autopurge|4lw|admin)' /opt/zookeeper/conf/zoo.cfg预期输出:
tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181
autopurge.snapRetainCount=5
autopurge.purgeInterval=24
4lw.commands.whitelist=ruok,srvr,stat,mntr,conf
admin.enableServer=false启动 ZooKeeper:
sudo /opt/zookeeper/bin/zkServer.sh start
sleep 2
sudo /opt/zookeeper/bin/zkServer.sh status预期输出的关键内容:
Mode: standalone若没有显示 standalone,应检查 /opt/zookeeper/logs/、2181 端口占用和数据目录权限。
6. 使用命令行完成 CRUD
执行以下命令进入客户端:
/opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181预期输出的关键内容:
CONNECTED进入客户端后执行:
create /anystack "v1"
get /anystack
set /anystack "v2"
get /anystack
stat /anystack
delete /anystack
quit预期输出的关键内容:
Created /anystack
v1
v2
version = 1判断验证成功的标准:
- 创建命令返回
Created /anystack; - 第一次读取结果为
v1; - 修改后读取结果为
v2; version从0增加到1;- 删除命令没有返回错误。
7. 三节点集群部署
假设三台服务器的主机名为:
zk1
zk2
zk3需要开放以下内部端口:
| 端口 | 用途 |
|---|---|
| 2181 | 客户端连接 |
| 2888 | 数据同步 |
| 3888 | Leader 选举 |
三台服务器使用相同的 /opt/zookeeper/conf/zoo.cfg:
tickTime=2000
initLimit=10
syncLimit=5
dataDir=/data/zookeeper/snapshot
dataLogDir=/data/zookeeper/transaction-log
clientPort=2181
maxClientCnxns=60
autopurge.snapRetainCount=5
autopurge.purgeInterval=24
server.1=zk1:2888:3888
server.2=zk2:2888:3888
server.3=zk3:2888:3888
4lw.commands.whitelist=ruok,srvr,stat,mntr,conf
admin.enableServer=false配置行为:
initLimit=10:Follower 最多使用10 × tickTime完成初始同步;syncLimit=5:运行时允许 Follower 落后 Leader 的最大 tick 数;dataLogDir:单独存放事务日志,生产环境应使用低延迟磁盘;server.x:定义节点编号、同步端口和选举端口。
在 zk1 上执行:
sudo mkdir -p /data/zookeeper/snapshot /data/zookeeper/transaction-log
echo 1 | sudo tee /data/zookeeper/snapshot/myid >/dev/null
cat /data/zookeeper/snapshot/myid预期输出:
1在 zk2 上执行:
sudo mkdir -p /data/zookeeper/snapshot /data/zookeeper/transaction-log
echo 2 | sudo tee /data/zookeeper/snapshot/myid >/dev/null
cat /data/zookeeper/snapshot/myid预期输出:
2在 zk3 上执行:
sudo mkdir -p /data/zookeeper/snapshot /data/zookeeper/transaction-log
echo 3 | sudo tee /data/zookeeper/snapshot/myid >/dev/null
cat /data/zookeeper/snapshot/myid预期输出:
3分别启动三台服务器:
sudo /opt/zookeeper/bin/zkServer.sh start
sleep 3
sudo /opt/zookeeper/bin/zkServer.sh status预期结果:
Mode: leader或:
Mode: follower三台服务器中应有一台 leader 和两台 follower。若全部显示 looking,按以下顺序排查:
zk1、zk2、zk3是否能互相解析;- 2888 和 3888 端口是否被防火墙拦截;
myid是否与server.x编号一致;- 数据目录是否可写;
- 三台服务器是否至少有两台正常启动。
客户端连接串必须包含多个节点:
zk1:2181,zk2:2181,zk3:2181不要只配置当前 Leader 地址,因为 Leader 在故障和重启后可能发生变化。
8. Java 客户端完整示例
项目结构:
zookeeper-demo/
├── pom.xml
└── src/main/java/cn/anystack/zk/ZooKeeperDemo.javapom.xml:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>cn.anystack</groupId>
<artifactId>zookeeper-demo</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.zookeeper</groupId>
<artifactId>zookeeper</artifactId>
<version>3.9.5</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.5.0</version>
<configuration>
<mainClass>cn.anystack.zk.ZooKeeperDemo</mainClass>
</configuration>
</plugin>
</plugins>
</build>
</project>该配置用于下载 ZooKeeper Java 客户端,并使用 JDK 17 编译项目。验证方式是执行后面的 Maven 命令。
ZooKeeperDemo.java:
package cn.anystack.zk;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.WatchedEvent;
import org.apache.zookeeper.Watcher.Event.EventType;
import org.apache.zookeeper.Watcher.Event.KeeperState;
import org.apache.zookeeper.ZooDefs;
import org.apache.zookeeper.ZooKeeper;
import org.apache.zookeeper.data.Stat;
public final class ZooKeeperDemo {
private static final String CONNECT_STRING = "127.0.0.1:2181";
private static final int SESSION_TIMEOUT_MS = 8000;
private static final String PATH = "/anystack-java-demo";
private ZooKeeperDemo() {
}
public static void main(String[] args) throws Exception {
CountDownLatch connected = new CountDownLatch(1);
CountDownLatch changed = new CountDownLatch(1);
try (ZooKeeper client = new ZooKeeper(
CONNECT_STRING,
SESSION_TIMEOUT_MS,
event -> handleConnection(event, connected))) {
if (!connected.await(10, TimeUnit.SECONDS)) {
throw new IllegalStateException("ZooKeeper connection timeout");
}
Stat existing = client.exists(PATH, false);
if (existing != null) {
client.delete(PATH, existing.getVersion());
}
String createdPath = client.create(
PATH,
"v1".getBytes(StandardCharsets.UTF_8),
ZooDefs.Ids.OPEN_ACL_UNSAFE,
CreateMode.PERSISTENT);
System.out.println("created=" + createdPath);
Stat readStat = new Stat();
byte[] before = client.getData(
PATH,
event -> {
if (event.getType() == EventType.NodeDataChanged) {
System.out.println(
"watch=" + event.getType()
+ " path=" + event.getPath());
changed.countDown();
}
},
readStat);
System.out.println(
"before=" + new String(before, StandardCharsets.UTF_8)
+ " version=" + readStat.getVersion());
Stat updated = client.setData(
PATH,
"v2".getBytes(StandardCharsets.UTF_8),
readStat.getVersion());
System.out.println("updatedVersion=" + updated.getVersion());
if (!changed.await(5, TimeUnit.SECONDS)) {
throw new IllegalStateException("Watch event timeout");
}
byte[] after = client.getData(PATH, false, new Stat());
System.out.println(
"after=" + new String(after, StandardCharsets.UTF_8));
client.delete(PATH, updated.getVersion());
System.out.println("deleted=" + PATH);
}
}
private static void handleConnection(
WatchedEvent event,
CountDownLatch connected) {
if (event.getState() == KeeperState.SyncConnected) {
connected.countDown();
}
if (event.getState() == KeeperState.Expired) {
System.err.println("session expired");
}
}
}在项目根目录运行:
mvn -q compile exec:java预期输出:
created=/anystack-java-demo
before=v1 version=0
updatedVersion=1
watch=NodeDataChanged path=/anystack-java-demo
after=v2
deleted=/anystack-java-demowatch 和 updatedVersion 两行的顺序可能因线程调度发生变化,但两行都应出现。
常见异常判断:
ConnectionLoss:先确认服务端状态,不要直接认定写入失败;NodeExists:检查是否有上次运行遗留节点;BadVersion:重新读取最新数据和版本;SessionExpired:创建新的客户端并重新注册临时节点。
9. 分布式锁的正确实现思路
生产级分布式锁应使用临时顺序节点,而不是反复竞争一个固定节点。
正确流程:
- 创建持久根目录
/locks/order; - 每个客户端创建临时顺序节点
lock-<request-id>-; - 获取并排序所有子节点;
- 若自己的节点最小,则获得锁;
- 若不是最小节点,只监听自己的前驱节点;
- 前驱删除后重新获取子节点并重新判断;
- 业务完成后删除自己的节点;
- 会话失效时,由 ZooKeeper 自动删除临时节点。
只监听前驱节点可以避免所有等待者同时被唤醒形成惊群。
发生 ConnectionLoss 时,创建请求可能已经成功。客户端应使用唯一请求标识查找自己是否已有候选节点,而不是直接再次创建。
分布式锁必须同时满足以下条件:
- 设置最大等待时间;
- 临界区尽可能短;
- 锁内不执行不可控的慢请求;
- 会话过期后立即停止业务操作;
- 高风险资源使用 fencing token;
- 监控锁等待时间、超时次数和会话过期次数。
10. ACL 与安全配置
ZooKeeper ACL 权限如下:
| 权限 | 含义 |
|---|---|
c |
创建子节点 |
d |
删除子节点 |
r |
读取数据和子节点 |
w |
修改节点数据 |
a |
修改 ACL |
使用 digest 认证的命令行示例:
cat <<'EOF' | /opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181
create /secure-config "db=primary"
addauth digest app:secret
setAcl /secure-config auth:app:secret:cdrwa
getAcl /secure-config
quit
EOF预期输出的关键内容:
Created /secure-config
digest
cdrwa实际摘要值会根据用户名和密码计算,因此不应把摘要字符串写死为判断条件。验证成功的标准是 ACL scheme 为 digest,身份以 app: 开头,权限为 cdrwa。
生产安全基线:
- 2181 只对业务网段开放;
- 2888 和 3888 只允许集群节点互访;
- 敏感节点禁止使用
OPEN_ACL_UNSAFE; - 不把密码和令牌直接写入代码仓库;
- 未使用 AdminServer 时保持关闭;
- 四字命令只开放巡检需要的命令;
- 不在 znode 路径中包含敏感个人信息;
- 定期升级到受支持的补丁版本。
11. 健康检查与监控
安装 netcat:
sudo apt-get install -y netcat-openbsd
printf 'ruok' | nc -w 2 127.0.0.1 2181预期输出:
imokimok 只能说明进程可以响应,不能证明集群拥有多数派或写入一定成功。
检查节点角色:
printf 'srvr' | nc -w 2 127.0.0.1 2181预期输出的关键内容之一:
Mode: leaderMode: followerMode: standalone查看关键指标:
printf 'mntr' | nc -w 2 127.0.0.1 2181 | grep -E 'zk_server_state|zk_znode_count|zk_watch_count|zk_outstanding_requests|zk_avg_latency|zk_max_latency|zk_num_alive_connections'预期输出结构:
zk_avg_latency <NUMBER>
zk_max_latency <NUMBER>
zk_num_alive_connections <NUMBER>
zk_outstanding_requests <NUMBER>
zk_server_state <STATE>
zk_watch_count <NUMBER>
zk_znode_count <NUMBER>其中 <NUMBER> 和 <STATE> 是动态值。生产环境至少监控:
- 平均延迟和最大延迟;
- 未完成请求数;
- 客户端连接数;
- znode 数量;
- Watch 数量;
- 磁盘使用率;
- JVM GC 停顿;
- Leader 选举次数;
- 会话过期次数。
12. 常见错误与排查方法
| 现象 | 常见原因 | 排查动作 |
|---|---|---|
ConnectionLoss |
网络抖动、节点重启、Leader 切换 | 确认操作结果,再决定是否重试 |
SessionExpired |
长时间网络中断、进程暂停 | 重建客户端并重新注册临时节点 |
NodeExists |
重试重复创建、残留节点 | 使用请求标识确认已有节点 |
NoNode |
父目录未创建、节点已删除 | 幂等创建父目录并重新读取 |
BadVersion |
并发更新 | 重新读取数据和版本 |
集群持续 looking |
无法形成多数派 | 检查主机名、端口和 myid |
| Watch 不再触发 | Watch 已触发但未重新注册 | 重新读取并注册新 Watch |
| 磁盘不断增长 | 自动清理未配置或未执行 | 检查 autopurge 和目录权限 |
| 延迟突然升高 | 磁盘慢、长 GC、发生 swap | 检查磁盘延迟、GC 日志和内存 |
推荐固定排查顺序:
- 使用
zkServer.sh status确认角色; - 检查 2181、2888、3888 端口;
- 确认集群是否仍有多数派;
- 检查数据目录权限和磁盘空间;
- 检查磁盘 I/O 延迟;
- 检查 JVM GC 和系统 swap;
- 检查客户端连接泄漏和重试逻辑;
- 最后再调整超时参数。
13. 生产最佳实践
部署方面:
- 使用 3 或 5 个投票节点;
- 将节点分散到不同故障域;
- 不与高 I/O 数据库或日志平台混合部署;
- 为事务日志使用低延迟磁盘;
- JVM 堆大小必须小于物理内存;
- 禁止系统发生 swap;
- 开启历史快照和事务日志自动清理;
- 客户端连接串包含多个节点。
应用方面:
- znode 只保存小型协调数据;
- 路径按环境和应用隔离;
- 创建、修改和删除操作设计为幂等;
- 明确区分连接丢失、会话过期和业务失败;
- Watch 回调只执行轻量操作;
- 分布式锁使用临时顺序节点和前驱监听;
- 不将 ZooKeeper 当作消息队列;
- 不在锁内执行长时间外部调用。
14. 上线检查清单
上线前逐项验证:
- 停止三节点集群中的任意一个节点,读写仍然成功;
- 节点恢复后能够重新加入集群;
- 客户端连接节点停止后能够自动切换;
- 会话过期后临时节点会被删除;
- 应用能够在新会话中重新注册服务;
- 未认证客户端无法读取敏感节点;
- 自动清理任务能够正常执行;
- 磁盘、连接、延迟和 Watch 数已接入监控;
- 故障演练具有明确恢复步骤;
- 业务代码正确处理
ConnectionLoss和SessionExpired。
15. 总结
ZooKeeper 的核心价值是利用多数派提交、会话、临时节点、顺序节点、版本号和 Watch,为分布式系统提供可靠的协调能力。正确使用 ZooKeeper 必须同时满足四个条件:只保存小型协调数据、使用奇数节点集群、正确处理会话与重试边界、建立完整监控和故障演练。只要其中一项缺失,系统在 Leader 切换、网络分区或长时间停顿时就可能出现锁失效、节点残留、状态不一致或无法恢复的问题。