保留消息 ​EMQX 实现了 MQTT 的保留消息功能。您可以将某个特定主题下发布的消息标记为“保留消息”，并将其保存为 EMQX 上的持久消息。当任何新的订阅者订阅与保留消息的主题匹配的主题时，他们会立即接收到该消息，即使该消息是在他们订阅该主题之前发布的。

您可以使用客户端工具连接 EMQX 并尝试这个消息服务。本节介绍如何使用 MQTTX Desktop 和 MQTTX CLI 模拟客户端，并查看如何发布和接收保留消息。

前置准备

了解 MQTT 的保留消息。能使用 MQTTX 进行基本的发布和订阅操作。使用 MQTTX Desktop 发布保留消息 ​启动 EMQX 和 MQTTX Desktop。点击新建连接创建一个名为 Demo 的客户端连接作为发布者。

在名称栏中输入 Demo。在本演示中，服务器地址使用本地主机 127.0.0.1 作为示例。其它设置保持默认，点击连接。TIP

MQTTX Desktop 中介绍了更多详细的连接创建信息。

连接成功后，在文本框中输入主题 sensor/t1，并按照屏幕截图中的方式编写消息 payload。点击发送按钮。主题为 sensor/t1的消息将出现在消息对话框中。

发布两条主题为 sensor/t2 的保留消息。

输入 1 作为第一条消息内容。选中 Retain。点击发送按钮。输入 2 作为第二条消息内容。点击发送按钮。点击连接窗格中的 + -> 新建连接创建另一个新连接作为消息接收客户端。将名称设置为 Subscriber，其他连接基础信息与客户端Demo 相同。

点击 + 添加订阅，设置订阅 Topic 为 sensor/+ ，点击确定。

TIP

当主题设置为 sensor/+时，客户端同时订阅了主题 sensor/t1 和 sensor/t2。有关主题和通配符的更多信息，请参阅理解 MQTT 主题和通配符。

您将看到客户端 Subscriber 只收到了最后一条保留消息，而没有收到主题 sensor/t1 的第一条消息和主题 sensor/t2 的第一条保留消息，因为 EMQX 仅存储每个主题的最新保留消息。

现在您已经尝试了使用 MQTTX 客户端发布保留消息。您还可以通过 EMQX Dashboard 查看保存在 EMQX 中的最后一条保留消息，详见在 Dashboard 中查看保留消息。

使用 MQTTX CLI 发布保留消息 ​使用一个客户端发起连接请求。

使用以下命令发布一条保留消息。将主题设置为t/1，payload 设置为A retained message from MQTTX CLI，并设置 retain = true：

bashmqttx pub -t 't/1' -m 'A retained message from MQTTX CLI' --retain true -h 'localhost' -p 1883使用另一个新的客户端连接请求连接到同一个 broker。使用新客户端订阅主题 t/1，它将接收到保留消息。

如果您连续创建新的客户端并让它们订阅主题 t/1，则所有新创建的客户端都将接收到保留消息。

bash$ mqttx sub -t 't/1' -h 'localhost' -p 1883 -v

topic: t/1

payload: A retained message from MQTTX CLI

retain: true发布一个空消息以清除保留消息：

bashmqttx pub -t 't/1' -m '' --retain true -h 'localhost' -p 1883创建一个新的客户端连接并订阅主题t/1。不会收到保留消息，表示保留消息已被清除。

在 Dashboard 中查看保留消息 ​当用户发布一条保留消息时，EMQX 将在系统中保存该消息。用户可以在保留消息列表页面中查看此消息。当用户订阅与保留消息的主题匹配的主题时，EMQX 将向该主题发布此消息，用户可以立即通过订阅主题来接收该消息。

保留消息的默认过期时间是永不过期，除非用户手动删除该消息。

保留消息列表 ​在监控 -> 保留消息页面中，用户可以查看系统中的所有保留消息，包括主题、QoS、发布时间和客户端 ID，通过搜索框可以进行搜索过滤，搜索框支持主题通配符。

页面还提供了查看 Payload 和删除这两个操作选项用来查看保留消息 Payload 以及删除保留消息。用户可以使用刷新按钮刷新列表，并使用设置按钮访问保留消息设置页面。

默认可以看到来自系统主题的三条保留消息：

$SYS/brokers/+/sysdescr：当前 EMQX 节点的系统描述$SYS/brokers/+/version：当前 EMQX 节点的版本号$SYS/brokers：当前 EMQX 的节点数量和名称删除保留消息 ​要删除 EMQX 中的保留消息，用户可以在客户端向保留消息的主题发布一个空消息，或在 EMQX Dashboard 中，点击指定保留消息的删除按钮进行删除。用户也可以通过清除全部按钮删除集群上所有保留消息。

此外，用户还可以在保留消息配置页面上设置保留消息的过期时间，使其在过期时自动删除。