跳到主要内容
安装配置教程

通配符证书怎么配置?Nginx、Apache、HAProxy 多服务端落地与 6 类报错排查(2025)

通配符证书怎么配置 — 通配符证书怎么配置?Nginx、Apache、HAProxy 多服务端落地与 6 类报错排查(2025)
核心结论

通配符证书配置的核心只有三件事:把 fullchain.pem(站点证书 + 中间 CA)与私钥放对位置、让 server_name 同时覆盖 *.example.com 与裸域 example.com、改完执行 nginx -t && nginx -s reload 让进程重新读取证书文件。 *.example.com 只替代最左一个标签,a.b.example.com 必须另签 *.b.example.com;裸域不在通配符范围内,需在 SAN 中显式列出,用 openssl x509 -noout -ext subjectAltName 核对。 Nginx 1.25.1 起用 http2 on; 取代 listen 443 ssl http2;Apache 2.4.8 起废弃 SSLCertificateChainFile,中间证书直接拼进 SSLCertificateFile 指向的 fullchain.pem。 HAProxy 2.8 要求证书、私钥、中间 CA 按序合并为单个 .pem 文件;Spring Boot 2.7+ 可直接读取 PEM,不必再转 JKS。 验证链路:openssl s_client -servername 抓链 → openssl x509 -checkhost 验域名 → openssl verify -untrusted chain.pem 验完整性;Let's Encrypt 90 天有效期务必配 --deploy-hook 自动 reload。

为什么通配符证书配好了还报名称不匹配?先看清 5 个根本原因

在排查现场,最常见的一句抱怨是”证书明明签下来了,浏览器却说域名不符”。这通常不是 CA 签错,而是匹配规则、证书链、server_name、SNI、进程重载五层中某一层没对齐。先看清这五层,再谈通配符证书怎么配置,能省掉大半返工。

  1. 通配符只顶一个标签,且不含裸域。据 RFC 6125 第 6.4.3 节,*.example.com 仅替代最左侧单个标签:匹配 a.example.com,不匹配 a.b.example.com,也不匹配 example.com——后者必须在 SAN 中显式列出 DNS:example.com。Let’s Encrypt 的通配符证书同样遵循此规则,且只能走 DNS-01 验证。自检命令(注意现代客户端忽略 CN,只看 SAN):
# 查看 SAN 列表,确认是否同时含 *.example.com 与 example.com
openssl x509 -in wildcard.crt -noout -ext subjectAltName
# 输出示例:X509v3 Subject Alternative Name: DNS:*.example.com, DNS:example.com

# 用 OpenSSL 3.x 的 verify 子命令模拟主机名校验
openssl verify -verify_hostname a.example.com   -CAfile chain.pem wildcard.crt   # OK
openssl verify -verify_hostname a.b.example.com -CAfile chain.pem wildcard.crt
# 报错:error 62 at 0 depth lookup: hostname mismatch
  1. 证书链缺失:只发了叶子证书。Nginx 的 ssl_certificate 若只指向站点证书 server.crt,握手时不会补发中间 CA。Chrome 120+ 会显示”证书颁发者无法验证”,而 Android 7 以下与 Java 8 客户端直接抛 CertPathValidatorException: Trust anchor for certification path not found。正确做法是拼接成 fullchain(叶子在前):
# 顺序不能反:站点证书 → 中间 CA;根证书不要拼进去
cat server.crt intermediate.crt > fullchain.pem
openssl verify -untrusted intermediate.crt server.crt

# 从服务端实际抓取,统计链上证书数量,期望 ≥2
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | grep -c "BEGIN CERTIFICATE"
  1. server_name 未命中,落到 default_server。同端口存在默认块时,Host 不在任何 server_name 中的请求会拿到默认块的证书,表现为”证书与域名不符”而非”证书不存在”。Nginx 1.19.4+ 建议直接拒绝:
server {
    listen 443 ssl default_server;
    server_name _;
    ssl_reject_handshake on;          # 1.19.4+,未命中 SNI 时直接拒绝握手
    ssl_certificate     /etc/nginx/ssl/default.crt;   # 兜底证书
    ssl_certificate_key /etc/nginx/ssl/default.key;
}
  1. 客户端不发 SNI,只能拿默认证书。Java 6、部分老爬虫与不带 -servername 的 openssl 调用都属于此类。据 OpenSSL 文档,s_client 默认不发送 SNI,需显式指定或用 -noservername 复现:
# 不带 SNI:拿到的是默认 server 证书
openssl s_client -connect 1.2.3.4:443 /dev/null | openssl x509 -noout -subject
# 带 SNI:拿到通配符证书
openssl s_client -connect 1.2.3.4:443 -servername a.example.com /dev/null 
  | openssl x509 -noout -subject -dates
  1. 文件已更新,进程没重载。Nginx 1.26 不会自动重读证书文件,master 进程持有旧证书直到 reload;续期脚本只跑 nginx -t 是典型踩坑点。HAProxy 的 reload 会新起进程,旧进程仍在服务存量连接。
# 先看服务端当前生效的证书有效期,再决定是否重载
openssl s_client -connect 127.0.0.1:443 -servername a.example.com /dev/null 
  | openssl x509 -noout -dates

nginx -t && nginx -s reload            # Nginx:等价 systemctl reload nginx
apachectl -t && apachectl graceful     # Apache 2.4:graceful 才会重读证书
haproxy -c -f /etc/haproxy/haproxy.cfg && systemctl reload haproxy
典型报错 / 现象 根因 一条命令定位
hostname mismatch(error 62) 层级或裸域不匹配 openssl x509 -in c.crt -noout -ext subjectAltName
证书颁发者无法验证 / Trust anchor not found 链缺失 openssl s_client -showcerts | grep -c BEGIN
证书与域名不符但域名存在 落到 default_server nginx -T | grep -n default_server
命令行正常、老客户端失败 无 SNI openssl s_client -noservername
有效期仍是旧的 未 reload openssl x509 -noout -dates + ps -o lstart -C nginx

通配符证书怎么配置?从文件准备到生效的 8 个步骤

问:证书文件已经拿到手,通配符证书怎么配置才不会踩坑?先把”文件准备 → 写入配置 → 续期后自动生效”这条链路走完,比直接抄一段 server 块可靠得多。下面 8 个步骤按顺序执行,每步都有可验证的输出。

  1. 步骤 1–2:用 SAN 确认这张证书到底覆盖哪些域名。
    # 通配符证书必须同时含 *.example.com 与裸域 example.com
    openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name"
    # 期望输出:
    #   X509v3 Subject Alternative Name:
    #       DNS:*.example.com, DNS:example.com
    

    通配符只匹配一个标签:*.example.com 覆盖 a.example.com,不覆盖 a.b.example.com,也不覆盖裸域 example.com。缺裸域只能在申请时追加 SAN 或重签,server_name 写得再全也绕不过浏览器校验(RFC 6125 §6.4.3 对通配符匹配有明确约束)。

  2. 步骤 3–4:生成私钥与带 SAN 的 CSR。
    # -addext 需 OpenSSL 1.1.1 及以上;3.0.x(含 3.0.13)同样适用
    openssl req -new -newkey rsa:2048 -sha256 -nodes 
      -keyout example.com.key -out example.com.csr 
      -subj "/CN=*.example.com" 
      -addext "subjectAltName=DNS:*.example.com,DNS:example.com"
    openssl req -in example.com.csr -noout -text | grep -A1 "Subject Alternative Name"
    

    -nodes 表示私钥不加密:加密私钥会让 Nginx 每次 reload 都需交互输入口令,生产环境不建议。1.1.1 之前无 -addext,须用 -config 指向含 [v3_req] 的配置文件。改用 ECDSA(-newkey ec -pkeyopt ec_paramgen_curve:prime256v1)可减小握手体积,但要确认客户端兼容性。

  3. 步骤 5:目录、权限与 SELinux 上下文。
    mkdir -p /etc/nginx/ssl/example.com   # 放入 fullchain.pem、privkey.pem、chain.pem
    chmod 600 /etc/nginx/ssl/example.com/privkey.pem
    chown root:root /etc/nginx/ssl/example.com/privkey.pem
    # RHEL 9 / CentOS Stream 9 且 SELinux 为 enforcing 时:
    chcon -t httpd_sys_content_t /etc/nginx/ssl/example.com/*.pem
    ls -lZ /etc/nginx/ssl/example.com/    # 核对上下文
    

    漏掉 chcon 的典型症状:nginx -t 通过、进程能起,但访问时报 SSL_CTX_use_PrivateKey_file() failed ... (13: Permission denied)。

  4. 步骤 6:按正确顺序拼接证书链。
    # 站点证书在前,中间 CA 在后;顺序反了部分客户端报 unable to get local issuer certificate
    cat server.crt intermediate.crt > fullchain.pem
    grep -c "BEGIN CERTIFICATE" fullchain.pem   # 通常为 2
    

    不要把根证书拼进去:握手包变大,且部分旧客户端(旧版 Android、Java 信任库)对多余的自签根会校验异常。据 Let’s Encrypt 文档,其签发的 fullchain.pem 已按此顺序排好,可直接使用。

  5. 步骤 7:写入 server 块并平滑生效。
    server {
        listen 443 ssl;
        server_name example.com *.example.com;   # 裸域与通配符都要写
        ssl_certificate     /etc/nginx/ssl/example.com/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/example.com/privkey.pem;
        ssl_protocols       TLSv1.2 TLSv1.3;
    }
    
    nginx -t && nginx -s reload
    
    操作 存量连接 配置写错时 适用场景
    nginx -s reload 旧 worker 处理完才退出,不中断在线请求 nginx -t 失败则不生效,继续跑旧配置 换证书、改 server 块(推荐)
    systemctl restart nginx 全部断开,出现短时 502 / 连接重置 启动失败,服务直接不可用 改监听端口、加载新模块
  6. 步骤 8:让续期后自动生效。
    certbot renew --deploy-hook "systemctl reload nginx"
    grep -r renew_hook /etc/letsencrypt/renewal/    # 应看到 renew_hook = systemctl reload nginx
    certbot renew --dry-run                         # 演练,不真正签发
    

    据 Let’s Encrypt 文档,--deploy-hook 仅在证书确实续期成功时触发,--post-hook 则每次运行都执行。缺少 renew_hook 字段时,定时任务续期成功但内存里仍是旧证书,可用 openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates 对比 notAfter 确认。

各服务端的通配符证书配置片段怎么写?Nginx、Apache、HAProxy、Spring Boot 示例

同一张 fullchain.pem,为什么在四个服务端要写成四种样子?因为每家加载私钥和证书链的方式不同:Nginx 分开读证书与私钥,Apache 的链文件参数已废弃,HAProxy 只认“单文件拼接”,Spring Boot 则从 2.7 起才原生支持 PEM。下面按服务端给出可直接复制的片段。

Nginx 1.24 / 1.26:注意 http2 指令位置变了

# Nginx 1.25.1+ 写法;1.24 及更早版本请把 http2 写回 listen 行:listen 443 ssl http2;
server {
    listen 443 ssl;
    http2 on;                                   # 1.25.1 起取代 listen 行的 http2 参数
    server_name *.example.com example.com;      # RFC 6125:通配符仅匹配最左一级标签,不匹配 a.b.example.com
    ssl_certificate     /etc/nginx/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;        # 与 Mozilla SSL Configuration Generator 的 intermediate 档一致
    ssl_session_cache   shared:SSL:10m;
}

Apache httpd 2.4.58:不要再写 SSLCertificateChainFile

<VirtualHost *:443>
    ServerName example.com
    ServerAlias *.example.com
    SSLEngine on
    SSLCertificateFile    /etc/httpd/ssl/fullchain.pem   # 站点证书 + 中间 CA 已合并
    SSLCertificateKeyFile /etc/httpd/ssl/privkey.pem
    Protocols h2 http/1.1
</VirtualHost>
# SSLCertificateChainFile 自 2.4.8 起废弃,继续使用会告警且链路可能不完整

HAProxy 2.8 / 2.9:拼接顺序错了直接启动失败

# 顺序必须是 站点证书 → 私钥 → 中间 CA;写反报 "unable to load SSL private key"
cat fullchain.pem privkey.pem chain.pem > /etc/haproxy/certs/example.com.pem
chmod 600 /etc/haproxy/certs/example.com.pem
chown haproxy:haproxy /etc/haproxy/certs/example.com.pem
# haproxy.cfg 中:bind *:443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1

Spring Boot 3.2 内嵌 Tomcat:不必再转 JKS

server:
  port: 443
  ssl:
    certificate: classpath:fullchain.pem          # Spring Boot 2.7 起原生支持 PEM
    certificate-private-key: classpath:privkey.pem

Kubernetes Ingress:secret 必须同 namespace

kubectl create secret tls wildcard-example --cert=fullchain.pem --key=privkey.pem -n prod
# Ingress 的 tls.hosts 写 *.example.com;跨 namespace 引用不会报错,而是静默回退到默认证书
服务端 证书文件形态 关键指令 最常见坑
Nginx 1.24/1.26 fullchain + privkey 分离 ssl_certificate / http2 on 1.24 用 http2 on 报 unknown directive
httpd 2.4.58 fullchain + privkey 分离 ServerAlias / SSLCertificateFile 沿用已废弃的 ChainFile 参数
HAProxy 2.8/2.9 三者 cat 成单文件 bind … ssl crt 拼接顺序错、权限非 600
Spring Boot 3.2 PEM 直接引用 server.ssl.certificate 2.6 及以前必须转 JKS/PKCS12

OCSP Stapling:只写 on 等于没开

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/example.com/chain.pem;  # 只放中间 CA,勿放站点证书
resolver 223.5.5.5 119.29.29.29 valid=300s;                     # 缺 resolver 时 stapling 永不生效
resolver_timeout 5s;

验证方式:openssl s_client -connect www.example.com:443 -status -servername www.example.com </dev/null | grep -A2 "OCSP Response",据 OpenSSL 文档,输出 OCSP Response Status: successful 才算真正生效。

通配符证书、单域名、多域名 SAN 怎么选?一张参数对比表

先给结论:子域都在同一个一级域下,就选通配符;子域分散在多个二级域且数量固定(8–10 个),多域名 SAN 往往更省事;需要向客户展示企业主体,才升到 OV。下表是 2025 年国内主流 CA 与 Let’s Encrypt 的实际参数区间,可直接拿去报预算。

类型 覆盖范围 域名验证方式 参考年费(人民币) 关键限制
单域名 DV 1 个 FQDN,如 api.example.com HTTP-01 文件 或 DNS-01 0–200 元(Let’s Encrypt 免费) 换一个子域就要重签一张
通配符 DV *.example.com 下无限个一级子域 仅 DNS-01 300–800 元(Let’s Encrypt 免费) 不含裸域 example.com;不含 a.b.example.com
通配符 OV 同上,另核验企业主体 DNS-01 + 营业执照核验 2000–6000 元 审核 1–3 个工作日;同样只覆盖一级
多域名 SAN 单证书 5–100 个不同域名,可跨主域 混合:每个域名独立过 HTTP/DNS 500–3000 元 新增域名须整张重签;SAN 条数受 CA 上限约束
EV 单域名或多域名 企业深度核验 3000 元起 不支持通配符;浏览器自 2019 年起不再显示地址栏绿条

覆盖范围为什么最容易算错?通配符只匹配一层标签。按 RFC 6125 的证书身份匹配规则,*.example.com 匹配 a.example.com,但不匹配 a.b.example.com,也不匹配裸域 example.com——后者必须作为独立 SAN 显式加进去。所以业务一旦出现二级结构(如 cn.api.example.com、us.api.example.com),正确规划是”每个二级域一张通配符”,即 *.api.example.com、*.shop.example.com 各签一张,证书数量与二级域个数成正比,预算按此估算。

验证方式对运维的真实影响:据 Let’s Encrypt 官方文档(ACME 协议见 RFC 8555),通配符订单一律不接受 HTTP-01,只走 DNS-01,因为 CA 无法在未知子域上放置验证文件。这意味着你必须在 DNS 服务商侧维护 API 凭据,并让客户端写入 _acme-challenge.example.com 的 TXT 记录。certbot 2.9+/3.x 用插件方式签发通配符证书:

# 适用于 certbot 2.9+ / 3.x;需先安装 python3-certbot-dns-cloudflare
# cloudflare.ini 权限必须 600,内容为 dns_cloudflare_api_token = <token>
certbot certonly 
  --dns-cloudflare 
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini 
  --dns-cloudflare-propagation-seconds 30 
  -d 'example.com' -d '*.example.com' 
  --cert-name wildcard-example.com

# 核对 SAN 是否同时包含裸域与通配符(缺一即是配置事故)
openssl x509 -in /etc/letsencrypt/live/wildcard-example.com/cert.pem 
  -noout -text | grep -A1 'Subject Alternative Name'

# 手工验证 TXT 是否已生效(CNAME 委派到 acme-dns 时同样查这个名字)
dig +short TXT _acme-challenge.example.com @8.8.8.8

续期复杂度决定人力成本。Let’s Encrypt 证书有效期 90 天,官方建议剩余 30 天时续期;certbot 安装的 certbot.timer 默认每天触发两次并带随机延迟,可用 systemctl list-timers certbot.timer 确认下次运行时间。商业 DV/OV 通配符通常 1 年期,必须在到期前 30 天重签、重新部署并 reload Nginx/Apache/HAProxy,这条人工流程要写进变更单——这也是”通配符证书怎么配置”里最常被低估的一环。

场景建议:内部多子域测试环境,Let’s Encrypt 通配符足够,成本为零;对外品牌站且页面需展示企业信息,用 OV 通配符;当子域分散在多个二级域、总数固定且不多时,一张多域名 SAN 证书只需一次部署,运维成本通常低于同时维护多张通配符。

配置通配符证书时最常见的 6 个报错怎么排查?

先给结论:这 6 个报错里有 3 个改 Nginx/Apache 配置根本救不回来,必须先重新签发证书或转换文件格式。下面按“报错原文 → 一条命令确认根因 → 修复动作”的顺序拆,命令都可以直接复制。

1. curl: (60) SSL: no alternative certificate subject name matches target host name 'a.b.example.com'

通配符只覆盖最左侧的一个标签。按 RFC 6125 §6.4.3 与 CA/Browser Forum 基线要求,*.example.com 匹配 a.example.com,但不匹配 a.b.example.com。这是签发范围问题,通配符证书怎么配置都绕不过去。先确认证书里到底有什么:

# 查看 SAN 列表,确认是否真的不含二级子域
openssl x509 -in /etc/nginx/ssl/fullchain.pem -noout -ext subjectAltName
# 期望输出形如:DNS:*.example.com, DNS:example.com
# 若目标是 a.b.example.com,则需要 DNS:*.b.example.com 或该具体域名

修复只有两条路:为 *.b.example.com 单独签发(据 Let’s Encrypt 文档,通配符证书必须走 DNS-01 验证,HTTP-01 不支持),或把该域名加进 SAN 重新签发。

2. nginx: [emerg] cannot load certificate "/etc/nginx/ssl/fullchain.pem": PEM_read_bio_X509_AUX() failed

OpenSSL 只认 PEM。拿到 .cer/.p7b 时,先用 file 判断,再转换:

# DER 转 PEM
openssl x509 -in cert.cer -inform DER -out fullchain.pem
# PKCS#7 转 PEM(.p7b,含中间证书)
openssl pkcs7 -in cert.p7b -inform DER -print_certs -out fullchain.pem
# 首行带 UTF-8 BOM 的,直接剥掉(Windows 记事本另存常见)
sed -i '1s/^xEFxBBxBF//' fullchain.pem
# 验证:必须看到 -----BEGIN CERTIFICATE-----
head -n 1 fullchain.pem

3. PEM_read_bio_PrivateKey() failed (SSL: error:...:bad decrypt)

私钥带口令。Nginx 到 1.26 稳定版仍不支持启动时交互输入密码,只有两个选择:

# 方案 A:去掉口令(注意:会生成明文私钥,务必 chmod 600)
openssl pkey -in enc.key -out dec.key
# 方案 B:保留加密私钥,用密码文件(权限必须 600,否则 Nginx 拒绝加载)
echo 'your-passphrase' > /etc/nginx/ssl/pass.txt
chmod 600 /etc/nginx/ssl/pass.txt
# nginx.conf 的 http{} 或 server{} 中:
# ssl_password_file /etc/nginx/ssl/pass.txt;

4. 客户端报 unable to verify the first certificate(Node.js 18、Java 17 常见)

服务端只发了叶子证书,没发中间证书。Java 17 与 Node 18 的默认信任库不会自动补齐链路:

# 统计服务端实际下发的证书张数,输出 1 即确诊
openssl s_client -connect a.example.com:443 -servername a.example.com 
  -showcerts /dev/null | grep -c "BEGIN CERTIFICATE"
# 修复:按 叶子证书 -> 中间证书 顺序拼接,再 reload
cat cert.pem chain.pem > fullchain.pem
nginx -t && systemctl reload nginx

5. Apache AH02032: Hostname a.example.com provided via SNI and hostname b.example.com provided via HTTP are different

反向代理把 Host 头改成了后端域名,但 TLS 握手里的 SNI 还是前端域名,Apache 2.4.30+ 默认开启 SSLProxyCheckPeerCN 会直接拒绝。要么统一前后端 Host,要么在代理层显式声明:

# Apache httpd.conf / vhost 中
SSLProxyEngine On
SSLProxyCheckPeerName On
SSLProxyCheckPeerCN On
ProxyPreserveHost On          # 保留原始 Host,避免与 SNI 不一致
# Nginx 作为反代时对应写法:
# proxy_ssl_server_name on;
# proxy_ssl_name        backend.internal;

6. NET::ERR_CERT_COMMON_NAME_INVALID 与 ERR_SSL_VERSION_OR_CIPHER_MISMATCH

前者是 SAN 不含该域名——Chrome 119 起已彻底不再回退比对 CN 字段,只认 SAN;后者通常是只开了 TLSv1.3,或只挂了 ECC 证书而客户端过旧(如 Java 7、Android 5)。按 Mozilla SSL Configuration Generator 的 intermediate 配置补齐:

ssl_protocols TLSv1.2 TLSv1.3;   # 只写 TLSv1.3 会打挂老客户端
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;

把 6 类报错压缩成一张排查表,遇到问题先查“确认命令”那一列,别急着改配置:

报错关键词 根因 确认命令 能否靠改配置解决
no alternative certificate subject name 二级子域超出通配符覆盖 openssl x509 -noout -ext subjectAltName 否,须重签
PEM_read_bio_X509_AUX() failed DER / PKCS#7 / BOM head -n 1 fullchain.pem 否,须转格式
bad decrypt 私钥带口令 openssl pkey -in k -noout -passin pass:x 是,ssl_password_file
unable to verify the first certificate 缺中间证书 openssl s_client -showcerts 否,须补链
AH02032 SNI 与 Host 头不一致 后端 access log 看 Host 是
COMMON_NAME_INVALID SAN 不含该域名 同上 SAN 检查 否,须重签

补充一个容易忽略的版本事实:ssl_password_file 自 Nginx 1.7.3 引入,默认无值(即不读取密码文件);ssl_protocols 在 1.23.4 之后的默认值已变为 TLSv1.2 TLSv1.3,但老配置文件里残留的 TLSv1 会同时触发合规扫描告警和降级风险,建议顺手清掉。

怎么确认通配符证书真的生效?6 条可复制的验证命令

问:Nginx 执行 nginx -t 和 systemctl reload nginx 都成功,就代表通配符证书已经生效了吗? 不代表。nginx -t 只检查配置语法和证书文件是否可读,它不解析证书内容,也不验证证书链顺序和域名是否匹配。通配符证书怎么配置只是第一步,真正生效需要按“证书文件 → 线上握手 → 客户端信任”三层逐级确认。以下 6 条命令可以直接复制执行,顺序不要打乱。

  1. 检查证书文件本身:SAN、签发者和到期日
    # 适用 OpenSSL 1.0.2+;-ext 需 1.1.0+,老版本改用 openssl x509 -text
    openssl x509 -in /etc/nginx/ssl/fullchain.pem -noout 
      -subject -issuer -dates -ext subjectAltName
    # 期望输出片段:
    #   subject=CN = *.example.com
    #   issuer=C = US, O = Let's Encrypt, CN = R11
    #   notBefore=...  notAfter=Jun  1 12:00:00 2026 GMT
    #   X509v3 Subject Alternative Name:
    #       DNS:*.example.com, DNS:example.com
    

    判据有两条:SAN 中必须同时存在 DNS:*.example.com 与 DNS:example.com;notAfter 与预期到期日一致。据 RFC 6125 §6.4.3,通配符只覆盖最左一级标签——*.example.com 不匹配裸域 example.com,也不匹配 a.b.example.com;而据 CA/Browser Forum Baseline Requirements,现代浏览器只认 SAN,CN 自 Chrome 58 起被忽略。所以“SAN 缺裸域”是通配符证书最常见的隐性故障。

  2. 检查线上握手链长度:应该看到 2 张证书
    # 统计服务端实际下发的证书张数(站点证书 + 中间 CA)
    openssl s_client -connect a.example.com:443 -servername a.example.com 
      -showcerts /dev/null | grep -c "BEGIN CERTIFICATE"
    # 正常输出:2    (只输出 1 即为链缺失)
    

    输出 1 说明 Nginx 的 ssl_certificate 指向了只含站点证书的 cert.pem;应改为 fullchain.pem(站点证书 + 中间 CA)。注意 -servername 不能省,否则 SNI 虚拟主机可能返回默认站点证书。

  3. 检查域名匹配:-checkhost 是权威判断
    # -checkhost 需 OpenSSL 1.1.0+;CentOS 7 自带 1.0.2 不支持,先 openssl version 确认
    echo | openssl s_client -connect a.example.com:443 -servername a.example.com 2>/dev/null 
      | openssl x509 -noout -checkhost a.example.com
    # 通过:Hostname a.example.com does match certificate
    # 失败:Hostname a.example.com does NOT match certificate
    

    把 a.example.com 换成裸域 example.com 再跑一次,可验证第 1 条中提到的裸域覆盖问题。

  4. 检查链完整性:verify 通过才算中间证书顺序正确
    # Debian/Ubuntu 根证书库为 /etc/ssl/certs/ca-certificates.crt
    # RHEL/CentOS 请改为 /etc/pki/tls/certs/ca-bundle.crt
    openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt 
      -untrusted /etc/nginx/ssl/chain.pem /etc/nginx/ssl/fullchain.pem
    # 期望输出:fullchain.pem: OK
    

    -untrusted 传入的是中间 CA(chain.pem,不含站点证书),它和 fullchain.pem 的分工不能混。为什么必须单独验证?因为顺序颠倒(中间 CA 在前、站点证书在后)时浏览器仍可能成功,但 Java、部分 Android 老版本和 Python requests 会直接失败。

  5. 检查客户端真实视角:curl 的 subject、issuer、expire date
    curl -vI https://a.example.com 2>&1 | 
      grep -E "subject:|issuer:|expire date:|SSL certificate verify"
    # 期望包含:SSL certificate verify ok.
    # 且 expire date 与第 1 条 notAfter 一致
    

    如果输出里出现 SSL certificate verify result: unable to get local issuer certificate (20),说明链缺失,需要回到第 2、4 条检查。

  6. 检查外部审计与 CT 透明度日志
    # SSL Labs 评级,需等待扫描完成(同一 IP 有速率限制,勿循环调用)
    curl -s "https://api.ssllabs.com/api/v3/analyze?host=a.example.com&all=done" 
      | jq -r '.status, .endpoints[0].grade'
    # 再用 crt.sh 核对这张证书是否已进入 CT 日志
    curl -s "https://crt.sh/?q=%25.example.com&output=json" | jq '.[0].not_after'
    

    %25 是 % 的 URL 编码,即查询 %.example.com。CT 日志中的 not_after 应与本地 notAfter 吻合;不一致说明线上仍在用旧证书,常见于 reload 未生效或多台后端只更新了一台。

# 验证维度 通过判据 失败典型信号
1 文件内容 / SAN 含 *.example.com 与 example.com 仅 *.example.com,裸域访问报错
2 线上链长度 输出 2 输出 1;verify error:num=21
3 域名匹配 does match certificate does NOT match certificate
4 链完整性 / 顺序 fullchain.pem: OK num=20: unable to get local issuer certificate
5 客户端信任 SSL certificate verify ok. curl: (60) no alternative certificate subject name matches
6 外部评级 / CT grade ≥ A,CT 记录日期一致 grade 为 T/M;CT 记录仍是旧到期日

真实报错对照:unable to verify the first certificate → 第 2 条,缺中间 CA;unable to get local issuer certificate → 第 4 条,根库路径不对或链断裂;Hostname ... does NOT match certificate → 第 1 条,SAN 不含目标域名。另据 Let’s Encrypt 官方公告,自 2024 年 6 月起默认链不再携带 DST Root CA X3 交叉签名,因此 Android 7.1 以下等老终端会验证失败——这属于第 5 条能暴露、第 4 条无法暴露的客户端侧问题,需要在通配符证书怎么配置的部署清单里单列一项。

续期后证书不生效?通配符证书的自动化更新与 reload 机制

先说结论:绝大多数「续期成功但浏览器还是旧证书」,不是 CA 的问题,而是钩子没跑或进程没 reload。按下面三步自查即可定位。

certbot 到底什么时候跑?为什么我看不到它执行?

systemctl list-timers | grep certbot
# NEXT                         LEFT      LAST                         PASSED   UNIT
# Mon 2025-03-10 03:41:07 UTC  6h left   Sun 2025-03-09 15:33:52 UTC  8h ago   certbot.timer

systemctl cat certbot.timer | grep -E 'OnCalendar|RandomizedDelaySec'
# OnCalendar=*-*-* 00/12:00:00
# RandomizedDelaySec=12h      <-- 2.9+ 的随机延迟,触发点不固定

据 Let’s Encrypt 文档,通配符证书有效期 90 天,官方建议剩余 30 天时续期。certbot 2.x 用 --renew-before-expiry(默认 30 天,写在 /etc/letsencrypt/renewal/*.conf 的 renew_before_expiry 中)判定,所以「每天跑两次」只是检查,不代表每次都真续。

手动加 TXT 记录的 DNS-01 为什么永远续不上? 因为验证需要你人工介入,certbot 无法在无人值守时完成。必须换成 DNS 插件,让 API 代写 TXT:

apt install python3-certbot-dns-cloudflare        # 插件与 certbot 主版本需匹配
install -m 600 /dev/null /root/.secrets/cf.ini    # 先建空文件并限权
cat > /root/.secrets/cf.ini <<'EOF'
dns_cloudflare_api_token = YOUR_TOKEN_HERE
EOF
chmod 600 /root/.secrets/cf.ini

# -d "*.example.com" 的引号不能省,否则 shell 会先做通配展开
certbot certonly --dns-cloudflare 
  --dns-cloudflare-credentials /root/.secrets/cf.ini 
  --dns-cloudflare-propagation-seconds 30 
  -d "*.example.com" -d example.com

--dns-cloudflare-propagation-seconds 默认 10 秒;Cloudflare 官方建议 30 秒,TXT 传播慢时续期会报 Incorrect TXT record found 或 Timeout during connect。

为什么续期日志显示成功,服务却没加载新证书? 因为 --renew-hook 在 certbot 2.x 已合并进 --deploy-hook,旧脚本里残留的 --renew-hook 会被忽略(日志里只有一行 deprecated 提示,不中断执行)。这就是最典型的「续了但没生效」。

选项 触发时机 certbot 2.x 状态 建议
--deploy-hook 首次签发成功 + 每次成功续期 有效 放 reload 命令,首选
--renew-hook 仅续期 已废弃、被忽略 迁移到 deploy-hook
--post-hook 每次运行结束(无论是否续期) 有效 会重复 reload,不推荐
grep -rE 'renew_hook|deploy_hook' /etc/letsencrypt/renewal/
# 有 renew_hook 的行就说明脚本没迁移

certbot renew --dry-run --deploy-hook "nginx -t && nginx -s reload"

reload 之后所有连接都用新证书了吗?不是。 nginx -s reload 只是让新 worker 加载新证书,旧 worker 会处理完存量连接才退出,受 worker_shutdown_timeout 控制,默认 240s(nginx 1.11.11 起)。切换窗口内抓包会看到两套证书,WebSocket、gRPC streaming 尤其明显。Apache 用 apachectl -k graceful;HAProxy 2.5+ 支持运行时热替换,无需 reload:

# HAProxy 2.5+:通过 runtime API 替换证书,不中断现有连接
{ printf 'set ssl cert /etc/haproxy/certs/example.com.pem <<n'
  cat fullchain.pem privkey.pem
  printf 'ncommit ssl cert /etc/haproxy/certs/example.com.pemn'
} | socat stdio /var/run/haproxy/admin.sock

# 验证线上实际下发的证书
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -subject -dates

商业证书重签后文件名带日期,每次都要改配置? 用固定软链,配置只引用软链路径,重签后只需换链接目标再 reload(nginx 只在启动/reload 时读文件):

cd /etc/nginx/ssl/example.com
ln -sfn example_2025_fullchain.crt fullchain.pem
ln -sfn example_2025.key          privkey.pem
nginx -t && nginx -s reload

怎么在到期前提前发现? 本地查:

openssl x509 -enddate -noout -in /etc/nginx/ssl/example.com/fullchain.pem
# notAfter=Jun  8 12:00:00 2025 GMT

黑盒监控用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry(秒级 Unix 时间戳),告警阈值建议 21 天,早于 CA 的 30 天重签窗口,留出人工介入余量:

- alert: SSLCertExpiringSoon
  expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
  for: 1h
  labels: { severity: warning }

通配符证书的安全加固:私钥、HSTS 与 OCSP 怎么配才不留坑

私钥 chmod 600 + chown root:root 之后,Nginx 的 worker 明明以 nginx 用户跑,为什么还能读到 key?

因为 Nginx 是”master 以 root 打开、worker 继承 fd”的模型:master 进程在解析配置阶段就以 root 身份 open() 了证书与私钥,拿到文件描述符后 fork() 出 worker 并 setuid(nginx) 降权,worker 用的是已打开的 fd 而不是重新读路径,所以权限检查发生在降权之前。反过来说,如果 master 本身就以非 root 启动(容器里常见的 nginx 用户直接跑、或 user nginx; + 非 root entrypoint),文件必须对该用户可读,否则启动即失败,报 cannot load certificate key ... Permission denied。据 Nginx 官方文档 Beginner’s Guide 与 ngx_process_cycle.c 的实现,这个”打开—降权”顺序是固定行为,不是配置项。

master 启动身份 key 属主:组 权限 结果
root(默认) root:root 600 ✅ 推荐;worker 降权后仍可读
root nginx:nginx 600 ⚠️ 可用,但任何能读该属主文件的进程都可窃取
nginx(容器/非 root) root:root 600 ❌ 启动失败,13: Permission denied
nginx nginx:nginx 600 ✅ 非 root master 的唯一可行解
# 通配符证书落地后的标准权限设置(Nginx / Apache / HAProxy 通用)
chown root:root /etc/nginx/ssl/*.key /etc/nginx/ssl/*.pem
chmod 600 /etc/nginx/ssl/*.key          # 私钥仅属主可读写
chmod 644 /etc/nginx/ssl/*.crt /etc/nginx/ssl/*.chain.pem  # 证书链可公开

# 容器内 master 非 root 时的替代写法(Dockerfile / k8s initContainer)
chown -R 101:101 /etc/nginx/ssl         # 101 通常是镜像内 nginx 用户 UID
chmod 640 /etc/nginx/ssl/*.key

RHEL 9 / CentOS Stream 9 上权限明明对了,还是 13: Permission denied?

先看 /var/log/nginx/error.log 是否出现 SSL_CTX_use_PrivateKey_file() failed (SSL: error:8000000D:system library::Permission denied)——这类报错在 SELinux enforcing 下与 DAC 权限无关。RHEL 9 默认 enforcing,自定义目录 /etc/nginx/ssl 没有 httpd_t 可读的上下文标签,需要显式打标:

# 1) 确认当前模式与标签
getenforce                              # 期望 Enforcing
ls -Z /etc/nginx/ssl/wildcard.example.com.key
# 未打标时形如:unconfined_u:object_r:etc_t:s0

# 2) 持久化 fcontext 规则(-a 追加,重启不丢)
semanage fcontext -a -t httpd_sys_content_t "/etc/nginx/ssl(/.*)?"
restorecon -Rv /etc/nginx/ssl           # 立即应用,-v 打印变更

# 3) 若仍失败,查 AVC 拒绝记录
ausearch -m avc -ts recent | audit2why

Apache httpd 同理(httpd 在 RHEL 上默认已能读 /etc/pki/tls/private,把 key 放那里可免打标)。

HSTS 加 includeSubDomains 会不会把自己锁死?

会。据 RFC 6797,HSTS 策略在浏览器侧缓存 max-age 秒,期间 includeSubDomains 会让全部一级子域的 http:// 请求在本地被改写为 https://;通配符证书恰好覆盖这些子域,一旦某个子域还没上 TLS,用户会直接看到证书错误且无法点”继续访问”。灰度顺序是先用 300 秒观察一周:

# Nginx:always 保证 4xx/5xx 响应也带此头;注意 add_header 在 location 内会覆盖 server 级
add_header Strict-Transport-Security "max-age=300; includeSubDomains" always;
# 验证一周无异常后改为:max-age=31536000; includeSubDomains
# 如需提交预加载列表,追加 preload(不可逆,需先满足 max-age>=31536000 且含 includeSubDomains)

协议与套件照哪个标准配?按 Mozilla SSL Configuration Generator v5.7 的 Intermediate 档,它兼容 TLS 1.2 客户端且不含已知弱套件;TLS 1.0/1.1 已被 RFC 8996(2021 年 3 月)正式弃用,不应再出现在 ssl_protocols 中。

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;   # TLS 1.3 时代交由客户端选,避免移动端劣化
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;         # 关闭 ticket 便于轮换密钥时彻底前向安全

通配符私钥泄露了,影响面与处置顺序是什么?影响面是证书覆盖的全部一级子域(*.example.com 不覆盖 a.b.example.com,这点常被误判)。处置按顺序:① CA 控制台吊销旧证书并重签(Let’s Encrypt 的 certbot revoke --cert-path ... --reason keycompromise,吊销后可通过 --force-renewal 重签);② 用 crt.sh 查询 %.example.com 是否存在未授权的 CT 日志签发记录;③ 轮换 DNS API 凭据与 ACME 账号密钥(ACME 的 DNS-01 挑战凭据泄露等同于可任意签发);④ 全量日志回溯私钥被读取的时间窗。

OCSP 与 Must-Staple 值不值得开?开 stapling 能省掉客户端回源查询 OCSP 的延迟与隐私泄露,但配置不全时部分客户端(尤其 Firefox 的硬失败策略)会直接拒绝连接。最小可用配置需要 resolver 与 ssl_trusted_certificate,缺一不可:

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/fullchain.pem;  # 必须是含根与中间证书的完整链
resolver 1.1.1.1 8.8.8.8 valid=300s;                   # 无 resolver 时 stapling 静默失效
resolver_timeout 5s;

# 可选 Must-Staple:签发时在 CSR 追加 status_request 扩展(RFC 7633)
openssl req -new -key wildcard.key -addext "tlsfeature=status_request" -out wildcard.csr
openssl req -in wildcard.csr -text -noout | grep -A1 "TLS Feature"  # 应显示 status_request

据 Let’s Encrypt 文档,其 OCSP 响应有效期约 4 天且已宣布逐步缩减 OCSP 服务,把 Must-Staple 绑死在通配符证书上属于高风险耦合——生产环境务必先在灰度子域观察 72 小时,确认 openssl s_client -connect gray.example.com:443 -status 稳定返回 OCSP Response Status: successful 再全量。

不能。按 RFC 6125,*.example.com 只替代最左侧一个标签,a.b.example.com 需要单独签发 *.b.example.com,或把该完整域名加入 SAN。若二级子域数量较多,建议按业务域拆成多张通配符证书统一管理。

默认不包含。多数 CA 允许申请时把 example.com 一并写入 SAN,用 certbot 时加 -d example.com 即可。部署后用 openssl x509 -noout -ext subjectAltName 确认,否则裸域访问会报证书名称不匹配。

Let's Encrypt 通配符 90 天有效、只能 DNS-01 验证、无赔付与人工支持,适合内部系统与成本敏感站点;商业 DV 通配符约 300-800 元/年、OV 通配符约 2000-6000 元/年,提供 1 年期与企业信息展示,适合对外品牌站。两者在浏览器加密强度上没有差别。

证书文件不是 PEM 格式或内容损坏,常见于把 .cer、.pfx 直接改后缀。用 openssl x509 -in file -inform DER -out fullchain.pem 转换,或执行 file fullchain.pem 确认输出为 PEM certificate;若首行有 BOM 也要去掉。

不需要。一张 *.example.com 可在同一 Nginx 的多个 server 块中复用同一对 fullchain.pem / privkey.pem,由 SNI 区分虚拟主机。只有跨到 *.b.example.com 这类二级域,或子域位于其他顶级域时,才需要额外证书。

文件被覆盖但进程未 reload,master 仍持有旧证书。执行 nginx -t && nginx -s reload,并检查 certbot 的 –deploy-hook 是否真的写入 /etc/letsencrypt/renewal/*.conf;再用 openssl s_client -connect a.example.com:443 -servername a.example.com 2>/dev/null | openssl x509 -noout -dates 对比线上到期时间与文件是否一致。

不能。据 CA/Browser Forum 的 EV Guidelines,EV 证书不允许使用通配符,需要 EV 的站点只能为主域逐个签发。因此通配符证书最高只能到 OV 级别,这也是很多企业主域用 EV、子域用通配符 OV 的原因。


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

内容审核

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