MQTT Broker 与 Connection 设置

创建 Broker 端点

打开 Connections 并选择 New Broker。为端点填写便于识别的名称，选择传输协议，然后填写 Broker Host 和 Listener Port。

没有现成端点？从免费公共 MQTT Broker 列表选择一个。

配置 mqtts、wss 或 quic 前，先用 TLS 证书配置指南判断是不上传、只上传 CA，还是同时配置 CA、客户端证书与私钥。

mqtt:// — TCP · 默认端口 1883

• 直接连接 Broker 的 TCP Listener。
• Host 使用 127.0.0.1，Port 使用 1883。

123

mqtts:// — TCP + TLS · 默认端口 8883

• 通过 TLS 直接连接 MQTT。
• 验证服务器身份用于检查 Broker 证书。公有证书选系统 CA；私有 CA 选自定义 CA。
• SNI 默认选自动，ALPN 默认留空；Broker 指定时再填写。只有 Listener 要求客户端证书和私钥时才开启 mTLS。

123

ws:// — WebSocket · 默认端口 8083

• 先完成 HTTP WebSocket Upgrade，再传输 MQTT，不使用 TLS。
• 必须填写 WebSocket Path，并以 / 开头；常见默认值是 /mqtt。
• Path 使用 Broker 或反向代理配置的值。该协议不显示 TLS 参数。

12

wss:// — WebSocket + TLS · 默认端口 8084

• 与 ws 一样使用 WebSocket Path，再通过 TLS 保护连接。
• Path、服务器证书信任、SNI 和 ALPN 必须与 Listener 或反向代理一致。
• Listener 要求客户端证书和私钥时再开启 mTLS。

123

quic:// — QUIC · 默认 UDP 端口 14567

• 仅用于 Broker 已开启 MQTT-over-QUIC Listener 的情况。
• 填写 Host 和 UDP Port，不显示 WebSocket Path。
• 服务器验证、CA 信任、SNI、ALPN 和可选 mTLS 需匹配该 Listener。

123

点击 Test Connection，再点击 Create。绿色 Connection OK 表示端点接受图中列出的 MQTT 版本；客户端认证和会话参数会在创建 Connection 后验证。

创建 MQTT Connection

Broker 保存后，选择 New Client。

• Name / Client ID： Name 只用于显示；Client ID 是 Broker 看到的身份，在线客户端必须唯一。恢复旧会话时还要保持 Client ID 稳定。
• MQTT 版本： 优先使用 Broker 支持的 5.0；设备只支持 3.1.1 时选择 3.1.1；3.1 只用于明确的旧系统。
• 认证： 使用 MQTT 5.0 时，按 Listener 要求选择 None、Password、JWT 或 SCRAM。凭据、SecretRef、JWT Claim 与 SCRAM 的具体要求请看认证方式指南。
• Clean Start： 第一次测试保持开启；关闭表示请求恢复已有会话，不是自动重试开关。
• Keep Alive： 空闲时通过 PINGREQ/PINGRESP 检查连接。默认 300 秒；0 表示关闭 MQTT Keep Alive。
• Session Expiry Interval： MQTT 5 中，0 表示断开后立即丢弃会话；正数表示保留秒数；4294967295 表示不过期。第一次测试保持 0。

123

没有明确要求时，其余 MQTT 5 参数保持默认：

• Receive Max / Topic Alias Max： 分别限制未确认的 QoS 1/2 消息数和可接收的 Topic Alias 数。
• Maximum Packet Size： 可接收的最大 MQTT 报文；设置过小会拒绝合法消息。
• Request Problem Info / Request Response Info / User Properties： 用于 MQTT 5 响应信息或应用元数据。
• Last Will： 只在消费者已经约定 Will Topic、Payload 和 QoS 时配置。

连接并核对证据

点击 Start，检查三处：

1. 客户端状态为 已连接，不是“连接中”或“重试中”。
2. Session 列显示预期的 Clean、300s 等摘要。
3. Trace 中先出现发送的 CONNECT，再出现收到的 CONNACK，Reason 为 Connection Accepted。

123

已连接不代表 Topic 有权限，也不代表消息已送达。 用第一条 MQTT 消息教程继续验证订阅、发布和 Trace。

快速排查

• 保存的 Connection 无法连接或意外断开： Mqttable 显示 Retrying 并自动重试：建连失败后等待 10 秒，已连接的 Connection 意外中断后等待 5 秒。重试会持续到连接成功或你选择 Stop。
• Test Connection 失败： 这是一次性的端点检查，不会进入自动重连循环。先检查 Host、Port、DNS、防火墙和 Listener 是否启动。
• TLS 或 WebSocket 失败： 检查 CA、服务器名称、客户端证书和 WebSocket Path。
• 收到拒绝的 CONNACK： 检查 MQTT 版本、Client ID 和认证材料。
• 已连接但不能发布或订阅： 检查 Topic ACL，而不是继续修改端点。

下一步

• MQTT 快速入门
• MQTT 认证：Password、JWT 与 SCRAM
• 看懂并配置 MQTT TLS 证书
• 安全管理 Credentials、TLS 与认证材料
• 验证 MQTT 消息投递与定时发布