Go tls.Config按域名选择证书的动态配置方法

多域名 TLS 服务最容易踩的坑，不是证书文件怎么读，而是“这次握手到底应该返回哪一张证书”。在 Go 中，可以把选择逻辑放进 tls.Config.GetCertificate，从 ClientHelloInfo.ServerName 读取客户端通过 SNI 发送的域名，再返回对应的 tls.Certificate。

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

先确定域名、证书和回退证书的数据边界

我更建议先定义“选择器”，再把它挂到监听器上。选择器至少要区分精确主机名、通配符主机名和默认证书：api.example.com 不能因为存在 *.example.com 就失去优先级；没有 SNI 时也不能悄悄拿一张不适用的证书冒充成功。

证书对象在返回后不应继续修改。加载阶段完成 PEM 解析和证书链组装，读取阶段只做查表。这样，握手回调的职责很窄：读取域名、选择快照、返回证书。

用 GetCertificate 读取 ClientHelloInfo

GetCertificate 的参数就是当前握手的 ClientHelloInfo。其中 ServerName 只有客户端发送 SNI 时才有值；回调不应该读取或写入 ClientHelloInfo.Conn，否则可能破坏握手。下面的示例用一个只读快照表达核心选择逻辑，证书加载错误则在启动阶段直接返回。

type certStore struct {
	// exact 保存完整主机名，默认证书处理无 SNI 或未知域名。
	exact   map[string]*tls.Certificate
	defaultCert *tls.Certificate
}

func (s *certStore) get(chi *tls.ClientHelloInfo) (*tls.Certificate, error) {
	host := strings.ToLower(strings.TrimSuffix(chi.ServerName, "."))
	// 精确匹配优先，避免 api.example.com 被通配符规则抢走。
	if cert := s.exact[host]; cert != nil {
		return cert, nil
	}
	// 生产环境可在这里接入受控的通配符匹配器。
	if strings.HasSuffix(host, ".example.com") && s.exact["*.example.com"] != nil {
		return s.exact["*.example.com"], nil
	}
	if s.defaultCert == nil {
		return nil, fmt.Errorf("no certificate for SNI %q", chi.ServerName)
	}
	return s.defaultCert, nil
}

cfg := &tls.Config{
	// 回调只读当前快照，不在握手期间加载或改写证书。
	GetCertificate: store.get,
}

示例里的通配符判断只服务于说明；真正上线时要明确通配符覆盖的标签层级，并让证书 SAN、私钥和中间证书链在加载阶段成套校验。

把热更新放在握手回调之外

证书轮换时不要在 GetCertificate 内部读文件、解析 PEM 或修改 map。更稳妥的做法是后台构建一份完整的新 certStore，然后用 atomic.Value 发布快照；每次握手只加载一次当前快照，读者之间不共享可变 map。

type storeHolder struct {
	current atomic.Value // 保存 *certStore，整体替换而不是修改内部 map
}

func (h *storeHolder) get(chi *tls.ClientHelloInfo) (*tls.Certificate, error) {
	store := h.current.Load().(*certStore)
	// certStore 在发布后视为不可变，多个握手可并发读取。
	return store.get(chi)
}

func (h *storeHolder) replace(next *certStore) {
	// 新快照应先完成所有证书和私钥校验，再一次性对外可见。
	h.current.Store(next)
}

cfg := &tls.Config{GetCertificate: holder.get}

这里的关键不是 atomic.Value 本身，而是“不可变快照”约定：旧快照交给正在进行的握手继续使用，新快照只影响后续读取。若证书加载失败，保留旧快照通常比发布半成品更安全。

按 SNI 和回退边界排查证书不匹配

遇到浏览器提示域名不匹配时，先记录选择器看到的 ServerName、命中的规则和证书主题，不要先改 TLS 版本。没有 SNI 往往意味着客户端或上游代理没有带域名；有 SNI 但命中默认证书，则应检查主机名规范化、通配符层级和快照是否已经替换。

• 回调没有被调用：检查客户端是否发送 SNI，以及 Certificates 是否让库直接完成了选择。
• 返回后握手失败：核对证书链顺序、私钥匹配和客户端支持的签名算法。
• 热更新偶发错证书：检查是否仍在原地修改 map，或是否把半成品快照提前发布。

相关问题

GetCertificate 和 GetConfigForClient 应该怎么选？

只需要按 SNI 选择证书时，优先使用 GetCertificate；如果不同域名还需要切换整套 TLS 配置，再考虑 GetConfigForClient。

没有 SNI 时一定要返回默认证书吗？

不一定。公共入口可以返回明确的默认站点证书，严格租户入口则可以返回错误，让调用方修正 SNI，而不是掩盖路由问题。

为什么不在回调里直接读取证书文件？

文件读取和 PEM 解析会把磁盘抖动带进握手延迟，还会让并发请求共享复杂的可变状态；把它们放在快照构建阶段更容易回滚和观测。