---
title: "Transport TCP Keep-Alive 空闲时间配置"
date: 2026-02-04
lastmod: 2026-02-04
description: "transport.tcp.keep_idle 配置项用于控制 TCP keep-alive 探测开始前的空闲时间。"
tags: ["Transport", "TCP", "Keep-Alive", "连接保活"]
summary: "配置项作用 #  transport.tcp.keep_idle 配置项用于控制TCP keep-alive 探测开始前的空闲时间（秒）。
配置项属性 #   配置路径: transport.tcp.keep_idle 数据类型: Integer（整数，秒） 默认值: -1（使用操作系统默认值） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置建议 #  默认配置 #  transport: tcp: keep_idle: -1 # 使用操作系统默认值 快速检测场景 #  transport: tcp: keep_alive: true keep_idle: 30 # 30秒空闲后开始探测 keep_interval: 5 # 每5秒发送一次探测 keep_count: 3 # 3次探测失败后声明连接死亡 稳定网络环境 #  transport: tcp: keep_alive: true keep_idle: 300 # 5分钟空闲后开始探测 keep_interval: 30 # 每30秒发送一次探测 keep_count: 5 # 5次探测失败后声明连接死亡 注意事项 #    非动态更新: 需要重启节点生效。"
---


## 配置项作用

`transport.tcp.keep_idle` 配置项用于控制**TCP keep-alive 探测开始前的空闲时间（秒）**。

## 配置项属性

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

## 配置建议

## 默认配置

```yaml
transport:
  tcp:
    keep_idle: -1  # 使用操作系统默认值
```

## 快速检测场景

```yaml
transport:
  tcp:
    keep_alive: true
    keep_idle: 30       # 30秒空闲后开始探测
    keep_interval: 5    # 每5秒发送一次探测
    keep_count: 3       # 3次探测失败后声明连接死亡
```

## 稳定网络环境

```yaml
transport:
  tcp:
    keep_alive: true
    keep_idle: 300      # 5分钟空闲后开始探测
    keep_interval: 30   # 每30秒发送一次探测
    keep_count: 5       # 5次探测失败后声明连接死亡
```

## 注意事项

1. **非动态更新**: 需要重启节点生效。

2. **操作系统默认值**: 设置为 -1 时使用操作系统默认值，不同平台默认值不同。

3. **计时器重置**: 当有数据发送或接收时，空闲计时器会重置。

4. **常用值范围**: 通常在 30 到 300 秒（5 分钟）之间。

5. **Linux 系统对应**: 此设置配置 Linux 系统的 `TCP_KEEPIDLE` socket 选项。

6. **配置关系**: 需要配合 `transport.tcp.keep_interval` 和 `transport.tcp.keep_count` 使用，共同控制 TCP keep-alive 行为。