常见故障排查

连接失败或持续重连

1. 检查主机、端口、传输协议是否对应 broker 监听配置。
2. 验证测试账号和访问权限，观察 broker 日志。
3. 排除重复 Client ID、网络中断和端口不可达。
4. TLS 场景核对主机名、证书链与系统时间。
5. WebSocket 场景确认路径限制，见传输协议。

不断点击连接不能修复权限或证书错误。记录第一条明确错误通常比截取最后一条重试日志更有用。

已连接却没有收到

先看订阅是否生效，再核对发布 Topic 与过滤器、大小写、连接地址和 broker ACL。普通非保留消息需要先订阅再发布。

清除实时方向、Topic 和订阅过滤，确认没有把 RX 隐藏。只有 TX 记录不表示接收已经完成。

发送按钮不能点击

确认连接已建立、主题不为空，JSON 模式下内容合法，且不是正在发送或退出。需要空载荷时选择 Text。

HEX 与预期不一样

当前 HEX 发送是将输入文本转为 UTF-8 字节，不解析十六进制文本。48 65 会产生五个字符字节。先用载荷示例表核对。

历史窗口没有记录

检查连接、关键词、Topic、方向与页码；在主窗口查找保存失败或数据库错误。收包日志入库和消息历史是不同设置。

实时列表达到上限并不表示所有数据都已丢失，去历史查询核对。不要通过删除数据库来“刷新”记录。

大消息或高流量卡顿

缩小订阅范围，使用紧凑密度，控制实时消息和日志条数，关闭不必要的收包日志入库，降低 JSON 自动格式化上限。

实时条数是显示保留策略，不是 broker 消息配额。定时发送也不是压力测试器；性能取决于实际载荷、订阅数量和运行环境。

窗口或更新异常

先记录「关于」中的版本与运行环境。检查更新失败不影响你对既有 broker 的手动连接；网络或更新服务不可用可能造成检测失败。

若能复现，记录最短操作链路、错误截图和日志，使用反馈模板。