Cloudflare Troubleshooting 是一个面向 Cloudflare 配置问题的排障技能，核心方法是“用证据调查，而不是用假设诊断”。它建立在通用网络诊断纪律之上，作为 Cloudflare 领域的专门层。
【用途】 用于排查和解决 Cloudflare 的配置问题，典型场景包括：ERR_TOO_MANY_REDIRECTS（重定向次数过多）、SSL 错误、DNS 问题、邮件路由与转发、源站返回 502/503/504 等。技能的价值在于系统化的调查方法论，而不是预设的解决方案。
【核心原则】 在诊断问题之前，始终通过 Cloudflare API 查询实际配置，先收集证据再下结论。
【调查流程】
- 收集凭据：复用用户或项目配置中已提供的域名和已授权的 Cloudflare 连接，只询问缺失的信息（域名、账户邮箱加 Global API Key，或 API Token）。Global API Key 位置：Cloudflare Dashboard → My Profile → API Tokens → View Global API Key。
- 获取 Zone 信息：第一步是通过 zones API 获取 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 '.' 应注意选择与目标域名和账户精确匹配的 zone 及其 account.id，账户或域名身份不明确时不应盲选第一条结果。 - 系统化调查：针对每个问题先收集证据，用 API 检查当前配置状态、近期变更（若审计日志可用）以及可能相互影响的相关设置。
【常见调查模式】
- 重定向循环：检查 SSL/TLS 模式、Always Use HTTPS 设置、Page Rules 中的 redirect（如 forwarding_url 或 always_use_https 动作），并尝试直连源站测试。诊断逻辑如 SSL 模式为 flexible 且源站强制 HTTPS 会形成循环；多个重定向规则可能冲突。修复示例为将 SSL 模式改为 full，并清除缓存。
- 邮件路由与转发：按 Email Routing 处理别名投递、目标验证、catch-all 行为或转发 MX 问题，区分已保存配置与实际收件到达。
- DNS 问题：列出 DNS 记录，使用 dig 与 dig @8.8.8.8 检查外部解析，检查 DNSSEC 状态；关注缺失的 A/AAAA/CNAME 记录、代理状态（proxied 与 DNS-only）、TTL 值和冲突记录。
- SSL 证书错误：检查证书包状态，使用 openssl s_client 检查源站证书，检查最低 TLS 版本、TLS 1.3、Opportunistic Encryption。常见如错误 526（SSL 模式为 strict 但源站证书无效）、错误 525（源站握手失败）、Universal SSL 签发延迟（等待 15-30 分钟）。
- 源站错误（502/503/504）：检查源站可达性、DNS 记录是否指向正确源站、负载均衡配置和防火墙规则。
【学习新 API】 遇到未覆盖的问题时，查阅 Cloudflare API 文档 https://developers.cloudflare.com/api/，用关键词搜索相关端点，先用 GET 请求理解数据结构，确认方案后再用 PATCH/POST 修改。可用 GET /zones/{zone_id}/settings 列出区域可用设置。
【参考资料】 references/api_overview.md 提供按类别整理的常用端点、请求/响应结构、认证模式、速率限制与错误处理；references/ssl_modes.md 提供 SSL/TLS 模式说明、平台兼容性与安全影响；references/common_issues.md 提供问题模式、症状、排查清单与平台特定说明。
【使用方式与最佳实践】 先查询再假设，交叉比对多个数据点，检查相关联配置，用 dig/curl 做外部验证，一次只改一项。解析 JSON 建议使用 jq 或 python；检查响应中的 success 字段和 errors 数组；注意速率限制。HTTP 方法约定：GET 获取信息，PATCH 更新设置，POST 创建资源或触发动作，DELETE 删除资源。修改前先收集证据、定位根因，再定点修复；若配置变更影响交付则清除缓存，并通过重新查询 API 验证。需告知用户等待时间：边缘服务器传播约 30-60 秒，DNS 传播最长 48 小时，浏览器缓存需手动清除。
【安全】 不得在输出中记录 API Key；若用户在公开环境分享凭据应提醒；建议使用限定权限的 API Token 而非 Global API Key；调查阶段使用只读操作。
【脚本】 内置脚本 scripts/check_cloudflare_config.py 与 scripts/fix_ssl_mode.py 可作为调查模式的参考实现、Python 可用时的快速诊断工具和编程式 API 用法示例；但更推荐用 Bash/curl 直接调用 API，以获得灵活性和透明性。技能的核心是调查方法论与 API 知识，而非脚本本身。
【限制】 资料未提供该技能的收费、价格和具体平台支持范围；部分操作（如审计日志）是否可用取决于用户账户情况，资料中未展开说明。