给不同设备部署 Docker 时，经常会遇到 CPU 架构不一致的问题：电脑使用 Intel 或 AMD 处理器，目标 NAS 却是 ARM64；手里的开发板也可能还是 32 位 ARM。今天分享一个 GitHub 开源项目 DockerTarBuilder，它可以通过 GitHub Actions 下载指定 CPU 架构的公开 Docker 镜像，并打包成可以离线导入的 tar.gz 文件。

项目地址：https://github.com/wukongdaily/DockerTarBuilder

---

一、DockerTarBuilder 是什么？

DockerTarBuilder 是一组已经写好的 GitHub Actions 工作流。使用者不需要准备云服务器，也不需要在电脑上执行构建脚本，只要填写镜像名称并选择目标架构，GitHub 的服务器就会拉取对应平台的镜像并完成打包。

它的处理流程可以概括为：

输入镜像名称和标签
        |
        v
选择 AMD64、ARM64 或 ARM32
        |
        v
GitHub Actions 按目标平台拉取镜像
        |
        v
导出并压缩为 tar.gz
        |
        v
下载后使用 docker load 导入

项目名称虽然带有 Builder，但它并不是读取 Dockerfile 编译新镜像。工作流实际执行的是 docker pull、docker save 和 gzip 压缩。

所以更准确地说，它是一个“按 CPU 架构下载公开 Docker 镜像并离线打包的工具”。它不会把 AMD64 镜像转换成 ARM64，而是下载镜像作者已经发布的目标平台版本。

---

二、主要用于什么场景？

1. 为不同 CPU 架构下载 Docker 镜像

这是 DockerTarBuilder 最主要的使用场景。

很多 Docker 镜像使用同一个名称和标签同时发布多个平台版本。例如 alpine:latest 可能同时包含 AMD64、ARM64 和 ARM32，但不同平台对应的镜像层并不相同。

当前操作环境	最终运行设备	需要下载的平台
Intel、AMD 电脑	ARM64 NAS、开发板	linux/arm64
Intel、AMD 电脑	32 位 ARM 设备	linux/arm/v7
ARM64 电脑或服务器	x86-64 服务器	linux/amd64

使用 DockerTarBuilder 后，当前电脑是什么架构并不决定下载结果，真正决定结果的是用户选择的工作流。

2. 同时为多种设备准备镜像

同一个应用需要部署到 x86-64 服务器、ARM64 NAS 和 ARM32 开发板时，可以分别运行三个架构的工作流，得到独立的镜像文件：

image_latest-amd64.tar.gz
image_latest-arm64.tar.gz
image_latest-arm32.tar.gz

文件名带有架构后缀，归档和分发时不容易混淆。

3. 给离线设备准备镜像

内网服务器、实验环境或无法直接访问镜像仓库的 NAS，可以先下载正确架构的 tar.gz，再通过局域网、移动硬盘或文件服务传到目标设备。

4. 目标设备拉取镜像较慢

目标设备能够运行 Docker，但访问 Docker Hub 或 GHCR 不稳定时，可以让 GitHub Actions 拉取对应架构，再下载离线文件。

---

三、支持哪些 CPU 架构？

当前项目提供三种目标平台：

工作流名称	Docker 平台	常见设备
AMD64 / x86-64	linux/amd64	Intel、AMD 处理器的电脑、服务器和 NAS
ARM64	linux/arm64	64 位 ARM NAS、开发板、ARM 云服务器
ARM32	linux/arm/v7	较老的 32 位 ARM 设备

项目为每种架构分别准备了 Release 和 Artifact 两类工作流：

目标架构	Release 工作流	Artifact 工作流
AMD64	Get-AMD64-Docker-Images-Release	x86-64 Pull and Save Docker Image
ARM64	Get-ARM64-Docker-Images-Release	ARM64 Pull and Save Docker Image
ARM32	Get-ARM32-Docker-Images-Release	ARM32 Pull and Save Docker Image

两类工作流生成的核心文件都是 tar.gz：

• Release：文件发布在自己仓库的 Releases 页面；
• Artifact：文件位于 Actions 运行详情页，下载时外层会包装成 ZIP。

按照项目 README 的说明，小于约 2GB 的镜像可以选择 Release；约 2GB 到 5GB 可以尝试 Artifact；大于约 5GB 的镜像不适合使用这个项目。

---

四、使用教程地址

项目中文操作步骤：

https://github.com/wukongdaily/DockerTarBuilder/blob/master/README_CN.md

作者的图文教程：

https://wkdaily.cpolar.top/archives/gc

视频教程：

https://www.bilibili.com/video/BV1EZ421M7mL

https://www.bilibili.com/video/BV1yyq6YREdF

项目常见问题：

https://github.com/wukongdaily/DockerTarBuilder/wiki

---

五、Docker 镜像如何查找？

1. Docker Hub

Docker Hub 地址：

https://hub.docker.com/

在搜索框中输入软件名称，进入镜像详情后查看 Tags。重点确认镜像名称、版本标签和 OS/ARCH，避免选择目标设备不支持的平台。

常见格式：

# Docker Hub 官方镜像
alpine:latest
nginx:latest

# Docker Hub 用户或组织镜像
homeassistant/home-assistant:latest

2. 项目提供的镜像查询页面

https://docker.fxxk.dedyn.io/

3. 项目官方文档和 compose 文件

不少应用会把镜像发布在 GitHub Container Registry。最可靠的来源通常是应用自己的 README、安装文档或 docker-compose.yml。

例如 compose 文件中出现：

services:
  app:
    image: ghcr.io/owner/image:tag

需要填写到 DockerTarBuilder 中的是：

ghcr.io/owner/image:tag

ghcr.io/ 不能省略，否则 Docker 会默认去 Docker Hub 查找。

---

六、使用前需要注意什么？

• 应根据最终运行容器的设备选择架构，而不是根据当前打开 GitHub 的电脑选择；
• 镜像作者必须已经发布对应平台，工具不能在不同 CPU 指令集之间转换镜像；
• 工作流默认适合公开镜像，不适合需要登录的私有镜像；
• Fork 公开仓库后，Release 文件也可能公开可见，不要处理包含敏感数据的镜像；
• Artifact 当前只保留 1 天，生成后应及时下载；
• GitHub Actions 有运行、存储和流量限制，不适合长期批量转存大量镜像。

下载后可以直接导入 gzip 压缩的镜像归档：

docker load -i image_latest-arm64.tar.gz

导入后检查镜像架构：

docker image inspect <镜像名:标签> --format '{{.Os}}/{{.Architecture}}'

---

总结

DockerTarBuilder 最有价值的地方，是可以根据最终设备主动选择 AMD64、ARM64 或 ARM32 镜像。