# Pages 静态托管使用

你会学到：如何在 OpenFlare 中使用 Pages 静态托管功能部署前端项目（如 React、Vue 等 SPA 或 VitePress、Hugo 等静态站点），配置单页应用 (SPA) Fallback 路由以及接口反向代理 (API Proxy)，并理解不可变部署与 Agent 侧原子切换的底层逻辑。

---

## 核心机制与工作流

OpenFlare Pages 提供受 Cloudflare Pages 启发的 **Direct Upload (直接上传)** 静态网站托管服务。它与常规代理站点的不同之处在于，数据面的边缘节点 (Agent) 会将静态文件拉取并解压到节点本地，直接通过本地的 OpenResty 提供高性能的静态文件服务，无需维护额外的 Nginx 宿主机静态目录同步。

```text
  [ 管理员 / CI ] ────── 1. 上传 ZIP 压缩包 ──────► [ OpenFlare Server ]
                                                           │
  [ 访客浏览器 ]  ◄────── 4. 访问页面 / 静态资源 ────────── [ Agent 节点 / OpenResty ]
                                                           ▲
                                                           │
                                                2. 检查 Checksum 并拉取 ZIP
                                                3. 解压并原子切换 current 链接
```

1. **直接上传部署包**：在控制面上传预构建好的网站 `.zip` 压缩包，Server 会生成一条带有唯一 SHA-256 校验和 (Checksum) 的不可变部署记录。
2. **发布与推送**：在路由配置中将源站类型 (Upstream Type) 设为 `Pages 静态托管` 并绑定项目。发布配置版本后，Server 会广播给所有 Agent 节点。
3. **安全拉取与部署**：Agent 节点识别到新配置引用了新的 Pages 部署，增量下载 ZIP 包，校验 Checksum 保证一致性，并在本地解压、完成原子目录切换，重载 OpenResty 使服务生效。

---

## 第一步：上传部署包与创建 Pages 项目

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. 单页应用 (SPA) Fallback 路由
对于使用 React Router、Vue Router 等进行前端路由的单页应用 (SPA)，当用户直接刷新类似 `/profile/settings` 的子路径时，边缘节点本地并不存在该物理文件，会导致 404 错误。
* **配置方式**：在项目设置中开启 **「SPA Fallback」**，并将路径设为入口文件（如 `/index.html`）。
* **生效逻辑**：开启后，如果访客请求的静态资源在物理上不存在，OpenResty 会自动降级重定向渲染入口文件，将路由交由前端 JavaScript 接管，避免 404 报错。

### 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` 开头的请求会被直接转发至后端服务，而其他请求则继续由静态托管服务处理。

---

## 第三步：绑定代理路由并发布

Pages 项目配置并上传好部署包后，需要绑定到对外公开的域名上才能被访客访问。

1. 导航至左侧菜单 **「网站配置」**，创建或编辑一个代理站点。
2. 在「路由规则」中修改或添加一条路由：
   * **源站类型 (Upstream Type)**：选择 **「Pages 静态托管」**。
   * **绑定 Pages 项目**：选择你刚才创建的项目，并指定要激活的部署版本（默认会自动关联最新上传成功的部署）。
3. 点击右上角 **「配置预览」** -> 确认无误后点击 **「发布并激活」**。

## 运维与回滚

* **不可变部署与回滚**：每次在 Pages 项目下上传 `.zip` 文件，系统都会产生一个全新且唯一的部署版本。如果在历史部署列表中将上一版本设为激活并重新发布，可实现边缘节点的秒级回滚。
* **原子切换与自愈**：边缘节点（Agent）在拉取静态资源包时，会执行校验与流式解压，并通过原子切换物理目录来保障服务的无缝过渡。同时，Agent 会定时清理不再引用的历史部署包。

> [!TIP]
> 关于不可变部署、目录结构设计、增量拉取和安全防逃逸校验等底层架构与自愈细节，请参阅 [Pages 静态托管设计](../design/pages-design.md)。