OpenRig数据库迁移管理指南：92个migration编号演进与版本兼容策略全解析-酒店常州论坛

OpenRig数据库迁移管理指南：92个migration编号演进与版本兼容策略全解析

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig（开源 Agent 协作网络工具）使用一套编号递增的 SQLite 数据库迁移（migration）体系管理数据库结构演进：001 → 092，每条迁移只增不改、已应用即跳过，并通过"fixture 对齐守卫"保证测试与生产 schema 永远一致。本文用通俗的方式讲透这套数据库迁移机制的编号规则、执行流程与版本兼容策略，帮你安全升级而不丢数据。

一、迁移机制总览：单文件、可追溯、自动执行

OpenRig 的守护进程（daemon）把团队拓扑、会话、队列、工作流等所有状态都存进一个本地 SQLite 数据库。每当产品功能新增字段或表，开发者就追加一条编号迁移文件，启动时自动补齐。

核心就三个文件：

执行引擎：migrate.ts —— 决定"怎么跑"
迁移清单：all-migrations.ts —— 决定"按什么顺序跑"
迁移本体：migrations/ 目录下 001 到 092 共 92 个编号文件，每文件一个功能主题

二、migration 编号演进：从 001 核心表到 092 的演进脉络

每个迁移文件命名格式为三位编号_功能名.ts，编号只增不复用，天然形成演进时间线。梳理全量编号，可以清楚看到 OpenRig 的功能成长史：

编号段	主题	代表迁移
001–006	基础 schema	001_core_schema.ts 建 rigs / nodes / edges 三张核心表
007–022	会话与运行时	014_agentspec_reboot.ts、020_rig_services.ts
023–037	消息队列与工作流	024_queue_items.ts、033_workflow_specs.ts
041–058	策略与归档	041_rig_policy.ts、055_node_permission_policy.ts
059–071	身份与生命周期	061_daemon_lifecycle.ts、067_i3_identity_provenance.ts
072–092	通知与最新能力	091_human_questions.ts、092_node_effort.ts

编号背后有两条铁律：

新迁移只往清单末尾追加：all-migrations.ts 开头注释明确写着"Append new migrations to the END, in order"，禁止中间插入或修改已发布条目。
001 是地基： rigs、nodes、edges 三张表和"同 rig 内连线"触发器约束都在此处建立，后续 91 个迁移全部在其上生长。

三、执行引擎如何保证版本兼容

阅读 migrate.ts，兼容策略其实只有四步，但环环相扣：

记账表：首次运行创建schema_migrations表，记录每个迁移的名称与应用时间；
查账：读回已应用迁移集合，已存在的直接跳过（幂等）；
排序：按名称字典序排列——因为编号是定长三位数，字典序恰好等于编号顺序；
事务落库：每条迁移包在一个事务里执行，SQL 成功才登记账本，失败则整体回滚，数据库永远停在"某个完整版本"上，不会出现半迁移状态。

这套机制意味着：老数据库升级新 OpenRig 版本时，只需启动一次，缺失的迁移会自动按序补齐；而新版本永远兼容旧库文件，因为迁移只加不删。

数据库连接层同样为兼容做了铺垫——connection.ts 默认开启 WAL 模式与外键约束，保证读写并发安全。

四、"Fixture 对齐守卫"：防止测试与生产 schema 脱节

这是 OpenRig 迁移管理中最有工程智慧的部分。如果测试只跑部分迁移，新迁移加入后测试可能漏列、报出莫名其妙的"缺列错误"。项目用三道保险解决：

单一事实源：all-migrations.ts 注释强调，守护进程启动路径和所有测试都从同一个数组迁移数据库，杜绝"手抄子集"；
声明式子集守卫：migration-subset-guard.ts 强制要求——任何精选测试迁移清单中的每一条，要么出现在清单里，要么在排除表中写明"为什么不需要"，并附可复查的理由；
失败必须响亮：migration-fixture-parity.test.ts 专门验证守卫本身会"开火"，新迁移被遗忘时测试直接点名报错并给出修复方案，而不是在无关测试深处埋雷。

注释里甚至记录了团队曾为此付出的"064/066/067 学费"——三个迁移漏进测试清单引发的连环排查，这也解释了为什么守卫要"教学式报错"。

五、升级实操：普通用户的三步检查清单

作为使用者，你几乎不需要动手，但升级后可用以下清单验证迁移健康：

看版本号：迁移清单当前到 092_node_effort.ts，对照 all-migrations.ts 可确认完整收录；
查启动日志：daemon 启动即跑迁移，正常启动本身即证明账本补齐成功（事务失败会拒绝启动而非带病运行）；
查账本：用任意 SQLite 工具打开数据库文件，SELECT name FROM schema_migrations ORDER BY name应能列出 001 起的全部条目。

六、小结：迁移编号演进的设计哲学

OpenRig 的数据库迁移管理可以浓缩为三句话：

编号即时间线：001 → 092 只增不改，每条迁移都是一个可追溯的功能决策；
账本即兼容性：schema_migrations让任意旧库都能一键升级到最新版本，事务保证中间态不存在；
守卫即纪律：fixture 对齐守卫把"忘记同步测试"这类隐患从线上问题提前消灭在 CI 里。

对于想学习迁移系统设计的开发者，packages/daemon/src/db/ 目录是一个干净、克制、可直接参考的范本；对于 OpenRig 用户，只需记住一点：放心升级，你的 Agent 团队状态都由这 92 条迁移安全守护着。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析