ZooKeeper数据模型全过程：znode、Stat、版本CAS、ACL与multi事务

ZooKeeper 的数据模型看起来像文件目录，但它不是分布式文件系统。每个 znode 同时承担命名、少量协调数据、版本元信息、ACL 和子节点关系；写操作经 ZAB 排序，客户端再用 version CAS、临时节点、顺序节点和 Watch 组合出注册发现、锁、选主和配置通知。

真正理解数据模型，要能回答：节点数据和子节点列表是不是同一个版本、临时节点为什么不能有子节点、删除节点应校验哪个版本、顺序后缀能否永久当Long使用、ACL是否自动继承、multi能否同时提交MySQL，以及ConnectionLoss后怎样判断操作是否成功。

一、学习目标

1. 区分 znode 与文件、目录、数据库行。
2. 掌握持久、临时、顺序、容器和 TTL 节点的版本边界。
3. 看懂 Stat 中 zxid、时间、version、ephemeralOwner 等字段。
4. 使用 version、cversion 和 aversion 做正确的并发裁决。
5. 解释 multi 的原子范围和 ConnectionLoss 结果未知。
6. 设计 ACL、认证、chroot 和多环境隔离。
7. 控制 znode 数量、数据大小、路径深度和热点节点。
8. 编写 JDK 8 CAS Demo，并能排查 BadVersion、NoNode、NodeExists。

二、znode树是什么

/
├── services
│   └── stock-service
│       ├── instance-0000000041
│       └── instance-0000000042
├── config
│   └── order-service
└── locks
    └── inventory
        └── SKU-1001

每个 znode 包含：

• 绝对路径中的节点名称。
• 一段字节数组数据。
• 直接子节点名称集合。
• Stat 元数据。
• ACL 列表。
• 节点类型和Session所有权信息。

数据和子节点是两个维度：一个节点既可以有数据，也可以有子节点。不要用“目录节点不能存数据”这种文件系统规则套 ZooKeeper。

三、为什么ZooKeeper不是文件系统

文件系统直觉	ZooKeeper真实边界
文件可存GB数据	znode用于小型协调数据，单请求受jute.maxbuffer等限制
目录和文件类型分离	znode可同时有数据和子节点
可以rename/move	没有通用原子rename树操作
逐块流式读写	数据通常作为整体字节数组读取和替换
适合日志和对象存储	大量业务数据会占内存、Snapshot和网络

ZooKeeper 常见默认最大缓冲区约 1 MiB，但它是协议/序列化边界，不是推荐每个节点塞到 1 MiB。不同Server和Client的 jute.maxbuffer 必须兼容；接近上限的节点会放大网络、内存、Snapshot、恢复和Watch重读成本。

生产配置值通常应保持KB级甚至更小，大文件只存URI、版本和摘要，内容放对象存储或配置系统。

四、路径与命名规则

• 路径必须是以 / 开头的绝对路径。
• / 是根节点。
• 通常不能有连续 /、.、.. 这种相对路径片段。
• 名称不能包含空字符及协议禁止的Unicode范围。
• /zookeeper 是系统保留管理路径，不应承载业务数据。
• ZooKeeper不会自动递归创建父节点，创建子节点前父路径必须存在，除非高层Recipe帮助创建。

业务路径应规范化和编码。不要直接把用户输入拼进路径，避免非法字符、路径逃逸、高基数节点和ACL绕过。

五、节点类型全景

节点类型	Session过期后	是否追加序号	典型用途
Persistent	保留	否	目录、配置、锁父路径
Persistent Sequential	保留	是	持久队列元数据，需明确清理
Ephemeral	删除	否	服务实例、成员在线状态
Ephemeral Sequential	删除	是	分布式锁、业务选主
Container	无子节点后可能被Server异步清理	否	动态子节点容器
Persistent with TTL	TTL条件满足后可清理	可分普通/顺序	有限生命周期协调数据

Container 和 TTL 属于较新版本扩展，Server、Client和功能开关有版本条件。不能在老 ZooKeeper 3.4 集群中复制新 API 示例并假定可用；TTL 节点还可能要求启用扩展节点类型。应以锁定版本官方文档和配置为准。

六、持久节点

持久节点在创建 Session 结束后仍存在，除非显式删除。适合：

• /services、/locks等稳定父路径。
• 少量配置和规则。
• 元数据索引。
• 业务Leader候选目录。

风险：

• 使用Persistent Sequential记录每次事件而不清理，znode数量持续增长。
• 把实例注册错建为持久节点，进程宕机后地址永远残留。
• 父路径由应用随意删除，破坏顺序号和ACL边界。

七、临时节点与Session所有权

临时节点记录 ephemeralOwner，属于创建它的 Session：

flowchart TD
    A["Session创建Ephemeral节点"] --> B["节点记录ephemeralOwner"]
    B --> C{"TCP是否短暂断开"}
    C -- "是但Session未过期" --> D["节点仍保留"]
    C -- "Session过期或正常关闭" --> E["Server删除临时节点"]

标准临时节点不能拥有子节点；尝试创建会得到类似 NoChildrenForEphemerals 的错误。这避免父临时节点随Session消失时留下复杂子树所有权。

临时节点不适合表达永久业务事实。订单已支付不能因为Session过期就被删除；Session只能表达在线成员或当前协调所有权。

八、顺序节点的内部语义

创建时给出前缀：

/locks/order/lock-

Server在名称后追加序号：

/locks/order/lock-0000000042

顺序计数与父节点的子节点变化状态相关，由ZooKeeper原子分配，多个客户端不会得到同一个完整节点名。

8.1 顺序号的边界

传统实现使用有符号32位计数语义并格式化后缀，长期高频创建可能发生溢出。不要假定：

• 后缀永远只有十个数字。
• 字符串字典序永久等于数值顺序。
• 删除并重建父节点后序列仍保持全球单调。
• 不同父路径的序号可以直接比较。

锁队列应使用成熟Recipe解析当前版本节点名；Fencing Token若直接来自顺序后缀，必须保证父路径稳定、理解溢出和重建边界，关键系统可使用独立数据库序列。

九、Container与TTL节点

9.1 Container节点

Container 节点用于容纳动态子节点。当最后一个子节点删除后，Server可能在后台删除空Container。它是异步清理，不应假设“子节点删除响应返回时父节点已经消失”。

如果业务必须永久保留父路径和ACL，不要使用Container。

9.2 TTL节点

TTL节点允许在满足无子节点、超过TTL等条件后清理，具体类型、API和清理时机依版本实现。TTL不是精确定时器：

• 不能要求毫秒级准时删除。
• 不能用作支付超时的唯一事实。
• Server停顿和扫描周期会影响删除时间。
• 业务仍需数据库截止时间和补偿扫描。

十、Stat字段逐个解释

字段	含义	常见用途
czxid	创建节点的事务zxid	审计创建顺序
mzxid	最后修改数据的事务zxid	判断数据变更位置
pzxid	最后修改直接子节点集合的事务zxid	服务目录/锁队列变化
ctime	创建时间	诊断，不用于严格排序
mtime	最后数据修改时间	诊断和展示
version	数据修改版本	setData、delete CAS
cversion	子节点集合修改版本	判断children是否变化
aversion	ACL修改版本	setACL并发控制
ephemeralOwner	临时节点所属Session ID；持久节点通常为0	诊断所有权
dataLength	数据字节长度	容量检查
numChildren	直接子节点数量	目录和锁队列检查

ctime/mtime来自Server时间，不能提供跨系统严格全局顺序；事务排序看zxid，节点内并发裁决看对应version。

十一、version、cversion、aversion为什么分开

同一节点有三类独立变化：

setData      → version + 1
create/delete child → cversion变化并更新pzxid
setACL       → aversion + 1

修改配置数据时检查 version；管理子节点队列不能拿 version 判断；更新ACL应使用 aversion。混用会让并发冲突漏检或产生无意义失败。

十二、版本CAS全过程

两个管理员同时修改配置：

flowchart TD
    A["Client A读取version=7"] --> C["A提交setData expectedVersion=7"]
    B["Client B读取version=7"] --> D["B提交setData expectedVersion=7"]
    C --> E["ZooKeeper按事务顺序处理"]
    D --> E
    E --> F["第一个成功，version推进到8"]
    F --> G["第二个得到BadVersion"]

BadVersion不是网络错误，而是明确的并发冲突。正确处理：

1. 重新读取当前数据和version。
2. 判断能否合并业务意图。
3. 人工确认或基于新version重试。
4. 不能改用 -1 无条件覆盖来“解决”。

十三、各操作校验什么版本

client.setData().withVersion(expectedDataVersion).forPath(path, bytes);
client.delete().withVersion(expectedDataVersion).forPath(path);
client.setACL().withVersion(expectedAclVersion).forPath(path, aclList);

删除非空节点仍会失败，ZooKeeper不会因为version匹配就递归删除子树。递归删除是客户端组合操作，期间可能有新子节点出现，必须明确并发和安全策略。

十四、multi事务原理与边界

multi把多个ZooKeeper操作作为一个事务提交：全部成功，或全部不生效。

示例意图：

check /config/order version=7
setData /config/order → v8
create /audit/config/change-0001

flowchart TD
    A["Client提交multi操作列表"] --> B["Leader校验所有check和权限"]
    B --> C{"所有操作都可执行"}
    C -- "否" --> D["整个multi失败，不应用部分结果"]
    C -- "是" --> E["作为一个ZooKeeper事务排序提交"]
    E --> F["原子应用所有znode变化"]

边界：

• 只能覆盖同一ZooKeeper集群内的znode操作。
• 不能把MySQL更新、Redis命令、MQ发送放进同一ZAB事务。
• 响应丢失时仍可能UNKNOWN，需要查询事实。
• 大型multi会增加请求大小和事务应用成本，应保持小而明确。

十五、ConnectionLoss后的结果未知

创建节点时连接丢失：

请求可能未到Leader
或已经提交但响应丢失

恢复策略按操作设计：

操作	查询证据
固定路径create	exists并比较节点数据/业务ID
顺序节点create	在节点数据中保存唯一请求ID，扫描同前缀节点识别自己的提交
setData CAS	读取data、version和业务revision
delete	exists，NoNode可视为幂等完成但要确认目标正确
multi	查询所有受影响节点和操作ID，不能只重发

顺序创建若无业务标识，客户端可能不知道哪个 lock-000... 是第一次请求创建的，盲目重试会留下重复候选节点。

十六、ACL模型

ACL条目由 scheme:id 和权限组成。

常见Scheme：

Scheme	示例	说明
world	world:anyone	所有人，生产慎用
auth	auth:	已认证身份
digest	用户摘要身份	适合基础认证，传输仍应配TLS
ip	10.0.0.0/24等支持形式依版本	网络身份，代理/NAT下慎用
sasl	Kerberos/SASL主体	企业认证集成
x509	证书主体，需TLS能力	双向TLS身份

常见权限：

权限	作用
READ	读取数据和列出子节点
WRITE	修改节点数据
CREATE	在该节点下创建子节点
DELETE	删除该节点的子节点
ADMIN	修改该节点ACL

CREATE/DELETE控制的是父节点下的子节点操作。删除子节点不是只看子节点自己的ACL。

十七、ACL不会自动像文件系统一样继承

创建子节点时必须显式提供ACL，或由客户端/框架默认ACL策略注入。父节点限制严格但子节点使用开放ACL，会造成权限漏洞。

生产建议：

• 为应用创建独立身份。
• 注册中心、配置、锁路径分权限。
• 普通Provider不能修改全局路由。
• 运维账号与应用账号分离。
• 定期扫描 world:anyone 开放写权限。
• 修改ACL使用版本控制并保留审计。

十八、认证不等于传输加密

Digest/SASL解决“你是谁”，TLS解决传输机密性和对端认证。仅使用Digest但明文连接，网络监听者仍可能观察敏感数据或认证流量。

安全部署应同时考虑：

• Client到Server TLS。
• Quorum节点间TLS。
• SASL/Kerberos或证书认证。
• ACL最小权限。
• 密钥、JAAS和证书轮换。
• 四字命令/AdminServer访问控制。

十九、chroot与命名空间隔离

连接串可以包含chroot，例如概念形式：

zk1:2181,zk2:2181,zk3:2181/prod/order

客户端看到的 /config 实际映射到集群 /prod/order/config。chroot降低路径冲突，但不是完整安全边界：

• chroot根路径必须预先存在。
• ACL仍要正确设置。
• 误用无chroot运维客户端仍能看到全局树。
• 测试、预发、生产更高隔离要求下应使用独立集群或严格网络/身份边界。

二十、容量为什么由整棵树决定

ZooKeeper DataTree主要驻留内存，容量受以下因素共同影响：

znode数据
+ 路径和对象开销
+ ACL
+ Stat
+ 子节点集合
+ Watch注册
+ Session与连接
+ JVM和缓存开销

不能用“总dataLength只有500MB”推导“1GB Heap足够”。百万小节点的对象、路径、ACL和集合开销可能远大于原始字节数。

二十一、热点路径与大目录

风险模式：

• 所有实例监听同一个高频变化配置节点。
• 一个父节点有几十万直接子节点并频繁 getChildren。
• 每个请求创建一个持久顺序节点。
• 把ZooKeeper当事件日志。
• 大量客户端在同一锁目录竞争。

优化：

• 按业务和资源分片路径。
• 只保存协调元数据，事件进入MQ。
• 使用前驱Watch避免羊群效应。
• 限制单目录children数和Watch扇出。
• 建立节点TTL/归档清理，但不要依赖不支持的类型。

二十二、JDK 8 Demo：版本CAS与结果复用

public class ZnodeCasDemo {

    static final class Value {
        final String data;
        final int version;

        Value(String data, int version) {
            this.data = data;
            this.version = version;
        }
    }

    static final class Store {
        private Value current = new Value("timeout=1000", 7);

        synchronized Value read() {
            return current;
        }

        synchronized boolean setData(String data, int expectedVersion) {
            if (current.version != expectedVersion) return false;
            current = new Value(data, current.version + 1);
            return true;
        }
    }

    public static void main(String[] args) {
        Store store = new Store();
        Value a = store.read();
        Value b = store.read();

        System.out.println("A=" + store.setData("timeout=1500", a.version));
        System.out.println("B=" + store.setData("timeout=3000", b.version));

        Value finalValue = store.read();
        System.out.println("final=" + finalValue.data + ", version=" + finalValue.version);
    }
}

预期输出：

A=true
B=false
final=timeout=1500, version=8

真实ZooKeeper中第二次写会得到BadVersion；调用方应重读和合并，不能无条件覆盖。

二十三、Curator multi Demo

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.api.transaction.CuratorOp;

import java.nio.charset.StandardCharsets;

public class CuratorMultiDemo {
    public static void update(CuratorFramework client, int expectedVersion) throws Exception {
        CuratorOp check = client.transactionOp()
                .check().withVersion(expectedVersion).forPath("/config/order");
        CuratorOp update = client.transactionOp()
                .setData().withVersion(expectedVersion)
                .forPath("/config/order", "timeout=1500".getBytes(StandardCharsets.UTF_8));
        CuratorOp audit = client.transactionOp()
                .create().forPath("/audit/order/change-", "request-1001".getBytes(StandardCharsets.UTF_8));

        client.transaction().forOperations(check, update, audit);
    }
}

示例中审计节点若需要顺序模式，应按当前Curator API显式配置创建模式；不能只靠路径尾部 - 自动变成顺序节点。

二十四、商业场景建模

场景	节点设计	关键边界
Dubbo实例	Ephemeral或应用级实例记录	Session窗口、注册地址、元数据
配置版本	Persistent + data version	Watch只提示，CAS更新
分布式锁	稳定父路径 + Ephemeral Sequential	前驱Watch、Fencing
业务选主	Ephemeral Sequential候选	Leader任务幂等
路由规则	Persistent + ACL + version	灰度发布和回滚
任务事实	不放ZooKeeper	使用数据库状态机和唯一键

二十五、生产排查Runbook

25.1 BadVersion频繁出现

1. 确认是数据、children还是ACL版本。
2. 记录读取version、提交version和当前version。
3. 查是否多个控制台/发布任务并发写。
4. 采用读取—合并—CAS，而不是 -1 覆盖。
5. 高频冲突说明数据模型可能不适合集中在一个热点znode。

25.2 NodeExists但客户端认为第一次创建失败

检查前一次是否ConnectionLoss后实际提交；比较固定路径数据中的请求ID。顺序节点扫描相同业务ID，删除重复节点前确认Session和所有权。

25.3 znode数量持续增长

按路径统计 children和持久/临时节点，重点检查Persistent Sequential、审计/日志式节点、锁取消失败和错误注册类型。清理前备份并确认业务仍未引用，不能直接递归删除生产父路径。

25.4 NoAuth

确认客户端实际认证Scheme和身份、chroot、目标节点ACL以及CREATE/DELETE是在父节点上检查。检查证书、Kerberos票据和JAAS轮换，不要临时改成开放ACL掩盖问题。

二十六、数据模型指标

• 总znode数、ephemeral数。
• 按一级/二级路径的节点数和增长率。
• 最大dataLength、平均dataLength。
• 最大直接children数。
• Watch数量和热点路径扇出。
• ACL开放写节点数量。
• BadVersion、NodeExists、NoNode、NoAuth次数。
• multi请求大小、失败率和延迟。
• 本地缓存version和年龄。

二十七、常见错误及后果

错误	后果
把ZooKeeper当文件系统	大数据拖慢内存、Snapshot和恢复
临时节点承载永久业务事实	Session过期后事实丢失
永久依赖顺序后缀字典序	溢出或父路径重建后排序错误
用version=-1解决冲突	静默覆盖合法更新
认为ACL自动继承	子节点可能开放写权限
Digest认证等于加密	网络仍可能明文暴露数据
multi包含数据库写	跨系统仍有双写窗口
ConnectionLoss直接重试顺序create	留下重复候选节点

二十八、面试标准回答

ZooKeeper是一棵znode树，每个节点可同时保存小型字节数据、直接子节点、Stat和ACL，不是文件系统。节点常见Persistent、Ephemeral及Sequential组合；临时节点属于Session且不能有子节点，较新版本还有Container和TTL类型但有版本及开关边界。Stat中的version、cversion、aversion分别描述数据、子节点集合和ACL变化，setData/delete/setACL应带对应期望版本做CAS。multi能把同一ZooKeeper集群内多个znode操作原子提交，但不能包含MySQL或MQ。ACL不自动继承，CREATE/DELETE主要控制父节点下的子节点操作。ConnectionLoss时写结果可能未知，固定节点按数据和业务ID查询，顺序创建必须在节点内容保存请求ID以识别重复，不能盲目重试。

二十九、关联知识点

• ZAB、zxid与一致性
• Watcher与Session
• 分布式锁、选主与Fencing
• ZooKeeper运维排查
• Dubbo注册发现
• ZooKeeper面试题

本章小结

znode数据模型的核心是“小型协调状态 + 多维版本 + Session所有权 + ACL”。Persistent/Ephemeral表达生命周期，Sequential表达队列顺序，Stat把事务位置和局部版本分开，CAS和multi提供ZooKeeper内部原子裁决。它们不能替代文件存储、业务数据库和跨系统事务；只有同时控制容量、ACL、ConnectionLoss和版本冲突，节点Recipe才是生产可用的。