当自定义主机名证书卡在 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 故障排除。
以下错误会出现在自定义主机名对象的 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 支持。 |
如果自定义主机名的 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 令牌在以下情况下会失效:
- 客户放置令牌前,令牌有效期已过(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 作为证书颁发机构时,Cloudflare 会同时请求一张 RSA 证书和一张 ECDSA 证书。每种证书类型都有自己的 DCV 周期,可以独立验证和签发。但只有两张证书都成功签发后,证书包才会被激活或部署。
请客户发布 ssl.validation_records 中返回的每一条 TXT 记录——不要假设记录数量,也不要自行推断哪条对应 RSA 或 ECDSA。该字段列出了所有待处理授权,必须全部满足后证书包才会变为活动状态。
Cloudflare 的 CA 合作伙伴偶尔会将某个域名标记为“高风险”——通常仅针对被 Google Safe Browsing 服务标记为钓鱼或恶意软件的域名。
如果域名被 CA 标记,你需要在验证完成前联系支持。API 调用会返回失败指示,以及可提交工单的链接。
即使已放置正确的 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-challengeTXT 记录正在阻止证书签发——请先删除它,再添加委托 CNAME。 -
如果返回 CNAME 目标,但证书验证仍卡住,冲突很可能来自客户直接 Cloudflare zone 内硬编码的
_acme-challengeTXT 记录。由于解析器会跟随 CNAME 链,而不是在源名称上暴露记录,确认这一点的唯一方法是直接检查客户的 zone:在其 zone 的 Cloudflare 仪表板中前往 DNS > Records(记录),查找任何_acme-challengeTXT 条目。
来自先前 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 请求体,而不是使用原始创建请求中的值。