服务注册与分布式协调 / 技术文章

ZooKeeper 完全指南:从原理架构到实战

1. ZooKeeper 解决什么问题

本文解决 ZooKeeper “为什么能协调分布式系统、如何正确部署、怎样在代码中使用以及出现故障时如何排查”这四类问题。完成阅读后,你将能够判断一个业务是否适合使用 ZooKeeper,独立搭建单机与三节点集群,并完成配置管理、服务注册、分布式锁和运行状态检查。

ZooKeeper 适合保存体积小、读多写少、需要多节点协调的数据,例如:

  • 服务实例列表;
  • 主节点身份;
  • 配置版本;
  • 任务归属;
  • 分布式锁竞争状态;
  • 集群成员在线状态。

ZooKeeper 不适合作为业务数据库、对象存储、消息队列或日志系统。可使用以下标准判断:

判断项 适合使用 ZooKeeper 不适合使用 ZooKeeper
数据大小 单个节点通常为 KB 级 图片、文件、大型 JSON
访问方式 读多写少、需要事件通知 高频写入、批量查询
一致性诉求 选主、锁、成员协调 复杂事务和统计分析
生命周期 数据与会话关联 数据需要永久归档
查询能力 按路径精确访问 条件检索、聚合查询

2. 核心概念:znode、会话、版本和 Watch

ZooKeeper 的数据组织形式是一棵树,树上的每个节点称为 znode。znode 同时具有路径、数据、版本、ACL 和时间信息。

ZooKeeper 数据树、会话与 Watch 关系

常见节点类型如下:

节点类型 生命周期 典型用途
持久节点 显式删除前一直存在 配置目录、业务根目录
持久顺序节点 持久存在并自动追加序号 持久队列、任务排序
临时节点 会话失效后自动删除 服务注册、在线状态
临时顺序节点 会话失效后删除并带递增序号 分布式锁、选主

每次修改 znode 数据,节点的 version 都会递增。客户端可以在更新时携带期望版本,从而实现乐观锁:

  1. 读取数据和当前版本;
  2. 根据旧数据计算新值;
  3. 使用旧版本提交更新;
  4. 若返回 BadVersion,说明数据已被其他客户端修改;
  5. 重新读取并决定是否重试。

Watch 用于监听节点变化,但普通 Watch 默认只触发一次。收到通知后,客户端必须重新读取节点并重新注册 Watch。

3. 集群架构与多数派机制

ZooKeeper 集群通常包含以下角色:

  • Leader:协调写请求,生成事务顺序并发起提交;
  • Follower:参与投票、同步事务,也可以处理读请求;
  • Observer:同步数据并处理读请求,但不参与多数派投票;
  • Client:连接任意可用服务器,在连接中断后尝试其他节点。

ZooKeeper 写请求在 Leader 与 Follower 之间的提交流程

写请求的基本流程如下:

  1. 客户端向当前连接的服务器发送写请求;
  2. 请求被转发给 Leader;
  3. Leader 生成事务提议并广播给 Follower;
  4. 多数投票节点确认后提交事务;
  5. 集群应用事务并向客户端返回结果。

ZooKeeper 依赖多数派维持服务。对于 N 个投票节点,至少需要 floor(N / 2) + 1 个节点存活。

节点数 最少存活数 可容忍故障数
1 1 0
3 2 1
4 3 1
5 3 2

由此可得明确结论:生产环境优先选择 3 或 5 个投票节点,增加偶数节点通常不会提高容错能力。

4. 一致性边界与客户端判断标准

ZooKeeper 能保证单个客户端请求顺序、写入原子性和已提交事务的可靠性,但不同客户端在极短时间内可能读取到不同进度的数据。

工程中应使用以下判断标准:

  1. 写请求成功返回:可以认为事务已被多数派接受。
  2. 发生 ConnectionLoss:不能直接判定写入失败,请求可能已经提交但响应丢失。
  3. 发生 SessionExpired:旧会话拥有的临时节点和锁资格已经失效。
  4. 发生 BadVersion:数据被并发修改,应重新读取后再计算。
  5. 跨客户端要求立即读到最新值:先调用 sync(),再执行读取。
  6. 会话仍有效但 TCP 连接切换:临时节点不会立即删除。

5. 单机安装与基础验证

以下示例以 ZooKeeper 3.9.5、Ubuntu 和 JDK 17 为例。

安装 Java 和下载工具:

bash
sudo apt-get update
sudo apt-get install -y openjdk-17-jre-headless curl
java -version

预期输出的关键内容:

text
openjdk version "17

补丁版本和发行版名称可能不同,但主版本应为 17,命令退出码应为 0。

下载并解压 ZooKeeper:

bash
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"

预期输出:

text
ZooKeeper installed

创建单机配置:

bash
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。

验证配置文件:

bash
grep -E '^(tickTime|dataDir|clientPort|autopurge|4lw|admin)' /opt/zookeeper/conf/zoo.cfg

预期输出:

text
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:

bash
sudo /opt/zookeeper/bin/zkServer.sh start
sleep 2
sudo /opt/zookeeper/bin/zkServer.sh status

预期输出的关键内容:

text
Mode: standalone

若没有显示 standalone,应检查 /opt/zookeeper/logs/、2181 端口占用和数据目录权限。

6. 使用命令行完成 CRUD

执行以下命令进入客户端:

bash
/opt/zookeeper/bin/zkCli.sh -server 127.0.0.1:2181

预期输出的关键内容:

text
CONNECTED

进入客户端后执行:

text
create /anystack "v1"
get /anystack
set /anystack "v2"
get /anystack
stat /anystack
delete /anystack
quit

预期输出的关键内容:

text
Created /anystack
v1
v2
version = 1

判断验证成功的标准:

  • 创建命令返回 Created /anystack;
  • 第一次读取结果为 v1;
  • 修改后读取结果为 v2;
  • version 从 0 增加到 1;
  • 删除命令没有返回错误。

7. 三节点集群部署

假设三台服务器的主机名为:

text
zk1
zk2
zk3

需要开放以下内部端口:

端口 用途
2181 客户端连接
2888 数据同步
3888 Leader 选举

三台服务器使用相同的 /opt/zookeeper/conf/zoo.cfg:

properties
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 上执行:

bash
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

预期输出:

text
1

在 zk2 上执行:

bash
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

预期输出:

text
2

在 zk3 上执行:

bash
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

预期输出:

text
3

分别启动三台服务器:

bash
sudo /opt/zookeeper/bin/zkServer.sh start
sleep 3
sudo /opt/zookeeper/bin/zkServer.sh status

预期结果:

text
Mode: leader

或:

text
Mode: follower

三台服务器中应有一台 leader 和两台 follower。若全部显示 looking,按以下顺序排查:

  1. zk1、zk2、zk3 是否能互相解析;
  2. 2888 和 3888 端口是否被防火墙拦截;
  3. myid 是否与 server.x 编号一致;
  4. 数据目录是否可写;
  5. 三台服务器是否至少有两台正常启动。

客户端连接串必须包含多个节点:

text
zk1:2181,zk2:2181,zk3:2181

不要只配置当前 Leader 地址,因为 Leader 在故障和重启后可能发生变化。

8. Java 客户端完整示例

项目结构:

text
zookeeper-demo/
├── pom.xml
└── src/main/java/cn/anystack/zk/ZooKeeperDemo.java

pom.xml:

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:

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");
        }
    }
}

在项目根目录运行:

bash
mvn -q compile exec:java

预期输出:

text
created=/anystack-java-demo
before=v1 version=0
updatedVersion=1
watch=NodeDataChanged path=/anystack-java-demo
after=v2
deleted=/anystack-java-demo

watch 和 updatedVersion 两行的顺序可能因线程调度发生变化,但两行都应出现。

常见异常判断:

  • ConnectionLoss:先确认服务端状态,不要直接认定写入失败;
  • NodeExists:检查是否有上次运行遗留节点;
  • BadVersion:重新读取最新数据和版本;
  • SessionExpired:创建新的客户端并重新注册临时节点。

9. 分布式锁的正确实现思路

生产级分布式锁应使用临时顺序节点,而不是反复竞争一个固定节点。

正确流程:

  1. 创建持久根目录 /locks/order;
  2. 每个客户端创建临时顺序节点 lock-<request-id>-;
  3. 获取并排序所有子节点;
  4. 若自己的节点最小,则获得锁;
  5. 若不是最小节点,只监听自己的前驱节点;
  6. 前驱删除后重新获取子节点并重新判断;
  7. 业务完成后删除自己的节点;
  8. 会话失效时,由 ZooKeeper 自动删除临时节点。

只监听前驱节点可以避免所有等待者同时被唤醒形成惊群。

发生 ConnectionLoss 时,创建请求可能已经成功。客户端应使用唯一请求标识查找自己是否已有候选节点,而不是直接再次创建。

分布式锁必须同时满足以下条件:

  • 设置最大等待时间;
  • 临界区尽可能短;
  • 锁内不执行不可控的慢请求;
  • 会话过期后立即停止业务操作;
  • 高风险资源使用 fencing token;
  • 监控锁等待时间、超时次数和会话过期次数。

10. ACL 与安全配置

ZooKeeper ACL 权限如下:

权限 含义
c 创建子节点
d 删除子节点
r 读取数据和子节点
w 修改节点数据
a 修改 ACL

使用 digest 认证的命令行示例:

bash
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

预期输出的关键内容:

text
Created /secure-config
digest
cdrwa

实际摘要值会根据用户名和密码计算,因此不应把摘要字符串写死为判断条件。验证成功的标准是 ACL scheme 为 digest,身份以 app: 开头,权限为 cdrwa。

生产安全基线:

  • 2181 只对业务网段开放;
  • 2888 和 3888 只允许集群节点互访;
  • 敏感节点禁止使用 OPEN_ACL_UNSAFE;
  • 不把密码和令牌直接写入代码仓库;
  • 未使用 AdminServer 时保持关闭;
  • 四字命令只开放巡检需要的命令;
  • 不在 znode 路径中包含敏感个人信息;
  • 定期升级到受支持的补丁版本。

11. 健康检查与监控

安装 netcat:

bash
sudo apt-get install -y netcat-openbsd
printf 'ruok' | nc -w 2 127.0.0.1 2181

预期输出:

text
imok

imok 只能说明进程可以响应,不能证明集群拥有多数派或写入一定成功。

检查节点角色:

bash
printf 'srvr' | nc -w 2 127.0.0.1 2181

预期输出的关键内容之一:

text
Mode: leader
text
Mode: follower
text
Mode: standalone

查看关键指标:

bash
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'

预期输出结构:

text
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 日志和内存

推荐固定排查顺序:

  1. 使用 zkServer.sh status 确认角色;
  2. 检查 2181、2888、3888 端口;
  3. 确认集群是否仍有多数派;
  4. 检查数据目录权限和磁盘空间;
  5. 检查磁盘 I/O 延迟;
  6. 检查 JVM GC 和系统 swap;
  7. 检查客户端连接泄漏和重试逻辑;
  8. 最后再调整超时参数。

13. 生产最佳实践

部署方面:

  • 使用 3 或 5 个投票节点;
  • 将节点分散到不同故障域;
  • 不与高 I/O 数据库或日志平台混合部署;
  • 为事务日志使用低延迟磁盘;
  • JVM 堆大小必须小于物理内存;
  • 禁止系统发生 swap;
  • 开启历史快照和事务日志自动清理;
  • 客户端连接串包含多个节点。

应用方面:

  • znode 只保存小型协调数据;
  • 路径按环境和应用隔离;
  • 创建、修改和删除操作设计为幂等;
  • 明确区分连接丢失、会话过期和业务失败;
  • Watch 回调只执行轻量操作;
  • 分布式锁使用临时顺序节点和前驱监听;
  • 不将 ZooKeeper 当作消息队列;
  • 不在锁内执行长时间外部调用。

14. 上线检查清单

上线前逐项验证:

  1. 停止三节点集群中的任意一个节点,读写仍然成功;
  2. 节点恢复后能够重新加入集群;
  3. 客户端连接节点停止后能够自动切换;
  4. 会话过期后临时节点会被删除;
  5. 应用能够在新会话中重新注册服务;
  6. 未认证客户端无法读取敏感节点;
  7. 自动清理任务能够正常执行;
  8. 磁盘、连接、延迟和 Watch 数已接入监控;
  9. 故障演练具有明确恢复步骤;
  10. 业务代码正确处理 ConnectionLoss 和 SessionExpired。

15. 总结

ZooKeeper 的核心价值是利用多数派提交、会话、临时节点、顺序节点、版本号和 Watch,为分布式系统提供可靠的协调能力。正确使用 ZooKeeper 必须同时满足四个条件:只保存小型协调数据、使用奇数节点集群、正确处理会话与重试边界、建立完整监控和故障演练。只要其中一项缺失,系统在 Leader 切换、网络分区或长时间停顿时就可能出现锁失效、节点残留、状态不一致或无法恢复的问题。

目录与阅读设置

记录一个想法

ZooKeeper 完全指南:从原理架构到实战

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通