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

nginx 部署通配符证书:从 CSR 到 reload 的完整实操与排错

nginx 部署通配符证书 — nginx 部署通配符证书:从 CSR 到 reload 的完整实操与排错
核心结论

nginx 部署通配符证书的核心只有三步:拿到含 SAN 的 fullchain 证书链、在 443 server 块用 ssl_certificate 指向 fullchain、nginx -t 通过后 nginx -s reload;但 *.example.com 不覆盖 example.com 裸域和 a.b.example.com 二级子域,这是 90% 的「装了还是报错」根因。 生成 CSR 必须带 SAN:openssl req -new -newkey rsa:2048 -sha256 -nodes -addext "subjectAltName=DNS:*.example.com,DNS:example.com",OpenSSL 需 ≥1.1.1(推荐 3.0.x/3.2.x),仅写 CN 在 Chrome 58+ 已不被采信。 Let's Encrypt 泛域名只能用 DNS-01 验证:certbot certonly --manual --preferred-challenges dns -d "*.example.com" -d example.com,或用 acme.sh --dns dns_cf 做 API 自动续期,默认 60 天触发续期。 证书链要按「叶子证书在前、中间证书在后」合并:cat wildcard.crt intermediate.crt > fullchain.pem,nginx 的 ssl_certificate 指向 fullchain.pem,ssl_certificate_key 指向私钥,顺序反了 Android 7 与 Java 客户端会报 unable to get local issuer certificate。 改完配置用 openssl s_client -connect 127.0.0.1:443 -servername api.example.com 验证返回的 SAN 与有效期,再配合 curl --resolve 做真实域名回源测试,最后接 blackbox_exporter 的 probe_ssl_earliest_cert_expiry 做到期告警。

为什么 nginx 装了通配符证书,子域还是报证书错误?

这是 nginx 部署通配符证书之后最常见的求助场景,先不要急着重新签发,而要按“证书覆盖了哪些名字、nginx 选中了哪个 server 块、证书链和私钥是否完整”这三层来排查。

通配符到底能匹配几层?据 RFC 6125 第 6.4.3 节以及 CA/Browser Forum 基线要求(Baseline Requirements §3.2.2.6),* 只替换一个标签层级,并且不能匹配裸域。因此,*.example.com 覆盖 api.example.com,但不覆盖 example.com,也不覆盖 a.b.example.com。多层子域只能另行签发证书,或者在 SAN 中补充条目。

浏览器访问的地址 证书 SAN 为 DNS:*.example.com 原因
api.example.com ✅ 匹配 单层子域被通配符替换
example.com ❌ NET::ERR_CERT_COMMON_NAME_INVALID 通配符不含裸域
a.b.example.com ❌ 同上 通配符不跨层级

裸域缺失是最常见的根因。签发时若只填了 *.example.com,访问 https://example.com 必然报错。正确做法是在 CSR 的 SAN 中同时写入两个名字,例如在 openssl.cnf 中设置 subjectAltName = DNS:*.example.com,DNS:example.com;或者在 nginx 层把裸域 301 到 www,前提是 www.example.com 确实在证书内。据 Let’s Encrypt 文档,同一张证书的 SAN 最多可放 100 个名字,所以直接加进去更省事。

证书链不完整:桌面浏览器正常,手机却报错。CA 下发的压缩包通常包含 wildcard.crt、intermediate.crt、ca_bundle.crt。若 ssl_certificate 只指向叶子证书,Chrome 或 Firefox 会靠 AIA 自动补链,而 Android 7 以下、部分 Java 8 客户端、老版 curl 则会报 unable to get local issuer certificate。nginx 官方文档明确要求该指令指向“包含中间证书的完整链”。

# 拼接完整链:叶子证书在前,中间证书在后,顺序不可颠倒
cat /etc/nginx/ssl/wildcard.crt /etc/nginx/ssl/intermediate.crt > /etc/nginx/ssl/fullchain.crt

# nginx.conf 片段(ssl_certificate 无默认值,必填)
server {
    listen 443 ssl;
    server_name example.com *.example.com;   # 裸域与通配同时列出,避免落到 default_server
    ssl_certificate     /etc/nginx/ssl/fullchain.crt;  # 必须是完整链
    ssl_certificate_key /etc/nginx/ssl/wildcard.key;
}

server_name 没写全,SNI 就落到默认站点。nginx 的选择顺序是:精确匹配优先于前缀通配,前缀通配优先于后缀通配,后缀通配优先于正则,正则优先于 default_server。新子域若没有对应的 server_name,返回的就是默认站点的证书,浏览器因此报域名不匹配。

私钥读不到或与证书不配对。master 进程以 root 读取私钥,worker 以 nginx 或 www-data 运行,chmod 600 + chown root:root 即可。CentOS/RHEL 上把证书放到非标准目录却没执行 restorecon,会报 open() ... failed (13: Permission denied)。配错文件则报 SSL_CTX_use_PrivateKey ... key values mismatch。

# 一条命令核对 SAN、链完整性与私钥配对
openssl x509 -in /etc/nginx/ssl/fullchain.crt -noout -subject -issuer -ext subjectAltName
openssl verify -untrusted /etc/nginx/ssl/intermediate.crt /etc/nginx/ssl/wildcard.crt
openssl x509 -noout -modulus -in /etc/nginx/ssl/wildcard.crt | openssl md5
openssl rsa  -noout -modulus -in /etc/nginx/ssl/wildcard.key | openssl md5   # 两行 md5 必须一致
nginx -t && nginx -s reload

“配置写了不生效”多半是版本问题。同一个 server 内多次写 ssl_certificate(RSA + ECDSA 双证书)从 nginx 1.11.0 起才支持;http2 on; 作为独立指令从 1.25.1 起才有,老写法 listen 443 ssl http2; 在 1.25.1+ 会输出 deprecated 警告。生产环境建议用 1.26.x 或 1.28.x 稳定分支。

能力 / 指令 起始版本 默认值与注意事项
ssl_certificate 可重复出现 1.11.0 无默认值,必填;用于 RSA + ECDSA 双证书
http2 on; 1.25.1 默认 off;旧 listen 写法产生 deprecated 警告
ssl_protocols 1.23.4 起 默认 TLSv1.2 TLSv1.3,旧版默认含 TLSv1/1.1

nginx 部署通配符证书的完整 7 步实操流程

先把结论摆前面:nginx 部署通配符证书翻车,90% 不是证书本身有问题,而是编译版本不匹配、证书链顺序错了、私钥权限或 SELinux 上下文不对。下面这 7 步按真实排错顺序排列,每一步都附可复制的命令和”通过标准”。

第 1 步 · 确认 nginx 与 OpenSSL 版本

先别急着生成 CSR,版本不对后面全白干。nginx 1.25.1 起才支持独立的 http2 on; 指令(旧的 listen 443 ssl http2; 写法在 1.25.1+ 已标记废弃);内置 OpenSSL ≥ 1.1.1 才支持 TLS 1.3 与 -addext 参数。

# 查看编译参数与链接的 OpenSSL 版本
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|openssl'
# 典型输出:
#   nginx/1.27.2
#   built with OpenSSL 3.0.13 30 Jan 2024
#   running with OpenSSL 3.0.13 30 Jan 2024   <-- 动态链接时才会出现,以这行为准

openssl version
# OpenSSL 3.0.13 30 Jan 2024   (3.0.x / 3.2.x / 3.5.x 为 LTS 分支,长期维护)

第 2 步 · 生成私钥与带 SAN 的 CSR

据 RFC 6125 与 CA/Browser Forum 基线要求,现代浏览器只认 SAN 扩展,CN=*.example.com 已不作为匹配依据——所以 -addext 里必须同时写泛域名和裸域名。

# RSA 2048 + SHA-256,SAN 同时覆盖 *.example.com 和 example.com
openssl req -new -newkey rsa:2048 -sha256 -nodes 
  -keyout wildcard.example.com.key 
  -out wildcard.example.com.csr 
  -subj "/CN=*.example.com" 
  -addext "subjectAltName=DNS:*.example.com,DNS:example.com"

# ECC 版:P-256 曲线,私钥体积约为 RSA 的 1/8,握手省去一次大数运算
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -sha256 -nodes 
  -keyout wildcard.example.com.key -out wildcard.example.com.csr 
  -subj "/CN=*.example.com" 
  -addext "subjectAltName=DNS:*.example.com,DNS:example.com"

# 自检 SAN 是否真的写进去了(漏了这一步是 CSR 被打回的头号原因)
openssl req -in wildcard.example.com.csr -noout -text | grep -A1 "Subject Alternative Name"

第 3 步 · 选签发通道

注意:据 Let’s Encrypt 文档,泛域名证书只能走 DNS-01 挑战(RFC 8555 定义的三种挑战里,http-01 无法证明通配符归属),这是硬约束,不是配置问题。

通道 泛域名验证方式 出证时间 续期方式 适用场景
商业 CA(DV) DNS TXT / 邮箱 / 文件 10 分钟 – 2 小时 手动或 CA 提供 API 需 OV/EV、有合规审计要求
Let’s Encrypt + certbot 仅 dns-01 1 – 5 分钟 cron/systemd timer + hook 单机、域名少、可接受手动 DNS
Let’s Encrypt + acme.sh dns-01,DNS API 全自动 1 – 2 分钟 内置定时器,自动续期 多域名、多机、无人值守
# certbot 手动 DNS 模式:会打印 _acme-challenge.example.com 的 TXT 值,需手工添加后回车
certbot certonly --manual --preferred-challenges dns -d "*.example.com" -d example.com

# acme.sh + Cloudflare API:签发、续期、部署全自动
export CF_Token="你的Cloudflare_API_Token"
acme.sh --issue --dns dns_cf -d "*.example.com" -d example.com

第 4 步 · 合并并校验证书链

顺序必须是”站点证书 → 中间证书”,根证书不要放(客户端自己持有)。顺序颠倒或漏掉中间证书,浏览器会报 NET::ERR_CERT_AUTHORITY_INVALID。

# 合并出 fullchain.pem
cat wildcard.crt intermediate.crt > fullchain.pem

# 校验:-untrusted 传入中间证书,输出 "wildcard.crt: OK" 才算链正确
openssl verify -untrusted intermediate.crt wildcard.crt
# wildcard.crt: OK

# 二次确认整条链(含根)
openssl verify -CAfile chain.pem fullchain.pem

若输出 error 21 at 0 depth lookup: unable to verify the first certificate,说明中间证书缺失或拼反了。

第 5 步 · 落地文件并收紧权限

install -d -m 755 /etc/nginx/ssl
install -m 600 wildcard.example.com.key /etc/nginx/ssl/   # 私钥仅 root 可读
install -m 644 fullchain.pem /etc/nginx/ssl/               # 证书链可公开读
chown root:root /etc/nginx/ssl/*

# RHEL/Rocky/Alma 默认 SELinux enforcing,必须修上下文
restorecon -Rv /etc/nginx/ssl
ls -lZ /etc/nginx/ssl   # 期望 system_u:object_r:httpd_config_t:s0 或 etc_t

只改 chmod 不改上下文,reload 时会直接报:nginx: [emerg] cannot load certificate "/etc/nginx/ssl/fullchain.pem": BIO_new_file() failed (SSL: error:8000000D:system library::Permission denied)——这个报错看着像权限,实际多半是 SELinux。

第 6 步 · 写配置并热加载

# 443 server 块(nginx ≥1.25.1 用独立 http2 指令,Mozilla SSL Configuration Generator 的 intermediate 配置可直接套用)
# server {
#     listen 443 ssl;
#     http2 on;
#     server_name example.com *.example.com;
#     ssl_certificate     /etc/nginx/ssl/fullchain.pem;
#     ssl_certificate_key /etc/nginx/ssl/wildcard.example.com.key;
#     ssl_protocols TLSv1.2 TLSv1.3;
# }

nginx -t
# nginx: configuration file /etc/nginx/nginx.conf test is successful
systemctl reload nginx    # 或 nginx -s reload

reload 由 master 启动新 worker、旧 worker 处理完存量连接后自行退出,不会中断现有 TLS 会话,比 restart 安全得多。验证:openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -dates。

第 7 步 · 配置自动续期与 reload 钩子

# certbot:先演练,确认挑战通路和 deploy-hook 都正常
certbot renew --dry-run --deploy-hook "systemctl reload nginx"

# 正式环境在 /etc/cron.d/certbot 或 systemd timer 里加 hook(-q 静默,仅在续期成功时执行 hook)
# 0 */12 * * * root certbot -q renew --deploy-hook "systemctl reload nginx"

# acme.sh:安装证书时绑定 reload 命令,此后每次续期自动执行
acme.sh --install-cert -d example.com 
  --key-file       /etc/nginx/ssl/wildcard.example.com.key 
  --fullchain-file /etc/nginx/ssl/fullchain.pem 
  --reloadcmd      "systemctl reload nginx"
工具 默认续期阈值 调整参数 定时器
certbot 剩余 30 天 --days 30 systemd timer / /etc/cron.d/certbot
acme.sh 剩余 60 天 --days 60 安装时自动写入 crontab

到这里,一套可自动续期的 nginx 部署通配符证书流程才算闭环:续期只换文件、reload 只换 worker,用户侧零感知。真正需要长期盯的只有两件事——DNS API Token 的有效期,以及 --dry-run 是否仍然通过。

nginx 通配符证书配置示例与关键命令(含参数默认值)

最短能跑通的 443 server 块长什么样?下面这段在 nginx 1.25.1+ 上可直接复制,注释里标了每个指令的默认值和改动点:

# /etc/nginx/conf.d/example.conf
server {
    listen 443 ssl;              # 1.25.1 起 http2 拆成独立指令;旧版写 listen 443 ssl http2;
    http2 on;
    server_name example.com *.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;      # 必须是 叶证书+中间证书 的顺序
    ssl_certificate_key /etc/nginx/ssl/wildcard.example.com.key;

    ssl_protocols TLSv1.2 TLSv1.3;   # 默认值 1.23.4+ 即 TLSv1.2 TLSv1.3,更早版本默认含 TLSv1/1.1
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;  # Mozilla SSL Config Generator 的 intermediate 套件
    ssl_prefer_server_ciphers off;   # 默认 off;TLS 1.3 的套件顺序不受该指令控制

    ssl_session_cache   shared:SSL:10m;  # 默认 none;1MB≈4000 会话,10m≈4 万并发会话
    ssl_session_timeout 1d;              # 默认 5m
    ssl_session_tickets off;             # 默认 on,关闭以保住前向保密(Mozilla 现代配置建议)
}

OCSP stapling 现在还值得开吗?要分情况。nginx 默认 ssl_stapling off、resolver_timeout 30s,开启需要额外的 resolver 与 ssl_trusted_certificate(默认回落到 ssl_certificate 里的证书链):

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;   # 中间证书链,不含叶证书也可
resolver 223.5.5.5 1.1.1.1 valid=300s;
resolver_timeout 5s;

据 Let’s Encrypt 官方公告,其 OCSP 响应服务已于 2025 年分阶段下线,因此 LE 证书即使配上这些指令也拿不到 staple 结果;商业 CA(如 DigiCert、Sectigo)证书仍然受益。证书里没有 OCSP URL 时,nginx 会在 error_log 打出真实报错:[warn] "ssl_stapling" ignored, no OCSP responder URL in the certificate——看到它说明配置没错,只是这张证书不支持。

80 端口怎么跳到 443,HSTS 又该怎么上?

server {
    listen 80;
    server_name example.com *.example.com;
    return 301 https://$host$request_uri;   # 用 $host 而非写死域名,通配符证书覆盖的子域才能一起跳
    # 注意:$host 取请求行/SNI/Host 头,未匹配 server_name 时会落到 default_server,建议显式声明
}
# 在 443 块内:
add_header Strict-Transport-Security "max-age=300; includeSubDomains" always;  # 灰度期
# 确认所有子域都有 HTTPS 后,再改为 max-age=31536000; includeSubDomains(或加 preload)

一张通配符证书能不能管住所有子域?能,但要看你是否需要差异化配置:

方案 配置要点 适用场景 注意
单 server 块通吃 server_name example.com *.example.com;,一套 ssl_certificate 所有子域同一 root / 同一 upstream 通配符只匹配一级,*.example.com 不含 a.b.example.com
多 server 块共用证书 每块重复写 ssl_certificate 与 ssl_certificate_key 不同子域不同 root、不同反代后端 证书路径写错一处就整块 443 起不来
snippet + include include /etc/nginx/snippets/ssl-wildcard.conf; 子域多、需要统一改 TLS 参数 改一处全生效,但 nginx -T 里定位要靠行号

reload 前后用哪几条命令自证配置正确?

nginx -t                                   # 语法 + 证书文件可读性
openssl x509 -in /etc/nginx/ssl/fullchain.pem -noout -subject -dates -ext subjectAltName
# 期望输出 SAN: DNS:*.example.com, DNS:example.com;确认 notAfter 未过期
openssl s_client -connect 127.0.0.1:443 -servername api.example.com /dev/null 
  | openssl x509 -noout -ext subjectAltName   # 验证 SNI 命中的确实是这张通配符证书
nginx -T | grep -n "ssl_certificate"          # 确认最终生效的是哪份配置(含 include 展开)
systemctl reload nginx                        # reload 不中断连接,优于 restart

这里再次提醒:nginx 部署通配符证书时最常见的“配置对了但浏览器报错”,几乎都是 fullchain.pem 只放了叶证书、缺中间证书,用 openssl s_client -connect ... -showcerts 数一下返回的证书条数即可确认。nginx 部署通配符证书的证书路径一旦用 snippet 复用,改证书只需替换文件并 reload。

通配符证书怎么选:Let's Encrypt、商业 DV、多张单域名对比

先问覆盖范围:一张通配符能顶几张单域名?通配符证书(*.example.com)只匹配一级子域,a.b.example.com 不匹配,且不包含裸域 example.com,签发时必须额外加 -d example.com 作为 SAN。选型时把”覆盖范围、验证方式、有效期、自动化成本”四项一起看:

方案 覆盖范围 验证方式 有效期 价格区间(元/年) 适用场景
Let’s Encrypt 泛域名 *.example.com + SAN 裸域 仅 DNS-01 90 天(官方计划缩短至 45 天) 0 有 DNS API、能自动化的团队
商业 DV 通配符 *.example.com(部分含裸域) DNS/文件/邮箱 1–3 年 400–1500 需要固定有效期与售后
商业 OV 通配符 *.example.com 企业资质核验 1–2 年 2000–6000 对外展示组织身份
多张单域名 DV 每个子域一张 HTTP-01 即可 90 天 0(LE) 子域少于 5 个、无 DNS API
多域名 SAN 证书 example.com + example.net 等 混合 1–2 年 800–3000 跨主域、品牌域名多

注:EV 证书按 CA/Browser Forum Baseline Requirements 不支持通配符,只能逐域签发。

子域多了会不会被限流?会。据 Let’s Encrypt Rate Limits 文档,同一注册域名 50 张证书 / 7 天,完全相同的域名集合 5 张 / 7 天,新订单 300 个 / 3 小时。子域超过 20 个时,一张通配符明显比逐张签发省事,也避开限流。撞限流的典型报错是:

Error creating new order :: too many certificates (5) already issued
for this exact set of domains in the last 168 hours

ACME 客户端选 certbot 4.x 还是 acme.sh 3.x?certbot 4.x 插件生态完整(certbot-dns-cloudflare、certbot-dns-aliyun 等),适合 Python 环境与 systemd 体系,--key-type 自 2.0 起默认 ecdsa(secp256r1);acme.sh 3.x 纯 Shell、无依赖,内置阿里云/腾讯云/DNSPod 的 dnsapi,适合精简镜像。两者都必须用 DNS API,manual 模式无法自动续期。

# certbot 4.x(Debian/Ubuntu),Token 只授目标 zone 的 Zone.DNS Edit
apt install -y certbot python3-certbot-dns-cloudflare
install -m 600 /dev/null /etc/letsencrypt/cloudflare.ini
printf 'dns_cloudflare_api_token = %sn' "$CF_TOKEN" > /etc/letsencrypt/cloudflare.ini
certbot certonly --dns-cloudflare 
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini 
  --dns-cloudflare-propagation-seconds 60 
  -d example.com -d '*.example.com' 
  --key-type ecdsa --elliptic-curve secp384r1

# acme.sh 3.x,RAM 子账号仅含 AliyunDNSFullAccess
curl https://get.acme.sh | sh -s email=ops@example.com
export Ali_Key="LTAI5t..."  Ali_Secret="..."
~/.acme.sh/acme.sh --issue --dns dns_ali -d example.com -d '*.example.com' 
  --keylength ec-256 --server letsencrypt   # acme.sh 默认 CA 为 ZeroSSL,需显式指定

权限与私钥怎么收口?TXT 记录 TTL 设 60–600 秒可缩短验证等待;不要用主账号 AK/SK。通配符私钥泄露即等于整域失守,建议独立目录、chmod 600、纳入备份但不进 Git,有条件放 HSM 或云 KMS,nginx 侧用 ssl_certificate_key 指向挂载的临时文件。商业 CA 通常附带 1 万至 100 万美元保修,但保修不等于赔付业务损失,别把它当保险。

nginx 通配符证书部署常见报错与排查对照

报错 BIO_new_file() failed ... No such file or directory,明明文件就在那儿?

这条来自 OpenSSL 的文件打开失败,90% 不是”文件不存在”,而是路径上某一级目录缺少执行位(x),或 SELinux 拒绝了 nginx worker 进程。nginx master 以 root 启动、worker 默认以 nginx/www-data 身份读取证书,/etc/nginx/ssl 若是 700 root:root,master 能读、worker 读不到。逐级排查:

# 1. 逐级打印每一层目录权限,缺 x 的目录会直接导致 ENOENT
namei -l /etc/nginx/ssl/fullchain.pem
# 2. 文件本身的属主与读权限(至少 o+r,且属主为 root)
ls -l /etc/nginx/ssl/
# 3. SELinux 环境(RHEL/CentOS/Rocky 默认 enforcing)检查安全上下文
ls -lZ /etc/nginx/ssl/
# 若上下文不是 etc_t/httpd_cert_t,用 restorecon 修正
restorecon -Rv /etc/nginx/ssl/
# 4. 用 worker 身份实测一次(把 nobody 换成 nginx.conf 中 user 指令的值)
sudo -u nobody cat /etc/nginx/ssl/fullchain.pem > /dev/null && echo OK

报错 PEM_read_bio_X509_AUX() failed ... no start line,证书文件是坏了吗?

不是坏,是格式不对:nginx 只认 Base64 编码的 PEM 文本,不认 DER/PKCS#12/PKCS#7。最常见的坑是把 Windows 导出的 .pfx 直接改后缀为 .pem,或者文件被编辑器加了 UTF-8 BOM、存成 CRLF 换行,导致首行变成 xEFxBBxBF-----BEGIN...。

file fullchain.pem                       # 期望:ASCII text, 而非 "data"
head -1 fullchain.pem | xxd | head -2    # 首字节应为 2d 2d 2d 2d(即 "----"),出现 efbbbf 就是 BOM
head -1 fullchain.pem                    # 必须是 -----BEGIN CERTIFICATE-----
dos2unix fullchain.pem                   # 修 CRLF;BOM 用 sed -i '1s/^xEFxBBxBF//' 去除
# 若源文件是 PFX,正确做法是提取而不是改名(-nodes 表示私钥不加密)
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -nodes -out cert.key

报错 SSL_CTX_use_PrivateKey() failed ... EVP lib,证书和私钥怎么对不上?

两种可能:私钥与证书不配对(换证书时忘了换 key,或证书链拼错),或私钥带密码短语——nginx 在启动阶段无法交互输入口令,直接失败。RSA 与 ECC 的比对方式不同:

# RSA:比较模数哈希,两行输出必须完全一致
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in x.key        | openssl md5
# ECC(或统一写法):导出公钥后 diff,无输出即匹配
openssl x509 -in fullchain.pem -noout -pubkey > cert.pub
openssl pkey -in x.key -pubout > key.pub
diff cert.pub key.pub && echo MATCH
# 私钥若带密码,去掉口令后再 reload(新文件权限务必 600)
openssl pkey -in x.key -out x.key.nopass   # 会提示 Enter pass phrase
chmod 600 x.key.nopass

浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID,或 curl 报 (60) no alternative certificate subject name matches target host name?

现代客户端早已不看 CN 字段。据 RFC 6125 与 RFC 5280,主机名校验只认 SAN 扩展;Chrome 58 起彻底忽略 CN。通配符 *.example.com 仅匹配一级子域,a.b.example.com 和裸域 example.com 都不在其覆盖范围,需要单独签发或写进同一张证书的 SAN 列表。

# 查看证书实际覆盖的域名(OpenSSL 1.1.1+ 支持 -ext)
openssl x509 -in fullchain.pem -noout -ext subjectAltName
# 输出示例:DNS:*.example.com, DNS:example.com
# 直接对目标域名做一次端到端校验,比看配置文件可靠
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -ext subjectAltName

Let’s Encrypt DNS-01 与限流报错怎么处理?

先看速查表,再对号入座:

报错关键字 根因 一条定位命令
Incorrect TXT record "xxx" found at _acme-challenge 旧 TXT 未删或多值并存 dig +short TXT _acme-challenge.example.com @8.8.8.8
urn:ietf:params:acme:error:caa CAA 未授权该 CA dig +short CAA example.com
too many certificates (5) already issued ... 168 hours 重复证书限流(同一域名集 7 天 5 张) certbot certificates
# 限流自救:复用证书名避免产生"新证书",并先干跑
certbot certonly --dns-XXX --cert-name example.com-wildcard 
  -d '*.example.com' -d example.com --dry-run
# 调试期一律走 staging,正式环境限额只有 5 张/周
certbot certonly --server https://acme-staging-v02.api.letsencrypt.org/directory 
  --cert-name example.com-wildcard -d '*.example.com' -d example.com
# 证书就位后先语法检查,再平滑 reload(reload 不会断开现有连接)
nginx -t && nginx -s reload

据 Let’s Encrypt 官方限流文档,exact set of domains 指域名集合完全相同,调整 -d 顺序或增删一个域名都会被视为新集合,这正是 --cert-name 应当固定下来的原因;CAA 记录中需存在 issue "letsencrypt.org" 或 issuewild "letsencrypt.org"(通配符签发依赖后者),否则签发在 CA 侧即被拒绝。

怎么确认 nginx 通配符证书真的生效了?6 种验证方法

证书 reload 成功不等于生效——nginx 可能还在读旧的 .pem,也可能只装了叶子证书没带中间证书。下面 6 层从配置到外部评级逐层收紧,每层失败都对应一个具体环节,比”打开浏览器看看锁”可靠得多。

1. 配置层:nginx 到底加载了哪个文件?

# 语法检查,期望输出:nginx: configuration file /etc/nginx/nginx.conf test is successful
nginx -t

# -T 打印完整合并后的配置(含 include),-n 显示行号,-A2 带出下一行证书路径
nginx -T 2>/dev/null | grep -n -A2 "server_name"

# 只关心证书指令本身,确认指向 fullchain.pem 而非旧的 cert.pem
nginx -T 2>/dev/null | grep -E "ssl_certificate(_key)?s"
# 正确形态:ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
#           ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

据 Let’s Encrypt 文档,fullchain.pem = 叶子证书 + 中间证书,而 cert.pem 只有叶子证书,误用后者会让部分客户端(尤其 Android 与 Java 老版本)报”证书链不完整”。

2. 本机 TLS 层:证书主体和有效期对不对?

# -servername 触发 SNI,必须带,否则可能命中默认 server 块的证书
openssl s_client -connect 127.0.0.1:443 -servername api.example.com /dev/null 
  | openssl x509 -noout -subject -dates -ext subjectAltName
# 期望看到:subject=CN = *.example.com
#          notAfter=... GMT(应为新证书日期)
#          DNS:*.example.com, DNS:example.com

注意通配符边界:按 RFC 6125,*.example.com 只匹配一级子域,api.example.com 命中,a.b.example.com 不命中——多级子域需要单独签发。

3. 链路完整性:中间证书有没有漏?

echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null 
  | grep -c "BEGIN CERTIFICATE"
# 正常 ≥2(叶子 + 中间);输出 1 说明只发了叶子证书

4. 真实域名回源:DNS 还没切也能先验新机

# --resolve 强制把域名指向新服务器 IP,绕过 DNS 缓存
curl -vI https://api.example.com --resolve api.example.com:443:203.0.113.10
# 期望:SSL certificate verify ok.  +  HTTP/2 200

5. 协议与套件:别残留 TLSv1.0/1.1

openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null | grep "Protocol"
openssl s_client -connect example.com:443 -servername example.com -tls1_3 </dev/null | grep "Protocol"

# 枚举套件,确认无 RC4/3DES/CBC 弱套件(nmap 7.x 的 ssl-enum-ciphers 脚本)
nmap --script ssl-enum-ciphers -p 443 example.com

# 或 testssl.sh(3.x)只看 HIGH 及以上严重级别
./testssl.sh --severity HIGH https://example.com

参考 Mozilla SSL Configuration Generator(Intermediate/Modern 档),ssl_protocols 默认值在 nginx 1.23.4 起为 TLSv1.2 TLSv1.3,显式写死比依赖默认值更稳。

6. 外部评级与自动告警

Qualys SSL Labs 目标 A 及以上;A+ 需要 HSTS 且无已知漏洞。人工巡检不可持续,用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry(Unix 时间戳)做提前预警:

# /etc/prometheus/rules/tls.yml
groups:
  - name: tls-expiry
    rules:
      - alert: TLSCertExpiringSoon
        expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21  # 剩余不足 21 天
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "{{ $labels.instance }} 证书剩余 {{ $value | printf "%.1f" }} 天"
验证层 关键命令 通过判据 典型失败信号
配置 nginx -T | grep ssl_certificate 指向 fullchain.pem 仍指向 cert.pem 或旧路径
本机 TLS openssl s_client -servername SAN 含 *.example.com、notAfter 为新日期 CN 与域名不符、日期未变
链路 grep -c "BEGIN CERTIFICATE" ≥2 等于 1,缺中间证书
回源 curl -vI --resolve verify ok + HTTP/2 200 证书验证失败、502/421
协议套件 nmap ssl-enum-ciphers 仅 TLS1.2/1.3 与 AEAD 套件 出现 TLSv1.1、3DES、RC4
评级告警 SSL Labs / blackbox_exporter A 以上,剩余 >21 天 评级 B、告警未触发

续期自动化与长期运维:别让通配符证书在半夜过期

通配符证书部署完只是起点。真正的运维风险在续期:Let’s Encrypt 免费证书 90 天有效期(据 Let’s Encrypt 官方文档 “Challenge Types” 与 “Renewing Certificates”),一旦自动续期链路断了,业务会在某个凌晨静默失败。下面是可直接落地的自动化配置与排错要点。

certbot 4.x 的续期钩子怎么配?不要在命令行临时拼参数,写进 renewal 配置才能持久生效。certbot 4.x 将每个证书的续期参数保存在 /etc/letsencrypt/renewal/*.conf,其中 renew_hook 在续期成功后执行:

# /etc/letsencrypt/renewal/example.com.conf(节选,certbot 4.x)
[renewalparams]
# 续期成功后重载 nginx;不要用 --pre-hook 停 nginx
renew_hook = systemctl reload nginx

# 验证钩子是否被正确读取(不会真正续期)
certbot renew --dry-run --cert-name example.com
# 期望输出包含:Running deploy-hook command: systemctl reload nginx

等价写法是命令行 --deploy-hook "systemctl reload nginx"。注意 --pre-hook 的语义是”续期前执行”,用 systemctl stop nginx 只会制造无谓的停机窗口——reload 本身就是热加载,无需停服。

acme.sh 3.x 怎么绑定 reload?在安装证书时一次性写入 reloadcmd,之后由 cron 自动检查(默认每天约 00:17 触发),剩余天数低于 --days(默认 60)时续期:

acme.sh --install-cert -d example.com -d '*.example.com' 
  --key-file       /etc/nginx/ssl/wildcard.key 
  --fullchain-file /etc/nginx/ssl/fullchain.pem 
  --reloadcmd      "systemctl reload nginx"
# --days 60 为默认续期阈值;有效期缩短后应改为剩余 1/3(45 天证书→15 天触发)
acme.sh --install-cert -d example.com --days 15 --reloadcmd "systemctl reload nginx"
方案 续期钩子位置 默认触发阈值 适用场景
certbot 4.x renewal/*.conf 的 renew_hook 剩余 30 天 单机、systemd 环境
acme.sh 3.x --reloadcmd(写入 account conf) 剩余 60 天(--days) 多 CA、无 root 依赖、容器化

有效期缩短了怎么办?Let’s Encrypt 已公布将证书有效期从 90 天逐步降至 45 天,并试验 6 天短周期证书。续期触发点应按”剩余 1/3″设计而非固定”提前 30 天”,监控告警阈值同步下调到 15 天,否则 45 天证书会在告警前就过期。

reload 后旧 worker 不退出?Nginx 的 worker_shutdown_timeout 默认 4h,长连接会拖住旧 worker:

# /etc/nginx/nginx.conf
worker_shutdown_timeout 30s;   # 默认 4h,缩短到 30s 让旧 worker 尽快退出

# reload 后观察
systemctl reload nginx && sleep 5 && ps -ef | grep nginx
# 数十秒后仍有旧 worker:检查是否有 SSE / WebSocket 长连接

备份与回滚:每次续期前归档旧证书,保留 30 天:

D=$(date +%F); mkdir -p /var/backups/nginx-ssl/$D
cp /etc/nginx/ssl/{fullchain.pem,wildcard.key} /var/backups/nginx-ssl/$D/
# certbot 默认复用原私钥;需换钥时加 --new-key,并同步 CDN 与边缘节点
certbot renew --cert-name example.com --new-key

多节点部署时,先在 1 台灰度机 reload 并用 openssl s_client -connect 127.0.0.1:443 -servername example.com 校验 SAN 与到期日,再批量推送;同时把到期日、签发 CA、SAN 列表写入 CMDB,避免”配置漂移”导致的续期失败。

不能。*.example.com 按 RFC 6125 只匹配一级子域,裸域 example.com 必须单独出现在 SAN 里。签发时在 CSR 中同时写 DNS:*.example.com 和 DNS:example.com,或用 -d "*.example.com" -d example.com 让 Let's Encrypt 一并签发。

不能。通配符只替换最左侧一个标签,a.b.example.com 需要单独签发,或申请 *.*.example.com(多数 CA 不支持),更常见的做法是把多级子域收进一张多域名 SAN 证书。浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID 时先核对 SAN 列表。

这是 ACME 协议(RFC 8555)的硬性规定:通配符订单必须使用 dns-01 挑战,因为 HTTP-01 无法证明申请者对整个域名空间的控制权。因此需要 DNS 服务商 API,certbot 用 –preferred-challenges dns 配合插件,acme.sh 用 –dns dns_cf 之类的 dnsapi。

说明 ssl_certificate_key 指向的私钥与证书不匹配,或私钥带密码短语。RSA 用 openssl x509 -noout -modulus -in fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in wildcard.key | openssl md5 比对,两个值必须一致;ECC 用 openssl pkey -pubout 分别导出后 diff。若私钥有密码,先 openssl pkey -in enc.key -out plain.key 解密。

子域超过 10 个、且有 DNS API 可自动化时,一张通配符明显更省事:续期只跑一次,nginx 只维护一对文件。子域少于 5 个、又不想开放 DNS API 权限时,Let's Encrypt 的单域名证书走 HTTP-01 更简单,无需 DNS 插件,但要注意同一注册域名 50 张 / 7 天的限流。

不需要重启,reload 即可。nginx 的 ssl_certificate 在配置加载时读取,systemctl reload nginx 会让 master 重新解析配置并启动新 worker,旧 worker 处理完存量连接后退出,TLS 会话不中断。只有改了监听端口、编译模块这类参数才需要 restart。

按三层查:先用 openssl s_client -connect 域名:443 -servername 域名 -showcerts 看返回的证书 SAN 是否包含当前域名、证书链是否 ≥2 张;再用 nginx -T | grep ssl_certificate 确认生效配置;最后看 server_name 是否命中该子域,未命中会落到 default_server 返回别的证书。八成问题出在 SAN 缺项或 server_name 未列全。


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

内容审核

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