跳到主要内容
Apache

Certbot 自动申请与续期 Let’s Encrypt 证书实战指南

一、证书为什么总在半夜过期:90 天有效期与自动化根因

Let’s Encrypt 证书有效期固定为 90 天,这是它主动做出的设计选择,而不是 CA/Browser Forum 的上限。按现行规则,公有 CA 签发的单张 TLS 证书最长有效期为 398 天(2020-09-01 起生效),Let’s Encrypt 却把周期压到 90 天,并在近年推出更短的测试 profile,目的就是逼所有站点做自动化。任何“手工申请、到期前再想起来”的流程,在 90 天周期下一年至少重复 4 次,遗漏几乎是必然的。

certbot 本质是一个 ACME v2 客户端:它读取 /etc/letsencrypt/renewal/*.conf 中的续期参数,在证书到期前 30 天进入续期窗口,重新走一遍 challenge 验证,然后替换 live 目录下的软链。/etc/letsencrypt/live/example.com/ 里的 fullchain.pem、privkey.pem 都指向 ../../archive/example.com/ 的历史文件,因此 Nginx 只要 reload 就能加载新证书,配置文件里的路径永远不用改。

续期失败最常见的根因有三类:其一,80 端口被旧 Nginx、Docker 端口映射或 Apache 占用,HTTP-01 验证取不到 /.well-known/acme-challenge/ 下的文件;其二,systemd timer 未启用或主机长期关机,触发时机器不在线;其三,签发后手工改过 Nginx 配置,--nginx 插件回滚时把 server 块改坏。

排查入口只有两条命令,先确认版本与定时器状态:

certbot --version
systemctl list-timers --all | grep -i certbot
ls -l /etc/letsencrypt/live/example.com/

如果 list-timers 输出为空,说明续期链路根本没启动,后面所有“证书突然过期”的告警都能追溯到这一点。

二、安装 Certbot:发行版仓库与 snap 的取舍

Debian/Ubuntu 官方仓库里的 certbot 往往落后一到两个大版本,对新版 ACME 参数、Nginx 新语法解析、ECDSA 默认策略支持不全,因此生产环境建议用 snap 安装官方维护的最新版;内网离线环境则退回 apt/dnf,但要接受功能差异。

# Debian / Ubuntu 仓库安装(版本较旧,够用但不推荐)
apt update
apt install -y certbot python3-certbot-nginx

# 推荐:snap 安装最新版
snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot
certbot --version

# RHEL / Rocky / AlmaLinux
dnf install -y epel-release
dnf install -y certbot python3-certbot-nginx

插件要与验证方式匹配:--nginx 依赖 python3-certbot-nginx;--webroot 与 --standalone 只需要 certbot 本体;DNS 验证需要对应插件,如 python3-certbot-dns-cloudflare。安装后用 certbot plugins 确认已加载的插件列表,缺插件会在签发时报 Could not choose appropriate plugin。

必须提前记住目录约定:/etc/letsencrypt/live/ 存当前证书软链,/etc/letsencrypt/archive/ 存历史版本,/etc/letsencrypt/renewal/ 存续期配置,/var/log/letsencrypt/ 存日志。迁移服务器时,只拷 live 目录是无效的,必须同时带走 renewal 和 archive,否则续期会报找不到私钥。

权限方面,privkey.pem 权限为 600 且属主 root。Nginx master 进程以 root 启动,配置中直接引用路径即可;若由非 root 的 systemd 服务读取证书,需要把运行用户加入 ssl-cert 组或调整属组,否则会报 Permission denied。

三、首次签发:–nginx 一键模式与 certonly 模式

最快的路径是 nginx 插件,它会自动改写 server 块、补上 443 监听与跳转规则:

certbot --nginx 
  -d example.com -d www.example.com 
  --email ops@example.com 
  --agree-tos --no-eff-email 
  --redirect -n

参数含义:-d 可重复,第一个域名作为证书的 Common Name,其余进 SAN;--redirect 自动把 80 请求 301 到 443;-n 非交互;--agree-tos 同意协议;--no-eff-email 不订阅 EFF 邮件。执行过程中 certbot 会调用 nginx -t 校验并 reload,失败会自动回滚配置。

如果不希望 certbot 触碰 Nginx 配置,用 certonly 加 webroot,把验证文件写进站点根目录:

certbot certonly --webroot -w /var/www/html 
  -d example.com -d www.example.com 
  --email ops@example.com --agree-tos -n

注意 -w 必须对应 80 端口那个 server 块的 root,且 http://example.com/.well-known/acme-challenge/ 要能被公网直接访问,不能被 CDN、WAF、强制 HTTPS 之外的跳转规则拦截。签发成功后证书位于 /etc/letsencrypt/live/example.com/,包含 fullchain.pem(站点证书加中间证书)、privkey.pem、chain.pem、cert.pem。

一张证书放多少域名要克制:Let’s Encrypt 单证书 SAN 上限为 100 个,且同一证书内的域名续期时同生共死,把核心业务域名和边缘测试域名混在一张证书里,会放大单点故障面。建议按业务线拆分证书,用 --cert-name 显式命名便于管理。

四、自动续期:systemd timer、cron 与 deploy-hook

通过包管理器安装时,certbot 会自动注册 certbot.timer,每天触发两次并带随机延迟,主机离线后恢复时会补跑一次:

systemctl status certbot.timer
systemctl list-timers certbot.timer
systemctl enable --now certbot.timer   # 若未启用
cat /lib/systemd/system/certbot.timer

续期判断逻辑在 certbot renew 内部:读取每个 renewal conf,只有剩余有效期小于 30 天才会真正续期,否则输出 Certificate not yet due for renewal 并跳过。手动演练用 dry-run,它会连到 staging 环境走完整流程但不落盘:

certbot renew --dry-run
certbot renew --dry-run --cert-name example.com

每次改完 Nginx 配置、换服务器、动过防火墙或 CDN 之后,都应该跑一次 --dry-run,这是唯一能在故障发生前发现“续期链路已断”的手段。

续期成功后必须让 Nginx 重新加载,否则它仍持有旧证书。用 deploy-hook 固化这一动作:

certbot renew --deploy-hook 'systemctl reload nginx'

或直接写进 renewal conf,避免手工命令丢失:

# /etc/letsencrypt/renewal/example.com.conf 末尾
[renewalparams]
renew_hook = systemctl reload nginx

hook 只在真正续期成功时触发,--dry-run 也会触发,所以脚本必须幂等。日志统一在 /var/log/letsencrypt/letsencrypt.log,排查时用 tail -n 100 配合 -v 提高详细度。老系统用 cron 时写 0 3 * * * certbot renew --quiet --deploy-hook 'systemctl reload nginx',但要确认 systemd timer 已停用,两者并存会重复执行。

五、配置示例:Nginx TLS 参数、renewal conf 与 hook 脚本

Nginx 侧不要复制证书文件,直接引用 live 软链,续期后自动生效:

server {
    listen 80;
    server_name example.com www.example.com;
    location /.well-known/acme-challenge/ { root /var/www/html; }
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 443 ssl;
    http2 on;
    server_name example.com www.example.com;

    ssl_certificate         /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key     /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;

    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;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    add_header Strict-Transport-Security 'max-age=31536000' always;
}

关于 OCSP stapling 需要更新认知:Let’s Encrypt 已于 2025 年停止提供 OCSP 响应,并从证书中移除 OCSP URL,因此 ssl_stapling on 对其证书已无实际意义,不必再为 stapling 报错浪费时间,吊销状态判断转向 CRL 或直接依赖短周期证书。

renewal conf 的关键字段如下,authenticator 不要手改成与插件不一致的值,否则续期时报插件不匹配:

[renewalparams]
account = 1234abcd
server = https://acme-v02.api.letsencrypt.org/directory
authenticator = nginx
installer = nginx
key_type = ecdsa
renew_hook = systemctl reload nginx

key_type = ecdsa 生成 P-256 证书,体积小、握手快,现代客户端全部支持;仍需兼容 Java 6、Android 4.x 等老设备时改为 rsa 并用 --rsa-key-size 2048 重签。多服务共用证书时,把动作写进全局 deploy hook 目录:

#!/bin/sh
set -e
nginx -t && systemctl reload nginx
systemctl reload postfix 2>/dev/null || true

保存为 /etc/letsencrypt/renewal-hooks/deploy/reload.sh 并 chmod +x,此后所有证书续期成功都会执行它。

六、验证方式与客户端选型对比

选错验证方式是续期失败的第一大来源。三种 ACME challenge 的差异如下表:

验证方式 原理 适用场景 局限
HTTP-01 在 80 端口提供 /.well-known/acme-challenge/<token> 公网可达的常规站点,certbot –nginx / –webroot 默认 必须开放 80;不支持通配符;CDN、WAF、强制跳转易拦截
DNS-01 写入 TXT 记录 _acme-challenge.example.com 通配符证书、内网主机、80 被封、纯 DNS 托管 需要 DNS API 凭据;生效受 TTL 影响;国内厂商需对应插件
TLS-ALPN-01 在 443 端口以 acme-tls/1 协议响应 443 可用但不能动 80 的场景 不能与其他占用 443 的服务共存;certbot 支持有限

客户端层面,certbot 官方维护、Nginx/Apache 集成度高、systemd timer 开箱即用,缺点是 Python 依赖较重;acme.sh 是纯 shell 实现,DNS API 覆盖阿里云、DNSPod、华为云等国内厂商,在解析商不提供国外 API 的场景下更稳;lego 是 Go 单二进制,适合容器与 CI 流水线。

国内环境特别提示:如果域名解析在国内厂商、且服务器 80 端口常被云厂商安全组或备案策略限制,HTTP-01 的失败率会很高,直接改用 DNS-01 配合 acme.sh --dns dns_ali 之类的 API 模式,把续期从“依赖端口连通性”变成“依赖 API 凭据有效性”,故障面小得多。

七、常见错误排查:真实报错与处置

1. Challenge failed … Timeout during connect (likely firewall problem)
80 端口不通。先用 ss -lntp | grep :80 确认本机监听,再检查云安全组与主机防火墙 firewall-cmd --list-ports,最后确认 CDN 回源是否放行 /.well-known/ 路径。

2. Problem binding to port 80: Could not bind to IPv4 or IPv6
端口被占用,--standalone 无法启动临时监听。停掉占用进程,或改用 --webroot、DNS 验证绕过端口依赖。

3. too many failed authorizations recently
验证失败触发限流:同一账户对同一主机名每小时 5 次失败;同一域名集每周 5 张重复证书;每个注册域名每周 50 张。调试阶段一律用 --dry-run 走 staging,正式环境不要试错。

4. nginx: [emerg] duplicate listen options for 0.0.0.0:443
--nginx 插件回滚时可能留下重复的 listen 443 ssl。用 nginx -t 定位行号后手工删除重复项;根治办法是改用 certonly --webroot,不让 certbot 写配置。

5. DNS problem: NXDOMAIN looking up A for example.com
解析未生效,或只配了 AAAA 而 A 记录缺失。确保 A 与 AAAA 都指向本机,或删除错误的 AAAA 记录后重试。

6. Certificate not yet due for renewal
这不是错误,剩余有效期大于 30 天会跳过。确需强制重签用 --force-renewal,但要清楚它会占用每周签发配额。

所有失败细节都写进 /var/log/letsencrypt/letsencrypt.log,加上 -vvv 可以看到完整的 ACME 请求与响应体,比盯屏幕猜快得多。

八、效果验证:证书链、到期时间与续期演练

签发或续期后,从四个维度验证:本地证书清单、服务端实际下发的证书、证书链完整性、自动续期链路可用性。

# 1. 本地证书与到期时间
certbot certificates

# 2. 服务端实际下发的证书
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# 3. 证书链是否完整
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl crl2pkcs7 -nocrl -certfile /dev/stdin | openssl pkcs7 -print_certs -noout

# 4. 续期链路演练
certbot renew --dry-run
systemctl list-timers certbot.timer

检查要点:notAfter 应在 90 天以内;issuer 应为 Let’s Encrypt 当前中间证书(如 R10/R11 或 E5/E6),若显示根证书名称说明链拼接有误;SAN 必须覆盖所有需要访问的域名,包括 www;链输出应包含站点证书与至少一张中间证书,缺中间证书会导致部分安卓客户端报“证书不受信任”。

浏览器侧可用 curl -sI https://example.com | head -n 5 快速确认 200 与 HSTS 头,深度检测用 testssl.sh --fast https://example.com 或 SSL Labs 评分,重点看协议版本、密钥强度与前向保密套件是否达标。

最后确认软链指向:ls -l /etc/letsencrypt/live/example.com/,输出中的 -> ../../archive/... 应指向最新时间戳文件。至此,从签发到无人值守续期的闭环才算真正跑通。

常见问题

包管理器安装会自动注册 certbot.timer,每天触发两次并带随机延迟,无需额外配 cron。用 systemctl list-timers certbot.timer 确认存在且已 enable,再跑一次 certbot renew –dry-run 验证链路。若同时存在 cron 任务,应停用其中一个,避免重复签发触发限流。

可以。改用 DNS-01 验证,在解析商写入 _acme-challenge 的 TXT 记录即可,certbot 用 –preferred-challenges dns 配合对应插件,或用 acme.sh 的 DNS API 模式。DNS-01 还支持通配符证书,适合 80 端口被安全组限制或走 CDN 的站点。

说明 Nginx 未重新加载。执行 nginx -t 校验后 systemctl reload nginx,并在 renewal conf 中固化 renew_hook = systemctl reload nginx。若前面有 CDN 或负载均衡,还需在控制台上传新证书,否则边缘节点仍下发旧证书。

不是。398 天是 CA/Browser Forum 对公有 CA 单张证书的最长有效期上限,Let’s Encrypt 主动采用 90 天固定周期以推动自动化。因此不要按 398 天规划续期窗口,certbot 在剩余 30 天时就会自动续签。

解析在国内厂商时优先 acme.sh。它是纯 shell 实现,内置阿里云、DNSPod、华为云等 DNS API,可直接走 DNS-01 验证,绕开 80 端口与备案限制。certbot 的 DNS 插件对国内厂商覆盖较弱,通常需要第三方插件或手工 TXT 记录。

内容审核

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