Keeper HTTP API 和仪表板

ClickHouse Keeper 提供 HTTP API 和内置 Web 仪表板，用于监控、健康检查和存储管理。该接口允许运维人员通过 Web 浏览器或 HTTP 客户端检查集群状态、执行命令，并管理 Keeper 存储。

配置

要启用 HTTP API，请在 keeper_server 配置中添加 http_control 部分：

<keeper_server>
    <!-- 其他 keeper_server 配置 -->

    <http_control>
        <port>9182</port>
        <!-- <secure_port>9443</secure_port> -->
    </http_control>
</keeper_server>

配置选项

配置项	默认值	描述
`http_control.port`	-	仪表板和 API 的 HTTP 端口
`http_control.secure_port`	-	HTTPS 端口 (需要 SSL 配置)
`http_control.readiness.endpoint`	`/ready`	就绪探针的自定义 path
`http_control.storage.session_timeout_ms`	`30000`	存储 API 操作的会话超时时间

端点

仪表板

路径: /dashboard
方法: GET
说明: 提供一个用于监控和管理 Keeper 的内置 Web 仪表板

该仪表板提供：

集群状态实时可视化
节点监控 (角色、延迟、连接)
存储浏览器
命令执行界面

集群选项卡

集群选项卡会以拓扑图和表格的形式展示 Raft 成员关系。每个成员会以不同颜色标示其健康状态：

绿色 — 存活且与 leader 保持同步
黄色 — 存活，但比 leader 落后超过 stale_log_gap 条日志条目
红色 — 不可达 (心跳过期窗口内未收到成功的 Raft 响应)
灰色 — 未知 (只有从 leader 才能查看 peer 的健康状态；跟随者看到的 peer 状态均为未知)

表格还会显示每个成员的角色 (leader、follower 或 observer) 、Raft priority、最新日志索引、相对于 leader 的复制延迟，以及距上次成功收到 Raft 响应的时间。当当前节点不是 leader 时，此选项卡会提供一个深层链接，用于打开 leader 的仪表板，那里可查看完整的 peer 健康状态。也可通过 /dashboard?tab=cluster 直接打开此选项卡。

就绪探针

路径: /ready (可配置)
方法: GET
描述: 健康检查端点

成功响应 (HTTP 200) ：

{
  "status": "ok",
  "details": {
    "role": "leader",
    "hasLeader": true
  }
}

命令 API

路径: /api/v1/commands/{command}
方法: GET, POST
描述: 执行 Four-Letter Word 命令或 ClickHouse Keeper Client CLI 命令

查询参数：

command - 要执行的命令
cwd - 基于路径的命令所使用的当前工作目录 (默认：/)

示例：

# 四字命令
curl http://localhost:9182/api/v1/commands/stat

# ZooKeeper CLI 命令
curl "http://localhost:9182/api/v1/commands/ls?command=ls%20'/'&cwd=/"

Storage API

基础路径: /api/v1/storage
说明: 用于 Keeper 存储操作的 REST API

Storage API 遵循 REST 规范，其中 HTTP 方法表示操作类型：

操作	路径	方法	状态码	说明
获取	`/api/v1/storage/{path}`	GET	200	获取节点数据
列表	`/api/v1/storage/{path}?children=true`	GET	200	列出子节点
是否存在	`/api/v1/storage/{path}`	HEAD	200	检查节点是否存在
创建	`/api/v1/storage/{path}`	POST	201	创建新节点
更新	`/api/v1/storage/{path}?version={v}`	PUT	200	更新节点数据
删除	`/api/v1/storage/{path}?version={v}`	DELETE	204	删除节点

基础知识

ClickHouse 概念

最佳实践

配置

配置选项

端点

仪表板

集群选项卡

就绪探针

命令 API

Storage API

​配置

​配置选项

​端点

​仪表板

​集群选项卡

​就绪探针

​命令 API

​Storage API

配置

配置选项

端点

仪表板

集群选项卡

就绪探针

命令 API

Storage API