EMQX Azure Event Hub 数据集成桥接:基于 Kafka 协议的 Producer 实现与配置指南

原创2026-09-20 19:03:331,674 阅读
文章标签:物联网IoT协议消息队列后端消息路由数据集成认证鉴权可观测性云原生

EMQX Azure Event Hub 数据集成桥接:基于 Kafka 协议的 Producer 实现与配置指南

导读

本文围绕 EMQX 仓库中 apps/emqx_bridge_azure_event_hub 应用,深入讲解 Azure Event Hub(AEH)数据集成桥接的实现原理与完整配置方法。该桥接以 Kafka 协议作为载体,将 EMQX 规则引擎产出的消息发布到 Azure Event Hub,并复用 wolff 库自带的 replayq 缓冲机制完成高吞吐、可落盘的缓冲保障。读完本文,你将掌握 AEH 桥接的架构设计(为何无需 emqx_resource 缓冲 worker)、Connector 与 Action 两级配置模型、每个关键参数的默认值与取值约束,以及源码与测试对这套行为的验证方式。

一、桥接定位:用 Kafka 协议对接 Azure Event Hub

Azure Event Hub 对外提供 Kafka 协议兼容接口(azure-event-hubs-kafka-overview 官方文档),这使得任何实现了 Kafka Producer 协议的客户端都可以向 Event Hub 命名空间发布消息。EMQX 的 emqx_bridge_azure_event_hub 应用正是基于这一事实构建的:

  • 它属于 EMQX 数据集成(Data Integration)桥接中的一种 Producer 型桥接,类型名为 azure_event_hub_producer;
  • 它复用 Kafka 桥接的底层实现(emqx_bridge_kafka 的 schema 与 emqx_bridge_kafka_impl_producer 资源回调模块),只在其上叠加 AEH 特有的约束;
  • 消息发布通道走 Kafka 协议,因此 Event Hub 侧无需任何额外插件,只需开放 9093 端口(SASL/SSL)。

从应用描述文件(mix.exs)可以看到,该应用直接依赖 wolff、kafka_protocol、brod、brod_gssapi、snappyer 等 Kafka 生态库,并且注册了两个信息模块:

提示:文章中的概念同样适用于 EMQX Enterprise 的数据集成场景,但所有配置字段与默认值均以当前仓库源码为准。

二、架构要点:自带 replayq 缓冲,不依赖 emqx_resource 缓冲 worker

原文档特别强调了两点架构事实,这是理解 AEH 桥接与普通 Kafka 桥接差异的关键:

  1. wolff 库自带 replayq 缓冲实现。wolff 是 EMQX 团队维护的 Kafka Producer 客户端库,其内部通过 replayq 维护按分区组织的发送队列。当 Kafka 服务端不可用时,消息可以留在 replayq 中等待重发;
  2. 因此该桥接不需要 emqx_resource 的 buffer worker。在 EMQX 数据集成框架中,普通桥接通常由 emqx_resource 提供缓冲、限流等通用能力;而 AEH 桥接因为缓冲职责已被 wolff/replayq 接管,故跳过这部分通用缓冲机制。

此外,原文档指出该桥接无需单独的 connector 应用。原因是它不被认证/授权(authentication and authorization)相关功能使用,连接管理直接内嵌于桥接应用自身(通过 emqx_bridge_azure_event_hub_connector_info 与 emqx_bridge_azure_event_hub 模块完成 schema 与配置转换)。

从源码看,配置入口 emqx_bridge_azure_event_hub.erl 实现了 hocon_schema 与 emqx_connector_resource 两个 behaviour,并在 connector_config/2 中完成 bootstrap hosts 的解析:

connector_config(Config, _) ->
    %% Default port for AEH is 9093
    BootstrapHosts0 = maps:get(bootstrap_hosts, Config),
    BootstrapHosts = emqx_schema:parse_servers(
        BootstrapHosts0,
        emqx_bridge_azure_event_hub:host_opts()
    ),
    Config#{bootstrap_hosts := BootstrapHosts}.

其中 host_opts() 返回 #{default_port => 9093},即配置中若省略端口,默认使用 9093(Azure Event Hub 的 Kafka 端点标准端口)。

三、连接(Connector)配置:必填项、默认值与校验规则

AEH 桥接采用 EMQX 5.x/6.x 的 Connector + Action 两级模型:先创建 Connector 负责与 Event Hub 建立连接,再创建 Action 定义消息映射与发布行为。

以下配置示例取自源码中的 API 示例(values(common_config),见 emqx_bridge_azure_event_hub.erl):

{
  "name": "my_azure_event_hub_producer_connector",
  "type": "azure_event_hub_producer",
  "enable": true,
  "authentication": {
    "username": "$ConnectionString",
    "password": "******"
  },
  "bootstrap_hosts": "namespace.servicebus.windows.net:9093",
  "connect_timeout": "5s",
  "metadata_request_timeout": "4s",
  "min_metadata_refresh_interval": "3s",
  "socket_opts": {
    "sndbuf": "1024KB",
    "recbuf": "1024KB",
    "nodelay": true,
    "tcp_keepalive": "none"
  },
  "ssl": {
    "enable": true,
    "server_name_indication": "auto",
    "verify": "verify_none",
    "versions": ["tlsv1.3", "tlsv1.2"]
  }
}

3.1 必填项

  • bootstrap_hosts:Event Hub 命名空间主机列表,格式为 主机:端口,默认端口 9093。格式校验由 emqx_schema:servers_validator(host_opts(), true) 保证;
  • authentication:必填,但结构固定(见下文);
  • ssl:必填,默认 {"enable": true} —— 这是与普通 Kafka 桥接最显著的差异。

3.2 认证:固定为 PLAIN + $ConnectionString

auth_overrides() 对认证字段做了强约束(源码 emqx_bridge_azure_event_hub.erl):

  • mechanism:固定为 plain,不可配置(importance => ?IMPORTANCE_HIDDEN),测试用例明确拒绝 scram_sha_256 与 scram_sha_512;
  • username:固定为 $ConnectionString(隐藏字段);
  • password:填入 Event Hub 命名空间的 SAS 连接字符串(Endpoint=... 形式)。

即认证方式被锁定为 Kafka 的 PLAIN 机制,用户名恒为 $ConnectionString,密码即连接字符串本身。

3.3 SSL:强制启用,SNI 自动解析

ssl_overrides()(源码 emqx_bridge_azure_event_hub.erl)说明:

  • enable 被强制为 true(mk(true, #{default => true})),测试用例验证配置 "enable": false 会直接校验失败;
  • server_name_indication 支持 auto、disable 或自定义字符串;当为 auto 时,server_name_indication_converter/2 会将其转换为 servicebus.windows.net——这是 Event Hub 证书的通用 SNI(命名空间主机名并不直接作为 SNI 使用)。

3.4 其它连接参数

  • connect_timeout:建立 TCP 连接超时,默认 5s;
  • metadata_request_timeout:元数据请求超时,默认 4s;
  • min_metadata_refresh_interval:元数据最小刷新间隔,默认 3s;
  • socket_opts:TCP socket 选项(sndbuf/recbuf/nodelay/tcp_keepalive 等);
  • request_timeout:由测试确认默认 30s(见 emqx_bridge_azure_event_hub_tests.erl)。

3.5 连接状态视图

GET 请求返回的 Connector 信息还会携带运行态字段:status(如 connected)、node_status(按节点显示连接状态)以及引用它的 actions 列表,便于在 Dashboard/API 中排查连接健康度。

四、Action(Producer)配置:消息映射与发布行为

Action 类型同样为 azure_event_hub_producer,其 schema 基于 Kafka Producer 的 producer_kafka_opts 派生(producer_overrides()),并叠加 AEH 特有约束。完整示例(来自源码 values(producer)):

{
  "enable": true,
  "connector": "my_azure_event_hub_producer_connector",
  "name": "my_azure_event_hub_producer_action",
  "type": "azure_event_hub_producer",
  "parameters": {
    "topic": "topic",
    "message": {
      "key": "${.clientid}",
      "value": "${.}"
    },
    "max_linger_time": "5ms",
    "max_linger_bytes": "10MB",
    "max_batch_bytes": "896KB",
    "partition_strategy": "random",
    "required_acks": "all_isr",
    "partition_count_refresh_interval": "60s",
    "kafka_headers": "${.pub_props}",
    "kafka_ext_headers": [
      {"kafka_ext_header_key": "clientid", "kafka_ext_header_value": "${clientid}"},
      {"kafka_ext_header_key": "topic", "kafka_ext_header_value": "${topic}"}
    ],
    "kafka_header_value_encode_mode": "none",
    "max_inflight": 10,
    "buffer": {
      "mode": "hybrid",
      "per_partition_limit": "2GB",
      "segment_bytes": "100MB",
      "memory_overload_protection": true
    }
  }
}

4.1 消息映射(message)

  • key:默认 ${.clientid},支持 EMQX 规则引擎模板语法;
  • value:默认 ${.},即整个消息上下文;
  • 注意:AEH 桥接的 kafka_message schema 删除了 timestamp 字段(源码 fields(kafka_message) 中 proplists:delete(timestamp, Fields0)),因为 Event Hub 的消息时间戳由服务端/系统管理,不需要客户端模板注入。

4.2 发布参数(producer_kafka_opts)

下表汇总了各参数及其默认值与约束(字段定义源自 emqx_bridge_kafka.erl,AEH 覆盖见 emqx_bridge_azure_event_hub.erl):

参数 默认值 取值/说明
topic 必填 目标 Event Hub(Kafka topic),支持模板语法
message.key / message.value ${.clientid} / ${.} 消息键值模板
max_linger_time 0ms 单批消息最大等待时间
max_linger_bytes 10MB 触发发送的累积字节阈值
max_batch_bytes 896KB 单个 Kafka 请求批次上限
compression no_compression 固定为 no_compression(隐藏字段),测试验证 snappy/gzip 均被拒绝
partition_strategy random random / key_dispatch
required_acks all_isr AEH 仅允许 all_isr / leader_only,不支持 none
kafka_headers / kafka_ext_headers — 头信息模板,支持 ${.pub_props} 等
kafka_header_value_encode_mode none none / json
partition_count_refresh_interval 60s 分区数刷新间隔
partitions_limit all_partitions 或正整数
max_inflight 10 单个分区在途请求数上限
max_batch_age infinity 或毫秒时长,如 500ms(测试验证可设置)
max_retries infinity 或非负整数,如 3(测试验证可设置)
reconnect_delay 2s 断线重连延迟(测试验证可设置)
query_mode async async / sync;sync_query_timeout 默认 5s
buffer — mode: memory/disk/hybrid(默认 memory);per_partition_limit 默认 256MB;segment_bytes 默认 10MB;memory_overload_protection 默认 true

4.3 与普通 Kafka 桥接的差异要点

  • 压缩固定关闭:compression 被 kafka_producer_overrides() 强制为 no_compression,避免与 Event Hub 端能力产生歧义;
  • acks 收紧:不允许 none,保证至少 Leader 确认;
  • 必须走 SSL:AEH 要求 TLS 连接,ssl.enable 不可关闭;
  • 无 timestamp 模板:消息时间戳由系统决定。

五、配置变更兼容性:kafka 字段名与 parameters 字段名

源码中有一段重要注释(producer_overrides()):

NOTE: field 'kafka' is renamed to 'parameters' since e5.3.1. We will keep 'kafka' for backward compatibility.

即早期版本使用 kafka 字段承载 producer 参数,自 e5.3.1 起改名为 parameters,当前版本两者兼容(schema 中同时保留 kafka 与 parameters 两个入口,并挂同一组 producer_kafka_opts 校验)。新配置一律推荐使用 parameters。

六、Schema 与 API 层:如何注册到 EMQX 数据集成框架

  • namespace() 返回 "bridge_azure_event_hub",roots() 返回 ["config_producer"],即 HOCON 配置树的命名空间入口;
  • 针对 REST API 的 GET/PUT/POST 方法,分别生成 get_connector、put_connector、post_connector、get_bridge_v2、put_bridge_v2、post_bridge_v2 等 schema 分支,统一由 emqx_connector_schema / emqx_bridge_v2_schema 路由;
  • bridge_v2_examples/1 与 connector_examples/1 提供 API 文档与 Dashboard 表单所需的示例配置(即本文第三节、第四节引用的配置)。

通过 emqx_bridge_azure_event_hub_connector_info.erl 可知,connector 的 type_name() 为 azure_event_hub_producer,bridge_types() 亦为 [azure_event_hub_producer],资源回调模块为 emqx_bridge_kafka_impl_producer——最终由 Kafka Producer 实现完成实际的消息发送。

七、测试验证:默认值与校验行为从何而来

仓库在 emqx_bridge_azure_event_hub/test 下提供了两类测试:

  • emqx_bridge_azure_event_hub_tests.erl(eunit):聚焦 schema 解析与校验,可验证本文中的多项结论:
    • 隐藏默认值:authentication.username 为 $ConnectionString、mechanism 为 plain、ssl.enable 为 true、ssl.server_name_indication 解析为 servicebus.windows.net;
    • SNI 支持 disable 与自定义值;
    • 关闭 SSL(ssl.enable=false)、使用 scram_sha_256/scram_sha_512 机制、required_acks=none、compression=snappy/gzip 均触发校验错误;
    • max_batch_age 与 max_retries 默认 infinity 且可设置为 500ms/3;reconnect_delay 默认 2s;request_timeout 默认 30s;
    • Action schema 会剔除 message.timestamp 字段。
  • emqx_bridge_azure_event_hub_SUITE.erl(common_test):在模拟 Kafka SASL/SSL 环境(toxiproxy)中做端到端验证,包括启动/停止、状态查询、规则动作触发、动态 topic、以及“AEH 桥接与同名 Kafka 桥接共存互不影响”等场景,其中规则动作测试直接复用 emqx_bridge_kafka_action_SUITE 的用例,印证了“AEH 桥接复用 Kafka 实现”的架构事实。

八、使用前提与限制说明

  • 本文配置基于当前仓库代码(应用版本 6.3.0,见 mix.exs),字段命名与默认值可能随版本演进,请以实际部署版本的 schema 为准;
  • 使用 AEH 桥接需在 Azure 侧准备:Event Hub 命名空间、命名空间级 SAS 连接字符串(或权限足够的策略)、允许 Kafka 协议访问的网络环境(标准端口 9093,TLS);
  • 该桥接为 Enterprise 数据集成能力,开源社区版不含此应用,但实现思路(复用 Kafka 协议与 wolff 缓冲)与配置模型对理解 EMQX 数据集成框架有普遍参考价值;
  • 本仓库为只读镜像,如需深入了解可在本地克隆后查看 apps/emqx_bridge_azure_event_hub 目录下的源码与测试,或参考 EMQX 官方数据集成文档中 Azure Event Hub 桥接章节(原文档所列的官方文档链接见 README.md)。

总结

emqx_bridge_azure_event_hub 应用以“Kafka 协议 + wolff 自带 replayq 缓冲”为设计主线,为 EMQX 提供了一条架构精简、可落盘缓冲的 Azure Event Hub 数据出口。它通过复用 Kafka 桥接的 schema 与 Producer 实现,仅在认证(固定 PLAIN + $ConnectionString)、传输(强制 SSL、SNI 自动解析为 servicebus.windows.net)、压缩(强制 no_compression)与 acks(仅 all_isr/leader_only)等维度做收紧约束,从而保证与 Azure 端行为的一致性与安全性。配合 Connector/Action 两级配置模型与详尽的默认值,开发者可以在几分钟内完成从 EMQX 到 Event Hub 的高吞吐消息管道搭建。

登录后查看全文
emqx