故障排查手册：从 cf-ray 到一个具体的原因
Cloudflare 前面加了一层之后，"网站打不开"的原因分散在五层里：DNS 解析、证书握手、边缘规则、Worker 代码、上游服务。乱猜会浪费大量时间，按层往下走，每一层用一条命令排除，通常三分钟内能定位到具体某一层。
DNS 层的排查细节见 95-dns-troubleshooting-dig.md，攻击相关的判断见 86-attack-triage-order.md。这篇是总顺序与错误码对照。
1. 五层顺序
| 层 | 一条命令 | 排除掉什么 | |
|---|---|---|---|
| 1 DNS | nslookup 你的域名 1.1.1.1 | 解析没生效、指到了旧 IP | |
| 2 证书 | `curl -sI https://域名 \ | head -1` | 握手失败、证书不匹配 |
| 3 边缘 | 看响应头 cf-ray / server | 请求有没有到 Cloudflare | |
| 4 Worker | wrangler tail <worker名> | 代码抛错、超时、额度 | |
| 5 上游 | 直连源站 IP 加 Host 头 | 源站自己挂了 |
顺序不能颠倒。证书错误时去看 Worker 日志是白费力气，请求根本没走到那一步。
2. 状态码对照
| 码 | 含义 | 先查什么 |
|---|---|---|
| 520 | 源站返回了未知响应 | 源站日志，通常是应用崩溃或返回了非 HTTP 内容 |
| 521 | 源站拒绝连接 | 源站进程是否在跑、端口是否监听 |
| 522 | 连接源站超时 | 防火墙、安全组、源站负载 |
| 523 | 源站不可达 | 源站 IP 是否正确（DNS 记录写错） |
| 524 | 源站在 100 秒内没响应 | 慢查询、同步阻塞；这个超时不可调 |
| 525 | TLS 握手失败 | 源站的 SSL 配置、协议版本 |
| 526 | 源站证书无效 | 证书过期、域名不匹配、自签证书 |
| 1016 | 源站 DNS 记录找不到 | CNAME 目标拼错、目标域名已删除 |
| 1020 | 被规则拦截 | WAF、防火墙、Bot 规则 |
| 1027 | Worker 超出额度 | 日请求用尽或 CPU 超限 |
| 1033 | 隧道错误 | Cloudflare Tunnel 没连上 |
| 1101 | Worker 抛了异常 | wrangler tail 看堆栈 |
| 1102 | Worker 超出资源限制 | CPU 时间、内存 |
524 值得单独说：它固定是 100 秒，改不了。源站接口偶尔要跑两分钟，那这个接口就不该同步等，改成异步任务加轮询。
3. cf-ray 怎么用
响应头里的 cf-ray: a58314a2c814045b-HKG，短横线后面是处理这次请求的机房代码。三个用途：
确认请求确实到了 Cloudflare。没有 cf-ray 说明 DNS 还没切过来，或者本地 DNS 缓存了旧记录。
判断是不是单机房问题。多个地区都报错但 cf-ray 后缀不同，说明是全局配置问题；只有某个后缀出问题，可能是该机房到源站的链路。
给支持提单。cf-ray 是 Cloudflare 支持定位请求的唯一凭据，出问题时先把它记下来。
4. 最小验证集
# 1. 解析
nslookup example.com 1.1.1.1
# 2. 完整响应头，不跟随跳转
curl -sI https://example.com/ | head -20
# 3. 带 Host 头直连源站，绕过 Cloudflare
curl -sI https://1.2.3.4/ -H "Host: example.com" -k
# 4. Worker 实时日志
npx wrangler tail cf97-url-shortener --format pretty第 3 步是关键的分叉点：直连源站正常、走 Cloudflare 异常，问题在边缘配置或 Worker；两边都异常，问题在源站。用 -k 跳过证书校验是为了排除证书因素，不是因为证书不重要。
5. 六种典型症状
全站 522，源站一切正常。多半是源站防火墙拦了 Cloudflare 的 IP 段，或者只放行了 80 没放行 443。让源站看连接日志里有没有来自 Cloudflare 的请求。
静态页正常，接口全挂。Worker 或 Pages Functions 的问题，先 wrangler tail 看有没有异常，再看是不是额度用尽（1027）。
只在部分地区慢。看 cf-ray 后缀分布。如果集中在某个机房，可能该机房回源链路异常，这种只能等或换源站区域。
重定向循环。curl -sIL 看每一跳的 location。常见原因是 SSL/TLS 模式设成了 Flexible，源站又强制跳 HTTPS，两边互相跳。
证书报错但控制台显示有效。检查是不是 Universal SSL 还没签发完（新接入的域名最长要等 24 小时），或者访问的是没覆盖的二级子域（免费证书只覆盖一级）。
偶发 520，重试就恢复。单次 520 且重试正常，通常是源站某个工作进程重启或返回了空响应。如果每小时出现几次，去看源站的进程数与内存，多半是 OOM 被杀后在重启。
改了 DNS 但没生效。TTL 和本地缓存。nslookup 指定 1.1.1.1 能拿到新记录，说明是本地或运营商缓存，等 TTL 过期即可。
6. 常见问题
wrangler tail 连不上怎么办？它走 WebSocket 到 Cloudflare，公司网络或代理可能拦。换成控制台的实时日志页面，或者临时在代码里 console.log 后看 Workers Logs。
怎么区分"我的代码慢"和"上游慢"？在 Worker 里打时间戳，performance.now() 夹住 fetch 前后，两个差值一看便知。CPU 时间不包括等上游的时间，所以 1102 通常是计算密集而不是 IO 慢。
需要每次都从头查一遍吗？不需要。把上面五层做成一个检查脚本，出问题时一次跑完，输出每层结果。状态页与告警的搭建见 101-project-status-page.md，配置备份见 103-backup-config-export.md。
小结
排查的效率取决于顺序，不取决于工具多少。DNS、证书、边缘、Worker、上游，五层依次排除，每一层有一条命令能给出是或否，通常两层之内就能定位。直连源站那一步是最有价值的分叉，它把问题一刀切成"边缘侧"和"源站侧"。
错误码表用来快速缩小范围，但不要停在码上。522 只是一个现象，真正的原因是端口、防火墙还是负载，得看源站日志。把 cf-ray、时间点、复现步骤记下来，无论自己查还是找人帮忙都省一半时间。
数据来源与检索时间
检索时间 2026-11-10。
| 来源 | URL | 对应数据 |
|---|---|---|
| 错误码说明 | https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/ | 520–526 的定义与 524 的 100 秒超时 |
| 4xx 与 1xxx 错误 | https://developers.cloudflare.com/support/troubleshooting/http-status-codes/ | 1016、1020、1027、1033 等 |
wrangler tail | https://developers.cloudflare.com/workers/observability/logs/tail/ | 实时日志用法与连接方式 |
| Universal SSL | https://developers.cloudflare.com/ssl/edge-certificates/universal-ssl/ | 签发时间、只覆盖一级子域 |
核验说明
- 文档核对：5xx 与 1xxx 错误码含义、524 的 100 秒、Universal SSL 的覆盖范围与签发时间来自上述页面。
- 真实执行：
cf-ray后缀在本会话的部署验证中出现过-HKG，格式与文中一致；wrangler tail未对已删除的 Worker 运行。 - 未做：没有刻意构造 520/522/525 等错误去验证排查步骤，源站相关章节依据错误码文档与通用排障经验。七个典型症状为归纳，不是逐条复现记录。