Go TLS 最低版本设置后旧客户端为什么握手失败

Go TLS 设置最低版本后旧客户端握手失败，最直接的原因是双方没有共同可用的协议版本。例如服务端把 MinVersion 设为 tls.VersionTLS13，而客户端最多只支持 TLS 1.2，它就无法完成版本协商。MinVersion 是接入下限，不是建议优先使用的版本；它不会让旧客户端自动获得新协议能力。

Go TLS 官方文档：https://pkg.go.dev/crypto/tls

先确定服务端允许哪些客户端接入

假设一个内部文件服务把接入要求收紧为 TLS 1.3，旧 SDK 开始报握手失败。首先要确认这批 SDK 的实际最高版本。如果它们只有 TLS 1.2 能力，拒绝连接就是新策略的预期结果；如果业务仍要求这些 SDK 接入，就需要重新评估服务端策略与客户端升级计划，不能只靠重试解决。

版本协商可以先理解为两个集合的交集：客户端版本集来自客户端能力及其启用配置；服务端下限与服务端上限限定服务端允许集；两者形成共同版本集，它与版本协商是否可能成功有关。共同版本集为空时必然无法协商，但有交集仍不保证整个握手成功。

图中“客户端能力”包含客户端版本集，“服务端策略”包含服务端下限、服务端上限与服务端允许集，“协商条件”包含共同版本集与版本协商。线段表示约束与集合关系，不表示网络执行顺序。

RFC 8996 已弃用 TLS 1.0 和 TLS 1.1，不应为了恢复旧端连接就把它们重新作为普遍接入方案。TLS 1.2 与 TLS 1.3 的取舍应服从明确的安全要求和客户端清单，而不能笼统声称所有系统都必须使用同一最低版本。规范地址：https://www.rfc-editor.org/rfc/rfc8996.html。

准备证书并找出真正的 TLS 终止点

准备与服务域名匹配、在有效期内且证书链完整的服务端证书。下面的本机示例使用 localhost 作为证书名称，因此证书应包含该 SAN；用自己的受控 CA 签发并在客户端提供对应根证书。私钥文件保留给运行服务所需的账号读取，不放入代码仓库或错误截图。

同时确认 TLS 在哪里结束：如果外部客户端先连接负载均衡器，由它解密后再用 HTTP 请求 Go 后端，外部版本选择受负载均衡器控制。在 Go Server 上设置 MinVersion 不会改变前面那一跳。若前后端都使用 TLS，则是两段独立握手，应分别记录客户端、服务端和配置。

排障还要对照实际域名、端口与 SNI。只看业务配置文件里的值，不能证明正在运行的监听器或某个动态配置回调最终使用的也是这个值。

在监听服务上显式设置最低版本

下面给出原创最小服务示例。它有意只接纳 TLS 1.3，用于清楚展示最低版本的限制；代码与命令未在本文执行，后文仅说明条件性预期行为。需要兼容 TLS 1.2 且政策允许时，可以在审核客户端清单后将最低版本设置为 tls.VersionTLS12；这不会自动解决证书或算法问题。

package main

import (
    "crypto/tls"
    "errors"
    "flag"
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    certFile := flag.String("cert", "localhost.pem", "服务端证书链文件")
    keyFile := flag.String("key", "localhost-key.pem", "对应的私钥文件")
    flag.Parse()

    // 启动前加载证书，路径或密钥不匹配时立即退出。
    cert, err := tls.LoadX509KeyPair(*certFile, *keyFile)
    if err != nil {
        log.Fatal("加载证书失败，请检查文件、权限和证书密钥对应关系")
    }
    mux := http.NewServeMux()
    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        if r.TLS == nil {
            http.Error(w, "需要 TLS 连接", http.StatusBadRequest)
            return
        }
        // 这里只能记录已经进入 HTTP 处理器的连接，无法统计握手失败。
        log.Printf("http_request tls_version=%s",
            tls.VersionName(r.TLS.Version))
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        fmt.Fprintln(w, "服务已接收 HTTPS 请求")
    })

    cfg := &tls.Config{
        // 示例假设接入方已升级到 TLS 1.3；这会有意排除仅支持 1.2 的客户端。
        MinVersion:   tls.VersionTLS13,
        Certificates: []tls.Certificate{cert},
    }
    srv := &http.Server{
        // 只监听本机演示端口，不把示例服务默认暴露到公网。
        Addr:              "127.0.0.1:8443",
        Handler:           mux,
        TLSConfig:         cfg,
        ReadHeaderTimeout: 5 * time.Second,
        IdleTimeout:       30 * time.Second,
        ErrorLog:          log.Default(),
    }
    // 已在 TLSConfig 中装入证书，因此这里传空文件名。
    if err := srv.ListenAndServeTLS("", ""); err != nil &&
        !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)
    }
}

cfg 必须传到实际使用的 http.Server.TLSConfig 上。只有创建 tls.Config 却没有绑定到监听服务，不会改变接入策略。示例不固定 MaxVersion，让运行时在最低版本以上使用自身支持的范围；如果项目显式配置 MaxVersion，应同时确认它没有低于 MinVersion。

字段含义及当前默认规则可查看 https://go.dev/src/crypto/tls/common.go。生产代码宜显式表达最低版本要求，并在升级时查看对应工具链文档，不把零值含义理解为“接受任何版本”。

把配置与证书权限限定在服务边界内

tls.Config 一旦传给 TLS 函数使用，就不应继续修改其中的字段。需要切换策略时，构造新的受控配置，并通过已设计的配置替换或重新发布机制生效；不要在并发握手中直接改共享对象。

如果使用 GetConfigForClient 按域名选择配置，它返回的配置可能成为该连接的实际策略。此时既要检查外层配置，也要检查域名分支，不能只看外层 MinVersion。业务路由参数不应直接决定是否降低 TLS 下限。

InsecureSkipVerify 与协议版本集合不是一回事。关闭证书校验不会让不支持 TLS 1.3 的客户端完成 TLS 1.3 握手，还会失去正常的证书身份校验。类似地，调整 CipherSuites 不是增加协议版本支持的开关；TLS 1.3 的密码套件也不通过该字段配置。

分别记录握手失败与成功连接

日志要区分握手层与 HTTP 层。图中“接入记录”包含握手错误日志、成功请求日志，“失败条件”包含版本不匹配、证书校验失败、算法不匹配，“成功状态”包含已协商版本。握手错误日志可能关联前述失败条件，但远端错误有时只有概括信息；成功请求日志才可以记录该请求已有的 TLS 状态。

示例处理器打印 r.TLS.Version 对应的名称，用于观察成功进入 HTTP 层的连接。版本不匹配的客户端在握手阶段就可能终止，不会进入 /health，因此“应用访问日志没有错误”不能证明不存在 TLS 兼容问题。

标准库服务端在无法找到共同版本时，可产生包含 tls: client offered only unsupported versions 的错误；对端也可能仅看到协议告警。不要用完整错误字符串作为跨版本的业务协议，应结合失败端、目标入口和允许范围判断。对应实现：https://go.dev/src/crypto/tls/handshake_server.go。

只采集排障所需的版本、错误分类、入口与时间窗口，不记录私钥、会话密钥或业务请求正文。不要为普通版本兼容排查启用 TLS 密钥导出。

发布前按版本组合安排回归

在由你管理的本机或授权预发布入口，可以用以下命令分别固定客户端版本。准备支持这些选项的 OpenSSL，命令参数说明见 https://docs.openssl.org/master/man1/openssl-s_client/。第一条启动服务；后两条需在服务运行期间另行执行，不是让同一个前台会话连续等待。

# 保存 Go 示例为 main.go；使用受控签发、包含 localhost SAN 的证书与私钥。
go run main.go -cert localhost.pem -key localhost-key.pem

# 以下命令由另一执行会话发起，root-ca.pem 是对应的受信任根证书。
# 固定 TLS 1.2，用于观察最低版本为 1.3 时的拒绝行为。
openssl s_client -connect 127.0.0.1:8443 -servername localhost -CAfile root-ca.pem -verify_hostname localhost -verify_return_error -tls1_2 /null

# 固定 TLS 1.3，证书链、主机名和算法也匹配时才可能完成握手。
openssl s_client -connect 127.0.0.1:8443 -servername localhost -CAfile root-ca.pem -verify_hostname localhost -verify_return_error -tls1_3 /null

最低版本为 TLS 1.3 时，TLS 1.2 请求预期被拒绝。TLS 1.3 请求只有在证书链、名称、算法和网络条件也满足时才可能成功。s_client 握手成功本身不等于 /health 已执行；需要另行发送 HTTP 请求才会触发处理器。这里不把任何预期描述为实测结果。

上线前列出仍需支持的客户端版本，确认 TLS 终止位置；再核对实际配置分支和证书权限，安排允许版本与低于下限版本的两类回归，最后保留经过批准的配置回退记录。回退不意味着默认重新开放已弃用协议，应优先推动客户端升级。

只设置客户端 MinVersion 能修复旧客户端吗？

不能。设置只表达该客户端允许的下限，不能替换它的 TLS 实现。需要升级客户端运行时或 SDK，并检查它实际启用的版本范围。

证书重新签发后为什么还是握手失败？

证书解决的是身份和信任条件；如果双方协议版本没有交集，换证书不能创造共同版本。

TCP 连接成功是否说明 TLS 版本兼容？

不是。TCP 可达只说明传输连接条件，TLS 协商仍可能拒绝，HTTP 请求是否成功又是后续判断。