TMQTT - 集群 MQTT broker

Appearance

常见问题 ​

本文档汇总 TMQTT 使用中常见的问题和解决方案。

安装与启动 ​

Q：编译时报错，缺少 CMake 或 protoc？ ​

A： 部分功能依赖系统库，按需安装：

报错原因解决方法
缺少 CMake启用了 rocksdb 或 bridge-kafka Feature安装 CMake：apt install cmake（Linux）或 brew install cmake（macOS）
缺少 protoc集群功能需要 Protocol Buffers 编译器安装 protoc：apt install protobuf-compiler（Linux）
缺少 C++ 编译器RocksDB 需要 C++ 编译安装：apt install build-essential（Linux）

如果只使用单机模式且不启用 RocksDB/Kafka，可以不安装这些依赖。

Q：启动后提示无法绑定端口？ ​

A： 可能原因：

  1. 端口已被其他程序占用 → 检查并释放端口，或修改 TMQTT 配置中的监听端口
  2. 权限不足（Linux 绑定 1024 以下端口需要 root） → 使用普通端口或用 sudo 启动

Q：Windows 下启动失败？ ​

A： Windows 下集群功能需要 protoc，但单机模式无此限制。如果只是单机部署，确认未启用集群配置即可。

连接问题 ​

Q：客户端连接被拒绝？ ​

A： 依次排查：

  1. 匿名连接：确认 anonymous_allow 是否为 true，或者客户端是否提供了用户名密码
  2. 认证失败：检查用户名密码是否正确，或 JWT Token 是否有效且未过期
  3. 连接数上限：确认 listener.tcp.max_connections 是否已达到上限
  4. 速率限制：确认是否在短时间内频繁重连，触发了 max_connections_per_sec 限制

Q：WebSocket 连接失败？ ​

A： WebSocket 端口默认未启用。需要在配置文件中显式配置 [listener.ws] 段，并确保客户端使用正确的子协议（mqtt）。

Q：TLS 连接报错"certificate verify failed"？ ​

A： 可能原因：

  1. 客户端不信任服务端证书 → 将 CA 证书添加到客户端的信任列表
  2. 证书过期 → 更新服务端证书
  3. mTLS 模式下客户端未提供证书 → 配置客户端证书

消息问题 ​

Q：发布的消息客户端收不到？ ​

A： 依次排查：

  1. 订阅主题不匹配：确认客户端订阅的主题和发布的主题一致，注意通配符使用
  2. ACL 拒绝：确认 ACL 规则是否允许该客户端订阅该主题或发布该主题
  3. QoS 0 丢失：QoS 0 消息不保证送达，网络波动可能丢失，改用 QoS 1
  4. 客户端离线：如果是持久会话，消息会被缓存，重连后投递；临时会话则消息已丢弃

Q：离线消息重连后收不到？ ​

A： 确认以下条件：

  1. 客户端重连时使用了相同的 Client ID
  2. 重连时 Clean Session 设为 false
  3. 会话未超过 session_expiry_sec 过期时间
  4. 离线消息数未超过 max_offline_messages 上限

Q：Retain 消息新订阅者收不到？ ​

A： Retain 消息仅在有新订阅时推送。如果是同一个客户端反复取消/重新订阅，可能因客户端缓存而不重新推送。尝试使用不同的客户端 ID 测试。

集群问题 ​

Q：新节点无法加入集群？ ​

A： 确认以下条件：

  1. seed_nodes 配置了集群中至少一个正常运行的节点地址
  2. 节点间网络互通，集群通信端口（默认 7000）未被防火墙阻断
  3. 各节点 ID 唯一，没有重复

Q：集群状态显示某节点为 Failed？ ​

A： Gossip 健康检测到该节点心跳超时，可能原因：

  1. 节点网络中断或防火墙规则变更
  2. 节点进程崩溃
  3. 系统负载过高导致心跳延迟

确认网络连通性后，Gossip 会自动恢复该节点状态。如果节点确实不可用，可通过 API 将其从集群移除。

桥接问题 ​

Q：消息未转发到 Kafka/TDengine 等下游？ ​

A： 依次排查：

  1. 规则是否创建：通过 API 查看规则列表，确认规则存在且已启用
  2. 主题是否匹配：确认发布消息的主题符合规则配置的主题匹配模式
  3. Sink 状态：通过 API 查看 Sink 状态，是否处于熔断状态
  4. 下游连通性：确认下游服务（Kafka/TDengine 等）是否正常运行，网络是否可达

Q：Sink 进入熔断状态？ ​

A： 表示下游系统连续失败超过阈值（默认 5 次），熔断器已保护性暂停发送。

处理：

  1. 排查并修复下游系统问题
  2. 等待冷却期过后，熔断器会自动尝试恢复
  3. 如果消息积压，可检查死信队列（DLQ）中是否有失败的消息，通过 API 重新投递

管理 API ​

Q：API 返回 401 Unauthorized？ ​

A： 管理 API 已启用 Token 鉴权，请求需携带 Authorization 头：

Authorization: Bearer <你的token>

检查 Token 是否与配置文件中 api.auth_token 一致。

Q：如何查看当前配置是否生效？ ​

A： 修改 config.toml 后，TMQTT 会自动检测并热重载。如需手动触发，可调用 POST /api/v1/config/reload。

性能问题 ​

Q：消息延迟高？ ​

A： 常见原因和解决方式：

  1. QoS 2 开销大：QoS 2 需要四次握手，延迟最高，如对可靠性要求不是极高可改用 QoS 1
  2. 网络延迟：检查客户端与 Broker 之间的网络质量
  3. 下游阻塞：如果启用了桥接，下游慢可能导致整体延迟，检查 Sink 的发送延迟指标

Q：内存占用持续增长？ ​

A： 检查以下配置：

  1. max_offline_messages：离线消息缓存上限，0 表示不限制，建议设置合理值
  2. session_expiry_sec：会话过期时间，过长会导致离线会话积累过多
  3. slow_consumer.drop_on_full：确保慢消费者队列满时丢弃消息而非堆积

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