> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/image-tags-and-arch · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 镜像 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` 两个架构。

## 需要显式钉架构时

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

```bash
# 方式一：--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 会丢失。离线环境两种正确做法：

```bash
# 做法一：显式按平台拉取后再 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
```

## 验证命令

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

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

## 相关

- [Docker 单机跑通](/zh-CN/quickstart/docker-single-node.md) —— 5 分钟零配置跑通，含「支持的架构」小节
- [上线检查清单](/zh-CN/practices/production-checklist.md) —— 生产部署前必查，含「镜像版本」
- [许可与授权状态](/zh-CN/reference/licensing.md) —— 镜像为商业构建，未授权时按免费版运行