mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-06 15:46:37 +08:00
[新增] 更新文档
This commit is contained in:
ryan
+111
-31
@@ -1,57 +1,137 @@
|
||||
# 系统架构
|
||||
|
||||
OpenFlare 由 Server、Agent 与节点本地 OpenResty 组成。
|
||||
你会学到：OpenFlare 的整体架构、Server、Agent、OpenResty 与管理端前端的职责边界，以及一次配置发布从管理端到节点生效的请求流。
|
||||
|
||||
OpenFlare 由 Server、Agent、节点本地 OpenResty 和管理端前端组成。Server 是控制面，Agent 是节点侧唯一受控落地入口，OpenResty 是实际数据面。
|
||||
|
||||
```text
|
||||
OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
|
||||
|
|
||||
| HTTP API / Config Pull
|
||||
v
|
||||
OpenFlare Agent (register / heartbeat / sync / apply / update)
|
||||
|
|
||||
v
|
||||
Local OpenResty or Docker OpenResty
|
||||
|
|
||||
v
|
||||
Browser
|
||||
|
|
||||
| Management UI / API
|
||||
v
|
||||
OpenFlare Server (Gin + GORM + SQLite/PostgreSQL)
|
||||
|
|
||||
| Agent API / heartbeat / config pull
|
||||
v
|
||||
OpenFlare Agent
|
||||
|
|
||||
| write config / openresty -t / reload / rollback
|
||||
v
|
||||
OpenResty binary
|
||||
|
|
||||
| reverse proxy
|
||||
v
|
||||
Origin
|
||||
```
|
||||
|
||||
## 组件职责
|
||||
|
||||
| 组件 | 职责 |
|
||||
| --- | --- |
|
||||
| Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
|
||||
| Agent | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集 |
|
||||
| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行反向代理 |
|
||||
| Frontend | 管理网站配置、源站、证书、节点、版本、用户、设置与观测页面 |
|
||||
|
||||
## Server
|
||||
|
||||
`openflare_server` 是单体控制面：
|
||||
|
||||
* Gin
|
||||
* GORM
|
||||
* SQLite / PostgreSQL
|
||||
* 现有登录与 Session 体系
|
||||
* 认证源与外部账号绑定
|
||||
* 托管 `openflare_server/web` 静态构建产物
|
||||
* Gin 提供 HTTP 服务。
|
||||
* GORM 访问 SQLite 或 PostgreSQL。
|
||||
* 现有登录体系提供管理端 Session。
|
||||
* 认证源与外部账号绑定支持 GitHub OAuth 和标准 OIDC。
|
||||
* Go Server 托管 `openflare_server/web` 静态构建产物。
|
||||
|
||||
Server 负责管理端 UI 与 API、Agent API、配置渲染、版本发布、数据存储与聚合查询。
|
||||
|
||||
认证源登录由 Server 统一处理。管理端配置 `github` 或 `oidc` 认证源后，登录页从 `/api/status` 获取已启用认证源列表；OAuth/OIDC callback 仍回到管理端前端页面，再由前端调用 Server API 完成 code 交换、账号绑定与 Session 建立。
|
||||
Server 不直接 SSH 到节点，也不在线修改节点文件。它只保存控制面状态、生成完整配置版本，并通过 Agent API 让节点主动拉取。
|
||||
|
||||
## Agent
|
||||
|
||||
`openflare_agent` 是 Go 单体程序：
|
||||
|
||||
* 单二进制
|
||||
* 节点本地执行
|
||||
* 优先使用 `openresty_path`
|
||||
* 未配置 `openresty_path` 时默认使用 Docker OpenResty
|
||||
* 单二进制运行在节点侧。
|
||||
* 启动后读取或生成本地节点信息。
|
||||
* 周期性 heartbeat，上报状态并获取激活版本摘要。
|
||||
* 发现新版本后拉取配置、备份旧文件、写入新文件、校验并 reload。
|
||||
* 应用失败时尝试恢复运行并回滚。
|
||||
|
||||
Agent 负责首次注册、周期性心跳、配置同步、文件写入、`openresty -t`、reload、失败回滚、自更新与轻量采集。
|
||||
Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、reload、启动与重启；未配置时默认调用 `openresty`。Docker 部署时，Agent 镜像内置 OpenResty 二进制，仍走同一套二进制控制逻辑。
|
||||
|
||||
## Frontend
|
||||
|
||||
`openflare_server/web` 是正式管理端前端：
|
||||
|
||||
* Next.js App Router
|
||||
* React 19
|
||||
* TypeScript
|
||||
* Tailwind CSS
|
||||
* 静态导出后由 Go Server 托管
|
||||
* Next.js App Router。
|
||||
* React 19。
|
||||
* TypeScript。
|
||||
* Tailwind CSS。
|
||||
* TanStack Query 管理服务端状态。
|
||||
|
||||
前端静态导出后由 Go Server 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。
|
||||
|
||||
## 数据与请求流
|
||||
|
||||
### 管理端请求流
|
||||
|
||||
```text
|
||||
Browser -> Frontend -> /api/* -> controller -> service -> model -> database
|
||||
```
|
||||
|
||||
管理端变更类接口使用 `POST`，只读接口使用 `GET`。成功与失败都返回清晰的 `message`。
|
||||
|
||||
### Agent 同步流
|
||||
|
||||
```text
|
||||
Agent heartbeat -> Server 返回激活版本摘要
|
||||
Agent 发现新版本 -> 拉取配置详情
|
||||
Agent 写入主配置 / 路由配置 / 证书 / Lua 资源
|
||||
Agent 执行 OpenResty 校验与 reload
|
||||
Agent 上报应用结果
|
||||
```
|
||||
|
||||
### 反向代理流
|
||||
|
||||
```text
|
||||
Client -> OpenResty server block -> named upstream -> Origin
|
||||
```
|
||||
|
||||
网站配置是反向代理聚合边界。一条网站配置可绑定多个域名，并共享站点级流量限制、反向代理和缓存配置。
|
||||
|
||||
## 核心对象
|
||||
|
||||
当前有效实体包括 `proxy_routes`、`origins`、`config_versions`、`nodes`、`auth_sources`、`external_accounts`、`apply_logs`、`tls_certificates`、`managed_domains`、`node_request_reports`、`node_access_logs`、`node_metric_snapshots`、`traffic_analytics_rollups` 与 `node_health_events`。
|
||||
当前有效实体包括：
|
||||
|
||||
* `proxy_routes`
|
||||
* `origins`
|
||||
* `config_versions`
|
||||
* `nodes`
|
||||
* `auth_sources`
|
||||
* `external_accounts`
|
||||
* `node_system_profiles`
|
||||
* `apply_logs`
|
||||
* `tls_certificates`
|
||||
* `managed_domains`
|
||||
* `node_request_reports`
|
||||
* `node_access_logs`
|
||||
* `node_metric_snapshots`
|
||||
* `traffic_analytics_rollups`
|
||||
* `node_health_events`
|
||||
|
||||
## 关键设计决策
|
||||
|
||||
| 决策 | 原因 |
|
||||
| --- | --- |
|
||||
| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界 |
|
||||
| Agent 主动拉取 | Server 不需要 SSH 权限，也不暴露远程命令入口 |
|
||||
| 全局单激活版本 | 降低 MVP 复杂度，保证所有节点默认一致 |
|
||||
| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 |
|
||||
| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 |
|
||||
|
||||
## 贡献者阅读建议
|
||||
|
||||
如果要修改架构相关代码，先阅读：
|
||||
|
||||
1. [产品边界](./index.md)
|
||||
2. [发布模型](./release-model.md)
|
||||
3. [开发约束](./development.md)
|
||||
4. [仓库结构](../reference/repository.md)
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 开发约束
|
||||
|
||||
你会学到：OpenFlare 代码修改的准入标准、后端/Agent/前端分层约束、数据模型边界、API 约定、数据库迁移要求和测试交付基线。
|
||||
|
||||
本文档融合原开发规范、前端规范与开发计划，是 OpenFlare `1.0.0` 之后的工程约束入口。
|
||||
|
||||
## 当前结论
|
||||
@@ -47,7 +49,7 @@ Server：
|
||||
* 现有登录体系
|
||||
|
||||
Agent：
|
||||
*
|
||||
|
||||
* 单二进制
|
||||
* 节点本地执行
|
||||
* `openresty_path` 优先
|
||||
|
||||
+37
-2
@@ -1,8 +1,30 @@
|
||||
# 产品边界
|
||||
|
||||
OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景，解决反向代理配置、节点同步、证书托管与基础观测的统一管理问题。
|
||||
你会学到：OpenFlare 是什么、解决什么问题、目标用户是谁、当前稳定能力有哪些，以及哪些设计边界在实现时不能被绕过。
|
||||
|
||||
当前稳定能力包括：
|
||||
OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组织内部运维场景。它解决反向代理配置、节点同步、证书托管、配置发布回滚与基础观测分散管理的问题。
|
||||
|
||||
## 项目定位
|
||||
|
||||
OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队：
|
||||
|
||||
* 希望用管理端维护反向代理网站配置。
|
||||
* 希望每次配置变更都有完整版本、预览、激活与回滚。
|
||||
* 希望节点主动同步配置，而不是由控制面 SSH 到节点执行命令。
|
||||
* 希望在同一系统中管理 TLS 证书、域名资产、节点状态和基础访问分析。
|
||||
|
||||
OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingress Controller 或多租户云平台。
|
||||
|
||||
## 目标用户
|
||||
|
||||
| 用户 | 需求 |
|
||||
| --- | --- |
|
||||
| 自托管用户 | 快速部署一个可视化 OpenResty 控制面 |
|
||||
| 内部运维团队 | 管理多个反向代理节点、证书和配置版本 |
|
||||
| 开发团队 | 为内部服务提供统一入口和基础访问分析 |
|
||||
| 贡献者 | 在明确边界内修复缺陷、补强测试和改进文档 |
|
||||
|
||||
## 当前稳定能力
|
||||
|
||||
| 能力 | 说明 |
|
||||
| --- | --- |
|
||||
@@ -24,6 +46,17 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
|
||||
* Server 保存配置与状态，不直接 SSH 管理节点。
|
||||
* Agent 是节点侧唯一受控落地入口。
|
||||
|
||||
## 典型使用场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
| --- | --- |
|
||||
| 内部服务统一入口 | 把多个内部 HTTP 服务通过统一域名和证书暴露 |
|
||||
| 多节点反代配置同步 | 多台 OpenResty 节点消费同一份激活配置 |
|
||||
| 配置变更审查 | 发布前查看预览或 diff，发布后保留不可变历史 |
|
||||
| 快速回滚 | 重新激活旧版本，让 Agent 拉取并应用 |
|
||||
| 证书托管 | 为不同域名绑定 TLS 证书 |
|
||||
| 基础观测 | 查看节点状态、请求聚合、访问分析和健康事件 |
|
||||
|
||||
## 核心对象
|
||||
|
||||
当前有效实体：
|
||||
@@ -108,6 +141,8 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
|
||||
## 文档维护原则
|
||||
|
||||
* 产品范围或系统边界变化时更新本文档。
|
||||
* 系统结构或模块职责变化时更新 [系统架构](./architecture.md)。
|
||||
* 发布、同步、回滚模型变化时更新 [发布模型](./release-model.md)。
|
||||
* 开发约束、代码规范、接口约定变化时更新 [开发约束](./development.md)。
|
||||
* 部署方式变化时更新 [部署说明](../guide/deployment.md) 与 README。
|
||||
* 配置项变化时更新 [配置项参考](../reference/configuration.md)。
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
# 发布模型
|
||||
|
||||
你会学到：OpenFlare 为什么以完整配置版本为发布单位，发布、激活、Agent 应用和回滚分别如何工作。
|
||||
|
||||
OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改节点配置。
|
||||
|
||||
标准链路：
|
||||
|
||||
```text
|
||||
修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
|
||||
修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
|
||||
```
|
||||
|
||||
## 发布规则
|
||||
@@ -13,25 +15,57 @@ OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改
|
||||
Server 发布时必须：
|
||||
|
||||
1. 读取全部启用的 `proxy_routes`。
|
||||
2. 读取 Server 侧 OpenResty 主配置与结构化参数。
|
||||
3. 渲染完整 OpenResty 配置。
|
||||
4. 计算 `checksum`。
|
||||
5. 写入 `config_versions`。
|
||||
6. 切换激活版本。
|
||||
7. 让 Agent 在后续 heartbeat 中发现并应用。
|
||||
2. 读取 Server 侧 OpenResty 主配置、性能参数、缓存参数和必要 Lua 资源。
|
||||
3. 读取域名与证书绑定关系。
|
||||
4. 渲染完整 OpenResty 配置。
|
||||
5. 计算 `checksum`。
|
||||
6. 写入 `config_versions`。
|
||||
7. 切换激活版本。
|
||||
8. 让 Agent 在后续 heartbeat 中发现并应用。
|
||||
|
||||
版本号格式固定为 `YYYYMMDD-NNN`。
|
||||
|
||||
## 预览与发布
|
||||
|
||||
预览和 diff 是只读能力，不产生发布记录。
|
||||
|
||||
发布会生成新的完整配置版本。版本必须包含足够信息，让未来回滚时可以基于历史快照重新应用，而不依赖当前可变配置。
|
||||
|
||||
## 激活版本
|
||||
|
||||
全局同时只能有一个激活版本。当前不做按节点分组的差异化版本。
|
||||
|
||||
Agent 通过 heartbeat 获取激活版本摘要；当远端版本或 checksum 与本地状态不一致时，Agent 才进入同步流程。
|
||||
|
||||
## 不可变历史
|
||||
|
||||
历史版本不可变。回滚不是修改旧版本，而是重新激活旧版本。
|
||||
|
||||
全局同时只能有一个激活版本，当前不做按节点分组的差异化版本。
|
||||
这样做的结果是：
|
||||
|
||||
* 每个版本都可以追溯。
|
||||
* 回滚链路与普通发布应用链路一致。
|
||||
* Agent 不需要理解“反向 patch”，只需要应用一个目标版本。
|
||||
|
||||
## Agent 应用策略
|
||||
|
||||
Agent 发现新版本后会备份旧文件，写入主配置、路由配置、证书与必要 Lua 资源，再执行配置校验和 reload。
|
||||
Agent 发现新版本后会：
|
||||
|
||||
1. 拉取目标版本详情。
|
||||
2. 备份旧文件。
|
||||
3. 写入主配置、路由配置、证书与必要 Lua 资源。
|
||||
4. 执行 OpenResty 配置校验。
|
||||
5. reload 或重建 Docker OpenResty。
|
||||
6. 上报成功、警告或失败。
|
||||
|
||||
如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告，回滚后仍无法恢复运行时上报失败。
|
||||
|
||||
某个目标 `version + checksum` 一旦应用失败并回退，Agent 会在本地状态中阻断该目标重复应用。只有远端激活版本或 checksum 发生变化，才允许再次尝试。
|
||||
|
||||
## 设计约束
|
||||
|
||||
* 发布必须读取全部启用的网站配置，而不是只渲染本次修改对象。
|
||||
* 回滚通过重新激活旧版本实现，不修改历史版本。
|
||||
* Agent API 固定使用节点专属 `agent_token`，首次接入可使用 `discovery_token`。
|
||||
* Server 不提供远程 shell 或任意命令执行入口。
|
||||
* 配置版本必须保存完整快照、渲染结果和 `checksum`。
|
||||
|
||||
Reference in New Issue
Block a user