镜像 tag 与架构

官方镜像发布到 ghcr.io/gatellm-io/gatellm。本章讲清三件事：有哪些 tag、各自什么时候用；镜像支持哪些 CPU 架构、拉取时怎么选；以及 GHCR 包页面上那些 -amd64 / -arm64 后缀的 tag 是什么、要不要用。

tag 语义与选用

tag	语义	何时用
vX.Y.Z	不可变，对应一次正式发布	生产环境推荐，可复现、可回滚
latest	浮动，始终指向最新正式发布	尝鲜、单机、非严格环境
sha-<sha7>	不可变，对应具体 git commit（7 位短 sha）	追溯二进制到源码、问题排查

⚠️ 生产环境不要用 latest：它是浮动 tag，重启或扩容时可能拉到不同版本，故障时既无法复现、也无法确定回滚目标。钉 vX.Y.Z，需要绝对不可变时再进一步钉到 @sha256:<digest>（见下）。

支持的架构

官方镜像是 multi-arch OCI index，docker pull 会自动按宿主架构解析，无需任何额外参数：

平台	覆盖
linux/amd64	x86_64：Intel / AMD 服务器、Docker Desktop on Windows、Intel Mac
linux/arm64	aarch64：鲲鹏 / 飞腾 / AWS Graviton / Ampere、Apple Silicon

docker / containerd / Kubernetes / podman / nerdctl 都按 OCI index 的 platform 字段自动选，所以同一句 docker pull ghcr.io/gatellm-io/gatellm:latest 在 ARM 服务器上拿到 arm64、在 x86 服务器上拿到 amd64。

未发布的架构：armv7、ppc64le、s390x、loongarch64（龙芯）等。在这些平台上 pull 会报：

no matching manifest for linux/<arch> in the manifest list entries

这是硬限制，官方只发 linux/amd64 与 linux/arm64 两个架构。

需要显式钉架构时

绝大多数情况不需要。但跨架构构建、镜像同步、或离线环境下，可用两种方式精确指定：

# 方式一：--platform 指定平台
docker pull --platform linux/arm64 ghcr.io/gatellm-io/gatellm:v0.2.0

# 方式二：@digest 钉到精确 manifest（绝对不可变）
docker pull ghcr.io/gatellm-io/gatellm@sha256:<digest>

⚠️ 别在 ARM 宿主上钉 linux/amd64：pull 能成功（manifest 存在），但容器启动会报 exec format error——二进制是 x86 指令，ARM CPU 无法执行，除非你装了 QEMU / Rosetta 之类的仿真层。同理，别在 x86 宿主上钉 linux/arm64。

包页面上那些 -amd64 / -arm64 后缀 tag

打开 GHCR 包页面，v0.2.0 及更早的发布会额外列出 v0.2.0-amd64、v0.2.0-arm64、latest-amd64 等后缀 tag。

这些是早期构建流程的中转产物，请忽略。 它们的来龙去脉：早期发布时两条架构腿在不同构建机上各自推一个可寻址的中间 tag（<tag>-<arch>），供合并步骤引用。这些中间 tag 的内容与对应 multi-arch tag 的同平台切片完全相同——v0.2.0-arm64 就是 v0.2.0 里的 linux/arm64 那一份，没有多出任何东西。

两个要点：

1. 它们无法删除。这些中间 tag 与 multi-arch tag 的对应切片是同一个 package version，删除它会连带删掉 v0.2.0 / latest 的 index 引用，导致该架构的用户拉取失败。
2. 新版本不再产生它们。构建流程已改为把中间镜像推入一个私有的 staging 仓库，公开包里只留最终的 multi-arch tag。

所以：直接用 vX.Y.Z / latest 即可；要钉架构就用上面的 --platform 或 @digest，不必理会这些后缀 tag。

离线 / 气隙环境搬运

docker save 只导出本地 daemon 里的那一份——也就是你 pull 时解析到的单架构镜像，multi-arch index 会丢失。离线环境两种正确做法：

# 做法一：显式按平台拉取后再 save（得到单架构 tar）
docker pull --platform linux/arm64 ghcr.io/gatellm-io/gatellm:v0.2.0
docker save ghcr.io/gatellm-io/gatellm:v0.2.0 -o gatellm-arm64.tar

# 做法二：skopeo copy --all 保留完整 index（适合同步到私有 registry）
skopeo copy --all docker://ghcr.io/gatellm-io/gatellm:v0.2.0 docker://registry.example.com/gatellm:v0.2.0

验证命令

# 看某个 tag 是不是 multi-arch index（列出所有平台）
docker buildx imagetools inspect ghcr.io/gatellm-io/gatellm:latest

# 看本地 daemon 里实际落地的是哪个架构
docker image inspect gatellm --format '{{.Architecture}}'

相关

• Docker 单机跑通 —— 5 分钟零配置跑通，含「支持的架构」小节
• 上线检查清单 —— 生产部署前必查，含「镜像版本」
• 许可与授权状态 —— 镜像为商业构建，未授权时按免费版运行