OpenViking 系统状态 API 实战指南健康检查、就绪探针、一致性校验与多写同步管理【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 系统 API 面向服务运维与排障场景提供健康检查、就绪检查、系统状态查询、文件系统与向量索引一致性校验、异步任务等待以及多写存储后端同步管理等一系列端点。本文以 docs/zh/api/07-system.md 为骨架结合 system.py、profile_middleware.py 与 ov_cli system 命令 的源码实现完整覆盖每个端点的认证要求、参数语义、HTTP / Python / TypeScript / Go SDK / CLI 五种调用方式读完即可独立完成 OpenViking 服务的探针配置、运行体检与数据一致性排障。一、端点总览系统状态 API 全部实现在openviking/server/routers/system.py挂载路径与功能如下端点方法认证要求用途/healthGET无需认证基础健康检查返回版本号与健康状态/readyGET无需认证就绪探针检查 AGFS、VectorDB、APIKeyManager、Ollama 等子系统/api/v1/system/statusGET需认证系统状态 当前认证用户信息/api/v1/system/consistencyPOST需认证指定 URI 子树文件系统与向量索引一致性检查/api/v1/system/waitPOST需认证等待异步处理embedding、语义生成完成/api/v1/system/backend/sync-statusPOSTROOT/ADMIN多写后端同步状态查询/api/v1/system/backend/sync-retryPOSTROOT/ADMIN多写后端同步重试组件级观测与 Prometheus 指标属于独立主题分别参见 运行观测 与 Metrics 文档本文不展开。二、health基础健康检查1. 实现与返回结构health_checksystem.py无需认证返回status、healthy、version三个基础字段。服务端会读取request.app.state.config上缓存的配置调用get_effective_auth_mode()得到auth_mode若请求携带X-API-Key或Authorization头还会尝试解析身份在响应中追加account_id、user_id与role解析失败仅记录日志不影响 200 返回。代码入口HTTP 路由system.py:health_checkPython SDK 入口SyncHTTPClient.health位于 sync_http.py其真实实现由_http_compat提供CLI 命令crates/ov_cli/src/commands/system.rs:health2. profile 参数随请求开启的 cProfileprofile是唯一的可选参数参数类型必填默认值说明profilestring否-传1、true、yes或on时为本次请求开启cProfile并在 JSON 响应里追加profile字段从 profile_middleware.py 的源码可以看到该参数的完整行为Middleware 级能力create_profile_http_middleware()profile_middleware.py对所有返回 JSON 的 OpenViking 接口生效不限于/health。受服务端开关约束profile_enabled()profile_middleware.py会先检查server.profile_enabled服务端配置未开启时直接返回False请求中的profile参数被忽略。该配置定义在 openviking/server/config.py默认值为False需要时在ov.conf中显式开启server.profile_enabled true。仅对当前请求生效请求结束后 profiler 自动关闭后续请求不会继承 profile 状态。只改写 JSON 响应inject_profile_into_response()profile_middleware.py对FileResponse、StreamingResponse以及 content-type 非 JSON 的响应直接原样放行因此纯文本、文件、流式响应不会被注入profile字段。返回格式profile是list[string]每一行对应一行格式化后的pstats输出便于浏览器直接查看、前端按行渲染。客户端侧ovCLI 会显示返回的profilePython HTTP client 可通过ovcli.conf.profile true触发服务端 profile但大多数 SDK 方法默认只返回业务result不会把顶层profile一并暴露给调用方。profile 输出按cumulative累计耗时排序PROFILE_SORT_BY cumulative最多保留前 100 行PROFILE_TOP_N 100总输出被裁剪到 16KBPROFILE_MAX_CHARS超长时以... [truncated]结尾文件路径会被裁剪为模块相对路径~:0(...)通常表示 builtin 或 C 扩展调用。profile 表头字段说明ncalls调用次数。若显示为总调用次数/原始调用次数前者是总调用数后者是 primitive calls。tottime函数自身耗时不含其调用的子函数耗时。percall第一列tottime / ncalls函数自身平均每次调用耗时。cumtime累计耗时包含当前函数及其所有子调用耗时。percall第二列cumtime / primitive calls按原始调用计算的平均累计耗时。filename:lineno(function)函数定义位置~:0(...)这类条目通常表示 builtin 或 C 扩展调用。3. 使用示例HTTP APIGET /healthcurl -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 healthov --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就绪探针Kubernetes 探针专用readiness_checksystem.py专为部署环境如 Kubernetes liveness/readiness probe设计无需认证。服务尚未初始化完成时get_service()抛出RuntimeError或service._initialized为假直接返回 503 与{status: not_ready, reason: initializing}。1. 检查项说明检查项判定逻辑取值agfs对viking://执行ls探测文件系统可访问性并尝试system_sync_status探测多写同步健康ok/not_supported/error其中multiwrite_sync子项在 AGFS 不支持时标记not_supportedvectordb通过viking_fs._get_vector_store().health_check()探测向量库健康ok/unhealthy/not_configuredapi_key_manager检查request.app.state.api_key_manager是否已加载ok/not_configuredembedding对 embedder 执行单 token 快速探测embed_compat(embedder, ok, is_queryTrue)10 秒超时ok/not_configured/error: ...ollama仅当配置了 Ollama 时检查连通性ok/unreachable at host:port/not_configured_is_ready_check_ok()system.py将ok、not_configured、not_supported均视为健康状态嵌套checks需要全部通过所有检查项健康时返回 200否则返回 503。2. 使用示例与响应HTTP APIGET /readycurl -X GET http://localhost:1933/ready响应示例{ status: ready, checks: { agfs: ok, vectordb: ok, api_key_manager: ok, ollama: not_configured } }四、status系统状态与多租户用户解析system_statussystem.py需要认证依赖get_request_context返回初始化状态与当前认证用户信息。关键语义result.user是认证请求的user_id来自 API 密钥或请求头而非进程级服务默认值——这正是 OpenClaw 等插件解析多租户路径的依据客户端可据此将请求路由到正确的租户目录。代码入口HTTP 路由system.py:system_statusPython SDK 入口SyncHTTPClient.get_statusCLI 命令system.rs:statusHTTP APIGET /api/v1/system/statuscurl -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文件系统与向量索引一致性检查check_consistencysystem.py检查指定 Viking URI 子树的文件系统内容和向量索引是否一致常用于调试索引缺失、向量快照导出失败等问题。该能力是通用数据一致性检查不属于 OVPack 私有接口ov export --include-vectors和ov backup --include-vectors复用同一检查逻辑。响应只返回摘要和缺失项不返回完整 expected 列表missing_records最多返回前 20 条若仍有更多缺失项missing_records_truncated为true。请求 URI 会先经过resolve_path_variables路径变量解析与validate_request_viking_uri校验。代码入口HTTP 路由system.py:check_consistencyPython SDK 入口SyncHTTPClient.check_consistencyCLI 命令system.rs:consistency表格输出模式由output_consistency_table渲染且该函数有专门测试保证 profile 段落被保留见 system.rs#L185-L205参数说明参数类型必填默认值说明uristring是-要检查的 Viking URI 子树HTTP APIPOST /api/v1/system/consistency Content-Type: application/jsoncurl -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等待异步处理完成wait_processedsystem.py阻塞等待所有异步处理embedding、语义生成完成直到所有队列任务处理完毕或超时。请求体由WaitRequest模型承载system.py实际等待逻辑委托给service.resources.wait_processed(timeout...)返回值按处理类型Embedding/Semantic分别给出processed、requeue_count、error_count与errors。参数说明参数类型必填默认值说明timeoutfloat否None超时时间秒None 表示无限等待HTTP APIPOST /api/v1/system/waitcurl -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对应 Rust 实现见 system.rs:wait直接向/api/v1/system/waitPOST{timeout: timeout}。响应示例{ 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 }七、backend_sync_status 与 backend_sync_retry多写后端同步管理这两个端点用于查询与重试指定 Viking URI 子树在多写存储后端之间的同步工作均要求 ROOT 或 ADMIN 权限路由通过require_role(Role.ROOT, Role.ADMIN)保护system.py。请求 URI 同样经过路径变量解析与 URI 校验实际逻辑分别委托service.fs.system_sync_status与service.fs.system_sync_retry。注意公共 Python、TypeScript 和 Go SDK 当前没有多写后端同步方法因此这两个端点只提供 HTTP 与 CLI 调用方式。1. backend_sync_status查询同步状态HTTP APIPOST /api/v1/system/backend/sync-status Content-Type: application/jsoncurl -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 路径形式对应路由 system.py:admin_sync_statusGET /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表示该范围内的同步记录数。具体后端可能附加待同步、失败记录等诊断字段。2. backend_sync_retry重试未完成的同步HTTP APIPOST /api/v1/system/backend/sync-retry Content-Type: application/jsoncurl -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 路径形式为对应路由 system.py:admin_sync_retryPOST /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是重试调度失败的记录数具体后端可能附加额外诊断字段。Rust CLI 侧的实现见 system.rs:backend_sync_status 与 system.rs:backend_sync_retry。八、运维实践要点探针区分/health适合作为存活探针进程活着即通过/ready适合作为就绪探针依赖子系统全部就绪才放流量两者均无需认证可直接配置到 Kubernetes 的httpGet探针。profile 排查服务端需先在ov.conf开启server.profile_enabled true默认关闭见 openviking/server/config.py随后对任意 JSON 接口追加?profile1即可得到该次请求的 cProfile 快照无需改代码重启服务CLI 侧可用ov --profile command触发。一致性排障当检索结果缺失或向量快照导出失败时用ov system consistency uri快速定位缺失记录level与key可反查索引层级missing_records_truncated为true说明缺失项超过 20 条需优先处理根因而非逐条补齐。写入后等待自动化脚本在add_resource后调用wait_processed可避免异步 embedding 尚未完成就发起检索导致的结果不稳定。多租户路由/api/v1/system/status返回的user是请求认证身份而非服务默认值多租户插件应以此字段解析租户路径而非硬编码进程级配置。相关文档Resources - 资源管理Retrieval - 搜索与检索Sessions - 会话管理运行观测 - 组件即时状态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），仅供参考