[新增] 添加 WAF 规则组及其绑定的 API 支持，更新前端页面以集成 WAF 功能

2026-10-05 15:26:36 +08:00 · 2026-05-30 12:16:28 +08:00
parent 290ddd7b51
commit 8300d3ec1c
39 changed files with 2574 additions and 38 deletions
@@ -30,8 +30,8 @@ Origin
 | --- | --- |
 | Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
 | Agent | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集 |
-| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行反向代理 |
-| Frontend | 管理网站配置、源站、证书、节点、版本、用户、设置与观测页面 |
+| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理 |
+| Frontend | 管理网站配置、WAF、源站、证书、节点、版本、用户、设置与观测页面 |

 ## Server

@@ -54,6 +54,7 @@ Server 不直接 SSH 到节点，也不在线修改节点文件。它只保存
 * 周期性 heartbeat，上报状态并获取激活版本摘要。
 * 发现新版本后拉取配置、备份旧文件、写入新文件、校验并 reload。
 * 应用失败时尝试恢复运行并回滚。
+* 维护 WAF GeoIP mmdb，启动时写入内置初始库，并按配置定期更新。

 Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、reload、启动与重启；未配置时默认调用 `openresty`。Docker 部署时，Agent 镜像内置 OpenResty 二进制，仍走同一套二进制控制逻辑。

@@ -84,7 +85,7 @@ Browser -> Frontend -> /api/* -> controller -> service -> model -> database
 ```text
 Agent heartbeat -> Server 返回激活版本摘要
 Agent 发现新版本 -> 拉取配置详情
-Agent 写入主配置 / 路由配置 / 证书 / Lua 资源
+Agent 写入主配置 / 路由配置 / 证书 / Lua 资源 / WAF 运行时配置
 Agent 执行 OpenResty 校验与 reload
 Agent 上报应用结果
 ```
@@ -94,11 +95,13 @@ Agent 上报应用结果
 ### 反向代理流

 ```text
-Client -> OpenResty server block -> named upstream -> Origin
+Client -> OpenResty server block -> WAF Lua -> named upstream -> Origin
 ```

 网站配置是反向代理聚合边界。一条网站配置可绑定多个域名，并共享站点级流量限制、反向代理和缓存配置。

+WAF 在 OpenResty `access_by_lua_file` 阶段执行。规则来自当前激活版本携带的 `waf_config.json`，全局规则组默认生效，网站可叠加自定义规则组。
+
 ## 核心对象

 当前有效实体包括：
@@ -118,6 +121,8 @@ Client -> OpenResty server block -> named upstream -> Origin
 * `node_metric_snapshots`
 * `traffic_analytics_rollups`
 * `node_health_events`
+* `waf_rule_groups`
+* `waf_rule_group_bindings`

 ## 关键设计决策

@@ -148,6 +148,8 @@ tests/
 * `traffic_analytics_rollups`
 * `node_health_events`
 * `options`
+* `waf_rule_groups`
+* `waf_rule_group_bindings`

 通用约束：

@@ -161,6 +163,7 @@ tests/
 * 上游统一使用 named `upstream` + keepalive；单上游如带 base path 或 query，应在 `proxy_pass` 上补回 URI，多上游仅允许纯 `scheme://host[:port]`。
 * 流量限制、反向代理与缓存配置当前都归属站点级 `proxy_routes`。
 * HTTPS 证书绑定必须通过与 `domains` 平行的 `domain_cert_ids` 逐域名保存；未绑定证书的域名不得参与 HTTPS 渲染。
+* WAF 全局规则组默认应用到所有网站，自定义规则组通过 `waf_rule_group_bindings` 绑定到网站配置；发布时必须进入完整版本快照。
 * `config_versions` 必须保存完整快照与渲染结果。
 * 全局同时只能有一个激活版本。
 * 回滚通过重新激活旧版本实现。
@@ -237,12 +240,14 @@ Agent 必须满足：
 * WS 连接升级开启且连接成功时，Agent 可通过 WS 接收激活版本摘要并立即同步；WS 失败或断开必须退回 HTTP heartbeat。
 * 发现新版本时先备份旧文件。
 * 写入主配置、路由配置与必要证书文件。
+* 写入 WAF/PoW 运行时配置，并确保 WAF Lua 资源由 Agent 统一管理。
 * 写入新配置后执行 `openresty -t -c <main_config_path>`，再 reload；reload 发现运行时未启动时允许直接启动 OpenResty。
 * 周期性运行时健康检查不得调用 `openresty -t`，避免健康探针触发 upstream 域名同步解析；应优先请求本地 `openresty_observability_port` 上的 `/openflare/stub_status`，以 HTTP `200 OK` 作为 OpenResty 主进程和 worker 正在提供服务的判断依据。
 * 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty。
 * 回滚后 OpenResty 恢复正常时上报警告；如果本地没有历史主配置可恢复，必须允许写入内置安全兜底配置并拉起对外只监听 `80` 端口、统一返回 `503` 的 OpenResty 运行态；兜底配置仍需保留本地 `stub_status` 健康检查入口。
 * 兜底运行态不得清除失败目标的阻断状态；应用记录必须能体现目标版本失败但 fallback runtime 已启动。存在历史主配置但回滚后仍无法恢复运行时上报失败。
 * 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用。
+* Agent 维护本地 MaxMind mmdb 时，下载或刷新失败只能记录警告，不得阻断心跳、同步、配置应用或 OpenResty 健康检查。

 ## 前端请求、状态与类型

@@ -35,6 +35,7 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre
 | Agent 同步 | 支持注册、心跳、同步、应用结果上报与自更新 |
 | OpenResty 托管 | 管理主配置模板、性能参数、缓存参数与 Lua 资源 |
 | HTTPS/TLS | 托管证书与域名资产，并按域名绑定证书 |
+| WAF | 以全局规则组与网站自定义规则组维护 IP/IP 段、国家级地域黑白名单 |
 | 基础观测 | 聚合节点请求、资源快照、健康事件和访问分析 |
 | 节点管理 | 节点状态、令牌体系、部署与更新链路 |
 | 管理端前端 | 基于 Next.js 的正式管理端 |
@@ -76,6 +77,8 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre
 * `node_metric_snapshots`
 * `traffic_analytics_rollups`
 * `node_health_events`
+* `waf_rule_groups`
+* `waf_rule_group_bindings`

 ## 网站配置约束

@@ -116,6 +119,24 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre
 * 未绑定证书的域名不得被自动带入 HTTPS。
 * 必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散。

+## WAF 约束
+
+WAF 以规则组为配置边界。系统固定一个全局规则组，默认应用到所有网站；网站可叠加多个自定义规则组。
+
+一期支持：
+
+* IP / IP 段白名单与黑名单。
+* 国家级地域白名单与黑名单。
+* 规则组级拦截状态码与响应页面，默认 `418` 与空页面。
+
+判定顺序：
+
+* 白名单是放行例外，任意启用规则组命中白名单即放行。
+* 未命中白名单时继续判断黑名单。
+* 多个黑名单命中时，全局规则组优先，其后按自定义规则组 ID 升序。
+
+地域识别由 Agent 维护节点本地 MaxMind mmdb，OpenResty Lua 在请求路径中读取本地库。GeoIP 依赖不可用时只能跳过地域规则，不得影响 IP 规则与反向代理主链路。
+
 ## 认证源约束

 `auth_sources` 是管理端第三方登录入口的配置对象，当前仅支持 `github` 与 `oidc` 两类。启用后的认证源会显示在登录页。
@@ -17,11 +17,12 @@ Server 发布时必须：
 1. 读取全部启用的 `proxy_routes`。
 2. 读取 Server 侧 OpenResty 主配置、性能参数、缓存参数和必要 Lua 资源。
 3. 读取域名与证书绑定关系。
-4. 渲染完整 OpenResty 配置。
-5. 计算 `checksum`。
-6. 写入 `config_versions`。
-7. 切换激活版本。
-8. 让 Agent 在后续 heartbeat 中发现并应用。
+4. 读取 WAF 全局规则组、自定义规则组与网站绑定关系。
+5. 渲染完整 OpenResty 配置与 WAF 运行时配置。
+6. 计算 `checksum`。
+7. 写入 `config_versions`。
+8. 切换激活版本。
+9. 让 Agent 在后续 heartbeat 中发现并应用。

 版本号格式固定为 `YYYYMMDD-NNN`。

@@ -53,7 +54,7 @@ Agent 发现新版本后会：

 1. 拉取目标版本详情。
 2. 备份旧文件。
-3. 写入主配置、路由配置、证书与必要 Lua 资源。
+3. 写入主配置、路由配置、证书、必要 Lua 资源与 WAF/PoW 运行时配置。
 4. 执行 OpenResty 配置校验。
 5. reload；如果运行时未启动，则尝试用当前配置启动 OpenResty。
 6. 上报成功、警告或失败。
@@ -69,3 +70,4 @@ Agent 发现新版本后会：
 * Agent API 固定使用节点专属 `agent_token`，首次接入可使用 `discovery_token`。
 * Server 不提供远程 shell 或任意命令执行入口。
 * 配置版本必须保存完整快照、渲染结果和 `checksum`。
+* WAF 规则组和网站绑定关系必须随完整配置版本进入快照与 checksum，回滚时不得依赖当前可变 WAF 配置。