阿里云开源 image-syncer 工具，容器镜像大批量迁移同步利器
发布时间：2025-11-05 02:35:37 来源：创站工坊 作者：IT科技类资讯
本文转自雷锋网，阿里如需转载请至雷锋网官网申请授权。云开源i移同
怎么把已有的工具容器镜像平滑的迁移到阿里云镜像服务 ACR 上？最近阿里云给出了很好的方案，他们开源了 image-syncer 工具，容器能够使得成百上千个镜像实现平滑的镜像批量迁移，其中最大镜像仓库的大批总量可以达到 3T 以上。而这一工具，量迁也被称为容器镜像迁移/同步利器，步利雷锋网AI 开发者将其重点内容及开源地址整理编辑如下。阿里
什么是云开源i移同 image-syncer？
顾名思义，image-syncer 本质上就是工具图像同步器。它是容器一个 docker 镜像同步工具，能够将多对多的镜像镜像仓库同步，并支持目前绝大多数主流的大批 docker 镜像仓库服务，例如：ACR、量迁DockerHub、Quay、自建 Harbor 等。
通常情况下，在 k8s 集群迁移场景中，镜像仓库之间进行镜像迁移/同步是基本需求，而使用 docker pull/push 结合脚本的传统方式进行镜像同步，网站模板有如下几个局限性：
依赖磁盘存储，需要及时进行本地镜像的清理，并且落盘造成多余的时间开销，难以胜任生产场景中大量镜像的迁移
依赖 docker 程序，docker daemon 对 pull/push 的并发数进行了严格的限制，无法进行高并发同步
一些功能只能通过 HTTP api 进行操作，单纯使用 docker cli 无法做到，使脚本变得复杂
图 1 阿里云迁移框架
而 image-syncer 开发之初的定位就是一个简单、易用的批量镜像迁移/同步工具；因此，它的特性如下：
支持多对多镜像仓库同步
支持基于 Docker Registry V2 搭建的 docker 镜像仓库服务 (如 Docker Hub、 Quay、 阿里云镜像服务 ACR、 Harbor 等)
同步只经过内存和网络，不依赖磁盘存储，同步速度快
增量同步, 通过对同步过的镜像 blob 信息落盘，不重复同步已同步的镜像
并发同步，可以通过配置文件调整并发数
自动重试失败的同步任务，可以解决大部分镜像同步中的网络抖动问题
不依赖 docker 以及其他程序
只需要保证 image-syncer 的运行环境与需要同步的高防服务器 registry 网络连通，使用者就可以快速地完成从镜像仓库的迁移、拷贝以及增量同步，并且该工具对硬件资源几乎没有要求（因为 image-syncer 严格控制网络连接数目=并发数，所以只有在当单个镜像层过大的情况下，并发数目过大可能会打满内存，内存占用 <= 并发数 x 最大镜像层大小）。
如何使用 image-syncer？
运行 image-syncer，只需要提供一个配置文件，内容如下：
{ "auth": { // 认证字段，其中每个对象为一个 registry 的一个账号和 // 密码；通常，同步源需要具有 pull 以及访问 tags 权限， // 同步目标需要拥有 push 以及创建仓库权限，如果没有提供，则默认匿名访问 "quay.io": { // registry 的 url，需要和下面 images 中对应 registry 的 url 相同 "username": "xxx", // 用户名，可选 "password": "xxxxxxxxx", // 密码，可选 "insecure": true // registry 是否是 http 服务，如果是，insecure 字段需要为 true，默认是 false，可选，支持这个选项需要 image-syncer 版本 > v1.0.1 }, "registry.cn-beijing.aliyuncs.com": { "username": "xxx", "password": "xxxxxxxxx" }, "registry.hub.docker.com": { "username": "xxx", "password": "xxxxxxxxxx" } }, "images": { // 同步镜像规则字段，其中条规则包括一个源仓库（键）和一个目标仓库（值） // 同步的云南idc服务商最大单位是仓库（repo），不支持通过一条规则同步整个 namespace 以及 registry // 源仓库和目标仓库的格式与 docker pull/push 命令使用的镜像 url 类似（registry/namespace/repository:tag） // 源仓库和目标仓库（如果目标仓库不为空字符串）都至少包含 registry/namespace/repository // 源仓库字段不能为空，如果需要将一个源仓库同步到多个目标仓库需要配置多条规则 // 目标仓库名可以和源仓库名不同（tag 也可以不同），此时同步功能类似于：docker pull + docker tag + docker push "quay.io/coreos/kube-rbac-proxy": "quay.io/ruohe/kube-rbac-proxy", "xxxx":"xxxxx", "xxx/xxx/xx:tag1,tag2,tag3":"xxx/xxx/xx" // 当源仓库字段中不包含 tag 时，表示将该仓库所有 tag 同步到目标仓库，此时目标仓库不能包含 tag // 当源仓库字段中包含 tag 时，表示只同步源仓库中的一个 tag 到目标仓库，如果目标仓库中不包含 tag，则默认使用源 tag // 源仓库字段中的 tag 可以同时包含多个（比如"a/b/c:1,2,3"），tag 之间通过","隔开，此时目标仓库不能包含 tag，并且默认使用原来的 tag // 当目标仓库为空字符串时，会将源镜像同步到默认 registry 的默认 namespace 下，并且 repo 以及 tag 与源仓库相同，默认 registry 和默认 namespace 可以通过命令行参数以及环境变量配置，参考下面的描述 } }用户可以根据配置不同的镜像同步规则组合，以匹配不同的迁移/同步需求，如将单个镜像 repo 同步到多个不同的镜像 repo、将多个源镜像同步到单个镜像 repo 中（以 tag 区分）、在同一个 registry 中以不同的名字拷贝一个镜像 repo 等等。
需要注意的是，如果匿名访问作为同步源的 registry 地址，可能存在权限问题无法 pull 镜像以及无法获取 tags，这种情况下需要在" auth "中加入有对应权限的账号密码；而如果匿名访问作为同步目标的 registry 地址，可能存在权限问题无法 push 镜像，同样也可能需要用户提供有对应权限的账号密码。
通常从自建 harbor 同步镜像到 ACR 需要 5 个步骤，包括：
创建 ACR 实例
创建命名空间
创建访问凭证
进行权限管理，完成配置
图 2 最小权限设置示例
下载 image-syncer 可执行文件（目前只支持 linux amd64 版本，可以自行编译）并解压，然后运行工具
最新版源码以及二进制文件：
https://github.com/AliyunContainerService/image-syncer/releases/tag/v1.0.3
常见问题
一次同步会经历三个阶段：生成同步任务、执行同步任务以及重试失败任务；其中，每个同步任务都代表了一个需要同步的 tag（镜像），如果配置文件中某条规则没有指定 tag，在「生成同步任务」阶段会自动 list 源仓库所有 tag，并生成对应的同步任务，如果生成同步任务失败，也会在重试阶段进行重试。（故意配错账号密码时）执行输出如下：
图 3 配错账号密码时执行输出
正常运行的输出：
图 4 正常操作时执行输出
在运行时，image-syncer 会打印出如下的日志信息：
图 5 输出结果日志
而在同步结束之后，image-syncer 也会统计成功和失败的同步任务数目（每个同步任务代表一个镜像），并在标准输出和日志中打印 "Finished, FAILED TASKS> sync tasks failed, TASKS> tasks generate failed" 的字样，从而可以获得同步的结果。
图 6 部分其它参数示例
原文链接：
https://yq.aliyun.com/articles/727565?utm_content=g_1000088598
Github 开源地址：
https://github.com/AliyunContainerService/image-syncer
更多 FAQ 参见：
https://github.com/AliyunContainerService/image-syncer/blob/master/FAQs.md
- Copyright © 2025 Powered by 阿里云开源 image-syncer 工具，容器镜像大批量迁移同步利器,创站工坊 滇ICP备2023006006号-44sitemap