EMQX 6.0 移除 Bridges V1：数据集成全面迁移至 Connectors/Actions/Sources 架构

EMQX 6.0 移除 Bridges V1数据集成全面迁移至 Connectors/Actions/Sources 架构【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx本指南基于 EMQX 仓库中的变更记录changes/ee/feat-15864.en.md深入解析 EMQX 6.0 中正式移除已废弃的 Bridges V1 API 与配置 schema 这一重大变更/bridges/*全部 HTTP 端点与bridges配置根键已不再可用数据集成已全面迁移到 Connectors / Actions / Sources 新模型。读完本文你将理解旧桥接模型被移除的来龙去脉、新模型的配置结构与 REST API 形态、升级过程中的配置迁移机制以及如何将存量配置平滑过渡到新架构。变更公告原文We have dropped the already deprecated Bridges V1 APIs and configuration schemas. Endpoints under/bridges/*and configurations under thebridgesroot key are no longer available, since data integrations have migrated to Connectors/Actions/Sources.这段变更记录对应 PR #15864同时收录于 changes/e6.0.0.en.md 第 132 行宣告了 EMQX 6.0 中一个里程碑式的清理动作Bridges V1 正式退役。其核心事实可以拆解为三点已废弃的Bridges V1 REST API被移除/bridges/*路径下的端点全部失效已废弃的Bridges V1 配置 schema被移除配置文件中的bridges根键不再被识别移除的根因是数据集成体系已整体迁移到Connectors / Actions / Sources三层模型。演进脉络从 Bridge 到 Connector / Action / Source理解这次移除需要先回顾 EMQX 数据集成模型的演进历史。仓库 changes/e5.3.1.en.md 第 7 行的变更记录给出了明确的时间线Feature Preview: Planned for EMQX v5.4.0, introducing the concepts ofConnectorandActionbased on data bridge. The existing data bridge will be gradually migrated to Connector and Action. Connector are designed to manage the integration with external systems, while Actions are solely used to configure the data processing methods. Connector can be reused across multiple Actions, providing greater flexibility and scalability.也就是说从 v5.4.0 起EMQX 便以 Feature Preview 形式引入了新模型并确立了逐步迁移、最终移除的路线Connector 负责与外部系统的连接管理Action 只负责配置数据处理方式且一个 Connector 可被多个 Action 复用以获得更高的灵活性与可扩展性。到 6.0这条迁移路线走到终点旧的 Bridges V1 被彻底清除。新模型的职责划分更为清晰概念职责定位配置根键REST API 路径Connector管理对外部系统的连接连接参数、认证、池化等可被多个 Action 复用connectors/connectors/*Action定义数据处理动作写入外部系统的具体方法引用某个 Connectoractions/actions/*Source定义数据来源从外部系统拉取/消费数据并注入规则引擎sources/sources/*新模型的配置结构HOCON 示例在 6.0 中bridges根键已被connectors、actions、sources三个根键取代。配置文件大致形态如下connectors { my_kafka_connector { connector_type kafka bootstrap_hosts 127.0.0.1:9092 ... } } actions { my_kafka_action { connector my_kafka_connector parameters { ... } resource_opts { health_check_interval 30s ... } } } sources { my_kafka_source { connector my_kafka_connector parameters { ... } } }其中connectors根键的 schema 由 apps/emqx_connector/src/schema/emqx_connector_schema.erl 定义。其roots/0函数第 150176 行注册了connectors配置根并挂载了validator校验器保证每个 Connector 实例的配置在加载时即被校验roots() - [ {connectors, ?HOCON( ?R_REF(connectors), #{ importance ?IMPORTANCE_LOW, validator fun validator/1 } )} ].而actions与sources两个根键的 schema 统一由 apps/emqx_bridge/src/schema/emqx_bridge_v2_schema.erl 管理。该模块通过emqx_action_info:registered_schema_modules_actions()动态汇总所有已注册的 Action 类型 schema并分别导出actions_get_response/0、actions_put_request/0、sources_get_response/0、sources_put_request/0等 API 响应/请求结构第 8188 行、149156 行这意味着新模型的 API 文档与配置 schema 是由各桥接插件的 schema 模块自动聚合生成的。REST API 形态/bridges/* 移除后由谁接管Connectors APIConnector 管理 API 定义于 apps/emqx_connector/src/emqx_connector_api.erl其paths/0函数第 107115 行注册了完整的端点族paths() - [ /connectors, /connectors/:id, /connectors/:id/enable/:enable, /connectors/:id/:operation, /nodes/:node/connectors/:id/:operation, /connectors_probe ].GET/POST /connectors列出 / 创建 ConnectorPUT/DELETE /connectors/:id更新 / 删除指定 ConnectorPOST /connectors/:id/enable/:enable启停POST /connectors_probe连通性探测在创建前验证连接参数是否可达。Actions 与 Sources APIAction 与 Source 管理 API 定义于 apps/emqx_bridge/src/emqx_bridge_v2_api.erl其paths/0第 114146 行注册的端点包括paths() - [ /actions, /actions/:id, /actions/:id/enable/:enable, /actions/:id/:operation, /nodes/:node/actions/:id/:operation, /actions/:id/metrics, /actions/:id/metrics/reset, /actions_probe, /actions_summary, /action_types, /sources, /sources/:id, /sources/:id/enable/:enable, /sources/:id/:operation, /nodes/:node/sources/:id/:operation, /sources/:id/metrics, /sources/:id/metrics/reset, /sources_probe, /sources_summary, /source_types ].相比旧版/bridges/*新端点族增加了三类能力/actions_probe与/sources_probe创建前的连通性/参数探测/action_types与/source_types枚举当前集群中所有已注册的 Action / Source 类型由各桥接插件注册便于 API 客户端动态发现能力/actions_summary与/sources_summary返回精简摘要便于 Dashboard 与自动化脚本快速获取状态概览。从源码结构看旧/bridges/*端点族在 6.0 中已被完全移除任何对该路径的请求都会返回 404客户端应改用上述三组端点。升级与配置迁移机制存量配置自动转换对于从 5.8.0 及以上版本滚动升级到 6.0 的用户无需手工改写全部配置。仓库 changes/e6.0.1.en.md 第 42 行记录了配套的迁移能力PR #16047Added support to perform rolling upgrade from EMQX Enterprise base version 5.8.0 and newer to 6.0. During the upgrade, legacy configurations are automatically migrated to the new format supported in 6.0. Specifically, the deprecatedbridgesconfiguration root is converted into the newconnectors,sources, andactionsroots.即升级过程中废弃的bridges配置根会被自动转换为新的connectors、sources、actions根用户无需手动拆分。配置导入的依赖顺序迁移并非简单的键名替换还涉及初始化顺序的编排。在 apps/emqx_conf/src/emqx_conf_cli.erl 的to_sorted_list/1第 837844 行中可以看到配置导入时的高优先级排序规则%% connectors actions/bridges/sources rule_engine Keys [connectors, actions, sources, bridges, rule_engine],从源码注释与排序逻辑可以推断导入顺序的设计原则是先建连接、再建动作/数据源、最后配置规则引擎Connector 必须先于引用它的 Action / Source 存在规则引擎rule_engine依赖 Action 而排在最后。这里仍保留了对bridges键的排序处理是为了兼容升级场景中尚未完成转换的遗留配置的导入顺序。历史兼容层更早版本的转换对于更早的版本v5.0.0v5.0.11仓库还保留了一个历史兼容模块 apps/emqx_bridge/src/schema/emqx_bridge_compatible_config.erl。该模块第 56 行注释负责将旧版 mqtt/webhook 连接器配置转换为新版格式%% doc This module was created to convert old version (from v5.0.0 to v5.0.11) %% mqtt/webhook connector configs to newer version (developed for enterprise edition).其up/1函数第 4066 行展示了典型的字段迁移逻辑读取旧配置中的connector子键按directionegress/ingress分别映射出egress/1、ingress/1结构并补齐默认值例如默认 SSL 关闭default_ssl/0、默认资源选项resource_optsinflight_window 100、health_check_interval 15s、max_buffer_bytes 1GB、query_mode sync、worker_pool_size 4。这表明配置键迁移在 EMQX 中并非 6.0 才出现的新机制而是伴随数据集成模型演进的一贯做法。测试与验证新模型的工程质量保障新模型在仓库中拥有独立的测试体系可作为验证迁移正确性的参照apps/emqx_bridge/test/emqx_bridge_v2_SUITE.erlV2 桥接Action/Source全流程集成测试覆盖创建、删除、重建等生命周期场景apps/emqx_bridge/test/emqx_bridge_v2_api_SUITE.erl/actions、/sourcesREST API 的契约测试apps/emqx_bridge/test/emqx_bridge_v2_testlib.erlV2 模型公共测试工具库供各桥接插件测试复用apps/emqx_bridge/test/emqx_bridge_v2_tests.erlschema 测试其中non_deprecated_fields/1第 1314 行专门过滤已废弃字段确保新模型 schema 中不残留 deprecated 配置项——这与本次移除 Bridges V1 的清理目标一脉相承。此外各桥接插件都提供了对应 Connector/Action 的实现与测试例如 apps/emqx_bridge_http/src/emqx_bridge_http_connector.erl、apps/emqx_bridge_azure_blob_storage/src/emqx_bridge_azure_blob_storage_connector.erl 等均为新模型下的 Connector 实现。迁移核对清单根据上述分析存量用户迁移到 6.0 时的核对要点如下API 客户端改造将所有/bridges/*请求改写为/connectors/*、/actions/*、/sources/*对应端点若脚本依赖/bridges返回的字段结构需对照emqx_bridge_v2_schema与emqx_connector_schema的示例输出如actions_examples/1、connector_info_examples/1调整字段名。配置文件清理确认emqx.conf中不再出现bridges { ... }根键若为 5.8.0 及以上版本滚动升级可依赖自动迁移但仍建议在升级前备份配置并在升级后用emqx_ctl conf show检查转换结果。依赖顺序确认若手工编写新格式配置务必保证connectors中定义的 Connector 先于引用它的actions/sources定义出现否则配置导入时可能因依赖缺失而报错对应 emqx_conf_cli.erl 第 842 行的导入排序约束。规则引擎关联检查规则引擎中引用的动作ActionID 是否已按新命名空间调整参考 emqx_bridge_v2.erl 中ensure_action_removed/3第 391 行等与规则引擎联动清理的逻辑。总结EMQX 6.0 移除 Bridges V1/bridges/*API 与bridges配置根键是自 v5.4.0 引入 Connector / Action 概念以来数据集成模型演进的自然终点。新模型通过 Connector连接管理、Action处理动作、Source数据来源的三层拆分实现了连接复用、配置解耦与更细粒度的运维控制。对存量用户而言5.8.0 版本可通过自动迁移平滑过渡对 API 客户端与自动化脚本则需要按上文清单完成端点与字段的适配。仓库中 emqx_bridge_v2_schema.erl、emqx_bridge_v2_api.erl、emqx_connector_api.erl 是理解新模型结构与 API 契约的第一手资料。【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考