PostgreSQL环境下Dify数据库迁移安全指南

必须严格按三步迁移Dify的PostgreSQL：先确认源库≥13版本，再用pg_dump --no-owner --no-privileges -Fc导出，最后记录并同步时区；导入前需校验表完整性、启用uuid-ossp扩展、核对users和documents数量；迁移后须chown -R 999:999修复目录权限，并用SQLAlchemy脚本验证连接。

将Dify的PostgreSQL数据库从一台服务器迁移到另一台，必须确保元数据、用户权限、时区设置、UUID主键完整性全部准确复现，否则会出现账号丢失、知识库不可用、API报500错误等严重问题。

迁移前必须做的三件事

第一步：确认源库 PostgreSQL 版本 ≥ 13，低于该版本会导致 pg_dump 兼容性异常，导出的 schema 可能缺失 GENERATED ALWAYS AS IDENTITY 字段定义。

第二步：在源库执行 【pg_dump --no-owner --no-privileges -Fc -f backup.dump dify】，强制使用自定义格式（-Fc）并剥离所有权与权限信息——这是避免目标库因用户ID不匹配而启动失败的关键动作。

第三步：检查并记录源库的时区配置：【show timezone;】，迁移后目标库必须设为完全相同的值（如 'Asia/Shanghai'），否则 created_at 等时间字段会偏移8小时，RAG检索结果按时间排序将彻底错乱。

迁移中两个不可跳过的校验点

方法一：用 pg_restore -l 预览 dump 文件内容，确认包含所有关键表（documents、applications、users、tenant_settings），若缺失 tenant_settings 表，整个租户体系将无法初始化。

方法二：导入前在目标库执行 【CREATE EXTENSION IF NOT EXISTS "uuid-ossp";】，Dify 的 UUID 主键依赖此扩展生成，未启用会导致 INSERT 失败并卡死迁移流程。

方法三：导入完成后立即运行 【SELECT COUNT(*) FROM users;】 和 【SELECT COUNT(*) FROM documents WHERE status = 'active';】，数值必须与源库完全一致；差1条都说明 WAL 日志未同步完或事务被中断。

迁移后必须修复的权限陷阱

PostgreSQL 容器内以 UID=999 的 postgres 用户运行，但宿主机挂载的 volumes/db/data 目录若属主是 root，容器将拒绝启动并报 FATAL: data directory has invalid permissions。

执行 【chown -R 999:999 ./volumes/db/data】，注意必须是 999 而非 1001 或其他数字——这是 Dify 官方 PostgreSQL 镜像硬编码的 UID，改错会导致数据库服务永远无法拉起。

这一步操作起来很简单，直接在新服务器 volumes 目录下运行 chown 命令即可，但漏掉就会卡在 docker-compose up 的第一秒。

验证连接是否真正生效

进入 dify-api 容器内部：【docker exec -it dify-api bash】。

执行 Python 连接测试脚本：

python3 -c "from sqlalchemy import create_engine; e = create_engine('postgresql://postgres:YOUR_PASS@db_postgres:5432/dify'); c = e.connect(); print(c.execute('SELECT version()').fetchone()); c.close()"。

输出必须包含 PostgreSQL 字样且无异常堆栈；若报 OperationalError: (psycopg2.OperationalError) could not translate host name "db_postgres"，说明 docker-compose.yaml 中 service 名称与环境变量 SQLALCHEMY_DATABASE_URI 里的 host 不一致。