EMQX Azure Event Hub 数据集成桥接:基于 Kafka 协议的 Producer 实现与配置指南
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_bridge_azure_event_hub_action_info:声明 action 类型名与 schema 模块(见 emqx_bridge_azure_event_hub_action_info.erl);emqx_bridge_azure_event_hub_connector_info:声明 connector 类型名、资源回调模块为emqx_bridge_kafka_impl_producer、配置 schema 模块(见 emqx_bridge_azure_event_hub_connector_info.erl)。
提示:文章中的概念同样适用于 EMQX Enterprise 的数据集成场景,但所有配置字段与默认值均以当前仓库源码为准。
二、架构要点:自带 replayq 缓冲,不依赖 emqx_resource 缓冲 worker
原文档特别强调了两点架构事实,这是理解 AEH 桥接与普通 Kafka 桥接差异的关键:
wolff库自带replayq缓冲实现。wolff是 EMQX 团队维护的 Kafka Producer 客户端库,其内部通过replayq维护按分区组织的发送队列。当 Kafka 服务端不可用时,消息可以留在replayq中等待重发;- 因此该桥接不需要
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_messageschema 删除了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 的高吞吐消息管道搭建。