TLS ServerName 缺失导致证书校验失败的修复

修复 TLS ServerName 缺失，关键不是关闭证书校验，而是把“连接到哪里”和“正在验证谁”分开。TCP 可以拨到固定 IP，但 tls.Config.ServerName 应填写服务证书 DNS SAN 中的主机名；Go 会用它做主机名校验，并在它不是 IP 地址时作为 SNI 放进 ClientHello。若只想把域名流量路由到指定 IP，优先自定义 http.Transport.DialContext，不要接管 TLS 握手。确实使用 tls.Client 或 DialTLSContext 时，再显式设置 ServerName。

官方文档：https://pkg.go.dev/crypto/tls#Config

生产目标：验证服务身份，而不只是连通端口

我遇到过一次典型故障：服务发现返回内网 IP，客户端在 DialTLSContext 中直接拨这个 IP，握手却报证书名称不匹配。第一反应很容易变成“内网先跳过校验”，但真正的问题是自定义拨号接管了 TLS 握手，却没有告诉 crypto/tls 预期的服务身份。

一条安全 TLS 连接至少要回答两个独立问题：证书链是否由受信任根签发，以及叶子证书是否对当前主机名有效。RootCAs 解决前者，ServerName 参与后者。端口能连通、CA 可信，都不能代替主机名匹配。

环境准备：先确认拨号地址、URL 主机名和证书 SAN

排查前先记录三项值，不要把它们混在一起：

Go 的 x509.Certificate.VerifyHostname 对 IP 地址检查证书的 IPAddresses，对其他名称检查 DNSNames。旧的 Common Name 字段已被忽略。因此，把证书只有 DNS SAN 的服务改成按 IP 校验，不会因为 Common Name 恰好相似而通过。

安全配置：优先只改 DialContext

如果需求只是“URL 仍使用域名，但 TCP 必须连到服务发现返回的 IP”，我更推荐保留 http.Transport 的 TLS 管理，只替换明文 TCP 拨号阶段。请求 URL 中仍写真实服务域名，Transport 可以据此完成标准 TLS 握手；自定义拨号器只决定数据包发往哪个地址。

package secureclient

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

func newClient(backendAddr string) *http.Client {
    dialer := &net.Dialer{
        Timeout:   3 * time.Second,
        KeepAlive: 30 * time.Second,
    }

    // 从默认 Transport 克隆，保留合理默认值和协议协商能力。
    transport := http.DefaultTransport.(*http.Transport).Clone()
    transport.DialContext = func(ctx context.Context, network, _ string) (net.Conn, error) {
        // 只覆盖网络去向；请求 URL 仍应使用证书中的 DNS 名称。
        return dialer.DialContext(ctx, network, backendAddr)
    }
    transport.TLSClientConfig = &tls.Config{
        // 生产策略可显式要求 TLS 1.2 及以上，不关闭证书校验。
        MinVersion: tls.VersionTLS12,
    }

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

调用时 URL 要保留域名，例如 https://api.internal.example.com/health，而 backendAddr 可以是 10.0.8.21:8443。不要把 URL 也改成 IP 后再期待证书 DNS SAN 自动匹配。

什么时候必须显式设置 ServerName

直接调用 tls.Client 时，官方文档要求配置非空，并设置 ServerName 或 InsecureSkipVerify。在生产环境中应选择前者。另一个高风险点是 http.Transport.DialTLSContext：该回调返回的连接被认为已经完成 TLS 握手，Transport 的 TLSClientConfig 与握手超时不再替你完成这部分工作，所以 ServerName 必须在回调内部处理。

func dialTLSBackend(
    ctx context.Context,
    network string,
    backendAddr string,
    serverName string,
    base *tls.Config,
) (net.Conn, error) {
    dialer := &net.Dialer{Timeout: 3 * time.Second}
    raw, err := dialer.DialContext(ctx, network, backendAddr)
    if err != nil {
        return nil, fmt.Errorf("TCP 拨号失败: %w", err)
    }

    // 每次连接克隆配置，避免并发请求修改共享 tls.Config。
    cfg := base.Clone()
    cfg.ServerName = serverName

    conn := tls.Client(raw, cfg)
    if err := conn.HandshakeContext(ctx); err != nil {
        // 握手失败时必须关闭底层连接，防止文件描述符泄漏。
        _ = raw.Close()
        return nil, fmt.Errorf("TLS 握手失败: %w", err)
    }
    return conn, nil
}

serverName 应来自服务注册配置、固定映射或请求允许列表，而不是直接接受未经验证的用户输入。否则调用方可能把校验目标切换到任意名称，破坏服务身份边界。

ServerName 为什么同时影响 SNI 与证书校验

Go 官方文档说明，ServerName 用于校验返回证书上的主机名；当它不是 IP 地址时，还会加入客户端握手以支持虚拟主机。也就是说，同一字段承担两个相关但不同的职责：

• SNI 帮助一台服务器在多个域名证书中选择合适证书。
• 主机名校验确认最终证书确实声明了预期 DNS 名称或 IP 地址。

缺失 SNI 时，虚拟主机服务器可能返回默认证书；即使这张证书链受信任，只要 SAN 不包含目标主机名，主机名校验仍会失败。反过来，设置 SNI 也不等于自动信任证书，根证书链仍需由系统根或自定义 RootCAs 验证。

权限边界：私有 CA 要补 RootCAs，不要跳过校验

如果错误是 x509: certificate signed by unknown authority，说明主要问题是信任链，而不是 ServerName。内部服务使用私有 CA 时，应把组织 CA 加入专用证书池，同时继续执行主机名校验。

func loadRoots(caPEM []byte) (*x509.CertPool, error) {
    roots, err := x509.SystemCertPool()
    if err != nil {
        return nil, fmt.Errorf("读取系统根证书失败: %w", err)
    }
    // 只加入经过发布流程管理的内部 CA，不加载任意请求提供的证书。
    if ok := roots.AppendCertsFromPEM(caPEM); !ok {
        return nil, errors.New("内部 CA PEM 无有效证书")
    }
    return roots, nil
}

func newTLSConfig(roots *x509.CertPool, serverName string) *tls.Config {
    return &tls.Config{
        RootCAs:    roots,
        ServerName: serverName,
        MinVersion: tls.VersionTLS12,
        // 保持默认证书链和主机名校验，禁止 InsecureSkipVerify。
    }
}

InsecureSkipVerify: true 会让客户端接受任意服务器证书和证书中的任意主机名。官方文档明确警告，除非另有正确的自定义校验，否则这种模式会暴露于中间人攻击。它不应成为“先让生产恢复”的常规开关。

日志审计：按错误类型记录，不打印证书秘密

日志应回答“验证谁、连到哪、失败在哪一层”，但不要记录私钥、完整客户端证书或敏感请求头。可以对错误链做类型判断，把主机名不匹配与未知 CA 分开告警：

func classifyTLSError(err error) string {
    var hostnameErr x509.HostnameError
    if errors.As(err, &hostnameErr) {
        // 证书可信但名称不匹配，优先检查 ServerName 和 SAN。
        return "hostname_mismatch"
    }

    var unknownCAErr x509.UnknownAuthorityError
    if errors.As(err, &unknownCAErr) {
        // 信任链缺失，优先检查 RootCAs 和服务端中间证书链。
        return "unknown_authority"
    }

    var verifyErr *tls.CertificateVerificationError
    if errors.As(err, &verifyErr) {
        // 其他证书验证失败，保留统一分类供审计聚合。
        return "certificate_verification"
    }
    return "tls_other"
}

建议结构化记录目标服务逻辑名、经过脱敏的后端地址、配置的 ServerName、错误分类和握手耗时。ServerName 本身通常不是秘密，但它应来自配置资产，便于追踪谁在什么时候修改了服务身份映射。

发布检查：上线前逐项确认

常见问题

通过 IP 连接时 ServerName 应该填 IP 还是域名？

看证书声明的身份。如果证书只有 DNS SAN，就填对应域名，即使 TCP 实际拨到 IP；如果证书明确包含目标 IP SAN，才按 IP 校验。IP 形式的 ServerName 不会作为 SNI 发送。

设置 ServerName 后仍报 unknown authority 怎么办？

这属于信任链问题。检查服务端是否发送完整中间证书链，以及客户端 RootCAs 是否包含正确根 CA。ServerName 不能替代 CA 信任。

为什么 Common Name 正确仍校验失败？

Go 的 VerifyHostname 忽略旧 Common Name，DNS 名称应出现在证书 DNS SAN 中，IP 地址应出现在 IP SAN 中。应重新签发符合当前规则的证书。

自定义 DialTLSContext 后 TLSClientConfig 为什么没生效？

因为该回调返回的连接被 Transport 视为已经完成 TLS 握手。接管这一步就同时接管了 ServerName、RootCAs、握手超时和失败清理；若没有特殊需要，优先只自定义 DialContext。