OpenFlare/docs/superpowers/specs/2026-08-29-openflare-cordis-refactor-design.md

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：

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 独立链，不并入插件版本表。