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

feat(cordis): add OpenFlare Cordis 架构改造设计

Browse Source 
docs(changelog): 修正表述笔误

refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本

按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），
本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到
Wavelet/pkg/cache/disk，同步后与上游零漂移。

验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与
232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。

docs(cordis): 记录 T1 清理结果与五个复用阻塞点

refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本

按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import：
shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→
上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异：
httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort*
一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。

两处非等价差异按语义处理：
- batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，
  避免 model 反向依赖基础设施类型；
- 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地
  副本，待与 infra 初始化一并迁移（已登记在清理计划）。

验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异；
make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为
response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。

chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染

按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手
属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为
纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。

同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被
gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与
driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh
现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。

AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束
（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、
internal/cmd）改到当前插件路径。

验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条
操作与基线逐条一致；make build-all 四进制；gofmt 干净。

feat(cordis): server 插件化并改由内核挂载控制面路由

新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix)
声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为
core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留
尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。
删除 router.Serve 与 registerRoutes，装配根改为 core.App +
driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；
前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。

路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条
(方法 路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的
openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线
逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend
标签编译通过；前端零改动。

已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与
改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。

feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由

server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达
/resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list
端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增
HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；
并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，
新增路由表导出 harness，固化 256 条 (方法 路径) 基线供插件化对拍。
上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录
前缀输出差异并在同步后提醒确认补丁是否仍在。

验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。

docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口

feat(cordis): agent/relay/flared 落地为内核驱动插件

三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver
（自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入
Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、
openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式
runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。

入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持
-config 旗标、默认路径、退出码与启动/停止日志不变。

验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份
与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置
均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。

refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层

backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared}
加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与
repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；
被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。
同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与
2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon
入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。

验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且
232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制
strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0
时报错（防门禁静默失效）；前端零改动。

feat(cordis): 落地 backend/share 共享层与上游同步脚本

跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包
移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向
引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖
backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。

go build 通过，go test ./... exit 0（142 包 ok），前端零改动。

refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核

按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare
全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持
Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至
backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。

行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API
操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，
待 P4 挂载上游路由后再纳入 plugins/。

style: 修正模块路径改写导致的 import 分组排序漂移

refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare

对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与
平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend，
swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费，
Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。

行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，
四进制产物正常，前端零改动。

chore(cordis): 落地改造计划与 schema/路由基线

新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序
（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与
版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单
与 foundation 实施计划。

docs(cordis): add OpenFlare Cordis 架构改造设计

明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件
(server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose
迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，
确保已部署库不重跑历史、不丢数据。
This commit is contained in:
ryan
2026-08-29 19:28:39 +08:00
parent 9f79fb9969
commit dbaa3bf140
1327 changed files with 91634 additions and 4157 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-08-29-openflare-cordis-refactor-design.md
+236
View File
@@ -0,0 +1,236 @@
# OpenFlare Cordis 架构改造设计
- **文档类型**: 架构设计 / 改造规范（Spec）
- **日期**: 2026-08-29
- **范围**: OpenFlare 后端全量迁移到 Wavelet Cordis 插件化架构
- **上游参照**: `/Users/ryan/Code/Go/Wavelet`（`backend/`，module `Wavelet`）
- **改造基线**: OpenFlare `main` @ `9f79fb99`（v3.5.4），工作分支 `cordis`
---
## 1. 目标与不可协商约束
| # | 约束 | 验证方式 |
| :-- | :-- | :-- |
| G1 | OpenFlare 改造为 Cordis 架构，上游包名为 `Wavelet` | `backend/Wavelet/` 与上游逐字节一致（`share/` 除外）；`go build ./...` 通过 |
| G2 | OpenFlare 功能收敛为 **4 个插件**：`server`、`agent`、`relay`、`flared` | `backend/plugins/` 下仅此 4 个目录，均实现 `core.Plugin` |
| G3 | 在上游树内创建 `share` 包承载跨插件共享资源 | `backend/Wavelet/share/` 存在且被 4 个插件至少两处 import |
| G4 | **不修改前端** | `git diff --name-only main...cordis -- frontend/` 为空 |
| G5 | 数据库迁移谨慎：已部署库不重跑历史、不丢数据、零破坏性变更 | 三方 schema 一致性门禁（§5.4） |
| G6 | 既有 HTTP 契约不变（前端与 API 消费者零感知） | 路由清单 diff + swagger 对拍 |
| G7 | 边缘三进制的 CLI 形态不变（`-config` 默认路径、退出码、日志格式） | 启动冒烟 + 现有测试保持绿 |
## 1.5 布局修正（v1.1，取代 §3 与 §4 中的路径描述）
初版设计提出的「`backend/` + `backend/Wavelet/` 双 module、OpenFlare 插件放 `backend/plugins/`」已被否定。
**采用与 Wavelet 完全同构的单 module 布局**（已落地，提交 `9bf0b2de`）：
```
backend/ module Wavelet（与上游同名，上游 import 路径逐字一致）
├── main.go cmd/ 控制面装配根（server）
├── core/ 【上游】微内核 + contracts + extpoints
├── pkg/ 【上游】通用库（禁止 import plugins）
├── plugins/{drivers,infra,domain}/ 【上游】平台插件
├── docs/ swaggo 产物（json/yaml 复制回根 docs/ 供站点消费）
├── share/ 【新增 G3】跨插件共享资源层
└── OpenFlare/ 【下游】占据上游 backend/downstream 的位置
├── cmd/{agent,relay,flared}/ 三个 daemon 入口（package main）
└── plugins/{server,agent,relay,flared}/ 【G2】4 个业务插件
```
约束更新：
- 上游同步 = 覆盖 `backend/{core,pkg,plugins}`，零 import 改写；`OpenFlare/` 与 `share/` 永不被覆盖。
- OpenFlare 现有代码（apps/repository/model/infra/router/shared/…）暂整体驻留 `backend/OpenFlare/**`，由 P4/P5 逐个搬入 `backend/OpenFlare/plugins/<插件>`；搬完后 `backend/OpenFlare` 下不再保留平铺的遗留层。
- 装配根在 `backend/cmd`（模块内非 internal 路径），因此下游树不得使用 `internal/`（已在本次落地时展平）。
- 平台表由上游 `plugins/domain/*` 拥有，业务表 `of_*` 由 `OpenFlare/plugins/server` 拥有；§5 迁移方案不变，仅历史链落点改为 `backend/OpenFlare/plugins/server/migrations/{postgres,sqlite}`。
落地验证（实测，非推断）：`go build ./...` 通过；`go test ./...` exit 0 且 142 个包 ok（含上游插件测试）；`make swagger` exit 0 且 232 条 API 操作与改造前基线逐条一致；`make build-all` 产出 4 个二进制；`git status --short -- frontend/` 为空。
上游 `plugins`、`core` 暂从 swaggo 扫描中排除（其包名 `model`、`disk` 与下游遗留注解的裸名引用冲突），P4 挂载上游路由时随 `OpenFlare/model` 展平一并解除。
## 2. 已核实的事实基线（设计前提，非推测）
1. **OpenFlare 是 Cordis 之前的 Wavelet 分叉**：`go.mod` module 路径即 `github.com/Rain-kl/Wavelet`；`internal/apps/` 同时含继承自 Wavelet 的平台应用（admin/oauth/user/upload/cap/config/health）与 OpenFlare 自有业务（openflare 29.6k 行、agent 7.4k、edge 1.5k、relay 1.0k、flared 0.9k）。Go 代码总量 151,473 行，209 个测试文件。
2. **表前缀双轨**：平台表沿用 `w_*`（OpenFlare 的 76 迁移已在其上分叉），业务表 `of_*`（28 张）。上游 `w_*` 表宇宙 17 张，且上游含 `w_message_channels`/`w_message_bindings`/`w_message_pairing_codes`（OpenFlare 无）→ **双向分叉**。
3. **内核支持非 HTTP 形态**（`Wavelet/backend/core`）：
- `normalizeProfile`（app.go:684）对未知 profile 字符串原样透传；`matchesProfile`（app.go:668）`default` 分支做字符串相等比较 → `core.Profile("agent")` 仅启动 `DriverType("agent")` 的驱动。
- `App.Run`（app.go:600-613）**始终**阻塞在 `signal.NotifyContext`；即使零驱动匹配也会阻塞 → 插件自身禁止阻塞。
- `Profile` 枚举仅 api/worker/schedule/all；驱动仅在 `Start` 中按 profile 过滤（app.go:487-494），插件 `Apply`、IoC、事件、配置在各 profile 下行为一致。
- 长生命周期服务标准写法（`plugins/drivers/driver_inproc_worker/plugin.go:118-151`）：`Apply` 内保存 coreCtx → `core.Provide` → `ctx.OnDispose(...)` → `ctx.RegisterDriver(p)`；`Stop` 逆序（LIFO）调用并受 `shutdownTimeout` 约束。
- `RunMigrations()`（app.go:414-433）在无 `MigrationEngine` 且容器无该服务时返回 nil → 无 DB 的 daemon 合法。
- DI 真实 API 为包级函数 `core.Provide[T](ctx, svc)` / `core.Inject[T](ctx)` / `core.Using[T](ctx, fn)` / `core.When[T](ctx, fn)`；`Context` **没有** `Provide/DB/Cache/Logger/Storage/DistLock` 方法（ cookbook 中的 `ctx.DB()` 写法为文档性简化，且内核无 DistLock 能力）。
4. **迁移子系统现状**：
- `w_schema_versions(plugin_id, version_id, applied_at)` 的 DDL 来自 Go（`Wavelet/backend/cmd/app.go:142-153`），**没有** SQL 文件创建它；插入使用 `ON CONFLICT DO NOTHING`。
- `sharedStore` 未实现 `TableExists` → goose 回退探测失败后会给每个 plugin_id 插入哨兵 `version_id = 0` 行（幂等、良性，但桥接必须知道）。
- 版本号解析：goose `NumericComponent` 取文件名首个 `_` 之前部分按十进制 int64 解析，须 ≥1；`2026MMDDNNNN` 与 `00001` 均合法；同一 plugin_id 内重复版本号致命。
- `findMigrationFS`（app.go:309-358）按目录名 `postgres`/`sqlite` 探测，**注册时传入的 `Dir` 参数被忽略** → 目录基名必须是 `postgres`/`sqlite`。
- 方言选择：`ctx.Config().Bool("database.enabled", false)` → postgres，否则 sqlite3；无 `WithSessionLocker` → **多节点并发迁移无保护**（上游未解）。
- 上游 `risk_control/logstore/migrations-clickhouse/00001_initial.sql` 是**未被 embed、无处应用**的孤儿文件。
- **上游不存在任何历史库基线/stamp 能力**（无 migrate 命令、无 `--baseline`），桥接为 OpenFlare 自有产物。
5. **`backend/` 化的路径耦合点**（Phase 1 必须一并处理）：
- `internal/router/root/frontend.go:18` `//go:embed all:dist`（前端导出物被 Go 包内嵌）；
- `.github/workflows/build-release.yml` 三处 `-X 'github.com/Rain-kl/Wavelet/internal/apps/{agent,relay,flared}/config.Version'` 与 `./cmd/*/main.go` 构建路径；
- `Makefile` 的 `build-embedded` / `build-backend` / `cross-build` / `swagger` / `code-check` / `dev-*`；
- `docker/` 四个镜像的构建上下文与 COPY 路径；`config.example.yaml`、`config/clickhouse`、`.env.example` 的读取路径。
## 3. 目标仓库布局
```
OpenFlare/
├── backend/ # Go 代码根，module OpenFlare
│ ├── go.mod # require Wavelet + replace Wavelet => ./Wavelet
│ ├── go.work # 本地一体构建（use . ./Wavelet）
│ ├── Wavelet/ # 【上游】从 Wavelet/backend 原样拷入
│ │ ├── go.mod # module Wavelet
│ │ ├── core/ # 微内核（零业务）
│ │ ├── core/contracts/ # 跨插件契约（纯 Interface + DTO）
│ │ ├── core/extpoints/ # 扩展点（Router/Task/Schedule/Migration/Setting/Config/Driver）
│ │ ├── plugins/drivers/ # driver_http / asynq_* / inproc_*
│ │ ├── plugins/infra/ # database / cache / cache_memory / config / logger / storage
│ │ ├── plugins/domain/ # admin / user / auth / message_gateway / risk_control / upload / cap / system
│ │ ├── pkg/ # 上游通用库（禁止 import plugins）
│ │ ├── scripts/check_cordis_architecture.sh
│ │ └── share/ # 【G3 新增】跨插件共享资源层，OpenFlare 所有
│ ├── plugins/ # 【G2】OpenFlare 的 4 个插件
│ │ ├── server/ # 控制面：of_* 业务域 + 边缘接入 API
│ │ ├── agent/ # 边缘 nginx/WAF 代理守护
│ │ ├── relay/ # frps 中继守护
│ │ └── flared/ # frpc 隧道客户端守护
│ ├── cmd/ # 装配根：root/server/agent/relay/flared/bridge
│ ├── main.go # server 入口（swagger 注释保留原位）
│ └── internal/ # 仅保留非业务基础设施（迁移桥接、构建信息）
├── frontend/ # 【不修改】
├── docs/ # VitePress + swagger 产物路径不变
├── docker/ Makefile .github/ # 路径改写至 backend/
└── config.example.yaml # 位置不变（新增 plugins.* 节点）
```
### 3.1 双 module 而非单 module 的理由
上游树内 import 保持 `Wavelet/core`、`Wavelet/plugins/...` 逐字节等于上游仓库，同步 = `rsync --delete` + 一条 `replace` 指令，无需任何 import 改写。单 module 方案（`OpenFlare/Wavelet/core`）每次同步都要全量重写 import，同步成本随上游演进线性上升，且必然产生漂移。以 Go module 依赖引用上游（不拷代码）被否，因为 OpenFlare 已分叉平台代码，需先在 `backend/Wavelet/` 内落地再回流。
### 3.2 `share` 的落点与所有权
`share` 建在上游 module 内（`Wavelet/share/...`），因为：`Wavelet/pkg/` 禁止 import 业务代码，而 `protocol`、`wsclient`、edge 日志/状态机、`geoip` 等资源**同时被 server 与三个 daemon 消费**；Cordis 规则禁止插件互相 import，故必须存在一个双方都可见的中立层。
**所有权声明**（写入 `backend/Wavelet/share/README.md`）：`share/` 由 OpenFlare 拥有，同步脚本 `scripts/sync-upstream.sh` 显式排除该目录；上游同步仅覆盖 `core/`、`plugins/`、`pkg/`、`scripts/`。此决定的代价是 `share/` 不能从上游获得更新——这是刻意选择，且是唯一需要否定的子决策（备选：落点 `backend/share/`，import `OpenFlare/share/...`，其余设计不变）。
### 3.3 模块与命名
- OpenFlare module 路径：`OpenFlare`（对齐上游 `module Wavelet` 的简化命名惯例）。
- 插件 ID 与目录名同名：`server` / `agent` / `relay` / `flared`。
- 表所有权：`of_*` 全部归 `server`；`w_*` 归各上游平台插件；`w_schema_versions` 归装配根。
- 插件内部分层：一律采用模式 2（`plugin.go` + `handler/ service/ repository/ model/ errs/ migrations/`），子包内文件按业务实体命名，禁止 `handlers_*` 平铺。
## 4. 插件设计
### 4.1 `server`
装配 profile：`api` / `worker` / `schedule` / `all`（与上游语义一致）。挂载上游 infra（database、cache 或 cache_memory、logger、storage）、8 个上游 domain 插件、`driver_http` + asynq/inproc 驱动对，再挂 `server` 插件。
`server` 插件职责：
- 路由：`ctx.Router().Group("/api/v1/...")` 自包含注册 OpenFlare 业务路由；免鉴权路径（边缘节点接入、健康探针、OAuth 回调）由本插件 `RegisterWhitelist` 主动声明，杜绝误拦截。
- 任务/调度：`ctx.Task().Register` / `ctx.Schedule().RegisterCron`（迁移现有 `internal/platform/bootstrap` 的显式装配）。
- 设置：`ctx.Settings().Register`（迁移现有动态设置声明）。
- 契约：向平台暴露 `contracts.*` 之外不新增跨插件事务；OpenFlare 自有能力经 `server` 单入口暴露。
- 迁移：`of_*` 全量 + 历史链（§5）。
内部按子域分包：`zone / cloudflare / pages / waf / node / proxy_route / dns / acme / tls / edge_control / config_version / health`，每子域内部遵循 handler→service→repository→model 单向依赖。
### 4.2 `agent` / `relay` / `flared`
同一模式，各自实现 `core.Plugin` + `core.Driver`：
```go
func (p *Plugin) Name() string { return "agent" }
func (p *Plugin) Type() core.DriverType { return core.DriverType("agent") }
func (p *Plugin) Apply(ctx *core.Context) error {
if err := ctx.Config().Bind("agent", &p.cfg); err != nil { return err } // JSON 配置经 ConfigSource 适配
core.Provide[contracts.LoggerService](ctx, lg)
ctx.OnDispose(func() error { return p.stop() })
return ctx.RegisterDriver(p)
}
func (p *Plugin) Start(ctx context.Context) error { /* util.Go 启动 heartbeat/sync/updater，select ctx.Done() */ }
func (p *Plugin) Stop(ctx context.Context) error { /* 收敛 frpc/frps 子进程与 ws 连接 */ }
```
- 入口 `cmd/agent/main.go` → `core.NewApp(core.WithProfile(core.Profile("agent")), core.WithConfigSource(jsonSource))` + `app.Use(agent.New())`；**不挂** http/database/cache/asynq 驱动。
- JSON 配置文件（`agent.json`/`relay.json`/`flared.json`）通过实现 `extpoints.ConfigSource`（`Lookup/LookupEnv/Describe`）接入，优先级：env 覆盖 → 文件 → default，与上游 `plugins/infra/config` 的解析优先级一致；`-config` 旗标与默认路径不变。
- 三者共享的 protocol / wsclient / edge logging / state 迁入 `Wavelet/share/`；`internal/apps/edge/` 消失（其内容分别归入 `share` 与 daemon 插件）。
- 裸 `go func()` 一律经 `util.Go`（架构门禁禁止裸 go）。
## 5. 数据库迁移方案（G5）
### 5.1 历史链保真
`goose/postgres`（76）与 `goose/sqlite`（76）文件**逐字节原样**迁入 `backend/plugins/server/migrations/{postgres,sqlite}/`，文件名、序号、内容不改；ClickHouse 链（14，含 `goose_clickhouse_version` 版本表）与其现有 `MigrateClickHouse` 路径**完全保持不动**，不并入 `w_schema_versions`（语义不同、且上游 CH 文件为孤儿，不引入其语义）。
### 5.2 插件初建与对齐
- 上游平台插件的 `00001_initial.sql` 保留：全部 `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` / seed `ON CONFLICT DO NOTHING` → 在 OpenFlare 老库上只补建上游新增表（如 `w_message_channels`），已存在表自动跳过。
- 若上游模型需要 OpenFlare 现库缺失的列，**只允许**在对应插件的 `migrations/{postgres,sqlite}/00002_openflare_align.sql` 追加（`ADD COLUMN` / `CREATE INDEX IF NOT EXISTS`）。全链路禁止 `DROP TABLE` / `DROP COLUMN` / `TRUNCATE`。
- 双方言目录必须文件名与版本号一一对应，否则 PG 与 sqlite 的 `version_id` 漂移。
### 5.3 一次性桥接（`cmd/bridge`，启动前置）
1. 以与上游 `cmd/app.go:142-153` **逐字节一致**的 DDL 建 `w_schema_versions`（保证上游 `CreateVersionTable` 的 `IF NOT EXISTS` 成为 no-op）。
2. 取 PG advisory lock（`pg_advisory_lock(key)`）/ sqlite 依赖单写者，补齐上游缺失的并发保护。
3. 若存在老库版本表（`goose_db_version` / OpenFlare 现名）且 `w_schema_versions` 无 `openflare/legacy` 记录：写入 `(openflare/legacy, 0)` 哨兵与 `(openflare/legacy, MAX(老库已应用版本))`，全部 `ON CONFLICT DO NOTHING`。
4. 桥接幂等：重复执行零变更；老库此后**永不重跑**历史链，新库正常跑完整链后收敛到同一 schema。
5. 桥接仅由 server 装配根在 `app.RunMigrations()` 之前调用一次；agent/relay/flared 不涉及（无 DB）。
### 5.4 三方一致性门禁（不可跳过）
| 路径 | 构造方式 | 断言 |
| :-- | :-- | :-- |
| A（基线） | 改造前 `main` 二进制在全新 sqlite/PG 上跑完 76 链 | dump `information_schema` + seed 行数 |
| B（新架构全新安装） | 桥接 + 历史链 + 各插件 initial/align | 与 A **逐项 diff 为空** |
| C（升级路径） | 恢复 A 的库文件后再启动一次新架构 | schema diff 为空，且本次启动**零 SQL 变更**（迁移结果集为空） |
工具：`backend/cmd/migrate-audit`（导 dump 与 diff，只读、不写源码树，临时目录用 `t.TempDir()`）。任一路径失败即视为改造未完成，禁止合并。
## 6. 前端与 API 契约（G4/G6）
`frontend/` 零改动（`git diff --name-only main...cordis -- frontend/` 必须为空）。内嵌物路径由 `Makefile` 的 `build-embedded` 负责：前端导出物仍拷到 `backend/internal/router/root/dist`（或迁移后对应包目录），`//go:embed all:dist` 随包位置同步。
服务端 HTTP 契约保持：路径、`{error_msg,data}` 信封、分页 `{total,results}`、成功 200 / 失败 `Abort*` 语义、swagger 产物路径（`docs/swagger.json|yaml`）。验收：改造前后各跑一次 `swag init`，对拍 `paths` 键集合必须一致（新增路径允许，删改不允许）。
## 7. 工具链、CI 与文档
- `Makefile`：Go 目标切到 `backend/`；新增 `sync-upstream`、`migrate-audit`、`arch-check`。
- `.github/workflows`：4 个 build-image 工作流的构建上下文/`Dockerfile` COPY 路径、`build-release.yml` 的 `./cmd/*/main.go` 与三处 `-X` ldflags 模块路径（改为 `OpenFlare/plugins/{agent,relay,flared}/config.Version`）。
- 门禁移植：`backend/Wavelet/scripts/check_cordis_architecture.sh`（core 不 import gin/gorm/asynq；pkg 不 import plugins；插件间不互相 import；禁 AutoMigrate；禁裸 go）在 OpenFlare `backend/` 下纳入 `make code-check`。
- 文档：中文文档同步（不同步英文）；`docs/changelog/index.md` 的 `[Unreleased]` 记录用户可读变更。
## 8. 分期执行计划（每期终点：`go build ./...` 通过 + 209 测试文件绿）
| 期 | 交付 | 验证 |
| :-- | :-- | :-- |
| P0 | 基线测量：构建/测试记录、A 路 schema dump、路由清单快照 | 存档于 `docs/superpowers/specs/baseline/` |
| P1 | Go 树 `git mv` 入 `backend/`，module 改 `OpenFlare`，import 全量改写，Makefile/CI/Docker 路径 | `go build ./...`、四二进制产出、swagger diff 为空 |
| P2 | 上游 vendoring 成 `backend/Wavelet/`（第二 module）+ `share/` 骨架 + 同步脚本 | `go work sync`、`go build ./...`、架构门禁通过 |
| P3 | 迁移子系统：`w_schema_versions` 引擎接入、桥接、历史链归属、align 迁移、`migrate-audit` | **§5.4 三方 diff 全空** |
| P4 | `server` 插件化：`apps/openflare` + health/config/edge 控制面 → 插件子包 + 扩展点注册 | 路由对拍 + 业务测试绿 |
| P5 | `agent`/`relay`/`flared` 插件化 + `share` 落地（protocol/wsclient/edge） | 三 daemon 实跑冒烟 + JSON 配置兼容 |
| P6 | 平台分叉审计与回流：OpenFlare 对 admin/oauth/user/upload/cap/push 的定制逐项移植进 `backend/Wavelet/` | 分叉清单逐项关闭，无静默丢功能 |
| P7 | 工具链/CI/文档/changelog | `make code-check`、`make format` |
| P8 | 加固：`go test -race ./...`、`-shuffle=on`、四 profile 实跑、老库升级演练 | 全绿方可声明完成 |
依赖：P3 依赖 P2；P4/P5 依赖 P2、P3；P6 可与 P4 并行但须在同一期收口。
## 9. 风险与对策
1. **fresh 安装与升级路径 schema 漂移**（桥接最大风险，`CREATE TABLE IF NOT EXISTS` 会静默保留旧表）→ §5.4 三方 diff 门禁 + `migrate-audit` 常驻 CI。
2. **平台分叉被静默丢弃**（OpenFlare 的 admin/oauth/push 定制）→ P6 强制逐项清单，禁止以"上游没有"为由删除行为。
3. **多节点同时迁移竞争**（上游无 session locker）→ 桥接与迁移阶段 advisory lock。
4. **29.6k 行业务塞进单插件导致不可维护**→ `server` 内部按子域物理分包（§4.1），插件数保持 4 不变。
5. **CI/Docker 路径漏改导致发布链断裂**（release 工作流含硬编码 ldflags 模块路径）→ P1 一次性收口并跑 dry-run 构建。
6. **规模**：151k 行、166 迁移文件，上游自身耗时 100+ 提交 → 分期增量、每期可编译可测；不以"部分完成"冒充目标达成。
## 10. 已定决策（可在复审时否定）
- 布局：镜像 `backend/`，上游为第二 module（用户选定）。
- 插件边界：每二进制 = 1 插件，四者全部走内核（用户选定）。
- 迁移：保留历史 + 版本 stamp 桥接（用户选定）。
- `share` 落点：`backend/Wavelet/share/`，OpenFlare 所有、同步排除（本设计采纳，备选见 §3.2）。
- 桥接粒度：stamp 至 `MAX(已应用版本)` 而非逐条 76 行（版本号语义为「≤ max 即已应用」，逐条无额外收益且放大漂移面）。
- ClickHouse：保持既有 `goose_clickhouse_version` 独立链，不并入插件版本表。