跳转至

DNS 提供商与传播检查

DNS-01 挑战的生命周期：写入 TXT 记录 → 等传播 → 通知 CA 验证 → 无论成败都清理记录。记录名为 _acme-challenge.<域名>（通配符去掉 *.）， 记录值为 key authorization 的 SHA-256 摘要（base64url 无填充）。

内置提供商

type_id 展示名 凭据字段 备注
cloudflare Cloudflare api_token V4 REST API，Bearer 认证；先按 zone 换 zone_id；删除只删值相同的记录
aliyun 阿里云 DNS access_key_id、access_key_secret RPC 风格 API（HMAC-SHA1 签名）；TTL 被 clamp 到 600–86400（低于 600 阿里云直接 400）

通用行为：

  • 凭据反序列化前对所有字符串字段 trim 首尾空白（粘贴带换行不致认证失败）。
  • create_txt / delete_txt 幂等：记录本不存在视为成功。
  • zone 由调用方显式给出，不从记录名推导（公共后缀如 .co.uk 会推错）。

写入与清理语义

cert.apply 对每个授权域名执行：

  1. 写前先查：同值记录已存在 → 幂等跳过；异值残留 → 直接报错（防止 CA 读到旧值验签失败）。
  2. 写入 TXT 记录。
  3. 等传播（见下，可用 wait_propagation=false 关闭）。
  4. 通知 CA 挑战就绪。
  5. 无论成败都清理：action 失败报原始错误（清理失败只 warn）；成功但清理 失败则优先报清理错误。

传播等待

默认策略：先向 provider 侧确认记录确实写入，再检查解析器可见性。 默认间隔 5 秒、总超时 120 秒；单次解析器查询上限 5 秒。

权威 NS 直查（默认）

默认不走公共 DoH，而是直查权威 NS：

  1. 经可信公共引导 DNS（阿里 223.5.5.5、腾讯 119.29.29.29、114、百度、 1.1.1.1、8.8.8.8、9.9.9.9 等，仅一跳）查出 zone 的 NS 委派及其 A/AAAA。
  2. 对每台 NS 直接查 TXT/CNAME。

判定规则：

  • 全部应答 NS 一致才算可见（anycast POP 有同步延迟，防 CA 打到滞后 POP 吃 NXDOMAIN）；单台失败跳过，全部失败才报错。
  • NXDOMAIN/NODATA 是合法的「还没有」，继续等。
  • CNAME 也只信权威直查：全部 NS 给出同一 CNAME 才跟随（支持挑战记录独立 托管到别的 zone）。

不走公共 DoH 的原因：公共解析器的 NXDOMAIN 负缓存（SOA minimum 通常 600–1800 秒）会让「写入 → 删除 → 重试」的第二次尝试稳定查不到新值。

自定义解析器

显式设置后改用配置而非权威直查：

  • 环境变量 ACMECAST_DOH_RESOLVERS：逗号分隔的 名称=端点（或仅端点）； none = 跳过传播等待（provider 确认写入后立即让 CA 验证，不推荐）。
  • config.toml 的 [[resolvers]] 段，见配置参考。
  • 合并顺序：内置 → config 条目 → 环境变量，按归一化端点去重。

此模式下任一解析器看到记录即算就绪（要求全部看到会被最慢/不可达的 拖死）；查询失败按「不可达」归并，不参与判定。

超时错误会区分两种形态：「提供商侧没认」与「解析器没看到/不可达」，排障时 先确认是哪种。

内置公共 DNS 清单

  • UDP 53：223.5.5.5、223.6.6.6、119.29.29.29、114.114.114.114、 114.114.115.115、180.76.76.76、1.1.1.1、8.8.8.8、9.9.9.9、149.112.112.112
  • DoH：dns.alidns.com、doh.pub、1.12.12.12、120.53.53.53、223.5.5.5、 dns.google、cloudflare-dns.com、1.1.1.1（均 /dns-query）

HTTP-01 的现状

HTTP-01 目前只有材料计算能力（token、/.well-known/acme-challenge/<token> 路径、key authorization 响应体），没有投放通道。申请证书请使用 DNS-01。