Go TLS证书验证失败时先区分主机名与信任链

Go 的 TLS 证书报错，最容易误判成“证书过期”或“服务端证书坏了”。实际排查应先看错误属于哪一层：如果出现 certificate is valid for ..., not ...，优先检查主机名；如果出现 x509: certificate signed by unknown authority，优先检查信任根和中间证书。两类问题的修复位置完全不同。

官方资料：https://pkg.go.dev/crypto/tls　x509资料：https://pkg.go.dev/crypto/x509

先不要把 InsecureSkipVerify 改成 true。它会同时跳过服务端证书链和主机名校验，只能作为隔离环境中的临时诊断，不是生产修复。

先从错误文本判断是哪条路径

主机名错误的关键证据是错误里同时出现“证书允许的名字”和“当前请求的名字”。这通常来自 tls.Config.ServerName，客户端会把它用于主机名验证，也会在不是 IP 地址时参与 SNI。信任链错误则更常见于私有 CA、精简容器镜像、服务器漏发中间证书或手动覆盖了错误的 RootCAs。

主机名不匹配时检查 ServerName

先记录三件事：连接使用的目标地址、ServerName 的值、证书 SAN 中的 DNS 名称。通过 IP 访问时，证书需要包含对应 IP；不能因为 DNS 名称证书看起来“属于同一台服务器”就认为验证会通过。代理、负载均衡和多域名入口还要特别确认 SNI 没有被错误覆盖。

package main

import (
	"crypto/tls"
	"fmt"
)

func main() {
	// ServerName 既用于主机名校验，也帮助服务端选择正确的证书。
	config := &tls.Config{ServerName: "api.example.com"}
	conn, err := tls.Dial("tcp", "10.0.0.8:443", config)
	if err != nil {
		// 这里保留原始错误，便于区分 hostname mismatch 与 unknown authority。
		fmt.Println("TLS 连接失败:", err)
		return
	}
	defer conn.Close() // 诊断成功后也要释放连接。
	fmt.Println("协商成功:", conn.ConnectionState().ServerName)
}

这段代码的重点不是把地址改成域名，而是明确“TCP 连接地址”和“证书校验名称”可以不同。修复时应让 ServerName 对应证书 SAN 中的名称，并保留正常校验。

信任链失败时检查 RootCAs 和 intermediates

如果错误是 unknown authority，先确认运行环境是否有系统根证书。企业内网常用私有 CA，此时可以创建证书池并通过 RootCAs 指定它；如果服务端没有发送中间证书，客户端即使信任根 CA，也可能无法拼出完整链，应该修复服务端证书链配置。

package main

import (
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"os"
)

func clientConfig(caPEM []byte) (*tls.Config, error) {
	// 先复制系统根证书，再追加组织自己的 CA，避免覆盖公共信任集合。
	roots, err := x509.SystemCertPool()
	if err != nil || roots == nil {
		roots = x509.NewCertPool()
	}
	if ok := roots.AppendCertsFromPEM(caPEM); !ok {
		return nil, fmt.Errorf("无法加入私有 CA")
	}
	return &tls.Config{RootCAs: roots, MinVersion: tls.VersionTLS12}, nil
}

func loadCA(path string) ([]byte, error) {
	// 只读取明确配置的 CA 文件，不在代码中硬编码证书内容。
	return os.ReadFile(path)
}

RootCAs 非空后，Go 不会自动替你补回未加入的系统根，因此“覆盖系统池”和“追加私有 CA”是两个不同动作。容器内若没有根证书包，也要把部署依赖补齐。

用 x509.Verify 把猜测变成证据

网络握手日志不够清楚时，可以把叶子证书解析出来，用 x509.VerifyOptions 分别设置 DNSName、Roots 和 Intermediates。设置 DNSName 后失败，说明名称或证书用途仍不匹配；不设置自定义 Roots 时失败，则优先回到系统信任材料和链路完整性检查。

opts := x509.VerifyOptions{
	DNSName:       "api.example.com", // 检查证书是否覆盖目标主机名。
	Roots:         roots,              // 指定允许的信任根。
	Intermediates: intermediates,      // 提供服务端未能自动拼接的中间证书。
}
if _, err := leaf.Verify(opts); err != nil {
	// 原始错误比自定义“证书错误”更能指导下一步排查。
	fmt.Println("链路验证失败:", err)
}

这个判断仍不等于完整的线上验收：证书吊销、代理改写、时间偏差和服务端实际发送链还需要在部署环境复查，但它能先把最常见的两类错误分开。

修复后的回归清单

• 主机名问题：核对 SAN、ServerName、SNI 和访问入口是否一致。
• 信任链问题：核对系统根、私有 CA、intermediates，以及服务器是否发送完整链。
• 配置边界：不要把 RootCAs 误写成只含一张无关证书的池，也不要用 InsecureSkipVerify 绕过验证。
• 验证结果：保留原始 x509 错误和环境信息，确认修复只影响目标入口。

相关问题

为什么加了私有根证书仍然失败？ 常见原因是中间证书未发送、叶子证书的 SAN 不含目标名称，或代码重新创建了一个覆盖系统根的证书池。

可以只关闭主机名校验吗？ 不建议在生产环境这样做。即使链路可信，跳过主机名校验仍可能把连接导向错误的服务；应修正入口名称和证书 SAN。