协调服务 Zookeeper

第一章：ZooKeeper 概述

1.1 分布式系统与协调服务

概念名称	说明	注意事项
分布式系统	多台计算机通过网络连接协同完成任务，对外表现为一个统一的系统。各节点独立运行，但需共享状态或协调行为。	节点间通信存在延迟和失败风险，需考虑网络分区、时钟漂移等问题。
协调服务	在分布式系统中用于实现配置管理、命名服务、分布式锁、选主等协调功能的中间件服务。	需具备高可用、强一致性和低延迟特性，否则会影响整个系统的稳定性。
CAP 定理	一个分布式系统最多只能同时满足一致性（Consistency）、可用性（Availability）和分区容错性（Partition tolerance）中的两个。	ZooKeeper 优先保证 CP（一致性 + 分区容错性），牺牲部分可用性。
一致性模型	描述分布式系统中多个副本之间数据一致性的程度，如强一致性、最终一致性等。	ZooKeeper 提供顺序一致性和原子广播，确保所有客户端看到相同的操作顺序。
分布式协调挑战	包括节点故障检测、状态同步、并发控制、脑裂问题等。	单点故障是常见问题，需通过集群和选举机制避免。

1.2 ZooKeeper 简介与核心特性

概念名称	说明	注意事项
ZooKeeper 定义	Apache 开源的分布式协调服务，为分布式应用提供高性能、高可用的一致性服务。	不适合作为通用数据库或大规模数据存储使用。
核心目标	提供简单的文件系统接口来实现复杂的分布式协调逻辑。	设计初衷是”做少而精”，专注于协调任务。
强一致性	所有服务器在任何时候都拥有相同的数据视图，客户端读取结果一致。	写操作需过半节点确认，可能导致写延迟较高。
高可用性	支持集群部署，即使部分节点宕机仍可对外提供服务。	至少需要 3 个节点组成集群以容忍单点故障。
顺序访问	每个更新操作都有全局唯一的事务 ID（zxid），保证操作的全局顺序性。	zxid 是 64 位长整型，前 32 位为 epoch（纪元），后 32 位为计数器。
快速读写	读请求由任意节点响应，写请求由 Leader 节点处理并广播至集群。	读性能高，适合读多写少场景；写吞吐受限于 Leader。

1.3 ZooKeeper 的典型应用场景

应用场景	说明	注意事项
配置管理	将分布式系统的配置集中存储在 ZNode 中，各节点监听变更并动态加载新配置。	避免频繁写入大体积配置，建议将大配置存于外部系统，ZooKeeper 只存引用路径。
命名服务	提供分布式环境下的全局唯一名称注册与查找服务，类似 DNS。	名称路径应具有层次结构，便于管理和查询。
分布式锁	利用临时顺序节点实现排他锁或共享锁，控制对资源的并发访问。	需正确处理连接断开导致的节点自动删除问题。
集群选主	多个候选节点竞争创建同一临时节点，成功者成为主节点（Leader）。	主节点崩溃后会触发重新选举，需设计好故障恢复逻辑。
服务注册与发现	服务启动时在指定路径下创建临时节点，消费者通过获取子节点列表发现可用服务。	需配合负载均衡策略使用，避免热点问题。
分布式队列	使用顺序节点实现 FIFO 队列，或通过屏障节点实现同步集合点。	大规模队列操作可能影响性能，建议结合其他消息中间件使用。

第二章：ZooKeeper 核心概念

2.1 数据模型（ZNode 树）

概念名称	说明	注意事项
ZNode 树	ZooKeeper 的数据模型是一个类似文件系统的树形结构，每个节点称为 ZNode，路径以 / 分隔。	根节点为 /，路径必须是绝对路径且唯一。
节点路径	每个 ZNode 通过唯一路径标识，如 /app/config/db_url。	路径不允许使用空字符和特殊控制字符，长度有限制（通常不超过 512 字节）。
节点数据	每个 ZNode 可存储少量数据（默认最大 1MB），通常用于存储配置、状态等信息。	不建议存储大量数据，以免影响性能和内存使用。
子节点	每个 ZNode 可包含多个子节点，形成层级结构。	节点不能循环引用，不允许自环。
全局唯一版本号	每个 ZNode 维护多个版本号：version（数据修改次数）、cversion（子节点修改次数）、aversion（ACL 修改次数）。	版本号用于乐观锁控制，可用于条件更新操作。

2.2 ZNode 类型详解

ZNode 类型	说明	注意事项
PERSISTENT	持久节点，一旦创建，除非被显式删除，否则一直存在。	适用于长期存在的配置项、服务注册根路径等。
PERSISTENT_SEQUENTIAL	持久顺序节点，在创建时由 ZooKeeper 自动追加一个单调递增的 10 位数字作为后缀。	用于实现分布式队列、唯一ID生成等场景。
EPHEMERAL	临时节点，生命周期与客户端会话绑定，会话结束或超时则节点自动删除。	常用于服务注册、分布式锁，注意不可有子节点。
EPHEMERAL_SEQUENTIAL	临时顺序节点，兼具临时性和顺序性，常用于选主和锁竞争。	节点路径末尾自动添加序号，如 /lock/node_0000000001。
CONTAINER	容器节点，当其子节点全部删除后，ZooKeeper 会在一段时间后自动将其删除。	从 3.5.3 版本开始支持，适用于临时资源组管理。
TTL（Time-to-Live）	带生存时间的持久节点，超过指定时间未更新则自动删除（需启用 extendedTypesEnabled）。	实验性功能，生产环境慎用。

2.3 会话（Session）机制

概念名称	说明	注意事项
会话 ID（Session ID）	每个客户端连接成功后，ZooKeeper 分配一个唯一的 long 类型会话 ID。	可用于会话迁移或故障恢复时识别客户端身份。
会话超时时间（Session Timeout）	客户端设置的会话有效期，单位毫秒，通常为心跳间隔的 2~3 倍。	设置过短易误判为失效，过长则故障发现延迟。
心跳机制	客户端定期发送 ping 请求维持会话活跃状态，默认每隔 1/3 超时时间发送一次。	网络抖动可能导致心跳丢失，需合理设置超时参数。
会话状态	包括 CONNECTING、CONNECTED、RECONNECTING、CLOSED 等状态。	编程时需监听状态变化以处理重连逻辑。
会话迁移	在某些高级用法中，可通过保存 Session ID 和密码实现跨进程会话复用。	需安全保管会话凭证，防止非法复用。
临时节点清理	当会话失效（超时或断开）时，ZooKeeper 自动删除该会话创建的所有临时节点。	这是实现服务发现和分布式锁的关键机制。

2.4 Watcher 机制原理

概念名称	说明	注意事项
Watcher	一种轻量级事件通知机制，客户端可在 ZNode 上注册监听器，当节点发生变化时收到通知。	Watcher 是一次性触发的，需在处理完事件后重新注册。
事件类型（EventType）	包括 None（连接状态变化）、NodeCreated、NodeDeleted、NodeDataChanged、NodeChildrenChanged。	不支持 NodeRenamed 或 DataMatched 等复杂事件。
Watcher 状态（KeeperState）	表示 ZooKeeper 客户端连接的状态，如 SyncConnected、Disconnected、Expired 等。	应优先处理 Expired 事件，表示会话已失效，需重建连接。
注册时机	Watcher 在读取节点信息时通过参数指定是否注册，如 getData(path, true)。	只有当节点确实存在时才能注册成功。
触发条件	节点数据更改、子节点增删、节点创建/删除等都会触发对应事件。	事件通知是异步的，不保证实时性，但保证顺序性。
一次性特性	每个 Watcher 被触发一次后即失效，必须重新注册才能继续监听。	编程中容易遗漏重新注册逻辑，导致漏掉后续变更。
客户端序列化	所有 Watcher 回调在同一个线程中串行执行，避免并发问题。	回调函数中不应执行耗时操作，以免阻塞其他事件处理。

2.5 ACL（访问控制列表）基础

概念名称	说明	注意事项
ACL 结构	每个 ZNode 可设置一组 ACL 权限，由 (scheme:id, permission) 对构成。	默认无权限控制，需显式设置 ACL 才生效。
Scheme	权限验证方案，常见的有 world、auth、digest、ip、x509 等。	不同 scheme 对应不同的认证方式。
world	最宽松的 scheme，仅有一个 id：anyone，代表所有用户。	如 world:anyone:READ 表示任何人都可读。
auth	已认证用户，指通过 addAuthInfo 添加凭据的用户，不限定具体身份。	如 auth::READ，添加凭据后即可获得相应权限。
digest	使用 username:password 形式的 MD5 哈希进行认证，格式为 digest:username:base64(md5(password))。	推荐用于生产环境，密码需加密传输。
ip	基于客户端 IP 地址进行访问控制，如 ip:192.168.1.100:READ。	仅限 IPv4，不支持动态 IP 场景。
x509	基于 X.509 证书的身份认证方式，适用于高安全要求环境。	配置复杂，依赖 TLS 证书体系。
Permissions	权限类型，包括 READ、WRITE、CREATE、DELETE、ADMIN、ALL。	ADMIN 权限允许修改 ACL，需谨慎授予。
权限组合	可为不同身份主体分配不同权限，实现细粒度控制。	错误配置可能导致无法访问或安全漏洞。

第三章：ZooKeeper 集群架构与部署

3.1 集群角色（Leader、Follower、Observer）

角色名称	说明	注意事项
Leader	集群中的主节点，负责处理所有写请求、发起投票、广播事务提案（Proposal）并提交（Commit）。	每个集群有且仅有一个 Leader；通过 ZAB 协议选举产生。
Follower	参与选举投票，接收客户端读请求，将写请求转发给 Leader，并参与事务投票。	多个 Follower 提高可用性和读性能；必须参与过半投票才能通过写操作。
Observer	不参与选举和投票，仅同步 Leader 的状态更新，可处理读请求以扩展读能力。	适用于大规模集群中提升读吞吐，但不增加写一致性开销。
角色转换	节点启动时为 LOOKING 状态，通过选举确定 Leader 后，其余节点成为 Follower 或 Observer。	网络分区可能导致脑裂，需保证奇数个投票节点（Follower）避免平票。
Quorum	参与投票的节点集合（Leader + Follower），写操作需获得超过半数节点确认。	建议部署 3、5、7 等奇数个投票节点以提高容错能力。

3.2 ZAB 协议简介

概念名称	说明	注意事项
ZAB（ZooKeeper Atomic Broadcast）	ZooKeeper 原子广播协议，是 ZooKeeper 实现数据一致性的核心协议，基于 Paxos 改进。	保证全局顺序性和强一致性。
协议阶段	包括恢复阶段（Leader 选举 + 数据同步）和广播阶段（事务广播）。	恢复阶段确保系统从故障中正确恢复。
Leader 选举	当无 Leader 或 Leader 失效时，各节点发起投票，选出新 Leader。	使用 zxid 和 server id 决定优先级，zxid 越大越优先。
数据同步（Sync）	新 Leader 与 Follower 同步状态，确保所有节点具有相同的数据视图。	包括 DIFF（增量同步）、TRUNC（回滚）、SNAP（全量快照）三种方式。
事务广播	所有写操作由 Leader 转为 Proposal 并广播，Follower 回应 ACK，Leader 收到过半 ACK 后提交。	读操作不参与 ZAB 流程，由本地节点直接响应。
zxid（事务 ID）	全局唯一 64 位事务标识，前 32 位为 epoch（纪元编号），后 32 位为事务计数器。	zxid 决定操作顺序，用于选举和数据同步判断。
崩溃恢复	当 Leader 崩溃后，ZAB 协议确保新 Leader 包含所有已提交的事务，防止数据丢失。	依赖持久化日志和快照文件。

3.3 单机模式部署

步骤	操作说明	示例/参数	注意事项
下载 ZooKeeper	从 Apache 官网下载稳定版本压缩包	wget https://archive.apache.org/dist/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4-bin.tar.gz	建议使用 3.5+ 版本，支持动态配置和 Observer。
解压安装包	解压到指定目录	tar -xzf apache-zookeeper-3.8.4-bin.tar.gz -C /opt/	使用专用用户运行，避免 root 权限。
创建配置文件	复制并编辑 zoo.cfg	cp conf/zoo_sample.cfg conf/zoo.cfg	单机模式无需 server.x 配置。
配置参数	编辑 zoo.cfg 设置基本参数	tickTime=2000 dataDir=/var/lib/zookeeper clientPort=2181	dataDir 应指向独立磁盘以提高 I/O 性能。
启动服务	使用脚本启动 ZooKeeper 服务	bin/zkServer.sh start	可使用 status 查看运行状态。
日志目录	默认日志输出到控制台，建议重定向	nohup bin/zkServer.sh start > zookeeper.out 2>&1 &	配置 log4j.properties 可定制日志级别。
连接测试	使用客户端连接验证	bin/zkCli.sh -server localhost:2181	成功连接后可执行 ls / 等命令测试。

3.4 集群模式部署

步骤	操作说明	示例/参数	注意事项
准备节点	至少准备 3 台服务器（推荐奇数台）	node1: 192.168.1.101, node2: 192.168.1.102, node3: 192.168.1.103	所有节点时间应同步（使用 NTP）。
安装 ZooKeeper	在每台机器上完成解压和基础配置	同 3.3 节步骤	保持版本一致。
配置 zoo.cfg	在每个节点配置相同的 zoo.cfg 并添加集群信息	tickTime=2000 dataDir=/var/lib/zookeeper clientPort=2181 initLimit=10 syncLimit=5 server.1=node1:2888:3888 server.2=node2:2888:3888 server.3=node3:2888:3888	2888 为 Follower 与 Leader 通信端口，3888 为选举通信端口。
创建 myid 文件	在 dataDir 目录下创建 myid 文件，写入唯一 ID	echo "1" > /var/lib/zookeeper/myid	每个节点 myid 必须唯一且在 server.x 中定义。
启动集群	按顺序或并行启动各节点	bin/zkServer.sh start	先启动多数节点以加快选举。
验证状态	检查各节点角色	bin/zkServer.sh status	应显示 Leader 或 Follower。
防火墙设置	开放必要端口	2181（客户端）、2888（Follower 通信）、3888（选举）	生产环境需配置安全组或 iptables。

3.5 配置文件详解（zoo.cfg）

配置项	说明	典型值	注意事项
tickTime	ZooKeeper 的基本时间单位（毫秒），心跳和超时基于此计算	2000	不宜过小，避免网络抖动误判。
dataDir	内存数据库快照的存储目录	/var/lib/zookeeper	必须存在且可写，建议独立磁盘。
dataLogDir	事务日志存储目录（可选），若未设置则使用 dataDir	/var/lib/zookeeper/log	分离日志和快照可提升性能。
clientPort	客户端连接端口	2181	可修改，但需同步客户端配置。
initLimit	Follower 启动时与 Leader 完成数据同步的最大 tick 数	10	即 10 * tickTime，大数据量时应调大。
syncLimit	Follower 与 Leader 心跳检测的最大延迟 tick 数	5	控制网络延迟容忍度。
server.x	定义集群节点，x 为 myid，格式为 host:peerPort:leaderPort	server.1=node1:2888:3888	peerPort 用于数据同步，leaderPort 用于选举。
maxClientCnxns	每个 IP 允许的最大客户端连接数	60	防止 DDoS，高并发场景可调大。
autopurge.snapRetainCount	自动清理后保留的快照数量	3	配合 autopurge.purgeInterval 使用。
autopurge.purgeInterval	自动清理旧日志和快照的时间间隔（小时）	24	设置为 0 表示禁用自动清理。
standaloneEnabled	是否允许单机模式运行（3.5+）	false	设为 false 可强制启用集群特性。
peerType	节点类型（participant 或 observer）	peerType=observer	用于配置 Observer 节点。

第四章：ZooKeeper 命令行操作

4.1 客户端连接与基本命令

命令	语法	用途	示例	注意事项
connect	connect [host:port]	连接到 ZooKeeper 服务器	connect localhost:2181	若未指定则连接到默认地址。
close	close	关闭当前连接	close	断开后会话进入 CLOSED 状态。
help	help	显示所有可用命令	help	初学者常用。
quit	quit	退出客户端	quit	等同于 exit。
history	history	显示命令历史	history	可结合 !n 重新执行第 n 条命令。
printwatches	printwatches on/off	设置是否打印 Watcher 事件	printwatches on	默认开启，调试时有用。
srvr（四字命令）	echo srvr | nc localhost 2181	查看服务器状态信息	echo srvr | nc localhost 2181	需启用四字命令白名单。
stat（四字命令）	echo stat | nc localhost 2181	查看服务器统计信息	echo stat | nc localhost 2181	包括连接数、延迟等。

4.2 ZNode 管理命令（create, get, set, delete 等）

命令	语法	用途	示例	注意事项
create	create [-s] [-e] path data acl	创建 ZNode	create /app "data"	默认为持久节点；-s：顺序，-e：临时
get	get path [watch]	获取节点数据和元信息	get /app	添加 watch 参数可注册监听
set	set path data [version]	更新节点数据	set /app "new_data"	version 可用于乐观锁控制
delete	delete path [version]	删除节点（仅当无子节点）	delete /app	不支持递归删除
deleteall	deleteall path	递归删除节点及其所有子节点	deleteall /app	非原生命令，客户端工具提供
ls	ls path [watch]	列出子节点	ls /	支持嵌套路径如 /app/config
ls2	ls2 path [watch]	同 ls，但包含节点状态信息	ls2 /app	已被 ls -s 替代
sync	sync path	强制客户端与 ZooKeeper 状态同步	sync /app	保证后续读取是最新的
stat	stat path [watch]	查看节点状态（不返回数据）	stat /app	返回 czxid, mzxid, version 等

4.3 Watcher 使用命令

命令	语法	用途	示例	注意事项
get	get path watch	为节点注册数据变更 Watcher	get /app true	仅触发一次，变更数据时通知
ls	ls path watch	为节点注册子节点变更 Watcher	ls /app true	子节点增删时触发
stat	stat path watch	注册节点状态变更 Watcher	stat /app true	如 ACL 修改、节点删除
Watcher 事件输出	WATCHER::	客户端收到事件通知格式	WATCHER:: WatchedEvent state:SyncConnected type:NodeDataChanged path:/app	包含状态、事件类型和路径
事件类型	NodeCreated, NodeDeleted, NodeDataChanged, NodeChildrenChanged, None	五种标准事件类型	—	None 通常表示连接状态变化
一次性机制	无专用命令	Watcher 被触发后自动失效	—	必须在处理逻辑中重新注册才能继续监听
重复注册	在事件处理后再次执行 get/ls + watch	实现持续监听	get /app true	编程中需注意异常处理

4.4 ACL 相关命令（setAcl, getAcl）

命令	语法	用途	示例	注意事项
getAcl	getAcl path	获取节点的 ACL 列表	getAcl /app	输出 scheme:id 和 permissions
setAcl	setAcl path acl	设置节点的 ACL	setAcl /app world:anyone:r	必须具有 ADMIN 权限才能设置
create	create path data acl	创建节点时指定 ACL	create /secure "data" auth:user:password:cdrwa	acl 可在创建时设定
ACL 格式	scheme:id:permissions	定义权限规则	digest:user:base64(md5(pass)):cdrwa	permissions 为组合字母
权限字母	r=read, w=write, c=create, d=delete, a=admin	权限缩写	cdrwa 表示全部权限	admin 权限可修改 ACL
digest 认证	addauth digest user:password	添加认证信息以通过 ACL 检查	addauth digest admin:123456	必须先认证才能访问受保护节点
world:anyone	最宽松权限	setAcl /public world:anyone:r	任何客户端都可读	—
ip 限制	setAcl /internal ip:192.168.1.100:rw	基于 IP 的访问控制	—	仅 IPv4 支持

第五章：ZooKeeper Java API 编程

5.1 客户端初始化（ZooKeeper 类构造）

方法/构造	语法	用途	代码示例	注意事项
ZooKeeper 构造函数	new ZooKeeper(String connectString, int sessionTimeout, Watcher watcher)	初始化客户端连接，指定连接地址、会话超时和根 Watcher	见下方代码块	watcher 用于接收连接状态事件（如 SyncConnected）
带会话复用的构造	new ZooKeeper(String connectString, int sessionTimeout, Watcher watcher, long sessionId, byte[] sessionPasswd)	复用已有会话（如故障恢复）	见下方代码块	需安全保存 sessionPasswd，否则会话失效
connectString	"host1:port,host2:port,..."	指定 ZooKeeper 集群地址列表	"node1:2181,node2:2181,node3:2181"	客户端会自动选择可用节点连接
sessionTimeout	int 类型，单位毫秒	会话超时时间，通常设为 2~10 秒	5000 表示 5 秒	过短易断连，过长故障发现延迟
Watcher 参数	实现 Watcher 接口的对象	接收连接状态变化事件	可传 null，但建议设置以监控连接状态	根 Watcher 主要处理 None 类型事件

ZooKeeper 构造函数示例：

ZooKeeper zk = new ZooKeeper("localhost:2181", 5000, new Watcher() {
    public void process(WatchedEvent event) {
        System.out.println("Event: " + event);
    }
});

带会话复用的构造示例：

long sid = zk.getSessionId();
byte[] passwd = zk.getSessionPasswd();
// 重启后使用：
new ZooKeeper("localhost:2181", 5000, watcher, sid, passwd);

5.2 连接管理与会话处理

方法	语法	用途	代码示例	注意事项
getState()	zk.getState()	获取当前客户端连接状态	if (zk.getState() == ZooKeeper.States.CONNECTED) { System.out.println("Connected"); }	状态包括 CONNECTING, CONNECTED, CLOSED 等
getSessionId()	zk.getSessionId()	获取当前会话 ID	long sid = zk.getSessionId();	只读，可用于日志追踪
getSessionPasswd()	zk.getSessionPasswd()	获取会话密钥	byte[] passwd = zk.getSessionPasswd();	用于会话复用，需加密存储
close()	zk.close()	关闭客户端连接，释放资源	zk.close();	关闭后所有临时节点将被删除
重连机制	在 Watcher 中监听状态变化	实现自动重连逻辑	见下方代码块	会话过期后必须重新创建 ZooKeeper 实例
连接超时处理	设置合理的 sessionTimeout	避免网络抖动导致误断	建议设置为心跳间隔的 2~3 倍	默认 tickTime 为 2s，initLimit=10 → 20s

重连机制示例：

public void process(WatchedEvent event) {
    if (event.getState() == KeeperState.Expired) {
        // 重建连接
    }
}

5.3 同步创建 ZNode（create）

方法	语法	用途	代码示例	注意事项
create	String create(String path, byte[] data, List<ACL> acl, CreateMode createMode)	同步创建节点，返回实际路径	见下方代码块	如果是顺序节点，返回值包含自动生成的序号
path	节点路径	必须是绝对路径	"/config/db"	路径不能以空格或特殊字符开头
data	byte[] 类型数据	存储节点内容	"value".getBytes(StandardCharsets.UTF_8)	最大 1MB，建议小于 1KB
acl	List<ACL> 类型	访问控制列表	ZooDefs.Ids.OPEN_ACL_UNSAFE（所有人可读写）	可自定义权限，如 digest 认证
CreateMode	枚举类型	指定节点类型	PERSISTENT, PERSISTENT_SEQUENTIAL, EPHEMERAL, EPHEMERAL_SEQUENTIAL	临时节点不能有子节点
异常处理	throws KeeperException, InterruptedException	必须捕获异常	KeeperException.NodeExistsException：节点已存在，KeeperException.ConnectionLossException：连接中断	建议重试机制处理连接异常

同步创建示例：

try {
    String actualPath = zk.create("/app", "data".getBytes(),
            ZooDefs.Ids.OPEN_ACL_UNSAFE,
            CreateMode.PERSISTENT);
    System.out.println("Created: " + actualPath);
} catch (Exception e) {
    e.printStackTrace();
}

5.4 同步读取 ZNode（getData, getChildren）

方法	语法	用途	代码示例	注意事项
getData	byte[] getData(String path, boolean watch, Stat stat)	读取节点数据	见下方代码块	watch=true 表示注册 Watcher
getChildren	List<String> getChildren(String path, boolean watch)	获取子节点列表	见下方代码块	不返回子节点数据，仅返回名称
watch 参数	boolean 类型	是否注册 Watcher	true：注册一次性的数据或子节点变更监听	事件触发后需重新注册
Stat 对象	输出参数	返回节点元信息	包含 czxid, mzxid, version, ctime, mtime, dataLength, childrenCount 等	可传 null，但建议使用以获取版本信息
节点不存在	KeeperException.NoNodeException	路径不存在时抛出	if (!zk.exists("/app", false)) { zk.create(...); }	建议先检查是否存在

getData 示例：

try {
    Stat stat = new Stat();
    byte[] data = zk.getData("/app", true, stat);
    System.out.println("Data: " + new String(data));
} catch (Exception e) {
    e.printStackTrace();
}

getChildren 示例：

try {
    List<String> children = zk.getChildren("/app", false);
    System.out.println("Children: " + children);
} catch (Exception e) {
    e.printStackTrace();
}

5.5 同步更新与删除 ZNode（setData, delete）

方法	语法	用途	代码示例	注意事项
setData	Stat setData(String path, byte[] data, int version)	更新节点数据	见下方代码块	version=-1 表示忽略版本（强制更新）
delete	void delete(String path, int version)	删除节点（必须无子节点）	见下方代码块	支持版本控制，version=-1 表示任意版本
version 参数	int 类型	乐观锁机制	使用 Stat.getVersion() 获取当前版本	若版本不匹配，抛出 BadVersionException
递归删除	无原生方法	需手动遍历删除子节点	使用递归或第三方工具类实现	建议封装 deleteAll 工具方法
删除临时节点	delete()	显式删除或会话结束自动删除	临时节点在会话失效时自动清理	不可删除其他会话创建的临时节点

setData 示例：

try {
    Stat stat = zk.setData("/app", "new_data".getBytes(), -1);
    System.out.println("New version: " + stat.getVersion());
} catch (Exception e) {
    e.printStackTrace();
}

delete 示例：

try {
    zk.delete("/app/temp", -1);
} catch (Exception e) {
    e.printStackTrace();
}

5.6 异步 API 操作详解

方法	语法	用途	代码示例	注意事项
createAsync	void create(String path, byte[] data, List<ACL> acl, CreateMode createMode, AsyncCallback.StringCallback cb, Object ctx)	异步创建节点	见下方代码块	非阻塞，适合高并发场景
getDataAsync	void getData(String path, boolean watch, AsyncCallback.DataCallback cb, Object ctx)	异步读取数据	见下方代码块	回调中处理结果
setDataAsync	void setData(String path, byte[] data, int version, AsyncCallback.StatCallback cb, Object ctx)	异步更新数据	见下方代码块	rc=0 表示成功
deleteAsync	void delete(String path, int version, AsyncCallback.VoidCallback cb, Object ctx)	异步删除节点	见下方代码块	不返回值，仅通知结果
AsyncCallback 接口	四种回调：StringCallback, DataCallback, StatCallback, VoidCallback	处理异步结果	所有回调在单一线程中串行执行	不要在回调中执行耗时操作
rc（Result Code）	int 类型	表示操作结果	0=OK, -4=ConnectionLoss, -101=NodeExists, -102=NoNode 等	需根据 rc 判断是否重试

异步创建示例：

zk.create("/async", "data".getBytes(),
        ZooDefs.Ids.OPEN_ACL_UNSAFE,
        CreateMode.PERSISTENT,
        new AsyncCallback.StringCallback() {
            public void processResult(int rc, String path, Object ctx, String name) {
                System.out.println("rc=" + rc + ", name=" + name);
            }
        }, null);

异步读取示例：

zk.getData("/app", false, new AsyncCallback.DataCallback() {
    public void processResult(int rc, String path, Object ctx, byte[] data, Stat stat) {
        if (rc == 0) System.out.println(new String(data));
    }
}, null);

异步更新示例：

zk.setData("/app", "new".getBytes(), -1, new AsyncCallback.StatCallback() {
    public void processResult(int rc, String path, Object ctx, Stat stat) {
        System.out.println("Updated: " + rc);
    }
}, null);

异步删除示例：

zk.delete("/temp", -1, new AsyncCallback.VoidCallback() {
    public void processResult(int rc, String path, Object ctx) {
        System.out.println("Deleted: " + (rc == 0));
    }
}, null);

5.7 Watcher 注册与事件处理

方法	语法	用途	代码示例	注意事项
process(WatchedEvent)	public void process(WatchedEvent event)	实现 Watcher 接口处理事件	见下方代码块	必须实现此方法
WatchedEvent.getType()	event.getType()	获取事件类型	NodeCreated, NodeDeleted, NodeDataChanged, NodeChildrenChanged, None	None 通常表示连接状态变化
WatchedEvent.getPath()	event.getPath()	获取事件关联路径	String path = event.getPath();	用于定位变更节点
一次性机制	无	Watcher 触发后自动失效	必须在处理逻辑中重新调用 getData/ls 并设 watch=true	忘记重注册是常见 Bug
重复注册	在事件处理中重新注册	实现持续监听	见 5.4 节 getData 示例	建议封装为通用监听器
多 Watcher 管理	使用不同的 Watcher 实例	区分连接状态与数据变更	根 Watcher 处理 None，业务 Watcher 处理数据变更	避免混淆

Watcher 事件处理示例：

public void process(WatchedEvent event) {
    if (event.getType() == Event.EventType.NodeDataChanged) {
        // 重新读取并注册 Watcher
    }
}

5.8 权限控制 API（setAcl, getAcl）

方法	语法	用途	代码示例	注意事项
getAcl	void getAcl(String path, AsyncCallback.ACLCallback cb, Object ctx)	异步获取 ACL	见下方代码块	同步版本为 List<ACL> getAcl(path, Stat stat)
setAcl	void setAcl(String path, List<ACL> acl, int version, AsyncCallback.VoidCallback cb, Object ctx)	异步设置 ACL	见下方代码块	必须具有 ADMIN 权限
addAuthInfo	void addAuthInfo(String scheme, byte[] auth)	添加认证信息	zk.addAuthInfo("digest", "user:pass".getBytes());	必须在操作前调用
ZooDefs.Ids	内置 ACL 常量	提供常用 ACL	OPEN_ACL_UNSAFE：所有人可读写，READ_ACL_UNSAFE：所有人只读，CREATOR_ALL_ACL：创建者全权	生产环境应使用 digest
ACL 结构	new ACL(perms, id)	自定义 ACL	new ACL(ZooDefs.Perms.READ, new Id("ip", "192.168.1.100"))	perms 为位掩码

getAcl 示例：

zk.getAcl("/secure", new AsyncCallback.ACLCallback() {
    public void processResult(int rc, String path, Object ctx, List<ACL> acl, Stat stat) {
        System.out.println("ACL: " + acl);
    }
}, null);

setAcl 示例：

List<ACL> acl = ZooDefs.Ids.parseACLs("digest:user:pass:cdrwa");
zk.setAcl("/secure", acl, -1, new AsyncCallback.VoidCallback() {
    public void processResult(int rc, String path, Object ctx) {
        System.out.println("ACL set: " + (rc == 0));
    }
}, null);

5.9 常用辅助类与工具方法

类/方法	说明	用途	示例	注意事项
ZooKeeper	主客户端类	所有操作入口	new ZooKeeper(...)	核心类
ZooDefs	常量定义类	提供 ACL、权限等常量	ZooDefs.Ids.OPEN_ACL_UNSAFE	避免硬编码
CreateMode	枚举类	节点类型	CreateMode.EPHEMERAL_SEQUENTIAL	类型安全
KeeperException	异常基类	所有 ZooKeeper 操作异常	catch (NodeExistsException e)	细化处理不同异常
InterruptedException	Java 标准异常	线程中断	在 finally 中关闭资源	建议包装为运行时异常
Stat	元信息类	存储节点状态	new Stat() 作为输出参数	包含版本、时间、大小等
WatchedEvent	事件类	传递事件信息	event.getType(), event.getPath()	用于 Watcher 回调
AsyncCallback	回调接口	异步操作结果处理	StringCallback, DataCallback 等	避免阻塞回调线程

第六章：ZooKeeper 典型应用场景实现

6.1 分布式锁实现

步骤	说明	代码逻辑要点	注意事项
锁路径	使用临时顺序节点	path = "/locks/lock_"	所有竞争者在同一父节点下创建节点
创建节点	每个客户端创建 EPHEMERAL_SEQUENTIAL 节点	zk.create(path, data, OPEN_ACL_UNSAFE, EPHEMERAL_SEQUENTIAL)	获取返回的实际路径（含序号）
判断最小序号	检查自己是否为最小序号节点	获取子节点列表，排序，判断自己是否排第一	是则获得锁
监听前驱节点	若非最小，监听前一个节点的删除事件	使用 getChildren 并注册 Watcher	前驱释放锁时触发
释放锁	删除自己的临时节点	zk.delete(myPath, -1)	会话结束也会自动释放
重复注册	Watcher 触发后重新检查并注册	在 process() 中重新获取列表并监听新前驱	防止遗漏事件
超时机制	可设置锁超时	记录创建时间，超过阈值自动放弃	避免死锁

6.2 集群选主（Leader Election）

步骤	说明	代码逻辑要点	注意事项
选举路径	所有候选者在同一路径下竞争	"/election/candidate_"	临时顺序节点
创建节点	每个节点创建 EPHEMERAL_SEQUENTIAL 节点	获取返回路径（含序号）	序号最小者为 Leader
检查序号	获取子节点并排序	Collections.sort(children)	判断自己是否最小
成为 Leader	最小序号节点开始执行主节点任务	启动服务、广播状态等	需处理故障恢复
监听前驱	非 Leader 节点监听前一个节点	一旦前驱消失，重新检查序号	实现自动再选举
故障恢复	Leader 宕机后自动选出新 Leader	临时节点自动删除，触发选举	保证高可用
避免羊群效应	不监听所有节点，仅监听直接前驱	减少 Watcher 数量	提升性能

6.3 配置中心管理

步骤	说明	代码逻辑要点	注意事项
配置路径	将配置存储为持久节点	"/config/app/db_url"	层级结构便于管理
读取配置	客户端启动时读取	zk.getData("/config/app", true, stat)	注册 Watcher
监听变更	配置更新时收到通知	在 Watcher 中重新加载配置	实现动态刷新
更新配置	管理员通过工具或 API 修改	zk.setData("/config/app", newBytes, -1)	版本控制可防止冲突
权限控制	设置 ACL 限制写权限	setAcl("/config", digest:admin:pass:cdrwa)	防止未授权修改
数据格式	使用 JSON、Properties 等可读格式	存储为字符串 byte[]	建议压缩大配置
一致性保证	所有节点看到相同配置	ZooKeeper 强一致性保证	优于本地文件

6.4 服务注册与发现

步骤	说明	代码逻辑要点	注意事项
服务路径	按服务名组织	"/services/user-service/"	持久节点作为根
注册服务	服务启动时创建临时节点	zk.create("/services/user/192.168.1.10:8080", info, PERSISTENT, EPHEMERAL)	节点数据可包含 IP、端口、元数据
发现服务	消费者获取子节点列表	zk.getChildren("/services/user", true)	注册 Watcher 监听变化
监听变更	服务上下线时更新本地缓存	在 Watcher 中重新获取列表	实现动态路由
健康检查	临时节点自动删除实现故障检测	服务崩溃后节点消失	不依赖心跳
负载均衡	客户端从列表中选择实例	随机、轮询、权重等策略	结合 Ribbon 等框架
命名空间隔离	使用不同路径区分环境	/services/prod/, /services/dev/	避免冲突

6.5 分布式队列与屏障

类型	说明	实现方式	注意事项
FIFO 队列	先进先出队列	使用 PERSISTENT_SEQUENTIAL 节点，按序号消费	生产者创建，消费者按最小序号取出并删除
消费逻辑	消费者监听子节点变化	获取最小序号节点，处理后删除	需处理并发消费冲突
屏障（Barrier）	集合点同步	创建屏障节点 "/barrier"，所有节点到达后继续	使用 exists(path, true) 注册监听
集合完成判断	最后一个节点到达时删除屏障	通过计数判断是否全部到达	其他节点收到 NodeDeleted 事件后继续
双屏障	开始和结束都同步	先等待所有节点到达，再等待全部完成	用于分布式计算任务协调
性能考虑	大规模队列影响性能	建议使用 Kafka 等专用消息队列	ZooKeeper 适合轻量级协调场景

第七章：ZooKeeper 运维与监控

7.1 四字命令（Four Letter Words）

命令	语法	用途	示例	注意事项
stat	echo stat | nc localhost 2181	查看服务器状态和客户端连接信息	echo stat | nc node1 2181	包含版本、延迟、连接数等
srvr	echo srvr | nc localhost 2181	仅显示服务器基本信息（不包含客户端）	echo srvr | nc node1 2181	输出更简洁，适合脚本解析
conf	echo conf | nc localhost 2181	显示当前配置参数	echo conf | nc node1 2181	包括 tickTime、dataDir、clientPort 等
cons	echo cons | nc localhost 2181	列出所有客户端连接及其会话信息	echo cons | nc node1 2181	可用于排查异常连接
dump	echo dump | nc localhost 2181	列出所有会话及其临时节点	echo dump | nc leader_node 2181	仅 Leader 支持，用于故障分析
envi	echo envi | nc localhost 2181	显示服务器环境变量	echo envi | nc node1 2181	包括 Java 版本、操作系统等
ruok	echo ruok | nc localhost 2181	检查服务器是否正常运行	echo ruok | nc node1 2181	正常返回 “imok”
srst	echo srst | nc localhost 2181	重置统计信息	echo srst | nc node1 2181	清零所有计数器
wchs	echo wchs | nc localhost 2181	列出 Watcher 概览（每个路径的 Watcher 数量）	echo wchs | nc node1 2181	诊断 Watcher 泄露
wchc	echo wchc | nc localhost 2181	按会话列出所有 Watcher	echo wchc | nc node1 2181	输出较大，可能阻塞服务
wchp	echo wchp | nc localhost 2181	按路径列出所有 Watcher	echo wchp | nc node1 2181	用于分析热点路径
mntr	echo mntr | nc localhost 2181	输出机器可读的监控指标	echo mntr | nc node1 2181	适合集成到 Prometheus 等监控系统
isro	echo isro | nc localhost 2181	判断是否处于只读模式	echo isro | nc observer_node 2181	Observer 返回 “ro”，其他返回 “rw”
配置启用	4lw.commands.whitelist=stat,srvr,ruok,mntr	在 zoo.cfg 中配置白名单	默认从 3.4.13 / 3.5.3 起需显式启用	禁用危险命令如 kill、crst

7.2 日志与快照管理

文件类型	存储路径	说明	管理建议	注意事项
事务日志（Transaction Log）	dataLogDir 或 dataDir 下的 log.* 文件	记录所有写操作的持久化日志	建议独立磁盘存放，避免 I/O 争抢	文件按 zxid 命名，如 log.100000001
快照文件（Snapshot）	dataDir 下的 snapshot.* 文件	内存数据库某一时刻的全量快照	定期清理旧快照	文件按 zxid 命名，如 snapshot.10000000a
自动清理配置	autopurge.snapRetainCount=3 autopurge.purgeInterval=24	保留最近 3 个快照，每天清理一次	在 zoo.cfg 中设置	purgeInterval=0 表示禁用自动清理
手动清理脚本	使用 zkCleanup.sh 工具	清理指定天数前的日志和快照	bin/zkCleanup.sh /var/lib/zookeeper -n 3	-n 表示保留最近 N 个快照
日志滚动机制	写满一个日志文件后创建新文件	基于 zxid 分段	不可手动删除正在写入的日志	—
恢复机制	启动时加载最新快照 + 重放日志	确保数据一致性	快照越新，恢复越快	—
磁盘空间监控	定期检查 dataLogDir 和 dataDir 使用率	避免磁盘写满导致服务中断	建议预留 50% 以上空间	—
日志压缩	无内置压缩	可外部归档压缩	注意保留足够恢复所需的日志	—

7.3 性能调优建议

调优项	建议值	说明	注意事项
tickTime	2000~3000 ms	基本时间单位	过小增加网络压力，过大影响响应速度
initLimit	10~15	Follower 启动同步最大 tick 数	大数据量时应调大，避免同步超时
syncLimit	5~7	Follower 与 Leader 心跳最大延迟	控制网络抖动容忍度
maxClientCnxns	60~100	每 IP 最大连接数	高并发客户端可调大，防 DDoS
dataLogDir	独立高速磁盘	分离事务日志与快照	提升 I/O 性能
JVM 堆大小	4GB~8GB（≤8GB）	避免长时间 GC 停顿	推荐使用 G1GC 垃圾回收器
Observer 使用	启用 Observer 节点	扩展读能力，减轻 Follower 负担	适用于读多写少场景
会话超时	2 * tickTime ~ 10 * tickTime	客户端设置	过短易断连，过长故障发现慢
Watcher 数量	避免热点路径大量 Watcher	减少 wchp 输出大小	防止事件风暴
节点数据大小	< 1KB，最大 1MB	小数据块提升性能	大数据建议存外部存储，ZK 存引用

7.4 监控指标与工具

指标类别	关键指标	获取方式	告警阈值	说明
基本状态	zk_server_state	mntr 命令	Leader/Follower/Observer	观察角色是否正常
	zk_znode_count	mntr 命令	持续增长需关注	当前节点总数
	zk_outstanding_requests	mntr 命令	>1000 警告	待处理请求数，反映负载
延迟	zk_avg_latency	mntr 命令	>100ms 警告	平均请求延迟
	zk_max_latency	mntr 命令	>500ms 严重	最大延迟，可能有慢请求
连接	zk_num_alive_connections	mntr 命令	突增或突降	当前活跃连接数
	zk_packets_received / zk_packets_sent	mntr 命令	对比历史基线	网络流量趋势
会话	zk_num_alive_clients	dump 命令或监控系统	—	当前活跃会话数
	zk_expired_time_outs	自定义监控	>0 警告	会话过期次数，反映稳定性
选举	zk_leader_election_status	日志或自定义	非 0 表示正在选举	频繁选举需排查网络
磁盘	dataDir / dataLogDir 使用率	系统监控	>80% 警告	防止写满
工具	Prometheus + Grafana	配置 JMX Exporter 或脚本采集 mntr	—	可视化展示
	Zabbix / Nagios	自定义脚本调用四字命令	—	传统监控集成
	ELK / Splunk	收集 zookeeper.out 日志	—	分析异常和选举日志

第八章：ZooKeeper 常见问题与最佳实践

8.1 连接超时与会话过期处理

问题	原因	解决方案	注意事项
ConnectionLossException	网络抖动、Leader 选举、GC 停顿	重试机制（指数退避）	建议重试 3~5 次，间隔递增
SessionExpiredException	会话超时未恢复	重建 ZooKeeper 实例，重新初始化状态	临时节点已丢失，需重新注册
连接超时	客户端设置 connectTimeout	合理设置超时时间	通常 5~15 秒
会话超时	sessionTimeout 设置过短	根据网络状况调整（建议 10~30 秒）	过长导致故障发现延迟
自动重连	客户端未实现重连逻辑	在 Watcher 中监听 Expired 事件并重建连接	保存 sessionPasswd 可复用会话
临时节点丢失	会话过期后自动删除	重新创建临时节点（如服务注册）	分布式锁需重新竞争
预防措施	网络不稳定、GC 压力大	优化网络、调整 JVM、使用 Observer	保证客户端与服务器时间同步

8.2 Watcher 的一次性与重复注册

问题	说明	解决方案	注意事项
一次性机制	Watcher 触发一次后自动失效	必须在事件处理中重新注册	忘记重注册是常见 Bug
重复注册逻辑	在 process() 方法中再次调用 getData/ls 并设 watch=true	实现持续监听	建议封装通用监听器类
事件丢失	网络中断期间变更未收到通知	结合版本号（Stat）判断数据是否变化	不能完全依赖 Watcher
羊群效应	所有客户端监听同一路径	改为监听特定节点或使用队列	避免大规模通知风暴
异步处理	Watcher 回调在单一线程执行	不要在回调中执行耗时操作	否则阻塞其他事件
批量变更	多个变更合并为一个事件	ZooKeeper 不保证每个变更都通知	应通过读取最新状态处理
调试技巧	使用 wchs 命令查看当前 Watcher 数量	诊断泄露或未注册问题	生产环境谨慎使用 wchc/wchp

8.3 脑裂与可用性保障

问题	说明	解决方案	注意事项
脑裂（Split Brain）	网络分区导致多个子集群各自选举 Leader	部署奇数个投票节点（Follower）	3 节点可容忍 1 故障，5 节点容忍 2
Quorum 机制	写操作需过半节点确认	保证数据一致性	2 节点集群无容错能力
Observer 使用	扩展读服务而不参与投票	提升读吞吐，降低写压力	适用于跨数据中心部署
多机房部署	避免单机房故障	推荐同一机房部署投票节点，跨机房使用 Observer	跨机房延迟高，影响选举
故障恢复	节点重启后自动加入集群	通过 ZAB 协议同步状态	确保 dataDir 正确挂载
数据一致性	ZAB 协议保证	所有写操作全局有序	读操作可能滞后（最终一致）
避免单点	不依赖单台服务器	使用集群模式，至少 3 节点	单机模式仅用于测试

8.4 数据一致性与顺序性保证

特性	说明	保障机制	注意事项
顺序一致性	所有客户端看到相同的操作顺序	ZAB 协议全局广播，zxid 全局唯一	满足 CP 系统要求
原子性	写操作要么全部成功，要么失败	两阶段提交（Proposal + Commit）	客户端收到成功即已持久化
单调递增 zxid	每个事务有唯一且递增的 ID	64 位，前 32 位为 epoch，后 32 位为计数	用于选举和同步判断
全局顺序	所有更新操作按 zxid 排序	客户端可依赖此顺序实现逻辑	如分布式队列按序消费
读写一致性	读操作返回最新已提交数据	Follower 本地读，但保证不超过 Leader	可能短暂滞后
会话一致性	同一会话中，读请求不会看到回退	客户端连接的服务器会跟踪会话进度	重连后可能看到旧数据
客观时间	不依赖物理时钟	使用 zxid 和版本号控制	避免使用本地时间做判断

8.5 生产环境最佳实践

实践项	建议	说明	注意事项
集群规模	3、5、7 个投票节点	奇数个便于选举，5 节点适合跨机房	避免 2 或 4 节点
硬件配置	独立磁盘（SSD）给 dataLogDir	事务日志顺序写，I/O 敏感	dataDir 可用普通磁盘
JVM 设置	-Xmx8g -Xms8g -XX:+UseG1GC	避免 Full GC 导致超时	堆不宜过大
版本选择	使用 3.5.x 或 3.6.x 稳定版	支持动态配置、容器化、Observer	避免使用 EOL 版本
安全配置	启用 ACL，使用 digest 认证	限制写权限，防止未授权访问	禁用 world:anyone:cdrwa
监控告警	集成 Prometheus/Grafana，监控关键指标	设置延迟、连接数、会话过期等告警	定期演练故障恢复
备份策略	定期备份 dataDir（快照 + 日志）	灾难恢复	结合外部备份系统
变更管理	使用 zkCli.sh 或自动化工具	避免手动误操作	变更前评估影响
客户端设计	实现重连、重试、Watch 重注册	提升容错能力	封装通用 ZooKeeper 客户端
避免滥用	不用于存储大文件、高频写入	适合协调服务，非通用数据库	大数据存外部系统