English version | 中文版

镜像打包侠 ImagePack

镜像打包侠 是一个用于容器镜像离线交付的命令行工具，命令名为 imagepack。它可以把一个或多个远程容器镜像导出为单个 OCI image layout tar 包，并在 index.json 中写入 containerd 兼容的镜像引用注解，方便在离线环境、私有化部署和内网交付场景中导入使用。

imagepack pull 不依赖 Docker daemon、containerd、nerdctl 或 crictl 等本地容器运行时服务。它直接访问远程 registry 拉取镜像数据并生成标准 OCI image layout tar 包，因此可以在没有安装或没有运行容器服务的构建机、跳板机、交付机和受限环境中使用。

适用场景

• 将多个业务镜像、Sidecar 镜像或 CSI/Operator 镜像打成一个离线包。
• 从有网环境拉取镜像后，交付到无公网访问能力的环境。
• 在没有 Docker 或 containerd 服务的机器上制作镜像离线包。
• 为 containerd、nerdctl 或支持 OCI image layout 的工具准备标准镜像归档。
• 保留镜像原始来源信息，同时生成不带 registry 地址的 org.opencontainers.image.ref.name。

安装与构建

make build

构建产物位于：

bin/imagepack

清理构建产物：

make clean

使用方式

拉取远程镜像并打包：

imagepack pull [flags] <output.tar> <image> [<image>...]

示例：

imagepack pull --platforms linux/amd64 images.tar \
  registry.local:5443/csi-s3/csi-s3-driver:0.43.2 \
  registry.local:5443/csi-s3/csi-node-driver-registrar:v1.2.0

导出过程中，imagepack pull 会在 stderr 输出进度信息，包括准备 OCI layout、逐个复制镜像、重写 index.json、写出 tar 包和完成状态。真实复制远程镜像时，会参考 docker pull 的样式按 blob 原地刷新同一行，显示进度条、已传输大小、总大小和实时网速。

上传离线包到私有仓库：

imagepack push <images.tar> --user <username:password> --base-name <registry/path>

示例：

imagepack push images.tar --user aaa:password_aa --base-name registry.local:5443/testpath

imagepack push 会读取归档中每个镜像的 org.opencontainers.image.ref.name 注解，并将原相对镜像名拼接到 --base-name 下面。例如归档中的 csi-s3/csi-s3-driver:0.43.2 会推送到 registry.local:5443/testpath/csi-s3/csi-s3-driver:0.43.2。

Pull 参数

• --platforms <os/arch[/variant][,...]>：导出指定平台的镜像，多个平台用逗号分隔，例如 linux/amd64,linux/arm64。
• --all-platforms：导出镜像索引中的所有平台。
• --authfile <path>：读取 Docker 兼容格式的 registry 认证文件。
• --tls-verify=false：允许访问使用自签名证书或无法校验证书的 registry。

规则：

• 至少提供一个镜像。
• 镜像必须包含完整 registry 地址。
• 镜像必须包含 tag 或 digest。
• --platform 和 --all-platforms 不能同时使用。
• 如果不指定平台参数，默认导出当前运行环境的平台。

示例：

Push 参数

• --user <username:password>：目标私有仓库的用户名和密码。
• --base-name <registry/path>：目标仓库前缀，镜像会推送到该路径下并保留原相对仓库路径和 tag/digest。

输出内容

imagepack pull 会生成一个 OCI image layout tar 包，包含：

• oci-layout
• index.json
• blobs/sha256/...

每个顶层 manifest descriptor 会写入以下注解：

• io.containerd.image.name：完整原始镜像引用。
• org.opencontainers.image.ref.name：去掉 registry 地址后的镜像引用。
• containerd.io/distribution.source.<registry-host>：镜像仓库路径。