cloudflare-troubleshooting

Cloudflare 故障排查

**方法论基础：**通用的、以证据为驱动的网络诊断规范（证伪、分层隔离、交叉审查）位于 debugging-network-issues 技能中。本技能是在此基础上的 Cloudflare 领域 层。

核心原则

**以证据开展调查，而非依赖假设。**诊断问题前，务必查询 Cloudflare API，检查实际配置。本技能的价值在于系统化的调查方法，而非预设解决方案。

调查方法

1. 获取凭据

重复使用用户或项目配置中已提供的域名和经过授权的 Cloudflare 连接。仅询问缺失的连接信息：域名、账户邮箱和 Global API Key，或 API Token。保留当前使用的身份验证方式；故障排查无需更换。

Global API Key 位置：Cloudflare Dashboard → My Profile → API Tokens → View Global API Key

2. 获取 Zone 信息

对于针对 Zone 的故障排查，获取 Zone ID：

curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=<domain>" \
  -H "X-Auth-Email: <email>" \
  -H "X-Auth-Key: <api_key>" | jq '.'

提取 id 前，先选择完全匹配的 Zone 和账户；当账户或域名身份不明确时，不要盲目选择首个结果。对于针对账户的调用，请使用该 Zone 的 account.id。

如果某个 Pages 主机名从未绑定过，那么精确 Zone 查询返回空结果是一项调查发现，而不是账户 ID，也不能证明网站不存在。请根据经过授权的配置确定现有账户/项目，并按照 Pages 自定义域名和 DNSSEC 迁移 操作。不要仅为让此查询成功而创建 Zone。

3. 系统化调查

针对每个问题，先收集证据，再得出结论。使用 Cloudflare API 检查：

• 当前配置状态
• 最近的变更（如果有审计日志）
• 可能相互影响的相关设置

常见调查模式

重定向循环（ERR_TOO_MANY_REDIRECTS）

证据收集顺序：

1. 检查 SSL/TLS 模式：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

   查找：result.value——用于确定当前 SSL 模式

2. 检查 Always Use HTTPS 设置：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/always_use_https" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

3. 检查 Page Rules 中的重定向：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/pagerules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

   查找：forwarding_url 或 always_use_https 操作

4. 直接测试源服务器（如果可行）：

   curl -I -H "Host: <domain>" https://<origin_ip>
   

诊断逻辑：

• SSL 模式为 "flexible" + 源服务器强制使用 HTTPS = 重定向循环
• 多条重定向规则可能相互冲突
• 检查浏览器与 curl 的行为差异

修复：

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

如果修复后仍存在过时的 HTTP 重定向，请清除相关的 HTTP 缓存：

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key" \
  -d '{"purge_everything":true}'

电子邮件路由与转发

对于别名投递、目标地址验证、全收配置或转发 MX 问题，请按照 电子邮件路由 操作。该指南提供账户/Zone API 读取顺序，并区分已保存的配置与邮件是否实际到达收件箱。

DNS 问题

如果 pages.dev 网站正常运行，但自定义主机名无法访问、缺少 Pages 绑定，或者正在进行名称服务器/DNSSEC 迁移，请在更改 DNS 前加载 Pages 自定义域名和 DNSSEC 迁移。该指南会分别检查注册商身份、父级发布、递归缓存以及正常主机名是否被接受。

证据收集：

1. 列出 DNS 记录：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

2. 检查外部 DNS 解析：

   dig <domain>
   dig @8.8.8.8 <domain>
   

3. 检查 DNSSEC 状态：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dnssec" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

查找：

• 缺失的 A/AAAA/CNAME 记录
• 代理状态错误（已代理或仅 DNS）
• TTL 值
• 冲突的记录

SSL 证书错误

证据收集：

1. 检查 SSL 证书状态：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/ssl/certificate_packs" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

2. 检查源站证书（如果使用 Full Strict）：

   openssl s_client -connect <origin_ip>:443 -servername <domain>
   

3. 检查 SSL 设置：

   • 最低 TLS 版本
   • TLS 1.3 状态
   • Opportunistic Encryption

常见问题：

• 错误 526：SSL 模式为“strict”，但源站证书无效
• 错误 525：源站 SSL 握手失败
• 证书签发延迟：检查所选产品的证书／域名验证状态，并报告剩余的前置条件或待处理状态

源站服务器错误（502/503/504）

证据收集：

1. 检查源站是否可访问：

   curl -I -H "Host: <domain>" https://<origin_ip>
   

2. 检查 DNS 记录是否指向正确的源站：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

3. 检查负载均衡器配置（如适用）：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/load_balancers" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

4. 检查防火墙规则：

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/firewall/rules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   

学习新的 API

遇到上述未涵盖的问题时，请查阅 Cloudflare API 文档：

1. 浏览 API 参考： https://developers.cloudflare.com/api/
2. 使用问题关键词搜索相关端点
3. 检查 API 架构，了解可用操作
4. 先使用 GET 请求测试，以了解数据结构
5. 确认方案后，使用 PATCH/POST 进行更改

探索新 API 的模式：

# List available settings for a zone
curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key"

API 参考概览

请查阅 references/api_overview.md，了解：

• 按类别整理的常用端点
• 请求／响应架构
• 身份验证模式
• 速率限制和错误处理

请查阅 references/ssl_modes.md，了解：

• SSL/TLS 模式的详细说明
• 平台兼容性
• 安全影响

请查阅 references/common_issues.md，了解：

• 问题模式和症状
• 调查检查清单
• 特定于平台的说明

最佳实践

基于证据的调查

1. 先查询再假设——使用 API 检查实际状态
2. 收集多个数据点——交叉核对设置
3. 检查相关配置——设置之间通常会相互影响
4. 从外部验证——使用 dig/curl 确认
5. 逐步测试——每次只做一项更改

API 使用

1. 解析 JSON 响应——使用 jq 或 python 提高可读性
2. 检查 success 字段——响应中的 "success": true/false
3. 妥善处理错误——读取响应中的 errors 数组
4. 遵守速率限制——Cloudflare API 有速率限制
5. 使用适当的方法：
   • GET：获取信息
   • PATCH：更新设置
   • POST：创建资源／触发操作
   • DELETE：删除资源

进行更改

1. 先收集证据——了解当前状态
2. 确定根本原因——不要猜测
3. 应用有针对性的修复——只更改必要内容
4. 仅在问题涉及 HTTP 缓存时清除缓存——清除 CDN 缓存不会发布注册商更改，也不会清除递归 DNS 缓存
5. 验证修复——重新查询 API 以确认
6. **报告等待阶段和下一次观测时机：**依据当前激活状态、注册局发布策略和观测到的 TTL。注册商保存、父级发布和客户端恢复可能发生在不同时间；没有证据时，不要指定固定等待时间或建议清除浏览器缓存。

安全

• 切勿在输出中记录 API 密钥
• 如果用户在公开场合分享凭据，应予以提醒
• 建议使用权限受限的 API Tokens，而不是 Global API Key
• 调查时使用只读操作

工作流模板

1. Reuse the configured domain and authorized API connection; obtain only missing values
2. Get zone_id via zones API
3. Investigate:
   - Query relevant APIs for evidence
   - Check multiple related settings
   - Verify with external tools (dig, curl)
4. Analyze evidence to determine root cause
5. Apply fix via appropriate API endpoint
6. Purge HTTP cache only if stale HTTP content is implicated
7. Verify fix via API query and normal-hostname external testing; provider or forced-IP success alone is partial
8. Inform user of resolution and any required actions

示例：完整调查

当用户报告“网站显示 ERR_TOO_MANY_REDIRECTS”时：

# 1. Get zone ID
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" | jq '.result[] | select(.name == "example.com") | {id, account}'

# Select the intended account from the exact-domain result before using its id.
# 2. Check SSL mode (primary suspect for redirect loops)
curl -s -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" | jq '.result.value'

# If returns "flexible" and origin is GitHub Pages/Netlify/Vercel:

# 3. Fix by changing to "full"
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

# 4. Only if stale HTTP redirects remain, purge HTTP cache
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "X-Auth-Email: [email protected]" \
  -H "X-Auth-Key: abc123" \
  -d '{"purge_everything":true}'

# 5. Recheck the ordinary hostname and browser; report observed recovery or the unresolved layer

脚本的适用场景

附带的脚本（scripts/check_cloudflare_config.py、scripts/fix_ssl_mode.py）可用作：

• 调查模式的参考实现
• Python 可用时的快速诊断工具
• 以编程方式调用 API 的示例

不过，为保持灵活性和透明度，优先通过 Bash/curl 直接调用 API。脚本不应限制能力——方便时可以使用，但在以下情况下应使用原始 API 调用：

• 不熟悉的场景
• 边缘情况
• 学习/调试
• 脚本未涵盖的操作

调查方法和 API 知识才是核心技能，而不是脚本。