mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 05:56:38 +08:00
docs(design): 边缘缓存默认可缓存范围对标 Cloudflare
约定开启缓存默认 static 扩展名策略，存量 url 映射为 all， 并明确第一期不做 Edge TTL/Purge/Cache Rules。
This commit is contained in:
ryan
@@ -132,6 +132,7 @@ function sidebarDesign(): DefaultTheme.SidebarItem[] {
|
||||
{ text: 'WAF 设计', link: 'waf-design' },
|
||||
{ text: 'WAF 可编排规则设计', link: 'waf-orchestration-design' },
|
||||
{ text: 'Pages 静态托管设计', link: 'pages-design' },
|
||||
{ text: '边缘缓存策略设计', link: 'edge-cache-design' },
|
||||
{ text: '边缘可观测与业务流量统计', link: 'observability-design' },
|
||||
{ text: '观测数据传输模型', link: 'observability-transport-model' },
|
||||
{ text: '观测上报协议与表结构', link: 'observability-data-model' },
|
||||
|
||||
@@ -95,7 +95,7 @@ OpenResty (Agent, TLS/WAF)
|
||||
### 3. OpenResty (数据面)
|
||||
接收访客流量并执行最终的业务落地：
|
||||
* 流量入口，支持 HTTP/2、HTTP/3（QUIC）和 TLS 证书动态绑定。
|
||||
* 嵌入 Lua 逻辑，在 `access_by_lua` 阶段高效过滤 WAF 规则、验证工作量证明 (PoW) 挑战，并在此之后执行连接数/速率限制及基础缓存。
|
||||
* 嵌入 Lua 逻辑，在 `access_by_lua` 阶段高效过滤 WAF 规则、验证工作量证明 (PoW) 挑战，并在此之后执行连接数/速率限制及基础缓存（策略见 [边缘缓存策略设计](./edge-cache-design.md)）。
|
||||
* *详细设计请参阅：[WAF 设计文档](./waf-design.md) 与 [Pages 静态托管设计文档](./pages-design.md)*
|
||||
|
||||
### 4. Relay 与 OpenFlared (穿透组件)
|
||||
|
||||
@@ -0,0 +1,189 @@
|
||||
# 边缘缓存策略设计（对标 Cloudflare 默认可缓存范围）
|
||||
|
||||
你会学到：OpenFlare 边缘 `proxy_cache` 的产品边界、默认可缓存范围如何对齐 Cloudflare「静态资源默认可缓存」、策略枚举与渲染规则、兼容迁移，以及本阶段明确不做的能力。
|
||||
|
||||
本设计是 [系统架构](./architecture.md) 中「基础缓存」的产品化专章；访问日志中的缓存结果见 [观测数据模型 §3.5.1](./observability-data-model.md)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标（第一期）
|
||||
|
||||
* **开箱接近 CF 默认**：路由开启缓存后，**默认只缓存静态扩展名**，不默认缓存 HTML/无扩展名动态路径。
|
||||
* **行为可解释**：与现有安全旁路（非 GET、Authorization、会话 Cookie、请求 `Cache-Control`）叠加，不削弱安全。
|
||||
* **可观测一致**：继续依赖 `$upstream_cache_status` → `cache_status` 明细三态。
|
||||
* **兼容存量**：旧路由 `cache_policy=url`（近似「过旁路即可缓存」）迁移为显式策略 `all`，行为不变。
|
||||
|
||||
### 1.2 非目标（后续迭代）
|
||||
|
||||
* Cache Rules 表达式引擎
|
||||
* Edge TTL / `proxy_cache_valid` / 忽略源站 `Cache-Control`
|
||||
* 可配置 Cookie 旁路列表、Query 忽略列表
|
||||
* Purge（按 URL/前缀/全站）
|
||||
* 浏览器 TTL 改写、客户端 `CF-Cache-Status` 响应头
|
||||
* 命中率看板
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状摘要
|
||||
|
||||
| 层 | 现状 |
|
||||
| --- | --- |
|
||||
| 全局 | `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 三态：命中 / 回源 / 未缓存 |
|
||||
|
||||
问题：默认策略 `url` 对「过旁路的 GET」范围过宽，与 CF「默认主要缓存静态扩展名、默认不缓存 HTML」不一致。
|
||||
|
||||
---
|
||||
|
||||
## 3. 产品语义
|
||||
|
||||
### 3.1 双层开关（不变）
|
||||
|
||||
* **全局** `openresty_cache_enabled`：生成 `proxy_cache_path` 等；关闭则路由级缓存指令不生效。
|
||||
* **路由** `cache_enabled`：是否在该站点 `location` 启用 `proxy_cache`。
|
||||
|
||||
两者均开启时才进入缓存逻辑。
|
||||
|
||||
### 3.2 策略枚举（第一期）
|
||||
|
||||
| `cache_policy` | 含义 | 新建默认 | 旧值兼容 |
|
||||
| --- | --- | --- | --- |
|
||||
| **`static`** | 仅 URI 匹配**标准静态扩展名**（内置表）才允许缓存 | **是** | — |
|
||||
| **`all`** | 过安全旁路后，不限制路径/扩展名（等同今日 `url`） | 否 | 存量 `url` → `all` |
|
||||
| **`suffix`** | 自定义扩展名列表（`cache_rules`） | 否 | 保持 |
|
||||
| **`path_prefix`** | 自定义路径前缀 | 否 | 保持 |
|
||||
| **`path_exact`** | 自定义精确路径 | 否 | 保持 |
|
||||
|
||||
> 渲染层：读到历史值 `url` 时按 `all` 处理，避免未迁移数据行为突变；API 校验与 UI 只暴露上表枚举（写入时可将 `url` 规范为 `all`）。
|
||||
|
||||
### 3.3 标准静态扩展名（内置，V1 硬编码）
|
||||
|
||||
对齐 Cloudflare 常见「默认可缓存静态」集合，**默认不包含** `html` / `htm`：
|
||||
|
||||
```text
|
||||
css js mjs map json
|
||||
ico cur gif jpg jpeg png webp avif svg svgz
|
||||
ttf otf woff woff2 eot
|
||||
mp3 mp4 webm ogg flac
|
||||
wasm pdf
|
||||
zip 7z gz tar
|
||||
```
|
||||
|
||||
* 匹配对象：`$uri` 的扩展名（大小写不敏感），实现上与现有 `suffix` 策略相同：
|
||||
`if ($uri !~* \.(?:css|js|…)$) { set $openflare_skip_cache 1; }`
|
||||
* **V1.1（可选）**：全局配置项覆盖该列表；第一期不强制。
|
||||
|
||||
### 3.4 安全旁路（保持硬编码）
|
||||
|
||||
在策略匹配之前/之外，仍设置 `$openflare_skip_cache=1`：
|
||||
|
||||
1. `$request_method != GET`（含 HEAD，与现网一致）
|
||||
2. `$http_authorization != ""`
|
||||
3. 会话类 Cookie 正则（现网列表）
|
||||
4. 请求 `$http_cache_control` 匹配 `no-cache|no-store|private`
|
||||
|
||||
`proxy_cache_bypass` / `proxy_no_cache` 均绑定 `$openflare_skip_cache`。
|
||||
|
||||
### 3.5 与源站头的关系（本阶段不改）
|
||||
|
||||
* 仍不输出 `proxy_cache_valid`。
|
||||
* 对象**是否进入缓存流程**由策略 + 旁路决定；**存多久**继续依赖源站 `Cache-Control` / `Expires` 等及全局 `inactive`。
|
||||
* Edge TTL / 强制忽略源站头 → 后续专项。
|
||||
|
||||
---
|
||||
|
||||
## 4. 渲染与数据流
|
||||
|
||||
```text
|
||||
全局 cache_enabled?
|
||||
│ no → 不生成 proxy_cache_*
|
||||
▼ yes
|
||||
路由 cache_enabled?
|
||||
│ no → location 无 proxy_cache
|
||||
▼ yes
|
||||
set $openflare_skip_cache 0
|
||||
→ 安全旁路 if → 置 1
|
||||
→ 策略 if（static/all/suffix/…）→ 可置 1
|
||||
proxy_cache openflare_cache
|
||||
proxy_cache_methods GET
|
||||
proxy_cache_bypass / proxy_no_cache $openflare_skip_cache
|
||||
→
|
||||
access.log cache_status=$upstream_cache_status
|
||||
```
|
||||
|
||||
### 4.1 策略 → Nginx 条件
|
||||
|
||||
| 策略 | 额外条件 |
|
||||
| --- | --- |
|
||||
| `static` | `$uri` 不匹配内置扩展名表 → skip |
|
||||
| `all` | 无额外路径条件 |
|
||||
| `suffix` | 不匹配 `cache_rules` 扩展名 → skip |
|
||||
| `path_prefix` / `path_exact` | 同现实现 |
|
||||
|
||||
### 4.2 涉及代码面（实现时）
|
||||
|
||||
| 区域 | 路径 |
|
||||
| --- | --- |
|
||||
| 渲染 | `pkg/render/openresty/render.go`（策略分支 + 内置扩展名常量） |
|
||||
| 校验 | `internal/apps/openflare/proxy_route/helpers.go` |
|
||||
| 模型/默认 | 创建路由默认 `cache_policy=static`；读写时 `url`→`all` |
|
||||
| 快照 | `config_version/snapshot.go` |
|
||||
| UI | `proxy-routes/detail/components/cache-section.tsx` |
|
||||
| 测试 | `pkg/render/openresty/render_test.go`、proxy_route helpers 测试 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 兼容与迁移
|
||||
|
||||
| 数据 | 处理 |
|
||||
| --- | --- |
|
||||
| DB 中 `cache_policy=''` 或 `url` | 读取/发布时规范为 `all`；可选一次性 SQL 更新为 `all` |
|
||||
| 新建路由 | 默认 `cache_enabled=false`；若用户开启缓存，表单默认策略 **`static`** |
|
||||
| 已开启且 `url` 的站点 | 迁移后为 `all`，**缓存范围不变** |
|
||||
| 期望「只缓存静态」的旧站点 | 用户在 UI 改为 `static` 或自定义 `suffix` |
|
||||
|
||||
**发布说明建议：** 说明默认策略变更仅影响**新配置**；存量 `url` 视为 `all`。
|
||||
|
||||
---
|
||||
|
||||
## 6. UI 文案要点（缓存 Tab）
|
||||
|
||||
* 开启缓存后默认：**标准静态资源**（列出扩展名摘要，并写明不含 HTML）。
|
||||
* 选项：**标准静态资源** / **所有可缓存 GET（高级）** / 自定义后缀 / 路径前缀 / 精确路径。
|
||||
* 固定说明：非 GET、带 Authorization、常见登录 Cookie、请求禁止缓存头时跳过缓存。
|
||||
* 提示：全局 Performance 中缓存总开关须开启，否则站点开关无效。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证要点
|
||||
|
||||
* 渲染：`static` 生成扩展名 `if`；`all`/`url` 无路径限制；旁路四条仍在。
|
||||
* 单测：内置表含 `css`/`js`/`woff2`，不含 `html`。
|
||||
* 手动：开启 `static` 后请求 `/a.css` 可出现 HIT/MISS；`/index.html` 或 `/api` 多为未缓存/BYPASS。
|
||||
* 观测：access log `cache_status` 与列表三态一致。
|
||||
|
||||
---
|
||||
|
||||
## 8. 后续路线图（非本设计交付）
|
||||
|
||||
1. **Edge TTL / 尊重源站开关**（`proxy_cache_valid`、`proxy_ignore_headers`）
|
||||
2. **可配置旁路**（Cookie/Query）
|
||||
3. **Purge API**
|
||||
4. **Cache Rules**（有序规则 + 动作）
|
||||
5. **全局默认可缓存扩展名配置**
|
||||
|
||||
---
|
||||
|
||||
## 9. 决策记录
|
||||
|
||||
| 决策 | 选择 | 原因 |
|
||||
| --- | --- | --- |
|
||||
| 默认可缓存范围 | 开启缓存默认 `static` 扩展名表 | 对标 CF 开箱行为，降低 HTML/API 被误缓存 |
|
||||
| 旧 `url` | 映射为 `all` | 避免存量站点行为变化 |
|
||||
| HTML | 默认不在白名单 | 对齐 CF 默认不缓存 HTML |
|
||||
| 第一期不做 Edge TTL/Purge | 明确 Out of Scope | 先收敛「谁可以进缓存」再优化「存多久/怎么清」 |
|
||||
@@ -22,6 +22,7 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
|
||||
| 能力 | 说明 | 详细设计/使用指南 |
|
||||
| --- | --- | --- |
|
||||
| **反代配置管理** | 以网站规则（Proxy Route）为聚合边界，支持多域名与多上游负载均衡 | [新建反代配置](../guide/proxy-config.md) |
|
||||
| **边缘缓存** | 单节点 OpenResty `proxy_cache`；开启后默认仅缓存标准静态扩展名（对标 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) |
|
||||
|
||||
Reference in New Issue
Block a user