Cloudflare Cache Reserve 故障排查实战指南常见错误、硬性限制与逐层排障流程【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文是 Cloudflare Cache Reserve基于 R2 构建的持久化缓存层的排障实战手册完整收录该功能在真实生产环境中最高频的 8 类故障资源不入缓存、Range 请求失败、回源带宽异常、Purge 失效、O2O 绕过等逐条给出根因分析与可落地的解决方案并用一张 9 步排查流程图串起从开启开关到Logpush 日志验证的完整排障路径。读完本文你将能根据cf-cache-status、响应头与日志字段快速定位 Cache Reserve 的缓存命中问题并掌握其全部硬性限制最小 TTL、Content-Length、Vary、范围请求等避免为不兼容的流量误付费。本文内容源自 gotchas.md并辅以同目录下的 README、configuration、api 与 patterns 文档进行纵深佐证。Cache Reserve 是什么排障前必须建立的心智模型在进入具体故障之前先明确 Cache Reserve 在整个缓存体系中的位置。根据 README它位于分层缓存的顶端是最接近源站的那一层Visitor Request ↓ Lower-Tier Cache (closest to visitor) ↓ (on miss) Upper-Tier Cache (closest to origin) ↓ (on miss) Cache Reserve (R2 persistent storage) ↓ (on miss) Origin Server它的工作方式是自动的、区Zone级别的缓存未命中时内容会同时写入 Cache Reserve 与边缘缓存边缘缓存被逐出后内容仍保留在 Cache Reserve 中后续请求若边缘未命中而 Cache Reserve 命中内容会被回填到边缘缓存。资产默认保留 30 天自最后一次访问起计算可通过 TTL 配置调整。理解排障问题的一个关键前提在 api.md 中被特别强调Workers 的 Cache API 与 Cache Reserve 是两回事。caches.default/cache.put()只作用于边缘缓存Cache Reserve 是 Zone 级设置、自动生效无法从 Workers 中按请求选择性写入它只与标准fetch()配合工作。这意味着排障时不要试图通过 Workers 代码手动写入 Cache Reserve——你只能通过响应头与 TTL 配置让资产有资格被它缓存。八大常见错误根因分析与解决方案1. 资产未被 Cache Reserve 缓存根因资产本身不可缓存、TTL 小于 10 小时、缺少Content-Length响应头或存在阻塞性响应头Set-Cookie、Vary: *。解决方案确保最小 TTL 达到 10 小时以上例如Cache-Control: public, max-age36000在源站响应中补齐Content-Length头移除Set-Cookie头或改用 private 指令将Vary设置为具体值如Vary: Accept-Encoding而不是*。这与 README 中的资格检查清单完全一致所有条件Zone 开启 Cache Reserve、开启 Tiered Cache、TTL ≥ 10 小时、有Content-Length、无Set-Cookie、Vary非*、非图片转换变体、非 Range 请求、非 O2O 请求必须同时满足缺一不可。2. Range 请求不生效视频拖动进度条失败根因Cache Reserve不支持Range 请求HTTP 206 Partial Content。解决方案Range 请求会完全绕过 Cache Reserve。对于需要拖动进度条的视频流场景只使用边缘缓存采用较短的 TTL考虑使用 R2 直连访问来承载 Range 密集型工作负载接受一个现实可拖动播放的内容无法从 Cache Reserve 的持久化存储中受益。这一点在 README 的选型决策树中也有对应警告视频流带 Range标注为 ✗ 不支持应改用 R2。3. 回源带宽高于预期根因Cache Reserve 从源站拉取的是未压缩的内容尽管它对访问者提供的是压缩后的内容。解决方案如果源站按带宽计费必须把未压缩内容传输的成本计入预算Cache Reserve 会自动为访问者压缩内容节省访问者侧的带宽权衡时需要对比源站出口流量的节省 vs 未压缩拉取带来的更高回源成本。patterns.md 的成本优化指引中同样标注了这一条Cache Reserve 从源站拉取未压缩内容、向访问者提供压缩内容——请将回源出口成本纳入考量。4. Cloudflare Images 不参与 Cache Reserve 缓存根因Cloudflare Images 携带Vary: Accept头用于格式协商这与 Cache Reserve 不兼容。解决方案Cache Reserve 会静默跳过带格式协商Vary的图片原始图片未经转换的可能仍然符合资格对于转换后的图片使用 Cloudflare Images 变体或边缘缓存。注意这里与第 1 条略有差异Vary: Accept-Encoding是允许的但Vary: Accept格式协商会导致图片被跳过——问题的关键在于 Vary 的具体取值与用途。5. Class A 操作费用过高根因缓存未命中过于频繁、TTL 过短、或反复触发重新验证。解决方案对稳定内容提高 TTL建议 24 小时以上开启 Tiered Cache 以减少直接打到 Cache Reserve 的未命中使用 stale-while-revalidate 策略平滑更新。从 api.md 的定价模型可以反推原因缓存未命中 1 次 Class A写入 1 次 Class B读取而缓存命中只产生 1 次 Class B每次未命中都会产生昂贵的 Class A 写入所以降低未命中率更长 TTL、Tiered Cache、SWR是控制成本的关键杠杆。6. Purge 清除不符合预期根因按 Tag 清除只触发重新验证并不会把资产从 Cache Reserve 存储中移除。解决方案按 URL 清除可立即移除或者先禁用 Cache Reserve、再清空全部数据以实现彻底移除。这与 api.md 的 Purge 行为说明完全吻合按 URL 清除立即从 Cache Reserve 与边缘缓存中移除按 tag/host/prefix 清除仅触发重新验证资产仍留在存储中费用会继续产生。7. O2OOrange-to-Orange资产不入缓存根因O2O 请求Cloudflare 上一个已代理的 Zone 请求另一个已代理的 Zone会绕过 Cache Reserve。解决方案什么是 O2OZone A已代理→ Zone B已代理两者都在 Cloudflare 上如何检测检查cf-cache-status是否为BYPASS并审查请求路径替代方案使用 R2 或直连源站访问而不是走 O2O 代理链。8. 清空数据前必须关闭 Cache Reserve根因在 Cache Reserve 仍处于启用状态时尝试清空其数据。解决方案先禁用 Cache Reserve等待传播完成约 5 秒再清空数据清空过程最长可能需要 24 小时。api.md 给出了对应的完整流程禁用 Cache Reserve → 调用POST /zones/{zone_id}/cache/cache_reserve_clear→ 等待最长 24 小时 → 重新启用可通过 GET 同一端点查询状态In-progress/Completed。硬性限制速查表限制项取值说明最小 TTL10 小时36000 秒TTL 更短的资产不具备资格默认保留期30 天2592000 秒可配置最大文件大小与 R2 限制一致无实际限制清除/清空时间最长 24 小时完整传播时间套餐要求付费 Cache Reserve 或 Smart Shield免费套餐不可用Content-Length 头必需必须具备才有资格Set-Cookie 头阻止缓存不能存在或使用 private 指令Vary 头不能为*可以使用Vary: Accept-Encoding图片转换变体不可参与仅原始图片Range 请求不支持HTTP 206 会绕过 Cache Reserve压缩拉取未压缩向访问者提供压缩内容Workers 控制仅限 Zone 级无法按请求控制O2O 请求绕过Orange-to-Orange 不具备资格关于最大文件大小与 R2 限制一致这一点可以参考 r2/gotchas.md 中的 R2 侧限制对象最大 5 TB、分片上传每片最小 5 MB 等来理解无实际限制的边界含义。而套餐要求的背景在 README 中有说明Cache Reserve 是 Smart Shield 的一部分Smart Shield Advanced 档包含 2TB 的 Cache Reserve 存储也可以单独购买已经在用 Smart Shield Advanced 的用户无需额外付费。9 步排查流程图资产不入缓存的完整定位路径当资产没有被 Cache Reserve 缓存时按以下流程逐步排查源自 gotchas.md1. 该 Zone 是否已启用 Cache Reserve → 否通过 Dashboard 或 API 启用 → 是继续第 2 步 2. 是否已启用 Tiered Cache → 否启用 Tiered Cache必需 → 是继续第 3 步 3. 资产 TTL 是否 ≥ 10 小时 → 否通过 Cache Rules 提高 TTLedge_ttl 覆盖 → 是继续第 4 步 4. 是否存在 Content-Length 响应头 → 否修复源站使其返回 Content-Length → 是继续第 5 步 5. 是否存在 Set-Cookie 响应头 → 是移除 Set-Cookie 或将其限定到合适范围 → 否继续第 6 步 6. Vary 头是否被设置为 * → 是改为具体值例如 Accept-Encoding → 否继续第 7 步 7. 这是否是一个 Range 请求 → 是Range 请求会绕过 Cache Reserve不支持 → 否继续第 8 步 8. 这是否是一个 O2OOrange-to-Orange请求 → 是O2O 会绕过 Cache Reserve → 否继续第 9 步 9. 检查 Logpush 的 CacheReserveUsed 字段 → 过滤日志确认资产是否曾命中 Cache Reserve → 验证 cf-cache-status 响应头首个请求后应为 HIT其中第 9 步的验证手段可以进一步细化api.md 提供了 Logpush 查询模板用CacheReserveUsed布尔字段区分命中与未命中SELECT ClientRequestHost, COUNT(*) as requests, SUM(EdgeResponseBytes) as bytes_served, COUNT(CASE WHEN CacheReserveUsed true THEN 1 END) as cache_reserve_hits, COUNT(CASE WHEN CacheReserveUsed false THEN 1 END) as cache_reserve_misses FROM http_requests WHERE Timestamp NOW() - INTERVAL 24 hours GROUP BY ClientRequestHost ORDER BY requests DESC同时也可以在 Dashboard 的Caching Cache Reserve页面观察 Egress Savings、Requests Served命中/未命中分布、Storage Used、Class A/B 操作数与成本估算见 api.md。排障的实操工具与配套命令排查时最常用的三个命令来自 README# 1. 检查 Cache Reserve 状态 curl -X GET https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve \ -H Authorization: Bearer $API_TOKEN # 2. 启用 Cache Reserve curl -X PATCH https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve \ -H Authorization: Bearer $API_TOKEN \ -H Content-Type: application/json \ -d {value: on} # 3. 检查资产的缓存状态看 cf-cache-status curl -I https://example.com/asset.jpg | grep -i cache启用/检查需要 API Token 具备Zone Settings Read、Zone Settings Write、Zone Read、Zone Write权限见 configuration.md。同时记住两个前置条件付费套餐或 Smart Shield Advanced以及Tiered Cache 必须开启。进阶从源头减少故障——让资产天然具备资格很多上述故障其实可以在上线前通过配置规避。结合 patterns.md 的最佳实践1. 用 Cache Rules 为不同内容设置不同 TTL静态不可变资产用 30 天2592000 秒常规图片用 24 小时86400 秒API 路径直接声明cache_reserve: { eligible: false }排除// 为不可变静态资产启用 Cache Reserve 并覆盖 30 天 TTL { action: set_cache_settings, action_parameters: { cache_reserve: { eligible: true }, edge_ttl: { mode: override_origin, default: 2592000 }, // 30 天 cache: true }, expression: (http.request.uri.path matches ^/static/.*\\.[a-f0-9]{8}\\.) }2. 让源站响应头一步到位patterns.md返回Cache-Control: public, max-age86400满足最小 10 小时、带上Content-Length、可选的Cache-Tag用于后续按 Tag 清理与ETag用于重新验证避免Set-Cookie和Vary: *。3. 在 Workers 中修正响应头使其具备资格注意这不能直接控制 Cache Reserve 存储只是让响应头达标见 patterns.mdconst headers new Headers(response.headers); headers.set(Cache-Control, public, max-age36000); // 10hr 最低线 headers.delete(Set-Cookie); // 它会阻止缓存 // 确保 Content-Length 存在 if (!headers.has(Content-Length)) { const blob await response.blob(); headers.set(Content-Length, blob.size.toString()); return new Response(blob, { status: response.status, headers }); }小结Cache Reserve 的绝大多数故障都可以归结为同一组资格条件TTL ≥ 10 小时、有Content-Length、无Set-Cookie、Vary非*、非 Range 请求、非 O2O 请求、非图片转换变体加上 Zone 级开关与 Tiered Cache 都就位。用上文 9 步流程图自上而下逐项核对再用cf-cache-status与 Logpush 的CacheReserveUsed字段做最终验证即可在几分钟内定位问题。对于 Range 视频流、O2O 代理链这类天生不兼容的场景则应尽早改用 R2 直连避免在错误的路径上继续投入排查成本。相关文档导航Cache Reserve 概览与核心概念Cache Reserve 配置指南Dashboard / API / SDK / Terraform / Cache RulesCache Reserve APIPurge、监控、Workers 集成Cache Reserve 最佳实践与成本优化Cloudflare Deploy 技能总览含 Cache Reserve 产品索引【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考