OpenFlare/docs/plan/20260723-edge-cache-cf-align.md

边缘缓存对齐 Cloudflare 默认模型 — 实现计划

对应设计：edge-cache-design.md

1. 目标与背景

• 需求背景：现网对会话 Cookie / Authorization / 请求 Cache-Control 一律旁路，登录用户静态资源几乎全是「未缓存」，命中率远低于 Cloudflare 默认。需对齐 CF 两段闭环：请求 eligible × 响应可共享缓存。
• Scope（必做）
  1. 删除请求侧 Cookie、Authorization、请求 Cache-Control 旁路
  2. 响应侧：proxy_no_cache 绑定 $upstream_http_set_cookie
  3. 默认 proxy_cache_valid（200/206/301→120m，302/303→20m，404/410→3m）
  4. 默认静态扩展名移除 json；保留 map/mjs/wasm
  5. 渲染单测 + UI 文案 + 设计/changelog
• Out of Scope：Purge、Cache Rules、强制忽略源站 CC、Auth RFC 条件缓存、HEAD→GET

2. 设计决策摘要

决策	选择
请求 Cookie	不旁路（对齐 CF）
Set-Cookie	不入库
无源站 CC	状态码默认 Edge TTL
json	默认表移除
兼容	url→all 不变；行为变更需重新发布配置

3. 修改清单

边缘渲染

• [MODIFY] pkg/render/openresty/render.go

  • renderRouteCacheBlock：仅保留非 GET 旁路；proxy_no_cache $openflare_skip_cache $upstream_http_set_cookie；追加三行 proxy_cache_valid

• [MODIFY] pkg/render/openresty/types.go

  • DefaultStaticCacheExtensions：去掉 json

• [MODIFY] pkg/render/openresty/render_test.go

  • 断言：无 cookie/auth/cache_control 旁路；含 set_cookie 与 proxy_cache_valid；表不含 json、含 map

前端

• [MODIFY] frontend/app/(main)/proxy-routes/detail/components/cache-section.tsx

  • 去掉「绕过登录 Cookie / Authorization」类文案
  • 改为 CF 对齐说明：源站 private/no-store、Set-Cookie 不入库、默认静态不含 HTML/JSON

文档

• [MODIFY] docs/design/edge-cache-design.md（已更新）

• [MODIFY] docs/changelog/index.md [Unreleased]

• [MODIFY] docs/plan/index.md 登记本计划

不改

• 无 DB 迁移
• 无 API 字段变更（策略枚举不变）

4. 验证计划

自动化

go test ./pkg/render/openresty/
make format
make code-check

数据面（配置发布后）

1. 站点 cache_enabled + static，全局缓存开
2. 带 session Cookie：GET /static/app.js 第二次应 HIT
3. GET /index.html 应为未缓存
4. 源站返回 Set-Cookie 的静态 URL 不应出现稳定 HIT
5. 访问日志 cache_status 与三态一致

5. 发布注意

• 节点需 重新发布/拉取配置版本 后旁路变更才生效
• 若站点依赖边缘缓存 *.json，改为 suffix 含 json 或 all

6. 状态

• 设计定稿（用户确认：全量对齐 CF）
• 渲染与单测
• UI 文案
• changelog / plan index
• make format + make code-check
• 复查补强：all 策略 UI 警告；proxy-config / troubleshooting 运维说明
• 用户确认后提交