Dify 平台从 x86_64 迁移至 ARM64 架构完整指南

以下为自己摸索的教程，使用GLM4.6进行文本润色

此教程并非内网迁移。如果内网迁移，需要重新构建plugin_daemon 整个image 并完整迁移，如果仅数据会导致容器内python环境的软连接丢失！！！

Dify 平台从 x86_64 迁移至 ARM64 架构完整指南

概述

本文档旨在提供一套完整、可靠的流程，用于将 Dify AI 应用开发平台从基于 x86_64 架构的服务器迁移至基于 ARM64 (aarch64) 架构的服务器。迁移过程涉及数据打包、镜像替换、插件数据清理及关键配置优化等环节。

注意事项：

• 本指南基于 Docker Compose 部署的 Dify 环境。
• 操作前请务必备份所有重要数据，并建议在测试环境中先行验证。
• 迁移过程会导致服务中断，请规划好停机窗口。

---

第一阶段：源机器（x86_64）准备工作

此阶段的目标是完整、无损地打包 Dify 的所有核心数据和配置。

1.1 停止 Dify 服务

在打包前，确保所有 Dify 相关容器均已停止，以保证数据一致性。

# 进入您的 dify 项目目录
cd /path/to/your/dify# 停止所有服务
docker-compose down

1.2 打包 Dify 目录

如无其他要求 务必打包整个dify目录 不要只打包volumes！！！

这是整个迁移过程中最关键的一步。务必使用 tar 命令进行打包，切勿使用 zip 或其他压缩工具。tar 能够更好地保留 Linux 文件系统的所有属性，包括权限、所有者、符号链接和特殊文件，这对于 Docker 环境的顺利迁移至关重要！！！！

# 确保您仍在 dify 项目根目录下
# 将整个 dify 目录打包为 dify-migration.tar.gz
tar czvf dify-migration.tar.gz .

⚠️ 重要提示：

• 绝对不要使用 zip 命令。使用 zip 可能导致文件权限或链接丢失，从而在新机器上引发不可预知的问题。
• dify-migration.tar.gz 文件将包含您的代码、配置文件（.env）、数据库文件、存储卷等所有内容。

1.3 传输打包文件

使用 scp、rsync 或其他安全文件传输工具，将打包好的文件传输到目标 ARM64 服务器上。

# 示例：使用 scp 传输文件
scp dify-migration.tar.gz user@target-arm64-server:/path/to/destination/

---

第二阶段：目标机器（ARM64）部署与配置

此阶段的目标是在新的 ARM64 服务器上解压部署，并进行针对性的适配和优化。

2.1 解压并准备环境

1. 登录到目标 ARM64 服务器。
2. 创建一个新的部署目录，并将传输过来的压缩包解压至此。

# 创建部署目录
mkdir -p /opt/dify-arm64
cd /opt/dify-arm64# 解压迁移文件（注意 --strip-components=1 用于去除顶层目录）
tar xzvf /path/to/destination/dify-migration.tar.gz --strip-components=1

2.2 修改 Nginx 镜像配置

ARM64 架构需要使用专门的镜像。在解压后的 docker-compose.yml 文件中，找到 nginx 服务，并将其 image 修改为 ARM64 版本。

# docker-compose.ymlservices:# ... other servicesnginx:# 原始配置可能是：image: nginx:latest# 修改为以下内容image: arm64v8/nginx:latest# ... rest of the nginx configuration# ... other services

2.3 清理插件数据（关键步骤）！！！

一定要清理，否则会导致空指针错误

为确保插件在 ARM64 环境下能正常重新安装和运行，必须彻底清理从 x86_64 环境迁移过来的旧插件数据和二进制文件。

步骤一：清除数据库中的插件记录

连接到 Dify 的 PostgreSQL 数据库，并执行以下 SQL 命令，删除所有与插件相关的数据。

-- 连接到 dify_plugin 数据库后执行
DELETE FROM plugin_installations WHERE plugin_unique_identifier IS NOT NULL;
DELETE FROM plugin_declarations WHERE plugin_unique_identifier IS NOT NULL;
DELETE FROM ai_model_installations WHERE plugin_unique_identifier IS NOT NULL;
DELETE FROM plugins WHERE plugin_unique_identifier IS NOT NULL;

步骤二：清除插件目录文件

执行以下命令，删除宿主机上与插件相关的目录内容。这会移除所有缓存的插件文件、工作目录和持久化数据。

# 确保您在 dify 项目目录下
# 注意：请根据您的实际部署路径调整 /app/storage 前缀
# 如果您的 docker-compose.yml 中挂载了 ./storage 到 /app/storage，则路径应为 ./storage/cwd/plugins/...
rm -rf ./storage/cwd/plugins/plugin/*
rm -rf ./storage/cwd/plugins/plugin-working/*
rm -rf ./storage/cwd/plugins/persistence/*
rm -rf ./storage/cwd/plugins/plugin-root/*

💡 提示： 执行此操作后，插件环境将是完全干净的，您需要在服务启动后，在 Dify 的管理界面中重新安装和配置所有插件。

---

第三阶段：优化配置与启动服务

在 ARM64 环境下，特别是插件环境的初始化速度可能有所不同。同时，为了在国内获得更好的依赖下载速度，建议进行以下配置优化。

3.1 修改 .env 文件

编辑部署目录下的 .env 文件，调整插件相关配置。
如果不修改大概率无法初始化环境，原因众所周知！

# .env# 找到以下几行配置
# 原配置
PLUGIN_PYTHON_ENV_INIT_TIMEOUT=120
PLUGIN_MAX_EXECUTION_TIMEOUT=600
PIP_MIRROR_URL=# 修改为
PLUGIN_PYTHON_ENV_INIT_TIMEOUT=600
PLUGIN_MAX_EXECUTION_TIMEOUT=1200
PIP_MIRROR_URL=https://mirrors.aliyun.com/pypi/simple/

配置说明：

• PLUGIN_PYTHON_ENV_INIT_TIMEOUT：将插件 Python 环境初始化超时时间从 120 秒增加到 600 秒，为 ARM64 环境下可能较慢的依赖安装预留充足时间。
• PLUGIN_MAX_EXECUTION_TIMEOUT：将插件最大执行超时时间适当延长，以应对复杂任务。
• PIP_MIRROR_URL：设置为中国大陆的 PyPI 镜像源（本例为阿里云镜像），可大幅提升 Python 包下载速度，避免因网络问题导致的安装失败。

3.2 启动 Dify 服务

所有配置完成后，即可启动服务。

# 在 dify 项目目录下执行
docker-compose up -d

3.3 验证与后续操作

1. 使用 docker-compose ps -a 检查所有容器是否正常启动。
2. 访问 Dify 的 Web 界面，确认核心功能（如应用、数据集、知识库等）是否正常。
3. 登录管理员账户，进入“插件”管理页面，重新安装您需要的插件并配置相应的 API 密钥。

---

总结

通过遵循以上三个阶段的操作，您可以成功将 Dify 平台从 x86_64 架构迁移至 ARM64 架构。核心要点可概括为：

1. 打包方式： 坚持使用 tar 进行数据打包。
2. 镜像适配： 确保关键服务镜像（如 Nginx）兼容 ARM64。
3. 插件清理： 迁移后务必彻底清理旧的插件数据和文件，这是保证插件功能正常的关键。
4. 配置优化： 增加插件超时时间并配置国内镜像源，以提升部署成功率和运行稳定性。

祝您迁移顺利！