Go net.TCPConn 怎样排查 KeepAlive 参数未生效

Go 中排查 net.TCPConn 的 KeepAlive 参数未生效，先看三个事实：是否打开了内核 KeepAlive、空闲多久才发第一个探测、探测失败后由谁决定断开。最常见的误判是只调用 SetKeepAlivePeriod 却没有确认开关；另一个误判是把 SetReadDeadline 或业务心跳当成 TCP KeepAlive。

Go 1.23 及更高版本可以用 SetKeepAliveConfig 明确设置 Enable、Idle、Interval 和 Count。旧版本则用 SetKeepAlive(true) 配合 SetKeepAlivePeriod。无论哪种写法，都要记录每个调用的错误，并把操作系统是否支持该选项纳入判断。

先把“未生效”拆成三个现象

一次排查中，连接长时间没有业务数据，监控显示连接仍然存在，但对端已经不可达。代码里有“KeepAlive 已设置”的日志，实际却无法说明参数真的生效。按下面三层拆开后，问题会清晰很多：

• 开关层：SetKeepAlive(true) 或 KeepAliveConfig.Enable = true 是否打开内核探测。
• 时序层：Idle 或 SetKeepAlivePeriod 表示空闲多久后才开始探测，不是“每隔多久一定看到一个包”。
• 失败处理层：Interval 和 Count 影响探测节奏与失败次数；业务读取超时、应用心跳和 TCP KeepAlive 是不同机制。

所以，“没有马上看到探测包”不能直接推出“参数没生效”。先确认连接是否真的进入空闲状态，再结合平台工具和 API 返回值判断。

先确认拿到的确实是 TCPConn

net.Dial 返回的是 net.Conn 接口。只有底层连接是 TCP 时，才能断言为 *net.TCPConn 并调用 TCP 专用方法。断言失败、连接已关闭、或者调用返回错误，都应进入同一条故障记录，而不是只打印“配置完成”。

package main

import (
    "errors"
    "fmt"
    "net"
    "time"
)

func configureLegacyKeepAlive(conn net.Conn) error {
    tcpConn, ok := conn.(*net.TCPConn)
    if !ok {
        // 先确认协议类型，避免把非 TCP 连接误当成 TCP 连接。
        return fmt.Errorf("连接类型不是 *net.TCPConn: %T", conn)
    }

    // 先打开内核 KeepAlive，再设置空闲周期；两个调用的错误都不能丢。
    if err := tcpConn.SetKeepAlive(true); err != nil {
        return fmt.Errorf("打开 KeepAlive 失败: %w", err)
    }
    if err := tcpConn.SetKeepAlivePeriod(30 * time.Second); err != nil {
        return fmt.Errorf("设置 KeepAlive 周期失败: %w", err)
    }
    return nil
}

func classifyKeepAliveError(err error) string {
    var opErr *net.OpError
    if errors.As(err, &opErr) {
        // OpError 保留了网络操作上下文，日志要同时记录 Op、Net 和 Err。
        return fmt.Sprintf("网络操作 %s/%s 失败: %v", opErr.Op, opErr.Net, opErr.Err)
    }
    return err.Error()
}

这段兼容写法把两个职责分开：SetKeepAlive(true) 负责启用，SetKeepAlivePeriod 负责空闲时长。不要只检查最后一行日志；如果第一步失败，第二步成功也不能当成完整配置成功。

Go 1.23 以后用 KeepAliveConfig 排查更直观

Go 1.23 新增的 net.KeepAliveConfig 把三个关键参数显式拆开：Idle 是首次探测前的空闲时间，Interval 是探测之间的间隔，Count 是允许无响应的最大探测次数。Enable 不为 true 时，不能把非零的时序参数理解为已经开启探测。

func configureModernKeepAlive(conn net.Conn) error {
    tcpConn, ok := conn.(*net.TCPConn)
    if !ok {
        // 让调用方知道这里需要的是 TCP 连接，而不是任意 net.Conn。
        return fmt.Errorf("需要 TCP 连接，实际类型为 %T", conn)
    }

    err := tcpConn.SetKeepAliveConfig(net.KeepAliveConfig{
        Enable:   true,
        Idle:     30 * time.Second,
        Interval: 10 * time.Second,
        Count:    3,
    })
    if err != nil {
        // 平台不支持某个 socket 选项时，必须保留原始错误供定位。
        return fmt.Errorf("设置 TCP KeepAliveConfig 失败: %w", err)
    }
    return nil
}

官方文档规定 Idle、Interval 和 Count 为零时会选择默认值，负值则表示对应 socket 级选项保持不变。需要保留系统值时，不要把零值和负值混用。

把连接创建路径纳入排查

如果连接由 net.Dialer 创建，可以在拨号前配置 KeepAlive 或 KeepAliveConfig。服务端则可以在 net.ListenConfig 中设置接受连接的 KeepAlive。这样做能避免“只给某一条连接设置、连接池后来又创建了另一条连接”的错觉。

func newDialer() net.Dialer {
    return net.Dialer{
        Timeout: 5 * time.Second,
        KeepAliveConfig: net.KeepAliveConfig{
            // 明确启用，避免只设置时间却没有打开探测。
            Enable:   true,
            Idle:     30 * time.Second,
            Interval: 10 * time.Second,
            Count:    3,
        },
    }
}

func newListenConfig() net.ListenConfig {
    return net.ListenConfig{
        KeepAliveConfig: net.KeepAliveConfig{
            // ListenConfig 会把配置带给后续接受到的活动连接。
            Enable:   true,
            Idle:     30 * time.Second,
            Interval: 10 * time.Second,
            Count:    3,
        },
    }
}

还要注意字段优先级：官方文档说明，当 KeepAliveConfig.Enable 为 true 时，KeepAlive 字段会被忽略；同时填了两套配置时，要先确认到底是哪一套在起作用。

为什么同样的配置在不同系统上表现不同

KeepAlive 最终落到操作系统的 socket 选项。Go 文档明确写出，协议或操作系统不支持时，相关字段会被忽略或返回错误。因此排查不能只贴 Go 代码，还要记录运行平台、Go 版本、网络类型（tcp、tcp4 或 tcp6）以及配置调用的原始错误。

• Windows 旧版本：Windows 10 1709 之前，Idle、Interval、Count 的独立设置能力有限；旧系统上同时设置 Idle 和 Interval，并对 Count 使用负值更符合官方建议。
• Solaris 及衍生系统：Interval 与 Count 的正负组合存在额外限制，某些组合会得到错误。
• 默认值：Go 当前文档给出的 KeepAliveConfig 零值默认值是 Idle 15 秒、Interval 15 秒、Count 9，但这不等于所有系统的抓包表现完全一致。

如果 API 已返回错误，优先修正平台兼容或配置组合；如果 API 返回成功但还没看到探测，先按 Idle 等待，再检查连接是否真的没有数据、对端是否仍可达，以及中间设备是否改变了观测结果。

一张表记录“参数未生效”的证据

真正需要对比的是“预期配置—调用返回—连接来源—平台能力”四个字段，而不是单看业务日志里一句“KeepAlive 设置成功”。

常见问题

只调用 SetKeepAlivePeriod 可以吗？

不建议这样排查。它负责设置连接保持空闲多久后开始探测，开关仍应通过 SetKeepAlive(true) 或 KeepAliveConfig.Enable 明确设置，并检查错误。

SetReadDeadline 和 KeepAlive 是一回事吗？

不是。读写 deadline 由应用控制等待时间，KeepAlive 是操作系统针对空闲 TCP 连接发送探测的机制。两者可以同时使用，但故障现象和调整参数不同。

为什么服务端只改 ListenConfig 还要看 Accept 返回值？

ListenConfig 负责把配置带入后续接受的活动连接；业务代码仍应记录接受错误、连接类型和关闭路径，避免把另一条旧连接或连接池连接当成新配置的结果。

什么时候应该用 SetKeepAliveConfig？

使用 Go 1.23 及以后版本、并且需要分别表达首次空闲时间、探测间隔和最大未响应次数时，优先使用它。需要兼容更早 Go 版本时，保留开关加周期的写法，并单独记录平台差异。

参考资料：Go net 包官方文档、Go net/tcpsock.go 源码、Go 官方发布历史。