跨架构突围！X86 Ubuntu Dify 无缝迁移 Arm64 openEuler Docker 实战指南

本文聚焦从 X86 架构 Ubuntu 系统迁移 Dify 到 Arm64（鲲鹏）架构 openEuler 系统的 Docker 环境，基于本地源码重构 web/api/worker 核心镜像，解决架构适配、海外源超时、依赖版本兼容等核心问题，全程使用国内源加速，确保迁移落地可执行。

一、迁移前置准备（必做）

1. 配置 Docker 国内加速 + Arm64 默认架构

python 复制代码

# 备份原有Docker配置
sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.bak

python 复制代码

# 写入多源加速配置（覆盖Docker Hub所有镜像，适配Arm64）
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://mirror.aliyuncs.com",
    "https://hub-mirror.c.163.com",
    "https://ccr.ccs.tencentyun.com"
  ],
  "experimental": true,
  "features": {"buildkit": true},
  "default-platform": "linux/arm64"
}
EOF

python 复制代码

# 重启Docker使配置生效
sudo systemctl daemon-reload && sudo systemctl restart docker

python 复制代码

# 清理旧镜像/缓存（避免校验bug干扰）
sudo docker system prune -af

python 复制代码

# 安装Docker Compose插件（openEuler适配版）
sudo dnf install -y docker-compose-plugin

python 复制代码

# 验证Compose版本（确保安装成功）
sudo docker compose version

2. 准备 Dify 本地源码

python 复制代码

# 进入Dify源码根目录（替换为你的实际路径）
cd /home/huawei/dify20251101

python 复制代码

# 切换到稳定版本（避开新版兼容性坑，如v0.6.10）
git checkout v0.6.10

python 复制代码

# 确认源码结构（需包含web/、api/、docker/核心目录）
ls -l

二、核心配置改造（解决架构 / 源 / 版本问题）

1. 改造 docker-compose.yaml（适配旧版 Compose+Arm64）

python 复制代码

# 进入docker子目录
cd docker

python 复制代码

# 备份原有配置（部署型配置无构建逻辑）
sudo mv docker-compose.yaml docker-compose.yaml.bak

python 复制代码

# 下载官方带构建逻辑的模板（支持本地源码构建）
wget https://raw.githubusercontent.com/langgenius/dify/main/docker/docker-compose.yaml -O docker-compose.yaml

python 复制代码

# 编辑模板，删除不兼容字段（旧版Compose不支持platform）
sudo nano docker-compose.yaml

关键修改 ：删除所有services.web/build、services.api/build、services.worker/build下的platform: linux/arm64行，修正后核心片段：

python 复制代码

web:
  build:
    context: ../web
    args:
      NPM_REGISTRY: ${NPM_REGISTRY:-https://registry.npmjs.org}

python 复制代码

api:
  build:
    context: ../api
    args:
      PIP_INDEX_URL: ${PIP_INDEX_URL:-https://pypi.org/simple}

python 复制代码

worker:
  build:
    context: ../api
    args:
      PIP_INDEX_URL: ${PIP_INDEX_URL:-https://pypi.org/simple}

2. 改造 web 模块 Dockerfile（Node 源 + 版本 + Apk 源）

python 复制代码

# 进入web源码目录
cd ../web

python 复制代码

# 编辑Dockerfile
sudo nano Dockerfile

核心修改：

python 复制代码

# 替换Node基础镜像（避开20-alpine Arm64校验bug）
FROM node:18-alpine AS base

python 复制代码

# 替换Alpine Apk源为阿里云（解决tzdata安装失败）
RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories

python 复制代码

# 保留tzdata安装命令（依赖时区配置）
RUN apk add --no-cache tzdata

python 复制代码

# 保留pnpm安装命令（前端包管理工具）
RUN npm install -g pnpm@9.12.2

3. 改造 api 模块 Dockerfile（Python 源 + 版本 + Poetry 源）

python 复制代码

# 进入api源码目录
cd ../api

python 复制代码

# 编辑Dockerfile
sudo nano Dockerfile

核心修改：

python 复制代码

# 替换Python基础镜像（避开3.12-slim-bookworm Arm64校验bug）
FROM python:3.11-slim-bookworm AS base

python 复制代码

# 升级pip+安装Poetry（使用清华源加速）
RUN pip install --upgrade pip setuptools wheel \
    && pip install poetry==1.8.3 -i https://pypi.tuna.tsinghua.edu.cn/simple

python 复制代码

# 配置Poetry国内源（核心：不继承pip源，需单独配置）
RUN poetry config repositories.tsinghua https://pypi.tuna.tsinghua.edu.cn/simple \
    && poetry config default-source tsinghua \
    && poetry config installer.max-workers 20

4. 修复 api 模块依赖版本（解决 yanked 包问题）

python 复制代码

# 编辑pyproject.toml
sudo nano pyproject.toml

替换被官方撤回的包版本：

python 复制代码

# 原aiohttp = "3.11.14" 替换为稳定版
aiohttp = "3.10.10"

python 复制代码

# 原pypdfium2 = "4.30.1" 替换为稳定版
pypdfium2 = "4.29.0"

python 复制代码

# 新增kaleido稳定版本（解决安装超时/失败）
kaleido = "0.2.1"

python 复制代码

# 生成新的poetry.lock（适配国内源+稳定版本）
sudo poetry lock --no-update

5. 预下载 kaleido（可选，解决 Arm64 下载超时）

python 复制代码

# 下载Arm64版本kaleido包到api目录
wget https://pypi.tuna.tsinghua.edu.cn/packages/24/79/790718124e1eb7a6241339e9514f399956a5f4956945057f0381999a90320/kaleido-0.2.1-py2.py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl -O kaleido-0.2.1.whl

python 复制代码

# 编辑api/Dockerfile，添加本地安装步骤
sudo nano Dockerfile

python 复制代码

# 在Poetry配置后新增本地安装kaleido
COPY kaleido-0.2.1.whl /tmp/
RUN pip install /tmp/kaleido-0.2.1.whl -i https://pypi.tuna.tsinghua.edu.cn/simple

三、本地源码构建全量镜像（核心命令）

1. 全量构建命令（单行可直接复制）

python 复制代码

sudo DOCKER_DEFAULT_PLATFORM=linux/arm64 docker compose --progress=plain -f docker-compose.yaml build --no-cache --build-arg NPM_REGISTRY=https://registry.npmmirror.com --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

2. 分模块构建兜底（单模块失败时使用）

python 复制代码

# 单独构建web镜像
sudo docker build --platform linux/arm64 --no-cache --build-arg NPM_REGISTRY=https://registry.npmmirror.com -t langgenius/dify-web:latest ../web

python 复制代码

# 单独构建api镜像
sudo docker build --platform linux/arm64 --no-cache --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple -t langgenius/dify-api:latest ../api

python 复制代码

# 单独构建worker镜像
sudo docker build --platform linux/arm64 --no-cache --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple -t langgenius/dify-worker:latest ../api

四、服务启动与验证

python 复制代码

# 启动Dify所有服务
sudo docker compose -f docker-compose.yaml up -d

python 复制代码

# 查看构建的Arm64镜像
sudo docker images | grep langgenius/dify

python 复制代码

# 查看服务运行状态（所有服务显示Up即成功）
sudo docker compose -f docker-compose.yaml ps

访问验证 ：浏览器打开 http://你的openEuler服务器IP:3000，进入 Dify 控制台即迁移成功。

五、全流程核心注意事项

1. 架构适配

所有构建命令必须指定linux/arm64，否则会生成 X86 镜像导致运行失败；
openEuler 鲲鹏版通过DOCKER_DEFAULT_PLATFORM全局指定架构，替代 Compose 的platform字段（旧版 Compose 不兼容）。

2. 国内源替换（核心）

NPM：registry.npmmirror.com 替代官方源；
PyPI：pypi.tuna.tsinghua.edu.cn/simple 替代官方源；
Alpine Apk：mirrors.aliyun.com 替代dl-cdn.alpinelinux.org；
Poetry：需单独配置源（不继承 pip 源），否则仍会访问海外源。

3. 版本避坑

Node：避开20-alpine（Arm64 校验 bug），使用18-alpine；
Python：避开3.12-slim-bookworm（Arm64 校验 bug），使用3.11-slim-bookworm；
依赖包：替换被撤回的aiohttp/pypdfium2版本，指定kaleido稳定版。

4. 构建耗时

Arm64 架构下 api/worker 镜像构建耗时 30-60 分钟（Python 依赖多），web 镜像 5-10 分钟，切勿中断进程。

5. 权限问题

所有 Docker 命令加sudo，或执行sudo usermod -aG docker $USER && newgrp docker配置免 sudo（需重新登录生效）。

6. 日志排查

构建时加--progress=plain输出详细日志，定位依赖下载 / 安装失败问题；
若 Poetry 安装超时，可替换为pip install -r requirements.txt绕过 Poetry（需先执行poetry export -f requirements.txt --output requirements.txt --without-hashes）。