OpenViking 0.3.x 到 0.4.0 升级指南

本文面向已经运行 OpenViking 0.3.x 的用户，说明升级到 0.4.0 前后需要做什么、哪些旧用法仍然兼容、数据迁移如何执行，以及业务代码如何逐步迁移到新模型。

是否需要升级

如果继续停留在 0.3.x，现有 agent_id、viking://agent/...、viking://session/... 行为不会变化，但也无法使用 0.4.0 的能力：

没有 User / Peer 数据模型。
没有 legacy agent/session 数据迁移和 cleanup 命令。
没有 actor_peer_id 请求级 peer 视图。
后续围绕新模型的修复和能力不会回补到旧模型。

如果升级到 0.4.0，可以先不迁移数据。0.4.0 提供运行期兼容，旧数据不会因为升级立即不可读：

agent_id 仍可临时配置，会映射成 actor_peer_id。
viking://agent/... 仍可读旧 agent 数据，但只读。
viking://session/... 仍可读旧 session 数据，并会合并新 session 视图。
legacy agent_id 模式下，find / search 会同时查新 peer 数据和未迁移的旧 agent 数据。

推荐顺序：

text

备份
  -> 升级 server / CLI / SDK
  -> 验证旧数据仍可读
  -> 执行数据迁移
  -> 验证新路径
  -> 逐步迁移业务用法
  -> 可选 cleanup

升级前备份

先用 0.3.x 兼容版本创建备份。建议使用 0.3.24：

bash

pip install openviking==0.3.24 --upgrade --force-reinstall
ov backup ./backups/openviking-before-0.4.0.ovpack

确认当前版本：

bash

python -c "import openviking; print(openviking.__version__)"
ov version

不要在 0.3.x 上执行 ov --sudo admin migrate。迁移命令只在 0.4.0 或更新版本可用。

升级服务和客户端

安装 0.4.0，重启服务端，并确保 CLI / SDK 也升级到同一版本线：

bash

pip install openviking==0.4.0 --upgrade --force-reinstall
openviking-server --config ov.conf

如果使用仓库内 Rust ov CLI，需要重新构建或安装 CLI；否则本地 ov 可能仍是旧二进制。

升级后先验证配置和旧数据读取：

bash

ov config validate
ov ls viking://agent
ov ls viking://session
ov session list

viking://session 的兼容合并发生在服务端。只升级 CLI、不重启 server，不会改变服务端读取行为。

兼容性速查

旧用法	0.4.0 行为
client 配置 `agent_id`	支持，映射成请求级 `actor_peer_id`，并标记为 legacy agent 模式。
`ov ls viking://agent`	支持读；如果设置了 `agent_id` / `actor_peer_id`，只显示当前 actor peer 对应的 legacy agent。
读 `viking://agent/<agent_id>/...`	支持读旧数据。
写 `viking://agent/...`	不支持。新写入应进入 `viking://user/<user_id>/peers/<peer_id>/...`。
`ov ls viking://session`	支持读，会合并新 session 和旧 session。
读 `viking://session/<session_id>/...`	支持读，按新路径优先、旧路径兜底。
写 `viking://session/...`	不支持。新 session 写入 `viking://user/<user_id>/sessions/...`。
`find` / `search` 传 `agent_id`	支持，会同时查新 peer 数据和旧 agent 数据。
`find` / `search` body 传旧 `peer_id`	不支持。新 peer 视图使用 `actor_peer_id` 或 `X-OpenViking-Actor-Peer`。
同时配置 `actor_peer_id` 和 `agent_id`	不支持，会报错。
legacy `agent_id` client 下显式传 message `peer_id`	不支持，会报错。
`role_id` 记忆隔离	不再支持，升级后忽略。

执行数据迁移

确认升级后旧数据可读，再执行迁移：

bash

ov --sudo admin migrate --output json

响应会返回 task id：

json

{
  "task_id": "..."
}

查询任务：

bash

ov --sudo task status <task_id>
ov --sudo task list --task-type legacy_migration

HTTP API：

http

POST /api/v1/admin/migrate
X-API-Key: <root-key>

请求体可以为空，等价于：

json

{
  "action": "migrate"
}

查询任务：

http

GET /api/v1/tasks/{task_id}
X-API-Key: <root-key>

ROOT 查询迁移任务时不会按普通 account/user 过滤。迁移会为整个存储创建一个 root 级别 task，不会按 account 分别创建 task。

迁移规则

0.4.0 的新模型是 User / Peer：

text

User = 自然人或业务使用者
Peer = User 下的交互对象
Session = User 下的会话状态
Skill = User 下的可执行技能

迁移目标：

旧数据	新位置
`viking://agent/<agent_id>/memories/...`	`viking://user/<user_id>/peers/<agent_id>/memories/...`
`viking://agent/<agent_id>/resources/...`	`viking://user/<user_id>/peers/<agent_id>/resources/...`
`viking://agent/<agent_id>/skills/<skill>/...`	`viking://user/<user_id>/skills/<skill>/...`
`viking://session/<session_id>/...`	`viking://user/<user_id>/sessions/<session_id>/...`

共享 legacy agent 数据会复制到每个目标 user 的 peer 目录。如果旧路径已经表达了 user owner，只迁移到该 user。

迁移会一并处理已有向量索引：对实际复制成功的 memory / resource / skill 文件或目录，直接读取旧记录中的 vector / sparse_vector 和标量字段，重写 URI 后写入新记录。迁移不会重新向量化，也不会自动调用 reindex。共享 legacy agent 数据复制到多个 user 时，会按每个目标 user URI 写入多份向量记录。

没有向量 payload 的旧标量记录会跳过并计入 migrated.skipped_vector_records。Session 迁移只复制文件状态，不处理向量索引。

Session owner 按以下顺序解析：

.meta.json.created_by_user_id
.meta.json.user_id、.meta.json.owner_user_id 或 .meta.json.created_by
旧路径里的 user hint，例如 /session/alice/sess-001
单用户 account 下的唯一注册用户

多用户 account 下，如果某个 legacy session 无法识别 owner，preflight 会失败。升级后的运行期兼容可以临时读取旧 session，但正式迁移前仍应补齐 owner。

Legacy agent instructions 不迁移：

text

viking://agent/<agent_id>/instructions

迁移会记录 warning，不创建替代目录。

迁移前检查

以下问题会在 task 创建前直接失败：

物理存储中存在 legacy 数据，但对应 account 不在 API key user registry 中。
多用户 account 下存在无法识别 owner 的 legacy session。
session owner 存在，但不是合法的 OpenViking user id。

以下问题会记录为 warning 或 skipped，并继续迁移：

目标 user 已经存在同名 skill。旧 skill 会被跳过，不覆盖现有 skill。
发现 legacy agent instructions。Instructions 不迁移。
存在共享 legacy agent，但 account 下没有可迁移的目标 user。

如果迁移发现 legacy 数据 owner 不在 user registry 中，会自动注册该 user。迁移结果只记录自动创建了哪些用户，不返回明文 user key。

如果开启了 api_key_hashing，明文 key 无法从存储中反查。需要重新生成：

bash

ov --sudo admin regenerate-key <account_id> <user_id>

验证迁移结果

查看任务结果：

bash

ov --sudo task status <task_id>

重点看：

migrated.files / migrated.directories
migrated.vector_records / migrated.skipped_vector_records
migrated.operations
skipped
warnings
created_users

验证新路径：

bash

ov ls viking://user/<user_id>/peers/<agent_id>/memories
ov ls viking://user/<user_id>/skills
ov ls viking://user/<user_id>/sessions

迁移只复制数据，不删除 legacy 路径或旧向量记录。重复执行是幂等的：已存在的目标文件和 skill 会被跳过，不会覆盖。如果迁移后的检索结果不符合预期，再由用户对新路径手动执行 reindex；迁移流程本身不会触发 reindex。

业务用法迁移

Client 配置

旧配置可以先继续用：

json

{
  "agent_id": "legacy-agent"
}

推荐逐步改成：

json

{
  "actor_peer_id": "legacy-agent"
}

不要同时配置：

json

{
  "actor_peer_id": "customer-a",
  "agent_id": "legacy-agent"
}

这会报错。

文件路径

旧路径：

text

viking://agent/code-agent/memories/profile.md
viking://session/sess-001/messages.jsonl

新路径：

text

viking://user/alice/peers/code-agent/memories/profile.md
viking://user/alice/sessions/sess-001/messages.jsonl

viking://session/<session_id> 可以继续作为当前 user session 的读 alias 使用，但新写入和长期引用建议使用 viking://user/<user_id>/sessions/<session_id>。

find / search

迁移窗口内，如果还需要读取未迁移的旧 agent 数据，可以继续传：

json

{
  "query": "deployment notes",
  "agent_id": "legacy-agent"
}

迁移完成并确认不再需要旧 agent 数据后，改为 client/request 级 actor_peer_id。

会话消息

legacy agent_id client 会自动给 assistant message 带 agent_id。迁移到新用法后，不要再依赖 agent_id；需要表达消息说话人时使用 message peer_id。

暂不迁移数据

升级后可以暂时不迁移，但要知道这些限制：

旧 agent/session 数据可读，但旧 namespace 不可写。
新 session 和新资源会写入新 namespace，数据会在新旧路径并存一段时间。
legacy agent_id 检索会同时查新旧数据；纯 actor_peer_id 不会默认查旧 viking://agent。
多用户 account 下 owner 不明确的旧 session，运行期可能可读，但正式迁移会被 preflight 拦截。
cleanup 之前旧目录和旧向量记录仍会保留。

因此不迁移适合作为短期过渡，不建议作为长期状态。

可选 cleanup

确认迁移结果无误后，可以删除旧 namespace：

bash

ov --sudo admin migrate --cleanup --output json
ov --sudo task status <cleanup_task_id>

HTTP 请求体：

json

{
  "action": "cleanup"
}

Cleanup 只删除：

text

/local/<account>/agent
/local/<account>/session
/local/<account>/user/<user>/agent

Cleanup 会先删除上述 legacy URI scope 下的旧向量记录，再删除对应 AGFS 目录。若向量读取或删除失败，该目录会被跳过，避免旧文件已删除但旧索引仍残留。Cleanup 不会删除新 user / peer 路径下的文件或向量记录。

不会删除新模型目录：

text

/local/<account>/user/<user>/peers
/local/<account>/user/<user>/sessions
/local/<account>/user/<user>/skills

Cleanup 后，viking://agent/... 不再用于读取迁移后的 peer 数据；请使用新路径。viking://session/... 仍可作为当前 user session 的 alias 读取新 session。

常见问题

ov ls viking://agent 只看到一个 agent

如果配置了 agent_id 或 actor_peer_id，这是预期行为。viking://agent 根目录会过滤到当前 actor peer，只显示对应 legacy agent。

ov ls viking://session 仍为空

确认服务端已经重启并加载 0.4.0。viking://session 的合并读发生在服务端；只升级 CLI 不会改变服务端读取行为。

配置同时有 actor_peer_id 和 agent_id

这是不允许的。保留 agent_id 进入 legacy 模式，或删除 agent_id 后改用 actor_peer_id。

Preflight 报告 unknown account

物理存储中存在某个 account 的 legacy 数据，但 API key registry 中没有这个 account。先恢复或重新创建该 account，再重新执行迁移。

Preflight 报告 unresolved session owner

给 legacy session 的 .meta.json 补充 owner 字段，或把 session 移到能明确识别 owner 的旧路径下，然后重新执行迁移。

某个 skill 没有迁移

查看 task 的 skipped 列表。最常见原因是目标 user 已经存在同名 skill。迁移不会覆盖现有 skill。

OpenViking 0.3.x 到 0.4.0 升级指南 ​

是否需要升级 ​

升级前备份 ​

升级服务和客户端 ​

兼容性速查 ​

执行数据迁移 ​

迁移规则 ​

迁移前检查 ​

验证迁移结果 ​

业务用法迁移 ​

Client 配置 ​

文件路径 ​

find / search ​

会话消息 ​

暂不迁移数据 ​

可选 cleanup ​

常见问题 ​

ov ls viking://agent 只看到一个 agent ​

ov ls viking://session 仍为空 ​

配置同时有 actor_peer_id 和 agent_id ​

Preflight 报告 unknown account ​

Preflight 报告 unresolved session owner ​

某个 skill 没有迁移 ​

OpenViking 0.3.x 到 0.4.0 升级指南

是否需要升级

升级前备份

升级服务和客户端

兼容性速查

执行数据迁移

迁移规则

迁移前检查

验证迁移结果

业务用法迁移

Client 配置

文件路径

find / search

会话消息

暂不迁移数据

可选 cleanup

常见问题

ov ls viking://agent 只看到一个 agent

ov ls viking://session 仍为空

配置同时有 actor_peer_id 和 agent_id

Preflight 报告 unknown account

Preflight 报告 unresolved session owner

某个 skill 没有迁移