TLS 最低版本配置与旧客户端兼容策略

我在给一个 Go 服务收紧 TLS 配置时，最先遇到的不是新客户端报错，而是一批多年没有升级的内部调用方突然握手失败。把服务端最低版本从默认策略明确设为 TLS 1.2 后，问题可以拆成两件事：双方允许的协议版本有没有交集，以及旧客户端是否值得让整个服务一起降级。

结论是：先用 tls.Config.MinVersion 表达服务的安全基线，再根据旧客户端的实际范围决定是否设置 MaxVersion；需要兼容时优先隔离入口，不要为了一个旧调用方把全局最低版本降到更低。官方参考：https://pkg.go.dev/crypto/tls

旧客户端兼容不是简单地“把 TLS 版本调低”。先确认双方版本交集，再把兼容范围限制在可观测、可退出的路径里。

先确认双方到底有没有共同版本

握手失败时，我会先画出双方的允许区间。客户端能发起的版本、服务端接受的最低版本和双方各自的最高版本共同决定结果；证书链、密码套件或服务器名称也可能导致失败，但如果日志明确指向版本不匹配，就先不要从证书方向反复试错。

例如，服务端只接受 TLS 1.2 及以上，旧客户端只支持 TLS 1.0，那么两段区间没有交集，继续改证书并不能解决根因。相反，客户端支持 TLS 1.2，服务端的最低版本也是 TLS 1.2，就应该把注意力转到证书、SNI 或密码套件等下一层。

用 MinVersion 表达服务端安全基线

在 Go 中，MinVersion 是允许的最低 TLS 版本，MaxVersion 是允许的最高版本。生产服务通常只需要明确最低版本，最高版本留给库的默认协商策略；只有在对端兼容性或合规边界很明确时，才把最高版本也固定下来。

package main

import (
    "crypto/tls"
    "log"
    "net/http"
)

func main() {
    tlsConfig := &tls.Config{
        // 把服务端最低协议版本设为 TLS 1.2，拒绝更旧的握手。
        MinVersion: tls.VersionTLS12,
    }

    server := &http.Server{
        Addr:      ":8443",
        TLSConfig: tlsConfig,
    }

    // 证书路径应替换为部署环境中的证书和私钥文件。
    if err := server.ListenAndServeTLS("server.crt", "server.key"); err != nil {
        log.Fatal(err)
    }
}

这里的关键不是把数字写进配置，而是明确“最低接受到哪里”。不要把 InsecureSkipVerify 当成版本兼容开关，它会改变客户端证书校验行为，不能修复协议版本没有交集的问题。

客户端要兼容旧服务时，先固定实际需要的范围

如果调用方确实只能使用 TLS 1.2，可以在客户端配置中把范围写清楚。设置 MaxVersion 不是“更兼容”，而是主动限制最高版本；它适合对端只支持某个版本、需要复现老设备行为或进行迁移验证的场景，不适合随手复制到所有客户端。

package main

import (
    "crypto/tls"
    "fmt"
    "net/http"
)

func main() {
    client := &http.Client{
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{
                // 兼容只支持 TLS 1.2 的旧服务，范围故意收窄为单一版本。
                MinVersion: tls.VersionTLS12,
                MaxVersion: tls.VersionTLS12,
            },
        },
    }

    resp, err := client.Get("https://service.example.test/health")
    if err != nil {
        // 版本不匹配时应保留原始错误，交给上层记录和分类。
        panic(err)
    }
    defer resp.Body.Close() // 读取响应后及时释放连接资源。
    fmt.Println(resp.StatusCode)
}

示例中的地址只是代码演示占位，不是文章要推荐的线上服务。真正的请求地址应由部署配置注入，不能因为兼容旧客户端而关闭证书校验。

用连接状态确认最终协商结果

配置写对不等于你已经知道实际使用的版本。请求成功后，可以从 resp.TLS.Version 读取连接状态，把最终协商版本、远端地址和客户端版本信息写入受控日志。这样才能区分“确实协商到了 TLS 1.2”和“请求走了另一条没有使用这份配置的连接池”。

package main

import (
    "crypto/tls"
    "fmt"
    "net/http"
)

func tlsVersionName(version uint16) string {
    // 用标准库常量映射版本，未知值保留十六进制便于排查新版本。
    switch version {
    case tls.VersionTLS12:
        return "TLS 1.2"
    case tls.VersionTLS13:
        return "TLS 1.3"
    default:
        return fmt.Sprintf("unknown(0x%04x)", version)
    }
}

func report(resp *http.Response) {
    if resp == nil || resp.TLS == nil {
        // 明文响应或空响应没有 TLS 状态，不能把它误记为协商成功。
        fmt.Println("no TLS connection state")
        return
    }
    fmt.Println("negotiated:", tlsVersionName(resp.TLS.Version))
}

复查时还要确认 Transport 是否被多个请求复用、是否存在代理终止 TLS，以及记录动作是否泄露证书内容或认证信息。只记录版本、失败分类和必要的连接元数据即可。

把兼容旧客户端变成受控例外

当旧客户端数量有限时，我更倾向于增加一个兼容入口：主入口保持 TLS 1.2 及以上，旧客户端通过独立域名、端口或网关策略进入兼容路径。兼容路径要有调用方清单、命中量、负责人和迁移截止时间，否则“临时兼容”很容易变成永久默认。

package main

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

func newServer(minVersion uint16) *http.Server {
    return &http.Server{
        // 兼容入口也要显式记录边界，避免从全局默认值漂移。
        TLSConfig: &tls.Config{MinVersion: minVersion},
        Handler:   http.NewServeMux(),
    }
}

func main() {
    mainServer := newServer(tls.VersionTLS12)
    legacyServer := newServer(tls.VersionTLS12)

    // 两个入口应绑定不同的监听地址或网关路由，并分别统计调用量。
    _ = mainServer
    _ = legacyServer
}

如果旧客户端连 TLS 1.2 也不支持，不要在主服务里无限下调最低版本。可以先让它升级；如果业务必须短期保留，则把更低版本放到隔离网络和专用代理中，同时限制权限、缩短存续时间，并将迁移指标纳入发布计划。

三个容易误判的边界

一是把证书问题当成版本问题。版本没有交集时，先修版本；版本有交集后，再看证书链、SNI、密码套件和代理终止点。

二是误用 MaxVersion。它会限制未来可协商的上限。除非你有明确的对端或回归边界，否则只设置合理的 MinVersion，并让标准库参与正常协商。

三是全局降级换取一次成功。一次握手成功不能证明策略正确。把旧客户端数量、来源和迁移状态记录下来，才知道兼容成本是否正在下降。

最后按这个顺序复查

先列出客户端和服务端支持的版本区间，再确认请求实际使用的 Transport 和 TLS 终止点；随后读取连接状态，区分版本协商成功与其他握手失败；最后检查兼容入口是否有独立指标和退出时间。这样处理后，TLS 最低版本就不再是一个孤立的数字，而是安全基线、兼容范围和迁移计划的共同边界。

常见问题：如果只需要允许 TLS 1.2，通常将 MinVersion 设为 tls.VersionTLS12；如果旧客户端只支持 TLS 1.2，才考虑在它对应的客户端或隔离入口设置相同的 MaxVersion。若双方没有共同版本，任何单纯重试都不会改变结果。