mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-02 23:06:36 +08:00
feat(option): add sw offline
fix(openresty): scope sw injection per cert partition fix(lint): satisfy revive and biome format for sw offline feature docs: sw offline scope changelog fix(frontend): use scoped query key for sw scope zones fix(frontend): hide preview link in sw contact page editor feat(frontend): add sw scope domain picker and contact page fields refactor(frontend): generalize html editor workspace for reuse feat(openresty): scope sw offline injection by route domains feat(openresty): add sw offline domains snapshot field feat(option): add sw offline domains scope option docs: fill html editor workspace generalization detail docs: sw offline scope implementation plan docs: sw offline scope design test(openresty): assert single merged access block in sw enabled servers fix(openresty): restrict sw intercept to https server blocks fix(openresty): version sw offline cache by html content fix(agent): escape redir in sw challenge page to prevent xss fix(agent): return sw.runtime module table and add lua spec docs: sw offline fallback changelog fix(frontend): memoize option map to preserve unsaved contact page edits feat(frontend): add response pages module with contact page tab feat(agent): ship sw offline lua assets and placeholder substitution feat(config): wire sw offline options into config snapshot feat(openresty): render sw offline assets and challenge intercept feat(openresty): add sw offline ConfigSnapshot fields and placeholder feat(db): seed sw offline options feat(option): add sw offline config keys and validation docs: add service worker offline fallback implementation plan docs: adopt global-option pattern for SW offline fallback (matches origin error page) docs: unify offline contact page with error pages as response pages docs: service worker offline fallback design (issue #23)
This commit is contained in:
ryan
@@ -0,0 +1,117 @@
|
||||
# Service Worker 离线兜底设计（issue #23）
|
||||
|
||||
- 日期：2026-08-08
|
||||
- 状态：设计已确认
|
||||
- 范围：Proxy Route（反代）+ Pages 静态托管 全覆盖
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
当 CDN 域名被墙、浏览器对所有网络请求失败时，用户会直接流失。本功能通过给网站下发 Service Worker，缓存一个"联系站长"离线页；域名被墙后，SW 从缓存吐出该页，保留用户并引导联系站长。
|
||||
|
||||
核心约束：
|
||||
|
||||
- 平台一键批量下发，避免逐个 Agent 配置。
|
||||
- 不改源页代码，全部在 OpenResty 边缘层完成。
|
||||
- 覆盖反代（Proxy Route）与 Pages 静态托管两种网站类型。
|
||||
|
||||
## 2. 机制总览
|
||||
|
||||
采用「首次挑战页 + Cookie 放行 + UA 白名单」模式，替代 `sub_filter` 响应体重写。
|
||||
|
||||
| 环节 | 行为 |
|
||||
|---|---|
|
||||
| 真实浏览器 UA（含特征版本，如 `Chrome/120`）首次访问首页 | 返回 SW 挑战页（内嵌 `register('/sw.js')` 与离线页预缓存），设置长过期 Cookie |
|
||||
| 带 Cookie 的请求 | 直接放行到上游，正常返回真实页面 |
|
||||
| 未知 UA（爬虫、curl，无真实浏览器特征） | 直接放过，交给 WAF 处理，拿到真实内容 |
|
||||
|
||||
### 为什么不用 sub_filter
|
||||
|
||||
`sub_filter` 需处理上游 gzip / Content-Type / 大响应扫描 / 流式缓冲等多处坑。本方案不改上游 body，整体替换首次响应，以上问题全部规避；且爬虫（不匹配真实浏览器 UA）天然绕过挑战页，不伤 SEO。
|
||||
|
||||
## 3. 分层职责
|
||||
|
||||
```
|
||||
apps/proxy_route ─┐
|
||||
apps/pages ─┼─ model → repository → 渲染(pkg/render/openresty) → Agent(OpenResty)
|
||||
前端设置卡 ─┘ ↑ SW 挑战页 + sw.js/offline 落盘
|
||||
```
|
||||
|
||||
### 后端数据（全局 Option，与 origin error page 同模式）
|
||||
|
||||
`sw_offline` 相关配置作为**全局 SystemConfig / OpenRestyConfig snapshot 字段**，对所有启用 HTTPS 的路由生效，实现"一键批量下发"。新增字段：
|
||||
|
||||
- `sw_offline_enabled`：是否启用 SW 离线兜底
|
||||
- `sw_offline_html`：联系站长离线页 HTML 内容（默认提供内置模板）
|
||||
|
||||
### 渲染层（`pkg/render/openresty`）
|
||||
|
||||
新增 `renderServiceWorkerChallenger(cfg ConfigSnapshot)` 工具，为真实提供内容的 HTTPS server 块（`sw_offline_enabled` 且 `EnableHTTPS` 时）输出：
|
||||
|
||||
```nginx
|
||||
# SW 脚本 + 离线页（作为 support file 落盘）
|
||||
location = /sw.js { alias .../sw.js; add_header Service-Worker-Allowed /; }
|
||||
location = /offline.html { alias .../offline.html; }
|
||||
|
||||
# 仅首页拦截：真实浏览器 UA 且无 cookie → 返回 SW 挑战页
|
||||
# 否则（带 cookie / 未知 UA）→ 放行到上游
|
||||
location = / {
|
||||
if (真实浏览器UA && 无cookie) { content_by_lua 返回 SW 挑战页; }
|
||||
放行到上游;
|
||||
}
|
||||
```
|
||||
|
||||
- SW 逻辑：`install` 阶段缓存 `/offline.html`；`fetch` 事件在网络失败时返回 `caches.match('/offline.html')`。
|
||||
- 仅在 `EnableHTTPS` 时注入（SW 要求 HTTPS 安全上下文）。
|
||||
- 多域名 server 块：`/sw.js`、`/offline.html`、挑战页在各 `server_name` 下同源可达。
|
||||
- 仅对首页 `location = /` 触发；js/css/图片/API/子页面请求不拦，零额外开销。
|
||||
|
||||
## 4. 数据流
|
||||
|
||||
```
|
||||
用户首次访问首页(真实UA, 无cookie)
|
||||
→ OpenResty 判断：真实UA && 无cookie
|
||||
→ 返回 SW 挑战页 (内嵌 register + 预缓存 offline.html)
|
||||
→ 浏览器执行 → 注册 SW → 设置长过期 cookie
|
||||
→ 用户再次请求(带cookie)
|
||||
→ 放行到上游，正常返回真实页面
|
||||
域名被墙后
|
||||
→ 所有请求失败 → SW fetch 兜底 → 从缓存返回 /offline.html(联系页)
|
||||
```
|
||||
|
||||
## 5. 边界与风险
|
||||
|
||||
| 项 | 处理 |
|
||||
|---|---|
|
||||
| 首次即被墙的用户 | SW 未注册，兜底无效（所有 SW 方案共性，接受） |
|
||||
| HTTP-only 站点 | 跳过注入（SW 需 HTTPS） |
|
||||
| 反代多域名 | 各域名同源提供 sw.js / offline.html / 挑战页 |
|
||||
| Cookie 过期 | 设长过期（约 1 年），过期后重新走一次挑战页 |
|
||||
| 未知 UA | 放过并交给 WAF 处理，不重复拦截 |
|
||||
| 资源/API 请求 | 不拦，仅首页触发 |
|
||||
|
||||
## 6. 测试
|
||||
|
||||
- 渲染层单元测试：
|
||||
- `sw_offline_enabled` 时输出 sw.js / offline.html / 挑战页 location
|
||||
- 非 HTTPS 或未启用时不输出
|
||||
- 仅首页触发，子路径/资源不触发
|
||||
- UA 判定：真实浏览器 / 爬虫 / curl 三种 UA 的放行分支。
|
||||
- Cookie 有无的放行分支。
|
||||
- 现有 config snapshot checksum / rebind 测试不回归。
|
||||
|
||||
## 7. 前端命名与入口
|
||||
|
||||
离线联系页设置与现有 origin error page 设置合并为同一个功能模块，命名为**「响应页面」**（路由 `responses`），内含两个 tab：
|
||||
|
||||
- **错误页设置**：源站错误兜底页（现有 origin error page）
|
||||
- **联系页设置**：SW 离线兜底联系页（本功能）
|
||||
|
||||
两者同属「边缘层兜底展示页」语义，统一管理与入口。
|
||||
|
||||
## 8. 待实现确认项（写 plan 时细化）
|
||||
|
||||
- SW 挑战页与 sw.js 的具体 Lua 实现与落盘路径（对齐现有 support file 机制）。
|
||||
- `sw_offline_html` 默认内置模板样式（参考 origin error page 内置模板）。
|
||||
- 「响应页面」前端模块下错误页/联系页两个 tab 的具体位置与交互。
|
||||
- UA 白名单默认真实浏览器特征集合（Chrome / Firefox / Safari / Edge + 版本号正则）。
|
||||
- SW 落盘路径：sw.js / offline.html 通过 SupportFile 下发，Agent 替换占位符（类似 ErrorPageTmplPlaceholder 机制）。
|
||||
@@ -0,0 +1,191 @@
|
||||
# SW 离线兜底生效范围（域名作用域）设计
|
||||
|
||||
- 日期：2026-08-08
|
||||
- 状态：设计已确认
|
||||
- 前置：issue #23 Service Worker 离线兜底（`docs/superpowers/specs/2026-08-08-service-worker-offline-design.md`）
|
||||
- 范围：SW 注入从「全局所有 HTTPS 站点」细化为「总开关 + 域名作用域」
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
issue #23 实现后，`sw_offline_enabled` 为全局布尔开关：开启后对所有启用 HTTPS 的路由注入 Service Worker 离线兜底。本需求将其细化为可选的**生效域名范围**：
|
||||
|
||||
- 保留总开关（`sw_offline_enabled`）。
|
||||
- 新增作用域：管理员选择需要生效的域名，仅作用域内域名注入 SW。
|
||||
- 域名选择交互参考 `/cloudflare/groups/1` 的「添加域名成员」弹窗（搜索筛选、按 Zone 分组、批量勾选），但**与 Cloudflare 完全解耦**——仅复用交互模式，数据源为平台自身 zones/zone_domains，不涉及 A 记录同步。
|
||||
|
||||
核心约束：
|
||||
|
||||
- 语义为「总开关 && 域名 ∈ 作用域」交集：总开关关 → 全部不注入；总开关开 + 作用域空 → 不注入；总开关开 + 域名命中 → 注入。
|
||||
- 与 Cloudflare 指向分组（A 记录）无任何关联。
|
||||
- 联系页 HTML（`sw_offline_html`）仍为全局单份，不分域名定制。
|
||||
|
||||
## 2. 机制总览
|
||||
|
||||
```
|
||||
sw_offline_enabled (bool, 已有) 总开关
|
||||
sw_offline_html (string, 已有) 联系页 HTML（全局一份）
|
||||
sw_offline_domains (JSON 字符串数组, 新增) 生效域名作用域
|
||||
|
||||
渲染: routeSWEnabled(routeDomains, cfg)
|
||||
= SWOfflineEnabled && routeDomains ∩ SWOfflineDomains ≠ ∅
|
||||
命中 → HTTPS server 块注入 access 检查 + SW location
|
||||
未命中 → 与 feature 前字节一致
|
||||
```
|
||||
|
||||
Support files（`sw/sw.js`、`sw/offline.html`）仅在「总开关开 && 作用域非空」时下发，避免空作用域产生无用资源。
|
||||
|
||||
## 3. 数据层
|
||||
|
||||
### 3.1 配置 key
|
||||
|
||||
`model.ConfigKeySWOfflineDomains = "sw_offline_domains"`（business 类型，visibility 0），值存 JSON 域名字符串数组：
|
||||
|
||||
```json
|
||||
["example.com", "api.example.com"]
|
||||
```
|
||||
|
||||
### 3.2 goose 迁移（postgres + sqlite 各一份）
|
||||
|
||||
`INSERT INTO w_system_configs (key, value, type, visibility, description, created_at, updated_at) VALUES ('sw_offline_domains', '[]', 'business', 0, 'SW 离线兜底生效域名列表（JSON 数组，空则仅总开关无效）', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP) ON CONFLICT (key) DO NOTHING;`
|
||||
|
||||
Down 删除该 key。migrator 测试计数 92 → 93，并更新注释。
|
||||
|
||||
### 3.3 validator
|
||||
|
||||
`validateSWOfflineDomains(key, value string) error`，注册进 `openRestyOptionValidators`：
|
||||
|
||||
- JSON 解析为 `[]string`，失败报「必须为 JSON 字符串数组」
|
||||
- 元素去重（重复报错）
|
||||
- 元素非空、小写规范化校验（复用/对齐 zone `normalizeDomain` 的域名格式约束：无 `*`、无 `://` `/` `?` `#` `@`、`publicsuffix.EffectiveTLDPlusOne` 可解析）
|
||||
- 数量上限 `maxSWOfflineDomains = 1000`（防滥用）
|
||||
|
||||
### 3.4 config_version snapshot
|
||||
|
||||
- `openRestyConfigSnapshot`（`snapshot.go`）新增 `SWOfflineDomains []string json:"sw_offline_domains,omitempty"`。
|
||||
- `buildOpenRestyConfigSnapshot` 新增 `getStringSliceConfig(key string, defaultVal []string) []string`（解析 JSON 数组，失败回退默认），赋值 `SWOfflineDomains: getStringSliceConfig(model.ConfigKeySWOfflineDomains, nil)`。
|
||||
- `logics.go`：`diffOpenRestyOptionDetails` 追加 `appendIfChanged("SWOfflineDomains", ...)`；`openRestyOptionKeys()` 追加 `"SWOfflineDomains"`。
|
||||
|
||||
## 4. 渲染层（pkg/render/openresty）
|
||||
|
||||
### 4.1 ConfigSnapshot
|
||||
|
||||
`types.go` 的 `ConfigSnapshot` 新增：
|
||||
|
||||
```go
|
||||
// SWOfflineDomains restricts the offline fallback to matching HTTPS routes.
|
||||
SWOfflineDomains []string `json:"sw_offline_domains,omitempty"`
|
||||
```
|
||||
|
||||
### 4.2 作用域判断
|
||||
|
||||
```go
|
||||
// routeSWEnabled returns true when SW offline fallback applies to this route.
|
||||
func routeSWEnabled(routeDomains []string, cfg ConfigSnapshot) bool {
|
||||
if !cfg.SWOfflineEnabled || len(cfg.SWOfflineDomains) == 0 {
|
||||
return false
|
||||
}
|
||||
scope := make(map[string]struct{}, len(cfg.SWOfflineDomains))
|
||||
for _, d := range cfg.SWOfflineDomains {
|
||||
scope[d] = struct{}{}
|
||||
}
|
||||
for _, d := range routeDomains {
|
||||
if _, ok := scope[d]; ok {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
```
|
||||
|
||||
域名精确匹配（存储时已小写规范化）。
|
||||
|
||||
### 4.3 server 渲染签名扩展
|
||||
|
||||
- `RenderRouteConfig`：每 route 计算 `swEnabled := routeSWEnabled(domains, doc.OpenRestyConfig)`，传入 `renderProxyRoute` / `renderPagesRoute`（新增 `swEnabled bool` 参数）。
|
||||
- 下传链路：`renderProxyRouteHTTPS` / `renderPagesRouteHTTPS` / `renderHTTPSServer` / `renderHTTPSPagesServer` 均新增 `swEnabled bool` 参数。
|
||||
- `swEnabled=true` → `renderAccessBlockWithSW(siteName, powEnabled, cfg)` + 追加 `renderServiceWorkerChallenger(cfg)`（现行为，两函数内部不再判断 `SWOfflineEnabled`，条件已上移到 route 层）。
|
||||
- `swEnabled=false` → 纯 `renderAccessBlock`，无 challenger（与 feature 前字节一致）。
|
||||
- HTTP（80）server 块保持不注入（issue #23 已定 HTTPS-only）。
|
||||
- `renderAccessBlockWithSW` / `renderServiceWorkerChallenger` 保留 `cfg` 参数（HTML 内容来自 `cfg.SWOfflineHTML`），仅移除其内部开关判断。
|
||||
|
||||
### 4.4 Support files
|
||||
|
||||
`Render` 中生成条件从 `if doc.OpenRestyConfig.SWOfflineEnabled` 改为：
|
||||
|
||||
```go
|
||||
if doc.OpenRestyConfig.SWOfflineEnabled && len(doc.OpenRestyConfig.SWOfflineDomains) > 0 {
|
||||
files = append(files, ServiceWorkerSupportFiles(doc.OpenRestyConfig)...)
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 测试
|
||||
|
||||
- `routeSWEnabled`：开关关 / 作用域空 / 无交集 / 单域名交集 / 多域名部分交集。
|
||||
- HTTPS server 渲染：命中 → 含 `require("sw.runtime").check()` + 三个 SW location；未命中 → 与旧输出字节一致。
|
||||
- `Render`：空作用域不下发 `sw/*` support files。
|
||||
- 现有 `TestRenderAccessBlockWithSWMergesSingleBlock` 等适配新签名（`cfg` 语义变化：禁用时不再由内部判断，改由上层传 `swEnabled`）。
|
||||
|
||||
## 5. 前端（frontend/app/(main)/responses）
|
||||
|
||||
### 5.1 联系页 tab 布局
|
||||
|
||||
联系页 tab 两张卡片：
|
||||
|
||||
**卡片 1：离线兜底（总开关）**
|
||||
- 标题「离线兜底」+ 描述。
|
||||
- 右上角「保存」按钮。
|
||||
- 「启用 Service Worker 离线兜底」Switch（`sw_offline_enabled`）。
|
||||
- 「生效范围」区块：当前已选域名 badge 列表（可移除）+「添加域名」按钮打开弹窗；开关关闭时整卡禁用/置灰。
|
||||
- 保存时 `updateBatch` 一次性提交三个 key：
|
||||
```ts
|
||||
{ key: KEY_SW_ENABLED, value: String(fields.enabled) },
|
||||
{ key: KEY_SW_HTML, value: fields.html },
|
||||
{ key: KEY_SW_DOMAINS, value: JSON.stringify(fields.domains) },
|
||||
```
|
||||
- 保存成功后 `invalidateResponseQueries`（toast 提示「请前往版本发布使配置生效」不变）。
|
||||
|
||||
**卡片 2：联系页 HTML**
|
||||
- 复用 `HtmlEditorWorkspace`（见 5.3），无占位符，实时预览原样 HTML。
|
||||
|
||||
### 5.2 域名选择弹窗（scope-domain-dialog.tsx）
|
||||
|
||||
- 交互复用 `member-add-dialog.tsx`：搜索框（域名/zone 模糊匹配）、按 Zone 分组折叠、组内勾选/取消、全选可见/清空、已选计数。
|
||||
- 无橙云开关、无 Cloudflare 依赖。
|
||||
- 数据源：`ZoneService.list()` + 每 zone `ZoneService.getOverview(id)` 并行拉取（`Promise.all`），zone 根域并入对应分组。**不新增后端 API**。
|
||||
- 弹窗预勾选当前已生效域名；确认后返回选中的域名字符串数组（覆盖式替换本地 fields.domains）。
|
||||
- 空态：无 zone 时提示「暂无可用域名，请先在 Zone 管理中注册」。
|
||||
|
||||
### 5.3 HtmlEditorWorkspace 复用（泛化）
|
||||
|
||||
`frontend/app/(main)/error-pages/components/html-editor-workspace.tsx` 泛化并移至 `frontend/components/common/html-editor-workspace.tsx`：
|
||||
|
||||
- Props 扩展：
|
||||
- `maxBytes?: number`（默认 `ORIGIN_ERROR_PAGE_HTML_MAX_BYTES` = 256 KiB，SW 同为 256 KiB 常量可共用）
|
||||
- `preview?: (html: string) => string`（默认 `previewOriginErrorPageHTML`；SW 传 `(html) => html` 原样预览）
|
||||
- `footerHint?: React.ReactNode`（预览 footer 提示文案，默认错误页的「`{{status}}`→502 · `{{host}}`→example.com」；SW 传 `null`）
|
||||
- 错误页 `edit/page.tsx` 改 import 路径，行为不变。
|
||||
- `frontend/components/common/` 若不存在则创建目录。
|
||||
|
||||
### 5.4 shared.ts 与表单
|
||||
|
||||
- `KEY_SW_DOMAINS = 'sw_offline_domains'`。
|
||||
- `ContactPageFields` 增加 `domains: string[]`；`defaultContactPageFields.domains = []`。
|
||||
- `mapOptionsToContactFields` 解析 `sw_offline_domains` JSON（容错：非法 JSON → `[]`）。
|
||||
|
||||
## 6. 验证
|
||||
|
||||
- 后端：`go test ./pkg/render/openresty/... ./internal/apps/openflare/option/... ./internal/apps/openflare/config_version/... ./internal/infra/persistence/migrator/...`
|
||||
- 前端：`pnpm tsc --noEmit` + `eslint`（联系页新字段/弹窗/多 zone 并行拉取）
|
||||
- 全量：`go test ./...`、`make code-check`、`make format`
|
||||
- `make swagger`：无新 API（验证无变更即可）
|
||||
|
||||
## 7. Changelog
|
||||
|
||||
`docs/changelog/index.md` `[Unreleased]` 更新 SW 条目：新增「可指定生效域名范围（仅对选中的 HTTPS 域名生效）」。
|
||||
|
||||
## 8. 已知边界
|
||||
|
||||
- 作用域存域名字符串数组：域名从 zone/zone_domain 改名后需手动同步作用域（与 `route.Domains` 精确匹配）。
|
||||
- 联系页 HTML 全局单份，不分域名定制。
|
||||
- 空作用域 + 总开关开 → 不注入（前端置灰提示先选域名）。
|
||||
- 匹配为精确匹配，不跨子域通配（选 `example.com` 不自动覆盖 `api.example.com`，需显式加入）。
|
||||
Reference in New Issue
Block a user