ZooKeeper 会话超时机制深度解析：配置、协商与过期处理

ZooKeeper 会话超时机制深度解析：配置、协商与过期处理

• • 一、会话超时概述
  • • 1.1 什么是会话超时？
    • 1.2 会话超时的核心作用
  • 二、会话超时时间的配置方法
  • • 2.1 客户端配置
    • • 使用原生 ZooKeeper 客户端
      • 使用 Curator 客户端
    • 2.2 服务端配置：超时时间的"协商"
    • • 协商规则
    • 2.3 配置建议
  • 三、会话超时后的处理流程
  • • 3.1 服务端视角：会话过期检测与清理
    • 3.2 客户端视角：状态转换与异常
  • 四、会话过期的连锁反应
  • • 4.1 临时节点被删除
    • 4.2 Watcher 失效
    • 4.3 客户端收到 SESSION_EXPIRED 异常
    • 4.4 CONNECTIONLOSS vs SESSIONEXPIRED 对比
  • 五、使用 Curator 优雅处理会话过期
  • 六、最佳实践总结
  • • 6.1 配置清单
    • 6.2 会话过期处理流程图
    • 6.3 核心要点回顾
    • 6.4 一句话总结

摘要：会话超时是 ZooKeeper 客户端与服务端之间维持连接的"生命契约"。合理配置会话超时时间，并深入理解超时发生后的一系列连锁反应，是构建健壮分布式应用的基础。本文将全面剖析 ZooKeeper 会话超时的配置方法、服务端与客户端的协商机制，以及会话过期后的完整处理流程，通过流程图和实战代码帮助读者掌握这一核心机制。

一、会话超时概述

1.1 什么是会话超时？

会话超时（Session Timeout）是指 ZooKeeper 服务端允许客户端会话保持活跃的最大空闲时间。如果在超时时间内，服务端没有收到客户端的任何消息（包括心跳和业务请求），则会判定该会话已过期。

#mermaid-svg-GL0dSPwvZoqIlkSK{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-GL0dSPwvZoqIlkSK .error-icon{fill:#552222;}#mermaid-svg-GL0dSPwvZoqIlkSK .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-GL0dSPwvZoqIlkSK .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-GL0dSPwvZoqIlkSK .marker{fill:#333333;stroke:#333333;}#mermaid-svg-GL0dSPwvZoqIlkSK .marker.cross{stroke:#333333;}#mermaid-svg-GL0dSPwvZoqIlkSK svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-GL0dSPwvZoqIlkSK p{margin:0;}#mermaid-svg-GL0dSPwvZoqIlkSK .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK .cluster-label text{fill:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK .cluster-label span{color:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK .cluster-label span p{background-color:transparent;}#mermaid-svg-GL0dSPwvZoqIlkSK .label text,#mermaid-svg-GL0dSPwvZoqIlkSK span{fill:#333;color:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK .node rect,#mermaid-svg-GL0dSPwvZoqIlkSK .node circle,#mermaid-svg-GL0dSPwvZoqIlkSK .node ellipse,#mermaid-svg-GL0dSPwvZoqIlkSK .node polygon,#mermaid-svg-GL0dSPwvZoqIlkSK .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-GL0dSPwvZoqIlkSK .rough-node .label text,#mermaid-svg-GL0dSPwvZoqIlkSK .node .label text,#mermaid-svg-GL0dSPwvZoqIlkSK .image-shape .label,#mermaid-svg-GL0dSPwvZoqIlkSK .icon-shape .label{text-anchor:middle;}#mermaid-svg-GL0dSPwvZoqIlkSK .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-GL0dSPwvZoqIlkSK .rough-node .label,#mermaid-svg-GL0dSPwvZoqIlkSK .node .label,#mermaid-svg-GL0dSPwvZoqIlkSK .image-shape .label,#mermaid-svg-GL0dSPwvZoqIlkSK .icon-shape .label{text-align:center;}#mermaid-svg-GL0dSPwvZoqIlkSK .node.clickable{cursor:pointer;}#mermaid-svg-GL0dSPwvZoqIlkSK .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-GL0dSPwvZoqIlkSK .arrowheadPath{fill:#333333;}#mermaid-svg-GL0dSPwvZoqIlkSK .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-GL0dSPwvZoqIlkSK .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-GL0dSPwvZoqIlkSK .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GL0dSPwvZoqIlkSK .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-GL0dSPwvZoqIlkSK .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GL0dSPwvZoqIlkSK .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-GL0dSPwvZoqIlkSK .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-GL0dSPwvZoqIlkSK .cluster text{fill:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK .cluster span{color:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-GL0dSPwvZoqIlkSK .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-GL0dSPwvZoqIlkSK rect.text{fill:none;stroke-width:0;}#mermaid-svg-GL0dSPwvZoqIlkSK .icon-shape,#mermaid-svg-GL0dSPwvZoqIlkSK .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GL0dSPwvZoqIlkSK .icon-shape p,#mermaid-svg-GL0dSPwvZoqIlkSK .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-GL0dSPwvZoqIlkSK .icon-shape rect,#mermaid-svg-GL0dSPwvZoqIlkSK .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GL0dSPwvZoqIlkSK .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-GL0dSPwvZoqIlkSK .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-GL0dSPwvZoqIlkSK :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

会话生命周期

是

否

会话创建

心跳维持

超时时间内有心跳？

会话过期

清理临时节点

关闭连接

1.2 会话超时的核心作用

二、会话超时时间的配置方法

2.1 客户端配置

使用原生 ZooKeeper 客户端

import org.apache.zookeeper.WatchedEvent;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooKeeper;
import java.util.concurrent.CountDownLatch;

public class ZooKeeperConnection {

public ZooKeeper connect() throws Exception {
CountDownLatch connectedLatch = new CountDownLatch(1);

// 设置会话超时时间为 5000 毫秒（5秒）
int sessionTimeout = 5000;

ZooKeeper zk = new ZooKeeper(
"localhost:2181",
sessionTimeout, // 客户端提议的超时时间
new Watcher() {
@Override
public void process(WatchedEvent event) {
if (event.getState() == Event.KeeperState.SyncConnected) {
connectedLatch.countDown();
System.out.println("连接成功，会话ID: " +
Long.toHexString(zk.getSessionId()));
}
}
}
);

connectedLatch.await();
return zk;
}
}

使用 Curator 客户端

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.CuratorFrameworkFactory;
import org.apache.curator.retry.ExponentialBackoffRetry;

public class CuratorConnection {

public CuratorFramework createClient() {
// 设置会话超时时间为 15000 毫秒（15秒）
int sessionTimeoutMs = 15000;
// 设置连接超时时间为 5000 毫秒（5秒）
int connectionTimeoutMs = 5000;

CuratorFramework client = CuratorFrameworkFactory.builder()
.connectString("localhost:2181")
.sessionTimeoutMs(sessionTimeoutMs) // 会话超时
.connectionTimeoutMs(connectionTimeoutMs) // 连接超时
.retryPolicy(new ExponentialBackoffRetry(1000, 3))
.build();

client.start();
return client;
}
}

2.2 服务端配置：超时时间的"协商"

客户端提议的超时时间并不一定会被服务端接受。ZooKeeper 服务端通过 minSessionTimeout 和 maxSessionTimeout 两个参数对客户端提议进行"协商" 。

# zoo.cfg 服务端配置
# 基本时间单位（毫秒）
tickTime=2000

# 最小会话超时时间（默认 2 * tickTime = 4000ms）
minSessionTimeout=4000

# 最大会话超时时间（默认 20 * tickTime = 40000ms）
maxSessionTimeout=40000

协商规则

服务端确定最终超时时间的逻辑如下 ：

public class SessionTimeoutNegotiation {

/**
* 服务端确定最终超时时间
* @param clientTimeout 客户端提议的超时时间
* @param minTimeout 服务端配置的最小超时
* @param maxTimeout 服务端配置的最大超时
* @return 最终协商的超时时间
*/
public static int determineTimeout(int clientTimeout, int minTimeout, int maxTimeout) {
if (clientTimeout < minTimeout) {
return minTimeout; // 客户端提议太小，使用最小值
}
if (clientTimeout > maxTimeout) {
return maxTimeout; // 客户端提议太大，使用最大值
}
return clientTimeout; // 在范围内，使用客户端提议
}

public static void main(String[] args) {
int min = 4000;
int max = 40000;

// 示例1：客户端提议 1000ms → 最终 4000ms
System.out.println("1000ms 提议 → " + determineTimeout(1000, min, max) + "ms");

// 示例2：客户端提议 5000ms → 最终 5000ms
System.out.println("5000ms 提议 → " + determineTimeout(5000, min, max) + "ms");

// 示例3：客户端提议 60000ms → 最终 40000ms
System.out.println("60000ms 提议 → " + determineTimeout(60000, min, max) + "ms");
}
}

重要建议：不要将 minSessionTimeout 和 maxSessionTimeout 设置得比默认值小，否则会导致客户端频繁判定连接超时，进而引发会话断开和故障 。

2.3 配置建议

重要警告：必须确保 JVM 的 Stop-the-world GC 暂停时间不超过会话超时时间，否则可能导致严重的分布式锁问题——两个客户端可能同时认为自己持有锁 。

三、会话超时后的处理流程

3.1 服务端视角：会话过期检测与清理

服务端通过 SessionTracker 组件使用分桶策略高效管理会话过期 。

#mermaid-svg-jf7XHNBlnPxVwk6I{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-jf7XHNBlnPxVwk6I .error-icon{fill:#552222;}#mermaid-svg-jf7XHNBlnPxVwk6I .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-jf7XHNBlnPxVwk6I .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-jf7XHNBlnPxVwk6I .marker{fill:#333333;stroke:#333333;}#mermaid-svg-jf7XHNBlnPxVwk6I .marker.cross{stroke:#333333;}#mermaid-svg-jf7XHNBlnPxVwk6I svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-jf7XHNBlnPxVwk6I p{margin:0;}#mermaid-svg-jf7XHNBlnPxVwk6I .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I .cluster-label text{fill:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I .cluster-label span{color:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I .cluster-label span p{background-color:transparent;}#mermaid-svg-jf7XHNBlnPxVwk6I .label text,#mermaid-svg-jf7XHNBlnPxVwk6I span{fill:#333;color:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I .node rect,#mermaid-svg-jf7XHNBlnPxVwk6I .node circle,#mermaid-svg-jf7XHNBlnPxVwk6I .node ellipse,#mermaid-svg-jf7XHNBlnPxVwk6I .node polygon,#mermaid-svg-jf7XHNBlnPxVwk6I .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-jf7XHNBlnPxVwk6I .rough-node .label text,#mermaid-svg-jf7XHNBlnPxVwk6I .node .label text,#mermaid-svg-jf7XHNBlnPxVwk6I .image-shape .label,#mermaid-svg-jf7XHNBlnPxVwk6I .icon-shape .label{text-anchor:middle;}#mermaid-svg-jf7XHNBlnPxVwk6I .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-jf7XHNBlnPxVwk6I .rough-node .label,#mermaid-svg-jf7XHNBlnPxVwk6I .node .label,#mermaid-svg-jf7XHNBlnPxVwk6I .image-shape .label,#mermaid-svg-jf7XHNBlnPxVwk6I .icon-shape .label{text-align:center;}#mermaid-svg-jf7XHNBlnPxVwk6I .node.clickable{cursor:pointer;}#mermaid-svg-jf7XHNBlnPxVwk6I .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-jf7XHNBlnPxVwk6I .arrowheadPath{fill:#333333;}#mermaid-svg-jf7XHNBlnPxVwk6I .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-jf7XHNBlnPxVwk6I .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-jf7XHNBlnPxVwk6I .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-jf7XHNBlnPxVwk6I .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-jf7XHNBlnPxVwk6I .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-jf7XHNBlnPxVwk6I .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-jf7XHNBlnPxVwk6I .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-jf7XHNBlnPxVwk6I .cluster text{fill:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I .cluster span{color:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-jf7XHNBlnPxVwk6I .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-jf7XHNBlnPxVwk6I rect.text{fill:none;stroke-width:0;}#mermaid-svg-jf7XHNBlnPxVwk6I .icon-shape,#mermaid-svg-jf7XHNBlnPxVwk6I .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-jf7XHNBlnPxVwk6I .icon-shape p,#mermaid-svg-jf7XHNBlnPxVwk6I .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-jf7XHNBlnPxVwk6I .icon-shape rect,#mermaid-svg-jf7XHNBlnPxVwk6I .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-jf7XHNBlnPxVwk6I .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-jf7XHNBlnPxVwk6I .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-jf7XHNBlnPxVwk6I :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

是

否

SessionTracker 启动

获取最近过期桶

当前时间 ≥ 桶时间？

取出该桶所有会话

标记会话 isClosing = true

收集该会话的所有临时节点

删除临时节点

关闭连接

从 SessionTracker 移除会话

获取下一个桶

等待到下一个检查点

过期时间的计算 ：

ExpirationTime = (当前时间 + sessionTimeout) 向上取整到 tickTime 的整数倍

例如：tickTime=2000ms, sessionTimeout=5000ms → 过期时间被取整为 6000ms 的整数倍。

3.2 客户端视角：状态转换与异常

当会话过期时，客户端会经历一系列状态转换 ：

#mermaid-svg-Hmqh75PU02bnOtoD{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Hmqh75PU02bnOtoD .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Hmqh75PU02bnOtoD .error-icon{fill:#552222;}#mermaid-svg-Hmqh75PU02bnOtoD .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Hmqh75PU02bnOtoD .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Hmqh75PU02bnOtoD .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Hmqh75PU02bnOtoD .marker.cross{stroke:#333333;}#mermaid-svg-Hmqh75PU02bnOtoD svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Hmqh75PU02bnOtoD p{margin:0;}#mermaid-svg-Hmqh75PU02bnOtoD defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-Hmqh75PU02bnOtoD g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-Hmqh75PU02bnOtoD g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-Hmqh75PU02bnOtoD g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-Hmqh75PU02bnOtoD g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-Hmqh75PU02bnOtoD g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-Hmqh75PU02bnOtoD .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-Hmqh75PU02bnOtoD .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-Hmqh75PU02bnOtoD .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-Hmqh75PU02bnOtoD .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-Hmqh75PU02bnOtoD .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-Hmqh75PU02bnOtoD .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-Hmqh75PU02bnOtoD .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-Hmqh75PU02bnOtoD .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Hmqh75PU02bnOtoD .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Hmqh75PU02bnOtoD .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Hmqh75PU02bnOtoD .edgeLabel .label text{fill:#333;}#mermaid-svg-Hmqh75PU02bnOtoD .label div .edgeLabel{color:#333;}#mermaid-svg-Hmqh75PU02bnOtoD .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-Hmqh75PU02bnOtoD .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-Hmqh75PU02bnOtoD .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-Hmqh75PU02bnOtoD .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-Hmqh75PU02bnOtoD .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-Hmqh75PU02bnOtoD .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Hmqh75PU02bnOtoD .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Hmqh75PU02bnOtoD #statediagram-barbEnd{fill:#333333;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Hmqh75PU02bnOtoD .cluster-label,#mermaid-svg-Hmqh75PU02bnOtoD .nodeLabel{color:#131300;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-Hmqh75PU02bnOtoD .note-edge{stroke-dasharray:5;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-note text{fill:black;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram-note .nodeLabel{color:black;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagram .edgeLabel{color:red;}#mermaid-svg-Hmqh75PU02bnOtoD #dependencyStart,#mermaid-svg-Hmqh75PU02bnOtoD #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-Hmqh75PU02bnOtoD .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Hmqh75PU02bnOtoD :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

CONNECTED：正常连接

CONNECTED

DISCONNECTED：网络中断

DISCONNECTED

CONNECTED：超时前重连成功

EXPIRED：超过会话超时时间

EXPIRED

：会话失效，需重建

Apache 官方 FAQ 的描述 ：

当客户端（会话）与 ZK 服务集群断开连接时，它将开始在会话创建时指定的服务器列表中进行搜索。最终，当客户端与至少一个服务器重新建立连接时，会话要么再次转换为"connected"状态（如果在会话超时时间内重新连接），要么转换为"expired"状态（如果在会话超时后重新连接）。

四、会话过期的连锁反应

当会话过期时，会发生以下一系列事件 ：

4.1 临时节点被删除

ZooKeeper 服务端会清理该会话创建的所有临时节点：

// 服务端清理逻辑示意
public class SessionCleanup {

public void cleanupSession(long sessionId) {
// 1. 从 ephemerals 映射中获取该会话的所有临时节点
Set<String> ephemeralNodes = ephemerals.get(sessionId);

// 2. 将删除操作转换为事务
for (String path : ephemeralNodes) {
deleteNode(path);
}

// 3. 从会话跟踪器中移除
sessionTracker.removeSession(sessionId);
}
}

4.2 Watcher 失效

该会话注册的所有 Watcher 都会失效，服务端不会再推送任何通知 。

4.3 客户端收到 SESSION_EXPIRED 异常

public class SessionExpiredHandler implements Watcher {

@Override
public void process(WatchedEvent event) {
if (event.getState() == Event.KeeperState.Expired) {
System.err.println("会话已过期，原会话ID: " +
Long.toHexString(zk.getSessionId()));

// 必须重建会话
reconnect();
}
}

private void reconnect() {
try {
// 关闭旧连接
if (zk != null) {
zk.close();
}

// 创建新会话
CountDownLatch latch = new CountDownLatch(1);
zk = new ZooKeeper(connectString, sessionTimeout, event -> {
if (event.getState() == Event.KeeperState.SyncConnected) {
latch.countDown();
}
});

latch.await(sessionTimeout, TimeUnit.MILLISECONDS);

// 重新创建临时节点
recreateEphemeralNodes();

} catch (Exception e) {
e.printStackTrace();
}
}
}

4.4 CONNECTIONLOSS vs SESSIONEXPIRED 对比

五、使用 Curator 优雅处理会话过期

Curator 提供了高级的会话管理机制，通过 ConnectionStateListener 可以优雅处理会话过期 。

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.state.ConnectionState;
import org.apache.curator.framework.state.ConnectionStateListener;
import org.apache.zookeeper.CreateMode;

public class SessionConnectionListener implements ConnectionStateListener {

private String path;
private String data;

public SessionConnectionListener(String path, String data) {
this.path = path;
this.data = data;
}

@Override
public void stateChanged(CuratorFramework client, ConnectionState newState) {
switch (newState) {
case LOST:
// 会话已过期，需要重建
System.err.println("会话丢失，尝试重建…");
handleSessionExpired(client);
break;

case RECONNECTED:
// 会话恢复
System.out.println("重连成功，会话恢复");
break;

case SUSPENDED:
// 连接挂起，但会话可能仍有效
System.out.println("连接挂起，可能网络故障");
break;
}
}

private void handleSessionExpired(CuratorFramework client) {
while (true) {
try {
if (client.getZookeeperClient().blockUntilConnectedOrTimedOut()) {
// 重新创建临时节点
client.create()
.creatingParentsIfNeeded()
.withMode(CreateMode.EPHEMERAL)
.forPath(path, data.getBytes("UTF-8"));
System.out.println("会话重建成功");
break;
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
break;
} catch (Exception e) {
// 重试
try {
Thread.sleep(1000);
} catch (InterruptedException ie) {
Thread.currentThread().interrupt();
break;
}
}
}
}
}

// 使用示例
CuratorFramework client = CuratorFrameworkFactory.builder()
.connectString("localhost:2181")
.sessionTimeoutMs(15000)
.retryPolicy(new ExponentialBackoffRetry(1000, 3))
.build();

client.getConnectionStateListenable().addListener(
new SessionConnectionListener("/recovery/node", "data")
);
client.start();

六、最佳实践总结

6.1 配置清单

6.2 会话过期处理流程图

#mermaid-svg-CmpwG06BzT7y7HiG{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CmpwG06BzT7y7HiG .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CmpwG06BzT7y7HiG .error-icon{fill:#552222;}#mermaid-svg-CmpwG06BzT7y7HiG .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CmpwG06BzT7y7HiG .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CmpwG06BzT7y7HiG .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CmpwG06BzT7y7HiG .marker.cross{stroke:#333333;}#mermaid-svg-CmpwG06BzT7y7HiG svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CmpwG06BzT7y7HiG p{margin:0;}#mermaid-svg-CmpwG06BzT7y7HiG .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-CmpwG06BzT7y7HiG .cluster-label text{fill:#333;}#mermaid-svg-CmpwG06BzT7y7HiG .cluster-label span{color:#333;}#mermaid-svg-CmpwG06BzT7y7HiG .cluster-label span p{background-color:transparent;}#mermaid-svg-CmpwG06BzT7y7HiG .label text,#mermaid-svg-CmpwG06BzT7y7HiG span{fill:#333;color:#333;}#mermaid-svg-CmpwG06BzT7y7HiG .node rect,#mermaid-svg-CmpwG06BzT7y7HiG .node circle,#mermaid-svg-CmpwG06BzT7y7HiG .node ellipse,#mermaid-svg-CmpwG06BzT7y7HiG .node polygon,#mermaid-svg-CmpwG06BzT7y7HiG .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-CmpwG06BzT7y7HiG .rough-node .label text,#mermaid-svg-CmpwG06BzT7y7HiG .node .label text,#mermaid-svg-CmpwG06BzT7y7HiG .image-shape .label,#mermaid-svg-CmpwG06BzT7y7HiG .icon-shape .label{text-anchor:middle;}#mermaid-svg-CmpwG06BzT7y7HiG .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-CmpwG06BzT7y7HiG .rough-node .label,#mermaid-svg-CmpwG06BzT7y7HiG .node .label,#mermaid-svg-CmpwG06BzT7y7HiG .image-shape .label,#mermaid-svg-CmpwG06BzT7y7HiG .icon-shape .label{text-align:center;}#mermaid-svg-CmpwG06BzT7y7HiG .node.clickable{cursor:pointer;}#mermaid-svg-CmpwG06BzT7y7HiG .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-CmpwG06BzT7y7HiG .arrowheadPath{fill:#333333;}#mermaid-svg-CmpwG06BzT7y7HiG .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-CmpwG06BzT7y7HiG .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-CmpwG06BzT7y7HiG .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-CmpwG06BzT7y7HiG .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-CmpwG06BzT7y7HiG .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-CmpwG06BzT7y7HiG .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-CmpwG06BzT7y7HiG .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-CmpwG06BzT7y7HiG .cluster text{fill:#333;}#mermaid-svg-CmpwG06BzT7y7HiG .cluster span{color:#333;}#mermaid-svg-CmpwG06BzT7y7HiG div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-CmpwG06BzT7y7HiG .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-CmpwG06BzT7y7HiG rect.text{fill:none;stroke-width:0;}#mermaid-svg-CmpwG06BzT7y7HiG .icon-shape,#mermaid-svg-CmpwG06BzT7y7HiG .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-CmpwG06BzT7y7HiG .icon-shape p,#mermaid-svg-CmpwG06BzT7y7HiG .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-CmpwG06BzT7y7HiG .icon-shape rect,#mermaid-svg-CmpwG06BzT7y7HiG .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-CmpwG06BzT7y7HiG .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-CmpwG06BzT7y7HiG .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-CmpwG06BzT7y7HiG :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

是

否

会话过期

服务端清理临时节点

客户端收到 EXPIRED 事件

关闭旧连接

创建新 ZooKeeper 实例

连接成功？

重新创建临时节点

重试策略

重新注册 Watcher

恢复服务

通知其他客户端

其他客户端更新状态

6.3 核心要点回顾

6.4 一句话总结

ZooKeeper 会话超时是客户端与服务端之间的"生命契约"：客户端通过 sessionTimeout 参数提议超时时间，服务端通过 min/maxSessionTimeout 进行协商 ；一旦超过协商后的时间未收到心跳，服务端将清理会话及关联的临时节点 ，客户端收到 SESSION_EXPIRED 后必须重建连接并恢复状态 ，而这一切需要通过完善的监听器和重试机制来保障 。