Go TLS 怎样处理证书主机名匹配

Go TLS 证书主机名匹配的关键，不是把请求地址原样塞进证书校验，而是明确区分“连到哪里”和“证书应该证明谁”。客户端可以拨到 10.0.0.8:443，但如果证书签给 api.example.com，就应在 tls.Config.ServerName 中写证书对应的 DNS 名称，同时保留默认校验链。这样既能支持内网 IP 拨号，也不会因为关闭校验而留下中间人风险。

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

升级范围：Go TLS 把三个名称问题分开处理

迁移旧连接代码时，先把名称相关字段拆开。网络地址决定 TCP 连接到哪个端点；ServerName 决定客户端在 TLS 层期待哪个服务名称，并参与证书主机名校验；证书本身则通过 SAN 中的 DNS 名称或 IP 地址表达它能证明的对象。

旧代码风险：用 IP 拨号时把证书名称也写成 IP

最容易遇到的错误是连接池、服务发现或测试环境把目标解析成 IP 后，代码直接把这个 IP 当作证书校验名。若证书只包含 api.example.com，Go 会把 IP 与 DNS 名称视为不同身份，握手阶段就会返回主机名不匹配。此时应该检查证书签发对象和服务发现策略，而不是先关闭校验。

如果服务端证书确实签给某个 IP，那么证书应在 SAN 的 IP 地址字段中包含这个地址；如果证书签给 DNS 名称，则把 DNS 名称放进 ServerName，网络地址仍可单独使用 IP。

新写法：拨号地址与 ServerName 分别配置

下面的示例演示一个常见内网场景：TCP 连接走固定 IP，TLS 仍按服务证书中的 DNS 名称进行 SNI 和主机名匹配。配置不设置 InsecureSkipVerify，因此系统根证书、证书链和名称校验仍由 crypto/tls 负责。

package main

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

func dialService() (*tls.Conn, error) {
    // 拨号地址只负责找到网络端点，不代表证书要匹配的名称。
    dialer := &net.Dialer{Timeout: 5 * time.Second}
    config := &tls.Config{
        // 这里填写证书 SAN 中的 DNS 名称，同时作为非 IP 场景的 SNI。
        ServerName: "api.example.com",
        MinVersion: tls.VersionTLS12,
    }

    // 内网固定 IP 与证书名称分离，仍保留默认证书链和主机名校验。
    conn, err := tls.DialWithDialer(dialer, "tcp", "10.0.0.8:443", config)
    if err != nil {
        return nil, fmt.Errorf("TLS 握手失败: %w", err)
    }
    return conn, nil
}

func useConnection() error {
    conn, err := dialService()
    if err != nil {
        return err
    }
    // TLS 连接不用时要关闭，避免连接和握手资源泄漏。
    defer conn.Close()
    return nil
}

如果服务端是多租户入口，ServerName 还会影响服务端选择哪张证书。若只把它写成负载均衡器 IP，即使网络可达，也可能拿到不属于目标服务的证书。

回归检查：先区分证书链错误，再定位名称错误

迁移后可以按下面的顺序整理日志，但不要把它当成跳过安全校验的理由：

1. 如果报未知颁发者、证书过期或链不完整，先处理根证书池、服务器链和有效期。
2. 如果是主机名不匹配，记录实际 ServerName，再对照叶子证书的 DNSNames 与 IPAddresses。
3. 通配符通常只覆盖完整的最左侧标签，例如 *.example.com 不等于任意多级子域。
4. 需要单独解释证书时，可对解析出的叶子证书调用 VerifyHostname；它返回错误就说明名称边界仍不成立。

func explainName(cert *x509.Certificate, expected string) error {
    // 这个检查用于诊断证书名称，不替代正式的证书链验证。
    if err := cert.VerifyHostname(expected); err != nil {
        return fmt.Errorf("证书不匹配 %q: %w", expected, err)
    }
    return nil
}

上面的诊断函数需要补充 crypto/x509 和 fmt 导入；生产连接仍优先使用 tls.Config 的默认验证路径。这样日志能告诉你究竟是信任链问题，还是服务名与证书 SAN 的问题。

Go TLS 主机名匹配常见问题

ServerName 应该写拨号地址还是证书域名？

写证书要证明的服务名。拨号地址可以是 IP、域名或代理端点；当两者不同，分别配置，不要把代理地址冒充业务证书名称。

证书只有 Common Name，为什么仍然匹配失败？

现代 Go 的主机名匹配看 SAN 中的 DNS 名称或 IP 地址，传统 Common Name 不再作为主机名匹配依据。应重新签发包含正确 SAN 的证书。

能不能把 InsecureSkipVerify 设为 true？

它会跳过默认证书链和主机名校验，容易把真正的配置错误变成不安全连接。除非你同时实现并审查了完整的自定义验证，否则不要用它解决名称不匹配。

迁移 Go TLS 连接时，最稳妥的清单是：确认拨号端点、确认证书 SAN、显式设置正确的 ServerName、保留默认校验，并把链错误和名称错误分别记录。名称匹配问题通常不需要关闭 TLS 安全性，只需要把网络定位与身份证明重新对齐。