镜像 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:latest

# 方式二：@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

早期（v0.2.0 及更早）的发布会在 GHCR 包页面上额外列出 v0.2.0-amd64、v0.2.0-arm64、latest-amd64 等后缀 tag——它们是早期构建流程的中转产物：两条架构腿在不同构建机上各自推一个可寻址的中间 tag（<tag>-<arch>）供合并步骤引用，内容与对应 multi-arch tag 的同平台切片完全相同。

这些后缀 tag 连同 v0.2.0 镜像已于 2026-09 一并清理。 当前包页面只保留最终 multi-arch tag：直接用 vX.Y.Z / latest 即可，要钉架构就用上面的 --platform 或 @digest。

构建流程也已改为把中间镜像推入私有 staging 仓库，公开包里只留最终 multi-arch tag，因此新版本不会再产生这类后缀 tag。

离线 / 气隙环境搬运

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

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

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

⚠️ 这里为简洁起见用了 latest —— 正式做镜像同步时请钉 vX.Y.Z（或 @sha256:<digest>），保证同步出的镜像可复现、可回滚。

验证命令

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

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

相关

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