企业官网建设流程全解析

ZooKeeper 节点操作这件事，说简单也简单，无非就是增删改查四个动作；说麻烦也是真麻烦，我见过太多人在set的时候不带版本号，线上配置被并发覆盖，排查了半天才发现是节点的 version 机制没用上。ZooKeeper 的 ZNode 不是普通的 key-value，它同时承载了数据、元信息、访问控制和子节点列表，还带有一套版本号做乐观锁。搞不清楚这些，你就只能停留在“能跑起来”的阶段，一旦遇到会话过期、节点残留、版本冲突这些场景就抓瞎。

这篇内容主要聊 ZooKeeper 节点的基本操作：四种节点类型怎么选、create / get / set / delete每个参数的实际含义、版本号到底在管什么、会话超时是怎么协商出来的，还有一套可以直接拿去改的 Curator 操作代码。刚接触分布式协调组件的同学可以跟着敲一遍，已经有使用经验但一直靠“抄配置”的人，建议重点看版本号机制和排错那一节，那里才是最容易被忽略的地方。下面所有示例都基于 ZooKeeper 3.6 以上的版本，3.4 与 3.6 在命令行上有少量差异，我会在涉及的地方标出来。

1. ZNode 到底是什么：先把数据结构吃透

1.1 四种节点类型与它们各自的使用场景

ZooKeeper 的节点类型不是随便设计的，每一种背后都对应一类很具体的协调需求。搞明白它们的生命周期，你选型的时候就不会犹豫。

持久节点（PERSISTENT）是默认类型，创建之后一直存在，除非你显式删除。它适合存配置、存路由表、存元数据这类“本来就是长期存在”的信息。比如一个服务的数据库连接串、限流阈值，放在持久节点里最省心。

临时节点（EPHEMERAL）的生命周期绑定在会话上。客户端断开会话，节点自动消失。这是服务注册与发现的基础——服务实例上线时创建临时节点，进程崩了或者网络断了，会话超时后节点自动清理，注册中心不需要额外的健康检查就能感知下线。这里有个硬限制：临时节点不能有子节点，执行create -e /lock/child会直接报Ephemeral nodes may not have children。很多人做分布式锁时想给锁节点挂子节点，就是在这里卡住的。

顺序节点（PERSISTENT_SEQUENTIAL / EPHEMERAL_SEQUENTIAL）是在前面两种类型上叠加了自增后缀。创建/tasks/task-，实际生成的是/tasks/task-0000000001，后缀是十位补零的数字，由父节点的 cversion 递增产生。分布式队列、全局有序 ID、公平锁的排队都用它。要注意这个序号是父节点范围内递增的，不是全局递增，换个父节点就是另一套计数。

容器节点（CONTAINER）和 TTL 节点是 3.5 之后引入的补充类型。容器节点专门用来“装子节点”，当最后一个子节点被删除后，服务端会在后台定期清理掉这个空容器，省得你手工收拾。TTL 节点则给持久节点加了一个过期时间，超过指定时间没有被修改且没有子节点，就会被清理，需要在服务端配置里开启zookeeper.extendedTypesEnabled=true才能用。

选型的判断逻辑其实很直接：跟会话有关系的用临时节点，需要对号入座的用顺序节点，只做目录容器不想手动清理的用容器节点，其余一律持久节点。

1.2 一个节点里存了什么：data、stat、ACL、children

很多人对 ZNode 的理解停留在“一个路径对应一个字符串”，实际上每个节点由四部分组成，缺一不可。

data是业务数据本体，字节数组，客户端自己序列化。看着没有大小限制，其实受服务端的jute.maxbuffer控制，默认 0xfffff，也就是不到 1MB，而且这个限制算的是整个请求包，路径、ACL 都算在里面。我见过有人把整个 JSON 配置塞进一个节点，超过限制直接报Packet len is out of range，那个报错信息还挺误导人的，看着像网络问题。

stat是元信息结构，包含 cZxid、mZxid、pZxid、ctime、mtime、version、cversion、aversion、ephemeralOwner、dataLength、numChildren 这些字段。这些字段不是摆设，版本号相关的三个字段直接决定了并发操作能不能安全落地，后面第 4 节会专门展开。

ACL是访问控制列表，由 (scheme, id, perms) 三元组组成。默认创建时用的是world:anyone:cdrwa，也就是谁都能读写。生产环境这么干是有风险的，至少要把写权限收敛到指定身份。常见的 scheme 有world、auth、digest、ip，其中digest用得最多，密码存的是base64(sha1(user:password))，注意不是明文。

children是子节点路径列表。这里有个容易忽略的点：ls返回的只是子节点的名字，不是完整路径，用的时候得自己拼父路径。另外 ZooKeeper 不支持递归创建，create /a/b/c如果/a/b不存在就是NoNodeException，命令行里没有mkdir -p，只能一层一层建，或者用 Curator 的creatingParentsIfNeeded()。

1.3 为什么是树而不是哈希表：从写入路径说起

有人会问，既然都是存数据，为什么 ZooKeeper 要用树形结构，而不是像 Redis 那样直接一个扁平哈希表？这个问题想明白了，你对它的很多行为就都能预测了。

ZooKeeper 的核心价值在于顺序一致性和原子广播。每一条写请求都会被分配一个全局递增的 zxid，然后通过一致性协议在集群内达成一致。树形结构让“批量相关操作”可以落在同一个父节点下，比如所有工作节点都挂在/workers下面，客户端要感知变化，只需要对/workers挂一个 watch，子节点有任何增删都能收到通知。如果换成扁平表，你就得用前缀扫描或者额外的索引来模拟这个语义。

更重要的是，父节点的 cversion 天然提供了一个轻量的序列发生器。顺序节点的编号就是从父节点的 cversion 来的，这个设计让“排队”变成了一件零成本的事——创建即排队，不需要额外维护一个计数器。这也是为什么基于顺序节点的公平锁方案比基于临时节点的方案更可靠，前者天然避免了惊群。

代价也很明显：树结构限制了单个父节点下的子节点规模，几十万子节点挂在一个父节点下，ls会非常慢，甚至影响整个集群的稳定性。所以实际使用中，节点路径一般会做分层打散，比如按业务线、按机房、按 hash 段拆开。

2. 动手前的准备：环境、客户端与连接参数

2.1 三节点伪集群的搭法

单机模式只适合验证语法，一旦涉及会话、选举、watch 的行为，单机跑出来的结果和集群是不一样的。我建议至少搭一个三节点的伪集群，一台机器就够，成本很低。

准备三个目录，分别放数据：

mkdir -p /opt/zk/{node1,node2,node3}/data echo 1 > /opt/zk/node1/data/myid echo 2 > /opt/zk/node2/data/myid echo 3 > /opt/zk/node3/data/myid

每个目录下放一份zoo.cfg，只有clientPort和dataDir不同：

tickTime=2000 initLimit=10 syncLimit=5 dataDir=/opt/zk/node1/data clientPort=2181 server.1=127.0.0.1:2888:3888 server.2=127.0.0.1:2889:3889 server.3=127.0.0.1:2890:3890

三个参数的含义得说清楚，不然后面调优没法下手：tickTime是基本时间单位，毫秒；initLimit是 follower 与 leader 初次同步允许的 tick 数；syncLimit是日常心跳允许的超时 tick 数。按 2 秒 tick 算，初次同步最多 20 秒，心跳超时 10 秒。

启动时分别指定配置：

bin/zkServer.sh start /opt/zk/node1/zoo.cfg bin/zkServer.sh start /opt/zk/node2/zoo.cfg bin/zkServer.sh start /opt/zk/node3/zoo.cfg

连上去验证一下角色，三个里应该有一个是 leader：

bin/zkCli.sh -server 127.0.0.1:2181

进去之后敲stat，会看到Mode: follower或者Mode: leader。如果三个都是 looking，说明选主失败，八成是 myid 没写对或者端口冲突。

注意：伪集群的三个server.x端口必须完全错开，2888:3888这种成对出现的写法里，前一个是数据同步端口，后一个是选举端口，两组都不能跟别的实例撞。

2.2 客户端三选一：命令行、原生 API、Curator

ZooKeeper 的客户端有三层选择，越往后封装越厚，但并不是封装越厚越好。

zkCli.sh是最直接的，适合临时查数据、验证 ACL、调试 watch。它的优点是所见即所得，缺点是脚本化能力差，create的参数顺序记错就报错。做运维排查的时候，我基本只用它。

原生 Java API（ZooKeeper 类）提供create / getData / setData / delete / exists这些方法，能力最全，但所有异常都要自己处理，连接断开要自己重连，watch 是一次性的要自己重新注册。写业务代码时直接用它，代码量会膨胀得很快。

Curator是在原生 API 上做的一层封装，主要解决三件事：连接管理（自动重连、阻塞直到连上）、重试策略（指数退避、可自定义）、常用场景的配方（分布式锁、Leader 选举、计数器）。日常业务开发我基本都用 Curator，除非是排查底层问题需要看原始请求。

选型的经验是：临时验证用 zkCli，写业务用 Curator，只有需要精确控制请求行为或者做中间件时才碰原生 API。

2.3 会话超时时间的协商逻辑与取值

会话超时是节点操作里最容易被忽视的参数，但它直接决定了临时节点什么时候消失、连接断开后多久触发重连。

客户端传的sessionTimeout只是一个建议值，服务端会做一次夹逼运算：

negotiated = min(maxSessionTimeout, max(minSessionTimeout, requested))

默认配置下，minSessionTimeout = 2 * tickTime，maxSessionTimeout = 20 * tickTime。按 tickTime 2000ms 算，允许范围是 4000ms 到 40000ms。你请求 15000ms，服务端给你 15000ms；你请求 1000ms，服务端给你 4000ms；你请求 300000ms，服务端给你 40000ms。想知道实际生效值，看客户端日志里打印的Session establishment complete on server ..., sessionid = ..., negotiated timeout = ...。

取值怎么定？太短会导致网络抖动时频繁误判下线，临时节点反复消失又重建，服务发现会出现虚假的上下线；太长则故障感知慢，进程已经死了，节点还挂着，流量继续打过去。我的经验值是10 到 15 秒，配合客户端 3 次重试，大多数场景够用。跨机房部署或者网络质量差的，可以拉到 20 秒，但不要超过 40 秒的默认上限，否则得同步改服务端配置，改完还要考虑所有客户端的兼容性。

3. 增删改查：四个高频操作逐个拆

3.1 create：参数、ACL 与容易踩的三个坑

命令行的完整语法是：

create [-s] [-e] [-c] [-t ttl] path [data] [acl]

-s顺序节点，-e临时节点，-c容器节点，-t指定 TTL（毫秒）。这几个开关里，-s和-e可以组合使用，生成临时顺序节点，分布式锁就是这么来的。

三个真实的坑，我按遇到频率排序。

第一个：data 传空和传 null 不是一回事。create /node ""创建的是长度为 0 的字节数组，create /node不传 data，创建的是 null。大部分场景没区别，但如果你用getData的返回值直接做new String(bytes)，null 会抛空指针。我一般统一传空字符串，省得判断。

第二个：ACL 顺序写错会报InvalidACL。正确的格式是scheme:id:perms，比如digest:app:xxxxxxxx:cdrwa，perms 的字母顺序是固定的 c(create)、d(delete)、r(read)、w(write)、a(admin) 中的一个或多个。写成rwcda也能认，但cdrwa是官方文档的写法，统一一下省得自己看混。

第三个：没有递归创建。这是新手最容易卡住的地方。create /a/b/c之前必须先create /a、create /a/b。命令行里除了手动敲两遍没别的办法，Java 侧用 Curator 的creatingParentsIfNeeded()可以一次搞定，但要注意这个选项在并发创建时可能抛出NodeExistsException，得配合重试。

3.2 读操作：ls、get、stat 的差异与 -s 的用处

读操作有三个命令，很多人只是凭感觉用，其实各自职责很清晰。

ls path返回子节点名称列表。加-R递归列出整棵子树，加-s会额外返回当前节点自己的 stat，加-w注册一个子节点变更的 watch。做运维巡检时ls -R /是最快的全量视图，但生产环境慎用，节点多的时候输出能刷屏，而且ls -R会一次性拉取大量数据。

get path返回节点数据。加-s同时返回 stat，加-w注册数据变更 watch。注意这个 watch 是一次性的，触发一次就失效，想持续监听必须在回调里重新注册。这一点在原生 API 里是必须手工做的，Curator 的NodeCache帮你做了自动重注册。

stat path只返回元信息，不返回数据。排查“这个节点是什么时候被改的”“谁改的”就用它。输出里几个关键字段值得记住：

ephemeralOwner这个字段特别有用。当临时节点没有按预期消失时，用它去对照cons命令输出的会话列表，能快速判断是会话还在导致节点没被清理，还是服务端清理有问题。

3.3 set 更新：为什么一定要带 version

set path data [version]里的 version 是可选的，不传就是无条件覆盖。这就是最危险的地方——两个人同时读到 version=3 的数据，各自改完写回去，后写的那个把先写的直接抹掉，而且不会有任何报错。

正确的做法是带上读到的版本号：

set -v 3 /config/limit "200"

如果服务端当前版本不是 3，直接抛BadVersionException，事务不会提交。客户端拿到异常后重新读取、重新计算、重新提交，这就是标准的 CAS 循环。

为什么这个机制值得强调？因为 ZooKeeper 的定位是协调服务，往里面写数据的往往是多个进程，并发覆盖的后果不是丢一个缓存，而是丢一份配置、丢一个路由决策，影响面比想象的大。我在实际项目里见过限流阈值被并发改回旧值的案例，排查了两天才定位到是有人图省事用了不带 version 的set。

有一点要注意：-v的参数是字符串形式的数字，写成-v 3没问题，写成-v -1表示忽略版本，等价于不传。另外版本号是数据版本，跟子节点版本无关，改子节点不会影响父节点的 dataVersion。

3.4 delete 与 deleteall：非空节点怎么办

delete path [version]只能删空节点。节点下有子节点时，报Node not empty。这在设计路径时就得考虑到，否则临时要删一棵子树就得很麻烦地自底向上递归。

3.5 之后加入了deleteall path，可以递归删除整个子树，运维层面方便了很多。低版本没有这个命令，只能用ls -R拿到全部路径，倒序逐个删，或者写个脚本处理。

-v参数在删除时同样有意义。带版本删除可以防止误删：假设你以为删的是旧版本节点，实际上别人刚更新过，带版本删除会失败，给你一个反悔的机会。这个用法比较小众，但在自动化脚本里我一般都会带上。

提示：删除父节点前，如果子节点里有临时节点，注意临时节点的清理是异步的，刚删完立刻ls父节点可能还看得到残留。这不是 bug，是服务端清理线程的调度延迟，一般毫秒级，但脚本里紧接着做判断时会有影响。

4. version 机制：ZooKeeper 的乐观锁全貌

4.1 dataVersion、cversion、aversion 各管什么

stat 里有三个版本字段，名字长得像，职责完全不同，混淆了会写出逻辑错误的代码。

version（也叫 dataVersion）管的是节点数据的修改次数。每次setData成功，version 加一。这是 CAS 操作里最常用的那个。

cversion管的是子节点列表的变更次数。子节点新增或删除，cversion 加一。顺序节点的序号就是从这个值来的。要注意，修改子节点的数据不会让父节点的 cversion 变化，只有子节点的增删才会。

aversion管的是ACL的变更次数。setACL成功一次加一。日常业务基本用不到，但在做权限审计时有用。

这三个值是相互独立的。我见过有人拿 cversion 去判断数据有没有被改，结果怎么都对不上，最后发现对方只是在节点下面加了个子节点。这种错误在代码 review 时很难一眼看出来，因为变量名都叫 version。

还有一组容易混的：zxid 和 version。zxid 是全局事务 ID，集群范围内唯一且递增，用来排序；version 是单个节点内部的修改计数，只在当前节点有意义。做跨节点顺序判断用 zxid，做单节点并发控制用 version，别弄反。

4.2 用 version 实现一个安全的自增操作

ZooKeeper 没有原子的increment命令，所有自增都得靠 CAS 循环。写一个能用的版本大概是这样：

public int safeIncrement(CuratorFramework client, String path) throws Exception { int maxRetry = 5; for (int i = 0; i < maxRetry; i++) { Stat stat = new Stat(); byte[] raw = client.getData().storingStatIn(stat).forPath(path); int current = Integer.parseInt(new String(raw, StandardCharsets.UTF_8)); int next = current + 1; try { client.setData() .withVersion(stat.getVersion()) .forPath(path, String.valueOf(next).getBytes(StandardCharsets.UTF_8)); return next; } catch (KeeperException.BadVersionException e) { // 版本冲突，说明别人抢先写了，重新读一遍再来 continue; } } throw new IllegalStateException("自增重试次数耗尽: " + path); }

这段代码的关键在于读和写之间必须靠 version 保证原子性，读取本身不是原子的，但写入时的版本校验把整个循环变成了一个乐观锁。冲突发生时不是阻塞等待，而是立刻重试，吞吐比悲观锁高得多。

重试次数为什么设 5？这是经验值。理论上冲突概率跟你写入的并发度成正比，10 个客户端同时写一个节点，5 次重试的成功率已经很高了。但如果是上百个并发，就得考虑换方案，比如用顺序节点把压力分散开，或者干脆换成专门的计数器组件。不要指望 CAS 循环解决高并发写，ZooKeeper 本来就不是干这个的。

withVersion(-1)是 Curator 里表示“忽略版本”的写法，跟不传版本等价。要特别注意别把-1当成“版本为零”来用，withVersion(0)才是要求当前版本必须是 0，通常用于“创建后第一次修改”的场景。

4.3 三个常见的 version 误用

误用一：把 version 当业务版本号。有人想给配置项加个version=2.0的业务语义，就直接读 stat 的 version 字段去比较，结果发现每次修改都会加一，跟语义版本对不上。stat 的 version 是内部计数器，业务版本应该放在 data 里自己维护。

误用二：以为带 version 就绝对安全。带版本能防止覆盖，但不能防止 ABA 问题。version 是单调递增的，理论上不会回到旧值，所以 ZK 层面没有经典 ABA，但如果业务逻辑是“读出来算一算再写回去”，在读取和写入之间节点可能被删掉重建，新节点的 version 从 0 开始，这时候旧版本号可能刚好匹配上。严格来说这是极端情况，但在删除重建频繁的场景里确实会发生。稳妥的做法是配合exists检查节点是否存在，或者用 zxid 做更严格的校验。

误用三：删除时忘了子节点版本。delete只校验节点的 dataVersion，不管 cversion。你想“只有节点没有任何修改时才删”，只带 version 是不够的，还得先检查numChildren == 0和cversion是否变化，否则可能出现“数据没改但子节点被加了一堆”然后被删掉的情况。

5. 完整实操：用 Curator 写一个节点管理工具

5.1 依赖与连接初始化

先在项目里加依赖，Curator 版本建议跟 ZooKeeper 服务端版本对齐，3.6 系列对应 Curator 5.x：

<dependency> <groupId>org.apache.curator</groupId> <artifactId>curator-framework</artifactId> <version>5.6.0</version> </dependency> <dependency> <groupId>org.apache.curator</groupId> <artifactId>curator-recipes</artifactId> <version>5.6.0</version> </dependency>

连接初始化用 builder 方式，把几个关键参数显式写出来，不要靠默认值：

CuratorFramework client = CuratorFrameworkFactory.builder() .connectString("127.0.0.1:2181,127.0.0.1:2182,127.0.0.1:2183") .sessionTimeoutMs(15000) .connectionTimeoutMs(5000) .namespace("demo") .retryPolicy(new ExponentialBackoffRetry(1000, 3, 10000)) .build(); client.start(); if (!client.blockUntilConnected(5, TimeUnit.SECONDS)) { throw new IllegalStateException("连接 ZooKeeper 超时"); }

namespace("demo")会给所有路径自动加上/demo前缀，好处是多个应用共用一个集群时天然隔离，坏处是排查问题时容易忘记前缀，去命令行看不到数据。ExponentialBackoffRetry(1000, 3, 10000)的含义是首次重试间隔 1 秒，最多重试 3 次，单次间隔上限 10 秒，退避序列大概是 1s、2s、4s。

connectString里把所有节点都写上，客户端会自动挑选可用的。不要只写一个，否则那个节点挂了就连不上，虽然集群还活着。

5.2 核心代码：创建、读、CAS 更新、递归删除

把增删改查封装成一个类，逻辑会更清晰：

public class ZnodeOperator { private final CuratorFramework client; public ZnodeOperator(CuratorFramework client) { this.client = client; } // 创建，自动补全父路径，返回实际路径（顺序节点会带后缀） public String create(String path, String data, CreateMode mode) throws Exception { return client.create() .creatingParentsIfNeeded() .withMode(mode) .forPath(path, data.getBytes(StandardCharsets.UTF_8)); } // 读取数据并带出 stat public String read(String path, Stat stat) throws Exception { byte[] raw = client.getData().storingStatIn(stat).forPath(path); return raw == null ? null : new String(raw, StandardCharsets.UTF_8); } // 带版本的更新，失败抛 BadVersionException public int update(String path, String data, int expectVersion) throws Exception { return client.setData() .withVersion(expectVersion) .forPath(path, data.getBytes(StandardCharsets.UTF_8)) .getVersion(); } // 递归删除，忽略版本 public void deleteRecursively(String path) throws Exception { client.delete() .guaranteed() .deletingChildrenIfNeeded() .forPath(path); } }

guaranteed()这个是 Curator 的一个技巧，意思是如果删除时连接断了，客户端会在重连后继续尝试，直到成功或者会话结束。它解决的是“删除请求发出去了但没收到响应”的模糊状态。代价是要多一次网络交互，用在清理敏感数据的场景比较值。

deletingChildrenIfNeeded()内部是自底向上递归删除，跟命令行的deleteall等价。要注意这个方法在子节点数量巨大时会有性能问题，几十万子节点删下来要很久，而且过程中会持续占用会话。生产环境清理大子树，我一般会做成异步任务，分批次删。

5.3 跑起来验证：预期输出与逐行对照

写个 main 方法串起来：

public static void main(String[] args) throws Exception { CuratorFramework client = CuratorFrameworkFactory.builder() .connectString("127.0.0.1:2181,127.0.0.1:2182,127.0.0.1:2183") .sessionTimeoutMs(15000) .connectionTimeoutMs(5000) .namespace("demo") .retryPolicy(new ExponentialBackoffRetry(1000, 3, 10000)) .build(); client.start(); client.blockUntilConnected(5, TimeUnit.SECONDS); ZnodeOperator op = new ZnodeOperator(client); // 1. 持久节点，自动创建父路径 op.create("/config/app/limit", "100", CreateMode.PERSISTENT); // 2. 顺序节点，观察后缀 String seq = op.create("/tasks/task-", "payload", CreateMode.PERSISTENT_SEQUENTIAL); System.out.println("顺序节点: " + seq); // 3. 读取并拿 stat Stat stat = new Stat(); String val = op.read("/config/app/limit", stat); System.out.println("值=" + val + " version=" + stat.getVersion()); // 4. CAS 更新 int newVer = op.update("/config/app/limit", "200", stat.getVersion()); System.out.println("更新后 version=" + newVer); // 5. 故意用旧版本更新，预期抛异常 try { op.update("/config/app/limit", "300", stat.getVersion()); } catch (KeeperException.BadVersionException e) { System.out.println("版本冲突，符合预期"); } // 6. 递归删除 op.deleteRecursively("/config"); client.close(); }

预期输出里几个点可以对照：顺序节点的路径是以task-0000000000开始的（父节点第一次创建子节点时序号从 0 开始），CAS 更新后 version 会从 0 变成 1，第二次用 version=0 更新必然失败。如果第一次跑顺序节点拿到了一个很大的数字，说明/tasks这个父节点被反复创建删除过，cversion 没有归零——这是个容易被忽略的细节，父节点删除重建后 cversion 会重新计数，但如果只删子节点不删父节点，序号会一直往上走。做业务时不能假设序号从 0 开始，只能假设它单调递增。

6. 排错实录：节点操作里最常见的六个报错

6.1 速查表

表格里最容易误判的是ConnectionLossException。它的语义是“请求可能成功了，也可能没成功”，客户端不知道结果。这时候不能简单地重试，因为如果第一次其实成功了，重试会变成重复操作。正确的处理是重新读一次当前状态，判断目标是否已经达成。Curator 的重试策略在遇到这个异常时会自动重试，但对非幂等操作是有风险的，所以create顺序节点特别容易重复创建，得到一个多余的序号。

6.2 几个文档里不写的避坑经验

第一，临时节点消失不等于服务下线。会话超时是服务端主动清理触发的，从网络断开到会话真正过期，中间有一段时间。如果客户端只是 GC 卡顿了几秒，会话还在，节点不会消失，但业务请求已经处理不了了。所以靠 ZooKeeper 做健康检查时，最好叠加一层业务层的心跳，不要完全依赖临时节点。

第二，watch 丢了不会报错。watch 是一次性的，如果不重新注册，后续的变更你就收不到了，而且整个过程静默无提示。原生 API 里这是最常见的坑，我见过服务运行三天后发现配置不更新的案例，最后定位到是 watch 触发后没有重新getData().usingWatcher(...)。用 Curator 的NodeCache或PathChildrenCache可以规避，但也要注意start()之后要等到初始化完成才能信任缓存内容。

第三，不要在一个父节点下挂太多子节点。官方没说具体数字，实际经验是单个父节点下超过一万个子节点就要考虑拆分了。getChildren会返回全部列表，节点多了之后单次请求的数据量很大，还会拖慢整个集群的快照和日志。按业务维度或者按 hash 取模打散，是标准做法。

第四，ls返回的名字不是路径。这个坑实在太常见了。ls /workers返回worker-1、worker-2，想get的时候必须拼成/workers/worker-1，直接用名字会报NoNode。写递归遍历的时候尤其容易忘，我一般在递归函数里显式传父路径参数，避免字符串拼接出错。

第五，删除和创建的 zxid 能帮你还原事故现场。如果发现某个节点行为异常，用stat看 ctime、mtime、cZxid，再配合服务端事务日志，能大致推断出操作发生的时间窗口。日志级别开 INFO 的时候会打印操作类型和路径，做故障复盘很有用。

第六，集群节点数最好是奇数。这是选主机制决定的，3 节点能容忍 1 个故障，4 节点也只能容忍 1 个，多出来的那个纯属浪费。反过来，2 节点的集群不能容忍任何故障，因为凑不够多数派，实际可用性比单机还差。这个常识在扩容时特别重要，从 3 扩到 4 不会提升容错能力，要扩就直接到 5。

我个人在实际操作中的体会是，ZooKeeper 的节点 API 本身很简单，难的是把版本号、会话、watch 这三件事组合起来用对。每次写涉及节点的代码，我都会先问自己三个问题：这个操作要不要幂等？失败了重试会不会有副作用？会话断了之后节点状态该怎么恢复？这三问答清楚了，代码基本就不会出大问题。