cloudflare-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Troubleshooting

Cloudflare 故障排查

Core Principle

核心原则

Investigate with evidence, not assumptions. Always query Cloudflare API to examine actual configuration before diagnosing issues. The skill's value is the systematic investigation methodology, not predetermined solutions.

基于证据调查，而非主观假设。 在诊断问题前，务必通过查询Cloudflare API来检查实际配置。这项技能的价值在于系统性的调查方法，而非预设的解决方案。

Investigation Methodology

调查方法

1. Gather Credentials

1. 收集凭证

Request from user:

Domain name
Cloudflare account email
Cloudflare Global API Key (or API Token)

Global API Key location: Cloudflare Dashboard → My Profile → API Tokens → View Global API Key

向用户获取：

域名
Cloudflare账户邮箱
Cloudflare全局API密钥（或API令牌）

全局API密钥位置：Cloudflare控制台 → 我的资料 → API令牌 → 查看全局API密钥

2. Get Zone Information

2. 获取Zone信息

First step for any Cloudflare troubleshooting - obtain the zone ID:

bash

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 '.'

Extract

zone_id

from

result[0].id

for subsequent API calls.

任何Cloudflare故障排查的第一步 - 获取Zone ID：

bash

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 '.'

从

result[0].id

中提取

zone_id

，用于后续API调用。

3. Investigate Systematically

3. 系统性调查

For each issue, gather evidence before making conclusions. Use Cloudflare API to inspect:

Current configuration state
Recent changes (if audit log available)
Related settings that might interact

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

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

Common Investigation Patterns

常见调查模式

Redirect Loops (ERR_TOO_MANY_REDIRECTS)

重定向循环（ERR_TOO_MANY_REDIRECTS）

Evidence gathering sequence:

Check SSL/TLS mode:

bash

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

Look for:

result.value

- tells current SSL mode

Check Always Use HTTPS setting:

bash

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"

Check Page Rules for redirects:

bash

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

Look for:

forwarding_url

always_use_https

actions

Test origin server directly (if possible):

bash

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

Diagnosis logic:

SSL mode "flexible" + origin enforces HTTPS = redirect loop
Multiple redirect rules can conflict
Check browser vs curl behavior differences

Fix:

bash

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"}'

Purge cache after fix:

bash

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}'

证据收集流程：

检查SSL/TLS模式：

bash

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模式

检查始终使用HTTPS设置：

bash

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"

检查页面规则中的重定向：

bash

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

动作

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

bash

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

诊断逻辑：

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

修复方案：

bash

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"}'

修复后清除缓存：

bash

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}'

DNS Issues

DNS问题

Evidence gathering:

List DNS records:

bash

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

Check external DNS resolution:
bash
```
dig <domain>
dig @8.8.8.8 <domain>
```

Check DNSSEC status:

bash

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

Look for:

Missing A/AAAA/CNAME records
Incorrect proxy status (proxied vs DNS-only)
TTL values
Conflicting records

证据收集：

列出DNS记录：

bash

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

检查外部DNS解析：
bash
```
dig <domain>
dig @8.8.8.8 <domain>
```

检查DNSSEC状态：

bash

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记录
不正确的代理状态（已代理 vs 仅DNS）
TTL值
冲突的记录

SSL Certificate Errors

SSL证书错误

Evidence gathering:

Check SSL certificate status:

bash

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"

Check origin certificate (if using Full Strict):

bash

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

Check SSL settings:
- Minimum TLS version
- TLS 1.3 status
- Opportunistic Encryption

Common issues:

Error 526: SSL mode is "strict" but origin cert invalid
Error 525: SSL handshake failure at origin
Provisioning delay: Wait 15-30 minutes for Universal SSL

证据收集：

检查SSL证书状态：

bash

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"

检查源服务器证书（如果使用Full Strict模式）：

bash

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

检查SSL设置：
- 最低TLS版本
- TLS 1.3状态
- 机会性加密

常见问题：

错误526：SSL模式为"strict"但源服务器证书无效
错误525：源服务器SSL握手失败
配置延迟：等待15-30分钟让Universal SSL生效

Origin Server Errors (502/503/504)

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

Evidence gathering:

Check if origin is reachable:

bash

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

Check DNS records point to correct origin:

bash

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

Review load balancer config (if applicable):

bash

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

Check firewall rules:

bash

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

证据收集：

检查源服务器是否可达：

bash

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

检查DNS记录是否指向正确的源服务器：

bash

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

查看负载均衡器配置（如果适用）：

bash

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

检查防火墙规则：

bash

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

Learning New APIs

学习新API

When encountering issues not covered above, consult Cloudflare API documentation:

Browse API reference: https://developers.cloudflare.com/api/
Search for relevant endpoints using issue keywords
Check API schema to understand available operations
Test with GET requests first to understand data structure
Make changes with PATCH/POST after confirming approach

Pattern for exploring new APIs:

bash

undefined

当遇到上述未覆盖的问题时，参考Cloudflare API文档：

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

探索新API的模式：

bash

undefined

List available settings for a zone

列出Zone的可用设置

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

undefined

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

undefined

API Reference Overview

API参考概述

Consult

references/api_overview.md

for:

Common endpoints organized by category
Request/response schemas
Authentication patterns
Rate limits and error handling

Consult

references/ssl_modes.md

for:

Detailed SSL/TLS mode explanations
Platform compatibility
Security implications

Consult

references/common_issues.md

for:

Issue patterns and symptoms
Investigation checklists
Platform-specific notes

参考

references/api_overview.md

获取：

按类别整理的常见端点
请求/响应Schema
认证模式
速率限制与错误处理

参考

references/ssl_modes.md

获取：

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

参考

references/common_issues.md

获取：

问题模式与症状
调查检查表
平台特定说明

Best Practices

最佳实践

Evidence-Based Investigation

基于证据的调查

Query before assuming - Use API to check actual state
Gather multiple data points - Cross-reference settings
Check related configurations - Settings often interact
Verify externally - Use dig/curl to confirm
Test incrementally - One change at a time

先查询再假设 - 使用API检查实际状态
收集多个数据点 - 交叉验证设置
检查相关配置 - 设置通常会相互影响
外部验证 - 使用dig/curl确认
增量测试 - 一次只做一项变更

API Usage

API使用

Parse JSON responses - Use
```
jq
```
or python for readability
Check success field -
```
"success": true/false
```
in responses
Handle errors gracefully - Read
```
errors
```
array in responses
Respect rate limits - Cloudflare API has limits
Use appropriate methods:
- GET: Retrieve information
- PATCH: Update settings
- POST: Create resources / trigger actions
- DELETE: Remove resources

解析JSON响应 - 使用
```
jq
```
或Python提升可读性
检查success字段 - 响应中的
```
"success": true/false
```
优雅处理错误 - 读取响应中的
```
errors
```
数组
遵守速率限制 - Cloudflare API有调用限制
使用合适的请求方法：
- GET：获取信息
- PATCH：更新设置
- POST：创建资源 / 触发动作
- DELETE：删除资源

Making Changes

进行变更

Gather evidence first - Understand current state
Identify root cause - Don't guess
Apply targeted fix - Change only what's needed
Purge cache if needed - Especially for SSL/redirect changes
Verify fix - Re-query API to confirm
Inform user of wait times:
- Edge server propagation: 30-60 seconds
- DNS propagation: Up to 48 hours
- Browser cache: Requires manual clear

先收集证据 - 了解当前状态
确定根本原因 - 不要猜测
应用针对性修复 - 只变更必要的设置
必要时清除缓存 - 尤其是SSL/重定向变更后
验证修复 - 重新查询API确认
告知用户等待时间：
- 边缘服务器同步：30-60秒
- DNS同步：最长48小时
- 浏览器缓存：需要手动清除

Security

安全

Never log API keys in output
Warn if user shares credentials in public context
Recommend API Tokens with scoped permissions over Global API Key
Use read-only operations for investigation

切勿在输出中记录API密钥
如果用户在公开场景分享凭证，需发出警告
推荐使用具有权限范围的API令牌，而非全局API密钥
调查阶段使用只读操作

Workflow Template

工作流模板

1. Gather: domain, email, API key
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 cache if configuration change affects delivery
7. Verify fix via API query and external testing
8. Inform user of resolution and any required actions

1. 收集：域名、邮箱、API密钥
2. 通过zones API获取zone_id
3. 调查：
   - 查询相关API收集证据
   - 检查多个相关设置
   - 使用外部工具（dig、curl）验证
4. 分析证据确定根本原因
5. 通过合适的API端点应用修复
6. 如果配置变更影响内容分发，清除缓存
7. 通过API查询和外部测试验证修复
8. 告知用户解决方案及任何必要操作

Example: Complete Investigation

示例：完整调查流程

When user reports "site shows ERR_TOO_MANY_REDIRECTS":

bash

undefined

当用户反馈"网站显示ERR_TOO_MANY_REDIRECTS"时：

bash

undefined

1. Get zone ID

1. 获取Zone ID

curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com"
-H "X-Auth-Email: user@example.com"
-H "X-Auth-Key: abc123" | jq '.result[0].id'

2. Check SSL mode (primary suspect for redirect loops)

2. 检查SSL模式（重定向循环的主要嫌疑点）

curl -s -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl"
-H "X-Auth-Email: user@example.com"
-H "X-Auth-Key: abc123" | jq '.result.value'

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

如果返回"flexible"且源服务器为GitHub Pages/Netlify/Vercel：

3. Fix by changing to "full"

3. 修改为"full"模式修复

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl"
-H "X-Auth-Email: user@example.com"
-H "X-Auth-Key: abc123"
-H "Content-Type: application/json"
--data '{"value":"full"}'

4. Purge cache

4. 清除缓存

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache"
-H "X-Auth-Email: user@example.com"
-H "X-Auth-Key: abc123"
-d '{"purge_everything":true}'

5. Inform user: Wait 60 seconds, clear browser cache, retry

5. 告知用户：等待60秒，清除浏览器缓存后重试

undefined

undefined

When Scripts Are Useful

脚本的适用场景

The bundled scripts (

scripts/check_cloudflare_config.py

scripts/fix_ssl_mode.py

) serve as:

Reference implementations of investigation patterns
Quick diagnostic tools when Python is available
Examples of programmatic API usage

However, prefer direct API calls via Bash/curl for flexibility and transparency. Scripts should not limit capability - use them when convenient, but use raw API calls when needed for:

Unfamiliar scenarios
Edge cases
Learning/debugging
Operations not covered by scripts

The investigation methodology and API knowledge is the core skill, not the scripts.

附带的脚本（

scripts/check_cloudflare_config.py

、

scripts/fix_ssl_mode.py

）用于：

作为调查模式的参考实现
当Python可用时作为快速诊断工具
作为程序化API调用的示例

但优先使用Bash/curl直接调用API以保证灵活性和透明度。脚本不应限制能力 - 方便时使用脚本，但在以下场景使用原生API调用：

不熟悉的场景
边缘案例
学习/调试
脚本未覆盖的操作

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