Dify接入PostgreSQL：用DBHub网关实现统一数据库连接管理

最近在做某AI应用平台的私有化部署，需要把Dify的元数据落到PostgreSQL上。按照运维侧的规矩，所有数据库访问不能由业务应用直连，必须走统一的连接管理入口。折腾下来，我在Dify和PostgreSQL之间加了一层DBHub作为数据库连接网关，让Dify只认DBHub的地址，由DBHub统一转发SQL到下游PG实例。整个过程涉及容器网络、认证方式、连接池参数、数据迁移等一堆环节，中间踩了不少坑，也沉淀了一些可以复用的经验。这篇博文就把完整的方案思路、配置过程和排查记录整理出来，给同样在折腾Dify外部数据库接入的开发者做个参考。

这个方案适合这几类人：用Docker Compose部署Dify、想把数据库切到独立PostgreSQL实例的同学；团队规定应用层不允许直连数据库、需要统一账号管理和审计的开发者；以及需要在Dify工作流里读取外部业务库数据做应用编排的朋友。我会把连接配置、环境变量、容器网络、常见坑全部展开，尽量做到可以直接照着操作。

1. 为什么要在Dify和PostgreSQL之间加一层DBHub

1.1 Dify的数据库依赖到底有多重

很多人对Dify的印象是一个LLM应用编排平台，觉得它主要是在跟模型打交道，数据库只是存个账号密码而已。实际用过之后你会发现，Dify对数据库的依赖相当重。应用配置、工作流定义、知识库分段和向量索引的元数据、对话历史、工具调用记录、用户反馈标注，这些数据最终都会落到关系型数据库里。对于有一定规模的使用场景，数据库一旦抖动，整个平台的创作和运行都会受牵连。

Dify默认支持SQLite和PostgreSQL两种存储方式。生产环境几乎没有用SQLite扛的，基本都是上PostgreSQL。这里说的"连接pg数据库"，本质上就是让Dify这个平台自己使用一个外部PostgreSQL实例来持久化所有业务数据。很多人第一次部署Dify时直接用docker-compose内置的PostgreSQL容器，这在开发环境没什么问题，但到了公司内部要统一管控数据库的阶段，就会碰到几个现实困难。

1.2 DBHub解决的核心痛点

直连数据库的方案，最直接的问题就是连接信息分散。Dify容器里的环境变量会直接写入真实的PG地址、端口、账号和密码，一旦容器被渗透或者说配置泄露，等同于把数据库账号拱手送人。而且直连模式下，各个应用各自维护连接数，没有中间层做连接池和限流，一旦Dify侧并发飙升，PG实例很容易被打到连接数上限。

我这次引入DBHub，核心思路是把数据库访问收敛到一个网关入口。DBHub在架构上扮演的角色类似数据库侧的流量网关：Dify只需要知道DBHub的服务地址，所有SQL请求先到DBHub，由它完成连接池管理、账号鉴权、SQL转发。对于运维团队来说，真实的PG凭据只存在于DBHub这一层，Dify看到的只是一个标准的PostgreSQL连接入口。

这个思路可以类比一下：正常情况下你访问后端API，前端不直接打业务服务，而是先进API网关，统一做鉴权、限流、路由。DBHub对数据库做的事情，基本就是同一套逻辑在数据访问层的复刻。

1.3 方案选型对比：直连、内网代理与DBHub

我最初想过两种方案：一是让Dify直连PostgreSQL，简单直接；二是只做一个内网转发端口，用防火墙限制来源。但最终都放弃了。

直连方案的问题在于连接池和账号管理不好做。Dify侧对连接数的需求会随着工作流并发数波动，直连模式下PG实例的max_connections配小了容易在高峰期被占满，配大了又浪费资源。而内网转发端口本质上只解决了网络安全隔离的问题，账号管理、连接复用、SQL审计这些能力依然是空白。

DBHub这种网关方案在安全、运维、性能之间找到了比较好的平衡点。它对外表现为一个标准的PostgreSQL监听端口，Dify侧配置起来没有额外的学习成本，同时DBHub内部可以维护多个上游PG实例的连接池，支持按连接串维度做账号隔离。下面是三种方案的快速对比：

从对比就能看出，DBHub方案虽然在部署阶段多了一步，但长期来看对运维侧的收益最大。尤其是后期如果同一个DBHub网关可以接多个PostgreSQL实例，Dify想切换或新增数据源时，只需要调整一下连接用户名和库名，底层真实地址完全不用暴露给应用层。

2. 部署DBHub并完成PostgreSQL侧的接入准备

2.1 前置条件与部署形态规划

在动手之前，先确认一下我这次的部署拓扑。Dify是通过Docker Compose方式运行的，整个Dify服务组跑在一台宿主机上。PostgreSQL是一个独立的实例，跟Dify不在同一台机器上，网络上是三层可达的。DBHub网关则单独部署在一台运维侧的机器上，两边都能访问它。

拓扑看起来不复杂，但有一个关键点值得先想清楚：DBHub要做到对Dify透明，就必须在网络上同时可达Dify容器和上游PG实例。如果Dify是容器化部署，而DBHub部署在宿主机外，那么Dify容器里访问DBHub时不能写"localhost"，必须写DBHub所在机器的内网IP。这个细节特别容易坑到人，后面我会详细展开。

安装DBHub的过程不复杂。我用的方式是直接下载对应的安装包解压运行，然后在初始化配置里设置一个网关管理界面端口和数据转发端口。管理界面用于配置上游数据源、查看连接状态，数据转发端口则是给Dify这类下游应用连的PostgreSQL协议端口。注意把这两个端口分开，不要图省事用一个端口，否则管理流量和数据流量混在一起，后续排查问题会比较难受。

2.2 DBHub中添加PostgreSQL数据源

首次登录DBHub的管理界面后，第一步是添加上游数据源。这一步需要填写的信息包括：数据源名称、真实PostgreSQL实例的内网地址、端口、要连接的数据库名，以及用于DBHub转发SQL的数据库账号。

这里有一个容易被忽略的点：DBHub转发时使用的账号，应该是在PostgreSQL侧单独创建的专用账号，而不是直接用超级用户。我在配置时创建了一个名为dify_gateway的账号，只授予了Dify实际需要操作的那些库表的权限，比如对dify库的CONNECT、建表、读写数据。这样即使DBHub被攻破，攻击者拿到的也只是一个有限权限的账号，而不是整个实例的管理员权限。

数据源配置完成后，DBHub会自动做一次到上游PG的连通性测试。如果测试失败，优先检查DBHub机器到PG实例的防火墙策略，然后再看账号密码是否输错。这一步能过的前提下，后面的转发才会正常。

2.3 PostgreSQL侧的安全加固与认证配置

在DBHub能连上PG之后，还有一个重要动作：收紧PostgreSQL本身对外的暴露面。既然Dify不再直连PG，那就应该将PG的防火墙策略收窄到只允许DBHub所在机器的IP访问。这个策略改动建议在DBHub连通性验证没问题之后再做，避免把自己关在门外。

另外，PostgreSQL的认证方式也需要配合调整。我这次使用的PG版本默认采用scram-sha-256密码认证。在pg_hba.conf里，需要确保DBHub机器来源的连接条目使用了scram-sha-256而不是trust，否则密码形同虚设。修改完pg_hba.conf后，需要执行pg_ctl reload或者等量级操作重载配置，不需要重启实例，生产环境重载比重启更稳妥。

注意：数据库密码加密方式和连接串是有联动的。如果PG配置为scram-sha-256，那么Dify侧连接串里的密码就必须是正确明文密码，不能使用旧的md5加密密码。这个坑在从旧版本PG迁移过来时特别常见，排查认证失败时要优先确认两边的密码加密方式是否匹配。

3. Dify接入DBHub的完整配置过程

3.1 部署方式对连接参数的影响

Dify的部署方式决定了你该在哪里改数据库连接信息。最常见的部署方式是用docker-compose起一整套服务，里面包含API服务、Worker、Web前端、Nginx以及依赖的PostgreSQL、Redis、Weaviate（或Qdrant）等容器。如果你用的是官方docker-compose.yaml模板，那么数据库连接参数是通过环境变量注入的。

在接线之前，先搞清楚Dify各服务组件连接数据库的路径。Dify的API服务和Worker服务都会访问数据库，两者在容器内部是通过配置的数据库连接串连接PostgreSQL的。所以关键的修改点是API和Worker容器启动时读取的环境变量。Web前端本身不直连数据库，不需要动。

我的实际操作是：把docker-compose.yaml里原本指向内置PostgreSQL容器服务的环境变量，改成指向DBHub网关的地址和端口。Dify镜像内部内置了PostgreSQL的客户端驱动，只要连接串正确，它并不会区分对面是原生PG还是DBHub网关转发，这一点保证了改动成本很低。

3.2 关键环境变量与连接串格式详解

Dify中控制数据库连接的核心环境变量如下：

如果你的部署方式不是通过环境变量而是通过DATABASE_URL连接串，则格式类似这样：

postgresql://dify_user:your_password@dbhub_gateway_ip:15432/dify?sslmode=prefer

连接串里有一点需要特别留意：sslmode这个参数。如果DBHub网关没有开启SSL终结功能，而Dify侧强制使用SSL连接，那么握手阶段会直接失败。我这次用的配置是sslmode=prefer，意思是优先尝试SSL，如果对方不支持就自动降级为明文连接，这样能兼容大多数网关形态。

有人可能会问，为什么端口不是默认的5432？因为DBHub网关的数据转发端口可以自定义，我用的是15432。端口改变本身不是重点，重点是Dify配置的这个端口必须与DBHub监听的数据端口严格一致，多一位少一位都不行。

3.3 从Dify容器内部验证连通性

改完环境变量后，需要重启Dify相关容器让配置生效。重启之后，我先做了一件事：进到Dify API容器内部，用自带命令直接验证到DBHub网关的连通性。这一步不是可有可无的，它能快速区分问题出在"网络不通"还是"Dify应用层配置错误"。

我用的验证命令大致是这样：

# 进入Dify API容器 docker exec -it dify-api bash # 在容器内检查到DBHub网关的网络连通性 apt-get update && apt-get install -y postgresql-client # 测试连接 psql -h dbhub_gateway_ip -p 15432 -U dify_user -d dify

执行psql连接时，系统会提示输入密码。能够成功进入psql交互界面并执行SELECT 1，说明从Dify容器到DBHub再到PG整条链路都是通的。走到这一步，Dify接管数据库基本就完成了90%，剩下的只是观察启动日志是否正常。

3.4 检查Dify启动日志与应用状态

链路通只是第一步，Dify应用本身是否成功初始化数据库，还得看日志。我重启容器后，用docker logs命令追踪了API服务的启动输出，正常情况下会看到数据库迁移、初始化表结构之类的日志。

有一个常见情况需要提一下：Dify在启动时可能会做数据库迁移操作。如果连的是一个全新的PostgreSQL库，Dify会自动创建业务表。如果连的是一个已有数据的库，迁移逻辑会更复杂。我这次用的是全新库，所以启动过程比较顺利。但如果你的场景是迁移已有环境，那么在切换数据库前一定要做好备份，并且确认新旧库的Dify版本一致，否则低版本代码连高版本结构的库，很容易出现字段缺失报错。

日志验证无误后，在浏览器里打开Dify的管理后台，正常能加载出应用列表，说明数据库连接已经可用了。到这一步，Dify本身连接PG的战略目标就完成了。

4. 在Dify工作流中通过DBHub访问外部业务库

4.1 工作流场景下的数据访问路径

Dify平台自身连接PostgreSQL只是基础。很多实际业务场景里，Dify编排的Agent或工作流还需要读取业务系统自己的数据库。比如做一个内部知识库问答助手，需要从业务库里查询产品信息、订单状态，然后交给大模型总结回复。

这种场景下，DBHub同样能发挥作用。你可以在DBHub中再创建一个数据源，指向具体的业务库，然后在Dify中通过HTTP工具节点或者代码节点调用DBHub提供的接口来执行查询。这里要说明的是，Dify的工作流本身并没有内置一个"数据库查询"节点，但可以用工具节点自定义API，或者直接用代码节点写Python调用数据库驱动的能力。

4.2 通过代码节点连接DBHub查询业务数据

Dify的工作流里支持Python代码节点。代码节点运行在Dify后端，它天然集成了部分常用依赖。我在做某个数据查询工作流时，就是在代码节点里通过psycopg2连接DBHub网关，执行SQL查询后返回结果集给大模型节点。

简化后的代码结构大致如下：

import psycopg2 def main(query: str): conn = psycopg2.connect( host="dbhub_gateway_ip", port=15432, user="app_readonly", password="your_password", dbname="business_db", connect_timeout=5 ) cursor = conn.cursor() cursor.execute(query) rows = cursor.fetchall() cursor.close() conn.close() return {"result": rows}

这里需要提醒的是，代码节点里执行SQL时务必做参数校验和超时控制。connect_timeout这个参数很有用，我把它设成5秒，避免DBHub网关或下游PG抖动时线程被长时间挂住。另外，openai函数调用或LLM节点拼接SQL的场景下，要严格控制输入，防止注入风险。数据库网关虽然能管理连接和账号，但它解决不了应用层的SQL注入问题。

4.3 工具节点方式：更安全的数据读取姿势

相比代码节点直接写SQL，我更推荐一种方式：在Dify中通过OpenAPI工具接入一个封装好的数据查询服务。这个服务由后端团队自己开发，内部通过DBHub连接PostgreSQL，对外只暴露有限的数据查询接口。

Dify的自定义工具节点可以配置OpenAPI schema，然后在工作流中以工具方式调用。这种方式把SQL完全藏在服务内部，Dify侧只看到有意义的输入输出字段。比如我封装了一个"查询订单状态"工具，输入是订单号，输出是订单状态和更新时间。工作流编排时，大模型只需从用户对话中抽取订单号，然后调用这个工具，不需要知道底层SQL长什么样。

这种做法的好处是很明显的：第一，数据库防护边界更清晰；第二，Dify侧的可观测性更好，因为工具调用的入参出参都是结构化数据；第三，后续如果业务库表结构变更，只需要改封装服务，不需要动Dify工作流。DBHub在这个链条里继续承担连接池和SQL转发的角色，整个链路是Dify工作流 -> 工具服务 -> DBHub -> PostgreSQL。

5. 实际运行中的踩坑记录与排查思路

5.1 连接超时：容器网络没走通

我在改造过程中遇到的第一个大坑是Dify容器连接DBHub网关超时。现象是Dify API服务启动失败，日志里报connection timeout。用psql从宿主机连DBHub是通的，但从Dify容器连就不行。

排查后发现，docker-compose里Dify服务默认的网络配置只能访问同栈内的容器，访问外部机器IP时需要在服务定义里显式声明网络模式或者确保宿主机IP路由可达。我最终的解决办法是在docker-compose.yaml中给API和Worker服务增加extra_hosts配置，把DBHub网关的hostname映射到宿主机可路由的内网IP。这样容器内通过hostname访问DBHub，比直接写死IP要灵活一些。

提醒一下：Dify容器内部不要使用localhost或127.0.0.1来访问外部的DBHub或PostgreSQL。localhost在容器里指向容器自身，不是宿主机。这个简单的认知错误会让很多人排查半天。

5.2 认证失败：scram-sha-256与连接串不匹配

还有一个典型的认证失败问题。现象是DBHub到PG的连接是好的，Dify到DBHub的密码也是对的，但Dify启动时一直报FATAL: password authentication failed。

查了半天发现，DBHub转发到上游PG时使用的账号密码是从数据源配置里读取的，而我这边DBHub的数据源配置中密码带了特殊字符，在大写字母转义后不一致。这个问题的根源是PostgreSQL密码包含特殊字符时，如果连接串是URL格式，需要用URL编码处理。比如密码中含有@符号，直接写在postgresql://user:pass@host/db里就会被解析器错误切分。

正确的做法是使用环境变量传密码，让驱动自动处理特殊字符，而不是手动拼URL。我改成环境变量注入方式之后，问题马上消失。

5.3 连接数打满：连接池参数调优

系统跑了一段时间后，某个业务高峰期出现PostgreSQL实例连接数飙升到上限，DBHub网关开始拒绝新的连接。排查后发现，Dify的多服务组件共享同一个DBHub接入账号，而DBHub对该账号默认维护的连接池上限是50。Dify的API服务在并发工作流场景下，单个工作流可能同时发起多个SQL请求，几个高并发任务直接就把连接池打满了。

解决方案有两个层面。一个是在DBHub侧调大该数据源的最大连接数，另一个是在Dify侧适当限制实际连接使用的并发度。我在DBHub中把连接池上限调到了150，同时让PG实例的max_connections至少保持在200以上，保证网关层预留缓冲。

需要平衡的是：连接池不是越大越好。每个连接在PG侧都会占用一块内存，如果DBHub把连接池调得过大而PG实例的max_connections没跟上，反而会在PG侧触发内存压力。调优的思路是"从下往上"：先把PG实例的总连接数上限确认好，再反推DBHub各数据源的连接池额度。

5.4 数据迁移：切换数据库时的注意点

最后说说数据迁移。如果你在本次改造之前，Dify已经在使用内置的SQLite或内置PostgreSQL，那么切换到外部PG之前需要做数据迁移。Dify自己的迁移工具会帮忙建表，但它不会把旧数据自动带过来。

我这次改造时，因为Dify平台本身还处于项目初始化阶段，没有需要保留的历史数据，所以直接切空了库。但如果你有历史数据，建议分两步走：先在维护窗口里停掉Dify写入，通过pg_dump导出旧库数据，再导入到新PG实例，最后再切换连接配置。两步之间最好做一个全量校验，对比表行数或者关键业务表的MAX(ID)，避免数据丢失。

6. 个人实操体会与扩展建议

我在整套方案落地后，最大的体会是：数据库连接网关这类中间件，表面上是多了一层转发，实际上是在帮你把"账号安全"和"连接治理"这两件事从业务代码里抽离出来。Dify这类低代码平台本身对数据库连接的管理能力比较有限，通过DBHub来弥补，是一个性价比很高的组合。

如果后续要继续扩展，我会建议往两个方向走。一个是在DBHub侧接入更多业务库数据源，把Dify的Agent工具统一建立在网关之上，让运维方对每个数据源的调用量都能被审计；另一个是给DBHub配置高可用模式，目前单节点部署虽然够用，但在Dify承载核心业务后，网关本身会成为单点，有条件的话还是建议搞一主一备。

最后分享一个小技巧：Dify切换数据库后，建议在管理后台重新生成一次加密密钥或者确认现有的密钥没有变化。有些团队会备份docker-compose和.env文件，但在迁移数据库后忽略了密钥的一致性。如果Dify的密钥和数据库里已有数据不匹配，会出现明明连接正常却无法解密历史数据的情况。这属于不踩不知道的坑，提前避开能省不少事。