crane Docker镜像文档

1. 镜像概述和主要用途

crane镜像是基于Alpine Linux的轻量级Docker镜像，集成crane工具，专注于Docker镜像的高效管理。其核心用途是简化多架构（Multi-Architecture）镜像的操作流程，支持镜像标签查询、跨仓库复制及多架构标签创建，确保镜像在不同环境中的一致性和可移植性。

2. 核心功能和特性

• 镜像标签查询：列出指定镜像的所有关联标签，快速获取版本信息
• 多架构镜像复制：完整复制包含多种操作系统/架构（OS/Arch）的镜像至目标仓库，保持镜像摘要（DIGEST）一致
• 多架构标签创建：为多架构镜像创建新标签，确保所有架构版本同步应用该标签

3. 使用场景和适用范围

• 多架构镜像迁移：在不同Docker仓库（如Docker Hub、私有仓库）间迁移包含多种架构的镜像
• 镜像版本管理：统一多架构镜像的标签策略，简化跨平台版本控制
• 镜像分发预处理：复制官方镜像至私有仓库并添加自定义标签，优化内部分发流程

适用人群：Docker镜像维护者、DevOps工程师、需要管理多平台应用部署的开发团队。

4. 使用方法和配置说明

4.1 前置条件

• 本地环境已安装Docker引擎（建议版本20.10+）
• 目标Docker仓库账号及访问令牌（非登录密码，需在仓库设置中生成，如Docker Hub的Personal Access Token）

4.2 显示镜像标签

功能说明

查询指定镜像的所有关联标签。

命令格式

docker run --rm alpine/crane ls <镜像名称>

参数说明

• <镜像名称>：需查询标签的目标镜像（如ubuntu）

示例

查询ubuntu镜像的所有标签：

docker run --rm alpine/crane ls ubuntu

输出示例

10.04
12.04.5
12.04
12.10
...

4.3 复制多架构镜像

功能说明

将源镜像（含所有架构版本）完整复制至目标仓库，保持镜像摘要（DIGEST）一致。

步骤1：仓库认证

通过挂载本地Docker配置目录，进行目标仓库登录认证（认证信息持久化至本地.docker/config.json）：

docker run -ti --rm -v $(pwd)/.docker:/root/.docker alpine/crane auth login -u <Docker账号> -p <访问令牌> <仓库地址>

参数说明

• -v $(pwd)/.docker:/root/.docker：挂载本地目录至容器，用于持久化认证配置
• -u：Docker仓库账号（如Docker Hub用户名）
• -p：仓库访问令牌（如Docker Hub的dckr_pat_xxx格式令牌）
• <仓库地址>：目标仓库域名（如Docker Hub为index.docker.io）

认证示例（Docker Hub）

docker run -ti --rm -v $(pwd)/.docker:/root/.docker alpine/crane auth login -u ozbillwang -p dckr_pat_vynZPg8C5KsqItk-xxxxxxxxxx index.docker.io

验证认证配置

认证成功后，本地.docker/config.json将生成认证记录：

more .docker/config.json

输出示例：

{
    "auths": {
        "[***]": {
            "auth": "b3piaWxsd2FuZzpkYxxxx"
        }
    }
}

步骤2：复制多架构镜像

执行复制命令，将源镜像完整复制至目标仓库：

docker run -ti --rm -v $(pwd)/.docker:/root/.docker alpine/crane copy <源镜像> <目标仓库/镜像名>

参数说明

• <源镜像>：待复制的源镜像（如nginx）
• <目标仓库/镜像名>：目标仓库及镜像名称（如ozbillwang/nginx）

复制示例

复制nginx镜像至ozbillwang/nginx仓库：

docker run -ti --rm -v $(pwd)/.docker:/root/.docker alpine/crane copy nginx ozbillwang/nginx

结果验证

复制完成后，目标仓库将显示包含所有原架构版本的镜像，且所有架构的镜像摘要（DIGEST）与源镜像完全一致。

4.4 创建多架构镜像标签

功能说明

为已存在的多架构镜像创建新标签，确保所有架构版本同步关联该标签。

命令格式

docker run -ti --rm -v $(pwd)/.docker:/root/.docker alpine/crane tag <源镜像> <新标签>

参数说明

• <源镜像>：需添加标签的多架构镜像（如ozbillwang/nginx）
• <新标签>：为镜像创建的标签名称（如abc）

标签创建示例

为ozbillwang/nginx镜像添加abc标签：

docker run -ti --rm -v $(pwd)/.docker:/root/.docker alpine/crane tag ozbillwang/nginx abc

结果验证

执行成功后，目标镜像将新增指定标签，且所有架构版本均关联该标签，可通过仓库界面或docker manifest inspect命令确认。

5. 注意事项

• 权限控制：操作前确保目标仓库具备写入权限，避免因权限不足导致复制/标签失败
• 认证安全：.docker/config.json包含敏感认证信息，操作完成后建议删除该目录或清理敏感数据
• 版本兼容性：多架构镜像操作依赖Docker引擎对OCI manifest的支持，建议使用Docker 20.10+版本以避免兼容性问题