- 后端
- 物联网
- 消息队列
- 通信
【免费下载链接】emqx
The most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles
版本发布信息：EMQX 5.10.0 发布于 2025-06-10，本文基于当前开源仓库 changes/e5.10.0.en.md 及对应源码，逐项解读该版本在核心 MQTT 功能、规则引擎、数据集成、多租户、网关与可观测性方面的增强、缺陷修复与破坏性变更。升级到该版本前，请务必先阅读文末的 Breaking Changes 部分，确认存量配置与集群行为是否受影响。
一、升级前必读：本版本的关键变化总览
5.10.0 是一次功能密集的版本迭代，核心看点包括：
- MQTT 层：新增
mqtt.subscription_max_qos_rules配置，可针对订阅 Topic 精细化限制单条订阅的 QoS 上限；middlebox_comp_mode从"始终开启"改为可配置。 - 规则引擎：事件 Topic 全面引入命名空间（旧名称保留兼容）、支持通配符匹配多事件、新增
ai_completionSQL 函数。 - 数据集成：新增 Apache Doris、S3Tables 两种数据目标，Kafka 连接器支持 Amazon MSK IAM 认证，Snowflake 连接器支持私钥文件认证。
- 运维与多租户：新增
emqx ctl conf remove x.y.z命令、批量删除命名空间 API、Helm Chart 自定义注解。 - 破坏性变更：所有连接器/动作/数据源新增
resource_opts.health_check_timeout（默认 60 秒），broker.routing.storage_schema被弃用并忽略。
以下按功能域逐一深入。
二、核心 MQTT 功能增强
2.1middlebox_comp_mode变为可配置项
在 5.10.0 之前，middlebox_comp_mode对所有 TLS 1.3 连接始终为true（启用）。该选项用于兼容中间盒（middlebox）对 TLS 1.3 握手消息的干扰——某些老旧防火墙/负载均衡设备无法正确处理 TLS 1.3 的 HelloRetryRequest 相关行为。5.10.0 将其改为可配置，默认值保持true以兼容大多数网络环境。
典型故障场景：当 TLS 握手失败并出现类似错误时：
unexpected_message, TLS client: In state hello_retry_middlebox_assert ...可尝试将middlebox_comp_mode设为false解决。
从源码看，该配置项定义在 apps/emqx/src/emqx_schema.erl 的client_ssl_opts_schema/1中（sc(boolean(), #{required => false, default => true, ...})），并作为 SSL 客户端选项在 apps/emqx/src/emqx_tls_lib.erl 的传输选项组装中通过{middlebox_comp_mode, fun conf_get_opt/2, #{omit_if => true}}传递。omit_if => true意味着当配置为默认值时可省略传递，避免对 OTP SSL 行为产生不必要的影响。
配置示例（以监听器 SSL 客户端选项为例）：
listeners.ssl.default { ssl_options { enable = true middlebox_comp_mode = false # ... 其余 TLS 配置 } }适用提示：仅在确认网络链路上存在中间盒兼容性问题、且出现上述hello_retry_middlebox_assert类报错时再关闭该选项；生产环境默认保持true即可。
2.2 订阅级 QoS 上限规则：mqtt.subscription_max_qos_rules
这是本版本在 MQTT 协议层最重要的新配置。它允许管理员根据 SUBSCRIBE 包中的 Topic 匹配规则，限制单条订阅允许请求的最大 QoS 等级，从而在共享同一 Broker 的混合负载场景下实现精细的 QoS 治理。
配置结构：mqtt.subscription_max_qos_rules是一个topic_qos_rule数组，每个规则由两个字段构成（定义见 apps/emqx/src/emqx_schema.erl 的fields("topic_qos_rule")）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
topic | topic predicate | 是 | 匹配谓词，仅支持matches（Topic 过滤器通配匹配）与equals（精确相等）两种 |
qos | 0 | 1 | 2 | 是 | 该规则允许的最大 QoS 上限 |
mqtt { subscription_max_qos_rules = [ { topic = { matches = "sensors/+/temperature" }, qos = 1 } { topic = { equals = "critical/alerts" }, qos = 2 } { topic = { matches = "logs/#" }, qos = 0 } ] }执行逻辑（对应 apps/emqx/src/emqx_mqtt_caps.erl）：
- 客户端发起 SUBSCRIBE 时，
check_sub/3从 Zone 配置中取出subscription_max_qos_rules与max_qos_allowed。 - 对每条规则按顺序求值：
eval_topic_qos_rule/2先对订阅的"真实 Topic"（已剥离$share/...前缀，见emqx_topic:get_shared_real_topic/1）执行谓词匹配，命中则返回该规则的 QoS 上限。 - 多条规则按数组顺序取第一个命中的结果；若全部未命中，则回退到全局
max_qos_allowed（emqx_maybe:define(eval_max_qos_allowed(Rules, Topic), FallbackMaxQoS)）。 - 若客户端请求的 QoS 高于计算出的上限，订阅仍被接受，但授予的 QoS 被降级（返回
{ok, MaxQoS}，即 MQTT 的GRANTED_QOS_*语义），而不是直接拒绝。
两个值得注意的实现细节：
- 谓词
matches在 SUBSCRIBE 语境下比较的双方都是 Topic Filter，直接使用emqx_topic:match/2可能产生令人困惑的结果（例如emqx_topic:match(<<"t/#">>, <<"t/+">>) = true），源码注释中对此有专门说明。设计时请仔细确认通配符组合的语义。 subscription_max_qos_rules的importance被标记为?IMPORTANCE_HIDDEN（见 emqx_schema.erl），属于进阶隐藏配置，测试覆盖见 apps/emqx/test/emqx_mqtt_caps_SUITE.erl。
2.3 WebSocket 连接性能与资源优化
根据官方合成基准（1 对 1 MQTT 消息性能测试）的说明，5.10.0 对 WebSocket 连接做了性能优化：
- CPU 占用降低约 20%，内存占用略有下降；
- 当启用了监听器级连接数限制（listener-wide connection limit）时，连接建立效率提升，尤其对单节点承载大量连接的场景改善明显。
该优化对使用 WebSocket/WebSocket TLS 端口接入的浏览器端、移动端 MQTT 客户端密集场景收益最直接，建议升级后通过监控对比 CPU 与内存曲线验证效果。
三、部署：Helm Chart 支持 StatefulSet 自定义注解
在 Kubernetes 上部署 EMQX 时，运维上常见的诉求是"当 ConfigMap 或 Secret 变更时自动滚动重启 Pod"。5.10.0 为 Helm Chart 中的 EMQX StatefulSet 增加了自定义注解支持（对应 PR #14791），可在 Chart 中通过annotations字段声明注解，配合诸如checksum/config之类的模板表达式实现配置变更自动触发 Pod 重启，提升自动化程度与部署可靠性。
# values.yaml 示例 statefulSet: annotations: checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}具体字段名请以 deploy/charts 目录下当前 Chart 模板为准。
四、访问控制：LDAP 认证与授权的三处改进
5.10.0 集中修复并增强了 LDAP 认证/授权（对应 PR #15250、#15249）：
- 正确提取
is_superuser标记：此前无论 LDAP 条目中是否包含有效的isSuperuser属性，is_superuser始终被置为false；现在 LDAP bind 认证会从条目属性中正确读取该标志。 - 增加
filter/base_dn配置校验：对 LDAP 认证与授权配置中的过滤器与基础 DN 增加了合法性校验，配置错误会在加载阶段尽早暴露。 - 修复变量插值（variable interpolation）问题：此前部分场景下模板变量无法正确展开，导致查询行为异常。
涉及模块为 apps/emqx_auth_ldap，相关实现位于src目录下。
五、规则引擎：AI 函数、事件命名空间与通配符匹配
5.1 新增ai_completionSQL 函数与base_url选项
规则引擎 SQL 新增ai_completion函数，可在规则处理数据流中调用 AI 服务对消息数据（如文本内容）进行智能处理（对应 PR #15001、#15201）。AI Completion Provider 配置中新增base_url选项，用于指定自定义 AI 服务端点地址，适配自建模型网关或不同服务商的 API 地址。
相关代码位于 apps/emqx_ai_completion 应用（12 个 Erlang 源文件），SQL 侧函数注册与 Provider 配置管理均可在此目录中找到实现。典型用法示例：
SELECT ai_completion(payload, 'provider_name') AS ai_result, topic, payload FROM "t/#"其中provider_name对应在 Dashboard / 配置中创建的 AI Completion Provider 名称。
5.2 规则事件 Topic 引入命名空间
这是规则引擎的一项潜在破坏性变更（虽然做了向后兼容）：规则事件 Topic 从扁平命名改为带命名空间的分层结构。完整映射如下：
| 原事件 Topic | 新事件 Topic |
|---|---|
$events/client_connected | $events/client/connected |
$events/client_disconnected | $events/client/disconnected |
$events/client_connack | $events/client/connack |
$events/client_check_authz_complete | $events/auth/check_authz_complete |
$events/client_check_authn_complete | $events/auth/check_authn_complete |
$events/session_subscribed | $events/session/subscribed |
$events/session_unsubscribed | $events/session/unsubscribed |
$events/message_delivered | $events/message/delivered |
$events/message_acked | $events/message/acked |
$events/message_dropped | $events/message/dropped |
$events/delivery_dropped | $events/message/delivery_dropped |
$events/message_transformation_failed | $events/message_transformation/failed |
$events/schema_validation_failed | $events/schema_validation/failed |
重要说明：
- 旧事件 Topic全部保留用于向后兼容，存量规则不会中断；
- 建议新规则统一使用新命名空间，并在合适的时机将旧规则迁移到新 Topic。
5.3 事件 Topic 通配符匹配
配合命名空间化，规则引擎现在支持在事件 Topic 中使用通配符一次匹配多个事件（对应 PR #15175），例如：
$events/#：匹配所有事件；$events/sys/+：匹配sys命名空间下的单层事件；$events/message/+：匹配message命名空间下的所有消息事件。
这大大简化了"对同一类事件做统一处理"的场景（例如统一埋点、统一监控），不再需要为每个事件分别创建规则。
六、Smart Data Hub：Schema Registry 支持上传 Protobuf 源码包
5.10.0 为 Schema Registry 增加了上传 Protobuf 源码文件 bundle的能力（对应 PR #15174），解决多文件 Protobuf 依赖的注册难题。
示例场景：假设 Protobuf 源码包位于/tmp/bundle.tar.gz，文件结构如下，其中a.proto为根 Schema 文件：
. ├── a.proto ├── c.proto └── nested └── b.proto通过 HTTP API 创建新 Schema：
curl -v http://127.0.0.1:18083/api/v5/schema_registry_protobuf/bundle \ -XPOST \ -H "Authorization: Bearer xxxx" \ -F bundle=@/tmp/bundle.tar.gz \ -F name=my_cool_schema \ -F root_proto_file=a.proto参数说明：
| 参数 | 说明 |
|---|---|
bundle | 上传的.tar.gz源码包文件（multipart 表单） |
name | 新 Schema 的名称 |
root_proto_file | 根 Protobuf 文件在包内的相对路径（如a.proto） |
其余相关修复还包括：External HTTP Schema 请求增加content-type头（#15285）；通过 Dashboard 更新 External Schema Registry 时不再将密码误改为******（#15224）；消息转换（Message Transformation）支持设置硬编码的 QoS 与 Topic（#15190）。
七、数据集成：Doris、S3Tables、Kafka IAM 与 Snowflake 私钥
7.1 新增 Apache Doris 数据集成
EMQX 5.10.0 正式支持与 Apache Doris 的数据集成，通过 SQL 语句写入数据（对应 PR #15248）。从实现看，Doris 连接器复用了 MySQL 连接器协议栈（见 apps/emqx_bridge_doris/src/emqx_bridge_doris_impl.erl），并在连接建立后执行SET enable_nereids_planner = true与SET enable_fallback_to_original_planner = false以启用新优化器；SQL 模板编译由独立的 emqx_doris_sql.erl 模块负责，动作参数结构定义在 emqx_bridge_doris_action_schema.erl。可在 Dashboard 的"数据集成 → 数据桥接"中创建 Doris 连接器与动作。
7.2 新增 S3Tables 数据集成
EMQX 支持将消息写入 AWS S3 Tables（对应 PR #14983）。该功能基于 Iceberg 表格式构建，当前版本存在明确的能力边界：
- 仅支持 S3Tables catalog（表数据与元数据必须存放于 S3）；
- 仅支持 Iceberg 表格式Version 2（行级删除）；
- 仅支持以下分区转换函数：
identity、void、bucket[N]； - 数据文件仅以Avro格式写入。
在规划 S3Tables 数据桥接前，务必确认目标表格式、分区方式与上述限制匹配。相关源码与测试位于 apps/emqx_bridge_s3tables（含priv目录下的.avsc文件与测试资源）。
7.3 Kafka 连接器支持 Amazon MSK IAM 认证
Kafka Producer/Consumer 连接器新增对 Amazon MSK（Managed Streaming for Apache Kafka）的 IAM 认证支持（对应 PR #15218）：当 EMQX 运行在 AWS EC2 上时，通过 AWS SDK 为 Kafka 客户端生成 OAuth Bearer Token 完成认证，从而无需在 EMQX 侧静态配置 Access Key/Secret，进一步提升安全性。
7.4 Snowflake 连接器支持私钥文件认证
Snowflake 连接器新增私钥文件路径认证方式（对应 PR #15157）。三种认证方式三选一：
- 使用密码（password）；
- 使用私钥文件路径（private key file path）；
- 都不设置，改为在
/etc/odbc.ini中配置参数。
7.5 InfluxDB 行协议时间戳修复
修复了 InfluxDB 动作中行协议转换失败的问题（对应 PR #15331）：当WriteSyntax中timestamp留空且规则中无时间戳字段时，现在使用系统当前毫秒值，并强制毫秒精度。
7.6 连接器健康检查与重连行为修复
- Postgres / Matrix / TimescaleDB：任何健康检查失败都将触发完全重连（#15274），避免连接进入不可用但仍被使用导致挂起乃至内存溢出。
- ClickHouse：健康检查超时时减少日志量，并将状态标记为
connecting而非disconnected，避免因超时频繁触发全量重连（#15219）。 - 修复聚合模式动作（S3、Azure Blob Storage、Snowflake）中罕见的竞态条件导致的
emqx_connector_aggregator:handle_close_buffer崩溃日志（#15154）。 - 修复连接器健康检查响应总是触发所有依赖动作/源健康检查的问题（#15306）。
- 修复部分动作在规则模拟测试时（用模拟数据测试）不发出 trace 事件的问题（#15147），受影响动作包括 Couchbase、Snowflake、IoTDB（Thrift 驱动）；并新增"动作未安装"与"Republish Fallback"动作的 trace 事件（#15234）。
八、多租户：新增三个管理 API
5.10.0 为多租户（Multi-Tenancy）管理补充了三个 HTTP API：
| API | 说明 |
|---|---|
GET /mt/ns_list_details | 与既有 ns_list 类似，但额外返回命名空间关联的元数据 |
GET /mt/ns_list_managed_details | 与上述类似，面向受管命名空间 |
DELETE /mt/bulk_delete_ns | 批量删除命名空间 |
同时修复了节点重启后配置了多租户限流器（limiter）时可能出现的limiter_group_not_found异常日志问题（#15242）。多租户模块实现位于 apps/emqx_mt。
九、CLI：新增emqx ctl conf remove命令
新增命令emqx ctl conf remove x.y.z（对应 PR #15158），用于从现有配置中移除指定配置键路径。例如：
emqx ctl conf remove dashboard.sso.github该命令与既有的emqx ctl conf show、emqx ctl conf set等形成完整的配置管理闭环。同时修复了执行emqx ctl conf remove dashboard.sso.<BACKEND_NAME>时输出function_clause错误日志的问题（#15247）。
十、网关：新增 NATS Gateway
5.10.0 引入NATS Gateway（对应 PR #15138），可接收 NATS 客户端通过 TCP/TLS、WS/WSS 传输协议的连接，并将其消息桥接进 EMQX 的 MQTT 生态。
消息转换示例：NATS 客户端发送：
PUB sub.t 5 hello将被转换为 Topic 为sub/t、Payload 为hello的 MQTT 消息，从而无缝复用规则引擎、数据集成等 EMQX 既有能力。注意 NATS 的 Topic 分隔符.与 MQTT 的/之间的映射约定。相关实现位于 apps/emqx_gateway_nats。
十一、Durable Storage：DS Raft 后端基础指标
为 Durable Storage 的 Raft 后端（DS Raft backend）增加了基础指标（对应 PR #15043），提供集群状态、数据库概览、分片复制与副本切换等维度的可观测性数据，便于排查 DS 集群健康与复制进度。实现位于 apps/emqx_ds_builtin_raft。
十二、其他值得关注的缺陷修复
- 访问控制：修复创建封禁列表记录失败时错误消息格式不正确的问题（#15184）。
- 集群：修复
static发现策略下 replicant 节点可能忽略未显式列入static_seeds的核心节点的问题（#15304），此前可能导致集群视图不一致与负载不均；修复ekka_locker未正确处理 RPC（badrpc）错误导致误报锁成功、进而引发锁状态不一致与死锁的问题（#15180）。 - 安全：改进 CRL 分发点（CDP）处理——若某个 CDP URL 持续刷新失败（默认超时 60 秒），将其驱逐出刷新列表，避免反复输出错误日志（#15159）。
- 可观测性：修复导出 OpenTelemetry 指标时的
badarg错误（#15299）。 - 遥测：修复存在已激活插件时
emqx_telemetry进程崩溃的问题（#15216）。
十三、Breaking Changes：升级前必读
以下四项变更可能影响现有部署行为，升级到 5.10.0 前请逐一核对：
13.1 所有连接器/动作/源新增resource_opts.health_check_timeout（默认 60 秒）
所有 Connectors、Actions、Sources 新增resource_opts.health_check_timeout配置，默认值 60 秒。健康检查超过该时长未返回响应时，Connector/Action/Source 将被判定为disconnected。
注意：由于默认值为 60 秒，若此前某组件的健康检查响应时间可能超过 60 秒，升级后它将被判定为断开。如存在此类慢健康检查组件，请显式调大该超时时间：
bridges.kafka.my_kafka { resource_opts { health_check_timeout = 120s } }13.2broker.routing.storage_schema弃用并忽略
配置项broker.routing.storage_schema现已弃用并被忽略。Legacyv1路由存储 schema 不再受支持；若集群中仍运行使用 v1 schema 的旧版本节点，EMQX 将拒绝启动。升级前请确认集群内所有节点版本一致且已迁移到新版路由存储 schema。
13.3multi_tenancy.default_max_sessions类型收紧
multi_tenancy.default_max_sessions的类型现为infinity或正整数，此前可接受的0将不再合法。若配置中使用了0，请改为infinity或具体正整数。
13.4dashboard.sso.oidc.issuer增加 URL 校验
dashboard.sso.oidc.issuer字段新增 Schema 校验，值必须为合法 URL。存量配置中若存在非 URL 形式的 issuer 值，升级后加载配置时将报错。
十四、总结
EMQX 5.10.0 在协议治理（订阅级 QoS 规则、TLS 中间盒兼容开关）、规则引擎（AI 函数、事件命名空间与通配符）、数据集成（Doris、S3Tables、MSK IAM、Snowflake 私钥）以及多租户/运维 API 上均有实质性进展。建议升级顺序：先在小规模测试集群验证 Breaking Changes 中列出的四类行为变化（尤其健康检查超时与路由存储 schema），再灰度到生产；规则引擎用户可利用事件命名空间与通配符能力简化规则治理，同时逐步将存量规则迁移到新事件 Topic。
进一步阅读：本文所有功能对应的配置定义可查阅 apps/emqx/src/emqx_schema.erl，MQTT 订阅 QoS 规则判定逻辑见 apps/emqx/src/emqx_mqtt_caps.erl，Doris 集成实现见 apps/emqx_bridge_doris/src/emqx_bridge_doris_impl.erl，S3Tables 相关代码与测试见 apps/emqx_bridge_s3tables，NATS 网关见 apps/emqx_gateway_nats。
- 后端
- 物联网
- 消息队列
- 通信
【免费下载链接】emqx
The most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles
相关推荐
EMQX 规则引擎命名空间隔离配置 `rule_engine.limit_selects_in_namespace` 深度解析
EMQX 规则引擎命名空间隔离配置 rule_engine.limit_selects_in_namespace 深度解析 导读 在 EMQX 的多租户（nam
后端物联网消息队列通信EMQX 与 TDengine 集成指南：通过 EMQX 规则引擎将 MQTT 数据零代码写入 TDengine
EMQX 与 TDengine 集成指南：通过 EMQX 规则引擎将 MQTT 数据零代码写入 TDengine 本篇技术指南讲解如何在 EMQX 开源 MQT
数据库时序数据库大数据物联网云原生使用 EMQX 规则引擎新事件 `$events/client/ping` 监控 MQTT 客户端心跳（PINGREQ）
使用 EMQX 规则引擎新事件 $events/client/ping 监控 MQTT 客户端心跳（PINGREQ） 本文依据 changes/ee/feat
后端物联网消息队列通信
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
