[新增] OpenFlare Pages

docs/design/architecture.md

@@ -85,7 +85,7 @@ Agent 本地 Pages 部署目录
 
 Server 不直接 SSH 到节点，也不在线修改节点文件。它只保存控制面状态、生成完整配置版本，并通过 Agent API 让节点主动拉取。
 
-Pages 静态托管场景中，Server 保存 Pages 项目、不可变部署元数据、文件清单和 zip 部署包；发布版本只记录部署引用和 checksum，不把大体积静态资源写入 `config_versions`。
+Pages 静态托管场景中，Server 保存 Pages 项目、SPA fallback 回退路径、不可变部署元数据、文件清单和 zip 部署包；发布版本只记录部署引用、checksum 与静态渲染策略，不把大体积静态资源写入 `config_versions`。
 
 ## Agent
 

docs/design/index.md

@@ -88,11 +88,11 @@ OpenFlare Pages 面向边缘节点静态站点托管，采用“项目 + 不可
 
 约束：
 
-* Pages 项目保存名称、标识、启用状态、SPA fallback 选项和当前激活部署。
+* Pages 项目保存名称、标识、启用状态、SPA fallback 启用状态、自定义回退路径和当前激活部署。
 * Pages 部署由管理端上传预构建 zip 包生成；部署包保存在 Server 本地 Pages 存储目录，数据库只保存部署元数据和文件清单，不保存大体积文件内容。
 * 只有项目存在激活部署后，`proxy_routes.upstream_type = 'pages'` 的网站规则才能绑定该项目。
 * Pages 网站继续复用网站规则的域名、HTTPS、WAF、PoW、Basic Auth、限流、缓存配置和配置版本发布机制。
-* 发布快照保存 Pages 项目、部署 ID、部署 checksum、入口文件和 SPA fallback 选项。Agent 拉取激活配置时按部署 checksum 下载并校验部署包，解压到本地 `pages_dir` 后再应用 OpenResty 配置。
+* 发布快照保存 Pages 项目、部署 ID、部署 checksum、入口文件、SPA fallback 启用状态和回退路径。Agent 拉取激活配置时按部署 checksum 下载并校验部署包，解压到本地 `pages_dir` 后再应用 OpenResty 配置。
 * V1 不支持 Git 自动构建、预览域名、边缘函数、动态 SSR、外部对象存储或多租户隔离。
 
 ## 内网穿透约束

docs/guide/usage.md

@@ -63,6 +63,21 @@ OpenFlare 不直接在线修改节点上的 Nginx/OpenResty 配置。你在管
 * 修改源站目录后，检查已发布的网站配置是否需要同步更新源站快照。
 * 发布前使用预览或 diff 确认渲染结果。
 
+## 托管 Pages 静态站点
+
+Pages 用于托管已经构建完成的静态资源包。当前阶段只支持 Direct Upload，不执行 Git 构建、边缘函数或 SSR。
+
+操作顺序：
+
+1. 进入 **Pages** 页面，点击 **新建 Pages 项目**。
+2. 填写项目名称、标识、描述；如为前端 history 路由应用，启用 **SPA fallback** 并填写回退路径，默认是 `/index.html`，也可以设置为 `/app.html` 等站点内绝对路径。
+3. 创建后回到 Pages 项目列表，点击项目进入详情。
+4. 在项目详情中上传 zip 静态资源包，并激活某个部署。
+5. 新建或编辑网站规则，将回源方式切换为 **Pages 静态站点**，选择该 Pages 项目。
+6. 发布并激活配置版本，Agent 会下载部署包、校验 checksum、解压到本地 Pages 目录，再由 OpenResty 本地服务静态文件。
+
+Pages 项目只有在启用且存在激活部署后，才会出现在网站规则的 Pages 项目选择列表中。
+
 ## 启用 HTTPS
 
 HTTPS 按域名绑定证书，而不是按整个网站统一强制启用。

docs/guildline/development-constraints.md

@@ -98,6 +98,7 @@ Frontend：
 * **Pages 与上游关联**：
   * `proxy_routes.upstream_type = 'pages'` 时，必须指定 `pages_project_id`。
   * 被引用的 Pages 项目必须启用，且必须存在当前激活部署。
+  * Pages 项目可启用 SPA fallback 并配置站点内绝对回退路径（默认 `/index.html`）；回退路径必须经 Server 校验后进入发布快照，不得直接拼接未校验输入到 OpenResty 配置。
   * Pages 部署包必须作为 Server 本地文件保存，数据库只保存部署元数据与文件清单；禁止把静态资源内容写入 `config_versions.support_files_json`。
   * 发布配置时，Server 将 Pages 上游渲染为 OpenResty `root` + `try_files` 静态服务，并保留网站规则已有的 HTTPS、WAF、PoW、Basic Auth、限流与缓存配置。
 
@@ -171,7 +172,7 @@ v1-v7 视为历史初始基线，不再维护逐版本升级文件。v8-v17 是
   - Token 管理（生成、轮换）。
   - 强制同步（触发 Client 立即拉取新配置）。
 * **Admin Pages 管理 API** - `/api/pages/*`，要求 Admin Session。
-  - CRUD Pages 项目。
+  - CRUD Pages 项目，包括 SPA fallback 启用状态与回退路径。
   - 上传 zip 部署包、查看部署历史、激活部署、删除非激活部署。
 * **Agent Pages 下载 API** - `/api/agent/pages/*`，使用 `X-Agent-Token` 认证。
   - Agent 仅能按激活配置引用的部署 ID 拉取静态部署包，不提供任意文件读取或远程命令入口。
@@ -197,7 +198,7 @@ v1-v7 视为历史初始基线，不再维护逐版本升级文件。v8-v17 是
 * 自动型 WAF IP 组只能由 Server 定时任务读取请求日志并执行 Expr 布尔规则，OpenResty Lua 与 Agent 不得直接访问请求日志库或执行自动挖掘逻辑。
 * 发布版本不得展开 WAF IP 组成员；Agent 必须通过独立的 IP 组 checksum 差异同步和 WebSocket 增量广播维护本地 `waf_ip_groups.json`。
 * **Pages 配置扩展**：区分上游类型，为 `upstream_type = 'pages'` 的代理规则生成 Pages 部署快照。
-  * OpenResty 侧：将 Pages 上游渲染为本地静态目录 `root` 与 `try_files`，不得渲染 `proxy_pass`。
+  * OpenResty 侧：将 Pages 上游渲染为本地静态目录 `root` 与 `try_files`，启用 SPA fallback 时使用项目配置的回退路径，不得渲染 `proxy_pass`。
   * Agent 侧：在应用 OpenResty 配置前，必须确保引用的 Pages 部署包已下载、checksum 校验通过并解压到 `pages_dir`。
 * **内网穿透配置扩展**：区分上游类型，为 `upstream_type = 'tunnel'` 的代理规则生成独立的 tunnel 配置数据。
   * OpenResty 侧：将 tunnel 上游自动渲染为 `http://127.0.0.1:{relay_vhost_port}`，必须保留原始 `Host` 请求头。