mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-01 14:46:36 +08:00
docs(pages): 收口部署源 V2 实现
同步 Pages、总体架构、Agent 与使用指南，记录阶段提交、验证结果和生产验收边界。
This commit is contained in:
deqiying
+89
-59
@@ -1,86 +1,116 @@
|
||||
# Pages 静态托管使用
|
||||
|
||||
你会学到：如何在 OpenFlare 中使用 Pages 静态托管功能部署前端项目（如 React、Vue 等 SPA 或 VitePress、Hugo 等静态站点），配置单页应用 (SPA) Fallback 路由以及接口反向代理 (API Proxy)，并理解不可变部署与 Agent 侧原子切换的底层逻辑。
|
||||
你会学到：如何通过本地上传、Remote URL 或公开 GitHub Release asset 部署预构建静态站点，配置 SPA Fallback 与 API 反向代理，并安全地检查更新、自动发布和回滚。
|
||||
|
||||
---
|
||||
|
||||
## 核心机制与工作流
|
||||
## 核心机制与页面结构
|
||||
|
||||
OpenFlare Pages 提供受 Cloudflare Pages 启发的 **Direct Upload (直接上传)** 静态网站托管服务。它与常规代理站点的不同之处在于，数据面的边缘节点 (Agent) 会将静态文件拉取并解压到节点本地，直接通过本地的 OpenResty 提供高性能的静态文件服务，无需维护额外的 Nginx 宿主机静态目录同步。
|
||||
OpenFlare Pages 受 Cloudflare Pages 的 Direct Upload 与部署历史交互启发，但当前处理的是**预构建产物**，不是仓库源码构建。项目详情按“当前生产部署 → 部署源 → 部署历史”组织：来源配置可以变化，已经创建的 deployment 保持不可变。
|
||||
|
||||
```text
|
||||
[ 管理员 / CI ] ────── 1. 上传 ZIP 压缩包 ──────► [ OpenFlare Server ]
|
||||
│
|
||||
[ 访客浏览器 ] ◄────── 4. 访问页面 / 静态资源 ────────── [ Agent 节点 / OpenResty ]
|
||||
▲
|
||||
│
|
||||
2. 检查 Checksum 并拉取 ZIP
|
||||
3. 解压并原子切换 current 链接
|
||||
本地上传 ─> 统一校验 / upload.Ingest ─> 新 candidate ─> 管理员显式激活 ─┐
|
||||
Remote URL ── Server 受限下载 ────────┐ │
|
||||
GitHub Release asset ─ Server 解析 ───┴─> create/load deployment ─────┤
|
||||
└─> source sync 原子激活 ────────┘
|
||||
|
|
||||
v
|
||||
Agent 按项目 latest 拉取
|
||||
|
|
||||
v
|
||||
OpenResty 本地静态服务
|
||||
```
|
||||
|
||||
1. **直接上传部署包**：在控制面上传预构建好的网站 `.zip` 压缩包，Server 会生成一条带有唯一 SHA-256 校验和 (Checksum) 的不可变部署记录。
|
||||
2. **发布与推送**：在路由配置中将源站类型 (Upstream Type) 设为 `Pages 静态托管` 并绑定项目。发布配置版本后，Server 会广播给所有 Agent 节点。
|
||||
3. **安全拉取与部署**：Agent 节点识别到新配置引用了新的 Pages 部署，增量下载 ZIP 包，校验 Checksum 保证一致性，并在本地解压、完成原子目录切换，重载 OpenResty 使服务生效。
|
||||
外部 URL、GitHub 元数据和自动检查都只由 Server 处理。Agent 只从控制面拉取当前激活的部署包，不接收外部来源凭据，也不执行 `git clone`、依赖安装或构建命令。
|
||||
|
||||
---
|
||||
## 第一步：创建项目
|
||||
|
||||
## 第一步：上传部署包与创建 Pages 项目
|
||||
1. 登录管理端，进入 **「Pages」**，点击 **「创建项目」**。
|
||||
2. 填写项目名称与唯一 Slug。
|
||||
3. 配置内容入口：
|
||||
* **入口文件名**：默认 `index.html`。
|
||||
* **静态资源根路径（RootDir）**：产物位于 `dist/` 等子目录时填写该相对路径；产物就在归档根目录时留空。
|
||||
4. 按需设置 SPA Fallback 与 API 代理。RootDir 和入口文件是项目级配置，会统一应用于所有来源。
|
||||
|
||||
1. 登录管理端控制面板，进入左侧导航 **「Pages」** 菜单，点击 **「创建项目」**。
|
||||
2. 填写项目基本信息：
|
||||
* **项目名称**：业务名称（如 `我的前端应用`）。
|
||||
* **项目标识 (Slug)**：URL 友好的唯一英文标识（如 `my-react-app`），将作为存储目录的文件夹名。
|
||||
3. 设定站点目录结构与入口：
|
||||
* **入口文件名**：默认为 `index.html`。
|
||||
* **静态资源根路径 (RootDir)**：如果你的打包产物在压缩包的子目录下（例如打包出来的 zip 里包含一个 `dist/` 目录），则需要在这里填入子路径（如 `dist`）。若打包产物直接在 zip 根目录，留空即可。
|
||||
4. **上传 ZIP 压缩包**：
|
||||
* 上传你的项目静态资源打包生成的 `.zip` 文件。
|
||||
## 第二步：选择部署源
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **部署包安全限制规范**
|
||||
> 为了保障控制面和边缘节点的系统安全与性能，上传的部署包必须满足以下硬性指标，否则会被系统拒绝：
|
||||
> * **大小限制**：ZIP 压缩包体积不得超过 **25 MiB**，解压后的总文件大小不得超过 **100 MiB**。
|
||||
> * **数量限制**：解压后的文件总数不得超过 **1,000 个**。
|
||||
> * **软链接拦截**：ZIP 包内禁止包含任何软链接 (Symbolic Link)，防御软链接劫持攻击。
|
||||
> * **Zip-Slip 防御**：压缩包中所有文件路径会被强制规范化，禁止使用 `..` 或以 `/` 开头，防止解压路径穿越攻击。
|
||||
> * **入口文件检查**：你指定的入口文件（在静态资源根路径下，如 `dist/index.html`）**必须在压缩包中存在**。
|
||||
### 1. 手动上传
|
||||
|
||||
---
|
||||
不配置持久来源时，项目保持手动模式。点击 **「上传部署包」** 选择预构建归档；上传成功会创建一条候选 deployment，再从部署历史中显式激活。重复上传不会修改已有 deployment。
|
||||
|
||||
## 第二步：配置高级路由规则
|
||||
支持 `zip`、`tar.gz` / `tgz`、`tar.xz` / `txz`、`tar.bz2` / `tbz2`、`tar` 与 `7z`。
|
||||
|
||||
在项目详情的配置页面中，你可以根据前端项目类型开启以下高级特性：
|
||||
### 2. Remote URL
|
||||
|
||||
### 1. 单页应用 (SPA) Fallback 路由
|
||||
对于使用 React Router、Vue Router 等进行前端路由的单页应用 (SPA)，当用户直接刷新类似 `/profile/settings` 的子路径时，边缘节点本地并不存在该物理文件，会导致 404 错误。
|
||||
* **配置方式**：在项目设置中开启 **「SPA Fallback」**，并将路径设为入口文件（如 `/index.html`）。
|
||||
* **生效逻辑**：开启后，如果访客请求的静态资源在物理上不存在，OpenResty 会自动降级重定向渲染入口文件，将路由交由前端 JavaScript 接管，避免 404 报错。
|
||||
在部署源卡片中选择 **Remote URL**，填写 HTTP(S) 地址并选择网络策略：
|
||||
|
||||
### 2. 内置 API 反向代理
|
||||
为了避免前端请求后端 API 时遭遇跨域 (CORS) 限制，Pages 托管支持在同一个域名下直通后端 API。
|
||||
* **配置方式**：
|
||||
* **API 代理路径 (APIProxyPath)**：匹配的 URL 前缀（如 `/api`）。
|
||||
* **后端服务地址 (APIProxyPass)**：后端 API 的源站地址（如 `http://10.0.0.5:8080`）。
|
||||
* **重写规则 (APIProxyRewrite)**：可选。如果需要剥离前缀或重写路径，可使用正则匹配。例如：
|
||||
* 剥离前缀：将请求 `/api/users` 重写为 `/users` 发送给后端，配置为 `^/api/(.*)$ /$1`。
|
||||
* **生效逻辑**：所有以 `/api` 开头的请求会被直接转发至后端服务，而其他请求则继续由静态托管服务处理。
|
||||
* **public**：默认策略，拒绝 loopback、私网、链路本地地址、DNS rebinding、自签 TLS，以及重定向到非公网目标。
|
||||
* **trusted_internal**：仅用于明确受信的内网或自签服务；保存前需要再次确认风险。
|
||||
|
||||
---
|
||||
保存后地址只以脱敏形式展示。编辑其它配置时无需重新填写；只有选择更换地址时才提交新 URL。Remote 来源只提供 **「同步并发布」**：每次由 Server 下载、校验并原子激活，不支持“检查更新”、定时检查或自动更新。
|
||||
|
||||
## 第三步：绑定代理路由并发布
|
||||
### 3. GitHub Release
|
||||
|
||||
Pages 项目配置并上传好部署包后，需要绑定到对外公开的域名上才能被访客访问。
|
||||
GitHub 来源仅支持公开 `github.com` 仓库。填写：
|
||||
|
||||
1. 导航至左侧菜单 **「规则管理」**，创建或编辑一条代理规则。
|
||||
2. 切换到 **「反向代理」** 选项卡：
|
||||
* **源站类型**：选择 **「Pages」**。
|
||||
* **选择 Pages 项目**：选择你刚才创建的项目，并关联要激活的部署版本（默认会自动关联最新上传成功的部署）。
|
||||
3. 点击右上角 **「配置预览」** -> 确认无误后点击 **「发布并激活」**。
|
||||
* `https://github.com/{owner}/{repo}` 格式的仓库地址；
|
||||
* **最新 Release** 或 **固定 Tag**；
|
||||
* 精确、区分大小写的 Release Asset 文件名，默认 `dist.zip`。
|
||||
|
||||
## 运维与回滚
|
||||
两种选择都可手动 **「检查更新」** 和 **「同步并发布」**。区别如下：
|
||||
|
||||
* **不可变部署与回滚**：每次在 Pages 项目下上传 `.zip` 文件，系统都会产生一个全新且唯一的部署版本。如果在历史部署列表中将上一版本设为激活并重新发布，可实现边缘节点的秒级回滚。
|
||||
* **原子切换与自愈**：边缘节点（Agent）在拉取静态资源包时，会执行校验与流式解压，并通过原子切换物理目录来保障服务的无缝过渡。同时，Agent 会定时清理不再引用的历史部署包。
|
||||
* **latest**：可设置 5～1440 分钟检查间隔，默认 60 分钟；自动更新默认关闭。开启后，scanner 发现新 revision 才会异步同步并发布。
|
||||
* **tag**：只支持管理员手动检查和同步，不参与定时 scanner。
|
||||
|
||||
“检查更新”只解析 Release/asset 并更新版本游标，不下载部署包；“同步并发布”才会下载、校验、创建或复用 deployment 并激活。如果同一个 Release 下的 asset 被替换，来源会进入 **「需要确认」**，必须确认页面显示的精确 revision 后才能发布，避免静默覆盖。
|
||||
|
||||
GitHub Release 在这里是预构建产物源，不等同于连接代码仓库自动构建。未来仓库集成会使用独立的 `git_repository` 来源和 Server build executor，再把构建产物送入同一部署管线。
|
||||
|
||||
### 4. 切换或删除来源
|
||||
|
||||
可以在手动、Remote 和 GitHub Release 之间切换。修改或删除来源不会删除当前生产部署和历史 deployment；切回手动模式后可继续上传并显式激活。
|
||||
|
||||
## 部署包安全限制
|
||||
|
||||
部署包必须满足以下约束：
|
||||
|
||||
* 压缩包大小由系统配置 `pages_max_package_size_mb` 控制，默认 100 MiB，可配置 1～2048 MiB。
|
||||
* 展开后的单文件和总量上限为“包大小上限 × 4”，且最低为 100 MiB；最多 1,000 个常规文件。
|
||||
* 控制面会流式读取常规文件体，核对声明大小与实际字节，并校验项目入口文件。
|
||||
* 归档中的绝对路径、`..` 路径逃逸、软链接、硬链接和特殊文件都会被拒绝。
|
||||
|
||||
Agent 下载时还会执行 SHA-256、真实响应字节上限、解压后文件数与总大小复核；失败不会切换现有 `current`。
|
||||
|
||||
## 第三步：配置高级路由规则
|
||||
|
||||
### 1. SPA Fallback
|
||||
|
||||
使用 React Router、Vue Router 等前端路由时，开启 **「SPA Fallback」** 并设置入口路径（通常为 `/index.html`）。访客直接访问不存在的物理路径时，OpenResty 会回退到入口文件交由前端路由处理。
|
||||
|
||||
### 2. API 反向代理
|
||||
|
||||
Pages 可在同一域名下把指定前缀转发到后端 API：
|
||||
|
||||
* **APIProxyPath**：匹配前缀，例如 `/api`。
|
||||
* **APIProxyPass**：后端地址，例如 `http://10.0.0.5:8080`。
|
||||
* **APIProxyRewrite**：可选的路径重写规则。
|
||||
|
||||
匹配 API 前缀的请求走反向代理，其余请求继续由静态站点处理。
|
||||
|
||||
## 第四步：绑定路由并首次发布
|
||||
|
||||
1. 创建或编辑一条代理规则。
|
||||
2. 将源站类型设为 **Pages**，并选择 Pages **项目**。
|
||||
3. 预览配置后发布并激活。
|
||||
|
||||
路由绑定的是稳定的项目 ID，不是某个 deployment。首次发布让 Agent 获得项目锚点；此后本地上传、来源同步、自动更新或人工回滚只会改变项目的 active deployment，Agent 会通过 latest hash 对账收敛，无需重新发布主配置。
|
||||
|
||||
## 运维、状态与回滚
|
||||
|
||||
* 来源卡片展示最近检查/同步、已发现与已应用 revision、下次检查和安全错误。检查或同步任务运行时，页面会轮询任务状态；latest 空闲时只在接近检查时间时低频刷新。
|
||||
* 自动更新失败不会替换旧 active deployment；单个来源失败也不会阻塞 scanner 处理其它项目。
|
||||
* 在部署历史中激活其它 deployment 即完成人工回滚。系统会 fence 在途来源任务，并关闭该来源的自动更新，避免下一轮 latest 又覆盖人工选择；重复激活当前版本是 no-op。
|
||||
* Agent 下载到临时文件并校验 SHA-256，安全解压后原子切换 `current`。任一步失败都保留旧内容，多项目对账时单项目失败不影响其它项目。
|
||||
|
||||
> [!TIP]
|
||||
> 关于不可变部署、目录结构设计、增量拉取和安全防逃逸校验等底层架构与自愈细节，请参阅 [Pages 静态托管设计](../design/pages-design.md)。
|
||||
> 关于来源状态机、自动 scanner、上传补偿、不可变部署和 Agent 原子切换，请参阅 [Pages 静态托管设计](../design/pages-design.md)。
|
||||
|
||||
Reference in New Issue
Block a user