Go crypto/tls区分系统根证书与自定义池的排查方法

排查 Go HTTPS 证书问题时，最容易混淆的是“系统根证书”和“自定义证书池”这两个概念。真正可靠的判断入口不是看报错里有没有 x509，也不是数 CertPool 里有多少证书，而是先看构造 tls.Config 时是否把 RootCAs 留为空，再记录这个配置的来源。

RootCAs 的三种来源要先在配置阶段分开

客户端配置可以按下面三类理解：字段为 nil 时交给 TLS 使用主机根证书；x509.NewCertPool() 创建的是空池，随后只追加指定 PEM 时就是纯自定义池；x509.SystemCertPool() 得到的是系统池副本，继续 AppendCertsFromPEM 则是系统信任加应用证书。

func buildTLSConfig(pemBytes []byte) (*tls.Config, string, error) {
	// nil 保留默认系统根证书；不要用空 CertPool 冒充默认值。
	if len(pemBytes) == 0 {
		return &tls.Config{MinVersion: tls.VersionTLS12}, "host-default", nil
	}

	// 这里明确选择“系统池副本 + 自定义根证书”，便于记录来源。
	pool, err := x509.SystemCertPool()
	if err != nil {
		return nil, "", fmt.Errorf("读取系统根证书失败: %w", err)
	}
	if ok := pool.AppendCertsFromPEM(pemBytes); !ok {
		return nil, "", errors.New("自定义 PEM 中没有可用证书")
	}
	return &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12}, "system-plus-custom", nil
}

工程上建议让构造函数同时返回来源标签，或者把标签放在自有配置结构体里。这样日志可以直接写出 host-default、custom-only、system-plus-custom，而不必事后猜一个已经封装好的 *x509.CertPool。

不要用 Subjects() 反推 CertPool 的真实来源

CertPool 的内部字段没有公开来源标记。尤其要注意，官方文档已经把 Subjects() 标为过时接口；如果池来自 SystemCertPool()，它不会把系统根证书完整列出来。于是“Subjects 为空”既可能是空的自定义池，也可能是系统池副本的表现，不能据此下结论。

如果只是比较两个已经保存的池，可以使用 Go 1.19 引入的 Equal。不过它回答的是“内容和系统池属性是否相等”，不是“这个池在业务上为什么被创建”。应用环境变化、追加证书或不同平台的系统验证器都会让事后比较变得脆弱。更稳妥的方式仍然是保留来源元数据；需要自定义池时也不要把系统池误写成匿名全局变量。

握手后只把 VerifiedChains 当作证据的一部分

连接成功后，ConnectionState.VerifiedChains 能告诉你实际验证链，客户端场景下链尾通常是信任锚；PeerCertificates 则是对端发送的证书列表。它们适合确认“这次握手最后落到了哪个根证书”，但无法单独证明应用是否使用了默认系统池，因为自定义池也可能包含相同根证书。

func logTLSRoot(conn *tls.Conn, source string) error {
	// ConnectionState 只读取握手结果，不修改连接或证书链。
	state := conn.ConnectionState()
	if len(state.VerifiedChains) == 0 {
		return errors.New("没有可记录的验证链")
	}
	chain := state.VerifiedChains[0]
	root := chain[len(chain)-1]
	log.Printf("tls source=%s server=%s root_subject=%s root_serial=%s",
		source, state.ServerName, root.Subject.String(), root.SerialNumber.String())
	return nil
}

若要把记录放进握手阶段，可使用 VerifyConnection，但不要在里面把 InsecureSkipVerify 当作排查捷径。官方说明中，正常验证失败时该回调不会替你挽回握手；生产配置应保持正常校验，并只读取状态或返回明确错误。

四项检查可以快速收敛误判

最后再核对 ServerName、PEM 加载返回值和实际错误类型。证书链不信任、主机名不匹配、系统池不可用，修复方向并不相同。特别是在 macOS、Windows 与 Linux 之间迁移时，系统证书来源和平台验证器行为可能不同，日志里应同时保存平台、来源标签和链尾证书摘要。

相关问题

RootCAs 设置为空指针和空 CertPool 一样吗？

不一样。空指针走主机根证书；空 CertPool 没有任何信任锚，通常会导致公开站点也无法完成验证。

系统池追加自签名根证书后还能称为系统池吗？

可以在业务命名上称为“系统池加自定义”，但它已经是应用显式传入的非 nil 池，应把追加动作和来源标签记录下来。

怎样确认是主机名问题而不是根证书问题？

先看验证错误类型和目标 ServerName，再看 VerifiedChains 是否存在；不要只根据“证书错误”四个字判断。