如何从多架构 Docker 镜像中导出指定的 ARM64 版本

以 quay.io/ascend/vllm-ascend:v0.22.1rc1-310p-openeuler 为例，手把手梳理从多架构镜像中精确导出 ARM64 镜像的完整命令。

背景

在部署昇腾（Ascend）等 ARM 架构服务器时，我们经常需要从公共镜像仓库拉取镜像。但很多官方镜像的 tag 其实是一个 多架构镜像（multi-arch image） ，同一个 tag 下同时打包了 amd64 和 arm64 两份独立的镜像。

如果直接用 docker pull <tag>，Docker 会自动匹配当前机器的架构下载对应版本。这在如下场景会出问题：

你想在 x86 开发机 上提前下载好 ARM 镜像，再拷贝到 ARM 服务器（离线部署）；
你需要明确导出某一个架构，而不是让 Docker 自动选择。

因此，关键在于：不要用 :tag 拉取，而要用架构对应的 @digest 精确拉取。

第一步：查看多架构清单（manifest list）

先用 docker manifest inspect 查看这个 tag 下有哪些架构：

bash 复制代码

docker manifest inspect quay.io/ascend/vllm-ascend:v0.22.1rc1-310p-openeuler

输出如下：

json 复制代码

{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 3468,
         "digest": "sha256:495204ae773849d88204f94344af907dc389397f488126054f8157a7c5cddbd2",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 3468,
         "digest": "sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8",
         "platform": {
            "architecture": "arm64",
            "os": "linux"
         }
      }
   ]
}

从 platform.architecture 字段可以清楚看到：

架构	digest
amd64	`sha256:495204ae773849d88204f94344af907dc389397f488126054f8157a7c5cddbd2`
arm64	`sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8`

我们要导出的就是 arm64 那一份，对应 digest：

复制代码

sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8

方案一：使用 Docker（最通用）

1. 按 digest 拉取 arm64 版本

注意用 @sha256:... 而不是 :tag：

bash 复制代码

docker pull quay.io/ascend/vllm-ascend@sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8

⚠️ 在 x86 机器上拉取时的注意事项

显式指定 digest 时，Docker 通常能拉下 arm64 的层。但部分旧版本 Docker 会报架构不匹配，此时补上 --platform 参数：

bash 复制代码

docker pull --platform linux/arm64 quay.io/ascend/vllm-ascend@sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8

2. （可选）重新打一个好记的 tag

digest 太长不好记，可以重新打个 tag：

bash 复制代码

docker tag quay.io/ascend/vllm-ascend@sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8 vllm-ascend:v0.22.1rc1-310p-arm64

3. 导出为 tar 包

bash 复制代码

docker save -o vllm-ascend-v0.22.1rc1-310p-arm64.tar quay.io/ascend/vllm-ascend@sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8

如果第 2 步已经打了 tag，也可以直接用 tag 导出（更直观）：

bash 复制代码

docker save -o vllm-ascend-arm64.tar vllm-ascend:v0.22.1rc1-310p-arm64

方案二：使用 skopeo（跨架构导出最省心，强烈推荐）

skopeo 的最大优势是不依赖本机架构，可以在 x86 机器上直接把 arm64 镜像复制成 tar / OCI 目录，特别适合「开发机下载 → 拷贝到 ARM 服务器 → 导入」的离线部署场景。

bash 复制代码

skopeo copy --override-arch arm64 --override-os linux docker://quay.io/ascend/vllm-ascend@sha256:8ec0c8ab8b8748632d432bd4b4f2aeb111683332593d33df0e20c545d201c1f8 docker-archive:vllm-ascend-v0.22.1rc1-310p-arm64.tar:vllm-ascend:v0.22.1rc1-310p-arm64

参数说明：

--override-arch arm64 --override-os linux：强制指定目标架构和系统，不受本机影响；
docker://...@sha256:...：源镜像，用 digest 精确定位 arm64；
docker-archive:文件名.tar:仓库名:标签：输出为可被 docker load 加载的 tar 包。

在目标 ARM 机器上导入

无论方案一还是方案二导出的 tar，导入方式一致：

bash 复制代码

# 导入镜像
docker load -i vllm-ascend-v0.22.1rc1-310p-arm64.tar

# 确认导入成功
docker images

命令速查表

步骤	Docker	skopeo
查看架构清单	`docker manifest inspect <tag>`	`skopeo inspect --raw docker://<tag>`
拉取指定架构	`docker pull <repo>@sha256:8ec0...`（必要时加 `--platform linux/arm64`）	`skopeo copy --override-arch arm64 ...`
导出 tar	`docker save -o xxx.tar`	输出目标写 `docker-archive:xxx.tar:repo:tag`
导入	`docker load -i xxx.tar`	同左

核心要点

多架构镜像的 tag 是一个 manifest list ，直接 pull tag 会按本机架构自动选择；
认准架构对应的 digest ，用 @digest 而非 :tag 拉取，才能确保拿到 ARM 版本；
跨架构准备镜像（x86 上下载 ARM 镜像）时，优先用 skopeo，避免本机架构干扰；
导出后用 docker load -i 在目标机器导入即可。

本文以 vllm-ascend 昇腾镜像为例，同样的思路适用于任何多架构 Docker 镜像的架构精确导出。