mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-04 23:16:37 +08:00
文档更新
This commit is contained in:
ryan
+66
-47
@@ -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)。
|
||||
|
||||
Reference in New Issue
Block a user