Skip to content

fix(controller): auto-migrate legacy hiclaw.db to agentteams.db on ki… - #1152

Open
LUOSENGWA wants to merge 1 commit into
agentscope-ai:mainfrom
LUOSENGWA:fix/kine-db-migration
Open

fix(controller): auto-migrate legacy hiclaw.db to agentteams.db on ki…#1152
LUOSENGWA wants to merge 1 commit into
agentscope-ai:mainfrom
LUOSENGWA:fix/kine-db-migration

Conversation

@LUOSENGWA

@LUOSENGWA LUOSENGWA commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Problem

v1.2.0 renamed the embedded kine database from hiclaw.db to
agentteams.db (#1063/#1065) without a migration path. README still
promises "Upgrade to latest (preserves all data)", but after the rename an
in-place upgrade makes the embedded controller read the new DB name while
all existing state (workers, teams, CRDs) lives in the old file — the
controller silently loses its full state.

Reported from a real v1.2.0 → v1.2.1 upgrade: all Workers disappeared after
the upgrade; recovery required manually copying the old DB files to the new
name.

Note: #1063 originally shipped this migration (agentTeamsDBPath), but
#1065's hard-cut rename removed it because it referenced the retired brand
name. This PR restores it (as a copy, not a rename) and adds the two store
files to the rename-contract allowlist, following the existing installer
allowlist precedent from #1079.

Fix

StartKine detects a legacy DB before opening the store and migrates it
once, at startup:

  • If hiclaw.db exists and agentteams.db does not → copy it (plus the
    SQLite -wal/-shm sidecar files) to agentteams.db.
  • Idempotent: an existing agentteams.db is never overwritten, so users
    who already migrated manually are untouched.
  • Rollback-safe: copy instead of rename, so the legacy file is preserved.
  • Migration failure aborts startup instead of silently opening an empty store.

问题背景

v1.2.0 将内嵌 kine 数据库文件名从 hiclaw.db 重命名为 agentteams.db
#1063/#1065),但没有提供迁移路径。README 仍承诺 "Upgrade to latest
(preserves all data)"(升级保留所有数据),但重命名后,就地升级会让
内嵌 Controller 读取新库名,而全部既有状态(Worker、Team、CRD)仍在旧
文件中——Controller 会静默丢失全部状态。

来自真实 v1.2.0 → v1.2.1 升级案例:升级后所有 Worker 消失;恢复需要
手动把旧库文件复制为新库名。

说明:#1063 最初自带该迁移逻辑(agentTeamsDBPath),但 #1065
hard-cut rename 因迁移函数引用了已退役的品牌名而将其删除。本 PR 恢复该
迁移(改用 copy 而非 rename),并按 #1079 的 install 脚本白名单先例,
把两个 store 文件加入 rename-contract 白名单。

修复内容

StartKine 在打开存储前检测旧库并迁移一次(启动时):

  • hiclaw.db 存在且 agentteams.db 不存在 → 复制(含 SQLite
    -wal/-shm 侧车文件)为 agentteams.db
  • 幂等:已存在的 agentteams.db 绝不被覆盖,手动迁移过的用户不受影响。
  • 可回退:使用 copy 而非 rename,旧文件保留用于回退。
  • 迁移失败会中止启动,而不是静默打开空库。

…ne startup

v1.2.0 renamed the embedded kine database from hiclaw.db to agentteams.db
without migrating existing data, so upgrades lost all controller state
(workers, teams, etc.) until the DB was copied manually.

Detect a legacy hiclaw.db at startup and copy it (plus SQLite -wal/-shm
sidecar files) to agentteams.db when the new DB does not exist yet.
Idempotent: an existing agentteams.db is never overwritten (covers manual
migrations). Copy instead of rename preserves the legacy file for rollback.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant