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

Nginx SSL 配置续期怎么做?Certbot 与 acme.sh 自动续期及 reload 排错指南

nginx ssl 配置续期 — Nginx SSL 配置续期怎么做?Certbot 与 acme.sh 自动续期及 reload 排错指南
核心结论

Nginx 证书续期的核心是:用 ACME 客户端重新签发 90 天有效期的证书,然后让 Nginx 重新加载证书文件。 Certbot 用 `certbot renew --deploy-hook "systemctl reload nginx"`;acme.sh 用 `--reloadcmd`,两者都建议先跑 `--dry-run` 或 staging 测试。 续期后不 reload,Nginx 仍使用内存中的旧证书;验证命令是 `openssl s_client -connect example.com:443 -servername example.com | openssl x509 -noout -dates`。 Let's Encrypt 速率限制:每注册域名每周 50 张证书、重复证书每周 5 张,正常 60 天续期不会触发。 Nginx 1.25.1+ 推荐 `http2 on;` 替代 `listen 443 ssl http2;`,TLS 1.3 从 1.13.0 起支持。

Nginx SSL 配置续期到底在续什么?90 天有效期意味着什么?

问:nginx ssl 配置续期到底在续什么?是改 nginx.conf 吗?

不是。续期不碰 nginx.conf,它做的是三件事:ACME 客户端(Certbot 或 acme.sh)按 RFC 8555 向 CA 重新提交订单并完成 http-01 或 dns-01 验证,CA 签发新证书后写入 /etc/letsencrypt/live/example.com/fullchain.pem(证书链)和 privkey.pem(私钥),这两个路径默认保持不变,最后触发 Nginx reload 重新读取文件。换句话说,nginx ssl 配置续期是”换文件 + 重载进程”,配置文本本身不动。

问:90 天有效期意味着什么?

据 Let’s Encrypt 官方文档,其证书有效期固定为 90 天(这是为了缩短吊销延迟、推动自动化),官方建议每 60 天续期一次。Certbot 2.x 的默认策略是在到期前 30 天开始尝试,并通过 certbot.timer 每天检查两次(带随机延迟,避免 CA 峰值)。可这样确认:

$ systemctl list-timers certbot.timer
NEXT                        LEFT     UNIT           ACTIVATES
Fri 2025-06-20 03:41:00 UTC 9h left  certbot.timer  certbot.service

$ certbot certificates
  Certificate Name: example.com
    Domains: example.com www.example.com
    Expiry Date: 2025-08-14 07:12:33+00:00 (VALID: 61 days)
    Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
    Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem

问:为什么换了证书浏览器还显示旧到期日?

Nginx 只在启动或 reload 时读取证书文件,运行期一直用内存中的副本。只替换文件而不执行 systemctl reload nginx 或 nginx -s reload,客户端看到的仍是旧证书。注意 ssl_certificate 应指向 fullchain.pem 而非 cert.pem,否则中间证书缺失,部分安卓与旧版 Java 客户端会报链不完整——这一点在 Mozilla SSL Configuration Generator 的推荐配置中同样强调。

问:续期失败最常见的原因?

80/443 端口被占用、DNS 解析漂移、防火墙拦截 ACME 验证请求、触发 CA 速率限制(Let’s Encrypt 为每注册域名每周 50 张)、reload hook 权限不足。建议每次续期后做双重校验:

$ nginx -t && systemctl reload nginx
$ echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
    | openssl x509 -noout -subject -dates
notBefore=May 16 07:12:33 2025 GMT
notAfter=Aug 14 07:12:33 2025 GMT

用 Certbot 给 Nginx 做自动续期的完整步骤是什么?

Certbot 是目前 Nginx 上最省心的 ACME 客户端之一,当前主版本为 2.x,走 ACME v2 端点 https://acme-v02.api.letsencrypt.org/directory。安装分两条路线(Certbot 官方文档推荐用系统包管理器安装):

# Ubuntu / Debian(Ubuntu 20.04+、Debian 11+ 均适用)
apt install certbot python3-certbot-nginx

# RHEL / CentOS Stream / Rocky / AlmaLinux 8+
dnf install certbot python3-certbot-nginx

首次签发用 nginx 插件,它会自动改写 server 块并加上 ssl_certificate 指令:

certbot --nginx -d example.com -d www.example.com

# 不想让 Certbot 动你的配置,改用 webroot
certbot certonly --webroot -w /var/www/html -d example.com

签发完先验证续期链路。据 Let’s Encrypt 文档,--dry-run 走 staging 环境,不消耗生产速率限制,能顺带验证 webroot 路径、DNS 与 hook 是否正确:

certbot renew --dry-run
certbot certificates        # 查看已管理证书与到期日

自动续期由 systemd timer 承担(Certbot 1.x 起默认安装 certbot.timer,不再依赖 cron):

systemctl list-timers | grep certbot
# 传统 cron 写法(无 systemd 的环境)
0 3 * * * /usr/bin/certbot renew --quiet --deploy-hook "systemctl reload nginx"

Nginx 侧只需确认证书路径正确,改完必测:

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}

nginx -t && systemctl reload nginx

手动强制续期用 certbot renew --force-renewal,但别频繁跑——Let’s Encrypt 限制为每注册域名每周 50 张证书、重复证书每周 5 张,撞上限会被锁到下周。日志在 /var/log/letsencrypt/letsencrypt.log,若怀疑 timer 没触发,用 journalctl -u certbot 看执行记录,再对照 journalctl -u nginx 确认 reload 是否成功。

acme.sh 怎么给 Nginx 续期?DNS-01 泛域名与 reload 钩子怎么写?

acme.sh 用纯 shell 实现,不依赖 Python,天生支持 DNS API 验证,是泛域名证书最省事的方案。下面按”装—签—装钩子—排错”的顺序走一遍。

1. 安装 acme.sh 3.x 并确认定时任务

curl https://get.acme.sh | sh -s email=admin@example.com
crontab -l | grep acme.sh
# 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null

安装脚本会自动写入这条 crontab,每天 00:00 执行一次续期检查;acme.sh 只在证书剩余有效期少于 30 天(默认 --days 60 阈值的一半以上逻辑)时才真正重新签发,所以不会天天打 ACME 接口。如果你用 systemd 机器且没有 cron,需要自己补一个 timer,否则证书到期不会自动续。

2. 泛域名必须走 DNS-01

HTTP-01 无法验证 *.example.com,泛域名只能用 DNS-01。以 Cloudflare 为例,先导出 API Token(权限只要 Zone:DNS:Edit,别用 Global API Key):

export CF_Token="你的_Zone_DNS_Edit_Token"
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'

签发成功后凭据会持久化到 ~/.acme.sh/account.conf,后续自动续期无需再 export。其他 DNS 商对应 dns_ali、dns_dp、dns_gd 等插件,完整列表见 acme.sh 官方 Wiki 的 dnsapi 目录。

3. 用 –install-cert 把证书落到 Nginx 并 reload

acme.sh 不会改你的 Nginx 配置,它只负责把文件复制到指定路径并在续期后执行 reload 命令——这一点比 Certbot 的 nginx 插件更可控:

acme.sh --install-cert -d example.com 
  --key-file       /etc/nginx/ssl/example.com.key 
  --fullchain-file /etc/nginx/ssl/example.com.crt 
  --reloadcmd      "systemctl reload nginx"

Nginx 侧对应写:

ssl_certificate     /etc/nginx/ssl/example.com.crt;
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols       TLSv1.2 TLSv1.3;

注意 --reloadcmd 必须用 systemctl reload nginx 而不是 restart:reload 会向 master 进程发 SIGHUP,平滑加载新证书且不断开现有连接,这符合 Nginx 官方文档对信号语义的描述。若用 restart,每次续期都会造成瞬断。

4. 换 CA 与查看状态

acme.sh 从 3.0.0 起默认 CA 是 ZeroSSL,想换回 Let’s Encrypt:

acme.sh --set-default-ca --server letsencrypt
acme.sh --list

据 Let’s Encrypt 文档,其 ACME v2 目录地址为 https://acme-v02.api.letsencrypt.org/directory,--list 会列出每张证书的 Renew 时间,可用来核对下次续期窗口。

5. 续期失败怎么排错

  • 日志在 ~/.acme.sh/acme.sh.log,先看这里再谈其他;
  • 手动跑一次 acme.sh --cron --debug,能看到完整的 ACME 请求响应;
  • DNS-01 失败九成是 Token 权限不足或域名不在该 Zone 下,检查是否给到了 Zone:DNS:Edit;
  • reload 失败则检查 systemctl reload nginx 在 root 下是否可直接执行、证书路径是否被 SELinux/AppArmor 限制。

与 Certbot 相比:Certbot 的 nginx 插件会自动改写站点配置文件,省事但可读性差、回滚困难;acme.sh 保持配置文件干净,泛域名支持也更顺,代价是 DNS API 凭据要自己管好。生产环境建议把 account.conf 权限设为 chmod 600。

续期后 Nginx 没生效?按这 6 步排查

这是最典型的”续期成功了但浏览器还在报旧证书”的场景。据 Let’s Encrypt 文档,证书有效期 90 天,Certbot 2.x 与 acme.sh 3.x 都会在到期前 30 天自动续期,但续期只负责写文件,不会替你 reload Nginx。按下面 6 步从磁盘到链路逐层排查。

  1. 第 1 步:文件到底更新了吗?先排除”续期根本没跑成功”。
    ls -l /etc/letsencrypt/live/example.com/
    ls -l /etc/nginx/ssl/

    看 fullchain.pem(或自管的 .crt)时间戳是否是刚才。若还是 90 天前,问题在 ACME 客户端而不在 Nginx,先查 /var/log/letsencrypt/letsencrypt.log 或 ~/.acme.sh/acme.sh.log。

  2. 第 2 步:Nginx 真的 reload 了吗?文件新了但进程没重载,下发仍是旧证书。
    systemctl status nginx
    ps -eo pid,lstart,cmd | grep nginx

    对比 master 进程的启动时间与证书时间戳。master 时间更早,说明没 reload,执行:

    nginx -t && systemctl reload nginx

    reload 走 SIGHUP,不中断连接;nginx -t 失败时 reload 会被拒绝,务必先测。

  3. 第 3 步:线上实际下发的是哪张证书?本地文件对不代表握手时用的就是它。
    echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates -subject

    对比 notAfter 是否前移了 90 天。-servername 不能省,否则拿到的可能是默认 server 的证书。

  4. 第 4 步:有没有别的 server 块覆盖?多个 server_name 相同、或 default_server 抢走了 SNI。
    nginx -T | grep -n ssl_certificate

    nginx -T 会输出合并后的完整配置,逐个确认该域名的 ssl_certificate 路径没有指向旧目录或测试证书。

  5. 第 5 步:OCSP stapling 是否正常?据 RFC 6960,装订的 OCSP 响应本身也有有效期,续期后旧响应会失效。Nginx 侧需要:
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    resolver 8.8.8.8 1.1.1.1 valid=300s;
    openssl s_client -connect example.com:443 -status -servername example.com

    返回 OCSP Response Status: successful 才算生效;出现 no response sent 通常是 resolver 不可达或 chain.pem 路径写错。

  6. 第 6 步:前置 CDN 或负载均衡换证书了吗?如果域名解析到 CDN,源站证书换了终端用户也看不到,需要在 CDN 控制台上传新证书或开启回源 TLS。同时用 timedatectl 确认系统时间准确——时间偏差会导致 OCSP 校验失败和 TLS 握手异常。
    timedatectl

如何验证 Nginx 证书续期成功并做到期监控?

续期到底有没有成功?先看工具自己的账本。Certbot 2.x 会记录每个证书的到期时间,acme.sh v3.x 则记录下一次续期时间。如果这里显示的日期还停留在上次签发时,说明定时任务根本没跑起来,先查 cron / systemd timer,再谈排错。

# Certbot:关注 Expiry Date 是否已刷新(VALID: 89 days 表示刚续期)
certbot certificates

# acme.sh:关注 Renew 一列(下次续期时间),默认到期前 30 天续期
acme.sh --list

不想依赖工具,直接读证书文件行不行?可以,这也是最可靠的一手证据。据 OpenSSL 官方文档,x509 的 -enddate 会打印 notAfter 字段:

openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -enddate
# 输出示例:notAfter=Jun 10 12:00:00 2025 GMT

# 从外部看线上真正在用的那张证书(含 serial,可确认 reload 是否生效)
curl -vI https://example.com 2>&1 | grep -Ei 'subject:|expire date|start date'

Let’s Encrypt 证书有效期 90 天,官方建议在到期前 30 天内完成续期,留出排错窗口。注意:Nginx 只在启动或 reload 时读取证书文件,续期成功但没 reload,浏览器看到的仍是旧证书——用上面的 curl 对比 serial 就能发现。相关配置见 nginx ssl 配置续期的 reload 章节。

生产环境怎么做到期监控?推荐 Prometheus blackbox_exporter,它暴露的 probe_ssl_earliest_cert_expiry 是指标为 Unix 时间戳的剩余到期时刻,配合告警规则即可:

# blackbox_exporter 0.24+ / Prometheus 2.x 告警表达式
(probe_ssl_earliest_cert_expiry - time()) / 86400 < 21   # 提醒
(probe_ssl_earliest_cert_expiry - time()) / 86400 < 14   # 告警

轻量场景可用 UptimeRobot 的 SSL 监控、SSL Labs 定期扫描或 Zabbix 的证书检查项。

续期失败了去哪儿找原因?Certbot 日志在 /var/log/letsencrypt/letsencrypt.log,acme.sh 日志在 ~/.acme.sh/acme.sh.log:

grep -i error /var/log/letsencrypt/letsencrypt.log | tail -20
grep -i error ~/.acme.sh/acme.sh.log | tail -20

常见报错是 80 端口被占用、DNS 记录变更、ACME 速率限制,以及 Nginx 未 reload。

能否用一行命令接入现有监控?可以,openssl 的 -checkend 直接给退出码,适合 Nagios、Zabbix 或自建脚本:

openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -checkend 1209600
# 退出码 0:14 天内不会过期;退出码 1:即将过期,触发告警
# 1209600 秒 = 14 天,改成 2592000 即 30 天阈值

把这条命令和 blackbox_exporter 指标一起接入告警,证书过期这类”低级事故”基本可以彻底消除。

生产可用的 Nginx TLS 配置模板与续期 hook 示例

Q:Mozilla SSL Configuration Generator 的 intermediate 预设怎么落到 Nginx?

据 Mozilla SSL Configuration Generator(v5.7)的 intermediate 方案,兼顾现代浏览器与 TLS 1.2/1.3 的核心三行是:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;

TLS 1.3 自 Nginx 1.13.0 起支持,其密码套件由 RFC 8446 固定、不受 ssl_ciphers 影响;若确实要调整,需 OpenSSL 1.1.1 配合 ssl_conf_command Ciphersuites(Nginx 1.19.4+)。另外 Nginx 1.25.1 起官方推荐用 http2 on; 替代 listen 443 ssl http2;,后者会输出 deprecated 警告。

Q:完整 server 块能直接抄吗?

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    resolver 8.8.8.8 1.1.1.1 valid=300s;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}

OCSP stapling 依赖 resolver,stapling 不生效多半是容器内 DNS 不通。HSTS 的 max-age 下发后难以回退,先在测试域名验证。ssl_early_data 从 1.15.3 起可用,但 0-RTT 存在重放攻击风险(RFC 8470),只建议对幂等 GET 开启。

Q:续期后怎么让 Nginx 加载新证书?

据 Let’s Encrypt 文档,Certbot 的 --deploy-hook 只在证书真正续期成功时执行,旧的 --renew-hook 已弃用;acme.sh 对应 --reloadcmd。两者都应写 systemctl reload nginx 而非 restart,reload 由 master 进程平滑加载新证书,不断开现有连接。

certbot certonly --webroot -w /var/www/html -d example.com 
  --deploy-hook "systemctl reload nginx"

acme.sh --issue -d example.com --webroot /var/www/html 
  --reloadcmd "systemctl reload nginx"

验证顺序:nginx -t → certbot renew --dry-run → systemctl reload nginx → openssl s_client -connect example.com:443 -servername example.com | openssl x509 -noout -dates。

Q:私钥权限和付费证书怎么办?

/etc/letsencrypt/live 与 archive 默认仅 root 可读,Nginx master 进程以 root 启动即可读取,切勿把 privkey.pem 复制到 web 目录,私钥保持 600 权限。付费证书中 DV 约 50–150 美元/年、OV 约 150–300 美元/年、EV 更高,续期需在 CA 控制台重新签发、替换文件后 reload;这套「替换 + reload」的流程与 nginx ssl 配置续期的自动化 hook 本质相同,只是少了 ACME 环节。

先确认 Nginx 是否执行了 reload。`certbot renew` 只负责签发证书,不会自动让 Nginx 重新加载;需要在 hook 里加 `systemctl reload nginx`,或使用 `–deploy-hook`。然后运行 `openssl s_client -connect example.com:443 -servername example.com | openssl x509 -noout -dates` 看 notAfter 是否更新;如果没变,检查是否有 CDN 缓存或另一份 nginx 配置指向旧证书路径。

不需要停机。`nginx -s reload` 会启动新的 worker 进程并优雅关闭旧 worker,现有连接不会中断;`restart` 会短暂停止服务,除非有 keepalived 等冗余。reload 前务必执行 `nginx -t` 校验配置,语法错误会导致新 worker 启动失败,旧进程继续使用旧配置。

正常 60 天续期不会触发。据 Let’s Encrypt 文档,每个注册域名每周最多 50 张证书,重复证书(相同域名集合)每周 5 张,失败验证每小时 5 次。测试时用 `certbot renew –dry-run` 走 staging 环境;如果触发限制,等待一周或提交豁免申请。

泛域名(`*.example.com`)只能用 DNS-01,因为 HTTP-01 无法验证通配符。Certbot 需要 `–manual –preferred-challenges dns` 或 DNS 插件;acme.sh 用 `–dns dns_cf`、`–dns dns_ali` 等 API 实现自动续期。普通单域名可用 HTTP-01 或 TLS-ALPN-01。

通常不需要。Let’s Encrypt 续期会自动生成新密钥或复用密钥,Certbot 默认复用,可用 `–reuse-key` / `–no-reuse-key` 控制。DH 参数用于 DHE 密码套件,现代配置优先 ECDHE,通常不必重新生成;如果仍在用 `ssl_dhparam`,建议 2048 位以上,且不需要随证书续期更换。

Let’s Encrypt 免费证书有效期 90 天,靠 Certbot 或 acme.sh 自动续期;付费 DV/OV 证书通常 1 年,在 CA 控制台手动或通过 API 重新签发,下载后替换 Nginx 文件并 reload。付费证书提供更长有效期、保修和技术支持,DV 约 50–150 美元/年,OV 约 150–300 美元/年。无论哪种,Nginx 侧都是替换 `ssl_certificate` 指向的文件并 reload。

内容审核

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