凌晨两点收到告警这种事情做过 ZooKeeper 相关服务的同学应该不陌生微服务突然成片报错登上去一看客户端全在 CONNECTING 状态临时节点被服务端清了个干净等集群恢复业务已经被那一波会话过期拖垮了。这种问题十有八九会被归到“网络抖动”头上但真正的原因往往藏在 ZooKeeper 客户端连接集群的细节里——从创建会话到服务真正可用中间隔着的不是一次 TCP 连接而是一整套参数协商、协议握手、心跳维护和故障转移逻辑。这篇内容就是围绕这条链路写的我会把 new ZooKeeper() 之后客户端到底做了什么、服务端在背后如何分配会话、断连之后怎么重连、以及我实际踩过的那些坑都拆开讲清楚。不管你是刚接触 ZooKeeper 的初学者还是已经在生产环境里维护过集群的工程师这篇都值得当一份连接细节的参考。1. new ZooKeeper() 只是起点连接阶段远比想象中漫长1.1 一份最简单的连接代码绝大多数人第一次接触 ZooKeeper都是从这么几行代码开始的ZooKeeper zk new ZooKeeper( zk1:2181,zk2:2181,zk3:2181, 30000, event - { // 处理 Watcher 事件 } );构造函数只有三个参数连接串、会话超时时间、默认 Watcher。写完大概率就往下走业务逻辑了觉得连接已经“成功”。但实际上ZooKeeper 的构造函数返回只代表客户端对象创建完了网络连接、会话创建、状态确认全都发生在后台线程里。如果你在 new 完立刻调用 getData、create大概率会撞上 ConnectionLossException——不是代码写错了而是时机没到。这个异步模型和普通的数据库连接不太一样。JDBC 连接是同步建立、同步校验连接不上直接抛异常而 ZooKeeper 客户端是事件驱动的它把“连接成功”定义为收到服务端的 ConnectResponse 并推进到 SyncConnected 状态。所以你要学会的第一件事就是不再用“连接是否建立”来判断可用性而是看会话状态。1.2 何时才真正可用SyncConnected 才是起点ZooKeeper 客户端的连接状态有几种Disconnected、SyncConnected、ConnectedReadOnly、SaslAuthenticated、Expired以及连接中状态 Connecting。客户端启动后默认处于 Disconnected后台线程开始尝试连接直到收到服务端响应并完成会话创建默认 Watcher 会收到一个 WatchedEventKeeperState 变成 SyncConnected。只有到了这一刻你才能认为“这个客户端可用了”。后续所有 create、getData、exists 等请求都应该发生在这个状态之后。我见过不少同学在构造函数里传入 Watcher又把业务初始化逻辑直接写在 new ZooKeeper() 后面结果出现偶发性的“刚开始能跑、过一会儿就 NoNode”的情况。原因很简单业务初始化里的读取操作跑在了连接建立之前数据还没读到连接就断了。正确的做法是把数据初始化逻辑放到监听 SyncConnected 事件的回调里或者用一个 CountDownLatch 等状态到位后再继续。1.3 客户端里的三驾马车SendThread、EventThread 与 IO 线程理解了异步模型还得知道客户端背后有几个核心线程在干活否则出了问题都不知道看哪。ZooKeeper 客户端启动后会拉起两个主要线程SendThread负责网络 IO、心跳发送、请求写入和服务端响应读取。名字叫 Send但读响应也是它。连接断开后的重连动作也由它发起。EventThread负责派发 Watcher 事件和异步回调。所有 Watcher 回调、异步结果回调都是串行执行的顺序和触发顺序一致。客户端还维护了一个请求队列每个待处理的请求都会包装成 Packet带上自增的 XID写入发送队列SendThread 发出后服务端处理完把响应带同一个 XID 返回客户端从待确认队列里匹配并唤醒对应的调用方。如果连接断开队列里还没收到响应的请求会得到 ConnectionLossException或者一直被挂起直到会话恢复。知道这个结构你就能理解两个常见问题第一不要在 Watcher 回调里做耗时的阻塞操作否则会卡住 EventThread后续所有事件和异步回调全部排队第二连接断了不是所有请求都立刻失败部分请求可能处于“发出去了但没收到响应”的状态得等重连或超时才能最终定论。2. 连接参数背后的博弈连接串、超时、Watcher 没有一个是随便填的2.1 连接串解析为什么要写三台而不是写一台连接串的格式是host:port[/chroot][,host:port[/chroot]]逗号分隔多台服务器。很多人不理解既然客户端最终只会连接其中一台那多写几台的意义是什么答案是故障转移。客户端拿到连接串后会构建一个 HostProvider默认实现是 StaticHostProvider。它在解析时会把服务器列表打乱随机选一个作为起点避免所有客户端一上来都连接列表里的第一台造成“连接热点”。连接第一台如果失败会依次尝试后面的机器如果全部失败过段时间再从头开始轮询。所以连接串里机器的数量决定了客户端在网络分区、单机宕机时的容错上限。生产环境至少写三台这是基本常识。如果连接串只写了单台那么这台机器宕机时客户端就只能无限 CONNECTING毫无自救能力。这属于最常见的低级配置错误后面我会专门展开讲。2.2 会话超时怎么协商Client 说了不算Server 才是裁判new ZooKeeper() 时传入的 sessionTimeout 并不是最终值它只是客户端的“期望值”。服务端在收到 ConnectRequest 后会根据自己的配置做一次修正计算公式大致是effectiveTimeout min(maxTimeout, max(minTimeout, clientTimeout))这里的 minSessionTimeout 和 maxSessionTimeout 由服务端的 tickTime 决定默认分别是 2 倍 tickTime 和 20 倍 tickTime。如果 tickTime 是 2000ms那会话超时范围就是 4 秒到 40 秒。你客户端申请 1 秒服务端给你 4 秒申请 60 秒服务端也只给你 40 秒。客户端收到 ConnectResponse 后会以服务端返回的 timeout 作为最终协商值。很多人在排查偶发的 SessionExpired 时会忽略这一层以为自己在客户端设了 10 秒就是 10 秒结果服务端最小超时被配得很大真实超时完全不是你以为的那个数。这个值的设置要和业务能容忍的失联时长挂钩而不是随手填一个。下面这张表是我常用的参数参考参数默认值/常见值建议connectString无默认必填至少 3 台或用域名指向多台sessionTimeout无默认必填30000~60000ms与业务容错匹配tickTime服务端2000ms决定服务端 min/max session timeoutminSessionTimeout2 * tickTime默认 4smaxSessionTimeout20 * tickTime默认 40smaxClientCnxns服务端60单 IP 最大连接数canBeReadOnlyfalse集群分区时是否接受只读连接2.3 Watcher 与默认 Watcher事件模型的基本盘构造函数里的 Watcher 是默认 Watcher它会收到两类事件会话状态事件SyncConnected、Disconnected、Expired、ConnectedReadOnly节点事件如果某个操作注册了 Watcher事件触发时先由服务端发给客户端再交给默认 Watcher 或对应操作的 Watcher 处理。Watcher 机制需要注意两个特性一是一次性默认 Watcher 也好、某个调用传入的 Watcher 也好触发一次后就失效后续要持续监听得重新注册二是异步派发事件进入 EventThread 队列处理顺序严格按照服务端下发顺序不会并发乱序。日常开发里很多人会在 getData 时传入一个新的 Watcher而不是复用默认 Watcher这没问题但要注意区分哪些事件走默认 Watcher、哪些走调用级 Watcher。会话状态变化永远走默认 Watcher而节点数据变化走的是调用级 Watcher。如果不小心把状态判断逻辑写在调用级 Watcher 里SessionExpired 这种关键事件你可能根本收不到。3. 一次完整会话创建从 ConnectRequest 到 SyncConnected 的状态推进3.1 网络层准备好了先发一条 ConnectRequest连接池、连接串这些准备好了之后SendThread 会从 HostProvider 中取出一个服务器地址建立 TCP 连接。TCP 建连成功还不够紧接着客户端要发一条 ConnectRequest这才是客户端真正和服务端“对上暗号”的协议消息。ConnectRequest 的协议结构大致包含这些字段protocolVersion协议版本号lastZxidSeen客户端最后一次见过的 zxid用于重连时数据同步判断sessionId会话 ID新连接为 0passwd会话密码新连接为全 0sessionTimeout客户端期望的会话超时readOnly是否接受只读连接。注意 lastZxidSeen 这个字段它不是可有可无的。客户端每次收到服务端响应都会记录最新的 zxid重连去另一台服务器时服务端会拿这个值判断如果新服务器上的数据版本比客户端记录还旧说明这台 follower 落后了连接会被拒绝或者要求重新同步。这也是 ZooKeeper 客户端保证“不读旧数据”的核心机制之一。3.2 服务端如何分配 sessionId 并校验旧会话服务端收到 ConnectRequest 后流程分成两类如果 sessionId 为 0说明这是一个全新会话。服务端会通过 SessionTrackerImpl 生成一个新的 sessionId并给客户端返回一个随机生成的 passwd。这个 sessionId 不是简单的递增数字它由两部分构成高 32 位带实例标识低 32 位才是递增序号主要目的是保证整个集群范围内生成的会话 ID 不冲突。如果 sessionId 不为 0说明是客户端重连恢复会话。服务端会去会话表里查这个会话是否还存在、是否过期。只要还在有效期内就返回同一个 sessionId 和 passwd临时节点数据也不受影响。如果已经过期服务端返回 SessionExpired客户端状态变成 Expired之前注册的临时节点已经被清理应用层必须重建数据和 Watcher。这里有个容易被忽略的点passwd 是服务端和客户端之间的私有凭证。会话恢复时不仅要 sessionId 对得上passwd 也要匹配。如果客户端进程重启后拿着旧的 sessionId 和 passwd 去重连——比如你自己实现了断线重连但没清空旧凭证——服务端会认为凭证无效直接拒绝恢复。3.3 状态推进与事件回调SyncConnected 的真相客户端收到 ConnectResponse 后并不是直接就完成了。它先解析响应里的 sessionId、passwd 和超时值把本地会话超时更新为服务端协商结果然后:标记当前连接状态为 SyncConnected把 pendingQueue 里之前未决的请求重新处理这里注意只有在新会话建立后发送的请求才会被正常处理旧连接中残留的请求会进入重试或抛错流程向 EventThread 提交一个状态事件最终回调到默认 Watcher 的 process 方法事件类型是 NoneKeeperState 是 SyncConnected。到这一步“创建会话”这件事才算真正结束。你看到日志里出现SESSION STATE SYNC_CONNECTED意味着客户端可以正常收发请求了。但要注意SyncConnected 只是会话状态它不代表你注册的 Watcher 已经生效也不代表数据已经全部缓存到本地——它只代表“连接可用”。4. 集群故障转移连接断开后客户端如何自己站起来4.1 断连最初 60 秒内发生了什么连接断开后客户端的行为往往被人误以为“需要重启应用才能恢复”其实完全不用。SendThread 会立刻感知 IO 异常或读超时把当前连接标记为断开客户端状态回到 CONNECTING然后开始自动重连。重连的地址选择顺序由 HostProvider 控制。它会从上次中断后的下一个服务器开始尝试而不是永远重连同一台失败节点。如果当前列表里所有服务器都试了一遍仍然失败客户端不会放弃而是等待一段时间后再次轮询整个列表。这个过程会持续下去直到会话超时。所以断连后最先发生的不是业务失败而是客户端在后台不断尝试其他节点。这个过程往往是透明的业务请求可能会短暂收到 ConnectionLossException但只要会话还没过期应用层可以选择重试。ZooKeeper 的哲学是“客户端自动恢复业务侧尽量无感”但无感的前提是会话不能过期。4.2 lastZxidSeen 与会话恢复为什么重连后数据还在重连成功不等于一切从头再来。客户端新连接上任一台服务器时会在 ConnectRequest 里携带原来的 sessionId、passwd 和 lastZxidSeen。服务端校验会话有效后会返回会话恢复成功客户端收到后又一次进入 SyncConnected。这期间会话对应的临时节点还活得好好的Watcher 也还挂在服务端你甚至感觉不到刚才断过。但有一个例外刚才说的 lastZxidSeen 如果大于新服务器当前的最新 zxid说明新服务器是个落后节点。服务端会拒绝连接或让客户端继续选择其他节点避免客户端读到比自己已知状态还旧的数据。这就是为什么客户端故障转移时不会随便连上一台落后 follower 就算完事。4.3 会话过期最不愿见到的 Expired 状态会话过期是所有 ZooKeeper 使用方最不想遇到的状态。触发条件很简单在 sessionTimeout 时间内服务端没有收到来自这个会话的任何请求或心跳它就会主动删掉会话、清理这个会话下所有临时节点。客户端这边如果一直重连不上超过服务端判定会话超时的时间后重连即使成功也恢复不了旧会话服务端直接返回 SessionExpired。客户端状态进入 Expired默认 Watcher 收到事件。此时所有旧 Watcher 全部失效所有临时节点、临时顺序节点全部被清理客户端必须销毁或重建 ZooKeeper 实例重新创建会话重新初始化业务数据。这个状态对业务影响很大特别是用临时节点做分布式锁的场景会话一过期锁丢失但业务不一定会立刻感知到可能还在继续做自己的事产生并发冲突。这是 ZooKeeper 分布式锁最典型的“坑”不是锁坏是会话没维护住。4.4 从裸客户端到 Curator重试策略的价值裸客户端虽然有自动重连能力但它不提供业务层面的重试策略。遇到 ConnectionLoss、SessionExpired 怎么办裸客户端只会抛异常具体的“哪些操作要重试、重试几次、退避多久”都得自己写。Apache Curator 就是来解决这个问题的。它包装了原生客户端提供了 RetryLoop 和 RetryPolicy比如 ExponentialBackoffRetry。Curator 默认的 sessionTimeoutMs 是 60 秒connectTimeoutMs 是 15 秒这两个值比很多手写场景合理。如果你在用 ZooKeeper我强烈建议直接用 Curator而不是拿着原生 ZooKeeper 自己封装重试。原因很简单原生客户端给出的异常种类多每种异常的语义和处理方式不一样没有完整的测试覆盖很容易处理错。5. 我实际踩过的连接坑现象、根因与解决记录5.1 错误一连接串只写一台机器成了单点现象部署在机房的三个服务实例分别连的是 zk1、zk2、zk3 三台机器结果 zk1 例行重启连 zk1 的那批客户端全部卡在 CONNECTING等到 zk1 起来才恢复。根因连接串里只写了zk1:2181没有写完整的集群列表。HostProvider 只有一个可选地址它根本没有“换一台试试”的机会。解决所有客户端连接串都写三个节点即使写三个节点最终只连一个也要给故障转移留出余地。这是最小成本、最大收益的配置修正。5.2 错误二sessionTimeout 拍到 10 秒Full GC 一来就崩现象线上频繁出现 SessionExpired 告警集中在每日凌晨流量高峰JVM 老年代 GC 时间偶尔超过 5 秒。每次告警后分布式锁的临时节点全部清掉业务恢复后锁重新竞争失败引发一串连锁反应。根因sessionTimeout 设成了 10 秒而服务端 tickTime 是 2000ms有效超时确实就是 10 秒。Full GC 停顿期间 SendThread 没有及时读写服务端等不到心跳判定会话超时直接干掉。GC 停顿和网络抖动在这个场景里是叠加的。解决把 sessionTimeout 调到 30 秒以上并且给 JVM 配置合适的 GC 参数避免长时间停顿。更关键的是这个值不是越小越“快”而是要和业务能容忍的故障恢复时间匹配。平时 30~60 秒是常见区间。5.3 错误三Watcher 注册时机不对事件丢了现象服务启动后从 ZooKeeper 读配置read 到一次之后就再也不刷新改配置也不生效。根因代码在 new ZooKeeper() 后立刻执行 getData(/config, watcher)此时连接尚未 SyncConnected第一次调用直接抛 ConnectionLossException项目代码里 catch 住之后没有重试。结果就是配置读到了旧值Watcher 根本没注册上。解决所有涉及 Watcher 注册的初始化操作必须先等 SyncConnected。用 CountDownLatch 等默认 Watcher 收到 SyncConnected 后再初始化或者用 Curator 的 PathChildrenCache 这类封装好的监听容器它对注册时机处理得比较完善。5.4 错误四只读模式与 chroot 路径的误解现象集群发生分区半数节点失联客户端连接到了一个仍在服务的节点但业务还是报错写操作全部失败。根因集群失去法定人数后剩余节点进入只读状态如果服务端没开启 readonlymode.enabled客户端建立连接会被拒绝如果开启了但客户端 canBeReadOnlyfalse客户端也不接受这种连接。只读连接下来读可用写不可用所以写操作失败是正常的。另外要说一下 chroot连接串里可以带/app/zk这种 chroot 路径。很多人以为连接时会自动创建这个路径其实不会。如果你的客户端连接串里写了不存在的 chroot 路径常见的表现是连接明明成功但后续 create、getData 一直 NoNode。生产里遇到过几次排查半天最后发现是 chroot 拼写少了一层。5.5 错误五单 IP 连接数打到 maxClientCnxns现象有新服务接入当天客户端日志刷Too many connections from /10.x.x.x服务端把连接直接关掉。根因服务端默认 maxClientCnxns60单台机器一个 IP 最多 60 个连接。这个服务每处理一个任务就 new 一个 ZooKeeper 实例且不关闭IP 连接数秒破限。解决整个进程共享一个 ZooKeeper 连接而不是每次创建。如果业务确实需要多个连接调大服务端 maxClientCnxns并排查为什么会有这么多同时连接。这些坑的共同特点是问题都不在服务端集群本身而在于客户端参数和生命周期的使用方式。把连接当成普通资源管理像数据库连接池那样去考虑复用和超时很多问题从一开始就能避免。6. 服务可用怎么判定客户端状态、四字命令与监控建议6.1 客户端自查状态机与健康检查客户端要确认自己是否可用最直接的方式是看ZooKeeper.getState()if (zk.getState().isConnected()) { // 已连接但请注意 isConnected 包含 ConnectedReadOnly }判断可用性不能只看这个布尔值。更严苛的做法是主动发一个读请求验证链路比如Stat stat new Stat(); byte[] data zk.getData(/health/path, false, stat);如果这一步能正常返回说明客户端、服务端、会话三者都健康。如果抛 ConnectionLossException说明当前正处于断连或状态切换期如果抛 SessionExpiredException说明会话已经没了必须重建实例。我建议在应用的健康检查接口里直接加这种探活逻辑比单纯依赖连接状态可靠得多。因为它测的是“会话是否真的还能用”而不只是“TCP 端口是否通”。6.2 服务端四字命令mntr、stat、srvr 这样看服务端侧排查连接问题时四字命令是最快的工具。ZooKeeper 默认监听 2181 端口四字命令通过该端口发送echo mntr | nc 127.0.0.1 2181mntr 会返回一批监控指标重点看这几个zk_num_alive_connections当前存活连接数突然下降说明客户端在批量断开zk_outstanding_requests积压的请求数持续增加说明服务端处理不过来zk_session_count会话总数会话量骤降基本等于崩了zk_avg_latency/zk_min_latency/zk_max_latency请求延迟延迟升高时对应客户端超时概率也会升高。echo stat | nc 127.0.0.1 2181可以看到角色、节点数、连接数等基础信息。新版 ZooKeeper 默认会限制四字命令需要显式配置白名单权限Java 系项目记得提前评估这些问题否则线上想看一眼指标却拿不到数据。6.3 日志与监控建议ZooKeeper 客户端默认日志级别偏保守很多关键状态变化只在 DEBUG 里能看到。建议在且仅在排查问题时临时调高日志生产环境保留 INFO 即可。服务端日志里出现SESSION STATE SYNC_CONNECTED / DISCONNECTED / EXPIRED的变化时间是串成一条线的核心线索。结合客户端 GC、网络丢包时间点一起看能快速定位是客户端自身停顿、网络抖动还是服务端全挂。按我现在的习惯连接 ZooKeeper 集群的配置基本固定为一套组合连接串写全三个节点sessionTimeout 不低于 30 秒应用内共享单例连接能用 Curator 的地方不用裸客户端并给健康检查接口加上真实读写探活。这套组合未必是性能最优解但运维起来省心能把“连接不可用”从一种业务事故降维成一条普通日志。
