密码学与证书 / 知识点
Certbot 常见故障排查速查
HTTP-01 验证故障
CA 已访问目标域名,但获取到的挑战内容不正确;优先检查域名解析、虚拟主机匹配以及 /.well-known/acme-challenge/ 是否由正确站点提供。
排查 HTTP-01 unauthorized
目标是确认 CA 请求的 http://<DOMAIN>/.well-known/acme-challenge/<TOKEN> 最终由正确虚拟主机返回完全匹配的挑战内容。unauthorized 通常不是 Certbot 本身无法运行,而是公网请求到达了错误地址、错误站点,或挑战路径被重写、代理、缓存覆盖。
前置条件
- 能修改目标站点的 Web 根目录或虚拟主机配置,并具备必要的
sudo权限。 - 已记录当前 Nginx/Apache、反向代理或负载均衡配置;改动前先保留可回退版本。
- 明确
<DOMAIN>的预期公网 IPv4/IPv6 地址,以及 HTTP-01 实际使用的 Web 根目录<PATH>。 - 如果域名前有 CDN、WAF 或负载均衡,确认挑战请求经过的真实链路。
定位顺序
- 先核对 A/AAAA 记录,确认没有旧地址或错误 IPv6 记录。
- 在 Certbot 使用的 Web 根目录创建一个固定测试文件,模拟挑战文件。
- 用
curl --resolve绕过公网 DNS 直连预期源站,确认虚拟主机和 Web 根目录本身正确。 - 再按公网 DNS 请求同一路径;只有源站请求与公网请求都返回相同内容,才重试证书申请。
片段示例:把 <DOMAIN>、<PATH> 和 <IP> 替换为当前站点的真实值后执行。
DOMAIN="<DOMAIN>"
WEBROOT="<PATH>"
ORIGIN_IP="<IP>"
TOKEN="anystack-acme-check"
echo "A:"
dig +short A "$DOMAIN"
echo "AAAA:"
dig +short AAAA "$DOMAIN"
sudo mkdir -p "$WEBROOT/.well-known/acme-challenge"
printf '%s\n' "$TOKEN" | sudo tee "$WEBROOT/.well-known/acme-challenge/$TOKEN" >/dev/null
echo "origin:"
curl --resolve "$DOMAIN:80:$ORIGIN_IP" -i "http://$DOMAIN/.well-known/acme-challenge/$TOKEN"
echo "public:"
curl -i "http://$DOMAIN/.well-known/acme-challenge/$TOKEN"预期输出(示意,实际地址和响应头可能不同):
A:
<IP>
AAAA:
<IPV6_OR_EMPTY>
origin:
HTTP/1.1 200 OK
...
anystack-acme-check
public:
HTTP/1.1 200 OK
...
anystack-acme-check验证与失败处理
如果 origin 正确而 public 错误,优先检查 DNS、CDN、WAF、负载均衡和 NAT 是否把域名导向了别的后端。如果两次请求都错误,检查虚拟主机匹配、root/DocumentRoot、/.well-known/acme-challenge/ 的 location 或 rewrite 规则,以及是否被应用路由接管。
若 A 记录正确但存在指向旧服务器的 AAAA 记录,CA 可能经 IPv6 命中错误主机;应修正 IPv6 服务或删除无效 AAAA 记录。若挑战路径被统一重定向,重定向后的目标也必须能返回该 token,不能最终落到登录页、404 页面或通用首页。
只有公网请求稳定返回测试 token 后,再重试原来的 Certbot 申请或续期命令。若仍失败,停止反复重试并查看 Certbot 错误中记录的具体 URL、状态码和返回内容,再沿同一路径复现。
清理与恢复
排查完成后删除 anystack-acme-check 测试文件。若为排障临时修改了虚拟主机、rewrite、CDN 缓存规则或代理策略,应恢复到经过验证的正式配置并重新加载服务;不要删除 Certbot 后续续期仍依赖的 ACME challenge 例外规则。
验证服务器连接目标地址时立即被拒绝,通常表示 80 端口没有服务监听、防火墙主动拒绝连接,或域名解析到了错误的服务器。
排查验证连接被拒绝
目标是让 HTTP-01 验证请求能够从公网建立到目标服务器 80 端口的 TCP 连接,并至少获得一个有效 HTTP 响应。Connection refused 表示连接被明确拒绝,优先检查域名是否指向正确主机、80 端口是否监听,以及主机防火墙、云防火墙、NAT 或负载均衡是否主动拒绝。
前置条件
- 能登录目标服务器并查看监听端口,必要时具备启动 Web 服务和调整网络规则的权限。
- 已记录当前防火墙、安全组、负载均衡和 Web 服务配置;修改前先保留原规则。
- 确认当前证书验证使用 HTTP-01;这种验证需要公网能够访问 80 端口。
- 如果有 A 和 AAAA 两类记录,两条地址都要分别检查,避免其中一条指向未开放 80 端口的主机。
定位顺序
先从 DNS 判断请求会去哪里,再看目标机是否真的监听 80 端口,随后验证本机 HTTP 响应,最后从服务器之外的公网网络测试域名。这样可以把问题快速收敛到“解析错误”“本机未监听”或“公网链路被拦截”三类。
片段示例:把 <DOMAIN> 替换为真实域名;标注“外部主机”的命令应在与目标服务器不同的公网网络执行。
DOMAIN="<DOMAIN>"
echo "A:"
dig +short A "$DOMAIN"
echo "AAAA:"
dig +short AAAA "$DOMAIN"
echo "LISTENER:"
sudo ss -ltnp '( sport = :80 )'
echo "LOCAL:"
curl --connect-timeout 5 -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1/
# 在外部主机执行
echo "PUBLIC:"
curl --connect-timeout 5 -sS -o /dev/null -w '%{http_code}\n' "http://$DOMAIN/"预期输出(示意,实际地址、进程名和状态码可能不同):
A:
<IP>
AAAA:
<IPV6_OR_EMPTY>
LISTENER:
LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("<PROCESS>",pid=<ID>,fd=<ID>))
LOCAL:
<HTTP_STATUS>
PUBLIC:
<HTTP_STATUS><HTTP_STATUS> 只要是三位 HTTP 状态码,就说明 TCP 连接已建立并收到 HTTP 响应;这里不要求首页必须返回 200。若外部测试仍出现 Connection refused,则公网到 80 端口的链路还没有打通。
验证与失败处理
ss 没有任何 80 端口监听时,先启动或修复 Nginx、Apache、反向代理或独立 challenge 服务,再确认监听地址不是仅绑定到错误接口。LOCAL 能返回状态码而 PUBLIC 被拒绝时,检查云安全组、主机防火墙、NAT 端口转发、负载均衡监听器和后端目标端口。
如果 DNS 指向错误服务器,先修正 A/AAAA 记录并等待权威 DNS 返回新值;不要通过反复重启 Certbot 规避解析问题。如果组织策略明确禁止开放公网 80 端口,就停止 HTTP-01 重试,改用适合当前 DNS 提供商的 DNS-01 验证方式。
恢复正常状态
临时修改过的防火墙、NAT 或负载均衡规则应与变更前配置逐项对照,只保留业务和续期真正需要的规则。若继续使用 HTTP-01 自动续期,必须确保后续验证时 80 端口仍可从公网到达;否则应在切换到 DNS-01 后再收紧 80 端口策略。
CA 无法在规定时间内访问 HTTP 验证地址;重点排查安全组、防火墙、路由、运营商端口限制以及公网地址是否真正指向当前服务器。
验证连接超时
目标是确认 HTTP-01 请求卡在“公网到服务器”的哪一层,并在重新执行 Certbot 前证明 TCP/80 已能从外部到达正确的 Web 入口。若外部请求已经返回任意 HTTP 状态码,说明“连接超时”这一层基本排除,应继续检查挑战路径或 Web 配置。
前置条件
- 能查看域名的 A/AAAA 记录,并知道当前服务器、负载均衡或公网入口的真实地址。
- 具备云安全组、防火墙或主机防火墙的查看权限;修改前先记录现有规则,避免误放行其他端口。
- 当前使用 HTTP-01 验证。该方式要求 CA 能从公网访问 TCP/80;仅开放 443 不能替代初始的 HTTP-01 访问。
- 若存在 CDN、WAF、反向代理或负载均衡,需要同时确认它们的 80 端口监听与回源路径。

排查步骤
- 先核对 DNS。A 记录应指向当前 IPv4 公网入口;如果保留 AAAA 记录,也要确认 IPv6 入口确实可达且能把 80 端口转发到同一站点。旧公网 IP、失效 AAAA 或 CDN 源站切换未完成都会把 CA 引向错误位置。
- 在服务器上确认 Web 服务确实监听 TCP/80;只监听
127.0.0.1:80时,公网请求无法直接进入。 - 从服务器之外的网络测试
http://<DOMAIN>/.well-known/acme-challenge/probe。重点看是否能建立 TCP 连接;即使返回 404,也比超时更进一步,说明公网链路已经到达 Web 服务器。 - 如果仍超时,按“云安全组或边界 ACL → 路由/NAT/负载均衡 → 主机防火墙 → Web 服务监听”顺序检查。每改一层就立即重测,不要同时修改多处,否则难以定位真正原因。
# 在目标服务器执行:确认 80 端口是否监听
sudo ss -ltnp 'sport = :80'
# 在服务器之外的另一台主机执行:验证公网 TCP/HTTP 是否可达
curl -4 -v --connect-timeout 5 "http://<DOMAIN>/.well-known/acme-challenge/probe"预期输出:第一条应出现 0.0.0.0:80、[::]:80 或实际对外监听地址;第二条只要成功建立连接并收到 HTTP 状态行即可。PID、地址和状态码会因环境不同而变化。
LISTEN ... 0.0.0.0:80 ... users:(("nginx",pid=<ID>,fd=<ID>))
< HTTP/1.1 404 Not Found验证与失败处理
外部访问能够稳定返回 200、301、302、403 或 404 等 HTTP 响应后,网络层已具备可达性;接下来再验证 /.well-known/acme-challenge/ 是否能返回正确挑战内容。若只有内网或本机可访问,而外部仍超时,问题仍在公网入口、防火墙、路由或运营商端口限制,不应转去修改 Certbot 参数。
如果服务器位于家庭宽带、企业出口或托管网络,还要确认上游是否屏蔽入站 80。无法开放 80 时,不要继续强行使用 HTTP-01,应改用与 DNS 提供商兼容的 DNS-01 方案。
恢复正常状态
保留修复后确有必要的 80 端口规则,否则自动续期仍会再次失败。若排查时临时放宽了过大的来源范围或其他端口,恢复为最小必要规则,并记录变更。确认后可再次运行原有 Certbot 续期或签发流程;如仍失败,再根据新的 HTTP 状态码进入对应路径排查。
验证请求已经到达 Web 服务器,但挑战文件没有从预期目录返回;常见原因是 Webroot 设置错误、Nginx root 不一致或请求被其他 location 接管。
挑战地址返回 404
目标是让 http://<DOMAIN>/.well-known/acme-challenge/<TOKEN> 精确映射到 Certbot 写入的 Webroot 文件。出现 404 说明请求已到达 Web 服务器,排查重点应从网络层转到“Certbot 写入目录”和“Web 服务器实际读取目录”是否一致。
前置条件
- 已确认 HTTP-01 请求能够从公网到达当前 Web 服务器,不再出现连接超时。
- 知道 Certbot
--webroot -w使用的目录,并具备读取 Nginx/Apache 生效配置和该目录文件的权限。 - 修改 Web 配置前先保存当前配置;若站点后面还有 CDN、反向代理或容器挂载,也要确认它们没有改写挑战路径。
- 以下示例以 Nginx 与 Webroot 模式为主;使用
--nginx、Apache 插件或容器化 Certbot 时,应核对对应插件或挂载后的实际路径。

定位 404 来源
先确认 Certbot 与 Web 服务器看到的是同一个目录。Webroot 模式会把挑战文件写到 <WEBROOT>/.well-known/acme-challenge/;Nginx 对该 URI 的 root 也必须能映射到同一文件。若站点有多个 server、正则 location、proxy_pass 或 SPA 回退规则,请特别检查挑战路径是否被其他规则提前接管。
可先查看 Nginx 的完整生效配置,而不是只看某个可能未被加载的文件:
sudo nginx -T 2>&1 | grep -nE 'server_name|root|acme-challenge|proxy_pass'预期输出:应能找到 <DOMAIN> 对应的 server_name、实际 root,以及挑战路径相关 location。行号和路径会随环境变化。
<LINE>: server_name <DOMAIN>;
<LINE>: root <PATH>;
<LINE>: location ^~ /.well-known/acme-challenge/ {如果根目录不一致,优先统一 Webroot 和站点根目录。一个常见且清晰的 Nginx 写法如下,属于配置片段,需放入 <DOMAIN> 对应的 server 块后再执行 nginx -t 验证:
location ^~ /.well-known/acme-challenge/ {
root <PATH>;
try_files $uri =404;
}这里的 <PATH> 应与 Certbot -w <PATH> 一致。使用 root 时,请求 /.well-known/acme-challenge/<TOKEN> 会映射到 <PATH>/.well-known/acme-challenge/<TOKEN>;不要把 root 和 alias 的路径语义混用。
生成探针并验证
先不要立即重新申请证书,手工放置一个探针文件验证路径映射。以下命令在目标服务器执行;把 <DOMAIN> 和 <PATH> 替换为真实值:
DOMAIN="<DOMAIN>"
WEBROOT="<PATH>"
sudo install -d -m 755 "$WEBROOT/.well-known/acme-challenge"
printf '%s\n' 'probe-ok' | sudo tee "$WEBROOT/.well-known/acme-challenge/probe" >/dev/null
curl -fsS --resolve "$DOMAIN:80:127.0.0.1" \
"http://$DOMAIN/.well-known/acme-challenge/probe"预期输出:
probe-ok本机验证通过后,再从服务器外部访问同一 URL。若本机返回 probe-ok、公网仍返回 404,继续检查 CDN/WAF、负载均衡、反向代理或不同节点之间的静态文件是否一致;若本机也 404,优先检查 Nginx server_name、root、location 优先级和文件权限。
验证与失败处理
修改 Nginx 后先做语法检查,再重载配置;语法检查失败时必须停止,不要强制重载。
sudo nginx -t && sudo systemctl reload nginx预期输出:nginx -t 应报告配置语法有效且测试成功;systemctl reload 成功时通常没有额外输出。
nginx: configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful恢复与清理
确认公网也能读取探针后,删除临时文件,再按原计划运行 Certbot。若排查中新增了临时 Nginx 配置,只保留续期仍需要的挑战路径规则;其余改动应恢复到变更前版本,并再次执行 nginx -t 与外部探针检查,确保站点正常且后续自动续期仍有可用路径。
HTTP-01 可以跟随有限的 HTTP 或 HTTPS 重定向,但错误跳转、循环跳转或跳到其他主机会导致验证异常;应单独确认挑战路径的最终响应。
挑战地址被错误重定向
目标是让 http://<DOMAIN>/.well-known/acme-challenge/<TOKEN> 在有限重定向后返回状态码 200,并且响应体与当前挑战要求的内容完全一致;站点其他路径仍可继续执行原有的 HTTP 到 HTTPS 或主域跳转。
前置条件
- 能查看并修改实际接收公网 80 端口流量的 Web 服务器、反向代理或 CDN 规则,并已备份当前配置。
- DNS 的 A/AAAA 记录指向预期入口,公网 80 端口可达;多入口场景要确认每个可能被访问的节点行为一致。
- 排查时应取得仍然有效的挑战 URL 和预期响应值。Certbot 的
--debug-challenges可让挑战在提交给 CA 前暂停,配合详细输出核对 URL 与期望值。
HTTP-01 允许有限的 HTTP/HTTPS 重定向,但最终链路必须可访问。跳到另一主机本身并不等于失败,真正要检查的是是否形成循环、是否超过重定向上限、是否跳到非 80/443 端口,或最终返回了主页、登录页、404 等错误内容。
定位重定向链
在挑战仍然存在时,从公网可访问的位置请求完整路径,并同时观察最终 URL、状态码和跳转次数:
# 跟随重定向,同时保留最终状态、URL 和跳转次数。
curl --location --max-redirs 10 --silent --show-error \
--write-out '\nstatus=%{http_code}\nfinal=%{url_effective}\nredirects=%{num_redirects}\n' \
"http://<DOMAIN>/.well-known/acme-challenge/<TOKEN>"预期输出:
<EXPECTED_CHALLENGE_BODY>
status=200
final=<FINAL_CHALLENGE_URL>
redirects=<N>其中 <EXPECTED_CHALLENGE_BODY> 必须逐字等于本次挑战要求的内容,<N> 应不超过 10。若看到重定向循环、最终状态不是 200,或最终正文变成站点首页、认证页、WAF 页面,就应先停止重试签发并修正规则。
修正挑战路径规则
优先让 /.well-known/acme-challenge/ 绕过与证书验证无关的主域跳转、登录跳转和应用路由。以下是 Nginx 片段示例,需要放在 <DOMAIN> 的 80 端口 server 块中,并把占位值替换为真实配置;若原来在 server 级直接 return,应把通用跳转下移到 location /,否则挑战路径仍会先被重定向。
# 挑战路径直接读取 Webroot,不进入全站重定向。
location ^~ /.well-known/acme-challenge/ {
root <WEBROOT>;
try_files $uri =404;
}
# 其他请求继续执行原有规范主机跳转。
location / {
return 301 https://<CANONICAL_HOST>$request_uri;
}该配置的生效行为是:挑战路径直接从 <WEBROOT>/.well-known/acme-challenge/ 读取文件,其他请求继续跳到规范 HTTPS 主机。修改后先执行 Web 服务器自身的配置检查,再 reload;检查失败时不要强制重载。非 Nginx 环境也应实现同样的“挑战路径例外、其他路径照常跳转”语义。
验证与失败处理
重新执行前面的 curl 检查。若挑战文件存在,应看到 200、可接受的最终 URL 和完全匹配的响应体。若本机正常、外部仍失败,继续检查 CDN/WAF、负载均衡、IPv6 入口和多个后端是否使用了不同规则。
若跳转链本身正确但正文不匹配,问题通常已从“重定向”转为“挑战文件位置或内容错误”;此时不要继续修改跳转规则,应转查实际 document root、Webroot 映射或代理缓存。
回滚方式
如果规则调整导致普通站点路径异常,立即恢复备份配置并 reload,使原有流量先恢复正常。不要通过删除全站 HTTPS 跳转来长期规避问题;稳定做法是只为挑战路径保留一条可验证、可重复续期的访问链路。
Certbot 写入挑战文件的目录与 Web 服务器实际对外目录不一致时,文件存在于磁盘却无法通过域名访问;应以公网请求对应的真实 document root 为准。
Webroot 路径配置错误
目标是确认 Certbot 的 -w <WEBROOT> 与该域名在公网实际使用的 document root 完全一致,使写入 <WEBROOT>/.well-known/acme-challenge/<TOKEN> 的文件能够通过 http://<DOMAIN>/.well-known/acme-challenge/<TOKEN> 原样读取。
前置条件
- 能读取当前虚拟主机、反向代理或容器挂载配置,并已备份准备修改的 Web 服务器配置。
- 对候选 Webroot 目录具备写权限;生产环境不要为了排障把整个站点目录改成宽松权限。
- 公网 80 端口可到达该站点;如果前面还有 CDN、负载均衡或多个后端,需要确认请求最终落到使用同一份挑战文件的节点。
- Web 服务器必须允许访问
/.well-known/acme-challenge/,不能被“禁止隐藏目录”或应用级路由规则截获。
用探针确认真实 Webroot
不要先相信配置文件中的目录名。把一个临时探针写入候选 Webroot,再通过域名读取;只有磁盘路径和公网 URL 同时对应,才说明 -w 选对了。
set -euo pipefail
WEBROOT="<WEBROOT>"
DOMAIN="<DOMAIN>"
TOKEN="anystack-webroot-probe"
FILE="$WEBROOT/.well-known/acme-challenge/$TOKEN"
# 退出时自动清理探针,避免把测试文件留在生产目录。
mkdir -p "$(dirname "$FILE")"
trap 'rm -f "$FILE"' EXIT
printf '%s\n' 'webroot-ok' > "$FILE"
# 必须通过公网域名读取,不能只检查本地文件是否存在。
curl --fail --silent --show-error \
"http://$DOMAIN/.well-known/acme-challenge/$TOKEN"预期输出:
webroot-ok实际 <WEBROOT>、域名和文件权限因环境而异。若文件在磁盘存在但请求返回 404、403、应用页面或其他正文,说明当前候选目录不是公网请求实际读取的位置,或挑战路径被额外规则拦截。
修正 Certbot 映射
确认探针成功后,Webroot 模式应把同一个目录传给 Certbot,例如 certbot certonly --webroot -w <WEBROOT> -d <DOMAIN>。多个域名若使用不同 document root,应分别在对应域名前指定正确的 -w;后续域名会继承最近一次给出的 Webroot,不能把一组域名误绑到同一目录。
常见误区是把项目源码目录、容器宿主机目录或 Nginx 配置文件所在目录当成 Webroot。判断依据只有一个:公网请求 /.well-known/acme-challenge/<TOKEN> 最终实际读取哪个文件系统路径。
验证与失败处理
先让探针请求稳定返回 webroot-ok,再重新执行证书签发或续期。若探针失败,停止反复运行 Certbot,因为挑战文件即使成功创建,也仍会被 CA 从错误位置读取。
若返回 403,检查 Web 服务器是否禁止点目录;若返回应用的 404 页面,检查挑战路径是否被转发给框架;若只有部分请求成功,检查 IPv4/IPv6、负载均衡后端和容器副本是否共享同一挑战目录。
回滚方式
探针脚本会在退出时删除临时文件。若排障期间修改了虚拟主机 root、容器挂载或挑战路径例外规则,验证完成后只保留续期真正需要的最小改动;一旦站点静态资源或路由异常,应恢复备份配置并 reload,再重新确认正确的 Webroot,而不是继续扩大目录权限。
A 或 AAAA 记录仍指向旧主机、代理节点或其他服务器时,CA 会在错误机器上执行验证;申请前应确认公网 DNS 与当前部署地址一致。
域名解析到错误服务器
目标是在重新执行 Certbot 前确认公网 DNS 已指向真正负责 ACME 验证的入口,避免挑战文件已经正确生成,却被 CA 请求到了旧服务器、错误代理节点或其他主机。
前置条件
- 已知域名
<DOMAIN>当前应使用的公网 IPv4,以及启用 IPv6 时对应的公网 IPv6。 - 具备 DNS 记录查看或修改权限,并记录修改前的 A、AAAA、CNAME 与 TTL,便于出现业务影响时恢复。
- 本机已安装
dig与curl。 - 如果域名前有 CDN、反向代理或负载均衡,DNS 指向代理地址可能完全正常;此时要确认代理能够把
/.well-known/acme-challenge/请求送到正确后端,而不是强行改成源站 IP。
检查公网解析
先从多个递归 DNS 解析器观察 A、AAAA,再检查 HTTP 请求实际连接到的地址。多个 A 或 AAAA 记录并不一定是错误,但其中每个可能接收验证流量的入口都必须能正确处理挑战请求。
DOMAIN="<DOMAIN>"
printf 'Cloudflare DNS - A:\n'
dig @1.1.1.1 +short "$DOMAIN" A
printf 'Google DNS - A:\n'
dig @8.8.8.8 +short "$DOMAIN" A
printf 'Cloudflare DNS - AAAA:\n'
dig @1.1.1.1 +short "$DOMAIN" AAAA
printf 'Google DNS - AAAA:\n'
dig @8.8.8.8 +short "$DOMAIN" AAAA
printf 'HTTP endpoint:\n'
curl --max-time 10 -sS -o /dev/null -w 'remote_ip=%{remote_ip} status=%{http_code}\n' "http://$DOMAIN/.well-known/acme-challenge/probe"预期结果:两个公共解析器看到的记录应与当前部署设计一致;若直接暴露源站,A 应包含 <EXPECTED_IPV4>,启用 IPv6 时 AAAA 应包含 <EXPECTED_IPV6>。测试路径返回 404 等 HTTP 状态并不代表挑战已成功,它只说明该 HTTP 入口产生了响应;重点是解析地址和实际请求入口不能仍落到已经下线的旧服务器。
Cloudflare DNS - A:
<EXPECTED_IPV4>
Google DNS - A:
<EXPECTED_IPV4>
Cloudflare DNS - AAAA:
<EXPECTED_IPV6_OR_EMPTY>
Google DNS - AAAA:
<EXPECTED_IPV6_OR_EMPTY>
HTTP endpoint:
remote_ip=<REMOTE_IP> status=<HTTP_STATUS><DOMAIN>、IP 和状态码都要替换或按现场结果判断,代理/CDN 场景中的 <REMOTE_IP> 通常是代理节点而不是源站。
修正解析并等待缓存更新
如果 A、AAAA 或 CNAME 确实仍指向旧入口,在 DNS 服务商处改为当前部署所需的值。不要在没有确认用途时删除其他记录,尤其要先确认 AAAA、CDN 代理和负载均衡是否仍承担生产流量。
修改后再次运行上面的查询。权威 DNS 已更新并不意味着所有递归缓存立即失效;旧记录可能持续到原 TTL 到期,因此至少要等常用公共解析器看到新值后再重新发起证书验证。
验证与失败处理
DNS 正确后,再执行原先使用的 Certbot 申请或续期命令。如果仍然验证失败,应检查错误信息中的域名、目标地址和 HTTP 状态,并进一步确认端口 80、防火墙、虚拟主机以及 /.well-known/acme-challenge/ 路径,而不是继续修改已经正确的 DNS。
如果不同公共解析器长期得到不同结果,先检查 DNS 提供商是否确实保存了修改,以及域名当前使用的权威 NS 是否就是你修改的那一组服务器。未确认公网解析一致前应停止重复申请。
回滚方式
DNS 修改后若正常业务流量异常,应根据事先记录恢复原 A、AAAA 或 CNAME,并重新验证解析与业务访问。恢复旧记录只能用于恢复业务入口;如果旧入口本身无法完成 ACME 验证,还需要先设计正确的代理转发或新的 DNS 切换方案,再重新申请证书。
域名存在 AAAA 记录但服务器 IPv6 未正确配置时,外部验证可能访问不可用的 IPv6 地址;应修复 IPv6 服务或移除不再使用的错误 AAAA 记录。
IPv6 导致验证失败
目标是确认域名的 AAAA 记录是否把 ACME 验证引向不可用或配置错误的 IPv6 服务,并在保留 IPv6 或删除错误 AAAA 之间做出明确处理,使 IPv4、IPv6 与实际 Web 服务配置保持一致。
前置条件
- 已确认域名
<DOMAIN>是否计划对公网提供 IPv6;不要仅为了让证书申请通过而删除仍承担生产流量的有效 AAAA。 - 具备 DNS 修改权限,并记录当前 AAAA、TTL 和原始 IPv6 地址。
- 如果计划保留 IPv6,服务器必须具备可用的公网 IPv6 路由,防火墙允许 HTTP-01 所需的 TCP 80,Web 服务也必须在 IPv6 上接受该域名的请求。
- 本机已安装
dig与curl,且执行测试的网络环境本身具有 IPv6 连通性。
分别测试 IPv4 与 IPv6
不要只测试浏览器是否能打开网站。浏览器可能自动使用可用地址,使损坏的 IPv6 路径被 IPv4 掩盖。分别强制 curl 使用两个地址族,可以直接判断 AAAA 对应链路是否可达。
DOMAIN="<DOMAIN>"
printf 'A records:\n'
dig +short "$DOMAIN" A
printf 'AAAA records:\n'
dig +short "$DOMAIN" AAAA
printf 'IPv4 HTTP:\n'
curl -4 --max-time 10 -sS -o /dev/null -w 'remote_ip=%{remote_ip} status=%{http_code}\n' "http://$DOMAIN/.well-known/acme-challenge/probe"
printf 'IPv6 HTTP:\n'
curl -6 --max-time 10 -sS -o /dev/null -w 'remote_ip=%{remote_ip} status=%{http_code}\n' "http://$DOMAIN/.well-known/acme-challenge/probe"预期结果:如果保留 AAAA,IPv6 请求应能连接到预期 IPv6 入口并得到 HTTP 响应;404 等状态只能证明请求已经到达某个 Web 服务,不能证明真实 ACME token 会被正确返回。如果 IPv4 正常而 IPv6 超时、拒绝连接或到达错误服务器,应先修复 IPv6,而不是依赖验证过程自动绕过它。
A records:
<EXPECTED_IPV4>
AAAA records:
<EXPECTED_IPV6>
IPv4 HTTP:
remote_ip=<EXPECTED_IPV4_OR_PROXY> status=<HTTP_STATUS>
IPv6 HTTP:
remote_ip=<EXPECTED_IPV6_OR_PROXY> status=<HTTP_STATUS><DOMAIN>、地址和状态码均为动态值;如果执行测试的客户端没有 IPv6 网络,curl -6 失败本身不能证明服务器 IPv6 有故障,应换到具备公网 IPv6 的测试环境继续确认。
选择修复方式
如果业务需要 IPv6,保留 AAAA,并逐项修复服务器地址、IPv6 默认路由、安全组或防火墙、Web 服务监听地址和虚拟主机配置。修复后必须再次确认 IPv6 上的 HTTP 请求进入与 IPv4 等价的 ACME 挑战处理路径。
如果业务明确不再使用 IPv6,并确认 AAAA 是遗留或错误配置,可以删除该 AAAA。修改后等待原 TTL 对应的递归缓存过期,并使用公共 DNS 再次确认域名已经不再发布旧 IPv6 地址。
如果域名位于 CDN 或反向代理之后,AAAA 可能属于代理服务而非源站。此时不应根据源站没有 IPv6 就直接删除记录,而应确认代理的 IPv6 入口能够正确转发 ACME 请求。
验证与失败处理
修复 IPv6 或清理错误 AAAA 后,再执行原 Certbot 申请或续期命令。仍失败时,重点核对 CA 错误信息中访问到的地址,以及 IPv6 上端口 80、HTTP 重定向和挑战路径是否与 IPv4 行为一致。
回滚方式
如果删除或修改 AAAA 后导致原本依赖 IPv6 的客户端无法访问,应恢复事先记录的 DNS 值,并先修复正确的 IPv6 服务再重新切换。若旧 AAAA 本来就指向错误服务器,不要把恢复错误地址当作长期方案;回滚的目的只是恢复必要业务,再完成受控修复。
HTTP-01 的公网验证固定从 80 端口开始,修改 Certbot 本地监听端口不能改变 CA 的访问端口;需要开放 80,或改用适合场景的 DNS-01。
让 HTTP-01 真正从 80 端口可达
目标是让公网 CA 能通过 http://<DOMAIN>/.well-known/acme-challenge/<TOKEN> 访问到当前服务器生成的挑战内容。HTTP-01 的公网入口是 TCP 80;Certbot 的本地监听参数只能改变本机接收挑战的端口,不能要求 CA 改用其他公网端口。

前置条件
- 域名的 A/AAAA 记录应指向实际承接 HTTP-01 的公网入口;如果同时发布 IPv4 和 IPv6,两条路径都要能正确到达服务。
- 云安全组、主机防火墙、路由器或负载均衡器允许入站 TCP 80,并把请求转到正确主机。
- 使用
standalone时确认 80 端口没有被其他进程占用;生产站点不宜为了验证而长时间停服,可优先使用现有 Web 服务器的 webroot 或对应插件。 - 修改防火墙、NAT 或 Web 配置前记录原值,确保验证结束后可以恢复。
检查公网路径
先在 Web 根目录放一个一次性探针,再从外部网络访问它。下面示例假设站点根目录为 /var/www/html;实际路径不同就替换 WEBROOT。
DOMAIN=example.com
WEBROOT=/var/www/html
sudo mkdir -p "$WEBROOT/.well-known/acme-challenge"
printf 'certbot-http01-check\n' | sudo tee "$WEBROOT/.well-known/acme-challenge/probe.txt" >/dev/null
curl -fsS "http://$DOMAIN/.well-known/acme-challenge/probe.txt"预期输出:
certbot-http01-check能得到该内容,说明 DNS、公网 80 端口和挑战路径至少在当前网络路径上已经贯通。若本机访问成功而外部网络失败,应优先检查安全组、NAT、边界防火墙和负载均衡转发,而不是继续调整 Certbot 的本地端口。
修复与验证
如果 80 端口根本没有监听,可用 sudo ss -ltnp 'sport = :80' 检查当前进程。使用反向代理或 Web 服务器时,应保证 /.well-known/acme-challenge/ 不被应用路由、登录页或统一跳转规则吞掉。
修复后重新执行原来的签发命令或 certbot renew --dry-run 验证。若仍出现连接超时或拒绝连接,先停止继续重试,确认公网探针能够稳定返回后再申请证书;如果网络策略长期不允许开放 80,应改用 DNS-01。
恢复现场
验证完成后删除探针文件,并撤销仅为排查临时添加的防火墙或转发规则。若曾停止生产 Web 服务,确认其已恢复并重新监听 80/443;保留 HTTP-01 所必需的长期规则,否则后续自动续期仍会失败。
CDN、WAF 或反向代理可能缓存、拦截或改写挑战请求,使 CA 无法获取 Certbot 生成的内容;应确认挑战路径能够稳定到达正确源站。
排除 CDN 或代理对 HTTP-01 的干扰
目标是确保 CA 请求 /.well-known/acme-challenge/<TOKEN> 时,CDN、WAF 和反向代理不会缓存旧内容、拦截请求或把它改写到错误源站。验证成功的标准是:公网连续请求都能拿到当前源站刚写入的挑战内容。

前置条件
- 已确认域名当前是否经过 CDN、WAF、负载均衡或反向代理,以及真正写入挑战文件的源站和 Web 根目录。
- 具备调整缓存、WAF、鉴权和路由规则的权限,并记录当前策略以便恢复。
- 如果计划临时绕过 CDN,先确认直接暴露源站不会违反安全策略,也不会让错误源站接管流量。
检查是否命中当前源站
用同一个公开 URL 连续读取两次,但在两次读取之间修改源站文件。第二次必须立刻返回新内容;如果仍得到旧值,通常说明中间层缓存了挑战路径或请求没有到达预期源站。
DOMAIN=example.com
WEBROOT=/var/www/html
PROBE="$WEBROOT/.well-known/acme-challenge/proxy-check"
sudo mkdir -p "$(dirname "$PROBE")"
printf 'origin-v1\n' | sudo tee "$PROBE" >/dev/null
curl -fsS "http://$DOMAIN/.well-known/acme-challenge/proxy-check"
printf 'origin-v2\n' | sudo tee "$PROBE" >/dev/null
curl -fsS "http://$DOMAIN/.well-known/acme-challenge/proxy-check"预期输出:
origin-v1
origin-v2如果第二次仍是 origin-v1、返回 403/429/5xx,或不同网络拿到不同内容,就不要继续触发证书申请;先处理 CDN/WAF/代理路径。
修复挑战路径
优先对 /.well-known/acme-challenge/ 做最小范围例外:关闭缓存,绕过登录鉴权、Bot Challenge 和会改写响应体的规则,并确保请求路由到 Certbot 实际写入文件的源站。若有多层代理,应确保挑战路径始终按预期路由到正确源站,避免把请求重写到应用首页或其他后端。
验证与失败处理
修复后再次运行上面的双写探针,并从至少一个不经过本地缓存的外部网络复查。只有内容能立即随源站更新,才重新执行 Certbot。若失败仅发生在某些地区或某些 CDN 节点,应继续排查边缘缓存和分流规则,而不是反复重试 ACME 请求。
恢复代理策略
排查结束后删除 proxy-check 文件,并恢复为本次排障临时关闭的安全策略。若后续自动续期仍依赖 HTTP-01,则应保留对挑战路径所需的最小例外;否则下一次续期会再次被缓存、WAF 或鉴权规则阻断。
Nginx 集成故障
Certbot Nginx 插件需要读取并修改有效配置;如果 Nginx 本身存在语法错误、重复指令或证书路径异常,应先修复配置再重新运行 Certbot。
Nginx 配置测试失败
目标是先让 Nginx 配置检查恢复为成功状态,再重新运行 Certbot。只要 nginx -t 仍失败,就不要 reload Nginx,也不要反复执行 Certbot 试图绕过配置错误。
前置条件
- 操作账号具备
sudo权限,并能读取 Nginx 配置和错误信息。 - 修改任何站点配置前先保留备份,尤其是生产环境中的
server块和 TLS 配置。 - 已运行的 Nginx 如果仍正常提供服务,不要因为磁盘上的新配置测试失败而直接重启服务。
定位失败位置
先执行 Nginx 自带的配置检查。错误通常会直接指出问题类型以及对应配置文件和行号。
sudo nginx -t预期结果:修复完成后应看到类似以下成功信息;实际主配置路径可能不同。
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful如果输出包含 [emerg],先按照其中的文件和行号修复,不要继续运行 Certbot。常见情况包括指令拼写或分号错误、同一上下文中不允许重复的指令,以及 ssl_certificate 或 ssl_certificate_key 指向不存在或无法读取的文件。
检查实际加载的配置
当单个配置文件看起来正常,但测试仍失败时,可展开 Nginx 最终加载的完整配置,确认错误是否来自其他 include 文件。
sudo nginx -T 2>&1 | grep -nE 'server_name|ssl_certificate|ssl_certificate_key'预期结果:命令会列出当前加载配置中匹配的指令及行号;具体域名、文件路径和行号取决于服务器实际配置。如果命令前半部分仍报告 [emerg],应优先处理该错误。
验证与失败处理
每次只修改一类问题,然后重新执行 sudo nginx -t。只有配置测试成功后,才执行 sudo systemctl reload nginx,随后重新运行原来的 Certbot 命令。
如果修改后出现更多错误,停止继续叠加变更,恢复修改前的配置备份,再从 nginx -t 报出的第一处错误重新排查。这样可以避免把 Certbot 问题扩大为 Nginx 服务故障。
Nginx 插件无法把域名对应到现有站点时,通常需要检查 server_name 是否包含申请域名,以及配置文件是否已经被 Nginx 正确加载。
找不到匹配的 Server Block
目标是让 Certbot Nginx 插件能够在实际加载的 Nginx 配置中找到申请域名对应的 server 块。关键检查点不是“配置文件是否存在”,而是目标域名是否出现在已经被 Nginx 加载的 server_name 中。
前置条件
- 操作账号具备读取 Nginx 配置和执行
sudo nginx -T的权限。 - 修改站点配置前已保留备份,并确认当前 Nginx 服务仍可正常工作。
- 申请证书的域名已经确定;后续证书验证还要求该域名的 DNS 能正确指向提供验证响应的服务器。
查找已加载的域名
下面以 example.com 为例检查 Nginx 最终加载的配置,而不是只搜索某个配置目录。
DOMAIN=example.com
sudo nginx -T 2>&1 | grep -nE "server_name[[:space:]].*${DOMAIN}"预期结果:如果存在可匹配的站点,会看到包含目标域名的 server_name 行;行号和其他域名会因实际配置不同而变化。
<LINE>: server_name example.com www.example.com;如果没有任何匹配结果,说明目标域名没有出现在当前加载配置的 server_name 中。即使某个文件已经写好,只要它没有通过 include 链路被加载,Certbot 仍无法把域名映射到该站点。
修正 Server Block
在负责该站点的现有 server 块中加入准确的域名,例如 server_name example.com www.example.com;。不要写成 https://example.com,也不要附带路径或端口;server_name 保存的是主机名匹配规则。
如果配置只存在于未启用的文件中,应按照当前 Nginx 的目录组织方式把它纳入实际 include 链路,而不是复制出多个内容相同的 server 块。仅有 server_name _; 之类的兜底站点,也不能代替目标域名的明确匹配。
验证配置生效
修改完成后先测试,再重新加载 Nginx。测试失败时必须停止,不要执行 reload。
sudo nginx -t && sudo systemctl reload nginx预期结果:配置检查成功,并且 reload 命令正常返回;nginx -t 通常会显示以下信息。
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful随后再次运行前面的 nginx -T 查询,确认目标域名确实出现在加载结果中,再重试原来的 Certbot Nginx 命令。
失败处理与回滚
如果 nginx -T 仍找不到域名,检查站点文件是否被主配置或其他 include 指令加载,以及是否修改了错误的 Nginx 实例或配置根目录。如果 nginx -t 因修改而失败,立即恢复备份并再次测试,确认 Nginx 回到原先可用状态后再继续排查。
Certbot 已签发证书不代表站点一定加载了它;应检查 HTTPS Server Block、证书文件路径以及 Nginx 是否完成配置重载,避免仍使用旧证书或其他虚拟主机。
证书申请成功但 HTTPS 未生效
目标是确认 Nginx 当前命中的 443 Server Block 确实引用 Certbot 刚签发的证书,并完成安全重载。验证完成时,线上 TLS 握手返回的证书序列号应与本机证书一致。
前置条件
- 操作账号具备
sudo权限,并已备份准备修改的 Nginx 站点配置。 - 已确认域名解析指向当前服务器;如果公网 TLS 由 CDN、负载均衡器或 Ingress 终止,必须在对应终止层更新证书,仅修改 Nginx 不会改变客户端看到的证书。
- 不要假定证书目录一定等于域名。Certbot 发生重名时,证书名称可能带
-0001等后缀,应以实际输出为准。
确认证书位置
先列出 Certbot 当前管理的证书,记录目标证书的名称、证书路径和私钥路径。
sudo certbot certificates预期结果:
Certificate Name: <CERT_NAME>
Certificate Path: /etc/letsencrypt/live/<CERT_NAME>/fullchain.pem
Private Key Path: /etc/letsencrypt/live/<CERT_NAME>/privkey.pem实际输出还会包含域名和到期时间;后续配置必须使用这里显示的真实路径。
检查并重载 Nginx
将 <DOMAIN> 和 <CERT_NAME> 替换为实际值。先检查最终生效配置,再做语法测试;只有 nginx -t 成功后才执行重载。
DOMAIN='<DOMAIN>'
CERT_NAME='<CERT_NAME>'
sudo nginx -T | grep -nE 'server_name|listen 443|ssl_certificate|ssl_certificate_key'
sudo nginx -t
sudo systemctl reload nginx
sudo openssl x509 -in "/etc/letsencrypt/live/$CERT_NAME/fullchain.pem" -noout -serial -dates
openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" </dev/null 2>/dev/null | openssl x509 -noout -serial -dates预期结果:
server_name <DOMAIN>;
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/<CERT_NAME>/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/<CERT_NAME>/privkey.pem;
nginx: configuration file <PATH> test is successful
serial=<SERIAL>
notBefore=<TIME>
notAfter=<TIME>
serial=<SERIAL>
notBefore=<TIME>
notAfter=<TIME>两组 serial 应相同;日期也应对应同一张新证书。nginx -T 若显示多个 Server Block 同时声明同一域名,应先消除重复配置,避免请求命中错误的虚拟主机。
失败处理
如果 nginx -t 失败,停止重载并修正报错中的文件路径、权限或语法。最常见的问题是 ssl_certificate 或 ssl_certificate_key 指向不存在的旧目录。
如果本机证书与线上证书序列号不同,说明流量没有使用这份配置。继续检查域名是否解析到其他主机,以及 CDN、负载均衡器、容器入口或其他反向代理是否承担了 TLS 终止。
回滚
若修改 Nginx 后验证失败,恢复操作前备份的 Server Block,再执行语法检查并重载。不要手工覆盖 /etc/letsencrypt/live/ 下的 Certbot 符号链接;需要退回旧证书时,应把 Nginx 路径明确切回已知稳定证书后再验证。
DNS-01 验证故障
HTTP-01 不能验证通配符域名;申请 *.example.com 一类证书必须使用 DNS-01,并确保 _acme-challenge TXT 记录能够被公网权威 DNS 查询到。
通配符证书申请失败
目标是改用 DNS-01 完成通配符域名验证,并确认 _acme-challenge TXT 记录已经同步到公网权威 DNS。只有权威 DNS 能返回 Certbot 本次给出的验证值时,才继续 ACME 验证。
前置条件
- 你必须能修改目标域名的权威 DNS 区域,并有权限新增或删除 TXT 记录。
- 本机需要可用的
certbot;下方验证命令还需要dig。 *.example.com不覆盖根域名example.com。如果两者都要使用同一张证书,应同时申请根域名和通配符域名。- 手工
--manual模式不会自动完成无人值守续期。生产环境长期使用时,优先改用 DNS 服务商插件或受控的 DNS API Hook。
启动 DNS-01 验证
将 <DOMAIN> 替换为根域名,例如 example.com。Certbot 会暂停并要求你发布 TXT 记录,此时不要提前确认验证。
DOMAIN='<DOMAIN>'
sudo certbot certonly --manual --preferred-challenges dns -d "$DOMAIN" -d "*.$DOMAIN"预期结果:终端会给出本次挑战需要发布的关键信息。
Record name: _acme-challenge.<DOMAIN>
Record value: <TOKEN>实际提示文字会随 Certbot 版本变化,但必须以终端给出的 <TOKEN> 为准。如果同一次申请为同一记录名给出多个 TXT 值,应保留所有仍在本次验证中使用的值,直到签发流程完成。
从权威 DNS 验证
在返回 Certbot 按回车继续之前,直接查询每台权威 DNS。只有所有权威服务器都能看到本次 TXT 值,才应继续验证。
DOMAIN='<DOMAIN>'
for NS in $(dig +short NS "$DOMAIN"); do
echo "== $NS =="
dig +short TXT "_acme-challenge.$DOMAIN" @"$NS"
done预期输出:
== <AUTH_NS_1> ==
"<TOKEN>"
== <AUTH_NS_2> ==
"<TOKEN>"如果本次挑战有多个有效 TXT 值,对应服务器可能返回多行。所有权威 DNS 的结果应一致;只在某一台看到新值时,应继续等待或修复 DNS 同步问题。
完成验证与失败处理
确认 TXT 已传播后,返回原来的 Certbot 进程继续验证。签发成功后应看到证书保存路径;若仍失败,不要反复立即重试,应先根据错误类型定位。
查不到 TXT 时,重点检查记录名是否被 DNS 控制台自动追加了域名、是否误改了错误的 DNS 区域,以及 _acme-challenge 是否通过 CNAME 或 NS 委派到了另一处。若 TXT 已正确可见但签发仍被拒绝,再检查 CAA 限制、ACME 服务器返回的具体错误和频率限制。
自动续期与回滚
手工 DNS-01 适合临时排障,不适合作为长期无人值守方案。稳定后应改用支持当前 DNS 服务商的 Certbot DNS 插件或受控 Hook,并为 API 凭据设置最小权限。
申请证书本身不会立即改变线上 HTTPS。若本次操作中止,只删除为这次挑战临时新增且已确认不再使用的 TXT 值,不要删除同名记录下属于其他验证流程的值;继续保留当前生产证书,直到新证书部署并验证完成。
CA 查询 _acme-challenge 时没有得到预期 TXT 值;应检查记录名称、DNS 区域和内容是否正确,并确认修改已经提交到实际权威 DNS 服务商。
找不到 TXT 验证记录
目标是确认 _acme-challenge 查询究竟落到哪组权威 DNS,并让所有权威服务器都返回本次 DNS-01 挑战要求的 TXT 值。仅在某个 DNS 控制台里看到记录并不足以证明 CA 能查到它。
前置条件
- 已取得 Certbot 当前要求写入的 TXT 值,且挑战尚未失效。
- 能修改该域名当前实际使用的权威 DNS 区域。
- 修改前记录现有
_acme-challengeTXT 值,避免覆盖仍被其他证书任务使用的记录。 - 本机安装了
dig;以下<DOMAIN>应替换为实际申请证书的域名。
定位权威 DNS
先确认该域名委派到哪些权威服务器,再直接向这些服务器查询挑战记录。不要只查询本机默认解析器,因为它可能返回缓存结果。
DOMAIN="<DOMAIN>"
NAME="_acme-challenge.${DOMAIN}"
for ns in $(dig +short NS "${DOMAIN}"); do
echo "== ${ns} =="
dig +noall +answer @"${ns}" TXT "${NAME}"
done预期输出:如果记录确实缺失,对应服务器标题后没有 TXT 的 ANSWER 行;实际权威服务器名称会因域名而不同。
== <NS1> ==
== <NS2> ==如果这里查不到记录,先不要继续 Certbot 挑战。检查控制台中填写的是完整记录名还是相对主机名:有些服务商要求填写 _acme-challenge,有些要求填写 _acme-challenge.<DOMAIN>。同时确认正在编辑的 DNS 区域正是上一条命令返回的权威服务商,而不是旧账号、旧托管商或未生效的备用区域。
修正并验证
把 Certbot 给出的 TXT 值写入正确记录后,再次直接查询每台权威服务器。已有同名 TXT 时,不要为了本次验证删除不确定用途的其他值;DNS-01 场景允许同一名称暂时存在多个 TXT 值。
DOMAIN="<DOMAIN>"
NAME="_acme-challenge.${DOMAIN}"
for ns in $(dig +short NS "${DOMAIN}"); do
echo "== ${ns} =="
dig +noall +answer @"${ns}" TXT "${NAME}"
done预期输出:每台权威服务器都应包含本次挑战值;TTL、服务器名称和挑战字符串的实际值可能不同。
== <NS1> ==
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<CHALLENGE_VALUE>"
== <NS2> ==
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<CHALLENGE_VALUE>"只有部分权威服务器返回新值时,说明权威 DNS 本身尚未同步完成,应停止继续验证并等待或检查 DNS 服务商状态。
失败处理
若 NS 查询返回的服务商与你修改记录的位置不同,应到实际权威 DNS 服务商创建记录。若 _acme-challenge 使用了 CNAME 委派,还要沿 CNAME 目标检查 TXT 最终应写入的区域;不要在错误区域反复新增同名记录。
如果所有权威服务器都能返回正确 TXT,但 Certbot 仍失败,再检查缓存和等待时间,这属于“TXT 记录尚未传播”问题,而不是继续修改记录名称。
恢复状态
证书验证成功后,可删除仅为本次手工挑战创建的临时 TXT 值。若同名记录还包含其他值,只删除本次挑战对应的 <CHALLENGE_VALUE>,不要整组清空。
本地控制台已经添加 TXT 不代表全球 DNS 节点立即可见;验证过早可能仍查询到旧结果,应等待权威服务器返回新记录后再继续挑战。
TXT 记录尚未传播
目标是在继续 DNS-01 挑战前确认新 TXT 已经出现在全部权威服务器,并判断剩余问题是否只是递归 DNS 缓存。DNS 并不存在一个需要“全球节点全部同步”的统一时刻,真正需要区分的是权威数据更新与递归缓存过期。
前置条件
- 已确认 TXT 的记录名和挑战值正确,且修改的是当前权威 DNS 区域。
- Certbot 当前挑战仍有效,不要在等待期间重新启动一次新的挑战并混用旧值。
- 本机安装了
dig;以下<DOMAIN>替换为实际域名。 - 如果此前存在同名 TXT,保留其原始值,避免把传播问题扩大成记录误删。
先检查权威服务器
直接查询每台权威服务器可以绕过普通递归解析器的缓存。如果各权威服务器返回结果不一致,继续等待或处理 DNS 服务商同步问题,此时不应让 Certbot继续验证。
DOMAIN="<DOMAIN>"
NAME="_acme-challenge.${DOMAIN}"
for ns in $(dig +short NS "${DOMAIN}"); do
echo "== ${ns} =="
dig +noall +answer @"${ns}" TXT "${NAME}"
done预期输出:所有权威服务器都返回同一个本次挑战值;TTL 和服务器名称为动态值。
== <NS1> ==
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<CHALLENGE_VALUE>"
== <NS2> ==
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<CHALLENGE_VALUE>"若某台仍返回旧值或没有 TXT,停止继续挑战。等待该权威服务器更新;持续长时间不一致时,应检查 DNS 服务商是否存在未提交更改、区域同步故障或错误的主从配置。
再检查递归缓存
权威服务器已经一致后,可以查询几个递归解析器观察缓存是否仍保留旧答案。下面示例只用于判断缓存状态,不代表 CA 一定使用这些解析器。
DOMAIN="<DOMAIN>"
NAME="_acme-challenge.${DOMAIN}"
dig +noall +answer @1.1.1.1 TXT "${NAME}"
dig +noall +answer @8.8.8.8 TXT "${NAME}"预期输出:缓存刷新后,两次查询都应包含本次 <CHALLENGE_VALUE>;具体 TTL 可能不同。
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<CHALLENGE_VALUE>"
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<CHALLENGE_VALUE>"递归解析器仍返回旧值并不表示权威记录错误。旧的正向答案会受原 TTL 影响;此前查询结果为空时,负缓存也可能暂时保留,因此仅反复刷新本地 DNS 缓存通常不能缩短外部解析器的等待时间。
继续验证的检查点
继续 Certbot 之前,至少确认全部权威服务器已经返回本次 TXT 值。若还希望降低缓存导致的失败概率,可再等到常用递归解析器也能看到新值,但不要在等待过程中删除并重新创建相同记录,否则可能重新引入不一致。
失败处理与恢复
若等待时间明显超过 DNS 服务商公布的正常更新窗口,而权威服务器仍不一致,应停止证书验证并检查服务商状态或提交支持请求。若权威服务器早已一致但 CA 持续报告旧值,则保留查询结果与时间点,确认不存在 CNAME 委派或错误区域后再重试挑战。
验证成功后,只删除本次手工挑战对应的临时 TXT 值。不要删除同名记录中的其他值,也不要为了“清缓存”修改无关 DNS 记录。
_acme-challenge 使用 CNAME 或 NS 委派时,目标区域配置错误会导致验证记录查询失败;应沿 DNS 委派链确认最终权威服务器能够返回正确 TXT。
排查 DNS 委派配置错误
目标是确认 _acme-challenge.<DOMAIN> 的查询确实沿预期的 CNAME 或 NS 委派链到达最终权威 DNS,并由该服务器返回当前 ACME 验证所需的 TXT 记录。只有这条链路正确,重新运行 Certbot 才有意义。
前置条件
- 已确认待签发域名
<DOMAIN>,并知道预期的 CNAME 目标或被委派的权威 DNS。 - 本机已安装
dig,并能从外部网络查询公共 DNS。 - 修改前已记录现有 CNAME、NS、TXT 值和 TTL;若是生产域名,优先在低风险窗口调整。
- 同一名称使用 CNAME 时不要再放置其他业务记录;采用 NS 委派时,应确保被委派的子区已在目标 DNS 服务中真实创建。
检查委派链
先从 _acme-challenge 的入口开始,检查是否存在 CNAME,再用 +trace 观察从根区到最终权威服务器的实际查询路径。执行前把 <DOMAIN> 替换为真实域名。
DOMAIN='<DOMAIN>'
NAME="_acme-challenge.${DOMAIN}"
TARGET="$(dig +short "$NAME" CNAME | head -n 1)"
if [ -n "$TARGET" ]; then
echo "CNAME -> $TARGET"
dig +trace "$TARGET" TXT
else
echo "No CNAME; trace delegated name"
dig +trace "$NAME" TXT
fi预期结果:
CNAME 方案:先显示 CNAME -> <TARGET>,随后 trace 在目标名称的权威区得到 TXT。
NS 委派方案:先显示 No CNAME; trace delegated name,随后 trace 进入被委派子区并在 _acme-challenge.<DOMAIN> 得到 TXT。
如果 trace 没有到达预期权威服务器,先修正委派,不要反复重跑 Certbot。若链路已经正确,再直接向最终权威服务器查询,排除递归缓存干扰。
NAME='_acme-challenge.<DOMAIN>'
AUTH_NS='<AUTH_NS>'
dig "@${AUTH_NS}" "$NAME" TXT +noall +answer预期结果:
_acme-challenge.<DOMAIN>. <TTL> IN TXT "<TOKEN>"
若返回为空、NXDOMAIN 或 SERVFAIL,说明问题仍在权威区配置或委派链,而不是 Certbot 本身。常见失败定位
CNAME 场景最常见的是目标名称写错、DNS 控制台把相对名称再次拼接当前区域,或 TXT 仍写在原区域而不是 CNAME 指向的目标名称。NS 场景则常见父区已经添加委派记录,但目标 DNS 服务中没有真正创建 _acme-challenge.<DOMAIN> 子区,最终会出现 NXDOMAIN、SERVFAIL 或非权威响应。
验证与恢复
修正后重复执行 dig +trace 和针对最终权威服务器的 TXT 查询;两者都正确后再重新运行 Certbot。若改动后问题扩大,立即恢复修改前记录的 CNAME 或 NS,并删除本次新增的错误委派;等待原 TTL 对应的缓存窗口后再次确认解析链恢复正常。
自动 DNS 插件无法创建或删除验证记录时,应检查 API 凭据、区域权限、凭据文件路径以及插件配置,并尽量使用仅允许修改必要 DNS 区域的最小权限凭据。
处理 DNS 插件没有修改权限
目标是让 Certbot 的 DNS 插件能够在指定区域创建并删除 _acme-challenge TXT,同时把凭据权限限制在完成验证所需的最小范围。生产签发前应先用暂存环境验证一次完整的创建、查询和清理流程。
前置条件
- 已确认 Certbot 实际使用的 DNS authenticator 插件、DNS 提供商账号和目标区域
<DOMAIN>。 - 已准备可轮换的 API 凭据,并记录旧凭据位置,便于失败时恢复。
- 凭据文件只对 Certbot 运行用户可读;API 令牌至少具备插件所需的区域查询权限和 TXT 记录创建、更新、删除权限,但不要授予无关区域的写权限。
- 插件与 Certbot 安装在同一运行环境中;容器、虚拟环境或系统包混用时要先确认实际执行的是哪一个
certbot。
确认插件与凭据文件
先确认插件已经被当前 Certbot 进程加载,再检查凭据文件是否存在且可读。以下命令假设 Certbot 以 sudo 运行。
CREDENTIALS='<PATH>'
sudo certbot plugins
sudo test -r "$CREDENTIALS" && echo "credentials-readable"
sudo ls -l "$CREDENTIALS"预期结果:
插件列表中能看到实际使用的 dns-<PROVIDER> authenticator。
credentials-readable
凭据文件存在,且没有向不必要的其他用户开放读取权限。如果插件没有出现在列表中,先修正安装环境;如果文件不可读,先修复路径、属主或权限。此时继续调整 API 权限不会解决问题。
用暂存环境验证写权限
不同 DNS 插件的参数名并不统一,不能机械把提供商名称替换进同一套参数。下面以 dns-cloudflare 为例演示验证方式;其他插件应按该插件自己的凭据参数替换。执行前把 <DOMAIN> 和 <PATH> 换成真实值。
DOMAIN='<DOMAIN>'
CREDENTIALS='<PATH>'
sudo certbot certonly --dry-run \
--dns-cloudflare \
--dns-cloudflare-credentials "$CREDENTIALS" \
-d "$DOMAIN" \
-d "*.$DOMAIN"预期结果:
命令退出码为 0;DNS API 不再返回认证或授权错误;验证 TXT 能被创建,并在挑战结束后由插件清理。如果出现 401 或 403,优先检查令牌是否过期、账号或租户是否匹配,以及目标区域是否在令牌授权范围内。若提示找不到区域,还要确认插件是否需要额外的 zone/list/read 权限;有些提供商即使允许修改记录,也必须先允许插件定位区域。
验证与失败处理
在 DNS 提供商后台或用 dig 观察 _acme-challenge.<DOMAIN>,确认插件创建的 TXT 能被权威 DNS 返回,并在 dry run 结束后被删除。若“能创建但不能删除”,不要直接切到生产续期;先补齐删除权限或修正资源范围,否则会留下陈旧验证记录并让自动续期持续失败。
恢复正常状态
如果新令牌或权限调整失败,撤销本次新建的令牌,恢复修改前的凭据文件,并检查是否遗留本次测试创建的 TXT。只有确认当前没有正在进行的 ACME 挑战时才手工删除孤立记录;随后重新做一次 dry run,成功后再恢复生产签发或自动续期。
自动续期故障
renew --dry-run 失败意味着未来自动续期存在风险;应根据失败证书逐项检查原认证插件、DNS、端口、Webroot 和 Hook,而不是等待正式证书临近过期再处理。
续期测试失败
目标是把失败范围缩小到具体证书和认证环节,并让 renew --dry-run 最终返回成功。--dry-run 用于验证未来续期路径,正式证书尚未临近过期也应先解决失败。
前置条件
- 具备运行 Certbot、读取
/etc/letsencrypt和检查 Web 服务配置的权限。 - 先执行
certbot certificates记下失败证书的<CERT_NAME>;在改动续期参数、Web 服务器或 Hook 前保留配置备份。 - 确认域名仍解析到预期入口;若使用 HTTP-01,外部必须能通过 80 端口访问挑战路径;若使用 DNS-01,必须能自动写入并查询对应 TXT 记录。
定位失败证书
先只测试一个证书,避免多张证书的日志混在一起。将 <CERT_NAME> 替换为 certbot certificates 显示的证书名称。
sudo certbot renew --cert-name <CERT_NAME> --dry-run -v && echo dry-run-ok预期结果:Certbot 的详细日志会因版本和认证插件不同而变化;只有测试续期成功时,最后才会出现以下标记。
dry-run-ok如果没有出现该行,保留本次错误信息并停止继续改其他证书,先处理当前失败点。
按认证方式检查
先查看该证书保存的续期配置,确认实际使用的认证器、Webroot 和 Hook,而不是按当前 Nginx 或 DNS 环境猜测。
sudo grep -E '^(authenticator|installer|webroot|pre_hook|post_hook|renew_hook|manual_)' /etc/letsencrypt/renewal/<CERT_NAME>.conf预期输出通常至少会包含认证器字段;其他字段取决于插件和证书配置。
authenticator = <AUTHENTICATOR>- Nginx/Apache:先通过各自配置检查,再确认 HTTP-01 的 80 端口和挑战路径未被重定向、代理或防火墙错误拦截。
- Webroot:核对保存的 Webroot 是否仍是站点真实根目录,并确认
/.well-known/acme-challenge/能从公网访问。 - Standalone:续期时 Certbot 必须能绑定 80 端口;若现有 Web 服务占用端口,应检查配套的 pre/post Hook 是否确实停止和恢复服务。
- DNS 插件:检查凭据文件仍存在、权限足够、API 权限未撤销,并确认 TXT 记录有足够传播时间。
- Hook:确认脚本路径未变、文件可执行、非交互运行会返回 0;认证 Hook 失败时不要用 deploy Hook 代替,因为两者职责不同。
验证与失败处理
修复后重复同一条按证书限定的 dry-run,直到成功,再执行一次完整的 sudo certbot renew --dry-run 检查所有证书。若仍失败,应以错误类型为边界处理:连接超时优先查 DNS、路由和端口;404 或 unauthorized 优先查挑战路径;插件或凭据错误优先查插件安装、配置与权限。
不要反复执行正式强制续期来试错,也不要直接删除 /etc/letsencrypt。dry-run 未通过时,自动定时器即使正常运行,也只会按同一错误路径再次失败。
回滚
如果排障中修改了 Nginx、Apache、Webroot、DNS 权限或 Hook,测试失败时恢复到改动前配置并重新加载相关服务。若手工编辑过 /etc/letsencrypt/renewal/<CERT_NAME>.conf,应恢复备份;直接编辑该文件容易破坏后续续期,优先使用 Certbot 支持的配置修改命令。
单纯通过 --manual 人工完成挑战的证书不能无人值守续期;应改用 Nginx、Webroot 或 DNS 插件,或者提供能够自动完成验证的 manual authentication hook。
手动证书无法自动续期
目标是把仅靠人工完成 --manual 挑战的证书迁移到无人值守的认证方式,并在不删除现有证书的前提下通过续期测试。优先改用 Nginx、Webroot 或 DNS API 插件;确实只能用 manual 时,必须用认证 Hook 自动完成挑战。
前置条件
- 用
certbot certificates确认证书名称、域名列表和当前有效期,并备份 Certbot 与 Web 服务相关配置。 - 选择可长期自动执行的认证方式:本机可控 Web 服务优先 Nginx/Webroot;需要通配符或无法开放 HTTP-01 时使用对应 DNS 提供商插件。
- DNS 插件或 manual Hook 所需的 API 凭据应采用最小权限并限制文件读取权限;不要把密钥直接写进命令历史或脚本源码。
优先迁移到自动化插件
下面以 Webroot 为例。<CERT_NAME> 是 Certbot 管理的证书名称,<WEBROOT> 是该域名实际对外提供文件的站点根目录。reconfigure 会用新的续期参数做测试;若当前 Certbot 不支持该子命令,应先按安装渠道升级,或用受支持的自动化插件重新签发同一组域名后再做 dry-run。
sudo certbot reconfigure --cert-name <CERT_NAME> --authenticator webroot --webroot-path <WEBROOT>
sudo certbot renew --cert-name <CERT_NAME> --dry-run && echo autorenew-ready预期结果:第一条命令完成新的续期配置验证;第二条测试成功后最后出现以下标记。
autorenew-ready若站点由 Nginx 直接管理,可选择 Nginx 插件;若使用 DNS-01,应安装与 DNS 服务商匹配的插件并配置凭据。不要只更换安装器而保留 manual 认证器,否则验证阶段仍需要人工介入。
必须保留 manual 时
只有认证过程可以完整脚本化时,manual 才能用于无人值守续期。配置 --manual-auth-hook <PATH> 让脚本自动放置 HTTP 文件或创建 DNS TXT 记录,必要时再配置 --manual-cleanup-hook <PATH> 清理挑战数据。Hook 不得等待人工输入,必须根据 Certbot 提供的挑战环境变量完成操作并用退出码报告成败。
验证自动续期链路
迁移后再次运行针对该证书的 dry-run,并确认机器上确实存在定时执行 certbot renew 的机制。dry-run 成功只能证明认证和续期配置可用,不能证明 systemd timer、cron 或平台自带计划任务已经启用。
如果 dry-run 仍出现需要按 Enter、手工创建 TXT 或复制验证文件的提示,说明续期链路仍然不是无人值守;不要把它视为“自动续期已配置”。
失败处理与回滚
自动化插件验证失败时,先恢复 Webroot、Nginx 或 DNS 的改动,保留现有有效证书继续提供服务,再单独修复认证链路。迁移期间不要先删除旧证书或其 /etc/letsencrypt/live/<CERT_NAME> 路径,以免正在引用该路径的服务立即失效。
如果选择 manual Hook,失败时应撤销本次创建的临时 TXT 记录或挑战文件,并恢复原有 DNS/HTTP 状态。只有 dry-run 成功且定时任务存在后,才算完成自动续期迁移。