MQTT

MQTT 是物联网 (IoT) 的标准消息传输协议。它被设计为一个极轻量级的发布/订阅消息传输机制，非常适合于需要小代码占用和最小网络带宽的远程设备连接。

EMQX 完全兼容 MQTT 5.0 和 3.x，本节将介绍 MQTT 相关功能的基本配置项，包括基本 MQTT 设置、订阅设置、会话设置、强制关闭设置和强制垃圾回收设置等。

基本 MQTT 配置

本节将介绍决定 MQTT 协议行为的配置设置，包括数据包大小、客户端 ID 长度、主题级别、服务质量（QoS）、主题别名和保留等。

TIP

您也可以在 EMQX Dashboard 中找到对应的配置项（管理 -> MQTT 配置 -> 通用）。一旦您通过 Dashboard 配置了这些项，您的设置将覆盖 emqx.conf 中的相同配置项。

示例代码：

mqtt {
  max_packet_size = 1MB
  max_clientid_len = 65535
  max_topic_levels = 128
  max_qos_allowed = 2
  max_topic_alias = 65535
  retain_available = true
}

其中，

配置项	Dashboard UI	描述	默认值	可选值
max_packet_size	最大报文大小	MQTT 报文用于在 MQTT 客户端和 EMQX 之间发送消息。 此设置允许的最大 MQTT 报文大小。	1MB
max_clientid_len	最大客户端 ID 长度	此设置 MQTT 客户端 ID 的最大长度。 它可以帮助防止客户端使用过长的客户端 ID 导致问题。	65535	23 - 65535
max_topic_levels	最大主题层级	MQTT 主题用于组织和分类消息。 此设置允许 MQTT 主题中的最大级别数量。	128	1 - 65535
max_qos_allowed	最大 QoS	QoS 等级决定了消息的可靠性和传递保证等级。 此设置允许 MQTT 消息的最大服务质量（QoS）等级。
max_topic_alias	最大主题别名数	主题别名是通过使用较短的别名代替完整主题名称来减少 MQTT 数据包大小的一种方式。 此设置允许在 MQTT 会话中使用的最大主题别名数量。	65535	1 - 65535
retain_available	启用保留消息	保留消息用于存储发布到主题的最后一条消息，以便新订阅该主题的客户端可以接收到最新的消息。 此设置是否启用 MQTT 中的保留消息功能。	true	true, false

订阅设置

在 EMQX 中，订阅指的是客户端在 EMQX 上订阅主题的过程。当客户端订阅一个主题时，它表示希望接收发布到该主题的消息。

本节介绍如何配置共享订阅、通配符订阅和排它订阅。

TIP

您也可以在 EMQX Dashboard 中找到对应的配置项（管理 -> MQTT 配置 -> 通用）。一旦您通过 Dashboard 配置了这些项，您的设置将覆盖 emqx.conf 中的相同配置项。

示例代码：

mqtt {
	wildcard_subscription = true
  exclusive_subscription = false
  shared_subscription = true
  shared_subscription_strategy  =  round_robin
}

其中，

配置项	Dashboard UI	描述	默认值	可选值
wildcard_subscription	允许通配符订阅	通配符订阅允许 MQTT 客户端使用单个订阅通过通配符如 + 和 # 订阅多个主题。 此设置是否启用通配符订阅。	true	true, false
exclusive_subscription	允许排它订阅	排它订阅允许一次只有一个 MQTT 客户端可以订阅一个主题。 此设置是否启用排它订阅。	true	true, false
shared_subscription	允许共享订阅	共享订阅允许多个 MQTT 客户端共享对主题的订阅。 此设置是否在 MQTT 中启用共享订阅。	true	true, false
shared_subscription_strategy	共享订阅策略	此设置定义了在共享订阅的 MQTT 客户端之间分发消息的策略。 仅当 shared_subscription 设置为 true 时需要。	round_robin	- random (将消息随机分发给选定的订阅者) - round_robin (以轮询方式选择订阅者) - sticky (总是使用最后选定的订阅者进行分发，直到订阅者断开连接。) - hash (根据 clientIds 的哈希选择订阅者)

延迟发布设置

本节介绍如何启用延迟发布以及如何设置允许的最大延迟消息数量。延迟发布功能允许客户端将消息延迟一定时间后发布到主题。这个功能对于需要在特定时间或满足某个条件时发布消息的场景非常有用。

示例代码：

delay {
  delayed_publish_enabled = true
  max_delayed_messages = 0
}

其中，

• delayed_publish_enabled 设置是否在 EMQX 中启用延迟发布功能；默认值：true，可选值：true, false。
• max_delayed_messages 设置允许的最大延迟消息数量；默认值：0。

Keep Alive 设置

Keep Alive 是一种机制，确保即使没有数据传输，MQTT 客户端和 EMQX 之间的连接仍然保持活动。其工作原理如下：当 MQTT 客户端创建到 EMQX 的连接时，可以在连接请求协议包的 Keep Alive 变量头字段中设置非零值。有关 Keep Alive 工作原理的详细信息，请参见 MQTT 协议 Keep Alive 详解。

对于启用了 Keep Alive 的客户端，您可以继续自定义 EMQX 用来确认客户端 Keep Alive 时长是否过期的系数。

keepalive_backoff = 0.75

其中，Keep Alive Backoff（keepalive_backoff）是 EMQX 用来确认客户端 Keep Alive 时长是否过期的系数。默认值：0.75。计算公式如下： $$ Keep Alive * Backoff * 2 $$

会话设置

本节介绍如何配置会话。在 MQTT 中，会话指的是客户端与代理之间的连接。如在 EMQX 中，当客户端连接到 EMQX 时，它建立了一个会话，允许它订阅主题并接收消息，以及向 EMQX 发布消息。

示例代码：

session {
    max_subscriptions = infinity
    upgrade_qos = false
    max_inflight = 32
    retry_interval = 30s
    max_awaiting_rel = 100
    await_rel_timeout = 300s
    session_expiry_interval = 2h
    max_mqueue_len = 1000
    mqueue_priorities = disabled
    mqueue_default_priority = lowest
    mqueue_store_qos0 = true
    
    force_shutdown {
      max_message_queue_len = 1000
      max_heap_size = 32MB
    }

    force_gc {
      count  =  16000
      bytes  =  16MB
    }
  }

其中，

配置项	Dashboard UI	描述	默认值	可选值
max_subscriptions	最大订阅数量	此设置允许客户端拥有的最大订阅数。	infinity	1 - infinity
upgrade_qos	升级 QoS	此设置是否允许客户端在消息发布后升级消息的 QoS (服务质量) 等级。	false (禁用)	true, false
max_inflight	最大飞行窗口	此设置允许同时在途（即已发送但尚未确认）的 QoS 1 和 QoS 2 消息的最大数量。	32	1 - 65535
retry_interval	消息重试间隔	此设置客户端应该以多久的间隔重试发送 QoS 1 或 QoS 2 消息。	30s 单位: 秒	--
max_awaiting_rel	最大待发 PUBREL 数量	此设置每个会话中挂起的 QoS 2 消息数量，直到收到 PUBREL 或超时。达到此限制后，新的 QoS 2 PUBLISH 请求将被拒绝，并返回错误码 147(0x93)。 在 MQTT 中，PUBREL 是 QoS 2 消息流中用于确保消息交付的控制包。	100	1 - infinity
await_rel_timeout	最大 PUBREL 等待时长	此设置等待接收到 QoS 2 消息的 PUBREL 的时间。达到此限制后，EMQX 将释放包 ID 并生成警告级别日志。 注意：无论是否收到 PUBREL，EMQX 都会转发收到的 QoS 2 消息。	300s 单位: 秒	--
session_expiry_interval	会话过期间隔	此设置会话可以空闲多久之后自动关闭。注意：仅对非 MQTT 5.0 客户端有效。	2 单位：小时
max_mqueue_len	最大消息队列长度	此设置当持久客户端断开连接或在途窗口已满时允许的最大队列长度。	1000	0 - infinity
mqueue_priorities	主题优先级	此设置主题优先级，此处的配置将覆盖 mqueue_default_priority 定义的优先级。	disabled 会话使用 mqueue_default_priority 设置的优先级。	disabled 或 1 - 255
mqueue_default_priority	默认主题优先级	此设置默认主题优先级。	lowest	highest， lowest
mqueue_store_qos0	存储 QoS 0 消息	此设置在连接断开但会话保持时是否存储 QoS 0 消息在消息队列中。	true	true, false
force_shutdown	--	此设置是否启用强制关闭功能，如果队列长度（max_message_queue_le）或堆大小（max_heap_size）达到指定值。	true	true, false
force_shutdown.max_message_queue_le	--	此设置触发强制关闭的最大队列长度。	1000	1 - infinity
force_shutdown.max_heap_size	--	此设置触发强制关闭的最大堆大小。	32 MB	--
force_gc	--	此设置是否启用强制垃圾回收，如果达到指定的消息数量（count）或接收字节（bytes）：	true	true, false
force_gc.count	--	此设置将触发强制垃圾回收的接收消息数量。	16000	0 - infinity
force_gc.bytes	--	此设置将触发强制垃圾回收的接收字节数量。	16 MB 单位: MB	--

TIP

要通过 Dashboard 配置 MQTT，请点击 Dashboard 左侧导航菜单的 管理 -> MQTT 配置。一旦您通过 Dashboard 配置了这些项，您的设置将覆盖 emqx.conf 中的相同配置项。

EMQX 提供了更多配置项以更好地满足定制化需求。详细信息请参见配置手册。