Dify 接入 PostgreSQL：用 DBHub 统一管理数据库连接与排障实践

上个项目要做企业级知识库问答技术栈选型时定了 Dify PostgreSQL数据库连接管理统一走 DBHub。最初我图省事直接把 Dify 的 .env 改了两行就 docker compose up结果报错一堆一会儿提示数据库连接拒绝一会儿提示关系不存在折腾到半夜才发现问题不在代码层面而是连接参数配置和数据库本身的权限没对齐。后来把 DBHub 加入工作流先统一管理 PostgreSQL 连接、把账号权限和扩展都查清楚再让 Dify 去接整个过程顺畅了很多。这篇文章就把这次“Dify 使用 DBHub 连接 PG 数据库”的完整链路写出来包括配置方式、验证方法、常见坑和排查路径给后面要接同样组合的团队做个参考。这篇文章适合两类人一类是正在部署 Dify 但被数据库连接卡住的人另一类是已经把 Dify 跑起来、想搞清楚 PostgreSQL 在里面到底承担什么角色、怎么用可视化工具去维护它的人。不管你是运维还是后端开发看完基本能自己动手接一遍。1. 项目背景与整体设计思路1.1 Dify 为什么绕不开 PostgreSQLDify 是一个开源的大模型应用开发平台它本身不是一个单二进制程序而是一组服务的集合。默认部署方式里包含 web 前端、api 服务、worker 任务队列、数据库、缓存、向量数据库等组件。其中 PostgreSQL 承担的是业务数据存储的角色比如用户账号、应用配置、对话日志、数据集元数据、文档分段信息等全都落在 PostgreSQL 里。Redis 则承担缓存和消息队列的功能。很多人第一次部署 Dify 时以为数据库只是“可选项”装个 MySQL 或 SQLite 也能凑合实际上社区版默认就把 PostgreSQL 写死在编排文件里。即使你强行改配置把数据库换成别的也可能遇到 Dify 内部 SQL 语句与方言不兼容的问题。所以最稳妥、最省事的做法就是顺着官方默认走PostgreSQL 当业务库Redis 当缓存。至于知识库的向量检索Dify 支持多种向量数据库除了常用的独立向量库之外也能用 PostgreSQL 的 pgvector 扩展来存向量和做相似度检索。也就是说PostgreSQL 在 Dify 这套架构里是“一肩挑两职”的角色既要存常规业务数据也可能要承担向量存储。理解这一点之后你就明白了PostgreSQL 连接配置得对不对直接影响的不只是登录还包括知识库能不能正常创建和召回。1.2 DBHub 在连接链路中的定位DBHub 在项目里的角色不是 Dify 的依赖组件而是团队用来管理 PostgreSQL 连接的可视化工具。你可以把它理解成一个“连接管家”多个环境的数据库连接信息集中在里面想连哪台就切哪台连接参数、SSL 模式、权限情况一目了然。为什么不用命令行 psql 一把梭因为实际项目里数据库往往不止一套本地开发一套、测试环境一套、生产环境一套。每条连接串的 host、端口、用户名、密码、SSL 模式都可能不同全记在脑子里或者记在 Markdown 里早晚要出错。DBHub 这类工具把连接信息集中管理双击就能连接还能直接看表结构、跑 SQL、观察连接数排查问题的效率比纯命令行高不少。在这次项目里我们用 DBHub 主要做三件事第一在 Dify 配置改动之前先用 DBHub 测试 PostgreSQL 连接是否可用确认账号密码和网络没问题第二启动 Dify 之后用 DBHub 去检查 Dify 是否自动建好了表比如 users、apps、datasets 这些第三知识库场景下用 DBHub 确认 pgvector 扩展是否生效、向量字段是否写入成功。1.3 先分清两种“连接”场景项目里说“连接 PG 数据库”其实有两种完全不同的连接场景很多人一开始混在一起导致配置改来改去都不知道改的是谁的配置。第一种是 Dify 平台自身的数据库连接。也就是 Dify 的 api 服务和 worker 服务要连 PostgreSQL 来读写业务数据。这个配置通常在 .env 文件和 docker-compose.yaml 里变量名大概是 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_NAME 这一类。改完这类配置再重启容器影响的是 Dify 这个平台本身能不能用。第二种是知识库的向量存储连接。如果想让 Dify 的知识库功能把文档向量数据存进 PostgreSQL需要 PostgreSQL 开启 pgvector 扩展同时在 Dify 配置里指定向量存储类型为 pgvector并配上对应的数据库连接参数。这个连接跟平台自身的业务库连接可以指向同一个 PostgreSQL 实例也可以分开指向另一个实例。这两个场景的配置位置不一样报错信息也不一样。前者连接失败时Dify 登录页都打不开或者接口直接 500后者配置不对时平台能登录但创建知识库或上传文档后处理任务一直在队列里失败。我在第一次配置时就是把这两类连接变量混在一起改结果平台起来了知识库却一直报错还以为是 embedding 模型的问题后来一查才发现是向量库的连接信息压根没配。2. 连接前准备PostgreSQL 与 DBHub 配置2.1 PostgreSQL 选型与初始化先聊 PostgreSQL 版本。Dify 官方部署文件里默认用的 PostgreSQL 版本是 15 左右的老版本实际用 14、15、16 我都试过基本都能跑。如果你用的是云数据库尽量选和官方默认版本接近的避免因为大版本差异导致某些行为不一致。还有一个点容易被忽略字符集。建议初始化和创建数据库时强制使用 UTF8否则后续中文内容写入时可能出现编码问题。创建数据库账号时不建议直接用 postgres 超级用户。Dify 的迁移脚本会建表、建索引有时候还要建扩展所以账号至少要有目标库的 ALL PRIVILEGES。我习惯的做法是单独创建一个账号、一个专用库把库的 owner 直接给这个账号。初始化 SQL 大概是这样的CREATE USER dify_user WITH PASSWORD 这里填密码; CREATE DATABASE dify_db OWNER dify_user ENCODING UTF8; GRANT ALL PRIVILEGES ON DATABASE dify_db TO dify_user;如果你要启用 pgvector还需要登录到目标库执行CREATE EXTENSION IF NOT EXISTS vector;这个扩展是 PostgreSQL 的第三方扩展不是默认安装的。云数据库一般需要在控制台或者用超级用户执行一次本地 Docker 装的 PostgreSQL 镜像里不一定自带要确认一下。扩展没装成功的话后面 Dify 知识库跑起来会报找不到 vector 类型。2.2 DBHub 连接信息配置在 DBHub 里新建一个 PostgreSQL 连接需要填的字段包括主机地址、端口、数据库名、用户名、密码、SSL 模式。端口默认 5432如果本地起 Docker 改了映射端口要用实际映射的端口。填完之后先别急着去改 Dify先在 DBHub 里点一下“测试连接”或者直接连接成功确认这套连接参数是能用的。连接成功后我一般会顺手执行一条 SQL 确认数据库状态SELECT version(); SELECT current_database(), current_user;这样能看到 PostgreSQL 的版本号、当前连接的库名和用户排查问题时很有用。比如说你以为是连的 dify_db结果 current_database() 返回的是 postgres那后面 Dify 建表就全建到默认库里去了数据混乱。如果 DBHub 连接失败优先排查顺序是网络通不通ping 或 telnet 端口、端口是否映射正确、数据库账号密码是否正确、pg_hba.conf 认证规则是否允许当前来源 IP 访问、SSL 模式是否匹配。这里面最容易出问题的是 pg_hba.conf很多自建 PostgreSQL 默认只允许本地连接或者只允许特定网段Dify 容器从另一个网络段访问时会被拒绝。2.3 把连接参数映射到 Dify 配置当你确认 DBHub 里填的那套连接参数能成功连上 PostgreSQL 之后接下来就是把同样的参数映射到 Dify 的配置里。这里有一个关键认知DBHub 里的“连接名”只是 DBHub 自己的标识Dify 不认它Dify 只认实际的主机地址、端口、库名、用户名、密码。所以操作方法很简单在 DBHub 里打开你正在用的连接把里面的 Host、Port、Database、User、Password 逐一复制出来对应填到 Dify 的环境变量里。注意 Host 这一项如果 Dify 和 PostgreSQL 都在同一台机器的 Docker 里Dify 容器访问数据库时要填 Docker 网络内的服务名比如 db而不是 localhost 或 127.0.0.1。如果是外部数据库才填数据库服务器的实际 IP 或域名。这里还有个容易忽略的点Dify 自己的 .env 文件里有 POSTGRES_* 这样一组变量同时服务层面还有 DB_HOST、DB_PORT 这样一组变量。POSTGRES_* 一般是用来初始化 PostgreSQL 容器的比如给容器创建默认用户和库DB_HOST 这类才是 Dify 应用服务真正用来连接数据库的。如果你用的是外部库POSTGRES_* 改不改可能影响不大但 DB_* 必须指向外部库的正确地址。建议直接打开 docker-compose.yaml 搜一下 DB_HOST确认当前版本到底读哪一套变量再来改配置别想当然。3. 核心实操Dify 接入 PostgreSQL 全过程3.1 修改环境变量并启动服务假设你已经拿到了 Dify 的部署目录里面应该有 .env 文件。在改动之前先备份一份这个习惯救过我很多次。然后找到数据库相关配置核心变量大概是这样的DB_HOSTdb DB_PORT5432 DB_USERNAMEdify_user DB_PASSWORD这里填密码 DB_NAMEdify_db如果 PostgreSQL 是跑在 Docker Compose 里的同一个网络中DB_HOST 填 db 即可。如果 PostgreSQL 在外部服务器上DB_HOST 就填那台服务器的 IP 或域名同时确保端口能从 Dify 容器所在的主机访问到。改完之后执行docker compose up -d启动之后观察容器状态docker compose ps docker compose logs -f apiapi 容器是最先连接数据库的服务之一如果数据库连接配置有问题日志里会直接抛异常比如 password authentication failed、connection refused、database dify_db does not exist 这一类。出现这类报错不用慌回到 DBHub 里再验证一次连接参数确认无误再改 .env 重启。3.2 用 DBHub 验证 Dify 建表结果Dify 启动成功不等于数据库配置就完全没问题还有一个重要的验证步骤检查 Dify 是否在数据库里自动创建了业务表。如果账号权限不足或者迁移脚本没有执行Dify 可能启动不报错但一登录就会 500。在 DBHub 里刷新连接展开 dify_db 的 Schemas看看 public 下有没有生成 users、apps、datasets、conversations 这些表。如果一张表都没有大概率是数据库迁移没有执行。Dify 的 api 服务启动时会运行数据库迁移如果迁移失败了日志里会记录错误。常见原因是账号没有建表权限或者数据库字符集不匹配。这时候回到 PostgreSQL 里给账号补上权限GRANT ALL PRIVILEGES ON SCHEMA public TO dify_user; GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO dify_user; GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO dify_user; ALTER SCHEMA public OWNER TO dify_user;补完权限后再重启 api 容器等迁移跑完表就出来了。这个过程在 DBHub 里看起来特别直观你甚至开着实时刷新看着表一批批冒出来基本就能确认数据库这层通了。3.3 知识库场景启用 pgvector 并配置向量存储业务库通了之后如果你的项目还要用 Dify 的知识库功能那就得处理向量存储。这里我以 PostgreSQL pgvector 为例。先确保扩展已创建CREATE EXTENSION IF NOT EXISTS vector;然后在 Dify 的配置里设置向量数据库类型。不同版本的 Dify 配置入口不完全一样老版本可能在 .env 里直接有 VECTOR_STORE 变量填 pgvector新版本可能在管理后台的界面里选。具体找到你当前版本的部署文档看一眼就行核心是数据库连接变量要填对。VECTOR_STORE 方面常见变量类似VECTOR_STOREpgvector VECTOR_DB_HOSTdb VECTOR_DB_PORT5432 VECTOR_DB_USERdify_user VECTOR_DB_PASSWORD这里填密码 VECTOR_DB_NAMEdify_db注意这里填的库名可以和业务库是同一个。如果同一个库pgvector 会新建一些向量相关的表来存文档 embedding。如果分开就再建一个数据库给向量专用。配好之后去 Dify 后台创建一个知识库上传一份文档触发分段和索引。这时候回到 DBHub 里看会发现新增了一些数据集相关的表里面出现了 embedding 字段类型是 vector。数据写入成功的话向量检索基本就通了。如果表有了但没数据或者任务是失败状态优先看 worker 容器的日志和向量库连接配置是否一致。4. 常见问题排查与避坑实录4.1 连接失败原因速查表这几个月里我在 Dify 接 PostgreSQL 时遇到的问题基本都集中在下面这张表里以后你们遇到类似报错可以直接照着查。报错现象常见原因排查方法解决办法connection refused网络不通或端口错误DBHub 测试连接telnet 主机 5432检查防火墙、安全组、容器端口映射password authentication failed密码错误或认证方式不匹配DBHub 用同参数重试重置密码调整 pg_hba.conf 认证方式database xxx does not exist数据库名填错SELECT datname FROM pg_database;创建数据库或修改配置relation users does not existDify 迁移未执行DBHub 查看表列表检查 api 容器日志补权限后重启permission denied for schema public账号缺少 Schema 权限查看角色权限GRANT 权限或把库 owner 改为该账号扩展不存在 vectorpgvector 未安装SELECT * FROM pg_available_extensions;用超级用户执行 CREATE EXTENSION vectorSSL 握手失败SSL 模式不匹配DBHub 切换 SSL 模式测试在连接串中加 sslmodedisable 或 require连接数占满连接池配置过大SELECT count(*) FROM pg_stat_activity;调整 max_connections 和池大小4.2 版本与扩展相关的坑PostgreSQL 版本差异带来的坑最隐蔽。比如有些云数据库默认开启了强校验要求所有连接必须走 SSL而 Dify 容器里的连接驱动可能默认没带证书导致连接时直接握手失败。这种情况在本地很难复现因为本地 PostgreSQL 默认没开 SSL。解决办法很直接在连接串或者环境变量里把 sslmode 设为 disable前提是确认数据库服务端允许非 SSL 连接如果必须走 SSL那就得准备客户端证书或者用 require 模式。还有 pgvector 的版本问题。老版本的 pgvector 只支持固定维度的向量如果 Dify 里选的是某款 embedding 模型输出向量是 1536 维但表结构里向量字段声明的是 768 维写入时就会报维度不匹配。这类问题在 DBHub 里执行一条查看表结构的 SQL 就能发现。我之前就遇到过一次Dify 默认的 embedding 模型维度和我表里向量字段维度不一致导致知识库创建任务一直在失败队列里卡着当时完全没往维度上想。另一个和扩展相关的坑是在 PostgreSQL 里扩展是安装在某个数据库里的。你在 postgres 库里执行了 CREATE EXTENSION vector不代表 dify_db 里就有这个扩展。换到 dify_db 里执行一次 CREATE EXTENSION确认当前库下面能用。4.3 权限与账号配置坑权限问题是我反复踩的坑所以单独拿出来说。Dify 启动时不仅会连库还会执行数据库迁移迁移包含建表、建索引、建扩展等一系列操作。如果你给 Dify 的账号只有 SELECT / INSERT / UPDATE / DELETE 权限没有 CREATE 权限迁移脚本就会失败表现为api 启动时报权限错误或者启动成功但表没建出来。这也是为什么我前面强调最好直接给 Dify 专用账号做库的 owner。你要是非要给最小权限那也可以得在迁移之前把所有权限都配好包括 Schema 的 USAGE 和 CREATE 权限、表权限、序列权限。实际操作中最小权限配置非常繁琐一旦 Dify 后续升级要加新表你又得重新补一遍权限维护成本很高。在团队协作时还遇到过一种情况A 同学在本地创建了一个数据库B 同学用 DBHub 连的时候用的却是另一个库名两边信息没对齐结果 B 同学在 DBHub 里看到的是空白库Dify 启动后一直在报表不存在。后来我们把 DBHub 的连接信息统一同步到团队文档里每个环境的库名、账号、用途都写清楚这个问题就再没出现过。建议你们也这样做以 DBHub 的连接配置为唯一事实来源Dify 的 .env 配置跟它对齐不要各自记各自的。4.4 运维与性能注意事项Dify 跑起来之后数据库层面的运维也不能忽视。我习惯定期在 DBHub 里看连接数SELECT usename, application_name, count(*) FROM pg_stat_activity GROUP BY usename, application_name ORDER BY count(*) DESC;Dify 的 api 和 worker 服务会建立一定数量的连接池如果你把连接池大小调得太大而 PostgreSQL 的 max_connections 不够其他服务就连不上了。这时候要么调小连接池要么调大 max_connections注意不要超过服务器实际能承受的连接数。慢查询也要留意。Dify 在数据集和文档数量上来之后某些查询可能会变慢尤其是向量检索。如果发现知识库召回慢看看是不是没有给向量字段建索引。pgvector 支持 IVFFlat 和 HNSW 索引建好之后检索性能能提升不少。执行类似这样的建索引操作CREATE INDEX ON datasets_embedding USING hnsw (embedding vector_cosine_ops);注意索引类型和相似度算子要跟 Dify 用的检索方式匹配不然索引不会生效。这个在 DBHub 里能看到执行计划和索引使用情况比在黑盒子里跑要直观很多。5. 实操体会与备查建议这次把 Dify 和 PostgreSQL 接通的整个过程我最大的体会是大多数连接问题都不是“Dify 的问题”而是连接参数和数据库权限的问题。Dify 只是一个普通客户端它对数据库的要求跟其他应用没有本质区别。只要你在 DBHub 里能用一个账号连上数据库能执行查询、能建表、能创建扩展那 Dify 大概率也能连上。反过来DBHub 都连不上那 Dify 一定连不上这时候别去改 Dify 的配置先把数据库主机、端口、账号、权限查清楚。最后分享一个我后来固定下来的操作顺序也算是个人的标准化流程第一步在 DBHub 里新建连接把各个环境的数据库连接信息全部录入并测试连通性第二步用 DBHub 连接目标库执行 SQL 检查账号权限、数据库列表、扩展可用性第三步照着 DBHub 的连接参数去改 Dify 的 .env启动服务第四步回到 DBHub 验证 Dify 建表和向量数据写入情况。整套流程走下来连接问题基本都能在 DBHub 这层暴露出来Dify 那边只是最后消费结果的角色。如果后续要把这套方案推到生产环境建议提前考虑三点数据库账号密码不要写在明文配置里用环境变量管理或者密钥管理服务对 PostgreSQL 做主从或高可用时Dify 连接串里要配置正确的读写地址知识库数据量增长后提前规划向量索引和备份策略。这些内容单独展开又是一篇长文了今天先记到这里。