证书有效但 Go 客户端仍提示主机名不匹配，应该检查什么

证书“有效”与证书“适用于当前主机名”是两项检查。证书可以仍在有效期内、签发链也可信，但只要 Go 客户端实际校验的名称没有出现在叶子证书对应的 Subject Alternative Name（SAN）里，TLS 握手仍会报主机名不匹配。排查时先确认被校验的名称，再检查 DNS SAN、IP SAN、通配符边界以及 SNI 让服务端返回了哪一张证书。

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

Go X.509 官方文档：https://pkg.go.dev/crypto/x509

趋势信号：SAN 已经是 Go 主机身份校验的明确边界

证书本身有效期、根链没问题的情况下还抛出主机名不匹配报错，绝大多数情况是Go客户端的证书校验逻辑和你预期的浏览器/ curl 校验规则不一样，顺着上面列的六项逐项排查，基本就能定位问题。

Go 1.15 起，证书只有 Common Name、没有 SAN 时，不再默认把 Common Name 当作主机名。当前 crypto/x509 文档也明确说明，Certificate.VerifyHostname 会忽略旧式 Common Name。这个变化把“链可信”和“服务身份正确”分得更清楚：CA 信任解决谁签发了证书，SAN 解决这张证书代表哪些 DNS 名或 IP。

常见错误可以先按文字分组：

给 RootCAs 增加一个根证书只能解决信任链，不能让不匹配的 SAN 变成匹配。反过来，SAN 匹配也不代表证书链一定可信，两项都必须通过。

解决的问题一：Go 到底在校验哪个名称

tls.Config.ServerName 是关键字段。官方文档说明，它用于校验服务端证书中的主机名；当值不是 IP 时，也会放进客户端握手作为 SNI，帮助虚拟主机选择证书。使用 net/http 时，如果没有显式设置 ServerName，Transport 通常按请求 URL 的主机部分建立 TLS；一旦显式填写 ServerName，它就代表你真正声明的服务身份。

典型场景是：应用访问 https://api.internal.example/，但自定义拨号把 TCP 连接定向到 10.0.0.8:443。正确身份仍是 api.internal.example；IP 只是路由目标。若把请求 URL 直接改为 IP，即使再设置 HTTP Host 头，TLS 仍会在 Host 头发送前按 IP 做验证。

解决的问题二：DNS SAN、IP SAN 和通配符不是一回事

VerifyHostname 会先判断输入是否为 IP。若是 IP，就检查证书的 IPAddresses；其他名称则不区分大小写地检查 DNSNames。把 10.0.0.8 字符串写进 DNS SAN，不能替代真正的 IP SAN。

通配符也有明确边界：它只能作为完整的最左侧标签。例如 *.example.com 可以匹配 api.example.com，但不匹配根域 example.com，也不匹配多一层的 v1.api.example.com。若服务同时被多个名称访问，签发时应把每个需要支持的 DNS 名或 IP 放进对应 SAN，而不是依赖模糊的 Common Name。

受益角色：网关、服务网格和内网直连尤其容易踩坑

单一域名直连时，URL、DNS 解析、SNI 与证书 SAN 通常天然一致。引入反向代理、云负载均衡、服务网格、固定 IP 灰度或自定义 DialContext 后，“连到哪里”和“服务器是谁”会被拆开。这正是显式梳理 ServerName 最有价值的场景。

• 应用开发者：检查 URL 与自定义 Transport 是否覆盖了 ServerName。
• 平台工程师：检查网关监听器按哪个 SNI 选证书，默认证书是否意外返回。
• 证书管理员：确认证书模板生成的是 DNS SAN 或 IP SAN，而不只是 CN。
• 运维人员：确认代理终止 TLS 的位置，以及后端 TLS 是否使用另一套服务名。

风险：不要用 InsecureSkipVerify 掩盖身份错误

InsecureSkipVerify=true 会让客户端跳过证书链与主机名的默认验证。官方文档明确警告，若没有配套自定义验证，这种模式容易遭受中间人攻击。它不应成为“证书看起来有效但名称不匹配”的生产修复。

如果确实要定制验证，应明确建立根证书池、验证中间证书、设置正确的 DNSName，并处理证书轮换。大多数业务客户端没有必要替换标准校验，只需让 URL、ServerName 和 SAN 对齐。

采用路径一：用诊断程序看清对端证书

下面的小程序只用于受控排障：它临时跳过默认验证以便读取服务端实际返回的叶子证书，然后立即调用 VerifyHostname 对期望名称做显式检查。它不会证明证书链可信，也不应复制到正式 HTTP 客户端。

package main

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

func main() {
	if len(os.Args) != 3 {
		// endpoint 是实际拨号地址，expectedName 是期望服务身份
		fmt.Fprintln(os.Stderr, "用法: go run tls_probe.go host:443 expected.example.com")
		os.Exit(2)
	}

	endpoint := os.Args[1]
	expectedName := os.Args[2]
	dialer := &net.Dialer{Timeout: 5 * time.Second}

	conn, err := tls.DialWithDialer(dialer, "tcp", endpoint, &tls.Config{
		// 仅为读取不匹配证书；随后显式执行 VerifyHostname
		InsecureSkipVerify: true,
		// 发送期望域名作为 SNI，观察虚拟主机实际选中的证书
		ServerName: expectedName,
		MinVersion: tls.VersionTLS12,
	})
	if err != nil {
		fmt.Fprintln(os.Stderr, "TLS 连接失败:", err)
		os.Exit(1)
	}
	defer conn.Close()

	state := conn.ConnectionState()
	if len(state.PeerCertificates) == 0 {
		fmt.Fprintln(os.Stderr, "服务端没有返回证书")
		os.Exit(1)
	}

	leaf := state.PeerCertificates[0]
	// 打印 SAN，避免只盯着已被忽略的 Common Name
	fmt.Println("DNS SAN:", leaf.DNSNames)
	fmt.Println("IP SAN:", leaf.IPAddresses)
	fmt.Println("Common Name:", leaf.Subject.CommonName)

	// 只验证名称匹配；完整信任链仍应由标准 TLS 客户端验证
	if err := leaf.VerifyHostname(expectedName); err != nil {
		fmt.Fprintln(os.Stderr, "主机名不匹配:", err)
		os.Exit(1)
	}
	fmt.Println("主机名匹配")
}

# 第一个参数是实际拨号端点，第二个参数是期望证书身份
go run tls_probe.go 10.0.0.8:443 api.internal.example

若换不同的 expectedName 后返回的 DNS SAN 也发生变化，通常说明前置代理在按 SNI 选择不同证书。若无论发送什么 SNI 都返回同一张不相关证书，应检查代理监听器、证书绑定和默认虚拟主机。

采用路径二：固定 IP 拨号时保留正确服务名

若业务必须绕过 DNS 连接固定 IP，不要把 HTTPS URL 改成 IP。保留域名 URL，并在 DialContext 中只替换网络目的地。下面示例克隆默认 Transport，既保留常用默认值，也明确设置 ServerName。

package main

import (
	"context"
	"fmt"
	"io"
	"net"
	"net/http"
	"time"
)

func main() {
	const serviceName = "api.internal.example"
	const fixedEndpoint = "10.0.0.8:443"

	transport := http.DefaultTransport.(*http.Transport).Clone()
	transport.TLSClientConfig.ServerName = serviceName
	transport.DialContext = func(ctx context.Context, network, address string) (net.Conn, error) {
		// 只允许目标服务走固定 IP，避免意外重定向其他请求
		if address != serviceName+":443" {
			return nil, fmt.Errorf("拒绝未预期的拨号目标: %s", address)
		}
		dialer := &net.Dialer{Timeout: 5 * time.Second}
		return dialer.DialContext(ctx, network, fixedEndpoint)
	}

	client := &http.Client{
		Transport: transport,
		Timeout:   10 * time.Second,
	}
	resp, err := client.Get("https://" + serviceName + "/health")
	if err != nil {
		fmt.Println("请求失败:", err)
		return
	}
	defer resp.Body.Close()

	// 限制读取量，排障示例不无限读取响应体
	body, err := io.ReadAll(io.LimitReader(resp.Body, 4096))
	if err != nil {
		fmt.Println("读取响应失败:", err)
		return
	}
	fmt.Println(resp.Status, string(body))
}

这里 TCP 连接到 10.0.0.8，但 TLS SNI 与证书校验仍使用 api.internal.example。服务端证书必须包含这个 DNS SAN，代理也必须为这个 SNI 返回正确证书。

采用路径三：能改证书时直接补齐 SAN

如果客户端确实需要按 IP 访问，就重新签发包含该 IP 的 IP SAN；如果客户端按域名访问，就签发对应 DNS SAN。证书轮换时同时检查旧客户端仍使用哪些入口，避免只给新域名补 SAN，却漏掉内部别名、健康检查域名或灾备入口。

私有 CA 场景还要把根证书加入客户端 RootCAs，并确保服务端发送必要的中间证书。但这些信任链工作与 SAN 匹配是并列关系，不能互相替代。

观察指标：修复后如何确认不会再次发生

• 按错误类型统计 x509.HostnameError、UnknownAuthorityError 和超时，不把所有 TLS 错误合并。
• 记录目标服务名和代理层级，但不要在日志中输出私钥、完整证书或敏感请求头。
• 证书轮换前对每个公开域名、内部别名和固定 IP 用例做测试。
• 网关变更后验证每个 SNI 返回的叶子证书 SAN，而不只检查默认证书。
• 若使用连接池，确认轮换后新连接拿到新证书，旧连接的生命周期符合预期。

常见问题

证书没有过期，为什么还会失败？

有效期只回答“现在是否处于可用时间段”，不回答“是否代表当前主机名”。Go 还会检查信任链、用途和 SAN。

设置 HTTP Host 头能修复证书不匹配吗？

不能。TLS 握手先发生，HTTP Host 头后发送。应修正 URL、ServerName、SNI 或证书 SAN。

把域名写入 Common Name 还够用吗？

不够。当前 Go 的 VerifyHostname 忽略 Common Name，应该签发带 DNS SAN 或 IP SAN 的证书。

自签证书为什么添加 RootCAs 后仍报主机名不匹配？

RootCAs 只建立信任。叶子证书还必须在正确类型的 SAN 中覆盖客户端校验的名称。

什么时候可以设置 InsecureSkipVerify？

仅限受控测试或与完整自定义验证结合的高级场景。普通生产客户端不应靠它绕过名称错误。

主机名不匹配的根因通常不是“证书坏了”，而是连接地址、期望身份、SNI 和证书 SAN 没有对齐。把这四个对象分别写出来，再按错误类型检查，定位会比反复导入根证书或关闭验证更快、更安全。