密码学与证书 / 知识点
Certbot 常见故障排查速查
自动续期故障
使用 Standalone 认证时 Certbot 需要监听验证端口;如果 Nginx 或其他服务已占用 80 端口,续期可能失败,需要调整认证方式或通过 Hook 协调服务启停。
Standalone 续期端口冲突
目标是让使用 Standalone 认证的证书恢复可续期状态,并在测试结束后确认原 Web 服务已经恢复。HTTP-01 验证要求外部验证请求能够到达 80 端口,因此不能仅把 Certbot 改到任意本地端口来绕过冲突。
前置条件
- 确认该证书的续期配置确实使用 Standalone 认证,而不是 Nginx、Webroot 或 DNS 插件。
- 域名必须解析到当前验证入口,公网 TCP 80 能到达执行 Certbot 的主机或被正确转发到它。
- 如果准备临时停止 Nginx,先确认允许短暂中断 HTTP 服务,并具备
systemctl管理权限。 - 生产环境优先考虑改用 Nginx、Webroot 或 DNS 认证;停服务 Hook 更适合作为已有 Standalone 配置的兼容方案。
定位端口占用
先检查谁正在监听 80 端口。若输出显示 Nginx、Apache 或其他进程占用该端口,Standalone 无法同时绑定同一地址和端口。
sudo ss -ltnp 'sport = :80'预期输出:可以看到监听 80 端口的进程;PID、地址等实际值可能不同。
LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("nginx",pid=<ID>,fd=<ID>))如果没有监听者仍出现绑定失败,还应检查容器端口映射、Socket 激活服务以及 Certbot 报错中实际尝试监听的地址。
协调 Standalone 与 Nginx
确认允许短暂停机后,可用续期 Hook 在验证前停止 Nginx,并在验证尝试结束后重新启动。先用 --dry-run 验证整个续期路径,不会把测试证书替换成正式证书。
sudo certbot renew --cert-name <CERT_NAME> --dry-run \
--pre-hook "systemctl stop nginx" \
--post-hook "systemctl start nginx"
sudo systemctl is-active nginx预期输出:Certbot 的具体日志文本会随版本变化,但模拟续期应成功,最后一条命令应确认 Nginx 已恢复运行。
<DRY_RUN_SUCCESS_MESSAGE>
active验证与失败处理
模拟续期成功后,再按正常计划执行正式续期,并确认 80 端口重新由原服务监听。如果 Certbot 仍失败,应停止反复重试,优先检查 DNS、云防火墙、安全组、NAT 或上游代理是否允许公网访问 80 端口。
若停止 Nginx 后验证失败且服务没有自动恢复,立即执行 sudo systemctl start nginx,再用 sudo systemctl is-active nginx 确认恢复。不要在业务服务仍停止的状态下继续排查证书问题。
长期运行时,尽量让续期过程不依赖停机;已有 Standalone 配置需要迁移认证方式时,应先备份当前续期配置并完成一次测试续期,再删除旧方案。
磁盘中的证书已经更新而线上仍返回旧证书,通常是 Web 服务未重新加载、配置仍引用旧路径,或 TLS 实际终止在 CDN、负载均衡器等其他节点。
证书已续期但网站仍显示旧证书
目标是确认“磁盘证书已更新”和“客户端实际收到的新证书”是否一致,并定位旧证书究竟来自本机 Web 服务,还是 CDN、负载均衡器等更靠前的 TLS 终止节点。
前置条件
- 已确认 Certbot 记录中的目标证书存在,并知道对应的证书名称与域名。
- 具备读取
/etc/letsencrypt、检查 Nginx 配置以及重新加载服务的权限。 - 修改或重载生产服务前应保留当前配置;如果 TLS 在 CDN 或负载均衡器终止,还需要对应平台的证书管理权限。
先确认 TLS 在哪里终止
浏览器连接的服务器不一定就是运行 Certbot 的主机。请求可能先在 CDN 或负载均衡器完成 TLS 握手,然后再通过另一条连接访问源站;这种情况下,更新源站证书不会自动改变公网返回的边缘证书。

如果 DNS 或网络架构显示公网流量经过 CDN、Ingress、反向代理或负载均衡器,应先确认哪个节点向客户端出示证书,再决定在哪里部署新证书。
核对本地证书与服务配置
先运行 sudo certbot certificates,确认目标证书的名称、有效期和证书路径。Nginx 应引用 /etc/letsencrypt/live/<CERT_NAME>/ 下的当前链接,而不是固定指向 archive 目录中的某个历史版本文件。
如果确认 TLS 直接终止在本机 Nginx,可在配置检查通过后重新加载服务,并比较磁盘证书与公网返回证书的 SHA-256 指纹。
DOMAIN=<HOST>
CERT_NAME=<CERT_NAME>
sudo certbot certificates
sudo nginx -t && sudo systemctl reload nginx
LOCAL_FP=$(sudo openssl x509 -in "/etc/letsencrypt/live/$CERT_NAME/fullchain.pem" -noout -fingerprint -sha256)
REMOTE_FP=$(echo | openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" 2>/dev/null | openssl x509 -noout -fingerprint -sha256)
printf 'local=%s\nremote=%s\n' "$LOCAL_FP" "$REMOTE_FP"预期输出:Nginx 配置检查成功;重新加载后,如果公网 TLS 确实由这台 Nginx 终止,本地和远端指纹应一致。配置路径、指纹等实际值可能不同。
nginx: configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful
local=sha256 Fingerprint=<FINGERPRINT>
remote=sha256 Fingerprint=<FINGERPRINT>指纹仍不一致时
如果远端指纹与本地不同,不要连续重载 Nginx。先确认域名解析到了哪些地址,并检查是否存在多台源站、IPv4 与 IPv6 不一致、旧实例仍在负载均衡池中等情况。
如果 TLS 在 CDN 或负载均衡器终止,本地证书与公网证书本来就可能不同。此时应在实际终止 TLS 的节点更新或启用新证书,并从公网重新检查证书,而不是继续修改源站 Certbot 文件。
如果 Nginx 配置引用了历史证书文件,应恢复为正确的 live/<CERT_NAME>/fullchain.pem 与对应私钥路径;修改后必须先通过 nginx -t,再重新加载服务。
恢复与回滚
若修改 Nginx 配置后检查失败,不要执行 reload,直接恢复先前配置并重新运行 nginx -t。如果已在 CDN、负载均衡器等边缘节点切换证书后出现异常,应切回此前已验证可用的证书版本,并保留新旧证书指纹和部署节点信息继续排查。
速查原则是:先确定谁在向客户端提供 TLS 证书,再在那个节点验证和部署。仅看到 Certbot 已续期,不能证明公网服务已经使用新证书。
证书持续接近过期且没有任何续期记录时,应确认安装方式是否配置了 systemd timer 或 cron,并检查任务是否启用、上次执行时间和失败日志。
自动续期任务没有运行
目标是确认 Certbot 的续期调度器是否真实存在并持续执行。完成排查后,应能确定当前安装由 systemd timer、Snap timer 还是 cron 负责,并确认调度任务已启用、最近运行记录正常,手工模拟续期也能通过。
前置条件
- 使用具备
sudo权限的账户,并先确认 Certbot 是通过系统包、Snap 还是其他方式安装,避免同时维护两套续期任务。 - 暂时不要新建自定义 cron 或 timer;先查清现有调度机制,防止同一证书被重复触发续期。
- 如果正在临近证书到期时间,先记录证书名称、到期时间和当前服务状态,便于后续判断是否需要人工续期。
检查实际调度方式
先同时检查 systemd timer 和常见 cron 目录。不同发行版和安装方式的单元名称可能不同,因此不要只判断固定的 certbot.timer。
echo '== systemd timers =='
systemctl list-timers --all | grep -Ei 'certbot|letsencrypt' || true
echo '== cron entries =='
sudo grep -R -Ei 'certbot|letsencrypt' /etc/cron.d /etc/cron.daily /etc/cron.hourly 2>/dev/null || true预期输出:至少一种调度机制能够找到 Certbot 相关记录;实际单元名、时间和路径会随安装方式变化。
== systemd timers ==
<NEXT> <LEFT> <LAST> <PASSED> <TIMER_UNIT> <SERVICE_UNIT>
== cron entries ==
<CRON_ENTRY_OR_EMPTY>如果两部分都没有任何相关记录,应先检查 Certbot 的安装来源和包是否完整,不要直接创建第二套定时任务。
启用并验证 timer
如果已经确认由 systemd timer 管理,但对应 timer 处于 disabled 或 inactive 状态,可启用正确的单元。<TIMER_UNIT> 必须替换成前一步实际查到的名称。
sudo systemctl enable --now <TIMER_UNIT>
systemctl is-enabled <TIMER_UNIT>
systemctl is-active <TIMER_UNIT>
systemctl list-timers --all | grep -F '<TIMER_UNIT>'预期输出:timer 应同时处于启用和活动状态,并显示下一次计划触发时间;具体时间值可能不同。
enabled
active
<NEXT> <LEFT> <LAST> <PASSED> <TIMER_UNIT> <SERVICE_UNIT>检查失败记录与续期链路
Timer 显示正常并不代表续期本身成功。检查其触发的 service 日志,并执行一次模拟续期。<SERVICE_UNIT> 使用 list-timers 中对应的实际服务单元。
sudo journalctl -u <SERVICE_UNIT> --since '7 days ago' --no-pager
sudo certbot renew --dry-run预期结果:日志中应能看到实际执行记录,renew --dry-run 应完成模拟续期;日志时间、证书名称和输出文本会因环境不同而变化。
<RECENT_RENEWAL_LOGS>
<DRY_RUN_RESULT>如果 timer 按计划触发,但 renew --dry-run 失败,问题已经不在“任务没有运行”,应根据错误继续检查域名验证、插件、端口、权限或 renewal 配置。若 timer 从未触发,则重点检查单元状态、系统日志和安装方式。
恢复与回滚
如果排查过程中误启用了不属于当前安装方式的 timer,可使用 sudo systemctl disable --now <TIMER_UNIT> 停止并禁用它,再恢复原有调度机制。最终应只保留一套明确、可验证的自动续期入口,并再次确认下一次计划时间。
续期配置缺少插件参数、路径失效或被手工修改后,renew 可能无法复现原来的申请流程;优先通过 Certbot 命令调整配置,不建议直接修改 renewal 文件。
续期配置文件异常
目标是恢复 Certbot 对既有证书申请方式的可重复执行能力。处理完成后,Certbot 应能正确识别目标 certificate lineage,所需验证插件和路径仍然有效,并通过 renew --dry-run 完成模拟续期,而不是依赖手工修改 renewal 文件。
前置条件
- 使用具备
sudo权限的账户,并确认当前 Certbot 的安装来源,避免混用系统包与 Snap 的插件或配置。 - 在修改任何续期参数前备份
/etc/letsencrypt,尤其是renewal、archive和live相关内容。 - 记录证书当前使用的域名、验证插件以及 Webroot、DNS 凭据或 Web 服务器配置位置;路径已经迁移时先确认新路径真实存在。
- 不要直接编辑
/etc/letsencrypt/renewal/*.conf来试错。文件中的参数彼此关联,手工修改可能留下只有下一次续期才暴露的问题。
定位异常配置
先让 Certbot 自己列出已管理的 certificate lineage,再检查可用插件,并针对目标证书执行模拟续期。<CERT_NAME> 替换为 certbot certificates 显示的 Certificate Name,而不一定只是某个域名。
sudo certbot certificates
sudo certbot plugins
sudo certbot renew --cert-name <CERT_NAME> --dry-run预期结果:前两条命令应能确认目标证书及当前可用插件;如果续期配置确有异常,模拟续期会在不替换生产证书的情况下暴露缺失插件、失效路径或验证失败等具体原因。
Certificate Name: <CERT_NAME>
<AVAILABLE_PLUGINS>
<DRY_RUN_SUCCESS_OR_SPECIFIC_ERROR>如果连目标证书都没有出现在 certbot certificates 中,应先确认当前进程读取的是正确的 Certbot 配置目录和安装实例,而不是继续修改 renewal 文件。
通过 Certbot 修正参数
较新的 Certbot 提供 reconfigure 子命令,可在测试新续期参数成功后更新既有 certificate lineage。下面以 Webroot 验证为例;只有原证书确实应使用 Webroot 时才使用这些参数,Nginx、Apache 或 DNS 插件应改成与实际环境匹配的插件选项。
sudo certbot reconfigure --cert-name <CERT_NAME> --webroot --webroot-path <WEBROOT>
sudo certbot renew --cert-name <CERT_NAME> --dry-run预期结果:重新配置过程通过测试,随后目标证书的模拟续期成功;<WEBROOT> 必须替换成当前 Web 服务实际暴露 /.well-known/acme-challenge/ 的目录。
<RECONFIGURE_SUCCESS>
<DRY_RUN_SUCCESS>如果当前版本的帮助信息中没有 reconfigure 子命令,不要因此直接编辑 renewal 文件。应使用当前安装渠道支持的升级或重新签发流程,并在变更前保存现有证书与配置,以免把版本差异误判成配置损坏。
验证与失败处理
修正后再次检查证书列表和 renew --dry-run。只有模拟续期成功,才能认为“当前证书还能自动续期”;单纯看到证书仍在 live 目录中并不能证明 renewal 配置有效。
若仍然失败,按错误信息停止继续修改:插件不存在时先修复与当前 Certbot 安装方式匹配的插件;Webroot 路径失效时先确认站点映射;DNS 凭据失效时先恢复凭据权限。连续改动多个参数会掩盖真正的故障点。
恢复方式
如果重新配置导致新的续期测试失败,不要删除现有 live、archive 或 renewal 文件。保留当前仍在使用的证书,从事先备份中恢复配置,或重新使用 Certbot 的受支持命令建立正确的 certificate lineage,再通过 renew --dry-run 验证。生产服务继续引用旧证书期间,还要确认其文件路径没有被误删或改名。
CA 与签发限制
域名的 CAA 记录未授权当前证书机构时,CA 会拒绝签发;需要检查主域名及相关 DNS 层级的 CAA 策略,并确认允许所使用的证书机构。
CAA 拒绝签发证书
目标是找出对申请域名实际生效的 CAA 策略,确认它是否授权 Let’s Encrypt,并在修正 DNS 后只做一次受控重试。CAA 问题既可能来自显式拒绝,也可能来自 DNSSEC、权威 DNS 超时等导致 CA 无法可靠读取记录的故障。
前置条件
- 已记录 Certbot 报错中的完整域名;证书包含多个名称时,要逐个检查,不能只看主域名。
- 具备 DNS 查看权限;要修改 CAA 时,还需具备对应 DNS 区域的变更权限并先保存原记录。
- 已确认申请是否包含通配符。普通证书主要看
issue;通配符在存在issuewild时由issuewild单独控制。 - 若域名使用 CNAME,还要能检查 CNAME 目标及其父级 DNS。
定位实际生效的 CAA
CAA 按“离待签发名称最近的记录优先”处理:CA 会从具体名称向父级查找,遇到第一组 CAA 记录后停止继续向上;若名称是 CNAME,还会跟随目标检查。因此只查看注册域名的一条记录,可能漏掉子域覆盖或 CNAME 目标上的限制。

先查询申请名称、其父级以及可能存在的 CNAME:
dig +noall +answer CAA <DOMAIN>
dig +noall +answer CAA <PARENT_DOMAIN>
dig +short CNAME <DOMAIN>预期输出:
<PARENT_DOMAIN>. <TTL> IN CAA 0 issue "letsencrypt.org"实际 TTL 和名称会不同;如果某一级没有 CAA,第一条或第二条命令也可能无输出。没有任何适用 CAA 并不等于拒绝签发;真正需要修正的是最近的有效 CAA RRset 不允许 Let’s Encrypt,或 DNS 查询本身失败。
修正授权记录
Let’s Encrypt 的 CAA 标识是 letsencrypt.org。对普通域名,issuewild 会被忽略:如果最近的 CAA RRset 含有 issue,至少一条必须授权 Let’s Encrypt;如果根本没有 issue,该 RRset 不会仅因存在 issuewild 而限制普通证书。对通配符,只要同一 RRset 存在 issuewild,就忽略 issue 并由 issuewild 决定授权;没有 issuewild 时才由 issue 控制。
如果现有策略只是漏掉 Let’s Encrypt,可在正确的 DNS 层级加入 CAA 0 issue "letsencrypt.org";若组织明确区分通配符权限,再按策略设置 issuewild。如果记录还使用 validationmethods 或 accounturi 参数,也要确认当前验证方式和 ACME 账户满足限制,不能只看 CA 名称。
修改后等待权威 DNS 和递归缓存更新,再重复前面的 dig 查询,直到看到预期策略后再重试 Certbot。
验证与失败处理
若 dig 返回 SERVFAIL,优先检查 DNSSEC、权威服务器状态和签名链;若查询超时,检查权威 DNS 可达性以及是否有防火墙丢弃 CAA 查询。此类故障即使没有显式 CAA 记录,也会让 CA 无法确认是否允许签发。
如果域名有 CNAME,必须继续检查目标名称的 CAA;如果证书包含多个 SAN,每个名称都要满足 CAA 检查。仍未定位时,先使用 Let’s Encrypt Staging 复现,避免连续消耗生产环境的失败额度。
回滚与恢复
若本次 CAA 修改不符合既定安全策略,从变更前备份恢复原 RRset,并确认 DNS 已重新收敛。需要注意:恢复为不授权 Let’s Encrypt 的策略后,后续自动续期也会再次失败;只有在确定不再使用 Let’s Encrypt 时才应这样回滚。
短时间重复申请、持续失败或自动化异常可能触发 CA 的速率限制;应停止无意义重试,修复根因并在调试阶段优先使用 Staging 测试环境。
触发 Let's Encrypt 速率限制
目标是立即停止无意义的生产重试,识别具体被限制的请求范围和可重试时间,用 Staging 验证修复后再恢复生产申请。速率限制不是靠“多试几次”解除的;连续自动重试只会增加噪声,甚至触发其他限制。
前置条件
- 保留 Certbot 的完整错误信息和发生时间,尤其是
too many、rate limit、retry after等字段。 - 确认失败来自生产环境,而不是 Staging,并记录涉及的域名、ACME 账户和触发任务。
- 具备暂停异常 cron、systemd timer、CI/CD 或自定义重试循环的权限。
- 当前证书仍有效时先保持服务继续使用它;不要通过吊销证书来“重置”速率限制。
识别限制并停止重复请求
先从 Certbot 日志找出最近的限制信息,同时确认是否有定时任务正在持续触发:
sudo grep -Ei 'rate limit|too many|retry after' /var/log/letsencrypt/letsencrypt.log | tail -n 20
systemctl list-timers --all | grep -i certbot || true预期输出:
<TIME> ... too many ... retry after <TIME>
<TIME> ... certbot.timer实际日志格式、时间和 timer 名称会因安装方式而不同。若日志给出可重试时间或 Retry-After,以该信息为准;不要套用旧文章里的固定等待时长。不同限制可能按域名、账户、标识符或请求端点分别计算,所以先确定是哪一种限制,再处理对应根因。
如果发现自定义脚本每几分钟重新申请同一张证书,应先暂停该脚本。健康的标准续期任务如果没有制造重复请求,不必为了排障全部关闭。
修复根因并使用 Staging
速率限制通常是结果而不是根因。先修复此前导致重复申请或验证失败的问题,例如 DNS 未生效、HTTP-01 路径不可达、错误地每次生成新账户、部署脚本重复执行 certonly,或多个节点同时为同一组域名申请证书。
对已有续期配置,使用 Certbot 的模拟续期验证修复,不消耗生产签发机会:
sudo certbot renew --dry-run预期结果:
模拟续期完成且命令退出码为 0;具体成功提示文字会随 Certbot 版本和安装方式不同。如果排查的是首次签发而不是续期,应在原有 Certbot 申请命令中使用 --test-cert 连接 Staging,并保持与生产相同的验证插件和域名集合。Staging 证书不受浏览器信任,只用于验证自动化链路。
等待恢复并恢复生产申请
生产速率限制会随时间恢复容量,触发后通常不能手工即时清零。证书吊销也不会返还已经消耗的签发额度。到错误信息给出的可重试时间之后,只执行一次生产申请;成功后再恢复原定时任务。
恢复后观察一个完整的续期或部署窗口,确认没有重复创建订单、连续验证失败或异常高频调用。若第一次生产重试又提示速率限制,阅读新的错误内容;可能还有另一项独立限制尚未恢复。
失败处理与回滚
只要 --dry-run 或 --test-cert 仍失败,就不要回到生产环境继续碰运气。应保持异常重试任务暂停,继续修复验证链路。
如果为排障修改了续期脚本、定时器或部署配置但结果变差,恢复到变更前版本,同时继续暂停高频生产申请;等 Staging 验证通过后再重新启用。这样可以把“恢复自动化”和“恢复生产签发”分开,避免一启用任务就再次形成重试风暴。
同一域名持续提交失败验证会消耗失败验证额度,继续盲目重试只会延长排障过程;应先切换测试环境定位 DNS、端口或挑战路径问题。
连续验证失败被限制
目标是先停止消耗生产环境的验证额度,再用 Let’s Encrypt staging 环境复现问题;只有模拟验证成功并确认限制已经解除后,才恢复生产申请。生产环境的授权失败存在频率限制,具体阈值可能调整,应以 CA 当前错误响应和官方限制说明为准。
前置条件
- 已确认失败的
<DOMAIN>、对应 Certbot 证书名称<CERT_NAME>,以及当前使用的 HTTP-01、DNS-01 或其他挑战方式。 - 具备查看 DNS、Web 服务、防火墙和 Certbot 日志所需的权限。
- 如果准备修改 Nginx、Apache、防火墙或 DNS,先保存现有配置;不要为了重试而删除
/etc/letsencrypt中的账户或证书数据。
停止生产重试并切换测试环境
出现 rateLimited、too many failed authorizations 一类错误后,不要循环执行生产申请。对已有 Certbot lineage,优先用 --dry-run 在 staging 环境模拟续期,它会复用该证书已有的验证配置,又不会保存 staging 证书到正式 lineage。
sudo certbot renew --cert-name '<CERT_NAME>' --dry-run预期结果:模拟续期成功时命令正常结束,并在续期摘要中标记测试成功;不会替换当前生产证书。具体日志文本和证书路径会随 Certbot 版本及环境变化。
按挑战类型定位失败点
如果 staging 仍失败,先依据错误信息判断验证请求停在哪一层。HTTP-01 重点检查 <DOMAIN> 的 A/AAAA 记录是否指向正确入口、外部 TCP 80 是否可达,以及 /.well-known/acme-challenge/ 是否被反向代理、重写、认证或错误的 Web Root 拦截。使用 standalone 插件时,还要确认 Certbot 能实际监听验证所需端口。
DNS-01 则重点检查 _acme-challenge.<DOMAIN> 的 TXT 记录是否写入正确区域、委派或 CNAME 是否指向预期目标,以及权威 DNS 是否已经能查询到新值。不要仅依据本机递归 DNS 的缓存结果判断传播完成。
验证与失败处理
只有 staging 验证成功后才进入生产重试。如果 staging 失败,继续修复 DNS、端口、挑战路径或插件配置,不要切回生产环境碰运气。如果 staging 成功但生产仍返回限流错误,应停止申请并按照错误响应给出的可重试时间或当前 CA 限制规则等待额度恢复。
恢复生产前再次确认域名解析没有临时指向测试主机、防火墙没有遗留临时开放规则,Web Root 中也没有排障用的挑战文件。若排障期间修改了服务配置但未解决问题,应恢复备份并重新执行配置检查,先让站点回到原有稳定状态。
证书与文件故障
cert-name 是 Certbot 管理证书 lineage 的名称,并不等于证书只能包含这个域名;操作续期、删除或重配置前应先确认目标证书名称和实际域名列表。
证书名称与域名混淆
目标是在续期、删除或重配置前准确识别 Certbot 管理的 lineage,避免把 Certificate Name 当成证书唯一包含的域名。完成检查后,应能分别说清目标 lineage 的名称、实际 Domains 列表以及 /etc/letsencrypt/live/<CERT_NAME>/ 路径。
前置条件
- 具备读取 Certbot 配置的权限,通常需要
sudo。 - 删除或改变现有证书前,已确认 Web 服务器、负载均衡器或其他服务实际引用的证书路径。
- 高风险操作前已备份
/etc/letsencrypt或具备可用的系统快照;不要直接用rm删除其中的 lineage 文件。
先建立名称与域名映射
运行 Certbot 自带的证书清单,不要根据目录名或某个站点域名猜测目标证书。
sudo certbot certificates预期结果:每个 Certbot 管理的证书都会分别显示 Certificate Name、Domains、到期信息以及证书路径。输出内容取决于本机现有证书,名称还可能出现类似 example.com-001 的后缀。
Certificate Name 是 Certbot 用来管理 lineage 的标识,也通常出现在 /etc/letsencrypt/live/<CERT_NAME>/ 路径中;Domains 才表示当前证书实际包含的 DNS 名称。一个名为 example.com 的 lineage 完全可以同时包含 example.com、www.example.com 等多个域名。
操作时使用正确的标识
需要针对单个 lineage 续期、删除或重配置时,应把清单中的 Certificate Name 原样传给 --cert-name。它负责选择 Certbot 管理对象,本身不会把证书内容限制为同名域名。
如果使用 certonly 等申请命令并同时提供 -d,-d 指定的是申请证书时要包含的标识符。对已经存在的同名 lineage 修改域名集合可能导致证书内容发生变化,因此执行前必须把当前 Domains 与目标列表逐项核对。
验证与失败处理
任何变更前至少确认三项信息一致:目标 Certificate Name、期望的 Domains 集合,以及服务实际引用的 /etc/letsencrypt/live/<CERT_NAME>/ 路径。如果名称相近的 lineage 有多个,例如带 -001、-002 后缀,应逐个核对而不是按创建时间猜测。
若发现选错 lineage,应在真正续期、删除或重配置前停止操作并重新运行 certbot certificates。如果已经误删,Certbot 没有通用的一键撤销操作,应优先从事先的 /etc/letsencrypt 备份或系统快照恢复,再检查 Web 服务配置和证书清单;不要通过手工拼接 live、archive 和 renewal 文件来恢复状态。
Web 服务器提示 fullchain.pem 或 privkey.pem 不存在时,不应手工复制或伪造 Certbot 管理目录;先确认对应证书是否仍存在以及配置引用的证书名称是否正确。
证书文件路径不存在
目标是确认 Web 服务器引用的证书名称与 Certbot 实际管理的证书一致,并恢复到一个真实存在、仍由 Certbot 管理的 fullchain.pem 与 privkey.pem 路径。不要在 /etc/letsencrypt/live/ 中手工创建文件或复制私钥来“补齐”目录。
前置条件
- 使用具备
sudo权限的账号检查证书目录。 - 先记录当前 Web 服务器配置中的证书路径;准备修改前备份对应配置文件。
/etc/letsencrypt/live/<CERT_NAME>/通常保存指向archive目录的符号链接,排障时不要改写这些链接关系。- 如果证书已从 Certbot 管理范围中删除,应重新签发或恢复证书,而不是伪造同名目录。
确认证书名称与文件
先让 Certbot 列出它仍然识别的证书,再检查配置中引用的证书名称是否一致。将 <CERT_NAME> 替换为 Certificate Name 显示的实际名称。
sudo certbot certificates
sudo ls -l /etc/letsencrypt/live/<CERT_NAME>/fullchain.pem /etc/letsencrypt/live/<CERT_NAME>/privkey.pem
sudo readlink -f /etc/letsencrypt/live/<CERT_NAME>/fullchain.pem
sudo readlink -f /etc/letsencrypt/live/<CERT_NAME>/privkey.pem预期输出
Found the following certs:
Certificate Name: <CERT_NAME>
Certificate Path: /etc/letsencrypt/live/<CERT_NAME>/fullchain.pem
Private Key Path: /etc/letsencrypt/live/<CERT_NAME>/privkey.pem
/etc/letsencrypt/live/<CERT_NAME>/fullchain.pem -> ../../archive/<CERT_NAME>/fullchain<ID>.pem
/etc/letsencrypt/live/<CERT_NAME>/privkey.pem -> ../../archive/<CERT_NAME>/privkey<ID>.pem
/etc/letsencrypt/archive/<CERT_NAME>/fullchain<ID>.pem
/etc/letsencrypt/archive/<CERT_NAME>/privkey<ID>.pem<ID> 等实际值可能不同。只要 certbot certificates 能列出证书,并且 readlink -f 能解析到真实文件,Certbot 侧的证书文件链路就是完整的。
修正 Web 服务器引用
如果 Certbot 中的 Certificate Name 与配置路径不同,应把 Web 服务器配置改为 Certbot 实际给出的 Certificate Path 与 Private Key Path。不要通过重命名 /etc/letsencrypt/live/ 目录来迁就旧配置,因为续期会继续按 Certbot 的证书名称维护链接。
修改后先执行对应 Web 服务器的配置测试,再重新加载服务;测试失败时停止,不要直接重启生产服务。若 certbot certificates 根本没有目标证书,先处理证书恢复或重新签发,再改服务器配置。
验证与失败处理
验证重点有两项:配置测试必须通过,Web 服务器进程也必须能读取私钥。如果文件存在但仍提示权限错误,应检查服务进程权限、父目录权限和安全模块策略,而不是放宽私钥为全局可读。
如果符号链接存在但目标文件缺失,说明证书目录已经不完整。此时不要手工补链接或复制其他证书,应从备份恢复 Certbot 管理目录,或按原域名与认证方式重新签发证书。
回滚方式
若修改证书路径后配置测试失败,立即恢复修改前备份的 Web 服务器配置,并再次执行配置测试。旧配置本身也引用不存在文件时,应保持服务不重载,先恢复一套已知有效的证书文件或证书配置,再恢复正常运行。
默认错误信息不足以判断认证插件、网络或续期阶段时,可以提高 Certbot 日志详细程度,并结合 /var/log/letsencrypt/ 中的日志定位实际失败步骤。
查看更多 Certbot 排障日志
目标是在不执行真实续期的前提下,提高 Certbot 输出详细度,并把终端信息与 /var/log/letsencrypt/ 中的日志对应起来,判断失败发生在插件加载、域名验证、网络请求还是证书续期阶段。
前置条件
- 使用具备
sudo权限的账号读取 Certbot 日志。 - 生产证书尚未到期时,优先使用
--dry-run复现续期流程,避免把诊断操作与真实续期混在一起。 - 日志可能包含域名、服务器路径和请求细节;复制到工单或公共渠道前先检查敏感信息。
- 如果当前故障来自正在运行的自动续期任务,先记录失败时间,便于与日志时间戳对应。
提高日志详细度
执行一次详细的模拟续期,然后立即查看最新日志尾部。-vv 会提高详细程度,--dry-run 使用模拟环境验证续期流程,不会替换当前生产证书。
sudo certbot -vv renew --dry-run
sudo tail -n 200 /var/log/letsencrypt/letsencrypt.log预期输出
Certbot 会输出更详细的续期与验证过程。
成功时可看到模拟续期成功的结果;失败时会在对应阶段给出异常或错误原因。
letsencrypt.log 中应出现与本次执行时间相符的详细记录。实际日志内容、域名、插件名称和时间戳会因环境不同而变化。排障时应关注首次出现的异常,而不是只看最后一行汇总错误。
定位失败阶段
先按时间找到本次 --dry-run 对应的日志段,再判断错误属于哪一类。认证插件报错通常会伴随插件名称和挑战类型;网络问题常见连接、超时或 DNS 相关异常;续期配置问题则可能指向某个 /etc/letsencrypt/renewal/<CERT_NAME>.conf。
如果日志显示挑战已经创建但验证失败,应继续检查该挑战方式要求的外部可达性或 DNS 记录。若错误在插件初始化之前就出现,则优先检查 Certbot 安装、插件可用性和续期配置,而不是反复修改域名解析。
验证与失败处理
修复后再次运行同一条 sudo certbot -vv renew --dry-run。只有模拟续期成功,且日志中没有新的致命异常时,才说明续期链路已经恢复。
如果详细日志仍无法解释问题,保留失败时间、Certbot 版本、使用的认证插件、相关异常堆栈和对应日志片段再继续分析。不要为了“看更多日志”直接删除 /var/log/letsencrypt/ 或续期配置文件。
恢复正常状态
诊断本身不会修改现有生产证书,因此通常无需回滚。若排障过程中同时改过续期配置、Web 服务器配置或 DNS 记录,应分别恢复其备份或已知稳定值,并重新执行 --dry-run 确认恢复后的续期链路可用。