OpenViking 0.3.x 到 0.4.0 升级与 User/Peer 数据模型迁移实战指南【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本指南面向已经运行 OpenViking 0.3.x 的开发者与运维人员系统讲解升级到 0.4.0 前后的完整动作哪些旧用法保持兼容、何时必须执行数据迁移、迁移的底层规则与向量索引处理方式以及业务代码如何从viking://agent/...、viking://session/...逐步迁移到新的viking://user/user_id/peers/peer_id/...模型。读完本文你将掌握一条可安全执行的升级迁移路径并理解 0.4.0 中 User / Peer / Session / Skill 新数据模型背后的源码级实现依据。是否需要升级如果继续停留在 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仍可临时配置。当前 HTTP SDK client 会把它映射成请求级actor_peer_id。viking://agent/...仍可读旧 agent 数据但只读。viking://session/...仍可读旧 session 数据并会合并新 session 视图。推荐顺序备份 - 升级 server / CLI / SDK - 验证旧数据仍可读 - 执行数据迁移 - 验证新路径 - 逐步迁移业务用法 - 可选 cleanup升级前备份先用 0.3.x 兼容版本创建备份。建议使用0.3.24pip install openviking0.3.24 --upgrade --force-reinstall ov backup ./backups/openviking-before-0.4.0.ovpack确认当前版本python -c import openviking; print(openviking.__version__) ov version重要约束不要在 0.3.x 上执行ov --sudo admin migrate。迁移命令只在 0.4.0 或更新版本可用。从源码看迁移入口POST /api/v1/admin/migrate见 admin.py依赖 0.4.0 的 task tracker 与LegacyDataMigration服务旧版本二进制中并不存在该能力。升级服务和客户端安装 0.4.0重启服务端并确保 CLI / SDK 也升级到同一版本线pip install openviking0.4.0 --upgrade --force-reinstall openviking-server --config ov.conf如果使用仓库内 RustovCLI需要重新构建或安装 CLI否则本地ov可能仍是旧二进制。仓库内 Rust CLI 的迁移命令实现在 crates/ov_cli/src/commands/admin.rs它通过 client.rs 中的admin_migrate以migrate或cleanup两种 action 调用服务端接口。升级后先验证配置和旧数据读取ov config validate ov ls viking://agent ov ls viking://session ov session list关键点viking://session的兼容合并发生在服务端。只升级 CLI、不重启 server不会改变服务端读取行为。0.4.0 的请求边界解析逻辑位于 openviking/core/namespace.pyviking://session/...会在认证请求边界被解析为当前用户的viking://user/user_id/sessions/...而~是当前用户空间的 home alias因此“只升级客户端”对服务端读取行为没有任何影响。兼容性速查旧用法0.4.0 行为client 配置agent_id支持。当前 HTTP SDK client 会映射成请求级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/...。HTTP SDKfind/search传agent_id支持只查选中的 actor peer 视图不会自动查未迁移的旧 agent 数据。find/searchbody 传旧peer_id不支持。新 peer 视图使用actor_peer_id或X-OpenViking-Actor-Peer。同时配置actor_peer_id和agent_id不支持会报错。HTTP SDKagent_idclient 下显式传 messagepeer_id支持。该 message 使用显式peer_id未提供时不会从agent_id推导。role_id记忆隔离不再支持升级后忽略。actor_peer_id 视图的源码依据“只读当前 actor peer”这一行为不是文档约定而是有真实实现支撑的在 openviking/core/namespace.py 中is_hidden_by_actor_peer_view与may_include_hidden_actor_peers会依据ctx.actor_peer_id过滤当前 user root 下peers集合中属于其他 peer 的内容——它只过滤peers集合不会隐藏非 peer 的用户内容也不会改变租户/用户身份。在 openviking/core/namespace.py 的is_accessible中访问agentscope 时若配置了actor_peer_id只有 agent id 与actor_peer_id一致的目录才可访问这正是“ov ls viking://agent只显示当前 actor peer 对应 legacy agent”的实现原因。请求上下文中的actor_peer_id会随RequestContext传递见 namespace.py 中构造RequestContext时保留actor_peer_id字段说明 peer 视图是请求级的而非全局状态。执行数据迁移确认升级后旧数据可读再执行迁移ov --sudo admin migrate --output json响应会返回 task id{ task_id: ... }查询任务ov --sudo task status task_id ov --sudo task list --task-type legacy_migrationHTTP APIPOST /api/v1/admin/migrate X-API-Key: root-key请求体可以为空等价于{ action: migrate }查询任务GET /api/v1/tasks/{task_id} X-API-Key: root-keyROOT 查询迁移任务时不会按普通 account/user 过滤。迁移会为整个存储创建一个 root 级别 task不会按 account 分别创建 task。从 admin.py 的实现可以看到migrate_legacy_data端点先构造LegacyDataMigration若 action 为migrate则先执行preflight()preflight 存在errors时直接抛出FailedPreconditionErrortask 根本不会被创建通过后以SYSTEM_TASK_ACCOUNT_ID/SYSTEM_TASK_USER_ID创建 task 并用asyncio.create_task异步执行因此接口立即返回task_id实际迁移在后台完成。对应的测试用例 tests/server/test_admin_api.py 专门验证了“preflight 失败不创建 task”的行为。迁移规则0.4.0 的新模型是 User / PeerUser 自然人或业务使用者 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。迁移规划器的源码视角迁移的核心实现在 openviking/service/legacy_migration.py三类 legacy 布局都会在 preflight 中识别/local/account/user/user_id/agent/agent_iduser 作用域_plan_user_agent_data、/local/account/agent/agent_id/user/user_idagent 作用域_plan_agent_user_data、以及共享的/local/account/agent/agent_id_plan_shared_agent_data。保留目录保护viking://agent/下的skills、endpoints、tools、payments属于新公共 scope 布局定义在_AGENT_RESERVED_SUBDIRSlegacy_migration.py迁移和 cleanup 规划器都会跳过它们不会当作 legacyagent_id处理。操作粒度迁移按TreeCopy描述每条复制操作带category如agent_memories、agent_skills、sessions最终汇总到MigrationResult.operations字典这就是任务结果中migrated.operations各项计数的来源。幂等性_copy_path在目标文件已存在时记录skippedreason 为target already exists; kept existing target而不是覆盖skill 复制同样以skip_tree_if_target_existsTrue跳过已有同名 skill。向量索引不重新向量化只重写 URI迁移会一并处理已有向量索引对实际复制成功的 memory / resource / skill 文件或目录直接读取旧记录中的vector/sparse_vector和标量字段重写 URI 后写入新记录。迁移不会重新向量化也不会自动调用reindex。共享 legacy agent 数据复制到多个 user 时会按每个目标 user URI 写入多份向量记录。实现位于 openviking/storage/vector_migration.pycopy_vector_recordsL200-L262通过_records_in_scope按 URI scope 过滤旧向量记录调用rewrite_vector_record保留vector/sparse_vectorpayload仅重写uri、id、account_id、owner_user_id、owner_space、context_type等字段后upsert到新 URI。对level为 0/1 的摘要型记录abstract / content会进一步用rewrite_viking_uri_references和rewrite_abstract_overview_for_transfer重写正文中嵌套的viking://引用避免迁移后正文链接指向旧路径。每个 scope 的向量记录上限为_MAX_VECTOR_RECORDS_PER_SCOPE 100_000vector_migration.py超过时会产生 warning 提示需手动 reindex。没有向量 payload 的旧标量记录会跳过并计入migrated.skipped_vector_records_has_vector_payload只检查vector/sparse_vector字段。Session 迁移只复制文件状态不处理向量索引——这一点在_copy_vectors中显式判断if operation.category sessions ... returnlegacy_migration.py。Session owner 解析顺序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 无法识别 ownerpreflight 会失败。升级后的运行期兼容可以临时读取旧 session但正式迁移前仍应补齐 owner。源码中_session_ownerlegacy_migration.py正是按created_by_user_id→user_id/owner_user_id/created_by的顺序读取.meta.json_looks_like_session_dir则通过.meta.json、messages.jsonl、history、tool-results、tools等文件判断目录是否为 session。Legacy agent instructions 不迁移viking://agent/agent_id/instructions迁移会记录 warning不创建替代目录见 _plan_agent_tree 中对instructions路径的处理。迁移前检查以下问题会在 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。源码中_ensure_plan_userlegacy_migration.py会先校验 user_id 合法性非法 id 进入plan.errors再检查用户是否已存在不存在则加入plan.created_usersrun()阶段对每个自动创建的用户执行register_user并调用initialize_user_directories初始化用户目录。如果开启了api_key_hashing明文 key 无法从存储中反查。需要重新生成ov --sudo admin regenerate-key account_id user_id验证迁移结果查看任务结果ov --sudo task status task_id重点看migrated.files/migrated.directoriesmigrated.vector_records/migrated.skipped_vector_recordsmigrated.operationsskippedwarningscreated_users这些字段的结构与 MigrationResult.to_dict 一一对应migrated下包含files、directories、vector_records、skipped_vector_records和按类别排序的operations字典顶层还有skipped、warnings、created_users。验证新路径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。仓库测试 tests/server/test_admin_api.py 覆盖了共享 agent 数据扇出、skill 迁移、session 迁移以及 “Skipped legacy instructions” warning 等场景可作为验证行为是否符合预期的参照。业务用法迁移Client 配置旧配置可以先继续用{ agent_id: legacy-agent }推荐逐步改成{ actor_peer_id: legacy-agent }不要同时配置{ actor_peer_id: customer-a, agent_id: legacy-agent }这会报错。actor_peer_id通过 openviking/core/peer_id.py 的normalize_peer_id校验与归一化任何空值或非法格式都会被拒绝因此旧agent_id与新的actor_peer_id二选一是硬约束而非建议。文件路径旧路径viking://agent/code-agent/memories/profile.md viking://session/sess-001/messages.jsonl新路径viking://user/alice/peers/code-agent/memories/profile.md viking://user/alice/sessions/sess-001/messages.jsonlviking://session/session_id可以继续作为当前 user session 的读 alias 使用但新写入和长期引用建议使用viking://user/user_id/sessions/session_id。从 openviking/core/namespace.py 可以看到canonical_session_uri生成的规范路径始终位于viking://user/user_id/sessions/之下同时resolve_uri对顶层sessionscope 会抛出NamespaceShapeError“Legacy session URI is not canonical”说明旧 session URI 只在请求边界resolve_request_uri/resolve_current_user_uri作为 alias 解析内部存储与写入一律使用规范化新路径。find / searchfind/search不再接受 legacy agent 身份字段也不会自动包含未迁移的旧 agent 数据。旧viking://agent/...路径仍可通过内容和文件系统接口只读访问但应先完成迁移再使用新检索路径。迁移完成并确认不再需要旧 agent 数据后所有 client 都改为 client/request 级actor_peer_id。会话消息Session 不再从 legacy agent id 推导消息归属需要表达说话人时必须显式使用 messagepeer_id。暂不迁移数据升级后可以暂时不迁移但要知道这些限制旧 agent/session 数据可读但旧 namespace 不可写。新 session 和新资源会写入新 namespace数据会在新旧路径并存一段时间。find/search不会默认查旧viking://agent数据。多用户 account 下 owner 不明确的旧 session运行期可能可读但正式迁移会被 preflight 拦截。cleanup 之前旧目录和旧向量记录仍会保留。因此不迁移适合作为短期过渡不建议作为长期状态。可选 cleanup确认迁移结果无误后可以删除旧 namespaceov --sudo admin migrate --cleanup --output json ov --sudo task status cleanup_task_idHTTP 请求体{ action: cleanup }Cleanup 只删除/local/account/agent /local/account/session /local/account/user/user/agentCleanup 会先删除上述 legacy URI scope 下的旧向量记录再删除对应 AGFS 目录。若向量读取或删除失败该目录会被跳过避免旧文件已删除但旧索引仍残留。这一顺序在 legacy_migration.py 的cleanup()中体现先_delete_vectors(target)并累加result.vector_records若vector_result.failed则将目标记入 skippedreason 为vector cleanup failed并跳过目录删除删除向量成功后才执行_agfs.rm(target.source_path, recursiveTrue)。Cleanup 不会删除新 user / peer 路径下的文件或向量记录。不会删除的新模型目录/local/account/user/user/peers /local/account/user/user/sessions /local/account/user/user/skills另外注意cleanup 规划器同样受_AGENT_RESERVED_SUBDIRS保护/local/account/agent下的skills、endpoints、tools、payments不会被当作 legacy agent 删除_cleanup_preflight。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。实现依据见上文对is_accessible与is_hidden_by_actor_peer_view的分析openviking/core/namespace.py。ov ls viking://session 仍为空确认服务端已经重启并加载 0.4.0。viking://session的合并读发生在服务端只升级 CLI 不会改变服务端读取行为。旧 session 的兼容读位于请求边界解析层namespace.py只有运行 0.4.0 的服务端才会执行该解析。配置同时有 actor_peer_id 和 agent_id这是不允许的。保留agent_id进入 legacy 模式或删除agent_id后改用actor_peer_id。Preflight 报告 unknown account物理存储中存在某个 account 的 legacy 数据但 API key registry 中没有这个 account。先恢复或重新创建该 account再重新执行迁移。对应的 preflight 检查位于 legacy_migration.py遍历物理存储的 account 与 registry 的 account 差集若该 account 存在 legacy 数据则记录 error。Preflight 报告 unresolved session owner给 legacy session 的.meta.json补充 owner 字段或把 session 移到能明确识别 owner 的旧路径下然后重新执行迁移。可补充的字段包括created_by_user_id、user_id、owner_user_id或created_by并按上述解析顺序读取。某个 skill 没有迁移查看 task 的skipped列表。最常见原因是目标 user 已经存在同名 skill。迁移不会覆盖现有 skill——目标已存在时规划器直接将该操作标记为 skipped 而不生成TreeCopy_plan_agent_skills。小结0.3.x 到 0.4.0 的升级本质上是数据所有权模型的升级从全局agent/sessionnamespace 收敛为User → Peer / Session / Skill的归属结构。本文给出的完整路径——备份、升级、兼容验证、preflight 检查、后台迁移任务、结果核验、业务代码切换、可选 cleanup——每一步都有对应的源码实现legacy_migration.py、vector_migration.py、namespace.py、admin.py与测试用例tests/server/test_admin_api.py作为依据。迁移不重新向量化、幂等可重跑、cleanup 先删索引再删目录等设计保证了整个升级过程在旧数据仍可读的前提下平滑推进。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考