必须严格按三步迁移Dify的PostgreSQL：先确认源库≥13版本，再用pg_dump --no-owner --no-privileges -Fc导出，最后记录并同步时区；导入前需校验表完整性、启用uuid-ossp扩展、核对users和documents数量；迁移后须chown -R 999:999修复目录权限，并用SQLAlchemy脚本验证连接。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
将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 不一致。
