perf(cache): 边缘缓存对齐 Cloudflare 默认模型

2026-10-06 23:56:37 +08:00 · 2026-07-23 23:39:15 +08:00
parent 5b1e27d0a3
commit f94767fbc7
14 changed files with 465 additions and 94 deletions
@@ -1,6 +1,6 @@
-# 边缘缓存策略设计（对标 Cloudflare 默认可缓存范围）
+# 边缘缓存策略设计

-你会学到：OpenFlare 边缘 `proxy_cache` 的产品边界、默认可缓存范围如何对齐 Cloudflare「静态资源默认可缓存」、策略枚举与渲染规则、兼容迁移，以及本阶段明确不做的能力。
+你会学到：OpenFlare 边缘 `proxy_cache` 如何在「该缓存」与「不该缓存」之间对齐 Cloudflare 默认闭环：请求 eligible（扩展名/策略）× 响应可共享缓存（源站 `Cache-Control` / `Expires` / `Set-Cookie`），以及与过往过严请求旁路的差异。

 本设计是 [系统架构](./architecture.md) 中「基础缓存」的产品化专章；访问日志中的缓存结果见 [观测数据模型 §3.5.1](./observability-data-model.md)。

@@ -8,35 +8,61 @@

 ## 1. 目标与非目标

-### 1.1 目标（第一期）
+### 1.1 目标

-* **开箱接近 CF 默认**：路由开启缓存后，**默认只缓存静态扩展名**，不默认缓存 HTML/无扩展名动态路径。
-* **行为可解释**：与现有安全旁路（非 GET、Authorization、会话 Cookie、请求 `Cache-Control`）叠加，不削弱安全。
+* **开箱接近 CF 默认**：路由开启缓存后，**默认只缓存静态扩展名**，不默认缓存 HTML；**不因请求会话 Cookie / Authorization / 客户端 Cache-Control 一律 BYPASS**。
+* **该缓存的能命中**：带登录 Cookie 的用户访问 `/_app/**/*.js` 等静态资源可出现 `MISS` → `HIT`。
+* **不该缓存的仍挡住**：策略不 eligible（等价 CF `DYNAMIC`）；源站 `private` / `no-store`；响应带 **`Set-Cookie` 不入库**（对齐 CF OCC 默认）；`all` 为高级选项并文档警示。
+* **无源站 freshness 时有默认 Edge TTL**：对齐 CF 按状态码的默认 TTL（见 §3.5）。
 * **可观测一致**：继续依赖 `$upstream_cache_status` → `cache_status` 明细三态。
-* **兼容存量**：旧路由 `cache_policy=url`（近似「过旁路即可缓存」）迁移为显式策略 `all`，行为不变。
+* **兼容存量**：旧路由 `cache_policy=url` 映射为 `all`；策略枚举与迁移规则保持 [§5](#5-兼容与迁移)。

 ### 1.2 非目标（后续迭代）

 * Cache Rules 表达式引擎  
-* Edge TTL / `proxy_cache_valid` / 忽略源站 `Cache-Control`  
-* 可配置 Cookie 旁路列表、Query 忽略列表  
+* 忽略源站 `Cache-Control` 的强制 Edge TTL（CF Cache Rules「Ignore cache-control」）  
 * Purge（按 URL/前缀/全站）  
 * 浏览器 TTL 改写、客户端 `CF-Cache-Status` 响应头  
+* 完整 RFC 条件：`Authorization` 仅当响应含 `public`/`s-maxage`/`must-revalidate` 才缓存（需 Lua；本期删除请求侧一律旁路，依赖策略 + 源站头）  
+* HEAD 转 GET 再缓存  
 * 命中率看板  

 ---

-## 2. 现状摘要
+## 2. Cloudflare 判定闭环（对齐基准）

-| 层 | 现状 |
+CF 默认是 **两段决策**，**不是**「请求带 Cookie 就不缓存」。
+
+### 2.1 阶段 A — 请求时 Eligible
+
+| 条件 | CF 结果 |
 | --- | --- |
-| 全局 | `proxy_cache_path` / key / lock / stale（Performance 部分字段） |
-| 路由 | `cache_enabled` + `cache_policy`：`url` \| `suffix` \| `path_prefix` \| `path_exact` |
-| 旁路 | 渲染器硬编码：非 GET、Authorization、会话 Cookie、请求 Cache-Control |
-| TTL | **无** `proxy_cache_valid`；存多久主要看源站头 + `inactive` |
-| 观测 | 已上报 `cache_status`，UI 三态：命中 / 回源 / 未缓存 |
+| 非 GET | 默认不缓存 |
+| 扩展名不在默认可缓存表，且无 Rules 强制 Eligible | **`DYNAMIC`**（不查缓存） |
+| 扩展名在默认表，或 Rules Eligible | 继续阶段 B |
+| **请求 Cookie** | **默认不影响** |
+| Cache Rules Bypass | `DYNAMIC` |

-问题：默认策略 `url` 对「过旁路的 GET」范围过宽，与 CF「默认主要缓存静态扩展名、默认不缓存 HTML」不一致。
+CF 默认可缓存扩展名按 **扩展名** 而非 MIME；**默认不缓存 HTML / JSON**。
+
+### 2.2 阶段 B — 响应是否可入库（OCC on，Free/Pro/Biz 默认）
+
+| 条件 | 结果 |
+| --- | --- |
+| `Cache-Control: no-store` / `private` | 不入库 |
+| `public` + `max-age>0`，或未来 `Expires` | 可缓存 |
+| 无 Cache-Control / Expires | 按状态码 **默认 Edge TTL** 仍可缓存（如 200 → 120m） |
+| 响应 **`Set-Cookie`**（默认缓存级别 + OCC） | **不入库**，状态倾向 **BYPASS** |
+| 请求 `Authorization` | 仅当响应另有 `public` / `s-maxage` / `must-revalidate` 才可缓存（完整条件本期用 Nginx 简化，见 §3.4） |
+
+### 2.3 状态语义（对照观测）
+
+| CF | 含义 | OpenFlare `cache_status` |
+| --- | --- | --- |
+| HIT / STALE / UPDATING / REVALIDATED | 命中类 | 同名或等价 |
+| MISS / EXPIRED | 回源取内容 | 同名 |
+| BYPASS | 请求时 eligible，响应不可缓存 | `BYPASS` → UI「未缓存」 |
+| DYNAMIC | 请求时不 eligible | 策略 skip 多为 `BYPASS` 或空 → UI「未缓存」 |

 ---

@@ -49,24 +75,24 @@

 两者均开启时才进入缓存逻辑。

-### 3.2 策略枚举（第一期）
+### 3.2 策略枚举

 | `cache_policy` | 含义 | 新建默认 | 旧值兼容 |
 | --- | --- | --- | --- |
-| **`static`** | 仅 URI 匹配**标准静态扩展名**（内置表）才允许缓存 | **是** | — |
-| **`all`** | 过安全旁路后，不限制路径/扩展名（等同今日 `url`） | 否 | 存量 `url` → `all` |
+| **`static`** | 仅 URI 匹配**标准静态扩展名**才 eligible | **是** | — |
+| **`all`** | 过方法旁路后，不限制路径/扩展名（高级，风险类似 CF Cache Everything） | 否 | 存量 `url` → `all` |
 | **`suffix`** | 自定义扩展名列表（`cache_rules`） | 否 | 保持 |
 | **`path_prefix`** | 自定义路径前缀 | 否 | 保持 |
 | **`path_exact`** | 自定义精确路径 | 否 | 保持 |

-> 渲染层：读到历史值 `url` 时按 `all` 处理，避免未迁移数据行为突变；API 校验与 UI 只暴露上表枚举（写入时可将 `url` 规范为 `all`）。
+渲染层：历史值 `url` 按 `all` 处理；API/UI 只暴露上表枚举。

-### 3.3 标准静态扩展名（内置，V1 硬编码）
+### 3.3 标准静态扩展名（内置）

-对齐 Cloudflare 常见「默认可缓存静态」集合，**默认不包含** `html` / `htm`：
+对齐 CF 默认「不缓存 HTML/JSON」；保留现代前端常用增强项：

 ```text
-css js mjs map json
+css js mjs map
 ico cur gif jpg jpeg png webp avif svg svgz
 ttf otf woff woff2 eot
 mp3 mp4 webm ogg flac
@@ -74,26 +100,68 @@ wasm pdf
 zip 7z gz tar
 ```

-* 匹配对象：`$uri` 的扩展名（大小写不敏感），实现上与现有 `suffix` 策略相同：  
-  `if ($uri !~* \.(?:css|js|…)$) { set $openflare_skip_cache 1; }`  
-* **V1.1（可选）**：全局配置项覆盖该列表；第一期不强制。
+* **不含** `html` / `htm` / **`json`**（对齐 CF 默认不缓存 JSON）。  
+* **含** `map` / `mjs` / `wasm`（有意增强，提高 sourcemap / ES module / WASM 命中）。  
+* 匹配：`$uri` 扩展名，大小写不敏感：  
+  `if ($uri !~* \.(?:css|js|…)$) { set $openflare_skip_cache 1; }`

-### 3.4 安全旁路（保持硬编码）
+### 3.4 请求侧旁路（对齐 CF 后）

-在策略匹配之前/之外，仍设置 `$openflare_skip_cache=1`：
+仅保留：

-1. `$request_method != GET`（含 HEAD，与现网一致）  
-2. `$http_authorization != ""`  
-3. 会话类 Cookie 正则（现网列表）  
-4. 请求 `$http_cache_control` 匹配 `no-cache|no-store|private`  
+1. `$request_method != GET`（含 HEAD，与现网一致；不做 CF 的 HEAD→GET）

-`proxy_cache_bypass` / `proxy_no_cache` 均绑定 `$openflare_skip_cache`。
+**删除（过往过严，导致缓存率过低）：**

-### 3.5 与源站头的关系（本阶段不改）
+* 会话类 Cookie 正则  
+* `$http_authorization != ""`  
+* 请求 `$http_cache_control` 匹配 `no-cache|no-store|private`

-* 仍不输出 `proxy_cache_valid`。  
-* 对象**是否进入缓存流程**由策略 + 旁路决定；**存多久**继续依赖源站 `Cache-Control` / `Expires` 等及全局 `inactive`。  
-* Edge TTL / 强制忽略源站头 → 后续专项。
+**安全如何仍成立：**
+
+| 威胁 | 闸门 |
+| --- | --- |
+| 误缓存 HTML/API | 默认 `static` 扩展名（不含 html/json） |
+| 个性化内容 | 源站 `private` / `no-store`（Nginx 尊重） |
+| 响应写会话 | **`Set-Cookie` → 不入库**（§3.6） |
+| `all` 过宽 | UI/文档警告：需源站正确 Cache-Control |
+| 带 Bearer 的 API | 依赖策略（勿对 API 用 `all`）+ 源站头；完整 Auth 条件缓存为后续 |
+
+### 3.5 默认 Edge TTL（无源站 freshness 时）
+
+对齐 CF 无 `Cache-Control`/`Expires` 时的状态码默认 TTL，在启用缓存的 location 输出：
+
+| 状态码 | TTL |
+| --- | --- |
+| 200, 206, 301 | 120m |
+| 302, 303 | 20m |
+| 404, 410 | 3m |
+
+```nginx
+proxy_cache_valid 200 206 301 120m;
+proxy_cache_valid 302 303 20m;
+proxy_cache_valid 404 410 3m;
+```
+
+* 源站提供合法 `Cache-Control` / `Expires` 时，仍以源站 freshness 为准（不 `proxy_ignore_headers`）。  
+* **不做**强制忽略源站头的 Edge TTL 覆盖。
+
+### 3.6 响应侧：Set-Cookie 不入库
+
+对齐 CF OCC 默认：eligible 请求若源站返回 **`Set-Cookie`**，**不写入** `proxy_cache`（可读路径仍可能 MISS/BYPASS 语义）。
+
+```nginx
+proxy_no_cache $openflare_skip_cache $upstream_http_set_cookie;
+```
+
+（`proxy_no_cache` 多参数：任一非空且非 `"0"` 则不写入。）
+
+`proxy_cache_bypass` 仍仅绑定 `$openflare_skip_cache`（请求侧 skip）；响应侧只影响**写入**，与 CF「eligible 但响应不可缓存」一致。
+
+### 3.7 与源站头的关系
+
+* **是否 eligible**：策略 + 方法旁路。  
+* **是否入库 / 存多久**：源站 `Cache-Control` / `Expires` + 默认 `proxy_cache_valid` + Set-Cookie 闸门 + 全局 `inactive`。  

 ---

@@ -107,11 +175,13 @@ zip 7z gz tar
    │ no → location 无 proxy_cache
    ▼ yes
 set $openflare_skip_cache 0
-    → 安全旁路 if → 置 1
+    → 非 GET → 置 1
    → 策略 if（static/all/suffix/…）→ 可置 1
 proxy_cache openflare_cache
 proxy_cache_methods GET
-proxy_cache_bypass / proxy_no_cache $openflare_skip_cache
+proxy_cache_bypass $openflare_skip_cache
+proxy_no_cache $openflare_skip_cache $upstream_http_set_cookie
+proxy_cache_valid …
    →
 access.log cache_status=$upstream_cache_status
 ```
@@ -125,16 +195,16 @@ access.log cache_status=$upstream_cache_status
 | `suffix` | 不匹配 `cache_rules` 扩展名 → skip |
 | `path_prefix` / `path_exact` | 同现实现 |

-### 4.2 涉及代码面（实现时）
+### 4.2 涉及代码面

 | 区域 | 路径 |
 | --- | --- |
-| 渲染 | `pkg/render/openresty/render.go`（策略分支 + 内置扩展名常量） |
+| 渲染 | `pkg/render/openresty/render.go`（旁路、Set-Cookie、`proxy_cache_valid`、扩展名常量） |
 | 校验 | `internal/apps/openflare/proxy_route/helpers.go` |
 | 模型/默认 | 创建路由默认 `cache_policy=static`；读写时 `url`→`all` |
-| 快照 | `config_version/snapshot.go` |
+| 快照 | `config_version` 快照规范化 |
 | UI | `proxy-routes/detail/components/cache-section.tsx` |
-| 测试 | `pkg/render/openresty/render_test.go`、proxy_route helpers 测试 |
+| 测试 | `pkg/render/openresty/render_test.go` 等 |

 ---

@@ -142,49 +212,79 @@ access.log cache_status=$upstream_cache_status

 | 数据 | 处理 |
 | --- | --- |
-| DB 中 `cache_policy=''` 或 `url`（且已启用缓存） | 读取 / 快照 / 渲染均规范为 **`all`**，保证存量「宽缓存」不变 |
-| API 写入时 `enabled` 且 policy 为空 | 规范为 **`all`**（兼容旧客户端）；UI 新建开启时**显式提交** `static` |
-| 新建路由 | 默认 `cache_enabled=false`；表单开启缓存时默认策略 **`static`** |
-| 已开启且 `url` 的站点 | 显示与发布为 `all`，**缓存范围不变** |
-| 期望「只缓存静态」的旧站点 | 用户在 UI 改为 `static` 或自定义 `suffix` |
+| DB 中 `cache_policy=''` 或 `url`（且已启用缓存） | 读 / 快照 / 渲染 → **`all`** |
+| API 写入 enabled 且 policy 为空 | 规范为 **`all`**；UI 新建开启时**显式提交** `static` |
+| 新建路由 | 开启缓存时默认 **`static`** |
+| 旁路行为变更 | **破坏性相对旧实现**：带 Cookie/Auth 的流量从「未缓存」变为可 HIT；需 **重新发布节点配置** 后生效 |
+| 默认扩展名 | 自表中 **移除 `json`**；已依赖缓存 `*.json` 的站点可改 `suffix` 自定义或 `all` |

-**发布说明建议：** 说明默认策略变更仅影响**新配置**；存量 `url` 视为 `all`。
+**发布说明：** 说明本次对齐 CF 默认模型；命中率预期上升；`all` 与错误源站头风险需运维自查。

 ---

 ## 6. UI 文案要点（缓存 Tab）

-* 开启缓存后默认：**标准静态资源**（列出扩展名摘要，并写明不含 HTML）。  
-* 选项：**标准静态资源** / **所有可缓存 GET（高级）** / 自定义后缀 / 路径前缀 / 精确路径。  
-* 固定说明：非 GET、带 Authorization、常见登录 Cookie、请求禁止缓存头时跳过缓存。  
-* 提示：全局 Performance 中缓存总开关须开启，否则站点开关无效。
+* 开启缓存后默认：**标准静态资源**（摘要扩展名，**不含 HTML/JSON**；含 map/mjs 等）。  
+* 选项：标准静态 / 所有可缓存 GET（高级）/ 自定义后缀 / 路径前缀 / 精确路径。  
+* 说明对齐 CF：  
+  * 登录 Cookie **不会**单独跳过缓存；  
+  * 源站 `private` / `no-store` / 响应 **`Set-Cookie`** 不会写入边缘缓存；  
+  * 无源站缓存头时使用默认 Edge TTL。  
+* **高级 `all`**：警告「类似 Cache Everything，个性化页面必须由源站声明 private/no-store」。  
+* 全局 Performance 缓存总开关须开启。

 ---

 ## 7. 验证要点

-* 渲染：`static` 生成扩展名 `if`；`all`/`url` 无路径限制；旁路四条仍在。  
-* 单测：内置表含 `css`/`js`/`woff2`，不含 `html`。  
-* 手动：开启 `static` 后请求 `/a.css` 可出现 HIT/MISS；`/index.html` 或 `/api` 多为未缓存/BYPASS。  
-* 观测：access log `cache_status` 与列表三态一致。
+* 渲染：无 Cookie/Auth/请求 Cache-Control 旁路；含 `proxy_cache_valid` 三行；`proxy_no_cache` 含 `$upstream_http_set_cookie`。  
+* 单测：内置表含 `css`/`js`/`map`/`mjs`，**不含** `html`/`json`。  
+* 手动：  
+  * 带 session Cookie 请求 `/a.js` → 第二次 `HIT`；  
+  * `/index.html` + `static` → 未缓存；  
+  * 源站对 eligible 路径返回 `Set-Cookie` → 不入库（持续 MISS/不 HIT）；  
+  * 源站 `Cache-Control: private` → 不入库。  
+* 观测：access log 三态与原始 `cache_status` 一致。  
+* 生效：配置版本发布并节点应用后验证。

 ---

-## 8. 后续路线图（非本设计交付）
+## 8. 决策矩阵（防漏判）

-1. **Edge TTL / 尊重源站开关**（`proxy_cache_valid`、`proxy_ignore_headers`）  
-2. **可配置旁路**（Cookie/Query）  
-3. **Purge API**  
-4. **Cache Rules**（有序规则 + 动作）  
-5. **全局默认可缓存扩展名配置**  
+| 场景 | CF | OpenFlare（本设计） |
+| --- | --- | --- |
+| GET 静态 + session Cookie + 源站 public max-age | HIT | HIT |
+| GET HTML + static 策略 | DYNAMIC | 策略 skip → 未缓存 |
+| GET + all + 源站 private | 不入库 | 不入库 |
+| GET 静态 + 响应 Set-Cookie | BYPASS（OCC） | 不入库 |
+| GET + Authorization + 静态 public | 条件缓存 | 可缓存（简化；依赖源站勿对敏感 API 乱标 public） |
+| GET + 无 CC 的 200 静态 | 默认 120m | `proxy_cache_valid` 120m |
+| DevTools Disable cache（请求 no-cache） | 边缘默认可仍 HIT | 边缘默认可仍 HIT |
+| POST | 不缓存 | 非 GET skip |

 ---

-## 9. 决策记录
+## 9. 后续路线图
+
+1. Auth 完整 RFC/CF 条件缓存（Lua）  
+2. 强制 Edge TTL / `proxy_ignore_headers`（Cache Rules 级）  
+3. Purge API  
+4. Cache Rules（有序规则 + 动作）  
+5. 全局默认可缓存扩展名可配置；可选对齐 CF 更长扩展名表  
+6. HEAD→GET  
+
+---
+
+## 10. 决策记录

 | 决策 | 选择 | 原因 |
 | --- | --- | --- |
-| 默认可缓存范围 | 开启缓存默认 `static` 扩展名表 | 对标 CF 开箱行为，降低 HTML/API 被误缓存 |
-| 旧 `url` | 映射为 `all` | 避免存量站点行为变化 |
-| HTML | 默认不在白名单 | 对齐 CF 默认不缓存 HTML |
-| 第一期不做 Edge TTL/Purge | 明确 Out of Scope | 先收敛「谁可以进缓存」再优化「存多久/怎么清」 |
+| 请求 Cookie 旁路 | **删除** | 对齐 CF；恢复登录用户静态命中率 |
+| 请求 Authorization / Cache-Control 旁路 | **删除** | 对齐 CF 请求 eligible 模型；响应闸门兜底 |
+| Set-Cookie | **proxy_no_cache 绑定** | 对齐 CF OCC「响应 Set-Cookie 不入库」 |
+| 默认 Edge TTL | **按状态码 proxy_cache_valid** | 对齐 CF 无头时默认 TTL，避免「永不入库」 |
+| 默认表去掉 json | **是** | 对齐 CF 默认不缓存 JSON |
+| 保留 map/mjs/wasm | **是** | 现代前端有用命中，有意增强 |
+| 默认可缓存范围 | 开启缓存默认 `static` | 对标 CF，降低 HTML/API 误缓存 |
+| 旧 `url` | 映射 `all` | 存量行为不收窄 |
+| 完整 Auth 条件 / Purge / Rules | 后续 | 先闭合默认闭环再扩展 |
@@ -22,7 +22,7 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
 | 能力 | 说明 | 详细设计/使用指南 |
 | --- | --- | --- |
 | **反代配置管理** | 以网站规则（Proxy Route）为聚合边界，支持多域名与多上游负载均衡 | [新建反代配置](../guide/proxy-config.md) |
-| **边缘缓存** | 单节点 OpenResty `proxy_cache`；开启后默认仅缓存标准静态扩展名（对标 CF 默认可缓存范围） | [边缘缓存策略设计](./edge-cache-design.md) |
+| **边缘缓存** | 单节点 OpenResty `proxy_cache`；默认 static 扩展名 + 源站头/Set-Cookie 闸门 + 默认 Edge TTL（对标 CF 默认模型） | [边缘缓存策略设计](./edge-cache-design.md) |
 | **Zone 与域名管理** | 以可注册根域为管理入口，聚合明确域名、域名证书与反代路由 | [Zone 与域名资源设计](./zone-design.md) |
 | **配置版本控制** | 支持全局单一激活版本的预览、发布、不可变快照历史与秒级一键回滚 | [Agent 与发布模型](./agent-design.md) |
 | **WAF 安全防护** | 支持可视化 DAG 编排规则、手动/自动/订阅型 IP 组、GeoIP 匹配与 PoW CC 防护 | [WAF 设计](./waf-design.md) / [WAF 可编排规则设计](./waf-orchestration-design.md) / [WAF 使用指南](../guide/waf-usage.md) |