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 记录。