OpenViking ovpack 打包：导出/导入整套上下文数据的完整指南-开发者社区

OpenViking ovpack 打包：导出/导入整套上下文数据的完整指南

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 是面向 AI 智能体的开源上下文数据库，把 Agent 的记忆、知识 RAG 和技能统一存放在viking://虚拟文件系统中。当你需要备份、迁移或交接这些上下文数据时，OpenViking 提供了 ovpack 打包格式——用ov export/ov import两条命令，就能把整套资源、记忆和会话数据导出为一个.ovpack文件，再无损地导入到另一套环境中。本文手把手带你掌握这套完整的导出/导入流程。

什么是 ovpack？一个文件装下整套上下文

在 OpenViking 中，所有内容都挂在viking://协议下：项目文档在viking://resources/...，用户记忆在viking://user/{user_id}/memories/...，会话数据在viking://user/{user_id}/sessions/...。

ovpack（OVPack v3 格式）就是为这套内容树设计的可恢复内容包：一个标准 ZIP 文件，里面不仅保存文件内容，还保存了语义侧边文件（.abstract.md摘要、.overview.md概览）、可迁移的索引标量，以及可选的 dense 向量快照。

它不是简单的裸 ZIP 拷贝。导入时会完整校验 manifest、文件列表、目录列表和 checksum，保证包内容没有被篡改或混入额外文件。

导出前先看一眼：确认要打包的目录

动手打包前，建议先用ov ls浏览一下viking://目录结构，确认导出范围：

快速开始：ov export 与 ov import 两条命令

导出一个资源目录树，只需一行命令：

ov export viking://resources/my-project ./exports/my-project.ovpack

导入到目标环境时，第二个参数是目标父目录，不是最终 root：

ov import ./exports/my-project.ovpack viking://resources/imported/

假设包根名是my-project，导入后会落在viking://resources/imported/my-project。如果目标位置已存在同名目录，加上冲突策略即可覆盖：

ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite

三条实用规则：

📁 普通子树包只能导入到同 scope的父目录（resources包不能导入user）；
🏷️ 顶级 scope 包（如整个viking://resources）只能导入到viking://根；
💾 记忆和 Session 有固定结构，导入到对应目录的父目录避免路径重复，例如viking://user/alice/sessions/。

全量备份与恢复：ov backup / ov restore

要整站迁移（资源 + 当前账号下所有用户内容 + 会话），不要用export viking://，而是使用专门的备份包：

ov backup ./backups/openviking.ovpack ov restore ./backups/openviking.ovpack --on-conflict overwrite

注意两点：

备份包只能通过ov restore恢复，普通import会拒绝它；
备份是线上逐文件读取，非原子快照；备份期间仍在变化的内容可能来自不同时间点，严格一致性场景建议在备份窗口暂停写入。

backup/restore仅允许 ROOT 或 ADMIN 调用，且备份包不包含账号、API Key 等鉴权数据。

向量怎么迁？--include-vectors 与 --vector-mode 决策

默认导出不保存dense 向量，导入后由目标环境重新向量化——这是最稳妥的默认行为。当确认两端 embedding 配置一致、又想加快冷迁移时，可以显式携带向量快照：

ov export viking://resources/my-project ./exports/my-project.ovpack --include-vectors ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode auto

--vector-mode三种取值：

值	行为
`auto`（默认）	包内有兼容 dense 快照就恢复，否则重新向量化
`recompute`	忽略包内快照，始终重新向量化
`require`	必须恢复兼容快照，缺失或不兼容直接报错

⚠️ 导出向量快照前，OpenViking 会先做数据一致性检查（缺失索引记录会拒绝导出，避免生成不完整迁移包）。可以用下面的命令单独排查：

ov system consistency viking://resources/my-project

另外，当前向量快照仅支持纯 dense 索引；hybrid 索引环境会直接拒绝--include-vectors导出。

冲突策略三选一：fail / overwrite / skip

值	行为
`fail`（默认）	目标 root 已存在时返回 409 CONFLICT
`overwrite`	删除已有 root，重新写入包内容并重建索引
`skip`	目标 root 已存在时直接返回该 URI，不写入任何内容

无论哪种策略，都会先完整校验manifest、文件和 checksum，损坏的包即使用skip也会报错。

包内结构：透明可查，校验严密

.ovpack就是标准 ZIP，可以用普通解压工具查看（但不要手改后导入，会破坏校验）：

my-project/ ├── files/ # 用户内容，路径与 viking:// 下完全一致 │ ├── notes.txt │ ├── .abstract.md │ └── .overview.md └── _ovpack/ ├── index_records.jsonl # 可迁移的索引标量 ├── dense.f32 # 仅 --include-vectors 时出现 └── manifest.json # 文件清单 + checksum

导入会执行 10 项校验：路径合法性、manifest 存在性与版本、root.name与包根一致、文件/目录集合与 manifest 完全匹配、每个文件的 size 与 sha256、内容整体 hash、向量快照元数据、scope 一致性等。校验全部通过前不会写入任何内容。

运行态字段（id、uri、account_id、created_at等）由目标环境重建，用户账号和 API Key 需要在新环境重新创建。

常见报错速查

报错	原因与处理
`Missing ovpack manifest`	旧版无 manifest 包被拒绝；先在可信旧环境导入，再用当前版本重新导出
`sha256 does not match manifest`	文件被改动过；丢弃该包，从可信源重新导出
`source scope does not match target scope`	跨 scope 导入（如 user 导入 resources）；改导入同 scope 父目录
`Resource already exists`	目标 root 已存在；加`--on-conflict overwrite`或`skip`
`Backup ovpack packages must be restored`	备份包要用`ov restore`而非`import`
`dense vector snapshot is incompatible`	embedding 配置不一致；改用`--vector-mode recompute`