EMQX PostgreSQL 桥接连接池泄漏修复解析:Connector 删除时连接池残留问题的根因与防护

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

EMQX PostgreSQL 桥接连接池泄漏修复解析:Connector 删除时连接池残留问题的根因与防护

导读

本文围绕 EMQX 开源仓库中 fix-15693.en.md 这条变更记录展开:基于 PostgreSQL 的桥接(Postgres-based bridges)此前存在连接池泄漏隐患——在连接池初始化过程中,若遭遇竞态条件,即使用户已删除 Connector,连接池仍可能残留于运行中的节点。文章将结合仓库源码,从连接池的分配/回收机制、竞态条件产生的根因、修复后的防护手段,以及如何验证连接池已被彻底清理等角度进行完整讲解。读完本文,你将掌握 EMQX PostgreSQL 连接器(Connector)与动作(Action/Bridge)的生命周期管理原理,并能在实际运维中通过命令和测试用例确认连接池是否正确释放。

变更记录原文

changes/ee/fix-15693.en.md 全文如下:

Postgres-based bridges were patched to avoid leaking connection pools. Previously, depending on race conditions when initializing the pool, if one later deleted the Connector, the pool could still be present.

翻译过来即:基于 PostgreSQL 的桥接已打补丁以避免连接池泄漏。此前,取决于初始化连接池时的竞态条件,如果随后删除了 Connector,连接池仍可能残留。

这虽然只有一句话,但它指向的是一类典型的 Erlang/OTP 资源生命周期问题:进程资源(连接池)的分配与清理不在同一个失败路径上闭环。下文将逐一拆解。

PostgreSQL 连接器与桥接:三层资源模型

在深入泄漏问题之前,先厘清 EMQX 中 PostgreSQL 相关组件的资源分层。从源码结构看,涉及三个应用:

  1. emqx_bridge_pgsql:定义 pgsql 类型的动作(Action),即桥接的“写入端”,承载 SQL 模板、批量参数(batch_size 默认 100、batch_time 默认 100ms)等配置。
  2. emqx_bridge_pgsql_connector_info.erl:将 pgsql 连接器注册到连接器框架,其 resource_callback_module() 指向 emqx_postgresql,说明实际的连接管理由后者承担。
  3. emqx_postgresql:实现 emqx_resource 行为,负责建立 PostgreSQL 连接、维护 ecpool 连接池、执行查询。

三者关系可概括为:Connector(连接器)是资源实例(resource),Action(动作/桥接)挂载在连接器之上作为通道(channel)。连接池以连接器资源实例为单位创建,名为 conn_pool(见 emqx_postgresql.erl 中的 -define(conn_pool, conn_pool)),这正是泄漏发生的位置。

连接池的初始化:on_start 与资源分配

连接器创建时,emqx_resource 行为回调 on_start/2 会被触发。emqx_postgresql.erl 中的 on_start/2 执行了如下关键步骤:

  1. 解析 server 配置(host/port)、构造 epgsql 连接选项(用户名、密码、数据库、application_name、auto_reconnect、pool_size 等);
  2. 解析 SQL 模板;
  3. 调用 emqx_resource:allocate_resource(InstId, ?MODULE, ?conn_pool, InstId) 登记“已分配资源”;
  4. 调用 emqx_resource_pool:start(InstId, ?MODULE, Options ++ SslOpts) 真正启动连接池;
  5. 初始化预处理语句(prepared statements)。

其中第 3 步非常关键。emqx_resource.erl 的实现是:

allocate_resource(InstanceId, ResourceMod, Key, Value) ->
    _ = ets:insert_new(?RESOURCE_ALLOCATION_TAB, {InstanceId, ?RES_MOD_KEY, ResourceMod}),
    true = ets:insert(?RESOURCE_ALLOCATION_TAB, {InstanceId, Key, Value}),
    ok.

它把“该资源实例分配了某类资源(此处为连接池)”登记在 ETS 表 ?RESOURCE_ALLOCATION_TAB 中,并记录资源模块 emqx_postgresql。资源分配登记发生在连接池真正启动之前,这是竞态条件产生的重要前提。

竞态条件分析:删除 Connector 时连接池为何会残留

变更记录指出,问题与“初始化连接池时的竞态条件”有关。结合源码可以还原出如下泄漏路径:

  • on_start/2 先调用 allocate_resource/4 完成 ETS 登记,再调用 emqx_resource_pool:start/3 启动连接池;
  • 连接池启动是一个异步、多步骤过程(创建 supervisor、生成 worker、建立 TCP/TLS 连接、执行认证等);
  • 若在资源登记完成之后、连接池完全启动之前,用户通过管理 API 或 Dashboard 删除了该 Connector,此时 emqx_resource_manager 收到 remove 请求;

从 emqx_resource_manager.erl 的 do_remove/2 可见删除流程:若资源进程已存在则正常同步移除;若资源进程尚未注册(gproc:whereis_name 返回 undefined),则只调用 try_clean_allocated_resources(ResId) 兜底清理。

而 emqx_resource.erl 的 clean_allocated_resources/1 逻辑是:

clean_allocated_resources(ResourceId) ->
    case emqx_resource:get_allocated_resource_module(ResourceId) of
        {ok, ResourceMod} ->
            case call_stop(ResourceId, ResourceMod, _ResourceState = undefined) of
                ok -> ok;
                {error, Reason} -> ... 记录日志后仍返回 ok
            end;
        error ->
            %% Nothing allocated
            ok
    end.

问题在于:兜底清理依赖 call_stop/3 能正确停掉连接池。若连接池仍在异步初始化途中(supervisor 与 worker 尚未就绪,或 ETS 登记与池进程注册之间出现时间窗口),call_stop 可能因找不到完整状态的资源进程而无法触达底层 ecpool 的清理,导致 ecpool 的 supervisor 树、worker 进程乃至已建立的 PostgreSQL 连接成为“孤儿”残留下来。

换言之,泄漏的本质是:资源登记(ETS 写入)与连接池进程树(ecpool supervisor/pool)的创建不是原子的,删除操作落在两者之间的窗口内时,仅靠“删除”路径上的清理无法覆盖“尚未完全建立”的池。

修复策略:保证资源分配与清理路径闭环

从源码结构看,修复围绕“无论连接池初始化处于哪个阶段,删除操作都必须能够完成清理”这一目标展开,体现在两个层面:

层面一:删除兜底必须无条件触发清理。 在 emqx_resource_manager.erl 中,即使资源进程不存在(undefined 分支),也调用 try_clean_allocated_resources/1,其内部(emqx_resource_manager.erl)委托给 emqx_resource:clean_allocated_resources/1。这一“从 ETS 登记反查资源模块并调用其 stop 回调”的机制,使得删除操作不必依赖进程注册状态,只要 ETS 中有登记即可尝试清理。

层面二:连接器停止时必须显式关闭连接。 在 emqx_postgresql.erl 中,on_stop/2 除了调用 emqx_resource_pool:stop(InstId) 之外,还通过 close_connections/1 遍历 ecpool:workers(PoolName),对每个 worker 的连接显式执行 epgsql:close(Conn):

on_stop(InstId, State) ->
    close_connections(State),
    Res = emqx_resource_pool:stop(InstId),
    Res.

close_connections_with_worker_pids/1 中逐一取出连接并调用 epgsql:close/1,同时对“连接已关闭”等错误采取忽略策略(catch _:_ -> ...),保证清理过程健壮、不因单个连接异常而中断。先关连接、再停池的顺序,确保了底层 socket 与驱动连接对象都能被及时回收。

从代码注释与实现可以推断,该补丁正是通过上述“删除路径兜底 + 停止路径显式关闭连接”的组合,消除了“初始化竞态导致池残留”的窗口:无论池是否完全建立,删除操作最终都会走到 on_stop/call_stop 路径并关闭所有已创建的连接。

如何验证连接池已被正确释放

修复后的行为可以通过以下方式验证,这也对应仓库测试 emqx_postgresql_SUITE.erl 中覆盖的场景:

  1. 停止资源后,池必须彻底消失。测试断言(emqx_postgresql_SUITE.erl):emqx_resource:stop(ResourceId) 返回 ok 后,emqx_resource:health_check(ResourceId) 返回 {error, resource_is_stopped},且直接查询池 ecpool:stop_sup_pool(PoolName) 返回 {error, not_found}——说明 supervisor 树已被移除。

  2. 删除资源后,连 ETS 中的资源数据也不应残留。测试进一步断言(emqx_postgresql_SUITE.erl):emqx_resource:remove_local(ResourceId) 之后再调用 ecpool:stop_sup_pool(PoolName) 同样返回 {error, not_found},并且“甚至不应该能从 ETS 中取出资源数据”。

  3. 重复停止必须是幂等的。测试验证对已停止的实例再次调用 stop/1 依然返回 ok(emqx_postgresql_SUITE.erl),这保证了删除/重启流程中重复清理不会报错。

对于生产环境的日常巡检,可借助 EMQX 管理 API 删除 Connector 后,在节点上检查进程与端口:

# 查看是否存在残留的 postgres 相关 ecpool 进程
ps aux | grep beam | grep -i postgres

# 或通过 EMQX 提供的 erl shell 查询连接池是否存在
# 在 emqx 控制台执行:
#   ecpool:find_pools()  -> 应不再包含被删除连接器对应的 pool

同时注意观察节点日志:修复后的 on_stop 会输出 "stopping_postgresql_connector" 日志(见 emqx_postgresql.erl),若删除操作触发了该日志但进程仍残留,则属于异常情况,应进一步检查连接池初始化是否被卡死。

运维建议:避免触发竞态条件的实践要点

虽然修复已从代码层面闭环了清理路径,但从运维角度仍建议:

  • 创建连接器后等待其状态变为 connected 再删除:连接池初始化期间(尤其是网络慢、SSL 握手耗时长、health_check_timeout 配置较大时)删除操作最容易落入竞态窗口;
  • 删除连接器前先停用其上的 Action/桥接:先解除通道(channel)与连接器的绑定,再删除连接器本身,可让 on_remove_channel(emqx_postgresql.erl)先关闭预处理语句,缩小清理面;
  • 关注 pool_size 配置:池越大,初始化与清理涉及的对象越多,删除操作需要的时间越长,相应地要保证管理 API 的请求超时设置足够;
  • 升级后重启节点:若曾在旧版本上发生过连接池泄漏,升级到修复版本后建议滚动重启节点,确保已残留的孤儿进程被彻底回收。

相关文件索引

登录后查看全文
emqx