跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

故障排除

最后更新 查看 MarkdownAgent 设置

当自定义主机名证书卡在 Pending Validation(待验证) 或签发失败时,说明某个域控制验证 (DCV) 步骤未成功完成。

职责

SaaS 的 DCV 涉及双方,职责不同。排查具体错误前,请先用下表确认该由谁采取行动。

SaaS 提供商 你的客户
控制范围 DCV 方法选择(TXT 或 HTTP)、CA 选择、向客户交付 DCV 令牌 DNS 设置(NS 记录、DNSSEC)、CAA 记录、指向你的 SaaS 目标的 DNS CNAME
负责事项 生成并共享新的 DCV 令牌;在被速率限制或阻止时切换 CA;确保 Workers 不拦截 DCV 路径 将 TXT DCV 记录放入 DNS(用于 TXT 验证);将自定义主机名 CNAME 指向你的 SaaS 目标(用于 HTTP 验证);修复 DNSSEC;更新 CAA 记录以允许所选 CA

CA 错误参考 会指明每类错误该由谁处理。


快速检查清单

在调查具体错误前,请先确认以下事项:

  • 已放置 DCV 令牌 — 对于 TXT 验证:客户已将 ssl.validation_records 中返回的每条 TXT 记录添加到其 DNS。对于 HTTP 验证,由谁提供令牌取决于所用方法:
    • 自动 HTTP:自定义主机名 CNAME(或 apex A 记录)指向你的 SaaS 目标后,由 Cloudflare 提供令牌。客户无需自行放置令牌。
    • 手动 HTTP:你在源站按 ssl.validation_records[].http_url 指定的路径提供 DCV 令牌,并返回 ssl.validation_records[].http_body 中的正文。详情请参阅 HTTP 验证。
  • 令牌未过期 — Let's Encrypt 令牌在 7 天后过期。Google Trust Services 和 SSL.com 令牌在 14 天后过期。如果令牌可能已过期,请刷新令牌。
  • CAA 记录允许该 CA — CAA 记录会从主机名沿 DNS 树向上评估。CA 会先检查自定义主机名本身(例如 shop.example.com),仅当该子域没有 CAA 记录时才会上移到父域(example.com)。任何包含 CAA 记录的层级上,限制性记录都会阻止签发。详情请参阅 CAA 记录。
  • DNS 可达 — 客户的权威 DNS 必须能从所有地理位置响应,且不能返回 SERVFAIL。
  • 没有 Worker 拦截 DCV 路径 — 如果 SaaS zone 使用 Worker 作为回退源站,请确保它原样放行 /.well-known/pki-validation/* 和 /.well-known/acme-challenge/*。

适用于所有 Cloudflare zone 的 DCV 问题(WAF 规则、重定向、DNS 配置),请参阅 DCV 故障排除。


CA 错误参考

以下错误会出现在自定义主机名对象的 ssl.validation_errors 中。

错误消息 原因 由谁处理 解决方法
Certificate authority encountered a SERVFAIL during DNS lookup, please check your DNS reachability. CA 无法到达客户的权威 DNS 服务器。 你的客户 检查 DNS 可达性。确保 NS 记录健康,且可从所有地理位置访问。使用 DNSViz ↗ 诊断问题。
dns problem: looking up caa for <hostname>: dnssec: bogus 该主机名的 DNSSEC 验证失败。 你的客户 在权威 DNS 提供商处修复 DNSSEC 配置。使用 DNSViz ↗ 识别无效签名。
CAA records block issuance. Please remove all CAA records or add records for this authority. 客户的 CAA 记录不允许所选 CA 为其域名签发证书。 你的客户 请客户为所选 CA 添加 CAA 记录,或移除限制性 CAA 记录。各 CA 所需的准确记录请参阅 CAA 记录。
Certificate authority encountered a multiple perspective CAA check error, please ensure your DNS is configured to allow CAA queries from all geographic perspectives. CA 会从多个地理位置进行验证;CAA 记录在所有位置返回的结果不一致。 你的客户 确保 CAA 记录已在所有权威 DNS 服务器上完全传播。检查可能因查询来源不同而返回不同结果的 split-horizon DNS 配置。
The authority has rate limited these domains. Please wait for the rate limit to expire or try another authority. 由于近期请求过多,CA 已暂时阻止为此域名签发证书。 你 等待错误响应中给出的重试窗口后再试。或者切换到其他 CA(需要 Enterprise 计划):调用 Edit Custom Hostname 端点,将 ssl.certificate_authority 设为 google、lets_encrypt 或 ssl_com(或设为 "" 以让 Cloudflare 选择)。
Internal error with Certificate Authority. Please check later. CA 侧的瞬时错误。 你 等待后重试。若错误持续,请通过 Edit Custom Hostname 端点切换 CA,或联系 Cloudflare 支持。

CAA 记录

如果自定义主机名的 ssl.validation_errors 包含与 CAA 相关的错误,说明客户的 CAA 记录阻止了证书颁发机构为其域名签发证书。此问题需要由客户解决。

请客户同时检查子域和父域级别的 CAA 记录,因为两者都可能具有权威性:

dig CAA shop.example.com
dig CAA example.com

这些记录必须允许你为该自定义主机名所选的证书颁发机构。请根据所选 CA 添加相应记录:

# Google Trust Services
example.com CAA 0 issue "pki.goog; cansignhttpexchanges=yes"
# Add issuewild only if you need wildcard certificates
example.com CAA 0 issuewild "pki.goog; cansignhttpexchanges=yes"

# Let's Encrypt
example.com CAA 0 issue "letsencrypt.org"
# Add issuewild only if you need wildcard certificates
example.com CAA 0 issuewild "letsencrypt.org"

# SSL.com
example.com CAA 0 issue "ssl.com"
# Add issuewild only if you need wildcard certificates
example.com CAA 0 issuewild "ssl.com"

如果客户不打算限制证书签发,可以移除所有 CAA 记录。更多详情请参阅 CAA 记录常见问题。


过期或失效的 DCV 令牌

DCV 令牌在以下情况下会失效:

  • 客户放置令牌前,令牌有效期已过(Let's Encrypt:7 天;Google Trust Services 和 SSL.com:14 天)。
  • 自定义主机名被删除后重新创建。

自定义主机名显示 ssl.status: pending_validation,且 ssl.validation_errors 报告某个客户认为已正确配置的域名缺少令牌;或者客户确认已放置令牌,但验证仍未推进。

要请求 DCV 重新检查,请向 Edit Custom Hostname 端点发送配置中立的 PATCH 请求。先用 GET 请求获取当前主机名,然后原样回传返回的 ssl.method、ssl.type 和 ssl.settings。省略或更改其中任何字段,可能会重置非默认设置(例如 Early Hints 或最低 TLS 版本)。

API 调用示例

# Step 1: retrieve the current ssl configuration
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>"

# Step 2: send a PATCH using the ssl object from the GET response.
# ssl.settings must be included as an object if present; omit the field entirely if absent or null.
curl --request PATCH \
  "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "ssl": {
      "method": "<method_from_get>",
      "type": "dv",
      "settings": { <ssl_settings_object_from_get> }
    }
  }'

验证超时

当 DCV 在重试计划结束前仍未完成时,自定义主机名会进入 Timed Out Validation(验证超时)(ssl.status: validation_timed_out)。

要重新启动 DCV 周期,请向 Edit Custom Hostname 端点发送配置中立的 PATCH 请求。先用 GET 请求获取当前主机名,然后原样回传返回的 ssl.method、ssl.type 和 ssl.settings。

API 调用示例

# Step 1: retrieve the current ssl configuration
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>"

# Step 2: send a PATCH using the ssl object from the GET response.
# ssl.settings must be included as an object if present; omit the field entirely if absent or null.
curl --request PATCH \
  "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "ssl": {
      "method": "<method_from_get>",
      "type": "dv",
      "settings": { <ssl_settings_object_from_get> }
    }
  }'

发送 PATCH 后,轮询 Custom Hostname Details 端点并检查 ssl.validation_records。仅当令牌值发生变化时,才与客户共享更新后的令牌。请确保令牌在再次过期前完成放置。


SSL.com:RSA 与 ECDSA 各自独立的 DCV 周期

使用 SSL.com 作为证书颁发机构时,Cloudflare 会同时请求一张 RSA 证书和一张 ECDSA 证书。每种证书类型都有自己的 DCV 周期,可以独立验证和签发。但只有两张证书都成功签发后,证书包才会被激活或部署。

请客户发布 ssl.validation_records 中返回的每一条 TXT 记录——不要假设记录数量,也不要自行推断哪条对应 RSA 或 ECDSA。该字段列出了所有待处理授权,必须全部满足后证书包才会变为活动状态。


高风险域名

Cloudflare 的 CA 合作伙伴偶尔会将某个域名标记为“高风险”——通常仅针对被 Google Safe Browsing 服务标记为钓鱼或恶意软件的域名。

如果域名被 CA 标记,你需要在验证完成前联系支持。API 调用会返回失败指示,以及可提交工单的链接。


冲突的 _acme-challenge TXT 记录

即使已放置正确的 CNAME 或 TXT 记录,证书验证仍卡住时,可能是冲突的 _acme-challenge TXT 记录阻止了证书颁发机构完成验证。

如何诊断

检查 _acme-challenge 主机名上是否已放置委托 CNAME:

dig _acme-challenge.example.com CNAME +short
  • 如果返回空,说明委托 CNAME 缺失。再运行 TXT 查询,检查是否还存在硬编码记录:

    dig _acme-challenge.example.com TXT +short

    如果返回原始令牌字符串,说明硬编码的 _acme-challenge TXT 记录正在阻止证书签发——请先删除它,再添加委托 CNAME。

  • 如果返回 CNAME 目标,但证书验证仍卡住,冲突很可能来自客户直接 Cloudflare zone 内硬编码的 _acme-challenge TXT 记录。由于解析器会跟随 CNAME 链,而不是在源名称上暴露记录,确认这一点的唯一方法是直接检查客户的 zone:在其 zone 的 Cloudflare 仪表板中前往 DNS > Records(记录),查找任何 _acme-challenge TXT 条目。

常见原因与修复

来自先前 Cloudflare 证书订单的记录 — Cloudflare 会在证书签发期间添加 _acme-challenge TXT 记录。先前或已放弃订单留下的记录可能仍然存在,且不一定会显示在 Cloudflare 仪表板中。联系 Cloudflare 支持 以将其移除。

位于直接 Cloudflare zone 中的记录 — 如果客户的域名也存在于一个直接 Cloudflare zone 中(例如他们通过自己的 Cloudflare 账户代理 example.com),该 zone 可能包含来自 Universal SSL 或 Advanced 证书订单的 _acme-challenge TXT 记录。当证书颁发机构查询 _acme-challenge.example.com 时,它会解析直接 zone 中的记录,而不是跟随委托 DCV CNAME。

要解决此问题,请客户在 Cloudflare 仪表板的 DNS 设置中从其 zone 删除 _acme-challenge TXT 记录,然后触发立即验证检查。


立即验证检查

你可以向 Edit Custom Hostname 端点发送 PATCH 请求,以请求对任意证书立即进行验证检查。请先用 GET 请求获取当前主机名,并将当前 ssl 对象(若存在则包含 ssl.settings)作为 PATCH 请求体,而不是使用原始创建请求中的值。


相关资源

这篇文档对您有帮助吗?