Dify正常运行必须完成PostgreSQL初始化与连接配置：先启动服务并创建专用数据库及用户；Docker部署时需在docker-compose.yml中正确配置DB_HOST=postgres等环境变量；沙盒环境还需添加psycopg2驱动、开放网络权限并用宿主机IP连接。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要让Dify正常启动并持久化存储用户、应用、知识库等关键数据，必须完成PostgreSQL数据库的初始化与连接配置，否则系统将无法写入结构化数据，控制台登录后立即报错或空白。
初始化PostgreSQL服务（非容器环境）
确保PostgreSQL已安装并运行：执行sudo systemctl status postgresql，若显示inactive，则需先启动服务。未启动时Dify所有数据库操作都会失败，且错误日志中仅提示“connection refused”，不会说明是服务未运行。
切换至postgres系统用户并进入psql命令行：sudo -u postgres psql。
为Dify创建专用数据库与用户：执行CREATE DATABASE dify; CREATE USER dify_user WITH PASSWORD 'dify1234'; GRANT ALL PRIVILEGES ON DATABASE dify TO dify_user;。这一步不可跳过——直接用postgres超级用户连接Dify存在严重安全风险，且Dify 1.0.0版本默认拒绝超级用户登录。
退出psql：\q。
Dify服务端连接PostgreSQL配置（Docker Compose部署）
编辑docker-compose.yml文件，在dify-api服务的environment区块中添加以下四行：
DB_HOST=postgres
DB_PORT=5432
DB_NAME=dify
DB_USER=dify_user
DB_PASSWORD=dify1234
【DB_HOST必须填postgres，不能填localhost】——Docker容器内localhost指向自身，而PostgreSQL运行在另一个同网络的容器中；若填错，Dify启动后日志持续刷出“Connection refused”，但前端无任何提示。
确认postgres服务块已正确定义，且与dify-api处于同一自定义网络（如dify-net）。网络不一致会导致DNS解析失败，容器间完全不通。
Dify沙盒环境连接外部PostgreSQL（NL2SQL等场景）
方法一：修改沙盒依赖清单
在volumes/sandbox/dependencies/python-requirements.txt末尾追加：psycopg2-binary==2.9.10。Dify 1.0.0沙盒默认不包含PostgreSQL驱动，不添加此行会导致<font color="red>ModuleNotFoundError: No module named 'psycopg2'。
方法二：开放网络权限
编辑沙盒配置文件config.yaml，找到network字段，将值从none改为default。否则即使装了驱动，也会卡在Operation not permitted系统调用拦截上。
方法三：代码中显式连接（Python沙盒脚本内）
① 导入模块：import psycopg2
② 构建连接：conn = psycopg2.connect(host="192.168.1.100", port=5432, database="sales_data", user="dify_admin", password="dify1234")
③ 执行查询：cur = conn.cursor(); cur.execute("SELECT * FROM customers LIMIT 5"); print(cur.fetchall())
注意：host必须填宿主机或远程服务器真实IP，不能填postgres或localhost——沙盒进程不在Docker网络命名空间内。
