OpenViking 系统状态 API 详解health、ready、consistency 与多写后端同步管理【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文基于 OpenViking 官方 API 文档 System Status系统讲解其 System API 的六个端点/health、/ready、/api/v1/system/status、/api/v1/system/consistency、/api/v1/system/wait以及多写后端同步的sync-status/sync-retry。读完本文你将掌握 OpenViking 服务的健康检查、Kubernetes 就绪探测、文件系统/向量索引一致性诊断、异步任务等待以及需要 ROOT/ADMIN 权限的后端同步重试的完整调用方式HTTP、Python/TypeScript/Go SDK、Rust CLI并能结合服务端源码理解每个检查项的实际探测逻辑。整体定位System API 覆盖什么OpenViking 的 System API 提供健康检查health、就绪探测readiness、**数据一致性consistency和多写后端同步状态multi-write backend sync**四类能力。服务端实现集中在 system.pyRust CLI 的ov system子命令实现于 system.rsPython SDK 入口为openviking_cli/client/sync_http.py中兼容路径SyncHTTPClient实际委托给 openviking_sdk/client.py 中的SyncHTTPClient。组件观察者observer与 Prometheus 指标在 Runtime Observability 与 Metrics 中单独记录。health基础健康检查与请求级性能剖析接口说明GET /health是基础健康检查端点无需认证返回服务版本与健康状态如果请求携带了认证信息还会额外返回认证模式与身份信息。从 system.py 源码看端点首先构造{status: ok, healthy: True, version: __version__}再从request.app.state.config读取生效的认证模式写入auth_mode当请求头带X-API-Key或Authorization时调用resolve_identity解析出account_id、user_id和role解析失败只记录告警而不影响健康状态本身。profile 参数请求级 cProfile 剖析参数类型必填默认说明profilestring否-取值为1、true、yes或on时开启当前请求的cProfile并在 JSON 响应中追加profile字段profile的行为有五个关键约束源码位于 profile_middleware.py它在HTTP 中间件层实现对任何返回 JSON 的 OpenViking 端点都有效不限于/health仅当服务端在ov.conf中启用server.profile_enabled true时才生效否则profile1会被忽略。源码中的profile_enabled(request)函数首先检查server_config.profile_enabled开关该字段定义于 config.py再匹配 query 参数是否属于真值集合剖析只作用于当前请求请求结束自动关闭后续请求不会继承中间件只向 JSON 响应注入profile字段纯文本、文件、流式响应保持原样返回值是list[string]每个元素是一行格式化后的pstats输出便于浏览器 JSON 查看器和逐行 UI 渲染。调用方差异ovCLI 会展示返回的profile内容Python HTTP 客户端可以通过ovcli.conf.profile true触发服务端剖析但大多数 SDK 方法只返回业务result不直接暴露顶层profile字段。profile各列含义标准 cProfile 语义列含义ncalls调用次数显示为total/primitive时前者是总调用后者是原始非递归展开调用tottime函数体自身耗时不含子调用percall第一列tottime / ncalls单次调用的平均自身耗时cumtime含所有子调用的累计耗时percall第二列cumtime / primitive calls单次原始调用的平均累计耗时filename:lineno(function)函数位置普通 Python 代码显示裁剪后的模块路径~:0(...)形式通常表示内建或原生扩展调用使用示例HTTP APIcurl -X GET http://localhost:1933/healthcurl -G http://localhost:1933/health \ --data-urlencode profile1Python SDKimport openviking as ov client ov.SyncHTTPClient(urlhttp://localhost:1933) client.initialize() healthy client.health() print(fHealthy: {healthy})TypeScript SDKconsole.log(await client.health());Go SDKhealthy, err : client.Health(ctx) if err ! nil { return err } fmt.Println(healthy)CLIov system health # 带请求级剖析 ov --profile health响应示例{ status: ok, healthy: true, version: 0.1.x, auth_mode: api_key }带profile的响应示例{ status: ok, healthy: true, version: 0.1.x, profile: [ 325 function calls (310 primitive calls) in 0.004 seconds, , Ordered by: cumulative time, List reduced from 87 to 87 due to restriction 100, , ncalls tottime percall cumtime percall filename:lineno(function), 1 0.000 0.000 0.003 0.003 starlette/middleware/base.py:112(call_next), 1 0.000 0.000 0.001 0.001 openviking/server/routers/system.py:39(health_check), 3 0.000 0.000 0.000 0.000 ~:0(method read of builtins.RAGFSBindingClient objects) ] }ready面向部署环境的就绪探测接口说明GET /ready是就绪探测readiness probe为 Kubernetes 等部署环境设计无需认证。全部已配置子系统就绪时返回 200否则返回 503。检查项文档口径检查项说明agfsViking 文件系统是否可访问vectordb向量数据库是否健康api_key_managerAPI key 管理器是否已加载ollamaOllama 服务是否可达仅当已配置时结合 system.py 的实现可以看到更完整的探测细节若服务仍在初始化service._initialized为假或 service 尚未设置立即返回503 {status: not_ready, reason: initializing}agfs探测分两步先ls(viking://)验证文件系统可访问再调用system_sync_status(viking://)验证多写同步健康后者抛AGFSInvalidOperationError/AGFSNotSupportedError时标记为not_supported对单写后端是合法状态vectordb通过向量存储的health_check()判断无存储时标记not_configured除文档列出的四项外实现中还包含一个embedding 快速探针调用embed_compat嵌入单个 token验证 embedding provider 可达探针超时上限 10 秒就绪判定由_is_ready_check_ok递归完成ok、not_configured、not_supported均视为健康嵌套的checks结构需逐项全过。使用示例curl -X GET http://localhost:1933/ready响应示例{ status: ready, checks: { agfs: ok, vectordb: ok, api_key_manager: ok, ollama: not_configured } }status初始化状态与多租户身份解析接口说明GET /api/v1/system/status返回系统初始化状态与当前认证用户信息。需要特别强调文档中的语义result.user是当前认证请求的user_id来自 API key 或请求头而不是进程级的服务默认值——客户端可以据此解析多租户路径例如 OpenClaw 插件场景。源码中该端点通过Depends(get_request_context)拿到ctx直接返回{initialized: service._initialized, user: ctx.user.user_id}。使用示例HTTP APIcurl -X GET http://localhost:1933/api/v1/system/status \ -H X-API-Key: your-keyPython SDKstatus client.get_status() print(status)TypeScript SDKconsole.log(await client.getStatus());CLIov system status响应示例{ status: ok, result: { initialized: true, user: alice }, time: 0.1 }consistency文件系统/向量索引一致性检查接口说明POST /api/v1/system/consistency对指定 URI 子树做文件系统与向量索引的一致性检查。文档明确其定位这是一个通用的数据一致性 API用于排查索引记录缺失、向量快照导出失败等问题并非 OVPack 私有接口——ov export --include-vectors与ov backup --include-vectors内部复用同一检查逻辑。响应只返回摘要与缺失记录不返回完整期望记录列表missing_records最多包含前 20 条超出时missing_records_truncated为true。参数类型必填默认说明uristring是-待检查的 Viking URI 子树从源码看端点先经resolve_path_variables与validate_request_viking_uri对 URI 做路径变量解析和合法性校验再委托service.check_consistency执行实际比对。CLI 侧在 system.rs 中提供了表格化输出--format table时先渲染摘要表ok、expected_count、missing_record_count、missing_records_truncated若存在缺失记录则追加missing_records明细表。使用示例HTTP APIcurl -X POST http://localhost:1933/api/v1/system/consistency \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {uri:viking://resources/my-project}Python SDKreport client.check_consistency(uriviking://resources/my-project) print(report[ok]) print(report[missing_records])TypeScript SDKconsole.log(await client.checkConsistency(viking://resources/));Go SDKreport, err : client.CheckConsistency(ctx, viking://resources/my-project) if err ! nil { return err } fmt.Println(report[ok])CLIov system consistency viking://resources/my-project响应示例{ status: ok, result: { ok: false, expected_count: 3, missing_record_count: 1, missing_records_truncated: false, missing_records: [ { uri: viking://resources/my-project/README.md, path: README.md, level: 2, key: README.md#level2 } ] } }wait_processed等待异步处理完成接口说明POST /api/v1/system/wait阻塞等待所有异步处理embedding、语义生成完成直到队列清空或超时。在批量导入资源的脚本流程中这是确认数据真正可检索的关键卡点源码中该端点直接委托service.resources.wait_processed(timeout...)。参数类型必填默认说明timeoutfloat否None超时秒数None 表示无限等待使用示例HTTP APIcurl -X POST http://localhost:1933/api/v1/system/wait \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d { timeout: 60.0 }Python SDK# 添加资源 client.add_resource(path./docs/) # 等待所有处理完成 status client.wait_processed(timeout60.0) print(fProcessing complete: {status})TypeScript SDKconsole.log(await client.waitProcessed(60));Go SDKstatus, err : client.WaitProcessed(ctx, openviking.WaitProcessedOptions{ Timeout: openviking.Float64(60), }) if err ! nil { return err } fmt.Println(status)CLIov system wait --timeout 60响应示例按任务类型分组返回 processed / requeue / error 统计{ status: ok, result: { Embedding: { processed: 10, requeue_count: 0, error_count: 0, errors: [] }, Semantic: { processed: 10, requeue_count: 0, error_count: 0, errors: [] } }, time: 0.1 }多写后端同步sync-status 与 sync-retry当 Viking 文件系统配置了多写后端时写入会异步同步到各后端。两个管理端点用于查询与重试该同步过程均要求 ROOT 或 ADMIN 权限源码中通过require_role(Role.ROOT, Role.ADMIN)强制校验。backend_sync_status()查询指定 URI 子树的多写后端同步状态委托service.fs.system_sync_status。HTTP API请求体形式curl -X POST http://localhost:1933/api/v1/system/backend/sync-status \ -H Content-Type: application/json \ -H X-API-Key: your-admin-key \ -d {uri:viking://resources}URI 路径形式GET /api/v1/system/sync/{sync_path}CLIov system backend sync-status viking://resources响应示例{ status: ok, result: { path: viking://resources, entry_count: 12 } }result由当前活动的文件系统后端提供path标识查询范围entry_count是该范围内的同步记录数后端可以追加 pending、failed 等诊断字段。backend_sync_retry()对指定 URI 子树中未完成的多写后端同步工作发起重试委托service.fs.system_sync_retry。HTTP API请求体形式curl -X POST http://localhost:1933/api/v1/system/backend/sync-retry \ -H Content-Type: application/json \ -H X-API-Key: your-admin-key \ -d {uri:viking://resources}URI 路径形式POST /api/v1/system/sync/{sync_path}/retryCLIov system backend sync-retry viking://resources响应示例{ status: ok, result: { path: viking://resources, retried: 2, failed: 0 } }其中retried是本次请求重新调度的记录数failed是无法调度的记录数后端同样可附加诊断字段。需要说明官方 Python、TypeScript 和 Go SDK 目前未暴露多写后端同步方法因此这部分只能通过 HTTP API 或 CLI 调用。SDK 与 CLI 入口速查端点HTTPPython SDKTypeScript SDKGo SDKCLIhealthGET /healthclient.health()client.health()client.Health(ctx)ov system healthreadyGET /ready----statusGET /api/v1/system/statusclient.get_status()client.getStatus()-ov system statusconsistencyPOST /api/v1/system/consistencyclient.check_consistency(uri...)client.checkConsistency(uri)client.CheckConsistency(ctx, uri)ov system consistency uriwaitPOST /api/v1/system/waitclient.wait_processed(timeout...)client.waitProcessed(timeout)client.WaitProcessed(ctx, opts)ov system wait --timeout ssync-statusPOST /api/v1/system/backend/sync-status---ov system backend sync-status uriROOT/ADMINsync-retryPOST /api/v1/system/backend/sync-retry---ov system backend sync-retry uriROOT/ADMIN典型运维排障组合服务启动后用curl http://localhost:1933/health快速确认进程存活与版本在 Kubernetes 中则将/ready配置为 readiness probe避免流量打到未初始化完成的实例初始化期间/ready会稳定返回 503。检索结果缺失时先ov system wait --timeout 60确认异步处理已排空再对可疑子树执行ov system consistency viking://resources/...根据missing_records中每条记录的uri与key如README.md#level2定位缺失的层级索引。配置多写后端后用ov system backend sync-status uri查看entry_count与后端追加的 pending/failed 诊断发现积压时用ov system backend sync-retry uri重放注意两步均需要 ADMIN 级 API key。接口性能定位在ov.conf开启server.profile_enabled true后对任意 JSON 端点附加?profile1或 CLI 使用ov --profile cmd直接获得该请求的函数级耗时剖析。相关文档Resources - 资源管理Retrieval - 搜索与检索Sessions - 会话管理Runtime Observability - 组件实时状态观察Metrics - Prometheus 指标【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考