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

docs/guide/index.md

@@ -10,7 +10,7 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
 
 1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，登录管理端，并接入第一个 Agent。
 2. [发布第一份配置](./first-site.md)：快速新建一条最基础的 HTTP 反代站点规则，并验证节点生效状态。
-3. [新建反代配置](./proxy-config.md)：一步一步了解如何从证书导入与申请开始，配置 HTTPS 加密与上游源站管理。
+3. [新建反代配置](./proxy-config.md)：一步一步了解如何从证书导入与申请开始，配置 HTTPS 加密、上游源站与边缘缓存。
 4. [Zone 域名迁移](./zone-domain-migration.md)：从旧托管域名/路由内嵌域名升级到 Zone 模型（goose 自动导入），含备份、验收与回滚说明。
 5. [Pages 静态托管使用](./pages-usage.md)：了解静态项目 ZIP 上传限制、SPA Fallback、以及内置 API 反向代理配置。
 6. [内网穿透与隧道使用](./tunnel-usage.md)：部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。
@@ -18,7 +18,7 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
 8. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
 9. [Uptime Kuma 监控同步](./uptime-kuma.md)：配置并使用 Uptime Kuma 自动差分同步和监控范围控制。
 10. [SSO 登录配置](./sso.md)：配置 GitHub 或 OIDC 实现第三方单点登录 (SSO) 接入。
-11. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
+11. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty、边缘缓存命中与前端构建问题。
 12. [引用与致谢](./credits.md)：查看系统依赖的优秀开源项目与社区致谢清单。
 
 ## 按角色查找
@@ -27,7 +27,8 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
 | --- | --- |
 | 5 分钟内跑起管理端 | [快速开始](./quick-start.md) |
 | 发布第一条反向代理配置 | [发布第一份配置](./first-site.md) |
-| 配置域名证书与高级反代 | [新建反代配置](./proxy-config.md) |
+| 配置域名证书、反代与边缘缓存 | [新建反代配置](./proxy-config.md)（含缓存说明） |
+| 静态资源不命中缓存 | [故障排查 · 边缘缓存](./troubleshooting.md#边缘缓存命中率异常) |
 | 托管单页应用或静态网站 | [Pages 静态托管使用](./pages-usage.md) |
 | 配置内网穿透映射 | [内网穿透与隧道使用](./tunnel-usage.md) |
 | 配置防 CC 与 IP 组拦截 | [WAF 安全防护使用](./waf-usage.md) |

docs/guide/proxy-config.md

@@ -84,3 +84,34 @@
 2. 在历史列表中找到发布前的上一个稳定版本。
 3. 点击 **「激活此版本」**。
 4. 所有在线 Agent 节点将在秒级自动重载回历史配置，实现秒级避险。
+
+---
+
+## 边缘缓存（可选）
+
+站点详情 **「缓存」** 页可开启边缘 `proxy_cache`（须同时开启 **性能设置 → 全局 OpenResty 缓存**）。行为对标 Cloudflare 默认模型，详见 [边缘缓存策略设计](../design/edge-cache-design.md)。
+
+### 推荐设置
+
+| 项 | 建议 |
+| --- | --- |
+| 策略 | **标准静态资源**（默认推荐）：仅 css/js/map/图片/字体等，**不含 HTML/JSON** |
+| 登录 Cookie | **不会**单独跳过缓存；带会话的用户仍可命中静态资源 |
+| 源站 | 静态资源建议 `Cache-Control: public, max-age=…`；动态/个性化必须 `private` 或 `no-store` |
+| 响应 Set-Cookie | 不会写入边缘缓存 |
+| 无源站缓存头 | 按状态码使用默认 Edge TTL（如 200 约 120 分钟） |
+
+### 高级策略「所有可缓存 GET」
+
+类似 Cloudflare Cache Everything：路径不再限制扩展名。若源站对 HTML 未声明 `private`/`no-store`，**可能把个性化页面缓存并串用户**。仅在源站缓存头正确、或内容全局一致时使用。
+
+### 生效方式
+
+缓存开关与策略写在配置快照中。保存站点后须 **发布并激活配置版本**，Agent 应用后才生效。仅改 UI 不发布则节点仍用旧规则。
+
+### 快速自检
+
+1. 全局缓存已开，站点缓存已开，策略为「标准静态资源」。  
+2. 发布配置并确认节点应用成功。  
+3. 带登录 Cookie 连续两次请求同一 `/assets/app.js`（或带 hash 的 immutable 路径），访问日志中 `cache_status` 第二次应为 **HIT**（或 UI「命中」）。  
+4. 若仍为「未缓存」：确认策略是否匹配该路径扩展名、是否非 GET、源站是否返回 `Set-Cookie` / `private`，以及节点是否已应用新版本。更多见 [故障排查 · 边缘缓存](./troubleshooting.md#边缘缓存命中率异常)。

docs/guide/troubleshooting.md

@@ -15,6 +15,7 @@
 | 发布后节点未更新 | 激活版本、节点 heartbeat、应用记录 |
 | OpenResty 应用失败 | 应用记录、Agent 日志、证书、上游地址、端口占用 |
 | 访问分析无数据 | OpenResty 容器状态、观测端口、Agent 补报日志 |
+| 静态资源总不命中缓存 | 全局/站点缓存开关、策略扩展名、配置是否已发布、访问日志 `cache_status`、源站 Set-Cookie / Cache-Control |
 
 ## Server 无法启动
 
@@ -238,6 +239,36 @@ pnpm build
 | API 类型不一致 | 检查 `lib/api/` 和 `types/` 中的响应结构 |
 | E2E 失败 | 确认 Server 和前端开发服务器都已启动 |
 
+## 边缘缓存命中率异常
+
+访问日志中缓存三态：**命中**（HIT/STALE/REVALIDATED/UPDATING）、**回源**（MISS/EXPIRED）、**未缓存**（BYPASS 或空，请求时未进入可缓存路径或响应未入库）。设计说明见 [边缘缓存策略设计](../design/edge-cache-design.md)。
+
+### 检查清单
+
+1. **性能设置** 中全局 OpenResty 缓存已开启。  
+2. 站点 **缓存** 已启用，策略与路径匹配（「标准静态资源」只覆盖内置扩展名，**不含** HTML/JSON；`.js.map` 的扩展名是 `map`，在默认表内）。  
+3. 已 **发布并激活** 配置版本，对应节点应用记录成功（改缓存规则不发布则节点仍用旧旁路逻辑）。  
+4. 请求方法为 **GET**（非 GET 一律不缓存）。  
+5. 源站未对目标 URL 返回 **`Set-Cookie`**（有则不会写入边缘）。  
+6. 源站未声明 **`Cache-Control: private` / `no-store`**（共享缓存不会存）。  
+7. 浏览器 DevTools「禁用缓存」只影响浏览器；边缘是否 HIT 看访问日志 `cache_status`，不要只看 Network 面板。
+
+### 常见误解
+
+| 现象 | 说明 |
+| --- | --- |
+| 登录后全是「未缓存」且从未发布新版本 | 旧配置曾因会话 Cookie 旁路；升级后须重新发布节点配置 |
+| `static` 下 `/api/foo` 或 `/index.html` 未缓存 | 预期行为（扩展名不在默认可缓存表） |
+| 策略为 `all` 后 HTML 被串用户 | 源站未禁止共享缓存；改回 `static` 或给动态响应加 `private`/`no-store` |
+| 带 `?v=` 的 URL 命中率低 | 默认缓存键含完整 `$request_uri`，query 不同即不同对象 |
+| 第一次 MISS、第二次仍 MISS | 查源站是否每次 `Set-Cookie`、是否 `private`，或节点磁盘/缓存 inactive 过短 |
+
+### 期望行为（对齐 Cloudflare 默认）
+
+* 带登录 Cookie 的用户访问 `/_app/**/*.js` 等静态资源：**可以 HIT**。  
+* 响应带 `Set-Cookie` 或 `private`：**不入库**。  
+* 无源站缓存头的可缓存状态码：使用默认 Edge TTL（如 200 约 120 分钟）。
+
 ## 文档站构建失败
 
 ```bash