MQTT 部署与排障

部署条件

所有承接 MQTT 流量的节点开启 mqtt.enable，使用匹配候选版本及工具，保持 namespace 一致。namespace 是稳定 ClientID 命名空间，不能随意修改以清理会话。遵守当前候选的停机升级约束；集成前 MQTT 开发候选数据不能直接视为升级来源，使用启用 MQTT 前的数据或单独验证的迁移。

单节点集群同样使用 256 个 hash slots。多节点部署仍需 Slot quorum 和内部通信；负载均衡不替代接管隔离证明。旧 Owner 无法证明停止时，即使其他 Slot 有 quorum，新 CONNECT 仍可能失败。

默认监听 0.0.0.0:1883；教程限制在回环地址。对外使用上游 TLS 终止，保护明文后端网络。mqtts:// 指向 TLS 代理，mqtt:// 指向原始 TCP，不能关闭证书验证。MQTT WebSocket 使用独立监听；已有 WKProto / JSON-RPC 监听不能接收 MQTT 帧。

字段、环境变量和范围统一维护在配置参考。同时保留认证配置。

浏览器 WebSocket 接入

保持 mqtt.enable=true，在原有 gateway.listeners 数组中追加：

{ name = "mqtt-ws", network = "websocket", address = "127.0.0.1:1884", transport = "gnet", protocol = "mqtt", path = "/mqtt" }

这是数组中的一个内联表项，不是完整 TOML 文件。每个监听使用独立地址。WK_GATEWAY_LISTENERS 以 JSON 替换整个数组，需保留仍使用的 WKProto 监听。MQTT WebSocket 共用 TCP 的认证、Topic、限额和持久会话；切换传输不会创建新的 MQTT namespace。IM /route 响应不发布该地址，由业务后端提供 URL。

安装 MQTT.js 5.16.0 的浏览器应用可使用后端签发的凭证连接：

import mqtt from 'mqtt';

const client = mqtt.connect('ws://127.0.0.1:1884/mqtt', {
  protocolVersion: 5,
  clientId: 'alice-browser-01',
  username: credentials.uid,
  password: credentials.token,
  clean: true,
  reconnectPeriod: 0,
  properties: {
    sessionExpiryInterval: 0,
    userProperties: { 'wk.device_flag': '1' },
  },
});
client.on('error', () => console.error('MQTT connection failed'));

credentials 来自可信业务后端，后端登记相同 WEB 设备类别的 Token。先注册接收事件，再发送；Topic 和确认规则见快速开始。持久恢复需保留稳定 ClientID 并遵守会话与 QoS 条件。

MQTT.js 自动提供大小写敏感的 mqtt WebSocket 子协议并发送二进制数据。监听返回 mqtt；缺少或不匹配的子协议返回 HTTP 400，错误路径返回 HTTP 404。文本数据会关闭连接；支持二进制 continuation、跨消息拆包和单消息合包。控制 ping/pong/close 帧保留普通 WebSocket 行为。这些要求来自 MQTT 5 第 6 节。

HTTPS 页面通过 TLS 代理使用 wss://。代理需转发 /mqtt、HTTP Upgrade 和子协议头，并保护明文后端监听。该传输不提供原生 TLS 或 WebSocket 压缩。

备份与迁移

wkcli db export 的 JSONL 格式尚不支持 MQTT 持久状态，包括 ClientID/UID 绑定、订阅、未完成交换、Will、共享回放和容量记录。发现这些数据时，导出在创建或覆盖输出目录前拒绝操作。关闭 MQTT 开关或等待 Session 过期不会解除这一限制。

保留原数据，使用匹配版本的原生备份与恢复流程。不要通过删除 MQTT 表、回放或恢复记录来绕过拒绝；这些数据可能仍承担投递责任或保存身份绑定。

配额如何生效

正文由多个会话共享时，在每个保留副本上计一次。普通历史、WAL、压缩整理和物理放大不计入逻辑限制。容量满限制新责任，保留已接收回放与未知结果，确认退休后才释放预留。不能靠删除数据或关闭连接声称容量已回收。

大群评估同时观察成员数、在线客户端数、消息速率、ACK 延迟、积压与磁盘余量。十万群成员不等于十万在线连接，演示或局部结果不能推广为容量保证。

按现象定位

保留时间、节点、脱敏 ClientID、Topic、Reason Code、Session Present、MessageID 和公开指标。不要记录 Token 或敏感 payload。业务重试遵守幂等键约定。

公开观测

开启 metrics 后，从 /metrics 观察 wukongim_mqtt_subscription_closures_total、wukongim_mqtt_storage_bytes、wukongim_mqtt_storage_events_total、wukongim_mqtt_owner_work 和 wukongim_mqtt_consumer_work。计数器可能重复计尝试，不是唯一连接数、消息数或回收证明。

先关联指标与客户端观测，再读取有界日志。见健康与监控和故障排查。