From a85919fd9e4bc1eb9a7b3101217013fb11c16810 Mon Sep 17 00:00:00 2001 From: ryan Date: Sun, 31 May 2026 15:24:02 +0800 Subject: [PATCH] =?UTF-8?q?[=E4=BC=98=E5=8C=96]=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/architecture.md | 51 ++++++--- docs/design/development.md | 8 +- docs/design/index.md | 32 +----- docs/design/repository.md | 83 +++++++++------ docs/guildline/development-constraints.md | 120 +++++----------------- 5 files changed, 108 insertions(+), 186 deletions(-) diff --git a/docs/design/architecture.md b/docs/design/architecture.md index 16c696bb..21182511 100644 --- a/docs/design/architecture.md +++ b/docs/design/architecture.md @@ -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 复杂度，保证所有节点默认一致；支持版本预览、历史查询与一键回滚 | +| 网站配置聚合多域名 | 支持一个业务站点共享站点级策略，同时允许按域名绑定证书 | +| 观测数据服务端聚合 | 避免前端临时统计造成口径不一致 | ## 贡献者阅读建议 diff --git a/docs/design/development.md b/docs/design/development.md index 8be8f1d6..38f10121 100644 --- a/docs/design/development.md +++ b/docs/design/development.md @@ -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)。 ## 环境要求 diff --git a/docs/design/index.md b/docs/design/index.md index 2760e042..8a361c97 100644 --- a/docs/design/index.md +++ b/docs/design/index.md @@ -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` ## 网站配置约束 diff --git a/docs/design/repository.md b/docs/design/repository.md index d903cb3c..4399c1fe 100644 --- a/docs/design/repository.md +++ b/docs/design/repository.md @@ -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/` | 静态资源 | diff --git a/docs/guildline/development-constraints.md b/docs/guildline/development-constraints.md index dde1a004..9a84fbc9 100644 --- a/docs/guildline/development-constraints.md +++ b/docs/guildline/development-constraints.md @@ -68,110 +68,36 @@ Frontend： * Vitest + Testing Library + Playwright * pnpm -## Server 分层 +## 工程分层约束 -| 目录 | 职责 | -| --- | --- | -| `controller/` | 参数解析、调用 service、返回响应 | -| `service/` | 业务逻辑、校验、事务编排、渲染 | -| `model/` | 模型定义与持久化 | -| `router/` | 路由注册 | -| `middleware/` | 认证、鉴权、限流等横切逻辑 | -| `common/` | 配置、全局状态与初始化入口 | -| `utils/` | 纯工具函数与通用 helper | +各组件和模块（Server、Agent、Frontend）的物理目录分层职责详见 [仓库结构](../design/repository.md)。在此结构下，开发必须遵守以下核心分层规则： -禁止在 `controller/` 堆积业务逻辑，禁止在 `middleware/` 实现业务流程，禁止为简单需求新增平台层抽象。 - -## Agent 分层 - -Agent 保持现有模块边界： - -* `config` -* `heartbeat` -* `sync` -* `openresty` / `nginx` -* `state` -* `httpclient` -* `protocol` -* `internal/updater` - -要求： - -* 每个模块职责单一。 -* 外部命令调用集中封装。 -* 状态落盘与配置落盘分离。 - -## Frontend 分层 - -推荐目录： - -```text -app/ -components/ -features/ -lib/ -hooks/ -store/ -types/ -styles/ -tests/ -``` - -职责约束： - -* `app/`：路由、布局、页面组装。 -* `features/`：按业务域组织模块。 -* `components/`：跨 feature 复用组件。 -* `lib/`：请求客户端、环境变量、工具函数、常量。 -* `store/`：少量跨页面 UI 状态。 -* `types/`：共享类型定义。 - -页面文件只负责获取路由参数、组织页面结构、调用 feature 组件；不应手写复杂 API 细节、复杂表单校验逻辑或维护大量彼此耦合的局部状态。 +* **Server 开发规则**：禁止在 `controller/` 堆积业务逻辑，禁止在 `middleware/` 实现业务流程，禁止为简单需求新增平台层抽象。 +* **Agent 开发规则**：每个模块职责单一，外部命令调用集中封装，状态落盘与配置落盘分离。 +* **Frontend 开发规则**：页面文件只负责获取路由参数、组织页面结构、调用 feature 组件；不应手写复杂 API 细节、复杂表单校验逻辑或维护大量彼此耦合的局部状态。 ## 数据模型规范 -当前有效实体： +在定义和修改 Go/GORM 模型实体时，所有模型的业务边界与设计约束必须严格符合 [产品边界](../design/index.md)。 -* `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` -* `options` -* `waf_rule_groups` -* `waf_rule_group_bindings` +### 1. 当前有效实体 +* **核心配置与反代**：`proxy_routes` (网站配置), `origins` (源站), `config_versions` (配置版本), `tls_certificates` (证书), `managed_domains` (托管域名). +* **节点与状态**：`nodes` (节点), `node_system_profiles` (系统概况), `apply_logs` (应用日志). +* **观测与分析**：`node_request_reports` (请求上报), `node_access_logs` (访问明细), `node_metric_snapshots` (指标快照), `traffic_analytics_rollups` (流量聚合), `node_health_events` (健康事件). +* **系统配置与第三方登录**：`options` (全局参数), `auth_sources` (第三方认证源), `external_accounts` (外部绑定账号). +* **安全与 WAF**：`waf_rule_groups` (WAF规则组), `waf_rule_group_bindings` (网站WAF绑定). -通用约束： - -* 不新增平台化对象，除非设计文档明确要求。 -* `origins` 仅作为可复用源站地址目录，字段保持轻量。 -* `proxy_routes` 以“网站配置”作为聚合边界，必须包含唯一 `site_name` 与非空 `domains` 列表。 -* `proxy_routes.domains` 中的每个域名都必须全局唯一，列表第一项视为主域名。 -* `proxy_routes` 继续允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool`。 -* 遗留 `domain` 字段只能作为 `domains[0]` 的兼容镜像；新代码不得继续以该字段作为唯一业务输入。 -* `proxy_routes` 如关联 `origins`，必须同时保存可直接渲染的 `origin_url`。 -* 上游统一使用 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` 必须保存完整快照与渲染结果。 -* 全局同时只能有一个激活版本。 -* 回滚通过重新激活旧版本实现。 -* `nodes` 只保留控制面状态与低频摘要。 -* 观测数据必须按节点与时间窗口关联，快照与聚合结果采用追加式模型。 -* 原始访问明细必须有受控保留策略。 -* `auth_sources` 仅保存管理端第三方登录源配置，当前支持 `github` 与 `oidc`。 -* `external_accounts` 是第三方账号与本地用户的唯一绑定来源；旧 `users.github_id` 仅用于兼容迁移，不得作为新登录流程的业务输入。 +### 2. 底层数据库技术约束 +在编写或修改模型时，必须严格遵守以下持久化与数据库设计准则： +* **禁止随意引入平台化新实体**：除非 [产品边界](../design/index.md) 设计发生调整并经评审。 +* **业务唯一性保障**： + * `proxy_routes.site_name` 作为业务唯一主标识。 + * `proxy_routes.domains` 中的各域名必须全局唯一，不可跨站点冲突，列表第一项视为主域名。 +* **兼容字段处理**：遗留的 `proxy_routes.domain` 只能作为 `domains[0]` 的只读/兼容镜像，新代码不得以该字段为唯一业务输入。 +* **多上游及 Keepalive**：单上游时应支持 base path/query 并在 `proxy_pass` 中正确补齐 URI；多上游负载均衡时仅允许纯 `scheme://host[:port]`。 +* **证书映射**：证书绑定必须通过逐域名平行的 `domain_cert_ids` 字段精确保存，未绑定证书的域名不得参与 HTTPS 渲染。 +* **版本快照一致性**：`config_versions` 必须保存版本发布时的完整快照及 checksum 校验码，确保渲染结果不可变且全局单激活版本。 +* **外部账户唯一绑定**：第三方登录必须通过 `external_accounts` 映射至本地唯一用户，原 `users.github_id` 仅用于向后兼容迁移，任何新登录流程禁止以此为业务输入。 ## 数据库迁移