mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-30 14:26:36 +08:00
feat(pages): configurable limits, multi-format packages, and dual versioning
Make Pages package size and history retention system-configurable, support zip/tar.gz/tar.xz/tar.bz2/tar/7z uploads, prune history with clear keep-N semantics, and rebind agent config to the live active Pages deployment so main-config rollback never depends on pruned packages.
This commit is contained in:
ryan
@@ -21,6 +21,19 @@ sidebar: false
|
||||
|
||||
## [unreleased]
|
||||
|
||||
### 新增
|
||||
|
||||
- Pages 现支持上传 zip、tar.gz、tar.xz、tar.bz2、tar、7z 等常用压缩格式的部署包。
|
||||
- 管理员可在运维设置中配置 Pages 部署包大小上限与每个项目的历史部署保留数量。
|
||||
|
||||
### 变更
|
||||
|
||||
- Pages 部署包上传体积限制改为系统动态配置，默认仍为 100 MiB，可按环境调整。
|
||||
- 上传新部署后会按保留策略自动清理超出数量的历史部署包，减少磁盘占用。
|
||||
- Agent 在同步 Pages 部署时信任控制面已完成的包校验，不再重复限制文件数与展开体积，仅校验下载完整性并安全解压到本地。
|
||||
- 明确 Pages 历史部署保留语义为每个项目最多 N 条（激活必留、其余按从新到旧填充），裁剪失败会记录日志且不回滚已成功上传。
|
||||
- 主配置版本与 Pages 部署双轨管理：下发给 Agent 的配置会将 Pages 路由重绑定到项目当前激活部署，主配置回滚不再依赖已裁剪的旧部署包。
|
||||
|
||||
## [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、校验 checksum、解压到部署 release 目录，并切换 `deployments/{deployment_id}/current` 供 OpenResty `root`/`try_files` 读取。
|
||||
* `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 信任控制面结果，解压时仅保留本机路径安全防护。
|
||||
|
||||
### 2. 精细化的重载动作
|
||||
1. **备份当前配置**：在写入新文件之前，Agent 会将现有的配置文件复制到 `.backup` 临时目录下，保留完整的现场快照。
|
||||
|
||||
@@ -26,7 +26,7 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
|
||||
| **配置版本控制** | 支持全局单一激活版本的预览、发布、不可变快照历史与秒级一键回滚 | [Agent 与发布模型](./agent-design.md) |
|
||||
| **WAF 安全防护** | 支持可视化 DAG 编排规则、手动/自动/订阅型 IP 组、GeoIP 匹配与 PoW CC 防护 | [WAF 设计](./waf-design.md) / [WAF 可编排规则设计](./waf-orchestration-design.md) / [WAF 使用指南](../guide/waf-usage.md) |
|
||||
| **内网穿透** | 通过中继节点（Relay）与内网客户端（OpenFlared），反向穿透暴露内网 Web 服务 | [内网穿透设计](./tunnel-design.md) / [穿透使用指南](../guide/tunnel-usage.md) |
|
||||
| **Pages 静态托管** | 直接上传前端 zip 包，由边缘节点拉取并由 OpenResty 本地服务，支持 API 反代与 SPA Fallback | [Pages 静态托管设计](./pages-design.md) |
|
||||
| **Pages 静态托管** | 直接上传前端压缩包（zip / tar.gz / tar.xz / 7z 等），由边缘节点拉取并由 OpenResty 本地服务，支持 API 反代与 SPA Fallback | [Pages 静态托管设计](./pages-design.md) |
|
||||
| **TLS 证书自动续期** | 将证书显式绑定到 Zone 域名，并通过 ACME 协议向 Let's Encrypt 申请/续期证书 | [Zone 与域名资源设计](./zone-design.md) |
|
||||
| **多节点监控与观测** | 收集节点资源快照、健康事件，聚合请求指标与访问日志明细 | [系统架构](./architecture.md) |
|
||||
|
||||
|
||||
+22
-13
@@ -19,11 +19,12 @@
|
||||
## 核心功能
|
||||
|
||||
Pages 静态托管子系统包含以下核心能力：
|
||||
* **Direct Upload 部署模式**：支持直接上传预构建的 `.zip` 静态资源包，省去复杂的 Git 集成和构建环境依赖。
|
||||
* **不可变部署快照**：每次上传产生一个带唯一 ID 和 SHA-256 Checksum 的不可变部署记录。历史包永久保留，支持随时激活和回滚。
|
||||
* **Direct Upload 部署模式**：支持直接上传预构建的静态资源压缩包（`zip`、`tar.gz`、`tar.xz`、`tar.bz2`、`tar`、`7z`），省去复杂的 Git 集成和构建环境依赖。
|
||||
* **不可变部署快照**：每次上传产生一个带唯一 ID 和 SHA-256 Checksum 的不可变部署记录。支持按系统配置保留最近 N 个历史部署，并可随时激活和回滚。
|
||||
* **SPA Fallback 支持**：支持对单页应用（SPA）进行 Fallback 路由配置，请求找不到静态文件时自动重定向到入口文件。
|
||||
* **内置 API 反代服务**：支持在 Pages 规则内一键启用 API 代理，消除跨域问题，将请求转发给指定的后端服务。
|
||||
* **安全包校验与解压缩**：内置 Zip-Slip 路径逃逸防御、防软链接劫持、文件大小/数量硬上限控制，保障节点物理安全。
|
||||
* **安全包校验与解压缩**：内置路径逃逸防御、防软链接劫持、文件大小/数量上限与可配置上传包体积控制，保障节点物理安全。
|
||||
* **可配置限额**：管理员可在运维设置中调整「部署包大小上限」与「历史部署保留数」。
|
||||
|
||||
---
|
||||
|
||||
@@ -40,7 +41,7 @@ graph TD
|
||||
|
||||
%% 控制流与心跳
|
||||
Server[OpenFlare Server 控制面] <-->|Agent API / Heartbeat| Agent[openflare-agent 进程]
|
||||
Server -.->|5. 存储 ZIP 部署包| LocalStore[(Server 本地存储)]
|
||||
Server -.->|5. 存储部署包| LocalStore[(Server 本地存储)]
|
||||
|
||||
Agent -->|1. 发现新版本| Server
|
||||
Agent -->|2. 下载部署包| Server
|
||||
@@ -88,21 +89,29 @@ graph TD
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 与主配置版本的双轨关系
|
||||
* **主配置版本**（`config_versions`）与 **Pages 部署** 是两套独立的版本体系。
|
||||
* 快照里记录的 `pages_deployment` 仅反映**发布当时**的激活部署，用于审计与当时渲染结果存档。
|
||||
* **运行时**：下发给 Agent 的配置会把各 Pages 路由**重绑定到该项目当前激活部署**（最新包）。主配置回滚/重新激活旧版本时，**不要求**仍能拉到旧 Pages 包，只保证指向当前最新激活部署。
|
||||
* 因此 Pages 历史裁剪可以安全删除非激活部署，无需为「主配置回滚到旧 Pages 包」预留存储。
|
||||
|
||||
---
|
||||
|
||||
## Server 端 (控制面) 职责与生命周期
|
||||
|
||||
### 1. ZIP 包安全校验与分析
|
||||
为了避免不可信的用户上传恶意压缩包攻击服务器，控制面在 `UploadPagesDeployment` 时执行严格的流式校验：
|
||||
* **大小限制**：ZIP 压缩包不得超过 25 MiB（保守的 V1 默认值），且展开后的解压总体积不得超过 100 MiB。
|
||||
### 1. 部署包安全校验与分析
|
||||
为了避免不可信的用户上传恶意压缩包攻击服务器，控制面在 `UploadDeployment` 时执行严格校验：
|
||||
* **格式支持**：`zip`、`tar.gz` / `tgz`、`tar.xz` / `txz`、`tar.bz2` / `tbz2`、`tar`、`7z`。
|
||||
* **大小限制**：压缩包体积由系统配置 `pages_max_package_size_mb` 控制（默认 100 MiB，范围 1～2048）；展开后总体积上限为「包大小 × 4」且不低于 100 MiB。
|
||||
* **数量限制**：压缩包中包含的静态文件总数不得超过 1,000 个。
|
||||
* **软链接阻断**：遍历 ZIP 文件，一旦检测到任何软链接 (`os.ModeSymlink`)，立即抛出错误并拒绝上传，防御软链接劫持攻击。
|
||||
* **Zip-Slip 防御**：对每个压缩文件路径进行 `Clean` 并检查是否包含 `..` 或以 `/` 开头，防御目录跨越漏洞，防止写入系统敏感路径。
|
||||
* **入口文件校验**：项目指定的入口文件（例如 `index.html`，可在 `project.RootDir` 下）必须在 ZIP 压缩包中存在，否则拒绝上传。
|
||||
* **公共根目录去噪**：许多打包工具（如 GitHub 导出的 zip）会包含一个多余的主文件夹作为公共根前缀。控制面自动探测公共根前缀并将其安全剥离。
|
||||
* **软链接阻断**：遍历归档文件，一旦检测到任何软链接，立即抛出错误并拒绝上传，防御软链接劫持攻击。
|
||||
* **路径逃逸防御**：对每个压缩文件路径进行 `Clean` 并检查是否包含 `..` 或以 `/` 开头，防御目录跨越漏洞，防止写入系统敏感路径。
|
||||
* **入口文件校验**：项目指定的入口文件（例如 `index.html`，可在 `project.RootDir` 下）必须在部署包中存在，否则拒绝上传。
|
||||
* **公共根目录去噪**：许多打包工具会包含一个多余的主文件夹作为公共根前缀。控制面自动探测公共根前缀并将其安全剥离。
|
||||
* **历史保留**：系统配置 `pages_max_history_count`（默认 20，0 表示不限制）在每次上传成功后执行裁剪。语义为：**每个项目最多保留 N 条部署**；当前激活部署始终保留；其余名额按部署 ID 从新到旧填充；超出的非激活部署连同文件清单与存储对象一并删除。上传已成功时裁剪失败只记日志、不回滚上传；并发上传下可能短暂超过 N，后续上传的裁剪会收敛回 N。主配置版本回滚不依赖旧 Pages 包（见上节双轨关系）。
|
||||
|
||||
### 2. 部署包存储规划
|
||||
控制面仅将 zip 文件存储在本地存储目录 `artifacts/{project_slug}/{checksum}.zip`，并在数据库中记录路径和清单。**大体积静态包不写入 config_versions 记录和任何配置推送通道**，以保障控制面数据同步的轻量与高效。
|
||||
控制面通过统一上传框架（`upload.Ingest`）存储原始部署包，并在数据库中记录 `upload_id` 与文件清单。**大体积静态包不写入 config_versions 记录和任何配置推送通道**，以保障控制面数据同步的轻量与高效。
|
||||
|
||||
---
|
||||
|
||||
@@ -118,7 +127,7 @@ Agent 运行在各边缘代理节点上，在应用配置版本前，必须先
|
||||
### 2. 安全解压缩与原子切换
|
||||
为了保证配置应用过程的“无缝”且能在出错时立即回滚：
|
||||
1. Agent 将下载的部署包数据写入临时目录，并重新计算 SHA-256 Checksum。如果与配置指明的 checksum 不符，立即报错并阻断发布流程。
|
||||
2. 解压部署包至临时目录 `releases/{checksum}.tmp`。解压时同样执行 Zip-Slip 目录跨越和软链接校验防御。
|
||||
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。
|
||||
|
||||
Reference in New Issue
Block a user