OpenViking OVPack：.ovpack 数据包的导入导出与备份恢复完整实践-北京尧图网络

OpenViking OVPack.ovpack 数据包的导入导出与备份恢复完整实践【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOVPack 是 OpenViking 提供的数据迁移与备份机制用于将 Viking URI 下的资源树打包为.ovpack文件并在目标环境完整恢复。本文基于 OVPack API 文档与仓库源码讲清四个核心接口export / import / backup / restore的参数、冲突与向量策略并深入.ovpack文件的内部格式、完整性校验与源码调用链读完后可独立完成 OpenViking 数据的迁移、备份与恢复。一、OVPack API 总览OVPack API 挂载在/api/v1/pack路由下见路由定义共提供四个接口覆盖导出—导入—备份—恢复完整链路接口路径用途权限要求export_ovpackPOST /api/v1/pack/export将指定 URI 下资源导出为.ovpack文件流ROOT / ADMIN / USERimport_ovpackPOST /api/v1/pack/import将.ovpack文件导入到指定父级 URIROOT / ADMIN / USERbackup_ovpackPOST /api/v1/pack/backup将全部公开 scope 备份为 restore-only 包仅 ROOT / ADMINrestore_ovpackPOST /api/v1/pack/restore恢复 backup 生成的备份包到原始 scope root仅 ROOT / ADMIN从源码结构看权限控制在路由层通过装饰器实现export 和 import 使用require_auth_role(Role.ROOT, Role.ADMIN, Role.USER)而 backup 与 restore 使用更严格的require_auth_root_or_admin见 pack.py 路由与 backup 路由。服务层PackService在 backup/restore 时还会通过_account_maintenance_ctx将 ADMIN 上下文的角色提升为 ROOT 执行账号级维护但保持 URI 归属不变见 PackService。二、.ovpack 文件格式解剖.ovpack本质是一个 ZIP 压缩包导出时用户内容原样放在root/files/下内部元数据放在root/_ovpack/下。这些目录名在 format.py 中定义为常量OVPACK_INTERNAL_DIR _ovpack、OVPACK_FILES_DIR files包的类型标识为kind: openviking.ovpack。包内关键文件文件作用root/_ovpack/manifest.json包清单含format_version、kind、root、entries、index等字段root/_ovpack/index_records.jsonl可迁移的索引标量记录每行一个 JSON 对象root/_ovpack/dense.f32仅当include_vectorstrue时存在纯 dense float32 向量快照little-endianroot/files/...用户内容文件路径相对于导出 rootmanifest 的核心语义来自 manifest.py 与 format.pyentries[].path是相对导出 root 的路径空字符串表示 root 目录本身每个条目kind必须是directory或file。文件条目包含size和sha256整体content_sha256是对按路径排序后的文件列表path、size、sha256做规范化 JSON 序列化后的 SHA-256实现见 manifest_content_sha256。id、uri、account_id、created_at、updated_at、active_count等运行态字段会在目标环境重新生成不从包内恢复——这是迁移不产生 ID 冲突的关键设计。当前支持的format_version为3OVPACK_FORMAT_VERSION 3见 format.py。导入时版本不匹配会被直接拒绝错误信息会同时给出包内版本与当前支持版本见 read_manifest。OVPack 不额外设置包大小、文件数量或目录深度上限实际可处理规模由 ZIP、存储后端和运行环境决定。安全方面导入时对 ZIP 成员路径做了严格校验拒绝反斜杠、绝对路径、Windows 盘符、..逃逸段并要求所有条目位于base_name/之下见 validate_ovpack_member_path防止恶意构造的包污染存储目录。三、export_ovpack导出资源树处理流程验证用户权限 → 遍历指定 URI 下的资源 → 写入内容文件和 manifest → 打包成 zip.ovpack→ 以文件流形式返回。参数参数类型必填默认值说明uristring是-要导出的 Viking URIinclude_vectorsboolean否false导出纯 dense 向量快照底层 index type 为 hybrid 时会拒绝权限要求ROOT、ADMIN 或 USER且仍受常规 URI 访问控制约束。使用示例HTTP APIcurl -X POST http://localhost:1933/api/v1/pack/export \ -H Content-Type: application/json \ -H X-API-Key: your-admin-key \ -d { uri: viking://resources/my-project/, include_vectors: false } \ --output my-project.ovpack此接口直接返回文件流Content-Type: application/zip不返回 JSON 包装体。从源码看路由层先把包写入临时文件export_随机hex.ovpack再经FileResponse流式返回文件名取 URI 末段并补.ovpack后缀响应完成后通过BackgroundTask清理临时文件见 export_ovpack 路由。CLI# 导出资源 ov export viking://resources/my-project/ ./exports/my-project.ovpack # 导出 dense 向量快照 ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectorsTypeScript SDKconst outputPath await client.exportOVPack( viking://resources/docs/, ./exports/docs.ovpack, true, ); console.log(outputPath);Go SDKoutPath, err : client.ExportOVPack( ctx, viking://resources/my-project/, ./exports/my-project.ovpack, openviking.PackOptions{IncludeVectors: false}, ) if err ! nil { return err } fmt.Println(outPath)Python SDKHTTP SDK 会自动处理下载导出功能也主要通过 CLI 使用import openviking as ov client ov.SyncHTTPClient(urlhttp://localhost:1933, api_keyyour-admin-key) client.initialize()CLI 端ov export命令由 handle_export 接收入口统一转发到 HTTP 客户端的 pack 命令模块。四、import_ovpack导入与迁移处理流程验证用户权限 → 解析上传的.ovpack文件 → 校验 manifest 元数据、路径、文件和目录集合、文件大小和 checksum → 应用on_conflict→ 导入资源到目标位置并重建向量。参数参数类型必填默认值说明temp_file_idstring是-临时上传文件 ID通过 temp_upload 获取parentstring是-目标父级 URI导入到此处on_conflictstring否fail冲突策略fail、overwrite或skipvector_modestring否auto向量处理方式auto、recompute或require权限要求ROOT、ADMIN 或 USER。请求模型对额外字段采用extraforbid策略API 已不再接受旧的vectorize或force参数见 ImportRequest。向量处理策略 vector_modeauto存在兼容 dense 快照时直接恢复否则重新向量化recompute总是忽略包内向量重新计算require要求必须存在兼容 dense 快照否则导入失败。dense 快照的兼容性会比较 embedding provider、model、input、query/document 参数和维度。从源码看这些元数据在导出时由 embedding_snapshot_metadata 从当前 embedding 配置中采集provider、model、input、query_param、document_param、dimensions导入时逐一比对任何一项不一致都视为不兼容。完整性与冲突行为导入校验相当严格以下情况都会被拒绝没有 manifest 的包无法提供内容完整性校验带 manifest entries 的包缺少内容文件或目录、混入额外文件或目录、文件大小不同、单文件sha256不同或整体content_sha256缺失/不匹配manifestformat_version不是当前支持版本3的包viking://resources/这类顶级 scope 包必须导入到viking://。冲突策略root 级on_conflictfail默认目标 root 已存在时返回结构化的409 CONFLICTon_conflictoverwrite替换已有目标 rooton_conflictskip保留已有目标 root直接返回该路径不写入包内容。注意skip是 root 级跳过不是文件级补齐。其他行为细节Session 文件属于 user 命名空间viking://user/{user_id}/sessions/...恢复后不触发向量化.abstract.md和.overview.md作为语义侧边文件一并恢复.relations.json和 OVPack 内部文件_ovpack/会被排除manifest index 标量中的context_type如果存在必须和最终导入路径语义一致OVPack 不额外设置导入包大小、文件数量或目录深度上限。使用示例HTTP API两步先 temp_upload 再 import# 第一步上传 .ovpack 文件 TEMP_FILE_ID$( curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \ -H X-API-Key: your-admin-key \ -F file./exports/my-project.ovpack \ | jq -r .result.temp_file_id ) # 第二步导入 curl -X POST http://localhost:1933/api/v1/pack/import \ -H Content-Type: application/json \ -H X-API-Key: your-admin-key \ -d { \temp_file_id\: \$TEMP_FILE_ID\, \parent\: \viking://resources/imported/\, \on_conflict\: \overwrite\, \vector_mode\: \auto\ }CLI# 导入 .ovpack 文件 ov import ./exports/my-project.ovpack viking://resources/imported/ # 显式冲突策略 ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite # 要求恢复兼容 dense 向量快照 ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode requireTypeScript SDKconst uri await client.importOVPack( ./exports/docs.ovpack, viking://resources/, { onConflict: overwrite, vectorMode: auto, }, ); console.log(uri);Go SDKuri, err : client.ImportOVPack( ctx, ./exports/my-project.ovpack, viking://resources/imported/, openviking.ImportPackOptions{ OnConflict: overwrite, VectorMode: auto, }, ) if err ! nil { return err } fmt.Println(uri)响应示例{ status: ok, result: { uri: viking://resources/imported/my-project/ }, telemetry: { operation_id: 550e8400-e29b-41d4-a716-446655440000 } }冲突错误示例{ status: error, error: { code: CONFLICT, message: Resource already exists at viking://resources/imported/my-project. Use on_conflictoverwrite to replace it., details: { resource: viking://resources/imported/my-project } } }从源码看import 路由先用TempUploadStore.resolve_for_consume把temp_file_id解析为本地文件并校验归属导入完成后在finally中清理临时文件见 import_ovpack 路由临时上传本身有独立的 temp_upload 接口可查。五、backup_ovpack账号级全量备份backup_ovpack将公开 scope root 备份为只能通过 restore 恢复的.ovpack文件。备份包含resources全部公开资源当前账号下所有user/{user_id}内容session 通过 user 命名空间下的user/{user_id}/sessions一起包含。不包含temp、queue等内部运行态数据也不包含用户账号或 API Key。该接口仅允许 ROOT 或 ADMIN 调用。设置include_vectorstrue时额外导出兼容的纯 dense 向量快照底层 index type 为 hybrid 时会拒绝导出向量快照。从源码看这个限制由 ensure_dense_snapshot_supported 实现它读取向量索引元数据中的VectorIndex.IndexType一旦包含hybrid即抛出 ovpack vector snapshots only support pure dense vector indexes 错误。重要限制备份是在线逐文件读取不保证同一时刻的原子快照。需要严格一致性时调用方应在备份窗口暂停写入。使用示例HTTP APIcurl -X POST http://localhost:1933/api/v1/pack/backup \ -H Content-Type: application/json \ -H X-API-Key: your-admin-key \ -d {include_vectors:false} \ --output openviking-backup.ovpackGo SDKoutPath, err : client.BackupOVPack( ctx, ./backups/openviking.ovpack, openviking.PackOptions{IncludeVectors: true}, ) if err ! nil { return err } fmt.Println(outPath)CLIov backup ./backups/openviking.ovpack ov backup ./backups/openviking.ovpack --include-vectors响应HTTP 成功时返回application/zip字节流不使用标准 JSON 响应包HTTP/1.1 200 OK Content-Type: application/zip Content-Disposition: attachment; filenameopenviking-backup.ovpack ovpack binary bodyGo SDK 和 CLI 将字节流写入指定路径并返回或输出该本地路径。六、restore_ovpack备份恢复restore_ovpack恢复backup_ovpack生成的备份包到原始公开 scope root普通 import 不接受备份包。该接口仅允许 ROOT 或 ADMIN 调用并恢复当前账号下包内所有用户路径。向量处理遵循vector_modeuser 命名空间下的 session 文件只恢复文件状态不触发向量化。参数参数类型必填默认值说明temp_file_idstring是-临时上传文件 IDon_conflictstring否fail冲突策略fail、overwrite或skipvector_modestring否auto向量处理方式auto、recompute或require合并覆盖语义on_conflictoverwrite使用合并覆盖包内缺失于目标的路径会创建同路径会覆盖目标独有路径会保留不会删除整个viking://resources或viking://user。向量只更新包内新增或覆盖的内容。skip仍是 scope root 级跳过但返回前也会完整校验 manifest、内容 checksum 和向量元数据——损坏的备份不会因为skip而返回成功。账号前提OVPack 不创建用户账号或恢复 API Key。新环境恢复后需要使用包内相同的user_id创建用户并使用目标环境新生成的 API Key。使用示例HTTP APITEMP_FILE_ID$( curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \ -H X-API-Key: your-admin-key \ -F file./backups/openviking.ovpack \ | jq -r .result.temp_file_id ) curl -X POST http://localhost:1933/api/v1/pack/restore \ -H Content-Type: application/json \ -H X-API-Key: your-admin-key \ -d {\temp_file_id\:\$TEMP_FILE_ID\,\on_conflict\:\overwrite\,\vector_mode\:\auto\}Go SDKuri, err : client.RestoreOVPack( ctx, ./backups/openviking.ovpack, openviking.ImportPackOptions{ OnConflict: overwrite, VectorMode: require, }, ) if err ! nil { return err } fmt.Println(uri)CLIov restore ./backups/openviking.ovpack --on-conflict overwrite ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require响应{ status: ok, result: { uri: viking:// } }uri是备份恢复到的公开 scope root。七、源码调用链速览从源码结构看OVPack 的完整调用链为三层HTTP 路由openviking/server/routers/pack.py └─ PackServiceopenviking/service/pack_service.py └─ openviking/storage/ovpack/operations.py ├─ format.py # ZIP 路径、checksum、路径安全校验 ├─ manifest.py # manifest 解析与结构校验 ├─ index.py # 索引标量记录 ├─ policy.py # root/scope 策略 ├─ validation.py # 内容完整性校验 └─ vectors.py # dense 快照与兼容性 CLIcrates/ov_cli/src/handlers.rshandle_export / handle_import / handle_backup / handle_restore关键实现细节对应关系导出/备份流式返回路由层生成随机临时文件 →FileResponse以application/zip流式下发 →BackgroundTask清理见 pack.py备份/恢复提权_account_maintenance_ctx仅允许 ROOT/ADMIN并将执行上下文角色提升为 ROOT 以覆盖账号下全部 user 命名空间见 pack_service.py格式版本硬约束format_version ! 3的包直接拒绝避免跨版本数据损坏见 manifest.py;混合索引保护hybrid 索引下禁用向量快照导出防止快照语义失真见 vectors.py。八、相关文档OVPack 指南 - 格式、迁移和操作流程快照 - 工作区版本管理临时上传 - 上传待导入的包【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenViking OVPack：.ovpack 数据包的导入导出与备份恢复完整实践

相关推荐

CPython 3.16 新特性：--with-build-details-suffix 配置项与 build-details.json 多版本并存安装方案

CPython frozenset 构造性能优化：避免复制，让 frozenset(frozenset) 直接复用原对象

深入理解Go的panic、defer与recover：运行时协作机制与工程实践

更多资讯

Postmortem: [Incident Title]

5分钟用Semgrep静态代码分析找出硬编码密钥：新手快速上手指南

AI搜索优化完全指南：从传统SEO到AEO/GEO的实战方法论

数据迁移工具全解析：从原理选型到DataX与CDC实战

Magnitude不是CLI工具：词向量检索库的真相与实战

AI代理安全加固：用E2B沙箱和Firecracker微虚拟机隔离OpenClaw风险

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？