tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-06 15:46:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

[优化] 更新文档

Browse Source
This commit is contained in:
ryan
2026-05-31 15:24:02 +08:00
parent 4cb8928e4e
commit a85919fd9e
5 changed files with 108 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/architecture.md
+34 -17
View File
@@ -26,12 +26,12 @@ Origin
## 组件职责
| 组件 | 职责 |
| --- | --- |
| Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
| Agent | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集 |
| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理 |
| Frontend | 管理网站配置、WAF、源站、证书、节点、版本、用户、设置与观测页面 |
| 组件 | 职责 |
| --------- | ---------------------------------------------------------------------- |
| Server | 管理端 UI、管理 API、Agent API、配置渲染、版本发布、数据存储与聚合查询 |
| Agent | 注册、心跳、同步、写入文件、校验、reload、失败回滚、自更新与轻量采集 |
| OpenResty | 接收真实流量，按 OpenFlare 渲染的配置执行 WAF、PoW、认证与反向代理 |
| Frontend | 管理网站配置、WAF、源站、证书、节点、版本、用户、设置与观测页面 |
## Server
@@ -64,13 +64,18 @@ Agent 通过 `openresty_path` 指向的 OpenResty 二进制统一执行校验、
`openflare_server/web` 是正式管理端前端：
* Next.js App Router。
* Next.js 15 App Router。
* React 19。
* TypeScript。
* Tailwind CSS。
* TanStack Query 管理服务端状态。
前端静态导出后由 Go Server 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。
前端采用静态导出模式（`output: 'export'`），导出后由 Go Server 通过 `embed.FS` 托管。所有 API 请求应统一经过 `lib/api/`，并处理 `success/message/data` 响应结构。
Server 集成以下安全特性：
* CORS 中间件：跨域请求保护。
* 速率限制：全局与关键接口限流。
* 会话管理：基于 Cookie/Redis 的会话存储。
## 数据与请求流
@@ -85,14 +90,23 @@ Browser -> Frontend -> /api/* -> controller -> service -> model -> database
### Agent 同步流
```text
Agent heartbeat -> Server 返回激活版本摘要
Agent HTTP heartbeat -> Server 返回激活版本摘要
Agent 发现新版本 -> 拉取配置详情
Agent 写入主配置 / 路由配置 / 证书 / Lua 资源 / WAF 运行时配置
Agent 执行 OpenResty 校验与 reload
Agent 上报应用结果
```
默认启用 WS 连接升级时，Agent 会先通过 HTTP heartbeat 获取设置，随后尝试连接 Agent WebSocket。WS 成功后，周期性状态上报改由 WS 承载；Server 发布或激活版本后会向已连接 Agent 广播激活版本摘要，使 Agent 立即进入既有同步流程。WS 断开或建立失败时，Agent 自动退回 HTTP heartbeat。
**WebSocket 升级流程**（可选，通过 `AgentWebsocketUpgradeEnabled` 选项控制）：
当启用 WebSocket 升级时：
1. Agent 通过 HTTP heartbeat 获取运行配置与设置。
2. Agent 尝试升级连接到 `GET /api/agent/ws`（WebSocket）。
3. WS 连接成功后，周期性状态上报和实时消息由 WebSocket 承载，降低延迟。
4. Server 发布或激活版本后，可向已连接 Agent 立即广播激活版本摘要，使 Agent 立即进入同步流程。
5. 若 WebSocket 断开或建立失败，Agent 自动降级回 HTTP heartbeat，保证可用性。
通过 `OpenRestyWebsocketEnabled` 选项，可在 OpenResty 层面启用或禁用 WebSocket 反向代理支持。
### 反向代理流
@@ -125,16 +139,19 @@ WAF 在 OpenResty `access_by_lua_file` 阶段执行。规则来自当前激活
* `node_health_events`
* `waf_rule_groups`
* `waf_rule_group_bindings`
* `acme_accounts`
* `dns_accounts`
* `geoip_update_configs`
## 关键设计决策
| 决策 | 原因 |
| --- | --- |
| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界 |
| Agent 主动拉取 | Server 不需要 SSH 权限，也不暴露远程命令入口 |
| 全局单激活版本 | 降低 MVP 复杂度，保证所有节点默认一致 |
| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 |
| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 |
| 决策 | 原因 |
| ------------------------------ | --------------------------------------------------------------------------- |
| 完整配置版本，而不是在线 patch | 让预览、激活、历史和回滚有稳定边界 |
| Agent 主动拉取 | Server 不需要 SSH 权限，也不暴露远程命令入口；支持 HTTP 与 WebSocket 双协议 |
| 全局单激活版本 | 降低 MVP 复杂度，保证所有节点默认一致；支持版本预览、历史查询与一键回滚 |
| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 |
| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 |
## 贡献者阅读建议
docs/design/development.md
+1 -7
View File
@@ -6,13 +6,7 @@
## 仓库结构
| 路径 | 职责 |
| --- | --- |
| `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 |
| `openflare_server/web` | Next.js 管理端前端，静态导出后由 Go Server 托管 |
| `openflare_agent` | Go 单体 Agent，运行在节点侧 |
| `scripts` | Agent 安装与卸载脚本 |
| `docs` | VitePress 文档站 |
项目的核心物理目录及各模块（Server、Agent、Frontend 等）的职责分层，详见 [仓库结构](./repository.md)。
## 环境要求
docs/design/index.md
+1 -31
View File
@@ -15,16 +15,7 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队：
OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingress Controller 或多租户云平台。
## 目标用户
| 用户 | 需求 |
| --- | --- |
| 自托管用户 | 快速部署一个可视化 OpenResty 控制面 |
| 内部运维团队 | 管理多个反向代理节点、证书和配置版本 |
| 开发团队 | 为内部服务提供统一入口和基础访问分析 |
| 贡献者 | 在明确边界内修复缺陷、补强测试和改进文档 |
## 当前稳定能力
## 当前能力
| 能力 | 说明 |
| --- | --- |
@@ -58,27 +49,6 @@ OpenFlare 当前不定位为通用日志平台、服务网格、Kubernetes Ingre
| 证书托管 | 为不同域名绑定 TLS 证书 |
| 基础观测 | 查看节点状态、请求聚合、访问分析和健康事件 |
## 核心对象
当前有效实体：
* `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`
* `waf_rule_groups`
* `waf_rule_group_bindings`
## 网站配置约束
docs/design/repository.md
+49 -34
View File
@@ -2,46 +2,61 @@
你会学到：OpenFlare 仓库中 Server、Agent、前端、脚本和文档目录分别负责什么，以及贡献代码时应把逻辑放到哪一层。
| 路径 | 职责 |
| --- | --- |
| `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 |
| `openflare_server/web` | Next.js 15 App Router 管理端前端，静态导出后由 Go Server 托管 |
| `openflare_agent` | Go 单体 Agent，运行在节点侧 |
| `scripts` | Agent 安装、卸载等辅助脚本 |
| `docs` | VitePress 文档站、设计基线、开发规范、部署与配置文档 |
| 路径 | 职责 |
| ---------------------- | ---------------------------------------------------- |
| `openflare_server` | Gin + GORM + SQLite/PostgreSQL 单体控制面 |
| `openflare_server/web` | Next.js 15 App Router 管理端前端，由 Go Server 托管 |
| `openflare_agent` | Go 单体 Agent，运行在节点侧 |
| `scripts` | Agent 安装、卸载等辅助脚本 |
| `docs` | VitePress 文档站、设计基线、开发规范、部署与配置文档 |
| `docs/en` | 英文版文档 |
## Server 分层
| 目录 | 职责 |
| --- | --- |
| `controller/` | 参数解析、调用 service、返回响应 |
| `service/` | 业务逻辑、校验、事务编排、配置渲染 |
| `model/` | 模型定义、数据库版本与迁移 |
| `router/` | 路由注册 |
| `middleware/` | 认证、鉴权、限流等横切逻辑 |
| `common/` | 配置、全局状态与初始化入口 |
| `utils/` | 纯工具函数与通用 helper |
| 目录 | 职责 |
| ------------- | ------------------------------------------------ |
| `controller/` | 参数解析、调用 service、返回响应 |
| `service/` | 业务逻辑、校验、事务编排、配置渲染 |
| `model/` | 模型定义、数据库版本与迁移 |
| `router/` | 路由注册 |
| `middleware/` | 认证、鉴权、限流、CORS、Turnstile 验证等横切逻辑 |
| `common/` | 配置、全局状态与初始化入口 |
| `utils/` | 纯工具函数与通用 helper |
| `job/` | 定时任务（如 SSL 证书续期） |
| `upload/` | 文件上传处理 |
| `docs/` | API 文档（Swagger） |
| `data/` | 静态数据（如 GeoIP 数据库） |
## Agent 模块
| 模块 | 职责 |
| --- | --- |
| `config` | 配置读取与默认值 |
| `heartbeat` | 心跳与版本摘要判断 |
| `sync` | 配置拉取与应用编排 |
| `nginx` / `openresty` | OpenResty 文件写入、校验、reload、启动与回滚 |
| `state` | 本地状态与观测补报缓冲 |
| `httpclient` | Server 通信 |
| `protocol` | Agent API 协议类型 |
| `internal/updater` | Agent 自更新 |
| 模块 | 职责 |
| ---------------- | -------------------------------------------- |
| `config/` | 配置读取与默认值 |
| `heartbeat/` | 心跳与版本摘要判断 |
| `sync/` | 配置拉取与应用编排 |
| `nginx/` | OpenResty 文件写入、校验、reload、启动与回滚 |
| `state/` | 本地状态与观测补报缓冲 |
| `httpclient/` | Server 通信 |
| `wsclient/` | WebSocket 客户端通信 |
| `protocol/` | Agent API 协议类型 |
| `updater/` | Agent 自更新逻辑 |
| `logging/` | 日志处理 |
| `observability/` | 可观测性（指标、链路等） |
| `geoipdata/` | GeoIP 数据处理 |
| `geoipupdate/` | GeoIP 数据更新 |
| `agent/` | 核心 Agent 逻辑与生命周期 |
## Frontend 分层
| 目录 | 职责 |
| --- | --- |
| `app/` | 路由、布局、页面组装 |
| `features/` | 按业务域组织模块 |
| `components/` | 跨 feature 复用组件 |
| `lib/` | 请求客户端、环境变量、工具函数、常量 |
| `store/` | 少量跨页面 UI 状态 |
| `types/` | 共享类型定义 |
| 目录 | 职责 |
| ------------- | -------------------------------------------- |
| `app/` | Next.js App Router 路由、布局、页面组装 |
| `features/` | 按业务域组织的功能模块 |
| `components/` | 跨 feature 复用的 UI 组件 |
| `lib/` | 请求客户端、环境变量、工具函数、常量 |
| `store/` | 少量跨页面 UI 状态管理 |
| `types/` | 共享类型定义 |
| `styles/` | 全局样式 |
| `tests/` | 前端单元测试与集成测试（Vitest、Playwright） |
| `scripts/` | 构建和部署相关脚本 |
| `public/` | 静态资源 |