docker/migrator Docker Image Overview

docker/migrator

自动构建

用于将Docker镜像从v1仓库迁移到v2仓库的工具

8 收藏0 次下载activedocker镜像

🚀专业版镜像服务，面向生产环境设计

中文简介版本下载

🚀专业版镜像服务，面向生产环境设计

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 并配置必要环境变量：

bash
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 必填环境变量

变量名	说明
`V1_REGISTRY`	v1 仓库或 Docker Hub 的 DNS 主机名（不含 `https://`）。若迁移 Docker Hub，使用 `docker.io`。
`V2_REGISTRY`	v2 仓库的 DNS 主机名（不含 `https://`）。

4.2.2 可选环境变量

变量名	说明	默认值/选项
AWS 相关
`AWS_ACCESS_KEY`	AWS 访问密钥（用于 ECR 迁移）。	-
`AWS_REGION`	AWS 区域（使用 ECR 时必须指定）。	-
`AWS_SECRET_ACCESS_KEY`	AWS 密钥（用于 ECR 迁移）。	-
错误处理
`ERROR_ACTION`	推送/拉取错误时的默认行为。	`prompt`（默认，提示用户）；`retry`（重试）；`skip`（跳过）；`abort`（终止）
迁移控制
`MIGRATION_INCREMENT`	按批次迁移镜像，每批 `n` 个（仅当源和目标 FQDN 不同时生效）。	不指定时一次性迁移所有镜像；需为正整数。
`USER_PROMPT`	是否提示用户输入/确认（非错误场景）。	`true`（默认，提示）；`false`（自动继续）
登录控制
`NO_LOGIN`	是否跳过 v1 和 v2 仓库的 `docker login`。	`false`（默认，提示登录）；`true`（跳过登录）
`V1_NO_LOGIN`	是否跳过 v1 仓库的 `docker login`。	`false`（默认，提示登录）；`true`（跳过登录）
`V2_NO_LOGIN`	是否跳过 v2 仓库的 `docker login`。	`false`（默认，提示登录）；`true`（跳过登录）
网络协议
`USE_INSECURE_CURL`	是否允许 curl 不安全 SSL 连接（用于 API 查询）。	`false`（默认，要求安全连接）；`true`（允许不安全）
`USE_HTTP`	是否允许 curl 通过 HTTP 连接 v1 和 v2 仓库（需 Docker 守护进程配置 `--insecure-registry`）。	`false`（默认，要求 HTTPS）；`true`（允许 HTTP）
`V1_USE_HTTP`	是否允许 curl 通过 HTTP 连接 v1 仓库（需 Docker 守护进程配置 `--insecure-registry`）。	`false`（默认，要求 HTTPS）；`true`（允许 HTTP）
`V2_USE_HTTP`	是否允许 curl 通过 HTTP 连接 v2 仓库（需 Docker 守护进程配置 `--insecure-registry`）。	`false`（默认，要求 HTTPS）；`true`（允许 HTTP）
过滤与命名
`DOCKER_HUB_ORG`	Docker Hub 组织名（迁移来源）。若未指定，默认使用登录用户名。	登录用户名
`V1_FULL_REPO_LIST`	空格分隔的仓库列表（用于跳过 v1 的 `_search` API，适用于禁用搜索的场景）。	-
`V1_REPO_FILTER`	仓库过滤规则（使用 `grep` 基本正则表达式）。	-
`V1_TAG_FILTER`	标签过滤规则（纯文本匹配）。	-
`LIBRARY_NAMESPACE`	是否为官方镜像添加 `library/` 命名空间（DTR 1.4+ 需设为 `true`）。	`true`（默认，添加）；`false`（不添加）
`SKIP_EXISTING_TAGS`	是否跳过目标仓库已存在的标签。	`false`（默认，不跳过）；`true`（跳过）

4.3 部署示例

4.3.1 基本迁移（v1 到 v2）

bash
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 凭证文件）

bash
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（通过环境变量传参）

bash
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. 迁移原理

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

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

7. 日志记录

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

bash
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

查看更多 migrator 相关镜像 →