Go tls.Config.GetCertificate 为什么没有按 SNI 返回证书

Go TLS 服务端没有按 SNI 返回证书时，先看 GetCertificate 回调收到的 ClientHelloInfo.ServerName，再看证书索引是否按规范化主机名匹配。SNI 没有发送、名称没有命中、回调返回了错误，和回调根本没有被调用，是四个不同问题。不要为了“让连接先成功”而关闭证书校验；应把匹配和回退规则写清楚。

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

最稳妥的排查顺序是：记录收到的 ServerName，确认它是否命中精确或通配符索引，再检查 GetCertificate 的返回值和默认证书策略。ServerName 为空时，不能凭空推断客户端想访问哪个域名。

先判断是哪一种“不按 SNI 返回”

服务端配置 GetCertificate 后，现象相同但原因可能完全不同。客户端使用 IP 地址连接、没有发送 SNI 时，回调中的 ServerName 可能为空；客户端发送了域名但索引没有匹配，通常是主机名规范化或通配符规则有问题；如果回调返回错误，握手会在证书选择阶段失败。还有一种常见情况是 Certificates 已经提供了可用证书，导致回调只在特定条件下被调用。

读取 ServerName，而不是从连接地址猜域名

ClientHelloInfo.ServerName 表示客户端在握手中提供的 SNI 名称。它不是服务端监听地址，也不是从 TCP 对端地址反推出来的主机名。多域名服务应以这个字段作为证书选择输入；如果它为空，就进入明确的默认站点策略或返回可诊断错误。

记录诊断信息时可以保留 ServerName、是否命中索引、选择了哪个站点配置以及证书加载错误类型。不要把完整证书内容写入普通日志，也不要把客户端地址当作证书域名。

让证书索引和匹配规则保持单一

证书通常在服务启动时加载，再按服务域名建立索引。索引键应采用同一套规则：去掉尾部点、统一大小写、拒绝带端口的输入，并把通配符匹配限制在一个左侧标签。这样可以避免配置文件使用 Example.COM.，而回调收到 example.com 时出现不必要的未命中。

匹配顺序建议固定为“精确名称、允许的通配符、显式默认站点”。通配符不能被当作任意多级域名；例如 *.example.com 不应自动覆盖 a.b.example.com。未命中时应记录诊断信息，是否回退到默认证书要由产品策略决定。

package main

import (
    "strings"
)

// normalizeServerName 只处理证书索引需要的主机名格式，不猜测客户端意图。
func normalizeServerName(name string) string {
    // ServerName 是主机名，不应把端口混进证书索引键。
    name = strings.TrimSpace(strings.TrimSuffix(name, "."))
    return strings.ToLower(name)
}

// matchCertificateKey 先精确匹配，再允许单级通配符匹配。
func matchCertificateKey(index map[string]string, serverName string) (string, bool) {
    host := normalizeServerName(serverName)
    if host == "" {
        return "", false // 没有 SNI 时交给默认站点策略
    }
    if certID, ok := index[host]; ok {
        return certID, true
    }
    labels := strings.Split(host, ".")
    if len(labels) 

理解 Certificates、GetCertificate 和 GetConfigForClient

服务端至少要有一条清晰的证书来源：直接配置 Certificates，或者配置 GetCertificate 动态返回证书，也可以使用 GetConfigForClient 为不同客户端问候选择配置。三者职责不同，不要同时写出互相矛盾的回退逻辑。

• Certificates 适合证书集合由 TLS 包自动选择的场景。
• GetCertificate 适合根据 ClientHelloInfo 自己决定返回哪条证书链。
• GetConfigForClient 返回非 nil 配置时，会改变这次连接后续使用的配置；它不是简单的域名到证书 map。

官方文档说明，GetCertificate 只有在客户端提供 SNI，或 Certificates 为空等条件下才会被调用。因而“我写了回调但没有打印日志”并不等于 SNI 被忽略，先确认是否存在可供默认选择的证书。

处理默认站点和错误回退

没有 SNI 或没有匹配项时，常见策略有两种：返回显式配置的默认站点证书，或者返回错误让握手失败。前者适合确实存在公共默认域名的服务；后者适合租户之间必须严格隔离的服务。无论选择哪种策略，都要在日志中区分“无 SNI”和“有 SNI 但未命中”。

如果返回默认证书，客户端随后仍可能因为主机名与证书不匹配而拒绝连接。这个结果是正确的安全反馈，不能通过 InsecureSkipVerify 之类设置掩盖。服务端证书选择成功和客户端证书校验成功是两个阶段。

用错误链保留证书加载原因

动态选择前，证书和私钥应尽量在启动阶段加载并校验。加载失败时保留原始错误，区分文件读取失败、证书解析失败和证书私钥不匹配。运行中热更新时，也要先构造完整的新证书对象，再用并发安全的方式替换索引，避免回调拿到半初始化状态。

type certificateStore struct {
    byName  map[string]tls.Certificate
    defaultCert *tls.Certificate
}

// certificateFor 根据 SNI 选择完整证书链；找不到时返回默认策略的结果。
func (s *certificateStore) certificateFor(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
    // nil 或空 ServerName 都表示不能从 SNI 选择具体站点。
    if hello == nil || normalizeServerName(hello.ServerName) == "" {
        if s.defaultCert == nil {
            return nil, fmt.Errorf("没有 SNI 且未配置默认证书")
        }
        return s.defaultCert, nil
    }
    key, ok := matchCertificateKey(s.keyIndex(), hello.ServerName)
    if !ok {
        return nil, fmt.Errorf("SNI %q 没有匹配证书", hello.ServerName)
    }
    cert, ok := s.byName[key]
    if !ok {
        return nil, fmt.Errorf("证书索引 %q 没有完成加载", key)
    }
    return &cert, nil
}

上面片段展示的是选择逻辑，完整程序还需要导入 crypto/tls 和 fmt，并实现 keyIndex 返回与加载阶段一致的索引。关键点是：回调返回错误就让调用方看到握手失败原因，不要把错误吞掉后随意返回一条不相关证书。

一个可复用的最小服务端配置

下面的配置把动态选择接到 tls.Config，并把默认证书作为显式策略。示例中的证书加载函数由业务代码提供；文章只展示配置边界，未在读者环境运行。

package main

import (
    "crypto/tls"
    "fmt"
)

// buildTLSConfig 只负责把已经加载好的证书索引接入 TLS 回调。
func buildTLSConfig(store *certificateStore) *tls.Config {
    return &tls.Config{
        MinVersion: tls.VersionTLS12, // 明确最低协议版本，按部署策略调整
        GetCertificate: func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
            // 保留选择错误，让握手和上层日志能够定位真实原因。
            cert, err := store.certificateFor(hello)
            if err != nil {
                return nil, fmt.Errorf("按 SNI 选择证书失败: %w", err)
            }
            return cert, nil
        },
    }
}

如果服务必须接受没有 SNI 的旧客户端，可以把默认证书策略写在 certificateFor 中；如果所有租户都必须带 SNI，则应明确拒绝空值。不要把两种策略隐藏在“找不到就取 map 第一项”的实现里，因为 map 的迭代顺序不是稳定的默认选择。

排查清单

1. 在回调入口记录脱敏后的 ServerName 和是否为空。
2. 用同一规范化函数处理配置域名与回调输入。
3. 确认客户端连接使用域名而不是 IP，且握手确实携带 SNI。
4. 检查精确匹配、单级通配符和默认站点的优先级。
5. 确认返回的证书链和私钥已经完整加载，错误没有被吞掉。
6. 区分服务端选证书失败与客户端验证失败，不用关闭校验绕过问题。

常见问题

为什么用 IP 访问时 ServerName 为空？

SNI 面向主机名虚拟托管。客户端如果使用 IP 连接，或没有发送 SNI，服务端就没有可用于域名索引的名称，应进入默认站点或拒绝策略。

GetCertificate 返回 nil 会怎样？

返回 nil 且没有可用的其他证书来源时，握手无法完成。不要把 nil 当成“让 TLS 自动选择任意证书”的可靠写法。

为什么配置了 Certificates 后回调没有触发？

Go TLS 会根据证书来源和客户端问候选择回退路径。官方文档明确说明，GetCertificate 并不是每次握手都无条件调用；需要检查 Certificates 是否已经提供可选证书，以及客户端是否发送 SNI。

默认证书能解决所有 SNI 问题吗？

不能。默认证书只能覆盖空 SNI 或明确允许回退的场景；如果客户端访问域名不在证书的 SAN 中，后续主机名校验仍会失败。

排查的核心不是让任意证书“先返回”，而是让 SNI 输入、证书索引、回退策略和错误日志一一对应。这样才能知道问题发生在客户端问候、服务端匹配、证书加载还是后续验证。