RobustMQ

简体中文

English

简体中文

English

RobustMQ Admin Server HTTP API 通用指南 ​

概述 ​

RobustMQ Admin Server 是 HTTP 管理接口服务，提供对 RobustMQ 集群的全面管理功能。

  • 基础地址: http://localhost:8080
  • API 前缀: /api (所有管理接口都使用此前缀)
  • 请求方法: 列表/详情查询使用 GET，创建/删除操作使用 POST
  • 数据格式: JSON
  • 响应格式: JSON

API 文档导航 ​

全量接口列表 ​

/cluster — 集群资源接口 ​

分类方法URI说明
ConfigGET/api/cluster/config/get获取集群配置
ConfigPOST/api/cluster/config/set更新集群配置
HealthGET/api/cluster/healthy集群健康检查
TenantGET/api/cluster/tenant/list租户列表查询
TenantPOST/api/cluster/tenant/create创建租户
TenantPOST/api/cluster/tenant/update更新租户
TenantPOST/api/cluster/tenant/delete删除租户
TopicGET/api/cluster/topic/list主题列表查询
TopicGET/api/cluster/topic/detail主题详情查询
TopicPOST/api/cluster/topic/create创建主题
TopicPOST/api/cluster/topic/delete删除主题
TopicGET/api/cluster/topic-rewrite/list主题重写规则列表
TopicPOST/api/cluster/topic-rewrite/create创建主题重写规则
TopicPOST/api/cluster/topic-rewrite/delete删除主题重写规则
UserGET/api/cluster/user/list用户列表查询
UserPOST/api/cluster/user/create创建用户
UserPOST/api/cluster/user/delete删除用户
ACLGET/api/cluster/acl/listACL 列表查询
ACLPOST/api/cluster/acl/create创建 ACL 规则
ACLPOST/api/cluster/acl/delete删除 ACL 规则
BlacklistGET/api/cluster/blacklist/list黑名单列表查询
BlacklistPOST/api/cluster/blacklist/create创建黑名单
BlacklistPOST/api/cluster/blacklist/delete删除黑名单
ConnectorGET/api/cluster/connector/list连接器列表查询
ConnectorGET/api/cluster/connector/detail连接器详情查询
ConnectorPOST/api/cluster/connector/create创建连接器
ConnectorPOST/api/cluster/connector/delete删除连接器
SchemaGET/api/cluster/schema/listSchema 列表查询
SchemaPOST/api/cluster/schema/create创建 Schema
SchemaPOST/api/cluster/schema/delete删除 Schema
SchemaGET/api/cluster/schema-bind/listSchema 绑定列表查询
SchemaPOST/api/cluster/schema-bind/create创建 Schema 绑定
SchemaPOST/api/cluster/schema-bind/delete删除 Schema 绑定
OffsetPOST/api/cluster/offset/timestamp按时间戳查询 Offset
OffsetPOST/api/cluster/offset/group按消费组查询 Offset
OffsetPOST/api/cluster/offset/commit提交 Offset

/mqtt — MQTT Broker 接口 ​

分类方法URI说明
OverviewGET/api/mqtt/overview集群概览信息
MonitorGET/api/mqtt/monitor/data监控数据查询
ClientGET/api/mqtt/client/list客户端列表查询
SessionGET/api/mqtt/session/list会话列表查询
SubscribeGET/api/mqtt/subscribe/list订阅列表查询
SubscribeGET/api/mqtt/subscribe/detail订阅详情查询
SubscribeGET/api/mqtt/auto-subscribe/list自动订阅规则列表
SubscribePOST/api/mqtt/auto-subscribe/create创建自动订阅规则
SubscribePOST/api/mqtt/auto-subscribe/delete删除自动订阅规则
SubscribeGET/api/mqtt/slow-subscribe/list慢订阅列表查询
FlappingGET/api/mqtt/flapping_detect/list连接抖动检测列表
AlarmGET/api/mqtt/system-alarm/list系统告警列表
AlarmGET/api/mqtt/ban-log/list封禁日志列表
MessagePOST/api/mqtt/message/send发送消息
MessagePOST/api/mqtt/message/read读取消息

/storage-engine — 存储引擎接口 ​

分类方法URI说明
ShardPOST/api/storage-engine/shard/listShard 列表查询
ShardPOST/api/storage-engine/shard/create创建 Shard
ShardPOST/api/storage-engine/shard/delete删除 Shard
SegmentPOST/api/storage-engine/segment/listSegment 列表查询

通用接口 ​

分类方法URI说明
InfoGET/获取服务版本信息
StatusGET/api/status集群状态查询
HealthGET/health/ready就绪健康检查
HealthGET/health/node节点健康检查
HealthGET/health/cluster集群健康检查

通用响应格式 ​

成功响应 ​

json
{
  "code": 0,
  "message": "success",
  "data": {...}
}

错误响应 ​

json
{
  "code": 500,
  "message": "error message",
  "data": null
}

分页响应格式 ​

json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": [...],
    "total_count": 100
  }
}

通用请求参数 ​

大多数列表查询接口支持以下通用参数：

参数名类型必填说明
limitu32否每页大小，默认 10000
pageu32否页码，从1开始，默认 1
sort_fieldstring否排序字段
sort_bystring否排序方式：asc/desc
filter_fieldstring否过滤字段
filter_valuesarray否过滤值列表
exact_matchstring否精确匹配：true/false

分页参数示例 ​

json
{
  "limit": 20,
  "page": 1,
  "sort_field": "create_time",
  "sort_by": "desc",
  "filter_field": "status",
  "filter_values": ["active"],
  "exact_match": "false"
}

基础接口 ​

服务版本查询 ​

  • 接口: GET /
  • 描述: 获取服务版本信息
  • 请求参数: 无
  • 响应示例:
json
"RobustMQ API v0.1.34"

集群状态查询 ​

  • 接口: GET /api/status
  • 描述: 获取集群完整状态信息，包括 RobustMQ 版本、集群名称、启动时间、Broker 节点列表以及 Meta 集群的 Raft 状态
  • 请求参数:
json
{}

（空对象）

  • 响应示例:
json
{
  "code": 0,
  "data": {
    "version": "0.2.1",
    "cluster_name": "broker-server",
    "start_time": 1760828141,
    "broker_node_list": [
      {
        "roles": ["mqtt-broker"],
        "extend": [],
        "node_id": 1,
        "node_ip": "192.168.100.100",
        "grpc_addr": "192.168.100.100:1228",
        "engine_addr": "192.168.100.100:1229",
        "start_time": 1760828141,
        "register_time": 1760828142,
        "storage_fold": []
      }
    ],
    "nodes": ["192.168.100.100", "127.0.0.1"],
    "meta": {
      "running_state": {
        "Ok": null
      },
      "id": 1,
      "current_term": 1,
      "vote": {
        "leader_id": {
          "term": 1,
          "node_id": 1
        },
        "committed": true
      },
      "last_log_index": 422,
      "last_applied": {
        "leader_id": {
          "term": 1,
          "node_id": 1
        },
        "index": 422
      },
      "snapshot": null,
      "purged": null,
      "state": "Leader",
      "current_leader": 1,
      "millis_since_quorum_ack": 0,
      "last_quorum_acked": 1760828146763525625,
      "membership_config": {
        "log_id": {
          "leader_id": {
            "term": 0,
            "node_id": 0
          },
          "index": 0
        },
        "membership": {
          "configs": [[1]],
          "nodes": {
            "1": {
              "node_id": 1,
              "rpc_addr": "127.0.0.1:1228"
            }
          }
        }
      },
      "heartbeat": {
        "1": 1760828146387602084
      },
      "replication": {
        "1": {
          "leader_id": {
            "term": 1,
            "node_id": 1
          },
          "index": 422
        }
      }
    }
  }
}

响应字段说明:

字段类型说明
versionstringRobustMQ 版本号
cluster_namestring集群名称
start_timeu64服务启动时间（Unix时间戳，秒）
broker_node_listarrayBroker 节点列表
nodesarray集群中所有唯一节点的 IP 地址列表（去重后）
metaobjectMeta 集群 Raft 状态信息（结构化对象）

Broker 节点字段说明:

字段类型说明
rolesarray节点角色列表（如 ["mqtt-broker"]）
extendarray扩展信息（字节数组）
node_idu64节点 ID
node_ipstring节点 IP 地址
grpc_addrstringgRPC 通信地址
engine_addrstring存储引擎地址
start_timeu64节点启动时间（Unix时间戳，秒）
register_timeu64节点注册时间（Unix时间戳，秒）
storage_foldarray存储目录列表

Meta 集群状态（meta）字段说明:

meta 字段包含 Meta 集群的 Raft 共识状态信息，用于监控集群的分布式一致性状态：

字段类型说明
running_stateobject运行状态，{"Ok": null} 表示正常运行
idu64当前节点 ID
current_termu64Raft 当前任期号
voteobject投票信息
vote.leader_idobjectLeader 标识，包含 term 和 node_id
vote.committedboolean投票是否已提交
last_log_indexu64最后一条日志的索引
last_appliedobject最后应用的日志信息
last_applied.leader_idobjectLeader 标识
last_applied.indexu64已应用的日志索引
snapshotobject/null快照信息（如果存在）
purgedobject/null已清理的日志信息（如果存在）
statestring当前节点 Raft 状态：Leader、Follower 或 Candidate
current_leaderu64当前 Leader 节点的 ID
millis_since_quorum_acku64自上次获得法定人数确认以来的毫秒数
last_quorum_ackedu128最后一次法定人数确认的时间戳（纳秒精度）
membership_configobject集群成员配置信息
membership_config.log_idobject配置对应的日志 ID
membership_config.membershipobject成员信息
membership_config.membership.configsarray配置数组，如 [[1]] 表示节点 1
membership_config.membership.nodesobject节点映射，键为节点 ID 字符串，值为节点信息
heartbeatobject心跳映射，键为节点 ID，值为心跳时间戳（纳秒）
replicationobject复制状态映射，键为节点 ID，值包含 leader_id 和 index

使用场景说明:

  • 通过 state 字段判断节点是否为 Leader
  • 通过 current_leader 字段找到当前集群的 Leader 节点
  • 通过 last_log_index 和 last_applied.index 检查日志同步状态
  • 通过 heartbeat 监控集群节点的活跃状态
  • 通过 membership_config 了解集群成员配置

错误码说明 ​

错误码说明
0请求成功
400请求参数错误
401未授权
403禁止访问
404资源不存在
500服务器内部错误

使用示例 ​

基本请求示例 ​

bash
# 获取服务版本
curl -X GET http://localhost:8080/

# 获取集群状态
curl -X GET http://localhost:8080/api/status

# 带分页的列表查询
curl "http://localhost:8080/api/cluster/user/list?limit=10&page=1&sort_field=username&sort_by=asc"

错误处理示例 ​

bash
# 当请求失败时，会返回错误信息
{
  "code": 400,
  "message": "Invalid parameter: username is required",
  "data": null
}

注意事项 ​

  1. 请求方法:
    • 列表/详情查询（/list、/detail、/api/status 等）使用 GET，参数通过 query string 传递
    • 创建/删除操作（/create、/delete）使用 POST，参数通过 JSON body 传递
  2. 请求体: POST 接口需要设置 Content-Type: application/json 并传递 JSON body；GET 接口参数通过 URL query string 传递
  3. 时间格式:
    • 输入时间使用 Unix 时间戳（秒）
    • 输出时间使用本地时间格式字符串 "YYYY-MM-DD HH:MM:SS"
  4. 分页: 页码 page 从 1 开始计数
  5. 配置验证: 创建资源时会验证配置格式的正确性
  6. 权限控制: 建议在生产环境中添加适当的认证和授权机制
  7. 错误处理: 所有错误都会返回详细的错误信息，便于调试
  8. 内容类型: 请求必须设置 Content-Type: application/json 头部

开发和调试 ​

启动服务 ​

bash
# 启动 admin-server
cargo run --bin admin-server

# 或者使用已编译的二进制文件
./target/release/admin-server

测试连接 ​

bash
# 测试服务是否正常运行
curl -X GET http://localhost:8080/

日志查看 ​

服务运行时会输出详细的日志信息，包括：

  • 请求路径和参数
  • 响应状态和数据
  • 错误信息和堆栈跟踪

最后更新: 2026-03-20

🎉 既然都登录了 GitHub，不如顺手给我们点个 Star 吧！⭐ 你的支持是我们最大的动力 🚀