--- title: "HTTP TCP Keep-Alive 启用配置" date: 2026-01-22 lastmod: 2026-01-22 description: "http.tcp.keep_alive 配置项用于控制是否启用 HTTP 服务器的 TCP Keep-Alive 机制。" tags: ["HTTP", "TCP", "Keep-Alive", "网络连接"] summary: "配置项作用 # 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` 配置项用于控制**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 │ │ │ │ │ 连接 发送 发送 发送 发送 建立 探测✅ 探测✅ 探测✅ 探测✅ │ ↓ 连接保持活跃 ``` ## 配置建议 ## 生产环境（默认） ```yaml http: tcp: keep_alive: true # 默认值 ``` **建议**: 保持默认值 `true`。适用于大多数生产环境，特别是云环境和跨网络部署。 ## 内网稳定网络 ```yaml http: tcp: keep_alive: true ``` **建议**: 保持启用。即使在内网环境，启用 Keep-Alive 也能提高连接可靠性。 ## 极端资源受限 ```yaml http: tcp: keep_alive: false ``` **建议**: 仅在极端资源受限且网络环境非常稳定的情况下考虑禁用。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml http: tcp: keep_alive: true # 默认值 ``` ## 完整 TCP Keep-Alive 配置 ```yaml http: tcp: keep_alive: true keep_idle: 60 # 空闲 60 秒后开始探测 keep_interval: 10 # 探测间隔 10 秒 keep_count: 5 # 最多探测 5 次 ``` ## 云环境优化配置 ```yaml http: tcp: keep_alive: true keep_idle: 30 # 缩短空闲时间 keep_interval: 5 # 更频繁的探测 keep_count: 8 # 增加重试次数 ``` ## 内网环境配置 ```yaml 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 且相关参数正确 ``` ## 注意事项 1. **默认启用**: 默认值为 `true`，适用于大多数场景。 2. **平台差异**: 不同操作系统对 TCP Keep-Alive 的支持程度不同。 3. **JDK 版本**: Java 11+ 提供了更完整的 Keep-Alive 参数支持。 4. **性能影响**: 启用 Keep-Alive 会产生少量的额外网络流量。 5. **相关配置**: Keep-Alive 需要与 `keep_idle`、`keep_interval`、`keep_count` 配合使用。 6. **防火墙规则**: 确保防火墙允许 Keep-Alive 探测包通过。 7. **负载均衡器**: 某些负载均衡器可能有自己的超时设置，需要协调配置。 8. **监控建议**: 监控连接断开和重连的情况，评估 Keep-Alive 效果。 9. **客户端配合**: 客户端也需要启用相应的 Keep-Alive 配置。 10. **动态更新**: 此配置不支持动态更新，修改后需要重启节点。