[优化] 目录调整

2026-10-02 23:06:36 +08:00 · 2026-06-06 16:08:40 +08:00
parent 314229b7ee
commit 959b134d67
230 changed files with 468 additions and 296 deletions
@@ -16,6 +16,9 @@ sidebar: false

 ## [Unreleased]

+### 变更
+
+- 标准化 Server Go 目录结构，引入 `cmd/server`、`openflare-server/internal` 与根级 `pkg` 分层，并拆分原 `utils` 公共能力包。

 ## [v2.3.3] - 2026-06-06

@@ -82,6 +82,7 @@ OpenResty (Agent, TLS/WAF)
 * 包含配置编译器（Compiler），将数据库中的规则、证书与全局参数统一编译为不可变的配置快照及 OpenResty 物理配置文件文本。
 * 存储 Pages 部署 ZIP 包于本地 Artifacts 目录，并向 Agent 提供受控的下载接口。
 * 后台集成 Uptime Kuma 监控同步服务，自动为可用站点维护 HTTP 探测任务。
+* Go 物理结构采用 `cmd/server` 启动入口、`internal` 私有应用层与根级 `pkg` 共享能力包，跨组件协议类型统一放在 `pkg/protocol`。
 * *详细设计请参阅：[Agent 与发布模型设计](./agent-design.md) 以及 [Uptime Kuma 监控同步设计](./kuma-design.md)*

 ### 2. Agent (配置落地端)
@@ -68,6 +68,7 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具
 | ---------------------- | ---------------------------------------------------- |
 | `openflare-server`     | Gin + GORM + SQLite/PostgreSQL 单体控制面            |
 | `openflare-server/web` | Next.js 15 App Router 管理端前端，由 Go Server 托管  |
+| `pkg`                  | 跨组件复用的协议类型与通用工具包                     |
 | `openflare-agent`      | Go 单体 Agent，运行在节点侧                          |
 | `openflare-relay`      | Tunnel 中继代理，运行在公网边缘管理 frps 进程        |
 | `openflared`           | Tunnel 客户端，运行在内网服务器侧管理 frpc 进程      |
@@ -77,21 +78,25 @@ OpenFlare 适合需要统一管理多台 OpenResty 代理节点的团队，具

 ### 1. Server 分层 (`openflare-server/`)

-| 目录          | 职责                                             |
-| ------------- | ------------------------------------------------ |
-| `controller/`  | 参数解析、调用 service、返回响应                                 |
-| `service/`     | 业务逻辑、校验、事务编排、配置渲染                               |
-| `model/`       | 纯净实体模型类定义、旧迁移框架兼容与上下文注入                   |
-| `model/goose/` | goose 迁移提供者、桥接逻辑、注册入口与具体迁移文件               |
-| `router/`      | 路由注册                                                         |
-| `middleware/`  | 认证、鉴权、限流、CORS、Turnstile 验证等横切逻辑                 |
-| `common/`      | 配置、全局状态与初始化入口                                       |
-| `utils/`       | 纯工具函数与通用 helper                                          |
-| `job/`         | 定时任务（各业务定时逻辑在独立文件中定义，cron.go 仅用于初始化调度） |
-| `upload/`      | 运行时本地临时文件上传目录（在 .gitignore 中忽略）               |
-| `logs/`        | 运行时本地日志输出目录（在 .gitignore 中忽略）                   |
-| `docs/`        | API 文档（Swagger）                                              |
-| `data/`        | 静态数据（如 GeoIP 数据库）                                      |
+| 目录                    | 职责                                             |
+| ----------------------- | ------------------------------------------------ |
+| `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 之间共享的 HTTP/WS 协议结构 |
+| `pkg/utils/`            | 跨组件可复用的纯工具函数                         |
+| `pkg/geoip`、`pkg/render`、`pkg/wsclient` | 被多个组件复用的 GeoIP、OpenResty 配置渲染与 WebSocket 客户端能力 |
+| `upload/`               | 运行时本地临时文件上传目录（在 .gitignore 中忽略） |
+| `logs/`                 | 运行时本地日志输出目录（在 .gitignore 中忽略）   |
+| `docs/`                 | API 文档（Swagger）                              |
+| `data/`                 | 静态数据（如 GeoIP 数据库）                      |

 ### 2. Agent 模块 (`openflare-agent/`)

@@ -76,20 +76,20 @@ Frontend：

 任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号。

-数据库版本号定义在 `openflare-server/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库。
+数据库版本号定义在 `openflare-server/internal/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库。

 每次提升数据库版本号时，必须补充从上一版本升级到新版本的显式迁移方法。迁移方法必须包含升级后的校验逻辑；只有校验通过，才能写入新的数据库版本记录。

-数据库升级统一使用 goose。新的 goose provider、桥接逻辑、注册入口和具体迁移文件必须全部放在 `openflare-server/model/goose` 包下，`openflare-server/model` 根包只保留纯净实体类、旧框架兼容适配和必要的上下文注入。每次新增数据库升级都必须新建一个单独的 Go 文件，文件名使用 `openflare-server/model/goose/goose_<timestamp>_<description>.go`，例如 `openflare-server/model/goose/goose_202606020001_add_node_capabilities_json.go`。迁移文件必须同时包含该版本的 goose migration 构造函数、升级逻辑和校验逻辑；`model/goose/migrations.go` 只能作为注册入口和公共构造工具，禁止把具体迁移逻辑集中堆放在该文件中。
+数据库升级统一使用 goose。新的 goose provider、桥接逻辑、注册入口和具体迁移文件必须全部放在 `openflare-server/internal/model/goose` 包下，`openflare-server/internal/model` 根包只保留纯净实体类、旧框架兼容适配和必要的上下文注入。每次新增数据库升级都必须新建一个单独的 Go 文件，文件名使用 `openflare-server/internal/model/goose/goose_<timestamp>_<description>.go`，例如 `openflare-server/internal/model/goose/goose_202606020001_add_node_capabilities_json.go`。迁移文件必须同时包含该版本的 goose migration 构造函数、升级逻辑和校验逻辑；`model/goose/migrations.go` 只能作为注册入口和公共构造工具，禁止把具体迁移逻辑集中堆放在该文件中。

 执行数据库升级时必须按以下步骤完成：

 1. 判断是否需要升级数据库版本：凡是新增/删除/重命名表、字段、索引、约束、列类型、分表规则，或改变持久化数据语义，都必须升级。
-2. 新增 `openflare-server/model/goose/goose_<timestamp>_<description>.go`，其中 `<timestamp>` 为 goose 版本号。文件头部或迁移构造函数附近必须包含注释，说明本次升级了什么内容，以及为什么需要升级。
-3. 在该文件中实现独立迁移构造函数，并返回通过 `newGORMMigration(...)` 创建的 migration；随后只在 `openflare-server/model/goose/migrations.go` 的 `registeredMigrations(...)` 中新增一条注册项。
+2. 新增 `openflare-server/internal/model/goose/goose_<timestamp>_<description>.go`，其中 `<timestamp>` 为 goose 版本号。文件头部或迁移构造函数附近必须包含注释，说明本次升级了什么内容，以及为什么需要升级。
+3. 在该文件中实现独立迁移构造函数，并返回通过 `newGORMMigration(...)` 创建的 migration；随后只在 `openflare-server/internal/model/goose/migrations.go` 的 `registeredMigrations(...)` 中新增一条注册项。
 4. 在同一个单独迁移文件中写入升级逻辑。可通过 goose `Context` 调用 `ApplyCurrentSchema`、历史 backfill、默认数据初始化等公共能力；复杂数据修复必须显式处理，不得只依赖 `AutoMigrate`。
 5. 在同一个单独迁移文件中写入升级后的校验逻辑。校验至少要覆盖新增表/字段/索引是否存在、关键默认数据是否存在、必要的数据回填是否成功。
-6. 如果新迁移需要新的公共 backfill 或校验辅助函数，优先放在该迁移文件中；只有多个迁移共同复用时，才放到 `openflare-server/model/goose` 包内的公共文件中。不要把新 goose 框架代码放回 `openflare-server/model` 根包。
+6. 如果新迁移需要新的公共 backfill 或校验辅助函数，优先放在该迁移文件中；只有多个迁移共同复用时，才放到 `openflare-server/internal/model/goose` 包内的公共文件中。不要把新 goose 框架代码放回 `openflare-server/internal/model` 根包。
 7. 补充迁移测试：至少覆盖从旧框架终点或上一 goose 版本升级后 schema version、字段/表结构、关键数据回填和校验结果。还应保留旧库从 v15/v17 桥接到 goose 的回归覆盖。

 新包启动后必须先检查数据库当前版本，再按顺序逐步升级到目标版本；禁止跳过中间升级步骤直接写目标版本。
@@ -28,5 +28,5 @@
 ## 4. 下一步行动指南 (Next Steps)
 新接手 AI 进来后应当立即执行的前 3 步命令或编辑操作：
 1. **第一步**：执行 `go test ./controller/...` 确认环境并复现 Fail 异常。
-2. **第二步**：修改 `openflare-server/controller/xxx.go` 中的逻辑以修复该 Fail。
+2. **第二步**：修改 `openflare-server/internal/controller/xxx.go` 中的逻辑以修复该 Fail。
 3. **第三步**：在管理端前端页面调试 xxx 表单的提交是否正常。
@@ -22,9 +22,9 @@
 按模块或组件列出需要修改的物理文件路径及修改点：

 ### 后端 Server
-* #### [NEW] `openflare-server/model/entity.go`
+* #### [NEW] `openflare-server/internal/model/entity.go`
  * 职责：...
-* #### [MODIFY] `openflare-server/service/feature.go`
+* #### [MODIFY] `openflare-server/internal/service/feature.go`
  * 职责：...

 ### 边缘 Agent 与 OpenResty