MQTT Broker 与 Connection 设置

创建 Broker 端点

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

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

配置 mqtts、wss 或 quic 前，先用 TLS 证书配置指南判断是不上传、只上传 CA，还是同时配置 CA、客户端证书与私钥。下方的 broker.example.com 只是未测试的占位地址，不是可用端点。

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

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

123

截图说明：浅色回环截图使用隔离的 18883 端口，因为截图机器的 1883 已被占用。实际操作时以获授权本地 Broker 的监听端口为准。

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。Broker 测试不携带 MQTT 用户名和密码，但使用当前 TLS 配置，包括启用的客户端证书。测试分别列出各 MQTT 版本的结果；一个成功、一个失败时显示部分成功。认证拒绝不妨碍保存 Broker，测试也不验证发布或订阅权限。

创建 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 Session / Clean Start： MQTT 3.1／3.1.1 显示 Clean Session；关闭时请求恢复并保留会话。MQTT 5 显示 Clean Start，只决定连接时是否丢弃旧会话，断线后的保留时长由 Session Expiry Interval 决定。第一次测试保持开启；它不是自动重试开关。
• 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： 开启时允许 Broker 在协议允许的报文中返回诊断字符串和用户属性；关闭时发送 Request-Problem-Information=0。这不隐藏原因码，也不禁止 PUBLISH、CONNACK 或 DISCONNECT 中规范允许的信息。
• Request Response Info： 请求 Broker 在 CONNACK 中提供 Response Information；Broker 可以不返回。它不会自动创建响应订阅。
• User Properties： CONNECT 的应用元数据，不会自动复制到之后发布的消息。
• Last Will： 只在消费者已经约定 Will Topic、Payload 和 QoS 时配置。

保存前测试 Client 认证

在 Add client 或 Edit Client 中选择测试连接，即可立即测试当前表单，不需要二次确认。测试使用所选 MQTT 版本和凭据，包括输入的密码或 JWT、保留的已保存密码、所选 SecretRef 或 SCRAM 认证，不会保存表单，也不会启动持续运行的 Client 连接。

按钮上方的紧凑浮层显示进度和结果。展开详情可查看端点、Client ID、协议和失败信息，不会显示敏感凭据。测试中关闭浮层或按 Escape 会取消测试；测试完成后关闭浮层，底部仍保留结果，点击结果可再次查看而不重新测试。修改连接配置会清除结果，仅修改 Client 名称不会。

测试使用真实 Client ID，可能断开同 ID 的其他客户端、触发对方遗嘱，并影响 Broker 会话和排队消息。按钮旁的信息提示说明这些风险，但不要求确认。测试自身不注册遗嘱、不发布消息、不订阅主题，也不自动重连。测试通过不代表 Client 持续处于已连接状态，也不代表消息权限已验证。

Client 已连接时，底部直接显示已连接，不再提供测试按钮。在线修改连接参数后，还会显示当前修改尚未验证，避免把已有连接当成未保存配置的验证结果。连接中和重连中也不会提供重复测试入口。测试功能不会自动断开已有连接，原有保存行为保持不变；运行时状态更新也不会覆盖未保存的输入。

1

1

连接并核对证据

点击 Start，检查三处：

1. 客户端状态为 已连接，不是“连接中”或“重试中”。
2. Session 列显示会话设置和配置的客户端认证方式，例如 Clean、300s 和 Password（密码）。认证标记表示已保存的客户端配置，不代表 Broker 返回的认证结果，也不会显示密码或 Token。
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 消息投递与定时发布