跳到主要内容
基础知识

通配符证书 troubleshooting:子域不生效、多节点证书不一致的 7 步排查与验证(2025)

通配符证书 troubleshooting — 通配符证书 troubleshooting:子域不生效、多节点证书不一致的 7 步排查与验证(2025)
核心结论

通配符证书 troubleshooting 的第一步永远是确认覆盖层级:*.example.com 只匹配一级子域(a.example.com),既不匹配 a.b.example.com,也不匹配裸域 example.com,这是 RFC 6125 §6.4.3 与 CA/B Forum BR 的硬规则。 多节点场景用 openssl s_client -connect :443 -servername api.example.com -showcerts 逐台比对序列号(openssl x509 -noout -serial),序列号不一致即说明该节点仍持有旧证书或 default_server 自签证书。 证书链缺失只在特定客户端暴露:浏览器靠 AIA 补链能过,Android 7 以下与 Java keystore 直接报 unable to verify the first certificate,需在 Nginx 配 ssl_trusted_certificate 或直接下发 fullchain。 复签时用 openssl req -new -addext 'subjectAltName=DNS:*.example.com,DNS:example.com' 一次性写全,cert-manager 1.14 则在 Certificate 资源的 dnsNames 里同时列裸域与通配符,避免“签出来却对不上”。 换证后至少观察 30 分钟:keep-alive 长连接与浏览器会话缓存会继续复用旧证书,验证要覆盖 openssl s_client、curl -vI、testssl.sh 3.2 三个层次。

通配符证书 troubleshooting 先查什么?6 类根本原因与覆盖规则

先给结论:在真实工单里,“通配符不生效”绝大多数不是签发失败,而是主机名覆盖规则、节点副本、SNI 回落这三类问题。拿到一台可疑主机,先用一条命令把“证书长什么样、链全不全、主机名匹配不匹配”一次性打出来,再决定往哪个方向查。

# 适用 OpenSSL 1.1.1 / 3.x;-verify_hostname 需要 OpenSSL >= 1.1.0
# 同时输出主体、签发者、UTC 有效期、SAN 扩展,并显式按目标主机名校验
openssl s_client -connect a.b.example.com:443 -servername a.b.example.com 
  -verify_hostname a.b.example.com -verify_return_error </dev/null 2>&1 
  | grep -E 'verify error|subject=|issuer=|notBefore|notAfter|DNS:'
# 典型输出:verify error:num=62:hostname mismatch  ← 覆盖层级问题(X509_V_ERR_HOSTNAME_MISMATCH)
# 典型输出:verify error:num=20:unable to get local issuer certificate ← 缺中间证书
根本原因 典型症状 快速定位
通配符覆盖层级不对 a.b.example.com 或裸域报 mismatch -verify_hostname 返回 num=62
多节点证书副本不一致 时好时坏,换网络就恢复 逐 IP 抓 -serial 比对
SNI 未命中回落默认站点 老客户端/探针报错,浏览器正常 -noservername 抓 subject
证书链不完整 Android 7 以下、Java、IoT 报错 grep -c 'BEGIN CERTIFICATE'
时间与缓存错位 “证书尚未生效”、换证后仍旧 date -u 对照 -dates
CSR/SAN 输入错误 签发成功但主机名不匹配 openssl req -text 看 SAN

一、覆盖层级(第一大坑,约占六成工单)。据 RFC 6125 §6.4.3 与 CA/Browser Forum Baseline Requirements 3.2.2.6,通配符只替换最左侧一个标签:*.example.com 匹配 a.example.com,不匹配 a.b.example.com,也不匹配 example.com 本身。证书里的 SAN 通配符同理,且 * 不能出现在中间(a.*.example.com 非法)。裸域必须单独写入 SAN——据 Let’s Encrypt 文档,ACME 客户端要显式把 example.com 与 *.example.com 两个标识一起提交,否则只覆盖一层子域。

二、多节点证书不一致。CDN 边缘、K8s Ingress Controller、独立回源机各自持有一份证书副本,漏发一台或某台仍是上一版,用户命中该节点的概率约等于它的流量占比,表现就是“时好时坏、切 4G 就好”。用 IP 直连并强制带 SNI,逐台比对序列号与指纹:

# 注意必须同时给 IP 和 -servername,否则拿到的可能是默认站点的证书
for ip in 203.0.113.10 203.0.113.11 198.51.100.7; do
  printf '%-16s ' "$ip"
  openssl s_client -connect "$ip:443" -servername www.example.com </dev/null 2>/dev/null 
    | openssl x509 -noout -serial -fingerprint -sha256 -enddate | tr 'n' ' '
  echo
done
# 序列号出现两种值 = 有节点没换证

三、SNI 未命中回落。Java 6/7、部分爬虫与监控探针不发 SNI,或直接用 IP 访问,Nginx 会回落到第一个 server 块(或 listen 443 default_server 那块)的证书,直接触发域名不匹配。复现方式:

# -noservername 模拟无 SNI 客户端,看它实际拿到哪张证书
openssl s_client -connect 203.0.113.10:443 -noservername </dev/null 2>/dev/null 
  | openssl x509 -noout -subject
# 修复方向:给 default_server 单独配一张自签或通用证书,别让它复用业务证书

四、证书链不完整。只下发 leaf、不带中间证书时,Chrome/Firefox 靠 AIA 自动补链能蒙混过关,Android 7 以下、Java truststore、部分 IoT 设备则直接报 unable to verify the first certificate(curl/Node)或 unable to get local issuer certificate。据 Mozilla 服务器端 TLS 配置建议,应下发 leaf + 全部中间证书、不含根证书:

# 服务端下发的证书张数;结果为 1 基本可判定缺中间证书
openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'

五、时间与缓存错位。据 RFC 5280 §4.1.2.5,notBefore/notAfter 一律以 UTC 记录,本地时区差 8 小时就会把“还有几小时生效”读成“尚未生效”:date -u 对照 openssl x509 -noout -dates -in fullchain.pem。同时 keep-alive 长连接与浏览器会话缓存在换证后会继续复用旧证书 5–30 分钟,别把缓存当成配置没生效。

六、签发输入错误。CSR 的 CN 写了 *.example.com 但 SAN 只填了裸域,或 ACME 客户端 dnsNames 漏写裸域,证书签发成功却与目标主机名不匹配。签发前先自检:openssl req -in wildcard.csr -noout -text | grep -A2 'Subject Alternative Name',确认 SAN 里同时出现 DNS:example.com 与 DNS:*.example.com。

通配符证书 troubleshooting 的 6 步实操流程(从定位到复签)

如果你已经确认症状是”某个子域不生效”或”多节点证书不一致”,先别逐个节点打开浏览器看锁标。下面这 6 步是一条可复现、可交接的排查链路,只依赖 openssl、dig、curl 与 nginx 自带命令,每一步都产出可对比的证据,而不是凭感觉猜测。

第 1 步:采集真实握手证书,而不是看控制台。浏览器会缓存、会走代理、会做 OCSP 软失败,唯一可信的是服务端在 SNI 命中后实际吐出的那张叶子证书。

# -servername 必须显式指定,否则拿到的是 default_server 的证书
# </dev/null 防止 s_client 等待 stdin 挂起,2>/dev/null 屏蔽 DH 参数与握手噪声
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -serial -ext subjectAltName

OpenSSL 1.1.1w 与 3.0.x 在该管道下的输出字段完全一致(3.x 仅对 X509v3 Subject Alternative Name 的换行做了排版调整),因此不同节点用不同发行版也能横向比对 serial。重点看 SAN 里是 DNS:*.example.com 还是写死的 DNS:api.example.com——据 RFC 9525(已取代 RFC 6125)第 2.3 节,通配符只匹配最左侧一个标签,*.example.com 不覆盖 v2.api.example.com,这是”子域不生效”最常见的根因之一。

第 2 步:把 DNS 问题和节点问题切开。先确认域名解析,再对每个节点 IP 单独发一次带 SNI 的请求。

dig +short api.example.com
# 逐个节点验证,用 --resolve 绕开本地 DNS 与出口代理
curl -vI --resolve api.example.com:443:203.0.113.10 https://api.example.com 2>&1 
  | grep -E 'subject:|issuer:|SSL certificate'

--resolve 自 curl 7.x 起支持 host:port:addr 三元组。所有节点返回同一 serial 说明证书一致,某个节点 serial 不同即该节点未被更新——这就是”多节点证书不一致”的判定依据。三种手段的分工如下:

手段 能回答什么问题 常见误判
dig +short 域名解析到哪些 IP、是否被 CNAME 到 CDN 本地 DNS 缓存命中旧记录,误判为节点故障
curl --resolve 指定 IP 上该域名返回哪张证书、HTTP 层是否通 直接用 IP 访问时 curl 不发 SNI,拿到默认证书
openssl s_client 握手层完整证书链、协议版本、SAN 明细 省略 -servername,结果与线上真实用户不同

第 3 步:单独校验证书链。把叶子证书与中间证书拼成完整链后本地验证,不经过网络。

cat cert.pem chain.pem > fullchain.pem   # 叶子在前,中间证书在后,顺序不可颠倒
openssl verify -CAfile root.pem -untrusted chain.pem cert.pem
# 期望输出:cert.pem: OK

若报 error 20 at 0 depth lookup: unable to get local issuer certificate,说明中间证书缺失或顺序颠倒;报 error 10 ... certificate has expired 则是时间问题。据 Let’s Encrypt 文档,其签发的 fullchain.pem 已包含中间证书,而 nginx 的 ssl_certificate 必须指向 fullchain 而非单独的 cert.pem——这正是多节点证书不一致的高频来源:一台机器配了 fullchain,另一台配了 cert。

第 4 步:核对服务端 SNI 分流。用 nginx -T 导出全部生效配置逐块比对,而不是只看主配置文件。

nginx -T 2>/dev/null | grep -nE 'server_name|ssl_certificate|listen 443'

确认没有 listen 443 ssl default_server 抢在具体子域之前命中;若 example.com 与 *.example.com 写在同一个 server 块,则所用证书的 SAN 必须同时包含两者(见第 5 步)。做通配符证书 troubleshooting 时,这一步能区分”证书本身不含该子域”和”含该子域但被别的 server 块截胡”。

第 5 步:重新签发并补齐 SAN。CN 字段已不被现代客户端用于校验,SAN 是唯一依据,所以签发时就要一次性写全。

openssl req -new -newkey rsa:2048 -nodes -keyout wildcard.key -out wildcard.csr 
  -subj '/CN=*.example.com' 
  -addext 'subjectAltName=DNS:*.example.com,DNS:example.com'
# 提交 CA 前复核,确认 SAN 已写入 CSR
openssl req -in wildcard.csr -noout -text | grep -A2 'Subject Alternative Name'

-addext 需 OpenSSL 1.1.1 及以上;1.1.0 及更早版本只能在 openssl.cnf 的 [req_ext] 段中声明 subjectAltName。另需注意,据 Let’s Encrypt 文档,通配符证书只能通过 DNS-01 挑战签发,HTTP-01 无法验证 *.example.com,因此签发前要确认 DNS TXT 记录可写。

第 6 步:灰度分发并重载。先小流量节点换证书,确认无误再全量。

nginx -t && nginx -s reload   # reload 平滑加载,不断开现有连接;restart 会重置全部 TLS 会话
kubectl rollout restart deploy/ingress-nginx -n ingress-nginx

nginx -s reload 会向 master 进程发送 HUP 信号,worker 处理完存量连接后退出,因此不会造成握手失败;systemctl restart nginx 则会直接断开在途连接。重载后必须重新执行第 1、2 步,确认各节点 serial 已统一,再按验证清单逐项回归。

配置与命令示例:Nginx 1.24、HAProxy 2.8、Caddy 2.7 与 cert-manager 1.14 怎么写

配置看起来“写对了”但子域仍然报证书不匹配,八成不是证书本身的问题,而是某个环节只认了裸域、没把 *.example.com 纳入 SNI 匹配范围。下面给出四套可直接落地的配置,以及两条比浏览器更快出结论的验证命令。据 Let’s Encrypt 文档,通配符证书只能通过 DNS-01 挑战签发,这决定了 Caddy 和 cert-manager 的写法与普通站点不同。

Nginx 1.24.0:一个 server 块同时覆盖裸域与通配符。关键点是 server_name 必须两个都写,且 ssl_trusted_certificate 不能省——据 Nginx 官方文档,ssl_stapling 与 ssl_stapling_verify 默认均为 off,而 stapling 生效的前提正是配置了用于校验 OCSP 响应的信任链文件。

# /etc/nginx/conf.d/example.conf  (Nginx 1.24.0)
server {
  listen 443 ssl;
  http2 on;                                   # 1.25.1 起推荐写法,1.24 用 listen 443 ssl http2;
  server_name example.com *.example.com;      # 裸域与通配符缺一不可
  ssl_certificate     /etc/ssl/fullchain.pem; # leaf + 中间证书
  ssl_certificate_key /etc/ssl/privkey.pem;
  ssl_trusted_certificate /etc/ssl/chain.pem; # 仅中间证书,OCSP stapling 的前提
  ssl_stapling on;
  ssl_stapling_verify on;
  ssl_protocols TLSv1.2 TLSv1.3;
}
# 校验并热加载
nginx -t && nginx -s reload

HAProxy 2.8:用 crt-list 做多证书匹配。单文件 PEM 的内部顺序必须为 leaf → 中间证书 → 私钥,否则启动即报 unable to load SSL private key from PEM file。crt-list 每行格式为“PEM 路径 + SNI 过滤器”,通配符只匹配一级子域。

# /etc/haproxy/certs.list  (HAProxy 2.8)
/etc/haproxy/certs/example.pem example.com
/etc/haproxy/certs/example.pem *.example.com

# haproxy.cfg
frontend fe_https
  bind :443 ssl crt-list /etc/haproxy/certs.list alpn h2,http/1.1
  default_backend be_app
# 校验配置
haproxy -c -f /etc/haproxy/haproxy.cfg

Caddy 2.7:不显式声明就不会申请通配符。Caddy 默认只为站点名走 HTTP-01/TLS-ALPN-01,*.example.com 根本不会进入证书 SAN。必须写出通配符并指定 DNS 提供商插件(需自行编译 xcaddy build --with github.com/caddy-dns/cloudflare):

# Caddyfile  (Caddy 2.7.x)
{
  email ops@example.com
}
example.com, *.example.com {
  tls {
    dns cloudflare {env.CF_API_TOKEN}   # 走 DNS-01,通配符的唯一途径
    resolvers 1.1.1.1
  }
  reverse_proxy 127.0.0.1:8080
}

cert-manager 1.14:dnsNames 必须同时列裸域与通配符。只写通配符会导致 https://example.com 回落默认证书;solvers 必须选 dns01(cloudflare 或 alidns),HTTP-01 无法签发通配符。

# Certificate 资源 (cert-manager 1.14)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard
  namespace: prod
spec:
  secretName: wildcard-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer          # Issuer 的 solvers 需配置 dns01 + cloudflare/alidns
  dnsNames:
    - example.com
    - '*.example.com'
# 签发后确认状态
kubectl describe certificate wildcard -n prod | grep -E 'Ready|Renewal Time'
组件 通配符如何进入证书 最常见失效点
Nginx 1.24 证书文件里已含 SAN,靠 server_name 匹配 漏写 *.example.com 或未配 ssl_trusted_certificate
HAProxy 2.8 crt-list 的 SNI 过滤器逐行匹配 PEM 内顺序错、私钥缺失
Caddy 2.7 站点块显式列出 + DNS-01 未写 *.example.com,只签了裸域
cert-manager 1.14 spec.dnsNames 数组 solvers 用了 http01,或漏列裸域

强制打到指定节点,绕过 DNS 与负载均衡。多节点证书不一致时,这一步比刷新浏览器可靠得多;curl 8.x 会直接打印主题与校验结论:

curl -vI --resolve api.example.com:443:203.0.113.10 
  https://api.example.com 2>&1 
  | grep -E 'subject:|issuer:|SSL certificate verify'
# 期望:subject: CN=*.example.com ...  SSL certificate verify ok.

链与 OCSP stapling 一次性核对。据 OpenSSL 文档,-status 会向服务端请求 OCSP 响应,-CAfile 用于本地验证链:

openssl s_client -connect api.example.com:443 -servername api.example.com 
  -status -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>/dev/null 
  | grep -E 'OCSP Response Status|Verify return code'
# 期望:OCSP Response Status: successful
#       Verify return code: 0 (ok)

若这里出现 Verify return code: 21 (unable to verify the first certificate),说明节点上少拼了中间证书——这正是多节点证书不一致最常见的成因,也是通配符证书 troubleshooting 中最容易被误判为“证书没签发成功”的一类问题。

“我买了一张 *.example.com,为什么 api.dev.example.com 还是报证书错误?”——因为通配符只匹配最左侧一个标签。据 RFC 6125 第 6.4.3 节与 RFC 9525 的表述,*.example.com 可以匹配 pay.example.com,但不能匹配 pay.cn.example.com,也不能匹配不带标签的裸域 example.com(后者必须在 SAN 里显式列出)。这一条决定了后面的选型逻辑:先判断你实际要覆盖的“层级深度”,再谈价格。先用 OpenSSL 把证书的真实覆盖范围打印出来,别信签发页面的宣传文案:

# 适用:OpenSSL 1.1.1+ / 3.x(3.x 用 -ext 更简洁,1.1.1 可用 -text 过滤)
openssl x509 -in fullchain.pem -noout -ext subjectAltName
# 典型输出:
#   X509v3 Subject Alternative Name:
#       DNS:*.example.com, DNS:example.com
# 说明:SAN 里没有 a.b.example.com,说明该通配符覆盖不到二级子域

# 交叉验证某个具体主机名是否被覆盖(-verify_hostname 自 OpenSSL 1.1.0 起可用)
openssl x509 -in fullchain.pem -noout -verify_hostname api.dev.example.com
# 不匹配时输出:Hostname api.dev.example.com does not match certificate

下面是 2025 年 8 月渠道询价的量级对比。价格随 CA、代理商与年限折扣浮动,仅用于判断预算档位,不作为报价依据;覆盖层级与吊销影响面才是决策主变量。

方案 覆盖层级 2025-08 询价量级 签发耗时 吊销爆炸半径 运维复杂度
通配符 DV *.example.com,仅一级子域 国内 CA 约 ¥600–1500/年;国际品牌约 $60–120/年 DNS-01,1–10 分钟 大:一次吊销全部一级子域同时失效 低(一张证书),但需保管 DNS API 凭据
通配符 OV 同上,仅一级子域 国内约 ¥2000–6000/年 1–3 个工作日(需企业实名与组织核验) 大:同上 中:每年组织信息复审
多域名 SAN(UCC) 10–100 个具体 FQDN,不受标签层级限制 单价随域名数递减,第 2 个起通常按 30%–60% 计价 DV 分钟级;OV 1–5 个工作日 中:等于证书内列出的全部域名 中:每新增子域都要重签整张证书
单域名 DV(ACME 免费) 单个 FQDN ¥0(Let’s Encrypt / ZeroSSL) HTTP-01 秒级到 1 分钟 最小:只影响一个主机名 高:证书数随子域线性增长,需编排与到期监控
私有 CA(内部系统) 任意层级,可签 *.corp.internal、*.*.svc.internal 仅人力与 HSM 成本 秒级 可控:短有效期 + 自建 CRL 精确吊销 中高:根证书必须推入所有客户端信任库

逐子域 ACME 之所以“最省心也最费心”,是因为它会撞上 CA 的速率限制——据 Let’s Encrypt 文档,同一注册域默认每周 50 张证书、每 3 小时 300 个新订单,几百个子域一次性铺开会直接触发 too many certificates (5) already issued for this exact set of domains 类报错,必须靠 cert-manager 或 acme.sh 分批续期。通配符则相反:DNS-01 一次签发覆盖全域,但凭据一旦泄露,攻击者可自行申请同域证书。cert-manager 里把这两条边界写清楚,比事后排查便宜得多:

# 适用:cert-manager 1.14+(v1 API);duration/renewBefore 单位均为 time.Duration
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example
  namespace: ingress
spec:
  secretName: wildcard-example-tls
  dnsNames:
    - example.com          # 裸域必须显式列出,通配符不覆盖
    - "*.example.com"      # 只覆盖一级;a.b.example.com 需另加 SAN 或另发证书
  issuerRef:
    name: le-dns01         # ClusterIssuer,DNS-01 solver 需配置 DNS API 凭据
    kind: ClusterIssuer
  duration: 2160h          # 默认 90 天
  renewBefore: 720h        # 默认 30 天,约有效期的 1/3

私有 CA 的隐性成本在信任库分发:客户端没装根证书时,报错非常具体——curl: (60) SSL certificate problem: unable to get local issuer certificate,浏览器则提示 NET::ERR_CERT_AUTHORITY_INVALID。因此它适合内网、mTLS 与服务网格(如 Istio 的 Citadel/istiod 签发的 workload 证书),绝不适合面向公网用户。最后提醒一点:据 Let’s Encrypt 2025 年公告,其 OCSP Responder 已于 2025 年 8 月 6 日下线,吊销状态转由 CRL 承载,而浏览器对 CRL 的实时检查本就宽松——这意味着“吊销”在通配符场景下往往不能立刻止血,缩短有效期(ACME 侧 90 天甚至更短)比依赖吊销更可靠。这也是排查多节点证书不一致时,第一步应当比对 notBefore/serial 而非只看域名是否匹配的原因。

常见错误与排查:8 条真实报错分别对应什么根因

做通配符证书 troubleshooting时,先分清两类问题:证书里根本没有那个名字(SAN 不匹配),还是证书有但没送到客户端(链路缺失、SNI 缺失、时间漂移)。下面 8 条报错几乎覆盖 90% 的线上工单,报错原文与根因一一对应。

报错原文(截取) 常见客户端/版本 根因 一句话验证
NET::ERR_CERT_COMMON_NAME_INVALID Chrome 117+ SAN 不含当前主机名,多为访问了 a.b.example.com 二级子域或裸域 openssl x509 -noout -ext subjectAltName
SSL_ERROR_BAD_CERT_DOMAIN Firefox 120+ 同上,Firefox 已完全忽略 CN 只看 SAN 同上
curl: (60) SSL: no alternative certificate subject name matches target host name ‘a.b.example.com’ curl 7.85+(OpenSSL 后端) 与上同源,通配符只覆盖一级,需重签多域名(SAN)证书 curl -vI https://a.b.example.com
java.security.cert.CertificateException: No subject alternative DNS name matching api.example.com found JDK 8u181 之前 旧版通配符匹配更严格;或客户端未发 SNI 命中默认站点 openssl s_client -connect host:443 -servername host
x509: certificate is valid for *.example.com, not example.com Go 1.15+ Go 严格按 SAN 匹配且不接受通配符覆盖裸域 证书 SAN 补 example.com
unable to verify the first certificate / UNABLE_TO_VERIFY_LEAF_SIGNATURE Node.js、curl、Java 中间证书缺失,只发了 leaf openssl s_client -showcerts 数条数
DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com cert-manager 1.13+ / Let’s Encrypt DNS-01 记录未写入或尚未传播(通常 10–120 秒) dig +short TXT
unable to obtain ACME certificate for domains ‘*.example.com’ Traefik 2.10 只配了 HTTP-01;据 Let’s Encrypt 文档,通配符只能走 DNS-01 检查静态配置 dnsChallenge
# 复核 SAN:OpenSSL 1.1.1+ 才有 -ext;1.1.0 及更早用 openssl x509 -noout -text
openssl x509 -noout -ext subjectAltName -in cert.pem
# X509v3 Subject Alternative Name:
#     DNS:*.example.com, DNS:example.com   ← 缺 example.com 就会触发 Go/裸域报错

# 数证书链:正常为 leaf + 1~2 张中间证书
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null 
  | grep -c 'BEGIN CERTIFICATE'
# 输出 1 = 只发了 leaf,检查 ssl_certificate 是否指向 fullchain.pem

# DNS-01 传播与时间漂移
dig +short TXT _acme-challenge.example.com @8.8.8.8
date -u; openssl x509 -noout -dates -in cert.pem   # notBefore/notAfter 均为 UTC,偏差 >5 分钟先校 NTP
# traefik.yml(静态配置,Traefik 2.10)——HTTP-01 无法签发通配符,必须 DNS-01
certificatesResolvers:
  le:
    acme:
      email: ops@example.com
      storage: /data/acme.json
      dnsChallenge:
        provider: cloudflare        # 关键行:缺失时即报 unable to obtain ACME certificate
        resolvers:
          - "1.1.1.1:53"            # 规避本地 DNS 缓存导致 NXDOMAIN

为什么通配符只匹配一级?RFC 6125 §6.4.3 规定 *.example.com 仅覆盖单个最左标签,a.b.example.com 不在其中——这也是通配符证书 troubleshooting里被误判最多的一条。JDK 8u181 起对 SAN 匹配规则做过修正,Go 1.15 则明确拒绝通配符覆盖裸域;两端行为差异,正是同一张证书”Chrome 正常、Go 服务报错”的原因。

效果验证:怎么确认通配符证书在每台节点、每个子域都生效

判断通配符证书是否”真的生效”,判据只有一条:所有节点、所有子域返回同一序列号(serial)与同一 notAfter。任一差异即说明分发失败、vhost 覆盖或回源回退到了旧证书。下面的 6 组验证由快到慢、由内到外排列,建议按顺序跑完再收工。

1. 批量握手脚本:所有子域是否同一张证书?

# OpenSSL 1.1.1 / 3.x 均可;-servername 必须显式给出,否则 SNI 缺失会拿到默认站点的证书
for h in www api admin; do
  echo | openssl s_client -connect $h.example.com:443 
    -servername $h.example.com 2>/dev/null 
    | openssl x509 -noout -serial -dates
done
# 期望:三行输出完全一致(同一 serial + 同一 notAfter)

2. 节点维度:CDN 边缘与回源 IP 逐个比对

# 对每个边缘/回源 IP 用同一个 SNI 握手,逐个看 serial
for ip in 203.0.113.10 203.0.113.11 198.51.100.7; do
  echo "== $ip"
  echo | openssl s_client -connect $ip:443 -servername api.example.com 2>/dev/null 
    | openssl x509 -noout -serial -subject -dates
done

连 IP 时同样要带 -servername,否则拿到的是默认 vhost 的证书,比对结果毫无意义。任一台 serial 不同,就按”分发失败”处理,而不是先怀疑客户端。

3. 协议与套件扫描:testssl.sh 3.2

./testssl.sh --severity HIGH --fast https://api.example.com
# 重点看三行是否为 OK:certificate matching / chain of trust / OCSP stapling

--fast 会跳过部分耗时探测,适合流水线内每轮发布后跑;--severity HIGH 只输出高危及以上问题,避免噪声淹没证书类告警。

4. 在线复核:SSL Labs 与 CT 日志

Qualys SSL Labs 查一次整体评级(注意其缓存可能滞后数小时,可点 “Clear cache”),crt.sh 用 https://crt.sh/?q=%25.example.com 确认新证书已进入 CT 日志(%25 即 % 的 URL 编码,等价于 %.example.com)。据 Let’s Encrypt 文档,其签发的每张证书都会提交 CT,通常 24 小时内可在 crt.sh 查到;查不到往往意味着签发链路走的是私有 CA 或中间代理。

5. 编排层状态:cert-manager 是否已把新证书下发到所有命名空间

kubectl get certificate -A                      # READY 应全部为 True
kubectl describe certificate api-example-com -n prod | grep -E 'Renewal Time|Not After|Ready'
# Renewal Time 距当前应不少于 30 天(90 天证书场景)

cert-manager 1.14 的默认行为是在证书已消耗 2/3 生命周期时触发续期(renewBefore 未显式设置时按此规则计算),因此 90 天证书续期后剩余约 30 天属正常;若 Renewal Time 已过期而 READY 仍为 True,说明 Secret 更新了但工作负载未热加载。

6. 客户端侧回归:三类行为缺一不可

客户端 代表行为 典型失败表现
Android 7 模拟器 不做 AIA 补链,只信任系统根 浏览器报”证书链不完整”,但 curl 正常
JDK 8(8u3xx) 严格 SNI 与主机名校验 SSLHandshakeException: No subject alternative names present
curl 8.x(OpenSSL 3) 现代客户端,会跟随 AIA 补链 通常成功,仅作基线对照

三者分别覆盖”不补链客户端””严格 SNI 客户端””现代客户端”。只测 curl 是最常见的漏测——它会把缺失中间证书的问题完全掩盖掉。

7. 一个高频误判:按 RFC 6125,通配符只匹配最左侧一个标签,*.example.com 既不匹配 a.b.example.com,也不匹配裸域 example.com。这类”子域不生效”根本不是分发问题,把 SAN 补上即可。这也是通配符证书 troubleshooting 中最容易被误判成”节点不一致”的一类。

把 troubleshooting 变成巡检:过期告警与回归清单怎么落地

告警阈值分几档才不至于被当成狼来了?

据 Let’s Encrypt 官方文档,其证书有效期为 90 天,且官方建议在剩余 30 天前完成续期;CA/Browser Forum Baseline Requirements 又把单张证书有效期上限压到 398 天。这意味着“到期前一周才想起来”必然出事。我们把它固化成三档,告警通道与响应动作分离,避免全部涌进同一个群:

档位 触发条件(剩余) 通道 响应动作
P3 工单 < 30 天 Jira / 企微群 创建续期工单,7 个工作日内关闭
P2 升级 < 15 天 PagerDuty / 电话值班 升级到 SRE owner,当日必须有人认领
P1 电话 < 7 天 电话 + 短信,循环呼叫 视为故障,走变更紧急通道

指标侧不用自己写解析器:blackbox_exporter 0.25.0 起稳定提供 probe_ssl_earliest_cert_expiry(gauge,单位秒的 Unix 时间戳,取整条链上最早过期的证书)。Prometheus 规则直接做差即可,注意用 probe_success == 1 过滤掉握手失败导致的 NaN,否则会天天误报:

# prometheus/rules/tls-expiry.yml
# 适用 blackbox_exporter >= 0.25.0;scrape_interval 默认 15s,for 给 10m 去抖
groups:
  - name: tls-expiry
    rules:
      - alert: TLSCertExpiresIn30Days
        expr: probe_success == 1 and (probe_ssl_earliest_cert_expiry - time()) < 86400 * 30
        for: 10m
        labels: { severity: ticket }
        annotations:
          summary: "{{ $labels.instance }} 证书剩余 {{ $value | humanizeDuration }}"
      - alert: TLSCertExpiresIn15Days
        expr: probe_success == 1 and (probe_ssl_earliest_cert_expiry - time()) < 86400 * 15
        for: 10m
        labels: { severity: page }
      - alert: TLSCertExpiresIn7Days
        expr: probe_success == 1 and (probe_ssl_earliest_cert_expiry - time()) < 86400 * 7
        for: 5m
        labels: { severity: phone }

没有 Prometheus 的小集群,怎么用一条 cron 兜底?

通配符证书 troubleshooting 最常见的现场就是“某个边缘节点没跟着换”,而这类节点往往没接监控。用 OpenSSL 3.x 写一个纯 shell 巡检,结果追加进日志,便于事后比对:

#!/usr/bin/env bash
# /usr/local/bin/tls-check.sh  —— 每日 UTC 03:00 由 cron 调用
set -uo pipefail
HOSTS="api.example.com www.example.com admin.example.com"
WARN=15                                   # 阈值天数,与 P2 档对齐
for h in $HOSTS; do
  end=$(openssl s_client -connect "$h:443" -servername "$h" </dev/null 2>/dev/null 
        | openssl x509 -noout -enddate | cut -d= -f2)   # 输出形如 Apr 12 08:00:00 2026 GMT
  if [ -z "$end" ]; then
    echo "$(date -u +%FT%TZ) host=$h HANDSHAKE_FAIL" >> /var/log/tls-check.log; continue
  fi
  exp=$(date -u -d "$end" +%s); now=$(date -u +%s)      # macOS 需改 date -j -f "%b %d %T %Y %Z"
  left=$(( (exp - now) / 86400 ))
  echo "$(date -u +%FT%TZ) host=$h not_after=$end days_left=$left" >> /var/log/tls-check.log
  [ "$left" -lt "$WARN" ] && echo "$h 证书仅剩 ${left} 天" | mail -s "TLS 告警" ops@example.com
done

务必带 -servername:省略 SNI 时很多 CDN 会返回默认站点证书,你会得到一个“看起来没问题”的假阴性——这正是通配符证书 troubleshooting 里最隐蔽的一类误判。

换完证书就算完事了吗?回归清单固定成哪 6 项?

任一项失败即回滚上一版证书,不允许“先上线再观察”:

  1. SAN 覆盖:*.example.com 按 RFC 6125 只匹配一级标签,a.b.example.com 必须额外列 SAN。
  2. 链完整性:服务端需下发叶子 + 中间证书,缺中间证书在旧安卓上直接报 unable to get local issuer certificate。
  3. OCSP stapling:未开启时输出为 OCSP response: no response sent。
  4. 各节点序列号一致:多节点不一致是通配符证书 troubleshooting 的高频根因。
  5. 旧客户端可访问:至少验证 TLS 1.2 握手成功(Mozilla SSL Configuration Generator 的 intermediate 配置为基线)。
  6. CT 日志可查:新证书应在 crt.sh 上可见。
# 1) SAN 覆盖
openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name"
# 2) 链完整性:期望 >= 2
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 3) OCSP stapling
openssl s_client -connect api.example.com:443 -servername api.example.com -status </dev/null 2>/dev/null | grep -i "OCSP Response Status"
# 4) 多节点序列号比对
for ip in 10.0.1.11 10.0.1.12; do echo -n "$ip "; openssl s_client -connect $ip:443 -servername api.example.com </dev/null 2>/dev/null | openssl x509 -noout -serial; done
# 5) 旧客户端
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>/dev/null | grep Protocol
# 6) CT 日志
curl -s "https://crt.sh/?q=api.example.com&output=json" | jq -r '.[].serial_number' | sort -u | head

续期方式怎么统一,才能彻底告别手工上传?

场景 工具与版本 挑战类型 有效期
公网子域 / 通配符 cert-manager 1.14(K8s 内) DNS-01(HTTP-01 无法签发 *.example.com) 90 天,自动续期
非 K8s 公网主机 acme.sh 3.0.x DNS-01 90 天,cron 续期
内部系统 step-ca 0.25+ ACME / JWK 90 天,强制自动轮换
# acme.sh 3.0.x:注意 -d 必须同时给裸域与通配符,且用单引号防止 shell 展开 *
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256 --server letsencrypt
# step-ca:--not-after 2160h = 90 天,与公网侧口径对齐
step ca certificate "api.internal" api.crt api.key --ca-url https://ca.internal --not-after 2160h

私钥权限和外泄怎么兜底?

签发后立即收敛权限并校验私钥完整性:

chown root:root privkey.pem && chmod 600 privkey.pem
openssl rsa -in privkey.pem -check -noout    # RSA 期望输出:RSA key ok
openssl pkey -in privkey.pem -check -noout   # EC 密钥期望输出:Key is valid

私钥一旦外泄,唯一正确动作是立即吊销并重签,而不是“先观察”。同时把 crt.sh 的查询结果接进巡检脚本,比对清单外的序列号——出现你不认识的签发记录,通常意味着 ACME 账户或 DNS API Token 已被滥用。

不能。据 RFC 6125 §6.4.3,通配符只替换最左侧一个标签,a.b.example.com 需要 *.b.example.com 或直接写进 SAN 列表。若业务存在多级子域,建议改用多域名 SAN 证书,或为每个二级域单独签发通配符。

九成是访问的主机名不在 SAN 里,常见于访问了裸域 example.com 或多级子域。先用 openssl s_client -connect host:443 -servername host -showcerts 取出实际下发的证书,再用 openssl x509 -noout -ext subjectAltName 核对,若 SAN 只有 *.example.com,就需补签带裸域的证书。

多域名 SAN 更好排查,因为每个域名在 SAN 里显式列出,报错时一眼能看出漏了谁;通配符则要先判断是否命中覆盖层级,多一层推理。但子域数量超过 10 个后,SAN 证书每次新增都要重签,运维成本反而更高,通常做法是主域用通配符、多级子域用 SAN 补充。

必须用 DNS-01,因为 HTTP-01 无法证明对整个域名的控制权。续期可以全自动:cert-manager 1.14 配置 dns01 solver 后会在到期前 30 天自动续期,acme.sh 3.0 用 –dns dns_cf 配合 cron 也能自动完成,关键是 DNS API Token 要长期有效。

取决于回源方式。如果 CDN 回源走 HTTP,源站无需证书;如果走 HTTPS 回源,源站必须配置一张覆盖回源域名的证书,否则 CDN 侧会报 526 或 502。建议回源使用独立的内部域名证书,与边缘通配符证书解耦,便于分别轮换。

立即通过 CA 或 ACME 接口吊销(Let's Encrypt 可用 certbot revoke 或 cert-manager 删除 Secret 触发重签),重新生成密钥对并签发新证书,切勿复用旧私钥。随后在 crt.sh 与 CT 监控里观察是否出现异常签发记录,并检查服务器上是否存在私钥文件权限过宽(应为 600、属主 root)。

可以,但 CSR 与 SAN 必须写 Punycode 形式,例如 *.xn--fiq228c.cn,不能直接写中文。签发后用 openssl x509 -noout -ext subjectAltName 确认显示为 xn-- 前缀,浏览器地址栏仍可正常显示中文域名。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。