跳到主要内容
版本：Nightly

Admin API

提示

本页所有 Admin API 都监听 Metasrv 的 HTTP_PORT，默认值为 4000。

Admin API 通过 HTTP 提供 Metasrv 状态、集群控制和元数据恢复操作。该 API 不提供认证，且部分端点会改变集群行为或元数据分配，部署时必须通过网络策略保护 HTTP 端口。 本页介绍以下 API：

  • /health
  • /leader
  • /heartbeat
  • /node-lease
  • /datanode
  • /maintenance
  • /procedure-manager
  • /procedure/status
  • /recovery
  • /sequence/table

所有这些 API 都在父资源 /admin 下。

在以下部分中，我们假设你的 metasrv 实例运行在本地主机的 4000 端口。

/health HTTP 端点​

/health 端点接受 GET 请求。HTTP 服务运行时返回 OK，但不会检查当前 Metasrv 是否为 leader，也不会检查外部依赖是否可用。

定义​

curl -X GET http://localhost:4000/admin/health

示例​

请求​

curl -X GET http://localhost:4000/admin/health

响应​

OK

/leader HTTP 端点​

/leader 端点接受 GET HTTP 请求，你可以使用此端点查询你的 metasrv 实例的 leader 地址。

定义​

curl -X GET http://localhost:4000/admin/leader

示例​

请求​

curl -X GET http://localhost:4000/admin/leader

响应​

127.0.0.1:4000

/heartbeat HTTP 端点​

/heartbeat 端点接受 GET HTTP 请求，你可以使用此端点查询所有数据节点的心跳。

你还可以查询指定 addr 的数据节点的心跳数据，但在路径中指定 addr 是可选的。

定义​

curl -X GET http://localhost:4000/admin/heartbeat
查询字符串参数类型可选/必选定义
addrString可选数据节点的地址。

示例​

请求​

curl -X GET 'http://localhost:4000/admin/heartbeat?addr=127.0.0.1:4100'

响应​

[
  [
    {
      "timestamp_millis": 1677049348651,
      "id": 1,
      "addr": "127.0.0.1:4100",
      "rcus": 0,
      "wcus": 0,
      "region_num": 2,
      "region_stats": [],
      "topic_stats": [],
      "node_epoch": 0,
      "datanode_workloads": {
        "types": []
      },
      "gc_stat": null
    }
  ]
]

/node-lease HTTP 端点​

/node-lease 返回 Metasrv 当前记录的 Datanode lease，可用于判断 Metasrv 是否仍将某个 Datanode 视为存活。

curl -X GET http://localhost:4000/admin/node-lease

/datanode HTTP 端点​

这些端点用于对 Datanode 执行 Drain，并控制 Metasrv 是否可以向该节点放置 Region。它们面向计划内的节点下线与维护，完整流程请参阅 Drain Datanode。

  • POST /admin/datanode/drain：提交一个异步 Procedure，迁移该 Datanode 上的 Leader Region。
  • POST /admin/datanode/mark-schedulable：允许 Metasrv 再次向该 Datanode 放置 Region。
  • GET /admin/datanode/scheduling/status：查询该 Datanode 是否可调度。

/drain 和 /mark-schedulable 接受 JSON 请求体，/scheduling/status 接受 node_id 查询字符串参数：

curl -X POST 'http://localhost:4000/admin/datanode/drain' \
  -H 'Content-Type: application/json' \
  -d '{"node_id": 1, "target_node_id": 2, "parallelism": 8, "strategy": "fail_fast", "timeout": "30m"}'
{"procedure_id":"a3b9f746-81c2-4e65-9d07-6f2c8b104ea5"}

请求支持可选字段 target_node_id、parallelism（1–32，默认 4）、strategy（默认 try_all，可选 fail_fast）和 timeout（默认 20m）。parallelism、strategy 和 timeout 显式传入 null 会被拒绝；各字段的含义参见Drain Datanode。Drain 以 Procedure 形式运行，因此响应会立即返回 procedure_id。

curl -X POST 'http://localhost:4000/admin/datanode/mark-schedulable' \
  -H 'Content-Type: application/json' \
  -d '{"node_id": 1}'

curl -X GET 'http://localhost:4000/admin/datanode/scheduling/status?node_id=1'

这两个调度请求都返回：

{"node_id":1,"schedulable":true}

scheduling/status 返回当前状态；mark-schedulable 恢复调度，重复调用也会成功，并返回 "schedulable": true。

使用时的注意事项：

  • 三个端点都必须发送到 leader Metasrv。在 follower 上调用会返回 HTTP 500 和错误码 1006。
  • Drain 会先标记节点不可调度，再开始迁移。无论 Procedure 成功还是失败，结束后节点都保持不可调度，直到 mark-schedulable 成功。
  • 只迁移 Leader Region；Follower Region 留在该节点上，Drain 也不会停止 Datanode 进程。
  • 同一 Datanode 已有 Drain 在跟踪时，再次提交 Drain（包括完全相同的请求）会被拒绝。应通过 /procedure/status 跟踪正在运行的 Procedure。
  • 同一节点正在 Drain 时，mark-schedulable 会被拒绝。
  • Metasrv 重启后尚未完成 Procedure 恢复时，Drain 提交和 mark-schedulable 都会被拒绝。
  • Drain 的时间预算默认为提交后 20 分钟，最多同时迁移 4 个 Leader Region。可通过 timeout 和 parallelism 按请求覆盖这些默认值。

/maintenance HTTP 端点​

维护模式在升级、计划停机等操作期间临时禁用自动集群管理。它对集群的具体影响参见集群维护模式。

/maintenance 端点支持以下 HTTP 请求：

  • GET /admin/maintenance 或 GET /admin/maintenance/status：查询维护模式状态。
  • POST /admin/maintenance/enable：启用维护模式。
  • POST /admin/maintenance/disable：禁用维护模式。

响应体使用以下格式：

{
  "enabled": true
}

/procedure-manager HTTP 端点​

该端点用于管理 Procedure Manager 状态。有关更多详细信息，请参阅防止元数据变更。

/procedure-manager 端点支持以下 HTTP 请求：

  • GET /admin/procedure-manager/status：查询 Procedure Manager 状态。
  • POST /admin/procedure-manager/pause：暂停 Procedure Manager。
  • POST /admin/procedure-manager/resume：恢复 Procedure Manager。

响应体使用以下格式：

{
  "status": "running"
}

/procedure/status HTTP 端点​

GET /admin/procedure/status?procedure_id=<uuid> 返回提交到 leader Metasrv 的 Procedure 状态，可用于跟踪 /datanode/drain 发起的 Drain。SQL 函数 ADMIN procedure_state 返回相同的状态。

curl -X GET 'http://localhost:4000/admin/procedure/status?procedure_id=a3b9f746-81c2-4e65-9d07-6f2c8b104ea5'
{"procedure_id":"a3b9f746-81c2-4e65-9d07-6f2c8b104ea5","status":"Done","error":null}

status 取值为 Running、Done、Retrying、Failed、PrepareRollback、RollingBack 或 Poisoned。Procedure 正在失败或已经失败时，error 包含失败信息，其他情况下为 null。当 Drain 无法迁移部分 Region 时，它们会列在 error 中；以 Done 结束的 Drain 不报告迁移数量。Done 只表示 Drain 没有更多需要提交的迁移。Metasrv 重启后，已恢复的迁移可能仍在运行，因此在将节点下线前，请按Drain Datanode中的步骤确认 Region 分布。

该端点必须发送到 leader Metasrv，且不受 Procedure Manager 暂停开关影响。

/recovery HTTP 端点​

Recovery mode 控制手动修改 table ID sequence 等元数据修复端点。它只用于恢复工作，不用于常规维护。

  • GET /admin/recovery/status：查询 recovery mode 是否开启。
  • POST /admin/recovery/enable：开启 recovery mode。
  • POST /admin/recovery/disable：关闭 recovery mode。

响应体格式如下：

{
  "enabled": true
}

修复完成后应关闭 recovery mode。如果只是计划暂停自动集群操作，应使用维护模式。

/sequence/table HTTP 端点​

这些端点用于检查或修复 table ID sequence：

  • GET /admin/sequence/table/next-id：返回下一个 table ID，但不执行分配。
  • POST /admin/sequence/table/set-next-id：推进下一个 table ID。

设置 sequence 前必须开启 recovery mode。新值必须大于当前值，不能通过该 API 回退 sequence。Recovery mode 只是该 API 的前置条件，不能阻止 DDL。执行该操作时，必须遵循管理 Table ID Sequence中的完整集群操作流程。

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"next_table_id": 2048}' \
  http://localhost:4000/admin/sequence/table/set-next-id

该操作会影响后续新表分配到的 ID。

错误响应​

/datanode 和 /procedure/status 端点返回统一的 JSON 错误响应体：

{"code":1006,"error":"Another drain procedure is running for datanode: 1","execution_time_ms":0}
  • 1006（IllegalState，HTTP 500）：请求打到了 follower Metasrv；该节点已有 Drain 在运行；恢复调度时该节点正在 Drain；或 Metasrv 尚未完成 Procedure 恢复。
  • 1004（InvalidArguments，HTTP 400）：Drain 的目标节点与源节点相同；parallelism 超出 1–32；timeout 为零或大到无法调度；或 procedure_id 格式不合法、不存在。
  • HTTP 422：JSON 请求体无法解析，例如缺少必填字段、strategy 取值未知或 timeout 时长格式错误。能正常解析但未通过校验的取值（例如 parallelism 超出 1–32）返回 HTTP 400。