系统状态

OpenViking 系统 API 提供健康检查、就绪检查、一致性检查和后台处理状态。 组件级观测和 Prometheus 指标分别提供独立文档。

API 参考

health

1. API 实现介绍

基础存活检查，无需认证。返回版本号、健康状态和认证模式。提供凭据后会尝试解析身份，成功时补充身份字段；凭据无效时返回认证错误。

Trusted 模式下，完整的 X-OpenViking-Account 和 X-OpenViking-User 请求头会触发身份解析， 必须携带匹配的 root API key，localhost 也不例外。Trusted 模式的 root_api_key_required 始终为 true，解析得到的 role 表示调用者权限。匿名健康探测返回基础存活信息，不包含身份字段。

代码入口:

• openviking/server/routers/system.py:health_check - HTTP 路由
• sdk/python/openviking_sdk/client.py:SyncHTTPClient.health - SDK 入口
• crates/ov_cli/src/commands/system.rs - CLI 命令

2. 接口和参数说明

参数	类型	必填	默认值	说明
profile	string	否	-	传 1、true、yes 或 on 时，为本次请求开启 cProfile，并在 JSON 响应里追加 profile 字段

profile 行为说明:

• profile 是 HTTP middleware 级能力，对任意返回 JSON 的 OpenViking 接口都生效，不限于 /health。
• 仅当服务端在 ov.conf 中开启 server.profile_enabled = true 时，请求里的 profile=1 才会生效；否则服务端会忽略该参数。
• profile 仅对当前请求生效，请求结束后自动关闭；后续请求默认不会继承这次 profile 状态。
• 仅 JSON 响应会追加 profile 字段；纯文本、文件、流式响应不会被改写。
• profile 的返回值是 list[string]，每个元素对应一行格式化后的 pstats 输出，便于浏览器直接查看和前端按行渲染。
• ov CLI 会显示返回的 profile；Python HTTP client 可以通过 ovcli.conf.profile = true 触发服务端 profile，但大多数 SDK 方法默认只返回业务 result，不会把顶层 profile 一并暴露给调用方。

profile 表头字段说明:

• ncalls: 调用次数。若显示为 总调用次数/原始调用次数，前者是总调用数，后者是 primitive calls。
• tottime: 函数自身耗时，总时间，不包含其调用的子函数耗时。
• percall（第一列）: tottime / ncalls，即函数自身平均每次调用耗时。
• cumtime: 累计耗时，包含当前函数及其所有子调用耗时。
• percall（第二列）: cumtime / primitive calls，即按原始调用计算的平均累计耗时。
• filename:lineno(function): 函数定义位置。普通 Python 代码会显示为裁剪后的模块路径；~: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_sdk 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

1. API 实现介绍

部署环境使用的就绪探针。检查 AGFS、VectorDB、APIKeyManager、Embedding 和 Ollama（如配置）的状态。当所有配置的子系统都准备完成时返回 200，否则返回 503。无需认证（专为 Kubernetes 探针设计）。

代码入口:

• openviking/server/routers/system.py:readiness_check - HTTP 路由

2. 接口和参数说明

无参数。

检查项说明:

• agfs: 包含文件系统访问和主备同步状态的嵌套检查结果
• vectordb: 向量数据库是否健康
• api_key_manager: API 密钥管理器是否已加载
• embedding: 启动时 Embedding provider 是否已初始化；不发起模型请求
• ollama: Ollama 服务是否可达（仅当配置时）

3. 使用示例

HTTP API

GET /ready

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

响应示例

{
  "status": "ready",
  "checks": {
    "agfs": {"status": "ok", "checks": {"filesystem": "ok", "multiwrite_sync": "not_supported"}},
    "vectordb": "ok",
    "api_key_manager": "ok",
    "embedding": "ok",
    "ollama": "not_configured"
  }
}

---

status

1. API 实现介绍

获取系统状态，包括初始化状态和当前认证用户信息。result.user 是认证请求的 user_id（来自 API 密钥或请求头），而非进程级服务默认值，客户端可用于解析多租户路径。

代码入口:

• openviking/server/routers/system.py:system_status - HTTP 路由
• crates/ov_cli/src/commands/system.rs - CLI 命令

2. 接口和参数说明

无参数。

3. 使用示例

HTTP API

GET /api/v1/system/status

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

公开 SDK 的 get_status() / getStatus() / GetStatus() 返回 Observer 汇总状态，不是本接口的身份信息。访问本接口使用 HTTP；这些 SDK 方法见运行观测。

CLI

ov system status

响应示例

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

---

consistency

1. API 实现介绍

检查指定 URI 子树的文件系统内容和向量索引是否一致，用于调试索引缺失、向量快照导出失败等问题。该能力是通用数据一致性检查，不属于 OVPack 私有接口；ov export --include-vectors 和 ov backup --include-vectors 会复用同一检查。

响应只返回摘要和缺失项，不返回完整 expected 列表。missing_records 最多返回前 20 条；如果还有更多缺失项，missing_records_truncated 为 true。

代码入口:

• openviking/server/routers/system.py:check_consistency - HTTP 路由
• sdk/python/openviking_sdk/client.py:SyncHTTPClient.check_consistency - SDK 入口
• crates/ov_cli/src/commands/system.rs:consistency - CLI 命令

2. 接口和参数说明

参数	类型	必填	默认值	说明
uri	string	是	-	要检查的 Viking URI 子树

3. 使用示例

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

1. API 实现介绍

等待处理队列排空。该检查不限定为调用方刚提交的请求，也不覆盖所有异步 API。需检查返回的 error_count 和 errors，队列排空不代表所有操作成功。确认某次导入或 commit 的结果，应查询它的任务 ID。

代码入口:

• openviking/server/routers/system.py:wait_processed - HTTP 路由
• sdk/python/openviking_sdk/client.py:SyncHTTPClient.wait_processed - SDK 入口
• crates/ov_cli/src/commands/system.rs - CLI 命令

2. 接口和参数说明

参数

无参数。HTTP 请求超时使用客户端配置。

3. 使用示例

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"

Python SDK

# 等待当前处理队列排空
status = client.wait_processed()
print(status)  # 检查各队列的 error_count 和 errors

TypeScript SDK

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

Go SDK

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

CLI

ov system wait

响应示例

{
  "status": "ok",
  "result": {
    "Embedding": {
      "processed": 10,
      "requeue_count": 0,
      "error_count": 0,
      "errors": []
    },
    "Semantic": {
      "processed": 10,
      "requeue_count": 0,
      "error_count": 0,
      "errors": []
    }
  }
}

---

相关文档

• Resources - 资源管理
• Retrieval - 搜索与检索
• Sessions - 会话管理
• 运行观测 - 组件即时状态
• Metrics - Prometheus 指标