Go HTTP/2 PING 超时引发连接回收的诊断方法

Go HTTP/2 连接因 PING 超时被回收，判断依据不是“连接空闲了多久”，而是连接在读空闲后发出健康检查 PING，却没有在 PingTimeout 内收到响应。客户端常见结果是 http2: client connection lost，可观测回调会记录 conn_close_lost_ping；服务端则可能记录等待 PING 响应超时。先把这三个证据对齐，再排查中间负载均衡、NAT、对端事件循环或网络抖动。

官方文档：https://pkg.go.dev/net/http

先确认连接为什么会被回收

HTTP/2 的 PING 健康检查有两个时间段。连接在 SendPingTimeout 内没有收到任何帧时，Go 才发送 PING；发送后进入 PingTimeout 等待窗口。如果期间收到匹配的 PING ACK，连接继续复用；如果没有响应，Transport 会把连接标记为丢失并关闭，连接上的流也会收到错误。

这里的“读空闲”是没有从连接读到帧，并不等于应用没有业务请求。长时间上传、对端写阻塞、代理只保持 TCP 会话却不转发 HTTP/2 帧，都可能让这一计时器到期。反过来，只要持续收到其他帧，健康检查计时会被刷新，不会因为没有业务响应正文就机械地发 PING。

因此，下面几种现象不能单独证明 PING 超时：

• 只看到请求的 context deadline exceeded：这是请求级截止时间，可能早于连接健康检查。
• 只看到连接不再复用：普通空闲回收、GOAWAY、最大空闲时间和服务重启都会产生相似结果。
• 只看到 TCP 连接关闭：还需要确认关闭前是否发出了 HTTP/2 PING，以及是否缺少对应 ACK。

四类诊断手段怎么选

排查时不要一开始就打开最详细的协议日志。四类手段的成本和回答范围不同，组合顺序比单个工具更重要。

推荐选择是：生产环境常驻 CountError 计数；在错误样本上增加 httptrace 的连接复用信息；仍无法定位时，对单个实例短时开启协议日志；只有应用明确发出 PING 而 ACK 未回来时，再把代理空闲超时、丢包和对端卡顿作为重点。

用 CountError 建立低开销证据

当前 net/http 的 HTTP2Config.CountError 会在 HTTP/2 错误发生时回调一个稳定的错误类型。PING 等待超时关闭连接时，Go 使用 conn_close_lost_ping。这个值适合做低基数计数器标签，但不要把远端地址、完整 URL 或请求 ID 直接塞进指标标签，否则会制造高基数。

package transport

import (
    "log/slog"
    "net/http"
    "sync/atomic"
    "time"
)

var lostPingTotal atomic.Uint64

func NewClient() *http.Client {
    protocols := new(http.Protocols)
    // 同时允许 HTTP/1 与 HTTP/2，便于与普通 HTTPS 服务协商。
    protocols.SetHTTP1(true)
    protocols.SetHTTP2(true)

    tr := &http.Transport{
        Protocols: protocols,
        HTTP2: &http.HTTP2Config{
            // 连接在 30 秒没有读到任何帧后发送健康检查 PING。
            SendPingTimeout: 30 * time.Second,
            // PING 发出后 10 秒收不到响应就关闭连接。
            PingTimeout: 10 * time.Second,
            CountError: func(errType string) {
                if errType == "conn_close_lost_ping" {
                    lostPingTotal.Add(1)
                }
                // 仅记录低基数错误类型，不写请求头或敏感参数。
                slog.Warn("HTTP/2 transport error", "type", errType)
            },
        },
    }

    return &http.Client{
        Transport: tr,
        // 总请求超时独立于连接 PING，按业务 SLA 单独设置。
        Timeout: 20 * time.Second,
    }
}

观察时至少关联三条曲线：conn_close_lost_ping 增量、请求网络错误数、新建连接或 TLS 握手数。如果 lost-ping 与请求错误、新连接同时抬升，说明连接回收影响了业务；若只有 lost-ping 增加但请求成功率稳定，可能是池中空闲连接被及时替换，优先检查参数是否过于激进。

旧项目直接使用 golang.org/x/net/http2 时，对应字段名是 ReadIdleTimeout、PingTimeout 和 CountError。当前文档已把这些字段标记为迁移到 http.Transport.HTTP2 与 http.HTTP2Config 的方向；不要在同一个 Transport 上重复配置两套互相覆盖的参数。

用 httptrace 判断是否命中旧连接

net/http/httptrace 不能直接告诉你“PING ACK 丢了”，但它能回答请求失败前拿到的连接是否复用、是否来自空闲池以及空闲了多久。如果故障几乎都发生在 Reused=true、WasIdle=true 且空闲时间接近某个固定阈值的请求上，就应把代理或 NAT 的空闲回收阈值与 Go 的健康检查窗口放在一起比较。

trace := &httptrace.ClientTrace{
    GotConn: func(info httptrace.GotConnInfo) {
        // 只记录连接复用属性，不读取或操作 Transport 持有的连接。
        slog.Info("request got connection",
            "reused", info.Reused,
            "was_idle", info.WasIdle,
            "idle_ms", info.IdleTime.Milliseconds(),
        )
    },
    WroteRequest: func(info httptrace.WroteRequestInfo) {
        if info.Err != nil {
            // 写请求失败与 lost-ping 同时出现时，检查连接是否刚被判定失联。
            slog.Warn("request write failed", "error", info.Err)
        }
    },
}

req, err := http.NewRequestWithContext(ctx, http.MethodGet, targetURL, nil)
if err != nil {
    return err
}
// 把追踪钩子只绑定到当前请求，避免全局日志噪声。
req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

注意 GotConnInfo.Conn 由 Transport 管理，官方文档明确指出调用方不应读、写或关闭它。排查代码只记录复用元数据，不要为了“探活”自行向这条连接写字节。

协议日志和网络指标何时启用

当 CountError 已确认 lost-ping，但 httptrace 只能说明“旧连接失败”，可以对单个实例、单个时间窗开启 HTTP/2 详细日志，并用请求 ID、连接远端地址和统一时钟与负载均衡日志对齐。示例命令只适合受控复现，结束后立即撤销：

# 仅在短时受控窗口内开启详细 HTTP/2 调试日志，避免长期产生大量输出。
GODEBUG=http2debug=2 ./your-service

# 复现结束后恢复默认日志级别，再由指标确认错误是否消失。
GODEBUG=http2debug=0 ./your-service

如果日志显示 PING 已写出而 ACK 未返回，接下来比较四个时间：Go 的 SendPingTimeout、Go 的 PingTimeout、负载均衡或代理的 HTTP/2/TCP 空闲超时、对端的暂停或事件循环延迟。典型误区是把 PingTimeout 调得比一次正常的短暂网络抖动还小，健康检查反而主动制造频繁重连。

网络侧证据应围绕连接重置、空闲回收、丢包重传和后端实例状态，而不是只看应用 5xx。PING 超时通常表现为传输层连接失效，请求甚至可能尚未到达业务 Handler。若只有某个可用区、某种代理链路或某批实例异常，优先比较路径差异；若所有路径同时出现并伴随 CPU 停顿或 goroutine 调度延迟，则更应检查对端处理能力。

配置与重试的边界

SendPingTimeout 不宜短于正常连接无帧间隔，PingTimeout 则要覆盖可接受的网络往返抖动与对端调度延迟。实践中先测量，再选择参数：让健康检查早于中间设备的硬空闲回收阈值发生，同时给 ACK 留出合理余量。不要直接复制固定秒数到所有跨地域链路。

连接回收后是否自动重试也要单独评估。net/http 对已成功使用过的连接发生网络错误时，只会在满足幂等且请求体可重放等条件下重试。GET、HEAD 等通常更安全；带副作用的 POST 不应假设 Transport 会自动补偿。业务侧若要重试，应配合幂等键、可重放请求体和明确的重试预算。

常见问题

PingTimeout 越大越好吗？

不是。过小会把暂时抖动误判为失联，过大则让坏连接在池中停留更久。应根据链路往返时间、对端最大可接受暂停和中间设备超时共同确定。

关闭 PING 健康检查能解决问题吗？

把 SendPingTimeout 设为零会停用这类健康检查，但只会推迟坏连接暴露，并不会修复代理丢帧或对端卡顿。除非已有其他可靠的连接健康机制，否则不应把关闭探测当作根因修复。

TCP Keepalive 和 HTTP/2 PING 能互相替代吗？

不能完全替代。TCP Keepalive 判断底层连接是否存活，HTTP/2 PING 则由协议端点确认 HTTP/2 通道仍能收发帧。两者的超时、可观测位置和中间设备处理方式不同。

为什么服务端没有业务 5xx，却有大量连接回收？

因为 PING 超时发生在连接层，请求可能没有进入业务 Handler。此时应把 lost-ping 指标、新建连接数、代理回收记录和实例调度停顿放在同一时间轴上，而不是只查看 HTTP 状态码。