控制器 API

这些 API 是特定于 LMCache Controller 组件的。它们提供对注册实例、工作者和关键统计信息的可见性。

GET /controller/key-stats — 关键统计信息

获取所有实例和工作节点的关键统计信息。

• 方法: GET

• 路径: /controller/key-stats

• 参数: 无

• 响应: application/json

curl http://localhost:6999/controller/key-stats

示例响应 (HTTP 200):

{
  "total_key_count": 1500,
  "total_instance_count": 2,
  "total_worker_count": 4,
  "instances": [
    {
      "instance_id": "instance_001",
      "key_count": 800,
      "worker_count": 2
    },
    {
      "instance_id": "instance_002",
      "key_count": 700,
      "worker_count": 2
    }
  ]
}

**错误响应**（控制器不可用，HTTP 503）：

{
  "detail": "Controller manager not available"
}

响应模式:

字段	类型	描述
total_key_count	整数	所有实例中 KV 键的总数
total_instance_count	整数	注册实例的总数
total_worker_count	整数	所有实例的工作线程总数
instances	列表	每个实例的详细信息（见下文）

实例架构:

字段	类型	描述
instance_id	字符串	实例的唯一标识符
key_count	整数	此实例持有的 KV 键数量
worker_count	整数	此实例中的工作线程数量

GET /controller/workers — 工作信息

使用灵活的查询参数获取工作信息。行为取决于参数的组合：

• 无参数：列出所有实例中注册的所有工作者。

• ``instance_id`` 仅: 列出特定实例的所有工作者。

• ``instance_id`` 和 ``worker_id``: 获取特定工作者的详细信息。

• 方法: GET

• 路径: /controller/workers

• 参数:

  名称	类型	描述
  instance_id	字符串	（可选）用于过滤工作节点的实例 ID
  worker_id	整数	（可选）特定工作者详细信息的工作者 ID（需要 instance_id）

• 响应: application/json

# List all workers
curl http://localhost:6999/controller/workers

# List workers for a specific instance
curl "http://localhost:6999/controller/workers?instance_id=instance_001"

# Get a specific worker
curl "http://localhost:6999/controller/workers?instance_id=instance_001&worker_id=0"

**示例响应**（列出工作者）：

{
  "workers": [
    {
      "instance_id": "instance_001",
      "worker_id": 0,
      "ip": "10.0.0.1",
      "port": 8000,
      "peer_init_url": "http://10.0.0.1:8000/init",
      "registration_time": 1706745600.0,
      "last_heartbeat_time": 1706745660.0,
      "key_count": 400
    },
    {
      "instance_id": "instance_001",
      "worker_id": 1,
      "ip": "10.0.0.2",
      "port": 8001,
      "peer_init_url": "http://10.0.0.2:8001/init",
      "registration_time": 1706745600.0,
      "last_heartbeat_time": 1706745660.0,
      "key_count": 400
    }
  ],
  "total_count": 2
}

**示例响应**（单个工作者）：

{
  "instance_id": "instance_001",
  "worker_id": 0,
  "ip": "10.0.0.1",
  "port": 8000,
  "peer_init_url": "http://10.0.0.1:8000/init",
  "registration_time": 1706745600.0,
  "last_heartbeat_time": 1706745660.0,
  "key_count": 400
}

**错误响应**（未找到工作者，HTTP 404）：

{
  "detail": "Worker (instance_001, 99) not found"
}

**错误响应**（实例未找到，HTTP 404）：

{
  "detail": "No workers found for instance unknown_instance"
}

**错误响应**（控制器不可用，HTTP 503）：

{
  "detail": "Controller manager not available"
}

工作者响应模式:

字段	类型	描述
instance_id	字符串	该工作者所属的实例
worker_id	整数	实例内的工作线程索引
ip	字符串	工作节点 IP 地址
port	整数	工作端口号
peer_init_url	字符串	(可选) 对等初始化 URL
registration_time	浮点数	工作节点注册的 Unix 时间戳
last_heartbeat_time	浮点数	最后心跳的 Unix 时间戳
key_count	整数	此工作线程持有的 KV 键数量