Dify 内网无外网服务器 完整迁移避坑手册（Ubuntu 专用）

Dify 内网无外网服务器 完整迁移避坑手册（Ubuntu 专用）

适用：无外网服务器、DNS异常、无法拉取Docker镜像、跨服务器完整数据迁移
版本：Dify 1.11.4 Ubuntu 系统

一、核心避坑总原则

1. 内网环境绝对不要配置阿里云/USTC等Docker镜像加速，大量403、解析失败，越改越故障
2. 禁止联网拉取任何镜像，全程老机导出→新机离线导入
3. 严禁随意修改 docker-compose.yaml 数据库服务名称，极易重复Key报错
4. PostgreSQL数据库默认带profile，不加参数不会自动启动
5. 直接root复制volumes目录一定会权限错乱，导致500/数据库连接失败
6. API、Web镜像版本必须严格一致，不可混用高低版本

二、完整离线迁移标准流程

1. 老服务器：打包全部Dify镜像

cd /home/kamo/dify/docker

一键导出全套必备镜像

docker save \
langgenius/dify-web:1.11.4 \
langgenius/dify-api:1.11.4 \
langgenius/dify-plugin-daemon:0.5.2-local \
langgenius/dify-sandbox:0.2.12 \
postgres:15-alpine \
redis:6-alpine \
ubuntu/squid:latest \
busybox:latest \
nginx:latest \
-o dify-all-images.tar

传输镜像包到新服务器

scp dify-all-images.tar root@192.168.4.198:/root/

2. 新服务器：离线导入镜像

docker load -i /root/dify-all-images.tar

3. 修改yaml禁止自动联网拉取

编辑 docker-compose.yaml

pull_policy: never

不要使用 always / if_not_present

4. 迁移volumes完整数据目录

直接打包老机整个volumes文件夹，全覆盖新机对应目录
迁移后执行权限修复

chmod -R 777 ./volumes
chown -R 1001:1001 ./volumes/app/storage

5. 正确启动Dify（必带数据库配置）

docker-compose --profile postgresql up -d

三、本次全部故障报错+一键解决方案

1. 镜像拉取超时 dial tcp i/o timeout

• 原因：内网无法访问外网Docker仓库
• 解决：全程离线镜像迁移，不使用任何公网镜像源

2. lookup xxx no such host DNS解析失败

• 原因：内网DNS异常，无法解析公网域名
• 解决：放弃修改DNS，直接离线导入镜像

3. yaml: mapping key “redis” already defined

• 原因：误将postgres数据库命名为redis，服务重复冲突
• 规范命名：
  • 主数据库：db_postgres
  • 缓存数据库：redis
  • 两者严禁同名

4. could not translate host name “db_postgres”

• 原因：Postgres未启动，profile默认不加载
• 解决：启动必须携带 --profile postgresql

5. 页面访问 502 Bad Gateway

• 原因：API正常，但无法连接数据库，Nginx无后端服务
• 排查顺序：数据库容器状态 → .env地址匹配yaml → volumes权限

6. /console/api/setup 500 内部服务器错误

• 原因：数据目录权限异常，数据库无法读写
• 修复命令

docker-compose down
chmod -R 777 volumes
docker-compose --profile postgresql up -d

7. plugin_daemon 无限重启 Restarting

• 插件非核心业务服务，异常不影响前台登录、应用、知识库正常使用

四、迁移成功校验标准

1. docker-compose ps 核心容器全部UP
   web、api、redis、nginx、sandbox、ssrf_proxy、worker、worker_beat
2. postgres数据库健康正常运行
3. 浏览器IP可正常打开登录界面
4. 原有账号、应用、知识库、对话历史100%完整保留

五、内网迁移绝对禁忌

1. 不随意改动docker-compose数据库服务名称
2. 内网服务器不折腾各类Docker加速源
3. 不删除原有volumes新建初始化Dify
4. 不混用不同版本API/Web镜像
5. 不直接用root覆盖数据目录文件

六、新机永久稳定一键启动命令

cd ~/dify/docker
docker-compose --profile postgresql up -d
docker-compose restart api web nginx