企业官网建设流程全解析

OpenViking 系统状态 API 实战指南：健康检查、就绪探针、一致性校验与多写同步管理

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

OpenViking 系统 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，挂载路径与功能如下：

组件级观测与 Prometheus 指标属于独立主题，分别参见 运行观测 与 Metrics 文档，本文不展开。

二、health：基础健康检查

1. 实现与返回结构

health_check（system.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_check
• Python SDK 入口：SyncHTTPClient.health（位于 sync_http.py，其真实实现由_http_compat提供）
• CLI 命令：crates/ov_cli/src/commands/system.rs:health

2. profile 参数：随请求开启的 cProfile

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 会显示返回的profile；Python HTTP client 可通过ovcli.conf.profile = true触发服务端 profile，但大多数 SDK 方法默认只返回业务result，不会把顶层profile一并暴露给调用方。

profile 输出按cumulative累计耗时排序（PROFILE_SORT_BY = "cumulative"），最多保留前 100 行（PROFILE_TOP_N = 100），总输出被裁剪到 16KB（PROFILE_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 API

GET /health

curl -X GET http://localhost:1933/health

curl -G http://localhost:1933/health \ --data-urlencode "profile=1"

Python SDK

import openviking as ov client = ov.SyncHTTPClient(url="http://localhost:1933") client.initialize() healthy = client.health() print(f"Healthy: {healthy}")

TypeScript SDK

console.log(await client.health());

Go SDK

healthy, err := client.Health(ctx) if err != nil { return err } fmt.Println(healthy)

CLI

ov 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：就绪探针（Kubernetes 探针专用）

readiness_check（system.py）专为部署环境（如 Kubernetes liveness/readiness probe）设计，无需认证。服务尚未初始化完成时（get_service()抛出RuntimeError或service._initialized为假）直接返回 503 与{"status": "not_ready", "reason": "initializing"}。

1. 检查项说明

_is_ready_check_ok()（system.py）将ok、not_configured、not_supported均视为健康状态，嵌套checks需要全部通过；所有检查项健康时返回 200，否则返回 503。

2. 使用示例与响应

HTTP API

GET /ready

curl -X GET http://localhost:1933/ready

响应示例

{ "status": "ready", "checks": { "agfs": "ok", "vectordb": "ok", "api_key_manager": "ok", "ollama": "not_configured" } }

四、status：系统状态与多租户用户解析

system_status（system.py）需要认证（依赖get_request_context），返回初始化状态与当前认证用户信息。关键语义：result.user是认证请求的user_id（来自 API 密钥或请求头），而非进程级服务默认值——这正是 OpenClaw 等插件解析多租户路径的依据，客户端可据此将请求路由到正确的租户目录。

代码入口：

• HTTP 路由：system.py:system_status
• Python SDK 入口：SyncHTTPClient.get_status
• CLI 命令：system.rs:status

HTTP API

GET /api/v1/system/status

curl -X GET http://localhost:1933/api/v1/system/status \ -H "X-API-Key: your-key"

Python SDK

status = client.get_status() print(status)

TypeScript SDK

console.log(await client.getStatus());

CLI

ov system status

响应示例

{ "status": "ok", "result": { "initialized": true, "user": "alice" }, "time": 0.1 }

五、consistency：文件系统与向量索引一致性检查

check_consistency（system.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_consistency
• Python SDK 入口：SyncHTTPClient.check_consistency
• CLI 命令：system.rs:consistency，表格输出模式由output_consistency_table渲染，且该函数有专门测试保证 profile 段落被保留（见 system.rs#L185-L205）

参数说明

HTTP API

POST /api/v1/system/consistency Content-Type: application/json

curl -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 SDK

report = client.check_consistency(uri="viking://resources/my-project") print(report["ok"]) print(report["missing_records"])

TypeScript SDK

console.log(await client.checkConsistency("viking://resources/"));

Go SDK

report, err := client.CheckConsistency(ctx, "viking://resources/my-project") if err != nil { return err } fmt.Println(report["ok"])

CLI

ov 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#level=2" } ] } }

六、wait_processed：等待异步处理完成

wait_processed（system.py）阻塞等待所有异步处理（embedding、语义生成）完成，直到所有队列任务处理完毕或超时。请求体由WaitRequest模型承载（system.py），实际等待逻辑委托给service.resources.wait_processed(timeout=...)，返回值按处理类型（Embedding/Semantic）分别给出processed、requeue_count、error_count与errors。

参数说明

HTTP API

POST /api/v1/system/wait

curl -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(timeout=60.0) print(f"Processing complete: {status}")

TypeScript SDK

console.log(await client.waitProcessed(60));

Go SDK

status, err := client.WaitProcessed(ctx, &openviking.WaitProcessedOptions{ Timeout: openviking.Float64(60), }) if err != nil { return err } fmt.Println(status)

CLI

ov 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 API

POST /api/v1/system/backend/sync-status Content-Type: application/json

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 路径形式（对应路由 system.py:admin_sync_status）：

GET /api/v1/system/sync/{sync_path}

CLI

ov system backend sync-status viking://resources

响应示例

{ "status": "ok", "result": { "path": "viking://resources", "entry_count": 12 } }

result由当前文件系统后端返回；path标识查询范围，entry_count表示该范围内的同步记录数。具体后端可能附加待同步、失败记录等诊断字段。

2. backend_sync_retry：重试未完成的同步

HTTP API

POST /api/v1/system/backend/sync-retry Content-Type: application/json

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 路径形式为（对应路由 system.py:admin_sync_retry）：

POST /api/v1/system/sync/{sync_path}/retry

CLI

ov 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 接口追加?profile=1即可得到该次请求的 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