通配符证书怎么配置?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、进程重载五层中某一层没对齐。先看清这五层,再谈通配符证书怎么配置,能省掉大半返工。
- 通配符只顶一个标签,且不含裸域。据 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
- 证书链缺失:只发了叶子证书。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"
- 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;
}
- 客户端不发 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
- 文件已更新,进程没重载。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–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 对通配符匹配有明确约束)。 - 步骤 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)可减小握手体积,但要确认客户端兼容性。 - 步骤 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)。 - 步骤 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已按此顺序排好,可直接使用。 - 步骤 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 / 连接重置 启动失败,服务直接不可用 改监听端口、加载新模块 - 步骤 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 条命令可以直接复制执行,顺序不要打乱。
- 检查证书文件本身: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 张证书
# 统计服务端实际下发的证书张数(站点证书 + 中间 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 虚拟主机可能返回默认站点证书。 - 检查域名匹配:-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 条中提到的裸域覆盖问题。 - 检查链完整性: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 老版本和 Pythonrequests会直接失败。 - 检查客户端真实视角: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 条检查。 - 检查外部审计与 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。