高级进阶

MQTT 5

Clean Start 和会话过期间隔

MQTT 5.0 引入了 Clean Start 和会话过期间隔（Session Expiry Interval）这两项特性，相比于 MQTT 3.1.1 的清除会话（Clean Session）提供了更多的灵活性。

在 MQTTX 中使用时，如果设置了 Clean Start，为了使其生效，需要设定会话过期间隔。默认情况下，如果关闭了 Clean Start，那么会话过期间隔默认设置为 7200 秒（两小时）。如果需要设置为永不过期，可以点击输入框右边的清除按钮，清空值后会话将永不过期。然而，如果关闭会话过期间隔，MQTTX 会自动将会话过期间隔设置为 0，即连接一旦断开，会话立即结束。

用户属性

点击新建按钮来到新建客户端页面，首先我们需要选择 MQTT 的版本为 5.0。这样，下方就会出现配置用户属性的卡片。卡片内包含一个可配置键值对的输入框。您可以点击右上角的添加按钮来增加用户属性配置，也可以点击每一行末尾的删除按钮删除配置。最后输入需要配置的属性名称和内容即可。连接成功后，MQTT 服务器就能获取到该客户端的用户属性内容。

除了在客户端连接时配置用户属性外，该版本还支持在发布消息时配置用户属性。当新建连接为 MQTT 5.0 的客户端时，我们可以看到发布消息区域的右下角出现了一个 Meta 按钮。点击该按钮即可看到配置发布时属性的卡片，在卡片顶部可以配置用户属性。

请求响应

点击 Meta 按钮，在输入框内输入一个响应主题：/ack/1，以及一个对比数据：light。然后，在当前连接客户端订阅一个 /ack/1。

内容类型和载荷格式

点击 Meta 按钮，在输入框内输入 Content-Type，并设置 Payload Format Indicator 的值。设置完成后，就可以发布消息了。

订阅标识符和订阅选项

打开订阅主题的弹出框，下方可以设置 Subscription Identifier 和订阅选项，订阅选项包括 No Local、Retain as Published 和 Retain Handling。用户可以在订阅报文中指定一个数字作为订阅标识符，并在消息分发时返回此标识符。这样，客户端就能建立订阅标识符与消息处理程序的映射，当收到 PUBLISH 报文时，可以直接通过订阅标识符将消息定向至对应的消息处理程序。同时，用户还可以配置这些订阅选项来改变服务器的行为。

设置

您可以通过点击左侧菜单栏底部的设置按钮或使用快捷方式来访问设置。macOS 用户可以使用 command +,，而其他用户可以使用 control +,。设置页面包括了分为通用、外观和高级三个部分的多项选项。

通用

通用设置允许您进行 MQTTX 的基本操作定制。在这里，您可以选择您喜欢的语言，启用或禁用自动更新，启用多主题订阅，并设置最大重连次数以在网络不稳定的情况下保持连接的连续性。

外观

外观设置允许您定制 MQTTX 界面的外观。您可以选择三种主题：Light，Dark 和 Night。另外，还有一个选项可以将 MQTTX 主题与您的操作系统同步，以实现一致的用户体验。

安装 MQTTX CLI 工具

从 v1.10.1 起，MQTTX 桌面客户端支持一键安装 MQTTX 命令行工具。用户只需点击安装按钮，即可自动完成安装过程，无需额外操作。整个过程通过图形界面进行，无需用户跳转到下载页面手动下载和配置。此功能自动提供最新版本的 MQTTX CLI，使得在下载桌面端的同时也能轻松获取到命令行工具，方便用户在多种使用场景下操作。

使用方法：

1. 进入设置页面 -> 找到 MQTTX CLI -> 点击右侧安装按钮。
2. 或点击顶部菜单，选择安装 MQTTX CLI 选项。

点击后，桌面客户端会自动下载并安装适合您系统的安装包。在安装过程中，您可能需要输入密码以授权访问权限。安装完成后，您便可以在任何命令行窗口中直接运行 mqttx 命令。

注意：对于 Windows 用户，点击安装后需要手动下载 MQTTX CLI 的 exe 程序，然后在对应目录下进行使用。

高级（数据管理）

在高级设置中，包含了数据备份，恢复和历史记录清理。

对于数据备份，包括所有接收和发送的消息的所有连接数据都会被导出，以确保您的连接信息和消息历史的安全。在数据恢复过程中，您需要选择要导入的文件的路径。一旦确认了文件路径，您的数据就会被恢复。这些操作支持的文件格式包括 JSON，XML，CSV，Excel 和 YAML。

如果必要，您可以清除历史记录以管理您的数据使用或保护您的隐私。

忽略 QoS 0 消息

在设置中，您可以选择开启或关闭对 QoS 0 消息的忽略功能。QoS 0（服务质量等级 0）消息是最基本的消息传递方式，不保证消息的交付，也不进行重试。对于某些应用场景，您可能希望忽略这些消息以减少不必要的网络流量或处理开销。

操作步骤

1. 打开设置页面。
2. 找到“忽略 QoS 0 消息“选项。
3. 切换开关至”开启”或”关闭”状态。

功能说明

• 开启：MQTTX 将忽略 QoS 0 的消息，消息将只显示到页面上，不会将其存储到本地，从而提高性能和减少不必要的存储开销。
• 关闭：所有 QoS 0 消息将正常接收和处理。

注意：已保存的 QoS 0 消息不会被自动清除。

脚本

自定义函数

此功能允许用户根据特定的需求或场景，编写自定义的函数代码，自由地对 Payload 的内容和格式进行调整和转化，实现更为精细化的数据管理和处理。如果同时配合定时发送功能，可以实现模拟数据报告的自动化测试等功能。

自定义函数使用示例可以在 scripts-example/function 文件夹中查看。如果你在使用中有更好、更实用的脚本，可以在此提交你的代码，让更多的人可以使用。

使用 JavaScript

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 自定义函数页面中，用户可以在顶部的代码编辑器中编写 JavaScript 代码。全局只有一个 execute API，用户需要编写一个接收 value 参数的自定义函数，此参数即为 Payload，函数可以自定义修改 value，最后通过 execute 传参执行自定义函数。

下方还有一个 输入 和 输出 框，可以输入预期的输入值，点击右侧的 测试 按钮可以在 输出 框中查看执行结果。输入值的格式包括 JSON 和 Plaintext，方便用户提前调试自定义函数。测试完成后，可以点击右上角的 保存 按钮，输入自定义函数名称保存自定义函数。保存后即可到连接页面使用，已保存的自定义函数也可以编辑和删除。

默认 JavaScript 函数示例如下：

/**
* @description: 默认脚本
* @param {any} value - Payload
* @param {string} msgType - 消息类型，值是 'received' 或 'publish'
* @param {number} index - 消息的索引，仅在脚本用于发布消息并启用定时消息时有效
* @return {any} - 脚本处理后的Payload
*/
function handlePayload(value, msgType, index) {
  return value.msg
}
execute(handlePayload)

编解码

此功能允许用户根据实际需求编写自定义的编解码文件，来对发送和接收的 Payload 进行编解码。在具体应用中，用户可以根据数据特性或特定的应用场景，编写特定的编解码规则。这个过程类似于为 Payload 设计一种特定的“语言”，并通过编写编解码文件来定义这种“语言”的翻译规则。这样，无论是发送还是接收 Payload，都可以根据这些规则来进行编码或解码，确保数据的正确理解和有效传输。

编解码使用示例可以在 scripts-example/schema 文件夹中查看。如果你在使用中有更好、更实用的编解码，可以在此提交你的代码，让更多的人可以使用。

使用 Protocol Buffers

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 编解码页面中，用户可以在顶部的下拉框中选择 Protobuf，然后在代码编辑器中编写 proto 文件。

下方还有一个 输入 和 输出 框，可以输入预期的输入值。输入定义的消息类型的名字之后，点击右侧的 测试 按钮可以在 输出 框中查看执行结果。输入值的格式包括 JSON 、 Plaintext 、Base64 和 Hex，方便用户提前调试自定义的编解码。输入 JSON 或者经过 Base64 和 Hex 编码后的 JSON 字符串，测试完成后，可以点击右上角的 保存 按钮，输入编解码名称保存编解码。保存后即可到连接页面使用，已保存的编解码也可以编辑和删除。

默认 Protocol Buffers 编解码文件示例如下：

syntax = "proto3";

message Person {
  int32 id = 1;
  string name = 2;
}

使用 Avro Schema

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 编解码页面中，用户可以在顶部的下拉框中选择 Avro，然后在代码编辑器中编写 avsc 文件。

下方同样支持输入预期的输入值，点击右侧的 测试 按钮可以在 输出 框中查看编解码的执行结果，使用方法与 Protobuf 基本相同。

使用 Avro 编解码文件示例如下：

{
  "type": "record",
  "name": "Person",
  "fields": [
    { "name": "id", "type": "int" },
    { "name": "name", "type": "string" }
  ]
}

工作流

如果用户同时使用了脚本的自定义函数功能和编解码功能，MQTTX 将使用一种高效的脚本工作流，涵盖了发布和订阅两个阶段。

在发布阶段，脚本工作流首先调用自定义函数来处理输入数据。经过这些自定义函数处理后，产生的消息将被显示出来。随后，将使用编解码对处理后的消息进行编码。

在订阅阶段，脚本工作流首先接收传入的编码消息。接收到消息后，编解码立即被调用以进行解码。解码后的消息会送入自定义函数进行处理。处理完成后，处理过的消息将被显示出来。

这种的脚本工作流设计允许用户灵活地在发布和订阅阶段处理数据，并保证了消息在传输过程中的安全和完整性。

使用指南

1. 导航到连接页面，点击页面右上角的下拉菜单。在下拉菜单中，选择 运行脚本 选项。
   
2. 这将会弹出一个脚本窗口，从中选择选择脚本要应用的位置，选项包括发布、接收和全部。然后，选择需要使用的自定义函数或者编解码。
   
3. 编解码选择框中，选择需要使用的编解码，当前支持 Protobuf 和 Avro 两种编解码。
   
4. 如果您看到在发布或者订阅的消息卡片上看到脚本使用提示，那么说明脚本功能已经被成功调用。
   
5. 如果您需要取消使用脚本，可以点击顶部状态栏中红色的 停止脚本 按钮，这将停止使用脚本。
   

日志

从 v1.5.0 版本开始，MQTTX 引入了日志功能，以帮助用户调试连接和报告错误。在生产环境中，日志系统会显示四个级别的信息：

• DEBUG 提供详细的调试信息，包括 MQTT.js 数据包的细节，便于排查问题
• INFO 用于提示用户操作信息
• WARN 生成不安全行为或潜在风险的警告
• ERROR 在失败时产生错误消息

默认情况下，日志将写入以下位置的日志文件，具体取决于您的操作系统：

操作系统	日志文件路径
Linux	~/.config/MQTTX/logs/log
macOS	~/Library/Application Support/MQTTX/logs/log
Windows	%USERPROFILE%\AppData\Roaming\MQTTX\logs\log

每次关闭 MQTTX 时，当前的日志文件都会根据时间戳重命名，格式为[YY]-[MM]-[DD]T[hh]:[mm].log。

视图器

从 v1.11.0 版本开始，MQTTX 引入视图器功能，提供 MQTT 数据可视化能力，帮助用户更直观地理解和监控消息流。

主题树（Beta）

主题树以层级结构展示 MQTT 主题和消息，让用户能够清晰地了解主题间的层级关系和消息流转。

注意：主题树功能目前为 Beta 版本，可能存在功能不完整或不稳定的情况。

主题树功能位于左侧菜单栏的"新建连接"下方的视图器菜单中。使用时，需要先创建一个连接并订阅相关主题，当订阅的主题收到消息后，主题树会自动更新。

页面主要包含搜索框、操作按钮区、主题树显示区和右侧详情面板等部分。在操作区域，你可以进行一键展开/折叠节点、查看可视化显示，同步连接历史消息为主题树和清除主题树等操作。

主题树中的节点分为三类：

• 根节点（Host 节点）：显示当前接收消息的客户端信息，包括客户端 ID、Host 信息、连接名称和包含的子主题节点。
• 中间节点：包含子主题节点，点击后可以查看当前节点的完整主题路径和包含的子主题。
• 叶子节点：显示接收到的最新消息，包含完整主题路径、接收时间、Retain 标识和 QoS 值。

每个节点名称旁都会显示子节点数量和消息数量。点击节点前的折叠按钮可以展开或折叠子节点，点击节点本身则在右侧显示详细信息。

注意：当删除对应的连接或清空连接内的消息时，主题树中对应的内容也会被清空。

可视化主题树

在更多操作中选择"可视化主题树"后，MQTTX 将以图形化方式展示当前连接的主题结构。相比列表形式，这种展示方式更加直观，便于理解主题的分布情况。

你可以在弹出框上方选择不同的 Host 节点，并调整默认展开层级（默认为 4 层）。通过展开/折叠按钮，可以随时调整查看的层级深度。当鼠标悬停在节点上时，会显示该节点的主题路径、消息数量和子节点数量等信息。

注意：如果数据在实时更新，可视化树会根据当前展开层级实时刷新。需要查看更深层的数据变化时，可以增加展开层级数。

同步连接数据

当主题树接收到新消息时会自动同步到连接页面的消息列表中。同时，MQTTX 也支持将连接页面的历史消息数据手动同步到主题树视图中。您可以通过以下两种方式进行同步：

1. 在连接页面：
   • 点击右上角下拉菜单中的"同步主题树"选项
   • 选择要同步的连接
   • 系统会自动将该连接的消息记录转换为主题树结构
   
   
2. 在主题树页面：
   • 点击右上角下拉菜单中的"同步连接数据"选项
   • 选择要同步的连接
   • 查看同步后的主题树视图
   
   
   

注意：

• 建议在连接空闲时进行数据同步，以确保数据准确性
• 同步后的主题树将显示每个主题的最新消息

清空主题树

在更多操作中选择"清除主题树"选项可以清空当前连接的主题树内容。

流量监控

从 v1.11.1 版本后当前流量统计功能已经从连接页面迁移到了视图器菜单下，并增强了数据分析能力。通过可视化图表展示 MQTT Broker 的流量数据，能帮助用户实时监控连接的收发数据状况，直观分析流量趋势和峰值，及时发现潜在的网络问题，优化系统性能和资源配置。

访问流量监控有两种便捷方式：

• 在连接页面，点击右上角的流量监控图标直接进入
• 通过左侧菜单栏，选择 视图器 -> 流量监控

从连接页面进入时，MQTTX 会自动帮你订阅 $SYS/# 系统主题，无需手动操作。如果你是从菜单直接访问，则需要先手动订阅系统主题才能看到监控数据。

注意：EMQX 默认只允许本地主机（localhost）上的客户端订阅 $SYS 主题。如果你在远程访问时遇到订阅失败，需要修改 EMQX 的 ACL 规则设置。具体配置可参考 EMQX 文档中的内置 ACL 规则说明。

顶部控制栏

界面上方有连接选择器，当从连接页面跳转时，会自动选中对应的连接，同时可以切换要监控的连接并查看其连接状态。右侧是时间范围的选择器，默认显示近 24 小时的数据。

时间选择器默认提供了过去 5 分钟，30 分钟，1 小时，1 天，1 周等时间范围，点击后可以切换时间范围来查看不同时间段的监控数据。

累计值统计

流量统计中卡片为显示最新的累计值，下面是一个折线图，标识累计值的增长趋势。

速率统计

下面是速率统计，卡片显示最新的速率信息，下面显示的当前时间平均的收发速率。

注意：速率数据是根据 MQTT Broker 发送系统主题的时间间隔计算得出。采样间隔越短，数据越准确。您可以在 MQTT Broker 配置中调整系统主题的发送间隔以获得更精确的数据。

其他

连接操作

通过点击顶部的操作栏按钮，您可以快速执行各种连接操作，如断开连接、删除当前连接、导入和导出数据，以及管理定时消息和流量统计等功能。

消息处理

您可以通过选择消息栏右上角的 "全部"、"接收" 或 "发布" 按钮来筛选消息。

点击顶部的操作栏按钮，选择 "搜索" 选项，或使用快捷键。macOS 用户可以使用 command + f 快捷键，其他用户可以使用 control + f 快捷键打开主题搜索功能，支持模糊查询主题和负载。

点击顶部的操作栏按钮，选择 "清除历史记录" 选项，可以快速清除当前连接的发送和接收消息。

检查更新

点击左下角的 "i" 按钮进入 "关于" 页面，可以查看 MQTTX 的版本信息和相关的 EMQX 信息。点击 "检查更新" 按钮可以检查是否有新版本可用。

多窗口

在连接列表中，右键单击并选择 "新建窗口" 可以为连接创建一个新窗口。在新窗口中，您可以建立连接、订阅主题、发布和接收消息等。如果有多个连接或需要同时查看接收到的消息，可以创建多个视图窗口并并排显示。从 v1.4.1 版本开始，用户还可以点击顶部的窗口按钮快速创建新窗口。

定时消息

在右上角的下拉菜单中，您可以选择 "定时消息" 选项来设置发送频率（以秒为单位）。设置完成后，手动发送一条消息，MQTTX 将按照指定的频率自动发送该消息。