TLS 会话复用未命中时的缓存边界

Go 客户端启用了 ClientSessionCache，并不等于每个请求都能看到 TLS 会话恢复。先看最容易混淆的一点：HTTP keep-alive 复用的是同一条已经完成握手的连接，没有第二次 TLS 握手；TLS 会话恢复则发生在新建 TCP/TLS 连接时。只有确认连接确实是新的，再观察 ConnectionState.DidResume，缓存命中率才有意义。

先给结论：缓存命中和连接复用不是一件事

一次请求可能走三条不同路径。第一种是 Transport 直接复用空闲连接，此时没有新握手，也谈不上本次请求的 TLS 会话恢复。第二种是新建连接并使用会话票据或 PSK 恢复，DidResume 为真。第三种是新建连接但条件不满足，执行完整握手，DidResume 为假。

因此，“请求很快”不能证明会话缓存命中，“DidResume 一直为 false”也不能在没有排除 keep-alive 的情况下证明缓存失效。排查时应先确认 Transport 是否复用了旧连接，再对真正的新连接检查 TLS 状态。

升级范围：哪些变化会让复用失效

Go 的 ClientSessionCache 负责为给定服务保存可恢复的客户端状态。TLS 1.2 及以前主要使用会话票据；TLS 1.3 则通过同一接口支持 PSK 恢复。缓存接口不是全局共享存储，它只在持有该实例的进程里生效，而且必须能被多个 goroutine 并发调用。

旧代码风险：每次 new cache 等于没有跨连接缓存

下面这种工厂函数看起来“已经配置缓存”，但每次调用都会得到空缓存。第一次连接只能写入票据，第二次连接如果又拿到另一个缓存，前一次写入的状态根本不可见。

func newTransport() *http.Transport {
    return &http.Transport{
        TLSClientConfig: &tls.Config{
            MinVersion:       tls.VersionTLS12,
            // 错误示例：每次创建 Transport 都得到一个空缓存。
            ClientSessionCache: tls.NewLRUClientSessionCache(64),
        },
    }
}

如果业务每次请求都调用 newTransport，还会同时失去 HTTP 连接池。正确的生命周期通常是：一个长期存活的 http.Client 持有一个长期存活的 Transport，该 Transport 再引用一个长期存活的会话缓存。

新写法：复用进程级并发安全 LRU 缓存

标准库的 NewLRUClientSessionCache 已满足并发安全要求，适合作为多数客户端的起点。容量表示要保留的会话缓存键数量，不是 HTTP 连接数。容量小于 1 时标准库会采用默认容量，但生产配置最好写出经过估算的正数，避免含义模糊。

package client

import (
    "crypto/tls"
    "crypto/x509"
    "net"
    "net/http"
    "time"
)

// 在进程生命周期内复用，不要放进单次请求函数。
var sessionCache = tls.NewLRUClientSessionCache(256)

func NewHTTPClient(serverName string, roots *x509.CertPool) *http.Client {
    tlsConfig := &tls.Config{
        ServerName:         serverName,
        RootCAs:            roots,
        MinVersion:         tls.VersionTLS12,
        ClientSessionCache: sessionCache,
    }

    transport := &http.Transport{
        TLSClientConfig: tlsConfig,
        DialContext: (&net.Dialer{
            Timeout:   5 * time.Second,
            KeepAlive: 30 * time.Second,
        }).DialContext,
        MaxIdleConns:        100,
        MaxIdleConnsPerHost: 20,
        IdleConnTimeout:     90 * time.Second,
    }

    return &http.Client{
        Transport: transport,
        Timeout:   15 * time.Second,
    }
}

tls.Config 交给 TLS 组件后不应继续修改。若不同目标需要不同 ServerName，应为目标创建稳定配置，或在接管拨号时先调用 Clone 再设置字段，不能让多个并发握手竞争修改同一个对象。

缓存边界：ServerName、进程与 LRU 容量

会话缓存并不是“所有 TLS 连接共用一个票据池”。它围绕服务身份查找状态，所以同一 IP 使用不同的 ServerName，或者同一域名在不同代码路径里使用不同名称，都可能进入不同缓存边界。ServerName 还参与证书主机名校验和 SNI，不能为了提高命中率而随意改成另一个值。

缓存也不会跨进程自动共享。滚动发布、Pod 重建、进程崩溃重启后出现一段冷启动完整握手是正常现象。LRU 容量过小时，访问大量服务身份会把较旧条目淘汰；容量过大则会让会话状态在内存中保留更久。应按真实目标数量和安全策略取值，而不是按 QPS 机械放大。

服务端边界：多节点票据密钥必须协调

客户端缓存 Get 命中，只代表它找到了可尝试的会话状态，不保证服务端一定接受。若负载均衡把后续新连接送到另一台 TLS 终止节点，而该节点没有对应的票据密钥，就会回退到完整握手。对同一主机提供服务的多个 TLS 终止节点，应采用受控的密钥同步与轮换方案，或者在统一入口终止 TLS。

Go 文档说明，多台服务器为同一主机终止连接时应共享会话票据密钥；同时也明确提醒密钥泄露会危及过去和未来的连接。自定义轮换或同步应使用 SetSessionTicketKeys，不要把票据密钥、会话票据或缓存键打印到日志，也不要把静态密钥硬编码进仓库。

TLS 1.3 还允许服务器在同一连接上提供多个票据，因此自定义 ClientSessionCache.Put 可能在一条连接上被调用多次。监控 Put 次数时必须记住这一点，不能把它直接当成“成功握手数”。

回归检查：DidResume 与 httptrace 要一起看

最可靠的回归方式是把“是否复用现有连接”和“新 TLS 连接是否恢复”拆成两个指标。下面的示例只记录布尔状态，不输出缓存键、票据或证书私密信息。

package main

import (
    "context"
    "log"
    "net/http"
    "net/http/httptrace"
)

func doRequest(ctx context.Context, client *http.Client, url string) error {
    trace := &httptrace.ClientTrace{
        GotConn: func(info httptrace.GotConnInfo) {
            // Reused=true 表示复用了既有连接，本次没有新的 TLS 握手。
            log.Printf("http_connection_reused=%t", info.Reused)
        },
    }

    req, err := http.NewRequestWithContext(
        httptrace.WithClientTrace(ctx, trace),
        http.MethodGet,
        url,
        nil,
    )
    if err != nil {
        return err
    }

    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    if resp.TLS != nil {
        // 只有确认这是新连接时，DidResume 才回答本次新握手是否恢复。
        log.Printf("tls_did_resume=%t", resp.TLS.DidResume)
    }
    return nil
}

测试时可以先完成一次请求，让客户端收到并保存票据；随后强制创建一条新连接，再看 DidResume。不要仅通过关闭响应体来假设一定会新建连接，也不要把生产代码中的 keep-alive 全局关闭当成长期修复。HTTP 连接池通常比频繁新建并恢复 TLS 连接更省成本。

需要缓存指标时，包装接口而不是记录敏感数据

标准接口允许包装 Get 和 Put 来统计命中、未命中与写入次数。包装器必须并发安全；内部缓存仍使用标准 LRU，计数器使用原子操作。日志只输出聚合计数，不保存原始 key。

type metricsCache struct {
    inner  tls.ClientSessionCache
    hits   atomic.Uint64
    misses atomic.Uint64
    puts   atomic.Uint64
}

func (c *metricsCache) Get(key string) (*tls.ClientSessionState, bool) {
    state, ok := c.inner.Get(key)
    if ok {
        c.hits.Add(1)
    } else {
        c.misses.Add(1)
    }
    return state, ok
}

func (c *metricsCache) Put(key string, state *tls.ClientSessionState) {
    // state 为 nil 时由底层缓存执行删除语义。
    c.inner.Put(key, state)
    c.puts.Add(1)
}

即使 Get 返回命中，服务端仍可能拒绝恢复，因此缓存命中指标必须与 DidResume 分开。前者回答“客户端是否找到候选状态”，后者回答“握手是否真正恢复”。

迁移清单

• 确认 ClientSessionCache 非 nil，并在 Transport 或客户端生命周期内复用。
• 确认自定义缓存实现可并发调用，Put 能处理 nil 删除和 TLS 1.3 多次写入。
• 确认 ServerName 稳定且与证书身份匹配，不用 IP、别名或空值混用。
• 确认排查对象是新连接，不把 keep-alive 命中误认为 TLS 会话恢复。
• 确认 LRU 容量覆盖实际服务身份数量，并接受进程重启后的冷缓存。
• 确认同一主机的多节点 TLS 终止方案能安全协调票据密钥及轮换。
• 用 GotConnInfo.Reused、Get 命中和 DidResume 三组指标分别定位。
• 禁止记录会话票据、原始缓存键和票据密钥。

常见问题

ClientSessionCache 容量应该等于并发连接数吗？

不应该。容量面向会话缓存键，而不是连接数。先按客户端会访问的服务身份数量估算，再根据淘汰和内存情况调整。

为什么第二次请求的 DidResume 仍然是 false？

先看是否复用了同一 HTTP 连接。如果确实新建连接，再检查缓存实例是否复用、ServerName 是否一致、票据是否已获得、LRU 是否淘汰，以及服务端节点是否能接受该票据。

为了测试，应该永久关闭 keep-alive 吗？

不应该。关闭 keep-alive 只适合隔离测试路径，生产中优先复用已经建立的连接；会话恢复是新连接不可避免时的优化，不是连接池的替代品。