mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-08 00:26:37 +08:00
ryan
dbaa3bf140
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 一致性门禁，
确保已部署库不重跑历史、不丢数据。
99 lines
8.2 KiB
Markdown
99 lines
8.2 KiB
Markdown
# server 插件复用上游能力清理计划
|
||
|
||
**目标**：`backend/OpenFlare/plugins/server` 里大量能力上游 Wavelet 已提供，删除本地副本改为复用；
|
||
按规约判定归属——通用能力回流上游，OpenFlare 业务留在插件内。
|
||
|
||
**事实基线**：`server` 实测 **68,117** 行非测试 Go 代码（早先记的 29.6k 只是 `openflare/` 一个域）。
|
||
路由契约冻结基准：`docs/superpowers/specs/baseline/routes-engine.txt`（256 条 方法+路径）与
|
||
`routes.txt`（232 条 swagger 操作），由 `plugin_parity_test.go` 逐条把守。
|
||
|
||
## 关键防线（先读，否则会做错）
|
||
|
||
直接挂上游插件**会破坏契约**，以下差异必须逐项处理，不允许“上游有就换”：
|
||
|
||
1. **验证码门禁丢失**：OF 在 `POST /api/v1/user/{login,register,send-email-code}` 上挂了
|
||
`cap.VerifyMiddleware`（`router/v1/user.go:71-73`），上游 `domain/user` 没有该门禁
|
||
（`user/plugin.go:126-129`）。直接替换=安全回归。
|
||
2. **路径变化**：`/api/cap/{challenge,redeem}`（OF，挂在 `/api` 组）vs `/api/v1/cap/*`（上游，且多一个 `GET`）；
|
||
`GET /api/health` vs `/healthz` + `/api/healthz`；`/api/v1/upload` 的 `GET /my`、`PUT /:id`、
|
||
`GET /download/:id`、`POST /download/batch` vs 上游 `GET ""`、`POST /batch-download`；
|
||
OF 独有 `GET /api/v1/user/self`。
|
||
3. **公共配置响应体不同**：`GET /api/v1/config/public` 路径相同但 JSON 字段不同，SPA 直接消费。
|
||
4. 上游额外需要表 `w_message_channels` / `w_message_bindings` / `w_message_pairing_codes`（OF 库中不存在）。
|
||
除此之外 13 张共享 `w_*` 表**列级零差异**；唯一缺口 `w_access_tokens.description/expires_at` 上游 Go 模型也未使用，非阻塞。
|
||
|
||
## 判定清单
|
||
|
||
| 包 | 行数 | 上游对应 | 判定 |
|
||
| :-- | --: | :-- | :-- |
|
||
| `shared/response` | 142 | `pkg/response` | 删（7/7 `Abort*` 逐字一致，仅风格差异） |
|
||
| `pkg/logger` | 382 | `pkg/logger` | 删（`Config` 字段完全一致） |
|
||
| `pkg/mail` | 266 | `pkg/mail` | 删 |
|
||
| `pkg/httppool` | 106 | `pkg/httppool` | 删（逐字节相同） |
|
||
| `pkg/trace` | 148 | `pkg/trace` | 删（差异仅默认 tracer 名，由 `app.app_name`/`otel.tracer_name` 决定） |
|
||
| `pkg/cache/ram` | 305 | `pkg/cache/ram` | 删（OF 用裸 `go`，上游用 `util.Go`，换过去是修复） |
|
||
| `infra/persistence/idgen` | 47 | `pkg/idgen` | 删（上游为超集） |
|
||
| `infra/persistence/batchwriter` | 337 | `pkg/batchwriter` | 删 |
|
||
| `listener` | 42 | `core/events.go Subscribe[T]` | 删，改事件订阅 |
|
||
| `testhelper` | 479 | `pkg/testhelper` | 合并，仅留 `SetupLogStoresForTest` |
|
||
| `pkg/cache/disk` | 412 | `pkg/cache/disk` | 先回流 OF 的 5 处类型断言 `ok` 守卫（通用健壮性修复），再删本地副本 |
|
||
| `pkg/cap` | 511 | `plugins/domain/cap/pow` | **不能直接复用**（跨插件 import 被禁）。二选一：pow 提取到上游 `pkg/pow`，或留 `server` 内并放弃“复用” |
|
||
| `infra/objectstore`、`infra/diskcache` | 1,058 | `plugins/infra/storage/*` | 改走 `contracts.StorageService`/上游 infra（P6） |
|
||
| `infra/task`（worker/scheduler/handlers） | 1,125 | `plugins/drivers/driver_asynq_*` | 换内核驱动（P6） |
|
||
| `infra/config`（全局 `Config` 单例） | 444 | `core/config.go` + `plugins/infra/config` | 改 `ctx.Config().Bind`（P6，18 处引用） |
|
||
| `infra/persistence`（DB/Redis 初始化） | 639 | `plugins/infra/database` | 换 `contracts.DBService`（P6） |
|
||
| `infra/persistence/migrator` | 298 | `w_schema_versions` + 每插件迁移 | 见 foundation 计划 P3（含历史 stamp 桥接） |
|
||
| `repository/logstore` | 3,286 | `plugins/domain/risk_control/logstore` | 近似分叉：合并并保留 OF 的 `AccessLogStore`/`ObservabilityStore` 接口 |
|
||
| `repository/analytics` | 2,848 | 同上（仅用户访问日志半边） | 合并半边；`node_*` 与 CH 维护上游没有，留 `server` |
|
||
| `repository`、`model` | 8,527 | 各上游域插件内 | 拆分：`w_*` 部分随 P6 归上游，`of_*` 留 `server` |
|
||
| `oauth`、`user`、`admin`、`upload`、`cap`、`config`、`health` | ~7,600 | `plugins/domain/{auth,user,admin,upload,cap,system}` | **受“关键防线”约束**，逐端点判定后合并，禁止整体替换 |
|
||
| `admin/push` | 1,776 | `plugins/domain/message_gateway` | 合并并保留 OF 的 `RegisterBuiltInEvent`/`RegisterChannelDefinition`/`SyncEvents` 钩子 |
|
||
| `admin/updater` | 832 | 上游仅 `GetUpdateStatus/ApplyUpdate` | OF 的 Prepare/Apply/Finish 三段式为业务能力，保留 |
|
||
| `openflare/`（27 子包） | 29,678 | 无 | 保留（产品逻辑）；`apiutil` 与 `integration/githubrelease` 若被多插件消费再移 `share` |
|
||
| `router`、`router/root`、`router/v1` | 1,242 | `core/extpoints` + `driver_http` | 保留为接线层，直至上游具备引擎中间件与 NoRoute 贡献点 |
|
||
|
||
## 执行顺序
|
||
|
||
1. **T1 纯风格差异**（`shared/response`、`pkg/{logger,mail,httppool,trace,cache/ram}`、
|
||
`infra/persistence/{idgen,batchwriter}`）：改 import → 删本地副本 → 全量门禁。
|
||
2. **T2 `listener` 改事件订阅**、`testhelper` 合并。
|
||
3. **T3 `pkg/cache/disk` 断言守卫回流上游**，再删本地副本。
|
||
4. **T4 基础设施换内核**（`infra/config` → `ctx.Config()`；`infra/persistence` → `contracts.DBService`；
|
||
`infra/task` → asynq 驱动）：与 P3/P4b 合并推进。
|
||
5. **T5 平台域逐个合并**（oauth/user/admin/upload/cap/config/health/push）：每个域先列差异
|
||
（路由、门禁、响应体、表列），差异以 `server` 内薄封装或回流上游解决，逐域过 256 条对拍。
|
||
6. **T6 `repository`/`model` 按表所有权拆分**：`w_*` 归上游，`of_*` 留 `server`。
|
||
|
||
每步完成判据：`go build ./...` + `go test ./...` 全绿 + `plugin_parity_test` 零差异 +
|
||
`make swagger` 232 条零差异 + `golangci-lint` 0 issues + `frontend/` 零改动。
|
||
|
||
## 执行记录与阻塞点
|
||
|
||
### T1 已完成（提交 `0adbfc1a`）
|
||
|
||
删除并改用上游：`shared/response`→`pkg/response`、`pkg/{logger,mail,trace,httppool,cache/ram}`、
|
||
`infra/persistence/batchwriter`→`pkg/batchwriter`。共 7 个本地包消失，`go test` 包数 144→138。
|
||
|
||
证据：256 条路由对拍零差异；232 条 swagger 操作零增减，且**把两个随包路径改名的定义
|
||
（`…shared_response.Any`→`response.Any`、`…pkg_logger.LogEntry`→`logger.LogEntry`）归一化后，
|
||
新旧 swagger.json 深度相等**——即接口形状完全未变。`$ref` 名由 Go 包路径派生，属生成物命名变化。
|
||
|
||
### 新发现的阻塞点（勿重复踩）
|
||
|
||
1. **`pkg/idgen` 暂不能换**：上游 `pkg/idgen` 要求先 `Init(nodeID)` 否则 panic
|
||
（`idgen: Init must be called before generating IDs`），而 OpenFlare 副本是懒初始化。
|
||
5 个 push/user 用例直接 panic。必须与 T4（`infra/config`、`infra/persistence` 改走
|
||
`ctx.Config()`/`contracts.DBService`）一起做，在 bootstrap 阶段显式 `Init`。
|
||
2. **`pkg/cap` 不能“复用上游”**：上游 pow 实现在 `plugins/domain/cap/pow` 里，
|
||
跨插件 import 被架构门禁禁止。合规出路二选一：把 pow 提取为上游 `pkg/pow`（通用能力，
|
||
按规约回流 Wavelet 后两边共用），或承认它是 server 的业务实现留在插件内。
|
||
3. **`listener` 需先有内核上下文**：`core.Subscribe[T](bus, topic, fn)` 要 `*core.EventBus` 实例，
|
||
而调用方（`oauth/handler_callback.go`、`user/routers.go`、`admin/push/custom_events/*`）都在
|
||
内核之外、手上没有 `*core.Context`。现在改只会把全局变量从包级切片挪到包级总线。
|
||
待 `server` 的 `Apply`/bootstrap 拿到 ctx 后随 T4 一起做。
|
||
4. **`pkg/trace` 覆盖缺口（非本次引入）**：核实后上游与 OpenFlare 副本都是 4 个同名文件、
|
||
都**没有**测试文件，因此删除本地副本没有降低覆盖率。要补测试应直接补在上游 `backend/pkg/trace/`。
|
||
5. **`pkg/cache/disk` 已完成**：5 处类型断言的 `ok` 守卫按规约回流上游
|
||
（Wavelet `f3d85d5`，附 `cache_corruption_test.go`：去掉守卫即 panic、加上守卫 4 用例全过），
|
||
上游的 `Default()` 全局实例保留（下游不使用它，不构成行为差异）；本地副本已删除。
|