管理 API

TMQTT 提供 HTTP REST API，用于查看 Broker 运行状态、管理客户端会话、触发热重载等操作。

---

基础信息

项目	说明
默认监听地址	0.0.0.0:8080
协议	HTTP
数据格式	JSON
鉴权	当配置 api.auth_token 后，所有接口（除 /healthz）需在请求头中携带 Authorization: Bearer <token>

---

接口列表

健康检查

接口	方法	说明
/healthz	GET	健康检查端点，无需鉴权，用于负载均衡健康探测

节点管理

接口	方法	说明
/api/v1/node/status	GET	获取当前节点运行状态，包括节点 ID、运行时间、连接数、消息统计等

会话管理

接口	方法	说明
/api/v1/sessions	GET	获取所有活跃会话列表
/api/v1/sessions/{client_id}	GET	获取指定客户端的会话详情，包括订阅主题列表、Inflight 消息数、连接时间等
/api/v1/sessions/{client_id}	DELETE	踢出指定客户端（主动断开连接），可用于故障排查或强制下线

保留消息

接口	方法	说明
/api/v1/retained	GET	获取所有保留消息列表
/api/v1/retained/{topic}	DELETE	删除指定主题的保留消息

配置管理

接口	方法	说明
/api/v1/config/reload	POST	触发配置文件热重载，修改 config.toml 后无需重启即可生效

集群管理

接口	方法	说明
/api/v1/cluster/state	GET	获取集群整体状态，包括成员列表、各节点角色和运行状态
/api/v1/cluster/members	GET	获取所有集群成员信息
/api/v1/cluster/members/{node_id}	GET	获取指定节点的详细信息
/api/v1/cluster/members/{node_id}/drain	POST	将指定节点设为 Drain 模式，停止接受新连接（用于维护或升级）
/api/v1/cluster/members/{node_id}/leave	POST	将指定节点从集群中移除
/api/v1/cluster/forward	POST	将请求转发到指定节点

消息桥接

接口	方法	说明
/api/v1/bridge/rules	GET	获取所有桥接规则列表
/api/v1/bridge/rules	POST	创建新的桥接规则
/api/v1/bridge/rules/{id}	GET	获取指定规则详情
/api/v1/bridge/rules/{id}	PUT	更新指定规则
/api/v1/bridge/rules/{id}	DELETE	删除指定规则
/api/v1/bridge/rules/{id}/sinks	GET	获取规则关联的所有 Sink 状态
/api/v1/bridge/rules/{id}/sinks/{name}	GET	获取指定 Sink 详情（连接状态、成功率、熔断状态等）
/api/v1/bridge/rules/{id}/sinks/{name}/dlq	GET	查看指定 Sink 的死信队列消息
/api/v1/bridge/rules/{id}/sinks/{name}/dlq/retry	POST	重新投递死信队列中的消息

---

鉴权说明

当配置文件中设置了 api.auth_token 时，除 /healthz 外的所有接口需要携带鉴权头：

Authorization: Bearer <你的token>

未携带 Token 或 Token 错误的请求将返回 401 状态码。

建议：生产环境务必配置 auth_token，防止 API 被未授权访问。

---

使用示例

查看节点状态

curl http://localhost:8080/api/v1/node/status

查看所有会话

curl http://localhost:8080/api/v1/sessions

踢出指定客户端

curl -X DELETE http://localhost:8080/api/v1/sessions/bad-client-id

触发配置重载

curl -X POST http://localhost:8080/api/v1/config/reload

Copyright (c) 2026 桃子 TaoZi.Pub https://taozi.pub | MIT License