EMQX S3 Connector 生命周期修复:禁用或删除连接器后 HTTP 连接池的可靠回收

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

EMQX S3 Connector 生命周期修复:禁用或删除连接器后 HTTP 连接池的可靠回收

本篇文章基于 EMQX 开源仓库 changes/ee/fix-14567.en.md 这条变更记录,深入讲解 S3 Connector 的 HTTP 连接池(Hackney Pool)在连接器被禁用(disable)或删除(remove)时如何被正确回收,包括问题成因、修复落点、on_start/on_stop 生命周期回调与 emqx_resource_manager 的联动关系,以及对应的源码与测试证据。读完本文,你将理解 EMQX S3 连接池的启动、更新、停止全流程,并能通过日志与状态接口验证池是否被干净回收,避免连接资源泄漏。

变更背景:S3 Connector 的 HTTP 连接池架构

S3 Connector 是 EMQX 中用于对接各类 S3 兼容对象存储(如 MinIO、AWS S3 等)的桥接组件,位于 apps/emqx_bridge_s3。它在运行时依赖底层 apps/emqx_s3 应用提供的 S3 客户端能力,而 S3 客户端的所有 HTTP 请求都通过 Hackney 连接池 发出:

  • emqx_s3_client_http.erl 是 HTTP 层的核心封装,导出 start_pool/2、update_pool/2、stop_pool/1 三个池管理接口;
  • 池名(PoolName)直接使用连接器实例 ID(InstId),保证每个 S3 连接器拥有独立、可定位的连接池;
  • 池配置由 transport_options.pool_size 决定最大连接数,timeout 固定为 60000ms(keepalive 空闲超时),见 pool_config/1 的实现:
    pool_config(#{
        transport_options := #{
            pool_type := _PoolType,
            pool_size := PoolSize
        }
    }) ->
        [
            {max_connections, PoolSize},
            {timeout, _Keepalive = 60000}
        ].
    
  • 所有对象读写操作(put_object、start_multipart、upload_part、complete_multipart 等)在 emqx_s3_client.erl 中构建 aws_config,并最终把请求委托给 emqx_s3_client_http:request/6 通过池发送。

连接池是长生命周期的共享资源:一旦启动,池内会保持已建立的 TCP/TLS 连接以复用。如果连接器被禁用或删除后池不被停止,连接将长期驻留,造成文件描述符与内存泄漏,这正是本次变更要修复的问题。

修复内容:池回收不完整的 Bug

原始变更记录(changes/ee/fix-14567.en.md)原文仅一句话,但信息量明确:

Fixed an issue where S3 HTTP pool would not be stopped after disabling or removing the S3 Connector. (修复了禁用或删除 S3 Connector 后,S3 HTTP 连接池不会被停止的问题。)

从当前仓库源码看,修复后的实现已在连接器生命周期回调中显式管理连接池:无论是 on_start 启动时的重建,还是 on_stop 停止时的回收,都会调用 emqx_s3_client_http:stop_pool/1。这意味着:

  • 连接器被删除(remove)时,连接池随资源一起销毁;
  • 连接器被禁用(enable = false)时,连接池同样被回收,不会残留在系统中;
  • 连接器重启 / 配置更新后重启时,先停旧池再建新池,避免同名池重复注册冲突。

源码级剖析:池的生命周期回调

on_start/2:先停后建,保证干净启动

在 emqx_bridge_s3_connector.erl 中,on_start/2 的启动逻辑如下:

on_start(InstId, Config) ->
    PoolName = InstId,
    S3Config = Config#{url_expire_time => 0},
    State = #{
        pool_name => PoolName,
        client_config => emqx_s3_profile_conf:client_config(S3Config, PoolName),
        channels => #{}
    },
    _ = emqx_s3_client_http:stop_pool(PoolName),
    case emqx_s3_client_http:start_pool(PoolName, S3Config) of
        ok ->
            ?SLOG(info, #{msg => "s3_connector_start_http_pool_success", pool_name => PoolName}),
            {ok, State};
        {error, Reason} = Error ->
            ?SLOG(error, #{
                msg => "s3_connector_start_http_pool_fail",
                pool_name => PoolName, config => S3Config, reason => Reason
            }),
            Error
    end.

关键点:

  1. PoolName = InstId:连接池以连接器实例 ID 命名,天然唯一;
  2. 先 stop_pool 再 start_pool:启动前先尝试停止可能残留的同名池(返回值被忽略,_ =),再创建新池,保证重启场景下不会因同名池已存在而失败;
  3. 启动成功/失败均有结构化日志(s3_connector_start_http_pool_success / s3_connector_start_http_pool_fail),便于排障。

on_stop/2:禁用与删除时回收池

修复的核心落在 on_stop/2:

on_stop(_InstId, _State = #{pool_name := PoolName}) ->
    Res = emqx_s3_client_http:stop_pool(PoolName),
    ?tp(s3_bridge_stopped, #{instance_id => _InstId}),
    Res.
  • 从 state 中取出 pool_name,调用 emqx_s3_client_http:stop_pool/1 停止 Hackney 池,释放全部连接;
  • 发出 s3_bridge_stopped 追踪事件(trace point),该事件同时被测试用例用作验证钩子(见下文「测试验证」);
  • 该回调由 emqx_resource 行为规定(-callback on_stop(resource_id(), resource_state()) -> term().,见 emqx_resource.erl),是连接器停止时的必经之路。

emqx_resource_manager:谁在调用 on_stop

on_stop/2 并不是直接被用户操作触发,而是由资源管理器 emqx_resource_manager.erl 统一驱动:

  • 用户禁用连接器时,资源管理器收到 stop 事件,进入 stop_resource/1 流程(emqx_resource_manager.erl);
  • 用户删除连接器时,收到 {remove, ClearMetrics} 事件,经由 handle_remove_event 同样进入停止流程(emqx_resource_manager.erl);
  • 资源管理器自身终止(如应用重启、监督树关闭)时,terminate/3 会调用 maybe_stop_resource/1(emqx_resource_manager.erl),兜底回收资源;
  • 最终统一由 stop_resource/1 调用 emqx_resource:call_stop/3(emqx_resource.erl),即 Mod:on_stop(ResId, ResourceState)。

由此可以推断:修复前的问题根源在于连接器停止路径上缺少对连接池的显式回收调用;修复后的代码保证无论连接器是被禁用、删除、还是伴随节点/应用关闭,都会走到 on_stop/2 并把池停掉。

stop_pool/1:容错式停止

emqx_s3_client_http.erl 中的 stop_pool/1 采用了容错设计:

stop_pool(PoolName) ->
    case hackney_pool:stop_pool(PoolName) of
        ok ->
            ok;
        {error, Reason} ->
            ?SLOG(error, #{msg => "s3_stop_http_pool_fail", pool_name => PoolName, reason => Reason}),
            ok
    end.

即使池不存在或已停止(返回 {error, ...}),也只会记录 s3_stop_http_pool_fail 错误日志并返回 ok,不会把异常抛给上层——这保证了 on_start 中"先停后建"的幂等性,也让 on_stop 在重复停止时安全无害。

测试验证:行为有据可依

仓库中的测试对池生命周期进行了直接或间接的覆盖:

  1. 连接器启停测试:emqx_bridge_s3_SUITE.erl 中 t_start_stop/1 调用 emqx_bridge_v2_testlib:t_start_stop(Config, s3_bridge_stopped),以 s3_bridge_stopped(即 on_stop/2 发出的 trace point)作为停止成功的验证信号;
  2. 池管理测试:emqx_s3_client_SUITE.erl 在每个用例初始化时通过 emqx_s3_profile_conf:start_http_pool/2 启动池,用例结束后调用 emqx_s3_client_http:stop_pool/1 清理——直接验证 stop_pool/1 对已启动池的回收能力;
  3. 配置样例:emqx_bridge_s3_SUITE.erl 中构造的 transport_options 包含 pool_size => 4、connect_timeout、request_timeout、ssl.enable 等,展示了池相关的完整配置形态,也可作为排障时的参考输入。

运维视角:如何确认池已被回收

结合上述实现,运维/开发人员在升级到包含该修复的版本后,可通过以下方式验证连接池回收是否生效:

  1. 观察日志:停止连接器时不应再出现异常堆栈;若池停止失败,会看到 s3_stop_http_pool_fail 错误日志(含 pool_name 与 reason);启动成功对应 s3_connector_start_http_pool_success;
  2. 查看连接数:禁用或删除 S3 Connector 后,通过系统工具(如 ss / lsof)观察到指向 S3 服务端口的 ESTABLISHED 连接随之关闭,即说明池内连接被回收;
  3. 结合状态接口:连接器的健康状态由 on_get_status/2 通过 emqx_s3_client:get_status/1 检查,确认连接器确实处于 stopped / disconnected 状态后再检查连接回收情况。

小结

fix-14567 这条变更看似微小,但补齐了 S3 Connector 生命周期中一个关键的资源回收缺口:让禁用、删除连接器的路径与连接池的销毁严格绑定。当前仓库中 emqx_bridge_s3_connector.erl 的 on_start/2、on_stop/2 与 emqx_s3_client_http.erl 的 start_pool/stop_pool 构成了完整的池管理闭环,配合 emqx_resource_manager 的统一生命周期驱动和基于 trace point 的自动化测试,保证了连接池在连接器任何停止场景下都不会泄漏。

登录后查看全文
emqx