通配符证书 renewal 总失败?DNS-01 委派与自动化续期 6 步实操(2025)
通配符证书 renewal 必须走 DNS-01;把 `_acme-challenge` 通过 CNAME 委派到独立 DNS 区,并用最小权限 API 令牌加 staging dry-run,可把续期过程做成可审计流程。 acme.sh 3.0.7 示例:`acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256 --dnssleep 300 --server https://acme-staging-v02.api.letsencrypt.org/directory --debug 2`,先 staging 再生产。 Certbot 2.11.0 用 `certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/acme/cloudflare.ini -d example.com -d '*.example.com' --dry-run` 验证;续期后 `nginx -t && systemctl reload nginx`。 常见报错 `Incorrect TXT record` 多因 CNAME 未生效、TTL 300 未过或并发续期;用 `dig +short TXT _acme-challenge.example.com @1.1.1.1` 核对。 成本:Let's Encrypt 通配符 0 元;OV 通配符约 ¥800–¥3000/年;私有 CA step-ca 软件 0 元,但需约 1–2 人日/月运维。
问题背景与根本原因:通配符证书 renewal 为什么总卡在 DNS-01?
通配符证书 renewal 失败,十次里有九次不是证书过期,而是 ACME 的 DNS-01 挑战没有顺利跑完。先明确一条硬性限制:据 Let’s Encrypt 文档,HTTP-01 无法验证 *.example.com,因为验证服务器需要把令牌放到 http://<domain>/.well-known/acme-challenge/<token>,而通配符本身不是一个可解析的主机名。因此 ACME 服务器只能要求你在 _acme-challenge.example.com 写入一条 TXT 记录,这也意味着续期链路上多了一个必须可控的 DNS 环节,故障面从“Web 服务器”扩大到“API 令牌 + 传播 + 并发”。
误解一:通配符覆盖范围。*.example.com 只匹配一级子域,不覆盖裸域 example.com,也不覆盖 a.b.example.com。很多人续期时只写了 -d '*.example.com',新证书的 SAN 悄悄变窄,站点在裸域上直接报 NET::ERR_CERT_COMMON_NAME_INVALID。正确写法必须两条都带:
# certbot 2.11.0(2025 年当前 stable),两条 -d 缺一不可
certbot certonly --dns-cloudflare
-d example.com -d '*.example.com'
--dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini
--cert-name example.com # 固定 cert-name,避免续期时生成新 lineage
# acme.sh 3.0.7,同样两条 -d
acme.sh --issue --dns dns_cf
-d example.com -d '*.example.com'
--keylength ec-256
误解二:权限给太大。大量脚本沿用 DNS 服务商的 Global API Key,一旦泄露,整个账号下所有域名可被改写。据 Cloudflare 官方文档,应改用 Scoped API Token,权限只勾 Zone → DNS → Edit,Zone Resources 限定到 example.com。acme.sh 3.0.7 通过环境变量 CF_Token 读取该令牌,而不是旧的 CF_Key/CF_Email 组合:
# /root/.acme.sh/account.conf 中持久化(acme.sh 会自动保存)
export CF_Token="仅含 Zone:DNS:Edit 的 scoped token"
export CF_Zone_ID="example.com 的 Zone ID" # 可选,减少一次 API 查询
误解三:CNAME 委派“配了但没生效”。把 _acme-challenge.example.com CNAME 到独立委派区(常见于集中式证书管理)时,如果 CNAME 自身 TTL 仍是 3600,或上游递归缓存未过期,ACME 的权威查询会命中旧 TXT,报出 Incorrect TXT record。建议 TTL 压到 300,并亲手核对:
# 权威与公共递归双查,确认新 TXT 已可见
dig +short TXT _acme-challenge.example.com @1.1.1.1
dig +short CNAME _acme-challenge.example.com @8.8.8.8
误解四:并发与清理竞态。多台机器同时跑 certbot renew 或 acme.sh --cron,会互相删除对方刚写入的 TXT,表现为随机失败、重跑又成功。要么集中到单台续期节点,要么加文件锁:
flock -n /var/lock/acme.lock -c 'certbot renew --quiet'
误解五:日志没留。Certbot 2.11.0 的日志在 /var/log/letsencrypt/letsencrypt.log,acme.sh 在 ~/.acme.sh/acme.sh.log。不加 --debug 2 时,你通常只看到 urn:ietf:params:acme:error:dns 这一个笼统错误码,无法区分“令牌无权限”“记录未传播”还是“CNAME 指错”。下面这张表是常见报错与根因的对应关系,可据此判断自己卡在哪一步:
| 报错片段 | 最常见根因 | 验证命令 |
|---|---|---|
Incorrect TXT record |
CNAME 委派 TTL 过长或缓存未刷新 | dig +short TXT _acme-challenge.example.com @1.1.1.1 |
urn:ietf:params:acme:error:dns |
令牌无 DNS:Edit 或 Zone 限定错误 | 用同一令牌手动调用 GET /zones/<id>/dns_records |
No valid IP addresses found |
误用 HTTP-01 申请通配符 | 检查命令行是否缺少 --dns-* 插件 |
| 随机成功/失败 | 多机并发写入与清理冲突 | flock 加锁后重跑对比 |
把上述五点对照一遍,绝大多数通配符证书 renewal 的失败都能在一次 --debug 2 重跑中复现并定位。剩下的工作,是把 DNS-01 的委派链路和续期调度做成可重复的自动化流程——这正是后续六步实操要解决的问题。
完整实操步骤:从账户隔离到生产续期的 6 步
续期失败的根因很少是“证书过期了”,而是身份、权限、路径三者没有隔离:一次手工签发用的令牌、账户、证书名,在三个月后的自动续期里可能已经全部错位。下面这 6 步按“先盘点、再隔离、后验证”的顺序排列,可直接照抄命令。
步骤 1:先盘点,给每张证书一个固定名字。通配符证书最容易踩的坑是“同名覆盖”——Certbot 在缺少 --cert-name 时用第一个 -d 生成名字,后续加一个 SAN 就会新建一张同名不同内容的证书,导致 Nginx 加载的还是旧文件。
# Certbot:列出证书名(Certificate Name)、域名、到期时间、部署钩子
certbot certificates
# acme.sh:列出 Main_Domain / SAN_Domains / Created / Renew,用于比对清单
acme.sh --list
盘点结果应落到一张清单:example.com、*.example.com、*.api.example.com 三张证书各自固定 --cert-name wildcard-example(Certbot)或 --home /etc/acme/wildcard-example(acme.sh),后续所有命令只引用这个名字,不再引用域名。
步骤 2:为 renewal 单独开账户与最小权限令牌。据 Let’s Encrypt 文档,ACME 账户与速率限制按账户维度统计,生产签发与手工调试共用账户会互相污染配额。因此用 ops-acme@example.com 注册独立账户;Cloudflare 侧创建 API Token,权限仅 Zone:DNS:Edit,Zone Resources 限定 example.com(不要用 Global API Key)。令牌写入 chmod 600 的凭据文件,绝不能写进 crontab 或 systemd unit 的 ExecStart:
# /etc/acme/cloudflare.ini
dns_cloudflare_api_token = 仅含 Zone:DNS:Edit、限定 example.com 的 Token
chmod 600 /etc/acme/cloudflare.ini && chown root:root /etc/acme/cloudflare.ini
步骤 3:用 CNAME 把验证流量委派出去。在 example.com 区只留一条指向,主区不再需要 DNS 写权限:
_acme-challenge.example.com. 300 IN CNAME example.com.acme.delegated.example.net.
_acme-challenge.api.example.com. 300 IN CNAME api.example.com.acme.delegated.example.net.
委派区只授予 ACME 客户端写 TXT 的权限。这样即使令牌泄漏,攻击面也仅限于验证子区,主区 A/MX 记录不受影响。
步骤 4:先打 staging,不消耗生产速率限制。Let’s Encrypt staging 目录签发的证书不被浏览器信任,但完整走一遍 DNS-01 流程,能提前暴露令牌权限与 CNAME 解析问题。
# acme.sh:指定 staging 目录 + 调试级别(--debug 2 会打印 API 请求与响应体)
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'
--server https://acme-staging-v02.api.letsencrypt.org/directory --debug 2
# Certbot:--dry-run 等价于走 staging
certbot certonly --dns-cloudflare
--dns-cloudflare-credentials /etc/acme/cloudflare.ini
-d example.com -d '*.example.com' --dry-run
若看到 urn:ietf:params:acme:error:unauthorized(RFC 8555 定义的错误类型),说明 TXT 记录未生效或 CNAME 目标写错;若出现 too many failed authorizations recently,说明已经撞上失败验证限流,需等待一小时再试。
步骤 5:生产签发并绑定 deploy hook。钩子必须以非零状态码退出,否则 cron 永远报成功,证书静默失效。
# acme.sh:签发后直接安装并重载
acme.sh --install-cert -d example.com --ecc
--key-file /etc/nginx/ssl/example.key
--fullchain-file /etc/nginx/ssl/example.fullchain.pem
--reloadcmd "systemctl reload nginx || exit 1"
# Certbot:deploy hook 失败会让 certbot 以非零码退出
certbot certonly --dns-cloudflare
--dns-cloudflare-credentials /etc/acme/cloudflare.ini
--cert-name wildcard-example
-d example.com -d '*.example.com'
--deploy-hook 'systemctl reload nginx'
步骤 6:固化定时、日志与季度审计。Certbot 官方推荐用 systemd timer(certbot.timer 默认每日触发两次随机延迟,见 systemctl list-timers certbot.timer);acme.sh 自带 cron 任务,需显式带 --home,否则 root 与普通用户的账户目录会混淆。
# acme.sh 的 cron 行(默认由 --install-cronjob 写入,60 天阈值)
17 3 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null
# 审计:日志留 90 天,按 ACME 错误 URN 告警
journalctl -u certbot.service --since "90 days ago" | grep -E "urn:ietf:params:acme:error"
| 维度 | Certbot | acme.sh |
|---|---|---|
| 证书标识 | --cert-name(默认取首个 -d) |
--home 目录 / -d 组合 |
| Staging 开关 | --dry-run 或 --server |
--server 指向 staging 目录 |
| 重载钩子 | --deploy-hook |
--reloadcmd |
| 定时机制 | certbot.timer(每日 2 次) |
--cron(默认 60 天阈值) |
最后一层保险是 ARI。Let’s Encrypt 的目录资源中已提供 renewalInfo 端点,对应 RFC 9773,支持 ARI 的客户端会在 CA 建议的时间窗口内续期,避开集中过期引发的拥堵;不支持 ARI 的老客户端仍由每日 cron 兜底。无论走哪条路,每季度手工跑一次 --dry-run,验证令牌未过期、CNAME 未被误删——这是唯一能提前发现“权限在续期前失效”的手段。
配置与命令示例:acme.sh 3.0.7、Certbot 2.11.0 与 CNAME 委派
acme.sh 3.0.7 怎么先用 staging 把通配符证书跑通?
通配符证书只能走 DNS-01,因此第一步永远是确认”DNS 记录写进去了、Let’s Encrypt 查到了”。acme.sh 的 Cloudflare 插件读取两个环境变量:CF_Token(API Token,权限需含 Zone:DNS:Edit 与 Zone:Zone:Read)和 CF_Zone_ID。据 Let’s Encrypt 官方 rate limits 文档,生产环境每个注册域名每周限 50 张证书、同一组域名重复签发限 5 张,所以务必先在 staging 验证——staging 与生产是两套独立的配额池。
# 凭证只走环境变量,避免出现在 shell history / ps 输出中
export CF_Token='<Zone:DNS:Edit + Zone:Zone:Read 的 API Token>'
export CF_Zone_ID='<example.com 的 Zone ID>'
acme.sh --issue --dns dns_cf
-d example.com -d '*.example.com'
--keylength ec-256
--dnssleep 300
--server https://acme-staging-v02.api.letsencrypt.org/directory
--debug 2
参数含义:--dnssleep 300 让 acme.sh 在写完全部 TXT 后固定等待 300 秒再触发校验,用于对抗权威 DNS 的负缓存;--keylength ec-256 显式声明,避免依赖版本默认值(acme.sh 2.x 早期默认 2048 位 RSA);--debug 2 会打印 ACME 请求体与 DNS 记录内容。看到 Cert success 后,去掉 --server 并加 --force 重跑生产(不加 --force,acme.sh 检测到同名证书已存在会直接跳过)。staging 证书链不受信任,浏览器报警属正常。
Certbot 2.11.0 的等价写法是什么?
# Debian 12 / Ubuntu 24.04 包名;RHEL 系为 python3-certbot-dns-cloudflare
sudo apt install python3-certbot-dns-cloudflare
# 凭证文件权限必须 600,否则 Certbot 直接报错退出
sudo install -m 600 /dev/null /etc/acme/cloudflare.ini
# 文件内容一行:dns_cloudflare_api_token = <token>
sudo certbot certonly --dns-cloudflare
--dns-cloudflare-credentials /etc/acme/cloudflare.ini
--dns-cloudflare-propagation-seconds 180
-d example.com -d '*.example.com'
--cert-name example.com --dry-run
--dns-cloudflare-propagation-seconds 默认仅 10 秒,对 TTL 300 的权威区明显不够,180~300 是常见取值。--dry-run 走 staging,通过后去掉它重跑;日常续期用 certbot renew --cert-name example.com --deploy-hook 'systemctl reload nginx'。--cert-name 很关键:没有它,通配符与裸域可能被拆成两条 lineage,续期时只续了其中一条。
CNAME 委派(acme-dns)怎么配?主域不给 DNS API 也行吗?
可以。核心思路是把 _acme-challenge 整棵子树委派给第三方,主区只需一条静态 CNAME,永不改动,也无需开放任何写权限:
# 主权威区仅此一条记录
_acme-challenge.example.com. 300 IN CNAME 1b2c3d4e.acme-dns.example.net.
# 向 acme-dns 实例注册,返回四元组
curl -s -X POST https://auth.acme-dns.io/register | jq
# {
# "username": "...", "password": "...",
# "fulldomain": "1b2c3d4e.acme-dns.example.net",
# "subdomain": "1b2c3d4e"
# }
export ACMEDNS_BASE_URL="https://auth.acme-dns.io" # acme.sh dns_acmedns 的默认值
export ACMEDNS_USERNAME="..."
export ACMEDNS_PASSWORD="..."
export ACMEDNS_SUBDOMAIN="1b2c3d4e"
acme.sh --issue --dns dns_acmedns -d example.com -d '*.example.com'
客户端只会往 subdomain 对应的 TXT 写入校验值,不碰主区。风险点在于 acme-dns 实例本身成为单点:自建时要保证它 7×24 可达,否则续期会以 SERVFAIL 或 Incorrect TXT record 失败。
| 方案 | 需暴露的凭证 | 支持通配符 | 续期典型失败原因 | 适用场景 |
|---|---|---|---|---|
| DNS API 直连(dns_cf / –dns-cloudflare) | 可写该区的 API Token | 是 | Token 缺 Zone:Zone:Read;记录被 CDN 橙云代理;TTL 过长 | 域名集中在单一 DNS 服务商 |
| CNAME 委派到 acme-dns | 无(主区只留一条 CNAME) | 是 | CNAME 未生效;subdomain 填错;acme-dns 实例不可达 | 主 DNS 无 API、合规禁止下发写权限 |
| HTTP-01(webroot / nginx 插件) | 无 | 否 | 80 端口被墙、.well-known 被重写规则吞掉 |
单域名、无通配符需求 |
续期成功后 Nginx 没生效?先看 deploy hook
#!/bin/sh
# /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
nginx -t && systemctl reload nginx
chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh。Certbot 2.x 会按文件名字典序执行 deploy hook,且仅在证书真正更新时才执行;任一 hook 退出码非 0,certbot renew 整体返回非 0,可被 systemd timer 的失败状态捕获。先跑 nginx -t 再 reload,能避免配置错误导致 reload 静默失败。
怎么确认新证书真的上线了?
# 看磁盘上的证书:有效期、主体、SAN
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem
-noout -dates -subject -ext subjectAltName
# 看线上实际下发的证书(-servername 必须与 SNI 名一致)
openssl s_client -connect example.com:443 -servername example.com -showcerts
</dev/null 2>/dev/null | openssl x509 -noout -issuer -dates -ext subjectAltName
参数语义见 OpenSSL 3.0 手册页(openssl-x509(1)、openssl-s_client(1)):-servername 设置 SNI,省略或写错会命中默认站点,从而”续期成功但线上仍是旧证书”;-ext 需 OpenSSL 1.1.1 及以上,3.0.13 上正常输出 X509v3 Subject Alternative Name,通配符应显示为 DNS:*.example.com。
失败时日志该 grep 什么?
# Certbot:ACME 错误码是 RFC 8555 定义的 urn:ietf:params:acme:error:*
grep -E 'Cert success|urn:ietf:params:acme:error|Incorrect TXT|SERVFAIL'
/var/log/letsencrypt/letsencrypt.log
# acme.sh
grep -E 'Cert success|Error|Verify error' ~/.acme.sh/acme.sh.log
# --debug 2 的日志含明文令牌,只保留 7 天
find ~/.acme.sh -name '*.log' -mtime +7 -delete
urn:ietf:params:acme:error:dns 多为权威 DNS 不可达或 SERVFAIL;unauthorized 配 Incorrect TXT record 通常是记录还没传播就发起了校验,把 --dnssleep 或 --dns-cloudflare-propagation-seconds 调大即可。据 acme.sh 官方 wiki,--debug 2 输出会包含账户密钥与 API 令牌片段,排查完请立即删除对应日志。
方案选型对比:手动 DNS、服务商 API、CNAME 委派与私有 CA 怎么选
先看结论:四种路线各自的边界在哪?通配符只能走 DNS-01(RFC 8555 §7.4.1 明确规定 wildcard 标识符必须用 dns-01 挑战,HTTP-01 无法验证 *.example.com),所以选型本质是”TXT 记录由谁写、写在哪、谁能审”。下表按权限边界和审计面拆开对比,价格与版本以 2025 年公开信息为准。
| 方案 | 适用场景 | 权限边界 | 自动化 | 续期审计 | 成本区间 |
|---|---|---|---|---|---|
| 手动 DNS TXT | 临时测试、域名 ≤3 个 | 人工操作,TXT 易残留触发 NXDOMAIN/冲突 |
低 | 靠人工台账 | 0 元 |
| 服务商 DNS API | 单云、单账号、DNS 集中在一家 | Token 仅授 Zone:DNS:Edit,不授 Zone:Read 全量 |
高 | ACME 日志 + API 审计日志 | 0 元(Let’s Encrypt) |
| CNAME 委派到 acme-dns | 多账号、多 DNS 服务商、多租户 | 仅委派区 _acme-challenge 可写,主区零凭据 |
高 | 委派区日志独立留存 | 自建 0 元;托管约 0–5 美元/月 |
| 私有 CA(step-ca) | 内网、合规隔离、无公网出口 | CA 策略集中下发,按 provisioner 授权 | 中高 | 内部 CA 签发日志 | 软件 0 元,运维 1–2 人日/月 |
| OV 通配符商业证书 | 对外品牌、合同/招投标要求 | CA 人工审核企业身份 | 中 | CA 门户到期提醒 | 约 ¥800–¥3000/年 |
单域名或单通配符、DNS 在 Cloudflare,最快怎么配?用 Certbot 2.11.0 加 dns-cloudflare 插件。关键参数 --dns-cloudflare-propagation-seconds 默认只有 10 秒,而 Let’s Encrypt 采用多视角验证(secondary validation),TXT 未传播完会直接报下面的错——这正是很多”通配符证书 renewal”在凌晨静默失败的根因:
Certbot failed to authenticate some domains (authenticator: dns-cloudflare).
Domain: example.com
Type: dns
Detail: During secondary validation: DNS problem: NXDOMAIN looking for TXT at _acme-challenge.example.com
# Certbot 2.11.0 + dns-cloudflare 2.x;Token 只给 Zone:DNS:Edit
cat > /etc/letsencrypt/cloudflare.ini <<'EOF'
dns_cloudflare_api_token = <仅含 Zone:DNS:Edit 的 API Token>
EOF
chmod 600 /etc/letsencrypt/cloudflare.ini
certbot certonly
--dns-cloudflare
--dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini
--dns-cloudflare-propagation-seconds 180 # 默认 10 秒;公共 DNS TTL 300 时建议 180–300
-d example.com -d '*.example.com' # 通配符不覆盖基域,两条都要写
--cert-name wildcard-example
# 续期:Let's Encrypt 有效期 90 天,官方建议每 60 天续一次
17 3,15 * * * /usr/bin/certbot renew --quiet --deploy-hook "systemctl reload nginx"
多 DNS 服务商、多账号怎么办?把验证记录 CNAME 到 acme-dns,主区只留一条静态 CNAME,续期时不再持有主区写权限。acme.sh 3.0.7 的 --dnssleep 默认 120 秒,委派链路多一跳,建议抬到 300;配合 --challenge-alias 指向可写区:
# 主区一次性配置:_acme-challenge.example.com CNAME <uuid>.acme-dns.example.net
# acme.sh 3.0.7;Token 只作用于委派目标区
export CF_Token="<委派区专用 Token>"
acme.sh --issue --dns dns_cf
--challenge-alias acme-delegated.example.net # 写入委派目标区,主区零凭据
--dnssleep 300 # 默认 120 秒
-d example.com -d '*.example.com'
内网或强合规场景为什么不用公共 CA?因为公共 CA 无法签发 .internal 这类保留域,且证书透明度日志(CT)会暴露内网主机名。step-ca 0.28.x 提供标准 ACME 端点,客户端可复用 Certbot/acme.sh:
# step-ca 0.28.x;--not-after 默认取 provisioner 上限(通常 24h)
step ca certificate "*.internal.example.com" wildcard.crt wildcard.key
--ca-url https://ca.internal:9000
--root /etc/step-ca/certs/root_ca.crt
--provisioner acme
--not-after 720h
选型原则:对外公共服务优先 Let’s Encrypt + CNAME 委派(凭据面最小、审计独立);单云单账号图省事就用服务商 API,但 Token 必须限定到单 Zone;内网隔离走 step-ca 或内部 ACME;合同要求 OV 时再买商业通配符,并把续期责任人写进 CMDB。时间参数统一口径:DNS TTL 300 秒、acme.sh
--dnssleep 300、Certbot--dns-cloudflare-propagation-seconds 180、cron 每天 2 次并错开整点(如 03:17/15:17),避开 Cloudflare 等厂商的 API 限流窗口。
常见错误与排查:看到这些 ACME 报错先查什么
续期失败时,不要急着重跑一遍——ACME 返回的 error URN 已经告诉你该查哪一层。下表是常见报错与第一步排查动作的对应关系,先查 DNS 传播,再查 CA 策略,最后才动客户端参数。
| 报错关键字 | 故障层级 | 首条排查命令 |
|---|---|---|
dns :: DNS problem: NXDOMAIN |
DNS 记录/委派 | dig +short TXT _acme-challenge.example.com @1.1.1.1 |
Incorrect TXT record |
旧记录残留/TTL | dig +short TXT _acme-challenge.example.com @8.8.8.8 |
caa :: CAA record ... prevents issuance |
CA 授权策略 | dig CAA example.com |
Invalid access token |
DNS API 凭据 | curl ... /client/v4/zones?name= |
too many certificates already issued |
CA 速率限制 | 停止重试,切 staging |
Q:提示 NXDOMAIN 查不到 TXT,是 DNS 还没生效吗?
多数不是“没生效”,而是记录压根没写对地方。用公共解析器确认记录是否真的存在:
# 查 TXT 是否已出现在公共视图
dig +short TXT _acme-challenge.example.com @1.1.1.1
# 追 CNAME 链:若 _acme-challenge 被委派到别的区,看最终落到哪
dig +short CNAME _acme-challenge.example.com @1.1.1.1
# 直接问权威 NS,排除递归缓存干扰
dig +short TXT _acme-challenge.example.com @$(dig +short NS example.com | head -1)
三处都没记录时,按顺序怀疑:CNAME 目标域名拼错(_acme-challenge 少了下划线前缀最常见);委派区(如 acme-delegated.example.net)里 API 脚本写入的是另一条 zone;以及 API Token 只授了读权限或没包含该 Zone。据 Let’s Encrypt 文档,验证节点会从多个网络位置查询,任一位置 NXDOMAIN 即判定失败。
Q:Incorrect TXT record 明明记录还在?
通常是上一轮的旧 TXT 没删干净,或 TTL 太长导致递归缓存里同时存在两条。对比公共解析器与权威服务器的返回:
# 公共视图 vs 权威视图,条数不一致 = 缓存未过期
dig +short TXT _acme-challenge.example.com @8.8.8.8
dig +short TXT _acme-challenge.example.com @ns1.example.com
清理重复 TXT 后,把等待时间拉长。注意默认值差异:acme.sh 的 --dnssleep 默认 120 秒,Certbot 各 DNS 插件用 --dns-<plugin>-propagation-seconds,默认仅 10 秒——后者是续期失败的常见元凶。
# acme.sh:显式延长到 300 秒,并确认走 DNS-01
acme.sh --renew -d example.com -d '*.example.com'
--preferred-challenges dns-01 --dnssleep 300
# Certbot + Cloudflare 插件:把默认 10 秒提到 300 秒
certbot renew --cert-name example.com
--dns-cloudflare --dns-cloudflare-propagation-seconds 300
Q:CAA 报错怎么改?
按 RFC 8659,CA 签发前必须检查 CAA。用 dig CAA example.com 查看,若存在 issue 属性却不含 Let’s Encrypt,就会被拒。Let’s Encrypt 的标识值是 letsencrypt.org(不是 letsencrypt.com,写错同样失败):
example.com. 300 IN CAA 0 issue "letsencrypt.org"
# 商业 CA 换成其对应值,例如 DigiCert:0 issue "digicert.com"
另外检查 CAA 是否只写在根域而通配符所在的子域另有记录——CAA 沿域名树向上查找,子域记录会覆盖父域。
Q:Cloudflare 报 Invalid access token 或 Invalid request headers?
先验证 Token 本身与 Zone 是否匹配,再怀疑插件:
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com"
-H "Authorization: Bearer $CF_Token" -H "Content-Type: application/json" | jq '.success, .result[].id'
success: false 说明 Token 过期或被吊销;result 为空说明 Token 权限范围不含该 Zone——需要 Zone : DNS : Edit,且 Zone Resources 显式包含目标域名。把返回的 Zone ID 与配置里的值逐字符比对,多账号场景下串号很常见。
Q:too many certificates already issued for exact set of domains?
这是 Let’s Encrypt 生产环境的速率限制被触发:同一注册域每 7 天 50 张证书,同一组完全相同的域名每 7 天 5 张。此时继续重试只会延长封禁窗口,正确做法是立刻改用 staging 端点调试(--staging / --server https://acme-staging-v02.api.letsencrypt.org/directory),确认流程通过后再切回生产。
Q:日志里出现 Problem binding to port 80 需要处理吗?
通配符证书与 80 端口无关。出现这个错误说明客户端退回了 HTTP-01 或 webroot 验证——检查是否漏了 --preferred-challenges dns-01,或在 Certbot 插件模式下误加了 --standalone。通配符域名(*.example.com)只能通过 DNS-01 签发,这是 CA/Browser Forum 基线要求决定的,不是客户端配置问题。
效果验证方法:如何确认 renewal 后证书、链和自动任务都生效
续期成功不等于生效。通配符证书 renewal 之后要确认三件事:文件里换了新证书、链完整可验证、自动任务和 deploy hook 真的跑通了。下面 6 步按顺序做一遍,大约 5 分钟。
第 1 步:核对 SAN 与有效期。通配符最常见的失败是续到了只含裸域的 lineage,导致 *.example.com 静默丢失。
# 查看 cert.pem 的起止时间与 SAN;notAfter 距签发约 90 天
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem
-noout -dates -ext subjectAltName
# 期望输出(两个名字必须同时存在):
# notAfter=Apr 5 03:12:44 2026 GMT
# X509v3 Subject Alternative Name:
# DNS:example.com, DNS:*.example.com
只看到 DNS:example.com 说明续期命令漏了 -d '*.example.com'。Let’s Encrypt 证书固定 90 天有效期,notAfter 未向后滚动就是根本没续成。
第 2 步:在线与离线双向验证链。据 Mozilla Server Side TLS 指南,服务器必须发送除根以外的完整中间链,否则 Android 7 之前的客户端和部分 Java 运行时直接握手失败。
# 从线上抓取实际下发的叶证书,看 issuer 是否为中间 CA
openssl s_client -connect example.com:443 -servername example.com
-showcerts /dev/null | openssl x509 -noout -issuer -dates
# 用系统信任库验证本地 fullchain.pem 能否走到根
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt
/etc/letsencrypt/live/example.com/fullchain.pem
# 期望:fullchain.pem: OK
第 3 步:确认定时任务真的排上了。certbot 走 systemd timer,acme.sh 走 cron,两者检查方式不同:
systemctl list-timers | grep certbot # 看 NEXT 列是否在 24h 内
journalctl -u certbot --since '7 days ago' | grep -E 'renew|hook'
crontab -l | grep acme.sh # acme.sh 默认每天 00:17 随机延迟执行
acme.sh --list # 看 Renew 列,通配符会列出两条域名记录
| 检查项 | certbot | acme.sh | 通过标准 |
|---|---|---|---|
| 调度载体 | systemd timer / cron | crontab | NEXT 在未来 24h 内 |
| 生效方式 | deploy hook | reloadcmd | 退出码 0 |
| 试运行 | --dry-run |
--staging |
返回 0 且无 hook 报错 |
第 4 步:查 CT 日志与吊销状态。新证书通常几分钟内出现在 CT 日志,在 crt.sh 搜 example.com 比对 notBefore 即可确认。吊销以 CA 的 CRL 为准:
# 判断证书是否已被提前吊销,避免"文件在但已作废"
openssl crl -in crl.pem -noout -text | head -n 20
# 查看序列号是否落在 Revoked Certificates 列表中
不要只依赖 OCSP:Let’s Encrypt 已按《Ending OCSP Support in 2025》逐步停用 OCSP,改为在证书中写入 CRL Distribution Points 并依赖短期证书加 CT 监控。
第 5 步:季度演练。每季度执行一次 certbot renew --cert-name example.com --dry-run,或 acme.sh --renew -d example.com --staging --force。dry-run 通过而生产失败,八成是生产环境速率限制(每注册域名每周 50 张)、CAA 记录不匹配,或 DNS 服务商 API 限流导致 DNS-01 挑战超时。
第 6 步:监控到期时间与 hook 退出码。Prometheus blackbox_exporter 的 probe_ssl_earliest_cert_expiry 是秒级时间戳,告警表达式写成 probe_ssl_earliest_cert_expiry - time() < 21 * 86400;Zabbix 用 web.certificate.get[example.com,443,,text] 取 expiry。两条告警之外,务必单独监控 deploy hook 退出码——证书已续期但 nginx 未 reload,是通配符证书 renewal 最隐蔽的故障形态。
是。据 Let's Encrypt 文档,HTTP-01 不能验证 `*.example.com`,通配符只能写 `_acme-challenge` TXT 记录。若同时签根域和通配符,一张证书可覆盖两者,但签发时要把 `example.com` 和 `*.example.com` 都列进去。
因为通配符只匹配一级子域,不自动包含根域。签发时需 `-d example.com -d '*.example.com'`,续期后用 `openssl x509 -ext subjectAltName` 检查 SAN 是否同时存在两项。
Certbot 2.11.0 插件化、systemd timer 集成好,适合单云单账号;acme.sh 3.0.7 单文件、DNS API 多、CNAME 委派灵活,适合多 DNS 服务商或多租户。两者用 Let's Encrypt 时证书成本均为 0 元,差异在运维习惯和审计方式。
先 `dig +short TXT _acme-challenge.example.com @1.1.1.1` 和权威 NS 对比;清理旧 TXT,把 TTL 调到 300,acme.sh 加 `–dnssleep 300`,Certbot 加 `–dns-cloudflare-propagation-seconds 180`。多实例续期加 `flock`,避免并发删除同一条 TXT。
通常不会,ACME 客户端会保留旧证书直到新证书签发成功;但不要随意用 `–force-renewal` 覆盖,且要监控剩余 21 天告警。失败后先在 staging 复现,确认 DNS 权限、CAA 和速率限制后再重试生产。
可以,用 step-ca 或内部 ACME 服务签发私有通配符,客户端仍走 DNS-01 或内部挑战。软件成本 0 元,但需维护 CA 根证书、CRL 和审计,约 1–2 人日/月;对外公共服务仍建议用 Let's Encrypt 或商业 OV。
优先 `nginx -t && systemctl reload nginx`,不断开现有连接;Apache 用 `apachectl graceful`,HAProxy 用 `kill -HUP`。Certbot 用 `–deploy-hook`,acme.sh 用 `–reloadcmd`,并让 hook 失败时返回非零退出码。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。