---
title: "TCP Keepalive 空闲时间配置"
date: 2026-01-13
lastmod: 2026-01-13
description: "network.tcp.keep_idle 配置项用于控制 TCP keepalive 机制开始前的空闲时间。"
tags: ["网络", "TCP", "Keepalive", "连接保活"]
summary: "配置项作用 #  network.tcp.keep_idle 配置项用于控制TCP 连接在空闲多长时间后开始发送 keepalive 探测包。
当连接在指定时间内没有数据传输时，系统会启动 TCP keepalive 机制，开始发送探测包来确认连接是否仍然活跃。
配置项属性 #   配置路径: network.tcp.keep_idle 数据类型: Integer（整数，秒） 默认值: -1（使用系统默认值） 最小值: -1 最大值: 300（5分钟） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  TCP Keepalive 空闲检测 连接建立后: 数据传输活跃: ├── 持续有数据 ├── keep_idle 计时器重置 └── 不发送探测 连接空闲: 00:00 ──→ 最后一次数据传输 00:01 ──→ 空闲中... 00:02 ──→ 空闲中... ... 05:00 ──→ 达到 keep_idle (300秒) ↓ 开始发送 keepalive probe ↓ 等待响应."
---


## 配置项作用

`network.tcp.keep_idle` 配置项用于控制**TCP 连接在空闲多长时间后开始发送 keepalive 探测包**。

当连接在指定时间内没有数据传输时，系统会启动 TCP keepalive 机制，开始发送探测包来确认连接是否仍然活跃。

## 配置项属性

- **配置路径**: `network.tcp.keep_idle`
- **数据类型**: `Integer`（整数，秒）
- **默认值**: `-1`（使用系统默认值）
- **最小值**: `-1`
- **最大值**: `300`（5分钟）
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）

## 配置项详解

## 工作机制

```
TCP Keepalive 空闲检测

连接建立后:

数据传输活跃:
├── 持续有数据
├── keep_idle 计时器重置
└── 不发送探测


连接空闲:

00:00 ──→ 最后一次数据传输
00:01 ──→ 空闲中...
00:02 ──→ 空闲中...
...
05:00 ──→ 达到 keep_idle (300秒)
        ↓
        开始发送 keepalive probe
        ↓
        等待响应...
```

## 探测时间线

```
完整 Keepalive 时间线

keep_idle = 300 (5分钟)
keep_interval = 300 (5分钟)
keep_count = 9 (系统默认)


00:00 ──→ 最后一次数据
       ↓
       空闲计时器开始


05:00 ──→ 达到 keep_idle
       ↓
       发送探测 1
       ↓
       等待 keep_interval (300秒)


10:00 ──→ 发送探测 2 (假设无响应)
       ↓
       等待 keep_interval


15:00 ──→ 发送探测 3 (假设无响应)
...
50:00 ──→ 发送探测 9 (假设无响应)
       ↓
       达到 keep_count
       ↓
       关闭连接 ❌


总空闲时间:
= keep_idle + (keep_interval × keep_count)
= 300 + (300 × 9)
= 3000 秒
= 50 分钟
```

## 特殊值说明

```
keep_idle 的特殊值

-1 (默认):
├── 使用系统默认值
├── Linux: 通常 7200 秒 (2小时)
├── Windows: 通常 7200 秒 (2小时)
├── macOS: 通常 7200 秒 (2小时)
└── 保持系统默认 ✅


0:
├── 立即开始探测
├── 不等待空闲
└── 可能产生额外开销 ⚠️


正整数 (1-300):
├── 自定义空闲时间（秒）
├── 例如: 60 (1分钟)
├── 例如: 300 (5分钟)
└── 根据网络环境设置
```

## 配置建议

## 生产环境（默认）

```yaml
network:
  tcp:
    keep_idle: -1  # 默认值
```

**建议**: 保持默认值 `-1`。使用系统默认值（通常2小时）。

## 防火墙友好

```yaml
network:
  tcp:
    keep_idle: 300  # 5分钟
```

**建议**: 设置为 `300`。防止防火墙切断空闲连接。

## 快速检测

```yaml
network:
  tcp:
    keep_idle: 60  # 1分钟
```

**建议**: 设置为 `60-180`。需要快速检测死连接时使用。

## 标准配置

```yaml
network:
  tcp:
    keep_alive: true
    keep_idle: 300
    keep_interval: 300
    keep_count: -1
```

**建议**: 设置为 `300`（5分钟）。现代网络推荐值。

## 代码示例

## easysearch.yml 基础配置

```yaml
network:
  tcp:
    keep_idle: -1
```

## 防火墙友好配置

```yaml
network:
  tcp:
    keep_alive: true
    keep_idle: 300
    keep_interval: 300
    keep_count: -1
```

## 快速检测配置

```yaml
network:
  tcp:
    keep_alive: true
    keep_idle: 60
    keep_interval: 60
    keep_count: 5
```

## 完整 TCP 配置

```yaml
network:
  tcp:
    keep_alive: true
    keep_idle: 300
    keep_interval: 300
    keep_count: -1
    no_delay: true
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `network.tcp.keep_alive` | 是否启用 keepalive | true |
| `network.tcp.keep_idle` | 空闲时间（秒） | -1 (2小时) |
| `network.tcp.keep_interval` | 探测间隔（秒） | -1 |
| `network.tcp.keep_count` | 探测次数 | -1 |

## 性能影响分析

| keep_idle 设置 | 优点 | 缺点 |
|----------------|------|------|
| 60 | 快速检测死连接 | 额外网络开销 |
| 300 | 防火墙友好 | 标准推荐 |
| 600 | 平衡开销和检测 | 中等设置 |
| -1（默认） | 系统默认 | 2小时较长 |

## 网络开销对比

```
不同 keep_idle 的探测频率

keep_idle = 60 (1分钟):

每空闲 1 分钟开始探测
假设 keep_count = 9, keep_interval = 60
每小时空闲连接探测: 约 9 次
网络开销: 低 ✅


keep_idle = 300 (5分钟):

每空闲 5 分钟开始探测
每小时空闲连接探测: 约 1-2 次
网络开销: 很低 ✅


keep_idle = -1 (默认，系统7200秒):

每空闲 2 小时开始探测
每小时空闲连接探测: 约 0 次
网络开销: 极低 ✅
```

## 使用场景

## 推荐使用默认值的场景

- **稳定内网**: 信任的内网环境
- **长时间连接**: 连接可能长时间空闲
- **系统默认**: 相信系统默认配置

## 推荐减少空闲时间的场景

- **防火墙环境**: 有防火墙可能切断空闲连接
- **负载均衡**: 经过负载均衡器
- **公网连接**: 跨越公网的连接
- **NAT 环境**: 经过 NAT 设备

## 推荐保持系统默认的场景

- **专用网络**: 专用的数据中心网络
- **稳定连接**: 网络非常稳定
- **长期运行**: 连接需要保持很长时间

## 防火墙影响

```
防火墙与 Keepalive

常见问题:

防火墙超时设置:
├── 许多防火墙: 5-15 分钟超时
├── 系统默认: 2 小时
└── 不匹配 → 连接被切断 ❌


解决方案:

keep_idle = 300 (5分钟):
├── 早于防火墙超时
├── 提前发送探测
├── 保持连接活跃
└── 防火墙不会切断 ✅


配置示例:

防火墙超时: 10 分钟
keep_idle: 300 (5分钟)
keep_interval: 300 (5分钟)
确保在防火墙超时前探测 ✅
```

## 系统默认值对比

```
不同系统的默认 keep_idle

Linux:
/proc/sys/net/ipv4/tcp_keepalive_time
默认值: 7200 秒 (2小时)
查看: cat /proc/sys/net/ipv4/tcp_keepalive_time


Windows:
默认值: 7200000 毫秒 (2小时)
注册表: TcpIp\Parameters\KeepAliveTime


macOS:
默认值: 7200 秒 (2小时)
sysctl: net.inet.tcp.keepidle


使用 -1:
├── 自动使用系统默认值
├── 跨平台一致
├── 无需手动配置
└── 推荐使用 ✅
```

## 注意事项

1. **默认值**: 默认值为 `-1`，使用系统默认值（通常2小时）。

2. **需要重启**: 修改此配置需要重启节点。

3. **单位是秒**: 配置值的单位是秒，不是毫秒。

4. **最大值限制**: 最大值为 300 秒（5分钟）。

5. **防火墙考虑**: 应根据防火墙超时设置调整。

6. **配合使用**: 需要与 `keep_interval` 和 `keep_count` 配合。

7. **网络开销**: 越小的值会产生更多网络开销。

8. **平台差异**: 不同系统的系统默认值可能不同。

9. **监控建议**: 监控连接异常中断情况。

10. **测试验证**: 配置变更后应验证连接稳定性。

## 连接保活策略

```
不同环境的 Keepalive 策略

内网环境:
keep_idle: -1
keep_interval: -1
keep_count: -1
├── 使用系统默认
├── 2 小时开始探测
└── 适合稳定内网 ✅


DMZ 环境:
keep_idle: 300
keep_interval: 300
keep_count: 9
├── 5 分钟开始探测
├── 防止防火墙切断
└── 适合 DMZ 环境 ✅


公网环境:
keep_idle: 180
keep_interval: 180
keep_count: 5
├── 3 分钟开始探测
├── 快速检测
└── 适合公网环境 ✅
```

## Java 限制说明

```
Java Socket 的限制

标准 Socket API:
Socket.setKeepAlive(true)
├── 只能启用/禁用
├── 不能设置具体参数
└── 使用系统默认 ✅


Easysearch 实现:
├── 使用 Netty/NIO
├── 直接设置 Socket 选项
├── 支持 TCP_* 参数
└── 可以自定义配置 ✅


平台兼容:
Linux: ✅ 完全支持
Windows: ✅ 完全支持
macOS: ✅ 完全支持
其他: ⚠️ 取决于 JVM 实现
```