Go TLS ServerName 为什么和证书 SAN 不匹配

Go 客户端报错 x509: certificate is valid for api.example.com, not 10.0.0.8 时，通常不是 TLS 算法不兼容，而是客户端拿去校验证书的名称和证书 SAN（Subject Alternative Name）没有对上。最稳妥的修复是让 tls.Config.ServerName 使用证书里的合法 DNS 名称，并让 DNS、SNI、证书 SAN 和实际服务保持同一套身份；不要为了绕过报错直接打开 InsecureSkipVerify。

这篇文章把排查基线限定为三个可观察对象：请求最终连接到哪里、ClientHello 里带了什么 ServerName、服务端返回的证书 SAN 写了什么。三者一致时，Go 的默认主机名校验才有机会通过。

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

先用错误信息判断是哪一类不匹配

不要先改配置。先把错误中的“期望名称”和“证书允许名称”分开看，它们对应的是不同一侧：

这里的基线不是虚构的压测数字，而是三项能复核的身份字段。它们比“重试几次就好了”更能说明问题：错误里的主机名是 Go 认为应该匹配的目标，证书里的 DNSNames 或 IPAddresses 是对端声明允许的身份。

ServerName、SNI 和 SAN 不是同一个字段

tls.Config.ServerName 在客户端有两个相关职责：它用于验证返回证书的主机名；当它不是 IP 地址时，还会作为服务器名称指示（SNI）放进客户端握手，帮助反向代理选择对应的证书。证书 SAN 则是证书本身声明的 DNS 名称或 IP 地址。它们有关联，但不会自动互相改写。

因此，连接地址里出现 10.0.0.8:443，不代表证书就应该写这个 IP。常见的内网做法是“拨号走 IP，但验证和 SNI 使用内部 DNS 名称”，前提是这个名称确实在证书 SAN 中，且该 IP 上的代理会按照这个 SNI 返回正确证书。

用一份最小配置把身份对齐

如果服务证书包含 api.example.com，而网络上只能通过固定 IP 访问，可以把拨号地址和 TLS 身份拆开：

package main

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

func main() {
    transport := &http.Transport{
        // 连接可以拨到固定 IP，但 TLS 身份使用证书中的 DNS 名称。
        TLSClientConfig: &tls.Config{ServerName: "api.example.com"},
    }
    client := &http.Client{Transport: transport}

    // URL 的 host 与 ServerName 同时保持为证书认可的域名，避免代理选错证书。
    req, err := http.NewRequest(http.MethodGet, "https://api.example.com/health", nil)
    if err != nil {
        panic(err)
    }
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("TLS 请求失败：", err)
        return
    }
    // 读取并关闭响应体，避免把连接资源留在未完成状态。
    resp.Body.Close()
}

这段配置的关键不是“永远手写 ServerName”，而是让它代表证书中的服务身份。若 URL 已经是正确域名，通常不需要额外设置；http.Transport 会依据请求目标建立默认 TLS 配置。只有在拨号地址、代理或自定义连接器改变了目标时，才需要明确拆分网络地址和验证名称。

按 SAN 类型检查真正的匹配边界

Go 的证书主机名验证会区分 DNS 名称和 IP 地址。普通名称会对照证书的 DNSNames，IP 会对照 IPAddresses；证书的旧式 Common Name 不能代替 SAN。通配符也不是任意字符串替换，例如 *.example.com 可以覆盖 api.example.com，但不能直接覆盖 v1.api.example.com。

可以把检查顺序固定成下面四个问题：

1. 请求 URL 的 host 是 DNS 名称还是 IP？
2. tls.Config.ServerName 最终是否为空、是否被自定义拨号逻辑覆盖？
3. 返回证书的 SAN 中，是否存在完全匹配的 DNS 名称或 IP 地址？
4. 如果前面都对，服务端是否因为 SNI 不正确而返回了另一个虚拟主机的证书？

如果需要在已经解析出的证书对象上做单独判断，x509.Certificate.VerifyHostname 的语义也很明确：传入 DNS 名称时检查 DNSNames，传入 IP 时检查 IPAddresses；成功返回 nil，失败则返回描述不匹配的错误。

为什么“只改拨号地址”经常把问题带回来

一些自定义 net.Dialer 或服务发现代码会把域名改成 IP，再把请求交给 TLS。这样做只改变了网络连接的落点，没有自动替换证书身份。如果同时把 URL host 也改成 IP，Go 就可能按 IP 做证书验证，而证书只包含 DNS SAN，结果自然失败。

更隐蔽的情况发生在反向代理：你连接的是同一个 IP，但代理依赖 SNI 选择证书。若 ServerName 为空、拼写不同，或者用了内部别名而证书未覆盖该别名，代理可能返回默认站点证书，错误信息看起来就像“证书突然换了”。这时应该记录最终的 ServerName 和证书 SAN，而不是只盯着后端 IP。

InsecureSkipVerify 只能是受控的临时边界

InsecureSkipVerify: true 会关闭服务端证书链和主机名的默认验证。它能让握手继续，并不能证明证书、服务端身份或网络路径正确；在没有自定义验证的情况下，连接会失去抵御中间人攻击的关键保障。

生产代码应优先修正 DNS、证书 SAN、代理 SNI 或 ServerName。如果确实需要自定义根证书，使用 RootCAs 添加受信任 CA；如果确实需要自定义验证，也应在 VerifyConnection 中重新完成明确的证书和主机名判断，而不是把跳过校验当成常规配置。

tlsConfig := &tls.Config{
    // 内网 CA 应加入 RootCAs，不要用跳过校验代替信任配置。
    RootCAs:    roots,
    ServerName: "api.example.com",
}

// 仅用于受控诊断：记录期望身份，不能作为生产修复。
fmt.Println("TLS 期望的 ServerName:", tlsConfig.ServerName)

最后用一张清单收口

• 错误中的目标名称是否来自正确的服务域名，而不是临时 IP 或别名？
• 证书 SAN 是否包含这个 DNS 名称，或在 IP SAN 中包含这个 IP？
• 通配符是否只跨了一层，是否误用了证书的 Common Name？
• 反向代理是否依赖 SNI 返回正确证书？
• 是否在不必要的情况下开启了 InsecureSkipVerify？

把“拨号地址”和“证书身份”分开看，通常就能解释大多数 ServerName/SAN 报错：网络连接只负责到达某个端点，TLS 校验负责确认这个端点确实代表你请求的主机。修复时让 ServerName、SNI 和 SAN 对齐，才是可复用、可审计的结果。

相关问题

问：证书里只有域名，能不能直接用 IP 访问？
可以连接到 IP，但应让 TLS 身份仍使用证书中的域名，并确保代理接受该 SNI；如果直接按 IP 校验，则证书必须包含对应 IP SAN。

问：把 ServerName 写成服务器 IP 就能解决吗？
只有证书的 IP SAN 中包含该 IP 时才可能解决；如果证书只包含 DNSNames，这样改反而会制造新的不匹配。

问：为什么浏览器能打开，Go 却失败？
浏览器可能使用了不同的 DNS、代理或证书链；应比较两边实际访问的主机名、SNI 和返回证书，不要仅凭“浏览器能开”推断 Go 配置正确。