---
title: "TCP 保持连接配置"
date: 2026-03-01
lastmod: 2026-03-01
description: "控制 TCP 保持连接选项的配置项说明"
tags: ["网络配置", "连接管理", "TCP参数"]
summary: "配置项作用 #  network.tcp.keep_alive 配置项控制是否启用 TCP 的 SO_KEEPALIVE 选项。启用后，操作系统会定期发送保活数据包来检测连接是否仍然有效，防止长时间空闲连接被中间设备（如防火墙、NAT 路由器）断开。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  true（启用保持连接） 是否必需 #  可选配置项（有默认值）
取值范围 #  true - 启用 TCP keep-alive false - 禁用 TCP keep-alive 配置格式 #  # 默认配置（启用保持连接） network.tcp.keep_alive: true # 禁用保持连接 network.tcp.keep_alive: false 相关配置项 #     配置项 默认值 说明     network.tcp.keep_alive true TCP 保持连接开关   network.tcp.keep_idle -1 空闲时间（秒）   network."
---


## 配置项作用

`network.tcp.keep_alive` 配置项控制是否启用 TCP 的 `SO_KEEPALIVE` 选项。启用后，操作系统会定期发送保活数据包来检测连接是否仍然有效，防止长时间空闲连接被中间设备（如防火墙、NAT 路由器）断开。

## 配置项类型

该配置项为**静态配置**，需要在启动时设置，修改后需要重启节点才能生效。

## 默认值

```
true（启用保持连接）
```

## 是否必需

**可选配置项**（有默认值）

## 取值范围

```
true  - 启用 TCP keep-alive
false - 禁用 TCP keep-alive
```

## 配置格式

```yaml
# 默认配置（启用保持连接）
network.tcp.keep_alive: true

# 禁用保持连接
network.tcp.keep_alive: false
```

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `network.tcp.keep_alive` | true | TCP 保持连接开关 |
| `network.tcp.keep_idle` | -1 | 空闲时间（秒） |
| `network.tcp.keep_interval` | -1 | 心跳间隔（秒） |
| `network.tcp.keep_count` | -1 | 心跳次数 |
| `transport.tcp.keep_alive` | true | 传输层保持连接 |

## 工作原理

TCP Keep-Alive 机制：

```
┌─────────────────────────────────────────────────────────────────┐
│                    TCP Keep-Alive 工作流程                        │
└─────────────────────────────────────────────────────────────────┘

建立连接
    │
    ├── 正常数据传输
    │
    └── 连接空闲
        │
        ├── 启用 keep_alive
        │   │
        │   ├── 等待 keep_idle 时间
        │   │
        │   ├── 发送 keep-alive 探测包
        │   │
        │   ├── 等待响应
        │   │   │
        │   │   ├── 收到 ACK → 连接正常
        │   │   │
        │   │   └── 未收到 ACK
        │   │       │
        │   │       ├── 重试 keep_count 次
        │   │       │   间隔 keep_interval
        │   │       │
        │   │       └── 仍无响应 → 关闭连接
        │   │
        │   └── 通知应用层连接断开
        │
        └── 禁用 keep_alive
            │
            └── 永不主动探测
                连接可能被中间设备断开
```

## 中间设备断开连接问题

```
常见断开连接的场景:

1. 防火墙/NAT 超时
    - 连接空闲时间过长
    - 防火墙自动断开
    - 双方不知道连接已断开

2. 负载均衡器超时
    - 空闲连接超时
    - 连接被删除
    - 后续请求失败

3. 网络设备重启
    - 交换机/路由器重启
    - TCP 连接状态丢失
    - 连接实际已断开

启用 keep_alive 的好处:
    ✓ 定期检测连接状态
    ✓ 及时发现断开连接
    ✓ 防止资源泄漏
    ✓ 提高集群稳定性
```

## 使用场景

### 1. 默认配置（强烈推荐）

```yaml
network.tcp.keep_alive: true
```

**适用场景：**
- 所有生产环境
- 跨地域部署
- 有防火墙的网络
- 有 NAT 的网络

### 2. 禁用保持连接

```yaml
network.tcp.keep_alive: false
```

**适用场景：**
- 不推荐使用
- 特殊调试场景
- 内网无防火墙环境

## 推荐设置建议

| 网络环境 | 推荐值 | 说明 |
|---------|-------|------|
| 所有生产环境 | true | 必须启用 |
| 跨地域集群 | true | 防止长连接断开 |
| 有防火墙 | true | 防止超时断开 |
| 测试环境 | true | 保持一致 |
| 特殊调试 | false | 仅调试时使用 |

## Keep-Alive 参数详解

```
TCP Keep-Alive 相关参数:

1. network.tcp.keep_alive
   - 是否启用 keep-alive
   - 默认: true
   - 开关控制

2. network.tcp.keep_idle
   - 首次探测前的空闲时间
   - 默认: -1（使用系统默认）
   - 通常系统默认: 7200 秒（2 小时）

3. network.tcp.keep_interval
   - 探测包发送间隔
   - 默认: -1（使用系统默认）
   - 通常系统默认: 75 秒

4. network.tcp.keep_count
   - 探测失败重试次数
   - 默认: -1（使用系统默认）
   - 通常系统默认: 9 次

探测总时间 = keep_idle + keep_interval × keep_count
系统默认: 7200 + 75 × 9 = 7875 秒（约 2.2 小时）
```

## 调整 Keep-Alive 参数

```yaml
# 默认配置（使用系统默认）
network.tcp.keep_alive: true
network.tcp.keep_idle: -1
network.tcp.keep_interval: -1
network.tcp.keep_count: -1

# 快速检测配置
network.tcp.keep_alive: true
network.tcp.keep_idle: 60      # 1 分钟后开始探测
network.tcp.keep_interval: 10   # 每 10 秒探测一次
network.tcp.keep_count: 3       # 最多探测 3 次

# 总检测时间: 60 + 10 × 3 = 90 秒
```

## 配置示例

```yaml
# 场景 1: 标准生产集群
cluster.name: prod-cluster
network.tcp.keep_alive: true

# 场景 2: 快速故障检测集群
cluster.name: fast-failover-cluster
network.tcp.keep_alive: true
network.tcp.keep_idle: 60
network.tcp.keep_interval: 10
network.tcp.keep_count: 3

# 场景 3: 跨地域集群
cluster.name: geo-cluster
network.tcp.keep_alive: true
network.tcp.keep_idle: 300
network.tcp.keep_interval: 30
network.tcp.keep_count: 5
```

## 监控建议

```bash
# 查看当前配置
GET /_nodes/settings?filter_path=nodes.*.network.tcp.keep_alive

# 查看连接状态
GET /_nodes/stats/transport

# 查看节点信息
GET /_cat/nodes?v

# 系统层面检查（Linux）
# 查看系统默认值
sysctl net.ipv4.tcp_keepalive_time
sysctl net.ipv4.tcp_keepalive_intvl
sysctl net.ipv4.tcp_keepalive_probes
```

## 故障排查

```
连接异常断开问题排查:

1. 检查 keep_alive 是否启用
   GET /_nodes/settings?filter_path=*.network.tcp.keep_alive

2. 检查系统参数
   sysctl net.ipv4.tcp_keepalive_*

3. 检查防火墙超时设置
   # 防火墙连接超时应大于 keep-alive 时间

4. 检查网络设备
   # 交换机/路由器/负载均衡器超时设置

5. 抓包分析
   tcpdump -i any host <目标节点> and port 9300

常见问题:
    - 防火墙超时太短 → 调整防火墙或减少 keep_idle
    - keep_idle 太长 → 减少以更快检测断开
    - 网络不稳定 → 增加 keep_interval 和 keep_count
```

## 与故障检测的关系

```
Keep-Alive vs 故障检测:

1. TCP Keep-Alive (network.tcp.keep_alive)
   - 操作系统层面
   - 检测连接是否有效
   - 周期较长（分钟/小时级）
   - 自动处理

2. 集群故障检测
   - 应用层面
   - 检测节点是否存活
   - 周期较短（秒级）
   - 触发选举

两者配合:
    - Keep-Alive 作为基础保障
    - 故障检测作为快速检测
    - 共同确保集群稳定性
```

## 注意事项

1. **静态配置**：修改需要重启节点
2. **默认推荐**：生产环境必须启用
3. **系统依赖**：参数值为 -1 时使用系统默认
4. **合理设置**：过短的空闲时间可能增加网络负载
5. **防火墙配合**：确保防火墙超时大于 keep-alive 时间
6. **与故障检测配合**：Keep-Alive 不能替代集群故障检测