镜像仓库 Registry

定义

镜像仓库（registry）是一套 HTTP 服务，按照 OCI Distribution 规范存储并分发镜像的清单、配置与层。客户端使用 pull 下载、push 上传。Docker Hub、GitHub Container Registry（ghcr.io）以及私有 Harbor 都属于 registry。

仓库名（例如 library/alpine）加上标签或摘要，构成一次拉取的引用。registry 返回的是内容寻址对象；本地运行时再把这些对象还原为可用的镜像。

问题背景

镜像若只能以 tar 文件在机器之间拷贝，则缺少统一的发现、鉴权、增量传输与完整性校验。registry 把「分发」从临时文件交换提升为稳定协议：任意兼容客户端都可以向同一仓库请求同一摘要，并验证收到的字节是否被替换。

机制说明

引用如何被解析

以 ghcr.io/example/api:v1 为例：

主机名 ghcr.io 决定联系哪一座 registry；
路径 example/api 是仓库名；
v1 是标签，指向当前该标签所绑定的清单摘要。

省略主机名的 alpine:3.20 通常默认指向 Docker Hub 的官方库。不同工具的默认仓库可以不同，因此脚本中应写全引用。

pull 与 push 传输的是对象，不是目录

pull 并不会把远程的一个文件夹同步下来。它请求清单，再按清单中的摘要拉取 blob（层与配置）。已存在于本地缓存、且摘要匹配的层不会重复下载。push 则是反向过程：先上传本地缺失于远端的 blob，再上传或更新清单与标签。

因此，两台机器「拉取同一个标签」并不保证得到同一份字节，除非该标签在两次拉取之间没有被移动。保证同一内容的方法是按摘要拉取，例如 alpine@sha256:...。

鉴权与策略

公开镜像可以匿名拉取；私有仓库需要登录。登录得到的是访问令牌，用于后续的 pull 或 push，而不是把密码写入每一层。Box 另有签名镜像策略：即使传输完整，也可以拒绝未按策略签名的清单。完整性（摘要匹配）与真实性（签名来自预期密钥）是两件不同的事。

在 Box 中的位置

分发与凭据代码位于 src/runtime/src/oci/registry/、credentials.rs、pull.rs。
CLI 提供 a3s-box login、logout、pull、push。
OCI Runtime 不实现 registry 客户端。Box 完成拉取、校验与 rootfs 准备后，才把不可变 bundle 交给运行时。

验证命令

a3s-box pull alpine:3.20
a3s-box images

若使用私有仓库，须先 a3s-box login，再对完整引用执行 pull 或 push。不要把登录口令写入 Compose 文件或状态记录。