[文档] 文档更新

2026-10-01 14:46:36 +08:00 · 2026-03-15 17:11:17 +08:00
parent 5858e30af6
commit b2eb4befba
11 changed files with 769 additions and 2232 deletions
@@ -1,108 +1,63 @@
 # OpenFlare 设计基线

-## 1. 文档目的
+本文档定义 OpenFlare `1.0.0` 之后仍然有效的产品边界、系统结构与长期约束。第六版已经完成并并入正式版；过程性设计不再在这里维护。

-本文档只保留 OpenFlare 当前有效的产品边界、系统结构与稳定约束。
+## 1. 产品定位

-当前状态：
+OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。

-* 第一版、第二版、第三版均已完成
-* 前端改造已完成，`openflare_server/web` 新版工程已成为正式基线
-* 第五版（0.5.x）已完成，OpenResty 反代、缓存性能优化与主配置接管已落地
-* 第六版（0.6.x）已立项，目标聚焦节点流量数据采集、访问分析与数据看板升级
-* 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计
-
---
-
-## 2. 产品定位
-
-OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
-
-当前核心能力：
+当前稳定能力包括：

 * 反代规则管理
 * 配置预览、发布、激活与回滚
 * Agent 注册、心跳、同步、应用结果上报
-* Agent 上报 OpenResty 运行健康状态与错误摘要
-* OpenResty 配置写入、校验、reload 与失败回滚
-* Server 向 Agent 下发受限运行指令（当前仅支持 OpenResty 重启）
-* Server 统一管理 OpenResty 主配置模板与性能优化参数
-* 反向代理链路的连接、缓冲、超时、压缩与缓存性能优化
-* HTTPS/TLS 路由支持
-* 证书托管与域名管理
-* 节点侧请求数据采集、随 heartbeat 批量上报与服务端聚合分析
-* 节点系统画像采集与展示，包括操作系统、内核、架构、CPU、内存、磁盘与在线时长
-* 节点实时资源快照、网络流量快照与 24 小时趋势展示
-* 节点健康事件归并与异常摘要展示
-* 管理端总览大盘与节点详情页的数据看板升级
-* 首页总览展示整套系统的可用性、容量、流量、异常与配置追平状态
-* 节点管理、节点专属 `agent_token`、全局 `discovery_token`
-* 配置变更摘要
-* Agent 运行参数下发
-* Agent 自我更新、一键部署、正式版默认更新与手动 preview 更新
-* Server 版本检查、正式版默认自升级、手动 preview 检查升级与手动上传二进制确认升级
-* 新版管理端 UI、主题切换与统一交互框架
+* OpenResty 主配置模板、性能参数与缓存参数托管
+* HTTPS/TLS 与域名资产管理
+* 节点请求聚合、资源快照、健康事件与看板展示
+* 节点管理、令牌体系、部署与更新链路
+* 基于 Next.js 的正式管理端前端

 默认工作方式：

 * 所有节点消费同一份全局激活版本
-* 控制面保存配置与状态，不直接 SSH 管理机器
-* Agent 是节点侧唯一落地入口
+* Server 保存配置与状态，不直接 SSH 管理节点
+* Agent 是节点侧唯一受控落地入口

---
-
-## 3. 范围边界
+## 2. 范围边界

 当前明确不做：

 * 多租户
-* WAF、限流防护平台化、Bot 管理
-* 节点分组、灰度百分比发布、按节点差异化下发
-* Redis、消息队列、对象存储、Prometheus 等新基础设施前置依赖
-* 平台化缓存产品能力、分层缓存、mid-tier
+* CDN SaaS 化能力
+* GeoDNS、全球调度、智能选路
+* WAF、Bot 管理、限流平台化
+* 灰度百分比发布、按节点差异化配置
+* 对象存储、消息队列、Prometheus、ClickHouse、Kafka 等前置基础设施
+* 通用日志检索平台、APM、调用链系统、任意 BI 报表
 * 证书自动签发与自动续期
-* 审批流、审计中台、Purge 平台化能力
 * 平台化抽象对象，如 `zone`、`origin_pool`、`policy`、`deployment`

-第五版边界补充：
+边界补充：

-* 允许在 OpenResty 单节点层面引入受控的代理缓存能力，但只服务于当前反代链路优化，不扩展为独立缓存产品
-* 主配置文件由 Server 统一生成并由 Agent 受控落地，不开放节点侧手改后再回传合并
-* 性能优化参数统一在 Server 配置，不支持按节点分叉不同性能模板
-* 第五版不开放任意自定义 Nginx/OpenResty 片段上传，不提供任意指令执行入口, 但是需要保留拓展能力, 为后续开放准备
-* 允许在管理端提供 OpenResty 主配置模板编辑能力，但模板必须保留 OpenFlare 预留占位符，确保性能参数、证书目录与受管路由 include 继续由 Server 统一渲染
+* OpenResty 代理缓存只作为当前反代链路优化能力存在，不扩展为独立缓存产品
+* 主配置文件由 Server 统一渲染并由 Agent 受控写入，不支持节点侧手工编辑后回传合并
+* 节点观测聚焦运营与运维排障所需的摘要、趋势和受控窗口数据，不提供长期日志托管

-第六版边界补充：
+新增能力如果超出上述边界，先更新本文档，再进入实现。

-* 节点通过 heartbeat 上报最近周期内的请求明细、资源占用快照和网络流量快照，Server 负责入库、聚合与看板展示
-* 第六版参考轻量探针产品的常见数据分层方式，将节点观测拆分为“静态系统画像、周期资源快照、窗口流量聚合、健康异常事件”四类数据，而不是持续向 `nodes` 主表堆叠字段
-* 第六版的数据分析目标聚焦当前反代链路的运营观测：QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码分布，以及节点级 CPU、内存、存储、磁盘 IO、入站/出站流量
-* 首页总览需要能回答“系统整体是否健康、容量是否逼近阈值、流量是否异常、是否存在配置未追平节点”这四类核心问题，可借鉴 WAF/安全大屏的信息组织方式，但不扩展为安全运营平台
-* 世界地图看板仅用于展示节点分布与节点状态，不扩展为 GeoDNS、调度、路由编排或全球流量调度系统
-* 为了支持世界地图看板，允许节点维护低频地图元数据，如位置名、纬度和经度；这类字段仍属于控制面摘要信息，可保留在 `nodes`
-* 节点详情页聚焦系统信息、实时资源、网络流量、24 小时趋势和目标版本，不继续堆积低价值静态字段
-* 在不引入 Prometheus、ClickHouse、Kafka 等新基础设施前提下完成第六版；数据采集、聚合与查询继续落在现有 Server/SQLite 基线内
-* 原始请求数据不作为长期日志平台对外开放；第六版允许保留受控时间窗口内的明细，用于聚合分析、趋势计算、节点详情辅助排查，以及管理端“日志”页面查看最近时间窗口内的访问记录
-* 第六版不做完整 APM、调用链追踪、日志检索平台、任意 SQL 分析接口或自定义报表系统
+## 3. 技术基线

-新增能力超出上述边界时，必须先更新本文档，再进入实现。
-
---
-
-## 4. 技术基线
-
-### 4.1 Server
+### 3.1 Server

 `openflare_server` 继续作为单体控制面：

 * Gin
 * GORM
 * SQLite
-* 现有 OpenFlare 登录体系
+* 现有登录与 Session 体系
 * 托管 `openflare_server/web` 静态构建产物
-* 托管 OpenResty 主配置模板、性能参数与缓存参数

-### 4.2 Agent
+### 3.2 Agent

 `openflare_agent` 继续作为 Go 单体程序：

@@ -110,22 +65,18 @@ OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部
 * 节点本地执行
 * `openresty_path` 优先
 * 未配置 `openresty_path` 时默认使用 Docker OpenResty
-* 生成资源默认落在 `./data`，可由 `data_dir` 覆盖
-* 负责接管 OpenResty 主配置文件与受管 include 文件

-### 4.3 Frontend
+### 3.3 Frontend

-`openflare_server/web` 作为正式管理端前端基线：
+`openflare_server/web` 是正式前端基线：

 * Next.js App Router
 * React 19
 * TypeScript
 * Tailwind CSS
-* 静态导出，继续由 Go Server 托管
+* 静态导出后由 Go Server 托管

---
-
-## 5. 总体架构
+## 4. 总体架构

 ```text
 OpenFlare Server (Gin + SQLite + Web UI)
@@ -135,56 +86,36 @@ OpenFlare Server (Gin + SQLite + Web UI)
 OpenFlare Agent (register / heartbeat / sync / apply / update)
        |
        v
-  Local OpenResty or Docker OpenResty
+Local OpenResty or Docker OpenResty
        |
        v
-      Origin
+Origin
 ```

 职责分工：

-* Server 负责配置、版本、节点、设置、管理端 UI 以及 OpenResty 主配置模板渲染
-* Agent 负责本地落盘、校验、reload、回滚、自更新，不负责维护独立于 Server 的主配置真相
-* Agent 负责本机观测数据的轻量采集、窗口聚合与体积控制，不直接承担长期历史查询职责
+* Server 负责配置、版本、节点、设置、证书、管理端 UI 与聚合查询
+* Agent 负责本地写入、校验、reload、回滚、自更新与轻量采集
 * 发布通过“生成完整版本并激活”完成
 * 历史版本不可变
-* Agent 常规轮询以 heartbeat 为主；heartbeat 响应返回当前激活版本的 `version` 与 `checksum` 摘要，Agent 仅在发现不一致时再拉取完整配置
+* heartbeat 响应返回激活版本摘要，Agent 仅在不一致时拉取完整配置

-第六版观测分层：
-
-* `nodes` 只承担节点身份、接入凭证、配置状态、运行控制状态等控制面字段
-* `nodes` 允许附带少量低频地图展示字段，如位置名、纬度和经度，用于总览世界看板真实落点
-* `node_system_profiles` 承担低频变化的节点系统画像，如操作系统、内核、架构、CPU 型号、逻辑核数、内存总量、磁盘布局、启动时间与 Agent 能力声明
-* `node_metric_snapshots` 承担周期性运行快照，如 CPU、负载、内存、文件系统占用、磁盘 IO、OpenResty 连接数与入站/出站吞吐
-* `node_request_reports` 承担最近心跳窗口内的请求批次或受控明细，不作为长期日志平台
-* `traffic_analytics_rollups` 承担分钟级、小时级的访问聚合结果，支持总览维度、节点维度和域名维度查询
-* `node_health_events` 承担状态变化与异常事件，如节点离线、OpenResty 不健康、配置未追平、资源逼近阈值、错误率突增
-
-第六版 heartbeat 扩展思路：
-
-* `profile`：低频系统画像，仅在首次注册、显著变化或周期性校准时上报
-* `snapshot`：每次 heartbeat 附带的实时资源快照
-* `traffic_report`：当前窗口的请求聚合结果与必要 TopN 分布
-* `health_events`：当前窗口内新增或恢复的异常事件
-
---
-
-## 6. 核心对象
+## 5. 核心对象

 当前有效实体：

-* `proxy_routes`：域名到源站的反向代理规则
-* `config_versions`：完整发布快照与渲染结果
-* `nodes`：节点状态、版本、凭证与 Agent 设置相关状态
-* `node_system_profiles`：节点系统画像与硬件/软件事实信息
-* `apply_logs`：节点应用版本结果
-* `tls_certificates`：托管证书与私钥
-* `managed_domains`：域名资产及默认证书关系
-* `node_request_reports`：节点通过 heartbeat 批量上报的请求明细或请求批次
-* `node_access_logs`：节点最近时间窗口内的受控访问明细，仅保留用于管理端排查的必要字段
-* `node_metric_snapshots`：节点实时资源、磁盘 IO 与网络流量快照
-* `traffic_analytics_rollups`：按时间窗口聚合后的访问指标，用于总览与节点详情看板
-* `node_health_events`：节点运行状态变化、阈值异常与配置偏差事件
+* `proxy_routes`
+* `config_versions`
+* `nodes`
+* `node_system_profiles`
+* `apply_logs`
+* `tls_certificates`
+* `managed_domains`
+* `node_request_reports`
+* `node_access_logs`
+* `node_metric_snapshots`
+* `traffic_analytics_rollups`
+* `node_health_events`

 稳定约束：

@@ -194,24 +125,11 @@ OpenFlare Agent (register / heartbeat / sync / apply / update)
 * `config_versions` 必须保存完整快照、渲染结果与 `checksum`
 * 全局同时只能有一个激活版本
 * 回滚通过重新激活旧版本实现
-* 激活版本中的 OpenResty 渲染结果必须包含主配置与路由配置的统一快照
-* 域名与证书匹配同时支持精确匹配与通配符匹配
-* 节点专属 `agent_token` 必须可立即失效
-* `nodes` 不承担高频观测事实存储；高频运行时字段必须进入快照、聚合或事件表
-* OpenResty 性能优化参数与缓存参数统一由 Server 设置管理，不允许节点侧形成额外配置源
-* OpenResty 主配置模板允许编辑，但必须保留系统要求的占位符，不能绕过结构化参数校验与受管 include 注入
-* Agent 只应用受控主配置文件，不提供任意配置片段拼接入口
-* 节点请求数据必须随 heartbeat 按批次上报，Server 不主动反向拉取节点日志文件
-* 指标看板使用服务端聚合结果，不在前端重复做大规模统计计算
-* 节点资源快照与请求明细必须能按时间排序并绑定节点，保证 24 小时趋势与节点详情可回放
-* 管理端日志页只展示受控保留窗口内的必要访问字段，如原始来源 IP、来源地区、访问域名、路径、命中的节点与响应状态码，不演变为通用日志检索平台
-* 原始请求明细、聚合统计与节点基础状态必须在时间窗口上可对齐
-* 首页总览的系统状态必须基于统一服务端口径生成，不能由多个历史列表接口在前端临时拼装推导
-* 健康事件必须支持“触发中/已恢复”状态，避免首页异常永远累积
+* `nodes` 只承载控制面状态与低频摘要，不承载高频观测事实
+* 指标、趋势和访问分析优先使用服务端聚合结果，而不是前端临时统计
+* 访问明细只保留受控时间窗口，不演变成通用日志平台

---
-
-## 7. 发布模型
+## 6. 发布模型

 标准链路：

@@ -222,96 +140,48 @@ OpenFlare Agent (register / heartbeat / sync / apply / update)
 发布规则：

 1. 读取全部启用的 `proxy_routes`
-2. 读取 Server 侧受管 OpenResty 性能参数与缓存参数
+2. 读取 Server 侧 OpenResty 主配置与结构化参数
 3. 渲染完整 OpenResty 配置
 4. 计算 `checksum`
 5. 写入 `config_versions`
 6. 切换激活版本
-7. Agent 在后续同步中发现并应用
+7. Agent 在后续 heartbeat 中发现并应用

-版本规则：
+版本号格式固定为 `YYYYMMDD-NNN`。

-* 版本号格式：`YYYYMMDD-NNN`
-* 版本不可变
-* 节点只拉取当前激活版本
+## 7. 模块边界

---
-
-## 8. 模块边界
-
-### 8.1 `openflare_server`
+### 7.1 `openflare_server`

 负责：

 * 管理端 UI 与 API
 * Agent API
-* 数据存储
-* 配置渲染
-* OpenResty 主配置模板管理
-* OpenResty 性能参数与缓存参数管理
-* 发布与激活
-* 节点状态与设置管理
+* 配置渲染与版本发布
+* 数据存储与聚合查询
+* OpenResty 主配置模板、性能参数与缓存参数管理

-### 8.2 `openflare_agent`
+### 7.2 `openflare_agent`

 负责：

 * 首次注册与凭证置换
 * 周期性心跳与同步
-* 运行参数接收
-* 采集最近周期内的请求明细、资源占用和网络流量
-* 主配置文件、路由配置与必要证书文件写入
+* 主配置、路由配置、证书与 Lua 资源写入
 * 执行 `openresty -t` / `openresty -s reload`
 * 失败回滚
-* 自我更新
-* 应用结果上报
+* 节点观测采集与结果上报

-### 8.3 `openflare_server/web`
+### 7.3 `openflare_server/web`

 负责：

 * 管理端页面、布局、交互与主题
-* 总览世界地图、访问分析看板与节点详情监控视图
-* 规则、版本、节点、证书、域名、用户、设置、性能等页面
+* 总览、节点详情、规则、版本、节点、证书、域名、用户与设置页面
 * 统一请求层与前端状态管理

---
-
-## 9. 接口域
-
-管理端接口当前覆盖：
-
-* `proxy-routes`
-* `config-versions`
-* `nodes`
-* `apply-logs`
-* `tls-certificates`
-* `managed-domains`
-* `users`
-* `settings`
-* `update`
-
-Agent 接口当前覆盖：
-
-* 注册
-* 心跳
-* 获取激活版本
-* 上报应用结果
-* 通过心跳回传 OpenResty 健康状态并接收受限运行指令
-
-统一约束：
-
-* 管理端与 Agent API 均使用 JSON
-* Agent API 固定放在 `/api/agent/*`
-* Agent 鉴权统一使用 `X-Agent-Token`
-* OpenResty 性能优化相关配置通过现有设置域统一管理，不新增节点直连配置入口
-
---
-
-## 10. 文档维护原则
-
-后续只维护当前有效基线：
+## 8. 文档维护原则

 * 产品范围或系统边界变化时更新本文档
-* 已完成阶段的步骤不再回填为长期计划
+* 已完成阶段不再以“版本计划”形式回填
 * 新阶段开始前，先补设计，再进入实现