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

文档更新

Browse Source
This commit is contained in:
ryan
2026-06-19 14:43:22 +08:00
parent 9eeeb09d2f
commit cc5e53c51e
48 changed files with 226 additions and 4612 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/agent-design.md
+4 -4
View File
@@ -38,13 +38,13 @@ Agent 在生命周期中主要通过 **基于 Token 的自动注册** 和 **心
### 1. 自动注册流程
若 Agent 启动时本地 `agent.json` 的 `access_token` 为空，但配置了 `discovery_token`，将触发自动注册流程：
1. Agent 向控制面 `/api/agent/register` 发送注册请求，携带本地硬件摘要、IP 及主机名。
1. Agent 向控制面 `/api/v1/agent/nodes/register` 发送注册请求，携带本地硬件摘要、IP 及主机名。
2. Server 校验 `discovery_token` 有效后，在数据库生成唯一的 `NodeID` 与专属 `AccessToken`（即 `agent_token`）并返回。
3. Agent 将获取的专用 Token 写入本地配置文件，擦除一次性 `discovery_token`，后续所有的通信均基于专属 `AccessToken` 进行鉴权认证。
### 2. 双通道心跳与同步机制
* **HTTP 轮询通道（兜底与探测）**：Agent 默认按设定的 `heartbeat_interval` 间隔发送 POST 心跳包。上报指标的同时获取当前激活版本的摘要信息（Version & Checksum）。
* **WebSocket 通道（实时通信）**：在 HTTP 心跳成功后，Agent 自动尝试将连接升级为 WebSocket (`/api/agent/ws`)。
* **WebSocket 通道（实时通信）**：在 HTTP 心跳成功后，Agent 自动尝试将连接升级为 WebSocket (`/api/v1/agent/ws`)。
* WS 连接建立后，心跳与指标上报全面转移到 WS 管道，降低网络开销。
* Server 发布或激活新版本时，通过 WS 广播通知 Agent。Agent 收到变更事件后，**立即触发同步流程**，实现秒级配置生效。
* 若 WS 链路因网络问题断开，Agent 自动降级为 HTTP 轮询，并采用指数退避机制尝试重建 WS。
@@ -67,7 +67,7 @@ sequenceDiagram
Note over Agent, Server: HTTP 兜底与 WebSocket 升级
Agent->>Server: 3. 发送 HTTP Heartbeat (上报系统状态与健康度)
Server-->>Agent: 4. 返回 ActiveConfig 摘要及 AgentSettings
Agent->>Server: 5. 发起 WebSocket 升级请求 (/api/agent/ws)
Agent->>Server: 5. 发起 WebSocket 升级请求 (/api/v1/agent/ws)
Server-->>Agent: 6. 升级成功 (建立双向持久实时通道)
end
@@ -171,5 +171,5 @@ graph TD
为保证数据与控制链路的安全边界，Agent 代码编写与二次开发必须严格遵守以下工程约束：
1. **零特权指令通道**：Server 绝对禁止向 Agent 传递任何任意 shell 命令或远程执行脚本（如 exec/eval 等）。所有系统控制原语（如启动、停止、重载、更新）必须硬编码在 Agent 二进制内部。
2. **严格的 Token 过滤与前缀验证**：Agent 侧向 Server 请求资源时，接口端点固定以 `/api/agent/` 为前缀，并强制携带 `X-Agent-Token` 进行签名或令牌核验。
2. **严格的 Token 过滤与前缀验证**：Agent 侧向 Server 请求资源时，接口端点固定以 `/api/v1/agent/` 为前缀，并强制携带 `X-Agent-Token` 进行签名或令牌核验。
3. **节点自治原则**：Agent 须具备完备的离线工作能力。在与 Server 失去连接期间，本地 OpenResty 必须依靠本地已落地的配置保持反向代理服务的绝对正常运行。
docs/design/architecture.md
+4 -5
View File
@@ -70,19 +70,19 @@ OpenResty (Agent, TLS/WAF)
| **OpenResty** | 接收真实流量，执行 WAF 过滤、PoW 防护、Basic Auth 认证与静态/反代服务 | [WAF 设计](./waf-design.md) / [Pages 设计](./pages-design.md) |
| **Relay** | 部署于边缘节点，管理 `frps` 守护进程生命周期，接受心跳派发的穿透中继配置 | [内网穿透设计](./tunnel-design.md) |
| **OpenFlared** | 部署于内网，管理 `frpc` 进程组，向多个 Relay 建立反向隧道，上报连接状态 | [内网穿透设计](./tunnel-design.md) |
| **Frontend** | Next.js 管理界面，提供路由、WAF、证书、节点、穿透隧道和 Pages 项目的可视化管理 | [开发约束](../guideline/Constraints.md) |
---
## 组件架构与分工
### 1. Server (控制面)
`openflare-server` 是 Go 编写的单体控制面：
* 提供管理端 REST API，通过 `OPENFLARE_TOKEN` 请求头鉴权。
仓库根目录的 Go 后端（模块 `github.com/Rain-kl/Wavelet`）是 OpenFlare 控制面，基于 Wavelet 全栈脚手架构建：
* 提供管理端 REST API（`/api/v1/d/*`），通过 **Session Cookie** 鉴权，可选 `X-Access-Token` 访问令牌。
* 边缘节点协议走 `/api/v1/agent|relay|tunnel/*`，分别使用 `X-Agent-Token` / `X-Tunnel-Token` 鉴权。
* 包含配置编译器（Compiler），将数据库中的规则、证书与全局参数统一编译为不可变的配置快照及 OpenResty 物理配置文件文本。
* 存储 Pages 部署 ZIP 包于本地 Artifacts 目录，并向 Agent 提供受控的下载接口。
* 后台集成 Uptime Kuma 监控同步服务，自动为可用站点维护 HTTP 探测任务。
* Go 物理结构采用 `cmd/server` 启动入口、`internal` 私有应用层与根级 `pkg` 共享能力包，跨组件协议类型统一放在 `pkg/protocol`。
* 启动入口为根目录 `main.go` + `internal/cmd/`（`api` / `worker` / `scheduler` / `all`）；OpenFlare 业务在 `internal/apps/openflare/`，边缘协议处理在 `internal/apps/openflare/{agent,relay,flared}/`。
* *详细设计请参阅：[Agent 与发布模型设计](./agent-design.md) 以及 [Uptime Kuma 监控同步设计](./kuma-design.md)*
### 2. Agent (配置落地端)
@@ -165,7 +165,6 @@ OpenResty (Agent, TLS/WAF)
修改系统架构或开发新功能前，请按以下顺序阅读：
1. **[产品边界](./index.md)**：了解 OpenFlare 核心定位与不允许逾越的设计边界。
2. **[开发约束](../guideline/Constraints.md)**：掌握数据模型、API 约定、数据库迁移（Goose）与前端规范。
3. **[Agent 与发布模型](./agent-design.md)**：理解版本快照同步及失败回滚的安全兜底逻辑。
4. **细分领域设计**：
* 穿透相关开发：阅读 [内网穿透隧道设计](./tunnel-design.md)。
docs/design/index.md
+66 -47
View File
@@ -62,39 +62,52 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
## 仓库结构
在贡献代码时，请严格遵守以下物理分层与目录分工，保持代码结构清晰：
OpenFlare 已收敛为**单 monorepo**（Go 模块 `github.com/Rain-kl/Wavelet`）。控制面 Server 与边缘组件（Agent、Relay、OpenFlared）共享同一仓库，业务代码按 Wavelet `internal/apps/` 领域模块组织。
| 路径 | 职责 |
| ---------------------- | ---------------------------------------------------- |
| `cmd` | 各组件的命令行启动入口及主函数（server, agent, relay, flared） |
| `internal` | 各组件的内部业务逻辑，通过子包隔离控制（agent, relay, flared, 核心控制面等） |
| `frontend` | Next.js App Router 管理端前端，由 Go Server 嵌入托管 |
| `pkg` | 跨组件复用的协议类型与通用工具包 |
| `scripts` | 安装、自更新等系统辅助脚本 |
| `docs` | VitePress 文档站、设计基线、开发规范、部署与配置文档 |
| `docker` | 各组件 of Dockerfile 构建文件 |
在贡献代码时，请严格遵守以下物理分层与目录分工：
### 1. Server 分层 (`internal/` / `cmd/server/`)
| 路径 | 职责 |
| --- | --- |
| `main.go` | Server 唯一入口，委派给 `internal/cmd/` |
| `cmd/agent`、`cmd/relay`、`cmd/flared` | 边缘组件 CLI 入口（**不含** Server） |
| `internal/` | 控制面与边缘运行时实现 |
| `frontend/` | Next.js 管理端，构建产物嵌入 Go Server |
| `pkg/` | 跨组件共享库（协议、渲染、GeoIP 等） |
| `scripts/` | Swagger 生成、安装脚本等 |
| `docs/` | VitePress 文档站与设计基线 |
| `docker/` | 各组件 Dockerfile |
| `uploads/`、`data/` | 运行时上传目录与静态数据（`.gitignore` 忽略） |
| 目录 | 职责 |
| ----------------------- | ------------------------------------------------ |
| `cmd/server/` | Server 命令行启动入口及主函数 |
| `internal/controller/` | 参数解析、调用 service、返回响应 |
| `internal/service/` | 业务逻辑、校验、事务编排、配置渲染 |
| `internal/model/` | 纯净实体模型类定义、旧迁移框架兼容与上下文注入 |
| `internal/model/goose/` | goose 迁移提供者、桥接逻辑、注册入口与具体迁移文件 |
| `internal/router/` | 路由注册 |
| `internal/middleware/` | 认证、鉴权、限流、CORS、Turnstile 验证等横切逻辑 |
| `internal/common/` | 配置、全局状态与初始化入口 |
| `internal/job/` | 定时任务（各业务定时逻辑在独立文件中定义，cron.go 仅用于初始化调度） |
| `internal/utils/` | 仅 Server 内部使用的基础能力包，如 ACME、限流、验证码、邮件、安全校验等 |
| `pkg/protocol/` | Server、Relay、OpenFlared 之间共享 of HTTP/WS 协议结构 |
| `pkg/utils/` | 跨组件可复用的纯工具函数 |
| `pkg/geoip`、`pkg/render`、`pkg/wsclient` | 被多个组件复用的 GeoIP、OpenResty 配置渲染与 WebSocket 客户端能力 |
| `upload/` | 运行时本地临时文件上传目录（在 .gitignore 中忽略） |
| `logs/` | 运行时本地日志输出目录（在 .gitignore 中忽略） |
| `docs/` | API 文档（Swagger） |
| `data/` | 静态数据（如 GeoIP 数据库） |
### 1. Server 分层（`main.go` + `internal/`）
| 目录 | 职责 |
| --- | --- |
| `main.go` | Server 启动入口 |
| `internal/cmd/` | Cobra 子命令：`api`、`worker`、`scheduler`、`all`（默认融合模式） |
| `internal/bootstrap/` | 跨模块装配：任务 Handler、推送域事件、进程级初始化 |
| `internal/router/` | HTTP 路由注册与全局中间件 |
| `internal/router/v1/openflare/` | OpenFlare 路由注册器（`register_*.go`） |
| `internal/apps/openflare/` | OpenFlare 控制面业务域（`routers.go` + `logics.go`） |
| `internal/apps/{admin,user,oauth,upload,cap,...}/` | Wavelet 平台能力（用户、认证、任务、推送等） |
| `internal/apps/openflare/{agent,relay,flared}/` | **Server 侧**边缘协议处理器（鉴权、心跳、WS） |
| `internal/model/` | GORM 实体（`openflare_*.go` + 平台模型） |
| `internal/db/migrator/goose/` | goose SQL 迁移（PostgreSQL / SQLite / ClickHouse） |
| `internal/repository/` | 平台域数据访问层 |
| `internal/task/` | Asynq 异步任务（Worker + Scheduler） |
| `internal/config/` | Viper 配置加载 |
| `internal/common/` | 统一 API 响应封装（`response/`） |
| `pkg/protocol/` | Relay / Tunnel 共享 HTTP/WS 协议结构 |
| `pkg/render/`、`pkg/geoip/`、`pkg/wsclient/` | OpenResty 配置渲染、GeoIP、WebSocket 客户端 |
**API 路由前缀：**
| 前缀 | 用途 | 鉴权 |
| --- | --- | --- |
| `/api/v1/d/*` | OpenFlare 管理控制台 API | Session Cookie + 可选 `X-Access-Token` |
| `/api/v1/agent/*` | Agent 节点协议 | `X-Agent-Token` |
| `/api/v1/relay/*` | Relay 中继协议 | `X-Agent-Token` |
| `/api/v1/tunnel/*` | Tunnel 客户端协议 | `X-Tunnel-Token` |
| `/api/v1/admin/*` | Wavelet 平台管理 API | 管理员 Session |
### 2. Agent 模块 (`internal/apps/agent/` / `cmd/agent/`)
@@ -118,24 +131,29 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
### 3. Frontend 分层 (`frontend/`)
| 目录 | 职责 |
| ------------- | -------------------------------------------- |
| `app/` | Next.js App Router 路由、布局、页面组装 |
| `features/` | 按业务域组织的功能模块 |
| `components/` | 跨 feature 复用的 UI 组件 |
| `lib/` | 请求客户端、环境变量、工具函数、常量 |
| `store/` | 少量跨页面 UI 状态管理 |
| `types/` | 共享类型定义 |
| `styles/` | 全局样式 |
| `tests/` | 前端单元测试与集成测试（Vitest、Playwright） |
| `scripts/` | 构建和部署相关脚本 |
| `public/` | 静态资源 |
基于 Wavelet Next.js 脚手架，OpenFlare 业务 UI 以路由共置方式组织在 `app/(main)/` 下。
| 目录 | 职责 |
| --- | --- |
| `app/` | Next.js App Router；`(main)` 控制台、`(auth)` 认证、`(docs)` 文档页 |
| `app/(main)/<domain>/` | 业务页面与域内组件（路由共置） |
| `components/` | 跨域复用 UI（`ui/`、`layout/`、`common/` 等） |
| `lib/services/` | API 服务层：`core/` 基类 + `openflare/` 业务 API |
| `lib/navigation/` | OpenFlare 侧栏导航配置（`openflare-nav.ts`） |
| `lib/theme/` | 主题解析与切换 |
| `contexts/` | 跨页面 UI 状态（用户、通知等） |
| `hooks/`、`lib/hooks/` | 可复用 React Hooks |
| `public/` | 静态资源与主题 CSS |
| `scripts/` | 构建辅助脚本 |
| `proxy.ts` | 开发/生产代理：API 限流与页面鉴权 |
**API 约定**：OpenFlare 业务接口统一前缀 `/api/v1/d/*`，通过 `OpenFlareBaseService` 封装；页面数据获取使用 `@tanstack/react-query`。
### 4. Relay 模块 (`internal/apps/relay/` / `cmd/relay/`)
| 模块 | 职责 |
| ---------------- | ------------------------------------------------ |
| `cmd/` | Relay 命令行启动入口及初始化主函数 |
| `cmd/relay/` | Relay 命令行启动入口及初始化主函数 |
| `internal/apps/relay/config/`| 本地配置文件解析与默认参数初始化 |
| `internal/apps/relay/frps/` | 管理 frps 进程生命周期、端口与 Token 并监控运行 |
| `internal/apps/relay/heartbeat/`| 周期性 HTTP 心跳通信、上报状态并获取更新请求 |
@@ -150,16 +168,18 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
| 模块 | 职责 |
| ---------------- | ------------------------------------------------ |
| `cmd/` | Client 命令行启动入口及初始化主函数 |
| `cmd/flared/` | Client 命令行启动入口及初始化主函数 |
| `internal/apps/flared/config/`| 本地客户端配置加载与解析 |
| `internal/apps/flared/flared/`| 内网穿透客户端的核心调度与状态管理机制 |
| `internal/apps/flared/frpc/` | 热重载/动态生成多 Relay 的 `frpc.toml` 并监控 frpc |
| `internal/apps/flared/frpc/` | 热重载/动态生成多 Relay 的 `frpc_{relayNodeID}.toml` 并监控 frpc |
| `internal/apps/flared/heartbeat/`| 与控制面进行的心跳通信，包含 Token 校验机制 |
| `internal/apps/flared/httpclient/`| 客户端通用 API 通信客户端 |
| `internal/apps/flared/httpclient/`| 客户端通用 API 通信（`/api/v1/tunnel/*`） |
| `internal/apps/flared/sync/` | 增量拉取最新 Tunnel 路由绑定关系、生成快照并应用 |
| `internal/apps/flared/updater/`| 客户端自更新、新版检查与更新落地逻辑 |
| `internal/apps/flared/wsclient/`| 用于实时监听 Server 端隧道配置变更推送的 WS 信道 |
> **说明**：OpenFlared 无独立 `state/` 包；版本与 checksum 由 `frpc/manager.go` 持久化到 `flared-state.json`。
---
## 文档维护原则
@@ -167,6 +187,5 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
* 产品范围或系统边界变化：更新本文档（[产品边界](./index.md)）。
* 系统结构、组件分工变化：更新 [系统架构](./architecture.md)。
* 发布、同步、回滚与 Agent 模型变化：更新 [Agent 与发布模型](./agent-design.md)。
* 开发约束、代码规范、接口约定变化：更新 [开发约束](../guideline/Constraints.md)。
* 部署方式变化：更新 [部署说明](../deployment/deployment.md) 与 README。
* 配置项变化：更新 [配置项参考](../reference/configuration.md)。