docker/migrator 镜像文档

1. 镜像概述

docker/migrator 是一款用于将 Docker 镜像从 Docker Hub 或 v1 版本镜像仓库（registry）迁移至 v2 版本镜像仓库（包括 Amazon Elastic Container Registry, ECR）的工具。该工具通过自动化脚本实现镜像的拉取、重新标记和推送，简化跨版本或跨平台的镜像仓库迁移流程。

项目地址：[***]

2. 核心功能与特性

• 多源迁移支持：支持从 Docker Hub 或 v1 registry 迁移至 v2 registry（含 ECR）。
• 灵活的环境配置：通过环境变量自定义迁移行为，如认证、网络协议、过滤规则等。
• 错误处理机制：提供错误时的重试、跳过、终止等策略，支持用户交互提示。
• 增量迁移：支持按指定数量分批次迁移镜像，适应磁盘空间有限的场景。
• 细粒度过滤：可通过仓库名、标签过滤迁移范围，支持正则表达式。
• 安全支持：支持自定义 CA 证书、客户端证书，以及 HTTP/HTTPS 协议配置。
• ECR 集成：原生支持 AWS ECR 迁移，可通过环境变量或 AWS 凭证文件认证。

3. 使用场景

• v1 仓库升级：将旧版 v1 registry 镜像迁移至 v2 registry（如 Docker Registry 2.x）。
• Docker Hub 迁移：将 Docker Hub 中的组织或个人镜像迁移至私有 v2 registry。
• 云平台迁移：将本地镜像仓库迁移至 Amazon ECR 等云托管容器镜像服务。
• 跨环境同步：在不同 v2 registry 间同步镜像（需配置源和目标 registry）。

4. 使用方法

4.1 基本用法

通过 docker run 命令启动容器，挂载 Docker 守护进程 socket 并配置必要环境变量：

docker run -it \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e V1_REGISTRY=v1.registry.fqdn \  # v1仓库或Docker Hub地址（不含[***]
    -e V2_REGISTRY=v2.registry.fqdn \  # v2仓库地址（不含[***]
    docker/migrator

4.2 环境变量配置

4.2.1 必填环境变量

4.2.2 可选环境变量

4.3 部署示例

4.3.1 基本迁移（v1 到 v2）

docker run -it \
    -v /var/run/docker.sock:/var/run/docker.sock \  # 挂载 Docker 守护进程 socket
    -e V1_REGISTRY=v1.registry.example.com \        # 源 v1 仓库
    -e V2_REGISTRY=v2.registry.example.com \        # 目标 v2 仓库
    -e ERROR_ACTION=skip \                          # 错误时跳过
    -e MIGRATION_INCREMENT=10 \                     # 每批迁移 10 个镜像
    docker/migrator

4.3.2 迁移至 Amazon ECR（通过 AWS 凭证文件）

docker run -it \
    -v ~/.aws:/root/.aws:ro \                       # 挂载 AWS 凭证文件（只读）
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e V1_REGISTRY=docker.io \                      # 源：Docker Hub
    -e V2_REGISTRY=123456789012.dkr.ecr.us-east-1.amazonaws.com \  # 目标 ECR
    -e AWS_REGION=us-east-1 \                       # ECR 区域
    docker/migrator

4.3.3 迁移至 Amazon ECR（通过环境变量传参）

docker run -it \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e AWS_ACCESS_KEY_ID=AKIAEXAMPLE \              # AWS 访问密钥
    -e AWS_SECRET_ACCESS_KEY=secret \               # AWS 密钥
    -e AWS_REGION=us-east-1 \                       # ECR 区域
    -e V1_REGISTRY=v1.registry.example.com \
    -e V2_REGISTRY=123456789012.dkr.ecr.us-east-1.amazonaws.com \
    docker/migrator

5. 先决条件

• 环境要求：需同时存在 v1 仓库（或 Docker Hub）和目标 v2 仓库。源和目标仓库可使用相同或不同 DNS 主机名（若相同，需将 V1_REGISTRY 和 V2_REGISTRY 设为同一值）。
• 网络与存储：建议在靠近仓库的 Docker 引擎上运行（减少网络延迟），且需足够磁盘空间存储临时镜像。若空间有限，可通过 MIGRATION_INCREMENT 分批次迁移。
• ECR 额外要求：迁移至 ECR 时，需提供 AWS 凭证（通过环境变量或 ~/.aws 目录挂载）。

6. 迁移原理

迁移流程通过容器内的自动化脚本实现，步骤如下：

1. 登录验证（可选）：提示用户登录 v1 仓库或 Docker Hub（若未启用认证，用户名留空）。
2. 仓库与标签查询：查询 v1 仓库或 Docker Hub 的所有仓库列表，再获取每个仓库的标签，生成待迁移镜像清单。
3. 镜像拉取：通过 Docker 引擎拉取所有待迁移镜像（含标签）。
4. 镜像处理：
   • 若源和目标仓库 DNS 不同：重新标记镜像（将源仓库地址替换为目标地址）。
   • 若 DNS 相同：需先切换 DNS 指向或停止 v1 仓库并启动 v2 仓库。
5. 目标登录（可选）：提示用户登录 v2 仓库。
6. 镜像推送：将处理后的镜像推送至 v2 仓库。
7. 验证与清理：验证迁移结果（暂未实现），清理本地临时镜像。

7. 日志记录

如需保存迁移输出日志，可在 docker run 命令末尾添加日志重定向：

docker run -it \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e V1_REGISTRY=docker.io \
    -e V2_REGISTRY=v2.registry.example.com \
    docker/migrator 2>&1 | tee migration.log  # 将输出保存至 migration.log