配置项作用 #
http.tcp.keep_alive 配置项用于控制HTTP 服务器是否启用 TCP Keep-Alive 机制。
TCP Keep-Alive 是一种网络连接保活机制，通过定期发送空的 TCP 探测包来保持连接活跃，检测已断开的连接，防止中间网络设备断开空闲连接。
配置项属性 #
- 配置路径:
http.tcp.keep_alive - 数据类型:
Boolean（布尔值） - 默认值:
true - 是否可选: 是
- 作用域: NodeScope（节点级别）
配置项详解 #
工作机制 #
TCP Keep-Alive 工作原理
不启用 Keep-Alive (keep_alive = false):
客户端 ────────────────────────────────→ 服务器
│ │
│ (连接空闲，长时间无数据传输) │
│ │
│ ↓ │
│ 防火墙/NAT 可能断开连接 │
│ ↓ │
│ (双方都不知道连接已断开) │
↓ ↓
【连接失效】────────────────────────【连接失效】
启用 Keep-Alive (keep_alive = true):
客户端 ────────────────────────────────→ 服务器
│ │
│ (连接空闲，但 Keep-Alive 运行中) │
│ │
│ ←── Keep-Alive 探测 ──── │
│ ↓ │
│ Keep-Alive 响应 ───→ │
│ ↓ │
│ (连接保持活跃，双方都知道连接正常) │
↓ ↓
【连接活跃】────────────────────────【连接活跃】
Keep-Alive 三阶段 #
TCP Keep-Alive 的三个阶段
阶段 1: 空闲等待 (keep_idle)
│
↓ 连接空闲超过 keep_idle 秒
↓
阶段 2: 发送探测 (keep_interval)
│
├─→ 发送探测包
│ ↓ 等待 keep_interval 秒
│
├─→ 收到响应 → 连接正常，重置计时器
│
└─→ 未收到响应 → 继续发送探测
│
↓
阶段 3: 重试判定 (keep_count)
│
├─→ 连续 keep_count 次无响应
│ ↓
│ 判定连接断开
│
└─→ 收到响应 → 连接正常，重置计时器
与防火墙/NAT 的关系 #
Keep-Alive 防止连接断开
无 Keep-Alive:
时间: 0s ────→ 300s ────→ 600s
│ │ │
连接建立 防火墙 连接被
超时断开 不可用
有 Keep-Alive (keep_idle = 60s):
时间: 0s ──→ 60s ──→ 120s ──→ 180s ──→ 240s
│ │ │ │ │
连接 发送 发送 发送 发送
建立 探测✅ 探测✅ 探测✅ 探测✅
│
↓
连接保持活跃
配置建议 #
生产环境（默认） #
http:
tcp:
keep_alive: true # 默认值
建议: 保持默认值 true。适用于大多数生产环境，特别是云环境和跨网络部署。
内网稳定网络 #
http:
tcp:
keep_alive: true
建议: 保持启用。即使在内网环境，启用 Keep-Alive 也能提高连接可靠性。
极端资源受限 #
http:
tcp:
keep_alive: false
建议: 仅在极端资源受限且网络环境非常稳定的情况下考虑禁用。
代码示例 #
easysearch.yml 基础配置 #
http:
tcp:
keep_alive: true # 默认值
完整 TCP Keep-Alive 配置 #
http:
tcp:
keep_alive: true
keep_idle: 60 # 空闲 60 秒后开始探测
keep_interval: 10 # 探测间隔 10 秒
keep_count: 5 # 最多探测 5 次
云环境优化配置 #
http:
tcp:
keep_alive: true
keep_idle: 30 # 缩短空闲时间
keep_interval: 5 # 更频繁的探测
keep_count: 8 # 增加重试次数
内网环境配置 #
http:
tcp:
keep_alive: true
keep_idle: 300 # 较长的空闲时间
keep_interval: 30 # 较长的探测间隔
keep_count: 3 # 较少的重试次数
相关配置 #
| 配置项 | 作用 | 默认值 |
|---|---|---|
http.tcp.keep_alive | 是否启用 Keep-Alive | true |
http.tcp.keep_idle | 空闲等待时间（秒） | -1（系统默认） |
http.tcp.keep_interval | 探测间隔时间（秒） | -1（系统默认） |
http.tcp.keep_count | 探测重试次数 | -1（系统默认） |
平台支持 #
TCP Keep-Alive 的平台支持情况
Linux:
✅ 完全支持
- 支持所有 Keep-Alive 参数
- 可以精细控制行为
macOS:
✅ 完全支持
- 支持所有 Keep-Alive 参数
- 行为与 Linux 类似
Windows:
⚠️ 部分支持
- 支持 SO_KEEPALIVE
- 精细控制需要 Java 11+
其他平台:
⚠️ 行为可能不同
- 依赖 JDK 版本
- 可能无法设置所有参数
使用场景 #
推荐启用的场景 #
- 云环境: 云服务商可能有连接超时限制
- 跨网络部署: 存在防火墙、NAT 等网络设备
- 长连接应用: 客户端可能长时间空闲后继续使用连接
- 高可靠性要求: 需要及时检测连接断开
- 代理/负载均衡: 通过代理或负载均衡器访问
可以考虑禁用的场景 #
- 极短连接: 每个请求完成后立即关闭连接
- 资源极度受限: CPU 或网络资源非常有限
- 稳定内网: 网络环境极其稳定且简单
Keep-Alive 超时计算 #
连接断开检测的总时间
总时间 = keep_idle + (keep_interval × keep_count)
默认配置（系统默认）:
keep_idle: 7200s (2小时)
keep_interval: 75s
keep_count: 9
总时间 = 7200 + (75 × 9) = 7875 秒 (约 2.2 小时)
优化配置:
keep_idle: 60s
keep_interval: 10s
keep_count: 5
总时间 = 60 + (10 × 5) = 110 秒 (约 2 分钟)
快速检测配置:
keep_idle: 10s
keep_interval: 2s
keep_count: 3
总时间 = 10 + (2 × 3) = 16 秒
常见问题排查 #
问题 1: 连接意外断开 #
现象: 长时间空闲后连接无法使用
原因 1: 防火墙超时
解决: 启用 Keep-Alive，缩短 keep_idle
原因 2: NAT 超时
解决: 启用 Keep-Alive，设置合理的 keep_interval
原因 3: 负载均衡器超时
解决: 检查负载均衡器配置，调整 Keep-Alive 参数
问题 2: Keep-Alive 不生效 #
现象: 配置了 Keep-Alive 但连接仍然断开
原因 1: JDK 版本过低
解决: 使用 Java 11+ 以获得完整支持
原因 2: 平台不支持
解决: 检查操作系统和 JDK 版本
原因 3: 配置错误
解决: 确保 keep_alive 为 true 且相关参数正确
注意事项 #
默认启用: 默认值为
true，适用于大多数场景。平台差异: 不同操作系统对 TCP Keep-Alive 的支持程度不同。
JDK 版本: Java 11+ 提供了更完整的 Keep-Alive 参数支持。
性能影响: 启用 Keep-Alive 会产生少量的额外网络流量。
相关配置: Keep-Alive 需要与
keep_idle、keep_interval、keep_count配合使用。防火墙规则: 确保防火墙允许 Keep-Alive 探测包通过。
负载均衡器: 某些负载均衡器可能有自己的超时设置，需要协调配置。
监控建议: 监控连接断开和重连的情况，评估 Keep-Alive 效果。
客户端配合: 客户端也需要启用相应的 Keep-Alive 配置。
动态更新: 此配置不支持动态更新，修改后需要重启节点。
