feat(pages): pull latest by project and keep a single edge release

Agents now treat pages_project_id as the stable anchor and fetch the control-plane active package via project latest APIs, so activating a deployment updates edges without republishing main config. Local roots use projects/{id}/current, only the newest release is retained after a successful switch, hash/package races retry, and per-project failures no longer block siblings.
2026-09-29 05:56:38 +08:00 · 2026-07-17 17:43:40 +08:00
parent a0fcf9f627
commit ce736e2de4
21 changed files with 871 additions and 219 deletions
@@ -32,7 +32,8 @@ sidebar: false
 - 上传新部署后会按保留策略自动清理超出数量的历史部署包，减少磁盘占用。
 - Agent 在同步 Pages 部署时信任控制面已完成的包校验，不再重复限制文件数与展开体积，仅校验下载完整性并安全解压到本地。
 - 明确 Pages 历史部署保留语义为每个项目最多 N 条（激活必留、其余按从新到旧填充），裁剪失败会记录日志且不回滚已成功上传。
- 主配置版本与 Pages 部署双轨管理：下发给 Agent 的配置会将 Pages 路由重绑定到项目当前激活部署，主配置回滚不再依赖已裁剪的旧部署包。
+- 主配置版本与 Pages 部署双轨管理：Agent 以 Pages 项目 ID 为锚点请求最新激活部署包，项目内切换激活版本无需重新发布主配置即可在边缘自动更新。
+- Agent 边缘仅保留每个 Pages 项目的最新部署包，新包就绪并切换成功后清理旧 release；拉取 latest 时增加 hash 二次校验与重试以降低激活竞态失败；单个项目同步失败不再阻塞同批其它项目。

 ## [v3.3.0] - 2026-07-14

@@ -98,7 +98,7 @@ Agent 对数据面 OpenResty 的管控实现了端到端的闭环，包含配置
 * `certs/`：证书存放目录（文件命名为 `{cert_id}.crt` 和 `{cert_id}.key`）。
 * `waf/` 与 `pow/`：WAF 及防 CC 挑战所需的专用 Lua 运行时脚本。
 * `waf_config.json` 与 `waf_ip_groups.json`：WAF 过滤引擎所需的结构化规则配置文件。
-* `pages_dir`：Pages 静态站点部署目录，默认位于 `data_dir/var/lib/openflare/pages`。当激活配置引用 Pages 部署时，Agent 会下载部署包（zip / tar.gz / tar.xz / tar.bz2 / tar / 7z）、校验下载 checksum、解压到部署 release 目录，并切换 `deployments/{deployment_id}/current` 供 OpenResty `root`/`try_files` 读取。业务侧体积/文件数校验由控制面完成，Agent 信任控制面结果，解压时仅保留本机路径安全防护。
+* `pages_dir`：Pages 静态站点部署目录，默认位于 `data_dir/var/lib/openflare/pages`。当激活配置引用 Pages **项目**时，Agent 按 `project_id` 请求控制面「最新激活包」（hash + package，下载后再校验 hash 防竞态），解压到 `projects/{project_id}/releases/{hash}`，切换 `current` 后**立即删除同项目其它历史 release**（仅保留最新）。项目内切换激活无需重发主配置；多项目对账时单项目失败不阻塞其它项目。

 ### 2. 精细化的重载动作
 1. **备份当前配置**：在写入新文件之前，Agent 会将现有的配置文件复制到 `.backup` 临时目录下，保留完整的现场快照。
@@ -124,7 +124,7 @@ OpenResty (Agent, TLS/WAF)
 * *同步与自愈的精细时序及回滚模型详见：[Agent 与发布模型设计](./agent-design.md)*

 ### 2. 静态托管与 API 代理流
-* 静态资源解压落地于 Agent 节点的 `deployments/{id}/current` 下，OpenResty 通过 `root`/`index`/`try_files` 指令在边缘直接向访客提供极低延迟的静态资源服务。
+* 静态资源解压落地于 Agent 节点的 `projects/{project_id}/current` 下（按项目 latest 拉取，仅保留最新包），OpenResty 通过 `root`/`index`/`try_files` 在边缘直接提供静态资源服务。
 * 当启用 API 代理时，OpenResty 自动根据站点配置的 `api_proxy_path`（如 `/api`）将 API 请求重写并转发（`proxy_pass`）给后端动态接口。
 * *部署包校验、解压逃逸防御及 Nginx 规则渲染详见：[Pages 静态托管设计文档](./pages-design.md)*

@@ -89,11 +89,16 @@ graph TD
 }
 ```

-### 3. 与主配置版本的双轨关系
-* **主配置版本**（`config_versions`）与 **Pages 部署** 是两套独立的版本体系。
-* 快照里记录的 `pages_deployment` 仅反映**发布当时**的激活部署，用于审计与当时渲染结果存档。
-* **运行时**：下发给 Agent 的配置会把各 Pages 路由**重绑定到该项目当前激活部署**（最新包）。主配置回滚/重新激活旧版本时，**不要求**仍能拉到旧 Pages 包，只保证指向当前最新激活部署。
-* 因此 Pages 历史裁剪可以安全删除非激活部署，无需为「主配置回滚到旧 Pages 包」预留存储。
+### 3. 与主配置版本的双轨关系（项目锚点 + latest 拉取）
+* **主配置版本**与 **Pages 部署** 是两套独立的版本体系。
+* 主配置中 Pages 路由的稳定锚点是 **`pages_project_id`（项目 ID）**，不是某次部署 ID。
+* OpenResty `root` 使用项目级路径：`__OPENFLARE_PAGES_DIR__/projects/{project_id}/current`，激活切换时路径不变，无需为换包而重发主配置。
+* Agent 按项目请求「最新激活包」（类似 `github/release/latest`）：
+  * `GET /api/v1/agent/pages/projects/:project_id/latest/hash`
+  * `GET /api/v1/agent/pages/projects/:project_id/latest/package`
+  * 控制面根据该项目**当前激活部署**返回哈希与压缩包；Agent 不关心具体 deployment_id。
+* 因此：在项目内切换激活部署后，**不必发布主配置**；Agent 在周期性对账时轮询 latest hash，发现变化即下载并切换 `current`。
+* 快照中的 `pages_deployment` 字段仍可记录发布时元数据（入口文件、SPA/API 代理等），但不作为 Agent 拉包的版本锁定。

 ---

@@ -119,19 +124,19 @@ graph TD

 Agent 运行在各边缘代理节点上，在应用配置版本前，必须先将 Pages 静态资源“原子”地拉取到节点本地。

-### 1. 校验式增量拉取
-1. Agent 解析激活配置中的 `SourceConfigJSON`，检索出所有 `UpstreamType == "pages"` 的路由引用的部署 `DeploymentID` 和 `Checksum`。
-2. 检查本地部署目录是否存在正确的版本标记文件 `.openflare-pages.json`，且 `Checksum` 匹配。
-3. 若不匹配，通过专属接口 `GET /api/agent/pages/deployments/:id/package` 下载对应的部署包。下载请求头必须携带节点独有的 `X-Agent-Token` 用于 Server 鉴权。
+### 1. 按项目拉取 latest
+1. Agent 从激活主配置中解析 `UpstreamType == "pages"` 的路由，收集稳定锚点 **`pages_project_id`**。
+2. 对每个项目调用 `GET /api/v1/agent/pages/projects/:project_id/latest/hash` 获取控制面当前激活包哈希（类似 latest 指针）。
+3. 若本地 `projects/{project_id}/releases/{hash}` 尚未就绪，再下载 `.../latest/package`。下载后 **再次请求 hash** 与包内容 SHA-256 对齐，避免激活切换造成的竞态；不一致则有限次重试。
+4. 请求头携带节点 `X-Agent-Token`。

-### 2. 安全解压缩与原子切换
-为了保证配置应用过程的“无缝”且能在出错时立即回滚：
-1. Agent 将下载的部署包数据写入临时目录，并重新计算 SHA-256 Checksum。如果与配置指明的 checksum 不符，立即报错并阻断发布流程。
-2. 解压部署包至临时目录 `releases/{checksum}.tmp`。解压支持 zip / tar.* / 7z。**Agent 默认信任控制面**：不再重复校验文件数/体积等业务限额（控制面上传时已完成）；仅做本机落盘安全处理（路径逃逸、软链接拒绝）与下载 checksum 完整性校验。
-3. 解压成功后，写入标记文件 `.openflare-pages.json`。
-4. 清理 `releases/{checksum}` 目录，将整个临时目录重命名为 `releases/{checksum}`。
-5. **原子切换**：建立拷贝当前部署的物理副本到目标位置 `deployments/{deployment_id}/current`。切换前先备份上一版本的 `current`，一旦重载配置失败，Agent 能够快速恢复 `current` 目录并回滚 OpenResty。
-6. **定时清理**：每次配置成功应用后，Agent 自动比对本地部署目录，将所有不活跃的（即未被当前激活版本引用的）历史部署包和文件夹进行物理删除，释放磁盘空间。
+### 2. 安全解压缩、原子切换与只保留最新
+1. 下载字节计算 SHA-256，须与「下载后再次查询」的 latest hash 一致。
+2. 解压至 `projects/{project_id}/releases/{hash}.tmp`（支持 zip / tar.* / 7z）。Agent 信任控制面业务校验，仅做路径逃逸/软链防护。
+3. 写入 `.openflare-pages.json` 后 rename 为 `releases/{hash}`。
+4. **原子切换** `projects/{project_id}/current` 指向新 release（优先 symlink，失败则拷贝）。
+5. **仅当新包已就绪且 current 切换成功后**，删除该项目下其它 `releases/*`（含 `.tmp`），**不保留历史部署包**。边缘节点每个项目永远只保留一份最新内容。
+6. 多项目对账时 **隔离失败**：单个项目失败记日志并继续其它项目，最后汇总返回错误。

 ---

@@ -141,13 +146,13 @@ Agent 运行在各边缘代理节点上，在应用配置版本前，必须先

 ### 1. 静态服务指令渲染
 * **`root` 与 `index`**：
-  Server 根据配置将 `root` 指向 Agent 的 Pages 动态目录占位符 `__OPENFLARE_PAGES_DIR__/deployments/{deployment_id}/current`，并在此基础上追加项目的 `RootDir`。`index` 指向设置的入口文件。
+  Server 将 `root` 指向项目级占位路径 `__OPENFLARE_PAGES_DIR__/projects/{project_id}/current`（可再追加 `RootDir`）。激活切换只换目录内容，路径不变，无需为换包重发主配置。
  ```nginx
  server {
      listen 80;
      server_name myapp.example.com;
      
-      root "/var/lib/openflare/pages/deployments/12/current";
+      root "/var/lib/openflare/pages/projects/3/current";
      index "index.html";
      ...
  }