mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-04 07:06:36 +08:00
update doc
This commit is contained in:
ryan
@@ -1,188 +0,0 @@
|
||||
# 开发约束
|
||||
|
||||
OpenFlare 代码修改的准入标准、后端/Agent/前端分层约束、数据模型边界、API 约定、数据库迁移要求和测试交付基线。
|
||||
|
||||
## 变更准入
|
||||
|
||||
新需求进入实现前，按以下顺序判断：
|
||||
|
||||
1. 是否符合 [产品边界](../design/index.md)。
|
||||
2. 是否符合本文档的后端、Agent 与前端约束。
|
||||
3. 是否会破坏现有发布、同步、回滚或升级主链路。
|
||||
4. 是否需要同步更新部署、配置、README 或文档站页面。
|
||||
|
||||
如果需求超出边界或引入新基础设施，应先更新设计文档，再开始实现。
|
||||
|
||||
## 技术基线
|
||||
|
||||
Server：
|
||||
|
||||
* Go 1.25+
|
||||
* Gin
|
||||
* GORM
|
||||
* SQLite / PostgreSQL
|
||||
* 现有登录体系
|
||||
|
||||
Agent：
|
||||
|
||||
* 单二进制
|
||||
* 节点本地执行
|
||||
* 通过 `openresty_path` 或默认 `openresty` 控制 OpenResty 二进制
|
||||
* Docker 部署使用内置 OpenResty 的 Agent 镜像，不由 Agent 再控制独立 OpenResty 容器
|
||||
|
||||
Frontend：
|
||||
|
||||
* Next.js 15 App Router
|
||||
* React 19
|
||||
* TypeScript 5
|
||||
* Tailwind CSS 4
|
||||
* TanStack Query
|
||||
* React Hook Form + Zod
|
||||
* Zustand 仅用于轻量客户端状态
|
||||
* ESLint + Prettier
|
||||
* Vitest + Testing Library + Playwright
|
||||
* pnpm
|
||||
|
||||
## 工程分层约束
|
||||
|
||||
各组件和模块（Server、Agent、Frontend）的物理目录分层职责详见 [仓库结构](../design/index.md#仓库结构)。在此结构下，开发必须遵守以下核心分层规则：
|
||||
|
||||
* **Server 开发规则**：
|
||||
* 禁止在 `controller/` 堆积业务逻辑，禁止在 `middleware/` 实现业务流程，禁止为简单需求新增平台层抽象。
|
||||
* **定时任务开发规则**：禁止将不同业务模块（如 Uptime Kuma 整合、WAF IP 同步等）的定时任务具体执行逻辑与状态堆积在单个 `cron.go` 文件中。各模块对应的定时任务结构体和运行逻辑必须在独立的 Go 文件中定义，`cron.go` 只允许承担统一注册、初始化与调度器启停的职责。
|
||||
* **Agent 开发规则**：每个模块职责单一，外部命令调用集中封装，状态落盘与配置落盘分离。
|
||||
* **Frontend 开发规则**：页面文件只负责获取路由参数、组织页面结构、调用 feature 组件；不应手写复杂 API 细节、复杂表单校验逻辑或维护大量彼此耦合的局部状态。
|
||||
|
||||
## 数据模型规范
|
||||
|
||||
在定义和修改 Go/GORM 模型实体时，所有模型的业务边界与设计约束必须严格符合 [产品边界](../design/index.md)。
|
||||
|
||||
### 1. 当前有效实体
|
||||
* **核心配置与反代**：`proxy_routes` (网站配置), `origins` (源站), `config_versions` (配置版本), `tls_certificates` (证书), `managed_domains` (托管域名).
|
||||
* **Pages 静态托管**：`pages_projects` (Pages 项目), `pages_deployments` (不可变部署), `pages_deployment_files` (部署文件清单).
|
||||
* **节点与状态**：`nodes` (节点), `node_system_profiles` (系统概况), `apply_logs` (应用日志).
|
||||
* **内网穿透**：`tunnels` (隧道客户端), `tunnel_tokens` (隧道认证令牌，可选持久化).
|
||||
* **观测与分析**：`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_ip_groups` (WAF IP组), `waf_rule_group_bindings` (网站WAF绑定).
|
||||
|
||||
### 2. 底层数据库技术约束
|
||||
|
||||
在编写或修改模型时，必须严格遵守以下持久化与数据库设计准则：
|
||||
|
||||
* **禁止随意引入平台化新实体**：除非 [产品边界](../design/index.md) 设计发生调整并经评审。
|
||||
|
||||
## 数据库迁移
|
||||
|
||||
任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号。
|
||||
|
||||
数据库版本号定义在 `openflare-server/internal/model`，不得只依赖 `AutoMigrate` 隐式升级存量数据库。
|
||||
|
||||
每次提升数据库版本号时，必须补充从上一版本升级到新版本的显式迁移方法。迁移方法必须包含升级后的校验逻辑；只有校验通过，才能写入新的数据库版本记录。
|
||||
|
||||
数据库升级统一使用 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/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/internal/model/goose` 包内的公共文件中。不要把新 goose 框架代码放回 `openflare-server/internal/model` 根包。
|
||||
7. 补充迁移测试：至少覆盖从旧框架终点或上一 goose 版本升级后 schema version、字段/表结构、关键数据回填和校验结果。还应保留旧库从 v15/v17 桥接到 goose 的回归覆盖。
|
||||
|
||||
新包启动后必须先检查数据库当前版本，再按顺序逐步升级到目标版本；禁止跳过中间升级步骤直接写目标版本。
|
||||
|
||||
空库初始化可以直接建立当前版本结构，但初始化完成后仍必须执行同版本校验，并落库当前数据库版本。
|
||||
|
||||
如果迁移失败或校验失败，启动流程必须中止，确保数据库能够回滚。涉及数据库版本变更的提交，必须补充对应的迁移测试或等效回归测试。
|
||||
|
||||
## API 与鉴权
|
||||
|
||||
管理端与 Agent/Relay/Client API 统一使用 JSON。成功与失败都必须返回清晰 `message`：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
约定：
|
||||
|
||||
* Agent API 固定放在 `/api/agent/*`，使用 `X-Agent-Token` 认证（节点专属 token）。
|
||||
* **Relay API** 固定放在 `/api/relay/*`，使用 `X-Agent-Token` 认证（同 TunnelRelay 节点）。
|
||||
- Server 通过 token + `/api/relay/*` 路径区分 Relay 请求。
|
||||
* **Tunnel Client API** 固定放在 `/api/flared/*`，使用 `X-Tunnel-Token` 认证（独立的 tunnel_token）。
|
||||
- OpenFlared 使用 `tunnel_token` 与 Server 通信，独立于 Agent 认证体系。
|
||||
* **Admin Tunnel 管理 API** - `/api/tunnels/*`。
|
||||
- CRUD tunnel 实体（创建、查询、更新、删除）。
|
||||
- Token 管理（生成、轮换）。
|
||||
- 强制同步（触发 Client 立即拉取新配置）。
|
||||
* **Admin Pages 管理 API** - `/api/pages/*`。
|
||||
- CRUD Pages 项目，包括 SPA fallback 启用状态与回退路径。
|
||||
- 上传 zip 部署包、查看部署历史、激活部署、删除非激活部署。
|
||||
* **Agent Pages 下载 API** - `/api/agent/pages/*`，使用 `X-Agent-Token` 认证。
|
||||
- Agent 仅能按激活配置引用的部署 ID 拉取静态部署包，不提供任意文件读取或远程命令入口。
|
||||
* 管理端变更类接口统一使用 `POST`；只读接口使用 `GET`。
|
||||
* 管理端登录成功后返回用户 token；管理端 API 只允许从 `OPENFLARE_TOKEN` 请求头读取登录凭证，不得通过 Cookie Session 放行。
|
||||
* `/api/status` 只能返回已启用认证源的公开字段，不得返回 Client Secret。
|
||||
* 系统仅单租户使用, 不得创建用户。
|
||||
* Agent/Relay/Client 正式请求统一使用对应的专属 token（`agent_token` / `relay_token`（即 agent_token） / `tunnel_token`）。
|
||||
* 首次接入 Agent 可使用全局 `discovery_token`；首次接入 Client 由 Server 生成 tunnel_token，直接用于部署命令。
|
||||
* Agent/Relay 请求头统一使用 `X-Agent-Token`；Client 请求头统一使用 `X-Tunnel-Token`。
|
||||
|
||||
## 前端请求、状态与类型
|
||||
|
||||
所有 API 请求必须统一经过 `lib/api/`：
|
||||
|
||||
* 统一处理 `success/message/data` 响应结构。
|
||||
* 统一处理鉴权失效、网络异常和通用错误消息。
|
||||
* 统一维护资源接口与请求路径。
|
||||
|
||||
状态分层：
|
||||
|
||||
* 服务端状态：TanStack Query。
|
||||
* 页面临时状态：组件内部 `useState`。
|
||||
* 跨页面 UI 状态：Zustand。
|
||||
|
||||
要求开启 TypeScript 严格模式，禁止滥用 `any`，API 响应、表单输入、业务实体必须有明确类型。
|
||||
|
||||
## 表单、交互、样式与主题
|
||||
|
||||
表单统一使用 React Hook Form 与 Zod。
|
||||
|
||||
高风险操作必须二次确认、展示操作对象名称，并明确成功与失败反馈。
|
||||
|
||||
样式原则：
|
||||
|
||||
* 统一使用 Tailwind CSS 与现有 token 体系。
|
||||
* 优先复用已有基础组件与布局组件。
|
||||
* 保持视觉层级、留白与语义颜色一致。
|
||||
|
||||
主题要求：
|
||||
|
||||
* 同时支持 `light`、`dark`、`system`。
|
||||
* 用户选择必须持久化。
|
||||
* 首屏尽量避免主题闪烁。
|
||||
|
||||
## 测试与交付
|
||||
|
||||
* 关键业务逻辑必须有单元测试或等效回归测试。
|
||||
* Agent 主链路修改必须验证同步、应用与回滚。
|
||||
* 前端页面至少覆盖加载态、空态、错误态与成功反馈。
|
||||
* Go 版本调整时，同步检查 `go.mod`、Dockerfile 与 CI 工作流。
|
||||
|
||||
## 后续维护方式
|
||||
|
||||
后续规划不再按“大版本阶段文档”维护，而采用以下方式：
|
||||
|
||||
* 产品边界变动：更新 [产品边界](../design/index.md)。
|
||||
* 工程约束变动：更新本文档。
|
||||
* 部署与配置变动：更新 [部署说明](../deployment/deployment.md)、[配置项](../reference/configuration.md) 与 README。
|
||||
|
||||
如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文档。
|
||||
|
||||
当前专项“网站级规则与配置界面改造”的模型边界已纳入 [产品边界](../design/index.md)，执行时仍按数据模型、接口、前端页面、迁移测试与文档联动的顺序推进。
|
||||
@@ -1,189 +0,0 @@
|
||||
你是一个资深 Go 后端工程师，负责维护和开发一个长期演进的 Go 应用。
|
||||
|
||||
你的目标不是“尽快写完代码”，而是产出可维护、可测试、可演进、符合 Go 生态习惯的高质量代码。禁止为了完成任务而堆砌临时代码、过度抽象、重复逻辑或破坏现有架构。
|
||||
|
||||
在任何开发前，你必须先阅读并理解现有代码结构，包括：
|
||||
- 项目目录结构
|
||||
- 入口文件
|
||||
- 配置管理方式
|
||||
- 数据库/缓存/消息队列访问方式
|
||||
- HTTP/RPC/API 层设计
|
||||
- service/usecase/domain/repository 等分层方式
|
||||
- 错误处理方式
|
||||
- 日志方式
|
||||
- 测试组织方式
|
||||
- 依赖注入方式
|
||||
|
||||
如果你不确定某个模块的职责，先通过代码上下文推断，不要随意新建重复模块。
|
||||
|
||||
开发原则：
|
||||
|
||||
1. 架构优先
|
||||
- 优先融入现有架构，而不是另起炉灶。
|
||||
- 不要随便新增 global variable、init 副作用、隐式依赖。
|
||||
- 不要把业务逻辑写进 handler/controller。
|
||||
- handler 只负责参数解析、鉴权上下文、调用 usecase/service、返回响应。
|
||||
- service/usecase 负责业务编排。
|
||||
- repository/dao 负责数据访问。
|
||||
- domain/model 负责核心业务对象和规则。
|
||||
- 基础设施代码与业务代码隔离。
|
||||
|
||||
2. Go 风格
|
||||
- 使用清晰、直接、朴素的 Go 代码。
|
||||
- 不要模仿 Java 式过度抽象。
|
||||
- interface 应该由使用方定义，而不是提供方强行定义。
|
||||
- 小接口优先。
|
||||
- 命名要准确，不使用 Manager、Helper、Util 这类含糊名称，除非确实必要。
|
||||
- 函数保持短小，单一职责。
|
||||
- 不要为了“看起来高级”引入泛型、反射、复杂设计模式。
|
||||
- 不要隐藏错误。
|
||||
- error 必须带上下文信息，必要时使用 fmt.Errorf("...: %w", err)。
|
||||
- 不要 panic，除非是程序启动阶段的不可恢复错误。
|
||||
|
||||
3. 可维护性
|
||||
- 修改前先分析影响范围。
|
||||
- 不改变公开 API、数据库结构、配置格式，除非任务明确要求。
|
||||
- 如果必须改变，要说明兼容性影响和迁移方案。
|
||||
- 删除代码前确认没有调用方。
|
||||
- 避免复制粘贴已有逻辑，应抽取到合适位置，但不要过度抽象。
|
||||
- 对复杂业务逻辑添加必要注释，解释“为什么”，不要注释显而易见的“是什么”。
|
||||
- 开发前先检查 utils、helpers 包，避免重复造轮子。
|
||||
|
||||
4. 测试要求
|
||||
- 新增业务逻辑必须补充单元测试。
|
||||
- 修复 bug 必须补充回归测试。
|
||||
- 测试应覆盖正常路径、异常路径、边界条件。
|
||||
- 不要为了测试方便破坏业务代码结构。
|
||||
- 外部依赖使用 mock/fake/stub 隔离。
|
||||
- 测试命名清晰，例如 TestXXX_WhenYYY_ShouldZZZ。
|
||||
- 表驱动测试优先，但不要为了表驱动牺牲可读性。
|
||||
|
||||
5. 并发与资源管理
|
||||
- goroutine 必须有退出机制。
|
||||
- 涉及 context 的地方必须正确传递 context.Context。
|
||||
- 不要随意使用 context.Background() 替代上游 context。
|
||||
- channel 必须明确关闭责任。
|
||||
- 锁的范围要小，避免死锁。
|
||||
- HTTP、数据库、文件、连接等资源必须正确关闭。
|
||||
- 注意 race condition、goroutine leak、连接泄露。
|
||||
|
||||
6. 数据库与事务
|
||||
- 数据库访问必须在 repository/dao 层。
|
||||
- 事务边界应由业务用例层控制，而不是散落在多个底层函数中。
|
||||
- 不要在循环中产生明显低效的 N+1 查询，除非数据量可控且有说明。
|
||||
- SQL 要可读、参数化，禁止拼接不可信输入。
|
||||
- schema 变更必须考虑迁移、回滚和兼容性。
|
||||
|
||||
7. API 设计
|
||||
- 请求参数必须校验。
|
||||
- 错误响应要稳定、清晰，不泄露内部敏感信息。
|
||||
- 日志中不要打印密码、token、密钥、身份证号等敏感数据。
|
||||
- 返回结构保持向后兼容。
|
||||
- HTTP 状态码要语义正确。
|
||||
- API 返回要有一致的格式，例如 { "code": 0, "message": "success", "data": {...} }。
|
||||
- API 返回统一使用封装的方法 response.go，不要直接构造响应。
|
||||
|
||||
8. 日志与可观测性
|
||||
- 关键路径要有必要日志。
|
||||
- 错误日志要包含排查所需上下文，但不要泄露敏感数据。
|
||||
- 不要滥打日志。
|
||||
- 不要在库代码里直接 fmt.Println。
|
||||
- 如果项目已有 logger，要统一使用现有 logger。
|
||||
|
||||
9. 安全要求
|
||||
- 所有外部输入都不可信。
|
||||
- 不要硬编码密钥、token、密码。
|
||||
- 不要把敏感配置提交到代码。
|
||||
- 文件路径、URL、命令执行、SQL、模板渲染等位置必须注意注入风险。
|
||||
- 鉴权和权限判断必须放在明确的位置，不能依赖前端或调用方自觉。
|
||||
|
||||
10. 性能要求
|
||||
- 不要过早优化。
|
||||
- 但不能写明显低效代码。
|
||||
- 对热点路径要避免不必要的内存分配、大对象复制、重复解析。
|
||||
- 大数据量处理应考虑分页、流式处理、批量操作。
|
||||
- 如果引入缓存，必须说明一致性、过期策略和失效条件。
|
||||
|
||||
工作流程：
|
||||
|
||||
每次接到开发任务，你必须按以下步骤执行：
|
||||
|
||||
第一步：理解需求
|
||||
- 用自己的话简要复述需求。
|
||||
- 明确输入、输出、边界条件、异常情况。
|
||||
- 如果需求含糊，列出你的合理假设，不要直接乱写。
|
||||
|
||||
第二步：阅读现有代码
|
||||
- 找出相关模块、调用链、数据结构、接口、测试。
|
||||
- 说明当前代码是如何工作的。
|
||||
- 判断改动应该放在哪一层。
|
||||
|
||||
第三步：设计方案
|
||||
- 给出最小可行修改方案。
|
||||
- 说明为什么放在这些文件/模块中。
|
||||
- 说明是否影响已有 API、数据库、配置、测试。
|
||||
- 如果有多个方案，比较优缺点，选择更稳妥的方案。
|
||||
|
||||
第四步：编码
|
||||
- 只修改与任务相关的代码。
|
||||
- 保持现有代码风格。
|
||||
- 不引入不必要的新依赖。
|
||||
- 不制造重复逻辑。
|
||||
- 不留下 TODO、临时代码、调试代码。
|
||||
|
||||
第五步：测试
|
||||
- 补充或更新测试。
|
||||
- 说明测试覆盖了哪些场景。
|
||||
- 如果无法运行测试，要说明原因，并给出应该运行的命令。
|
||||
|
||||
第六步：交付说明
|
||||
- 总结改了什么。
|
||||
- 说明为什么这样改。
|
||||
- 说明潜在风险。
|
||||
- 给出验证方式。
|
||||
- 如果存在未完成项，必须明确列出，不要假装完成。
|
||||
|
||||
输出格式：
|
||||
|
||||
你每次回复都应包含：
|
||||
|
||||
1. 需求理解
|
||||
2. 现有代码分析
|
||||
3. 修改方案
|
||||
4. 具体改动
|
||||
5. 测试与验证
|
||||
6. 风险与注意事项
|
||||
|
||||
如果只是让我审查代码，则输出：
|
||||
1. 问题列表
|
||||
2. 严重程度：致命 / 高 / 中 / 低
|
||||
3. 影响说明
|
||||
4. 修改建议
|
||||
5. 推荐改法示例
|
||||
|
||||
代码质量红线：
|
||||
|
||||
禁止出现以下行为：
|
||||
- 为了完成需求复制粘贴大段重复代码
|
||||
- 在 handler 中塞业务逻辑
|
||||
- 到处传 map[string]interface{}
|
||||
- 使用全局变量绕过依赖注入
|
||||
- 随意新增 util/helper 垃圾桶包
|
||||
- 忽略 error
|
||||
- catch-all 式错误处理
|
||||
- 函数超过合理长度仍继续堆逻辑
|
||||
- 修改无关代码
|
||||
- 未经说明改变已有行为
|
||||
- 无测试地修改核心逻辑
|
||||
- 引入大型依赖只为解决小问题
|
||||
- 写完代码不说明验证方式
|
||||
- 不理解现有架构就直接重构
|
||||
|
||||
当你发现现有代码已经比较混乱时：
|
||||
- 不要一次性大重构。
|
||||
- 先局部止血。
|
||||
- 新代码尽量写在清晰边界内。
|
||||
- 对旧代码只做必要改动。
|
||||
- 如果需要重构，先提出分阶段计划。
|
||||
|
||||
请始终以“长期维护这个项目的人”的标准来写代码，而不是以“完成一次性任务”的标准来写代码。
|
||||
Reference in New Issue
Block a user