EMQX 5.10.0 版本技术详解：MQTT 订阅 QoS 规则、规则引擎事件命名空间与数据集成新能力

后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载版本发布信息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)字段类型必填说明topictopic predicate是匹配谓词仅支持matchesTopic 过滤器通配匹配与equals精确相等两种qos0 | 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_allowedemqx_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 HubSchema 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 创建新 Schemacurl -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 namemy_cool_schema \ -F root_proto_filea.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 MSKManaged 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、IoTDBThrift 驱动并新增动作未安装与Republish Fallback动作的 trace 事件#15234。八、多租户新增三个管理 API5.10.0 为多租户Multi-Tenancy管理补充了三个 HTTP APIAPI说明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 Gateway5.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 StorageDS Raft 后端基础指标为 Durable Storage 的 Raft 后端DS Raft backend增加了基础指标对应 PR #15043提供集群状态、数据库概览、分片复制与副本切换等维度的可观测性数据便于排查 DS 集群健康与复制进度。实现位于 apps/emqx_ds_builtin_raft。十二、其他值得关注的缺陷修复访问控制修复创建封禁列表记录失败时错误消息格式不正确的问题#15184。集群修复static发现策略下 replicant 节点可能忽略未显式列入static_seeds的核心节点的问题#15304此前可能导致集群视图不一致与负载不均修复ekka_locker未正确处理 RPCbadrpc错误导致误报锁成功、进而引发锁状态不一致与死锁的问题#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.erlMQTT 订阅 QoS 规则判定逻辑见 apps/emqx/src/emqx_mqtt_caps.erlDoris 集成实现见 apps/emqx_bridge_doris/src/emqx_bridge_doris_impl.erlS3Tables 相关代码与测试见 apps/emqx_bridge_s3tablesNATS 网关见 apps/emqx_gateway_nats。赞分享后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载相关推荐EMQX 规则引擎命名空间隔离配置 rule_engine.limit_selects_in_namespace 深度解析EMQX 规则引擎命名空间隔离配置 rule_engine.limit_selects_in_namespace 深度解析 导读 在 EMQX 的多租户nam后端物联网消息队列通信EMQX 与 TDengine 集成指南通过 EMQX 规则引擎将 MQTT 数据零代码写入 TDengineEMQX 与 TDengine 集成指南通过 EMQX 规则引擎将 MQTT 数据零代码写入 TDengine 本篇技术指南讲解如何在 EMQX 开源 MQT数据库时序数据库大数据物联网云原生使用 EMQX 规则引擎新事件 $events/client/ping 监控 MQTT 客户端心跳PINGREQ使用 EMQX 规则引擎新事件 $events/client/ping 监控 MQTT 客户端心跳PINGREQ 本文依据 changes/ee/feat后端物联网消息队列通信创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考