From 5d932945ff44b6b28033499f3a332086ff55d145 Mon Sep 17 00:00:00 2001 From: hhyasdf <552483776@qq.com> Date: Thu, 20 Jul 2023 19:50:31 +0800 Subject: [PATCH] chore: update zh_CN README --- README-zh_CN.md | 134 +++++++++++++++++++++--------------------------- 1 file changed, 58 insertions(+), 76 deletions(-) diff --git a/README-zh_CN.md b/README-zh_CN.md index 496ca5d..a0c1b80 100644 --- a/README-zh_CN.md +++ b/README-zh_CN.md @@ -8,25 +8,29 @@ [![codecov](https://codecov.io/gh/AliyunContainerService/image-syncer/graph/badge.svg)](https://codecov.io/gh/AliyunContainerService/image-syncer) [![License](https://img.shields.io/github/license/AliyunContainerService/image-syncer)](https://www.apache.org/licenses/LICENSE-2.0.html) -`image-syncer` 是一个docker镜像同步工具，可用来进行多对多的镜像仓库同步，支持目前绝大多数主流的docker镜像仓库服务 +`image-syncer` 是一个容器镜像同步工具，可用来进行多对多的镜像仓库同步，支持目前绝大多数主流的 docker 镜像仓库服务 [English](./README.md) | 简体中文 ## Features - 支持多对多镜像仓库同步 -- 支持基于Docker Registry V2搭建的docker镜像仓库服务 (如 Docker Hub、 Quay、 阿里云镜像服务ACR、 Harbor等) -- 同步只经过内存和网络，不依赖磁盘存储，同步速度快 -- 增量同步, 通过对同步过的镜像blob信息落盘，不重复同步已同步的镜像 -- 并发同步，可以通过配置文件调整并发数 -- 自动重试失败的同步任务，可以解决大部分镜像同步中的网络抖动问题 -- 不依赖docker以及其他程序 +- 支持基于 Docker Registry V2 搭建的镜像仓库服务 (如 Docker Hub、 Quay、 阿里云镜像服务 ACR、 Harbor 等) +- 同步过程只经过内存和网络，不依赖磁盘存储，同步速度快 +- 自动增量同步, 自动忽略已同步且不需要修改的镜像 +- 支持镜像层级别的并发同步，可以通过配置文件调整并发数（可以理解为同一时间在同步的镜像层数量上限） +- 自动重试失败的同步任务，可以解决大部分镜像同步中的偶发问题（限流、网络抖动），支持重试次数配置 +- 简单轻量，不依赖 docker 以及其他程序 ## 使用 +### GitHub Action + +可以使用 [image-sync-action](https://github.com/marketplace/actions/image-sync-action) 这个 github action 来实现灵活触发的镜像同步作业（比如定时同步），不依赖任意底层资源的同时，也可以解决外网访问的问题 + ### 下载和安装 -在[releases](https://github.com/AliyunContainerService/image-syncer/releases)页面可下载源码以及二进制文件 +在 [releases](https://github.com/AliyunContainerService/image-syncer/releases) 页面可下载源码以及二进制文件 ### 手动编译 @@ -46,81 +50,59 @@ make # 设置配置文件为config.json，默认registry为registry.cn-beijing.aliyuncs.com # 默认namespace为ruohe，并发数为6 -./image-syncer --proc=6 --auth=./auth.json --images=./images.json --namespace=ruohe \ ---registry=registry.cn-beijing.aliyuncs.com --retries=3 +./image-syncer --proc=6 --auth=./auth.json --images=./images.json --registry=registry.cn-beijing.aliyuncs.com --retries=3 ``` - +认证信息中可以同时描述多个 registry（或者 registry/namespace）对象，一个对象可以包含账号和密码，其中，密码可能是一个 TOKEN + +> 注意，通常同步源需要具有 pull 以及访问 tags 权限，同步目标需要拥有 push 以及创建仓库权限；如果对应仓库没有提供认证信息，则默认匿名访问 + +认证信息文件通过 `--auth` 参数传入，具体文件样例可以参考 [auth.yaml](./example/auth.yaml) 和 [auth.json](./example/auth.json)，这里以 [auth.yaml](./example/auth.yaml) 为例 + +```yaml +quay.io: #支持 "registry" 和 "registry/namespace"（v1.0.3之后的版本） 的形式，image-syncer 会自动为镜像同步规则中的每个源/目标 url 查找认证信息，并且使用对应认证信息进行进行访问，如果匹配到了多个，用“最长匹配”的那个作为最终结果 + username: xxx + password: xxxxxxxxx + insecure: true # 可选，（v1.0.1 之后支持）registry是否是http服务，如果是，insecure 字段需要为 true，默认是 false +registry.cn-beijing.aliyuncs.com: + username: xxx # 可选，（v1.3.1 之后支持）value 使用 "${env}" 或者 "$env" 形式可以引用环境变量 + password: xxxxxxxxx # 可选，（v1.3.1 之后支持）value 使用 "${env}" 或者 "$env" 类型的字符串可以引用环境变量 +docker.io: + username: "${env}" + password: "$env" +quay.io/coreos: + username: abc + password: xxxxxxxxx + insecure: true +``` -### 配置文件 +#### 镜像同步规则 -在 v1.2.0 版本之后，image-syncer 的配置文件支持JSON和YAML两种格式，并且支持将原config文件替换为一个认证信息文件和一个镜像同步文件。详细的配置文件示例可在目录 [example](./example) 下找到，旧版本的配置文件格式（auth 和 images 字段放在一起的版本，通过 --config 参数指定）也是兼容的，目录下 `config.json` 为示例。 +每条镜像同步规则为一个 “源镜像 url: 目标镜像 url” 的键值对。无论是源镜像 url 还是目标镜像 url，字符串格式都和 docker pull 命令所使用的镜像 url 大致相同（registry/repository:tag），但在 tag 和 digest 配置上和 docker pull 所使用的 url 存在区别，这里对整体逻辑进行描述： -#### 认证信息 +1. 源镜像 url 不能为空 +2. 源镜像 url 不包含 tag 和 digest 时，代表同步源镜像 repository 中的所有镜像 tag +3. 源镜像 url 可以包含一个或多个 tag，多个 tag 之间用英文逗号分隔，代表同步源镜像 repository 中的多个指定镜像 tag +4. 源镜像 url 可以但最多只能包含一个 digest，此时如果目标镜像 url 包含 digest，digest 必须一致 +5. 目标镜像 url 可以不包含 tag 和 digest，表示所有需同步的镜像保持其镜像 tag 或者 digest 不变 +6. 目标镜像 url 可以包含多个 tag 或者 digest，数量必须与源镜像 url 中的 tag 数量相同，此时，同步后的镜像 tag 会被修改成目标镜像 url 中指定的镜像 tag（按照从左到右顺序对应） +7. 如果目标镜像 url 为空，会将镜像同步到 “默认 registry” 的、跟源镜像 url 相同的 repository 下，并且保持镜像 tag 一致 -`auth.json` 包含了所有仓库的认证信息 - -```java -{ - // 认证字段，其中每个对象为一个registry的一个账号和 - // 密码；通常，同步源需要具有pull以及访问tags权限， - // 同步目标需要拥有push以及创建仓库权限，如果没有提供，则默认匿名访问 - - "quay.io": { // 支持 "registry" 和 "registry/namespace"（v1.0.3之后的版本） 的形式，需要跟下面images中的registry(registry/namespace)对应 - // images中被匹配到的的url会使用对应账号密码进行镜像同步, 优先匹配 "registry/namespace" 的形式 - "username": "xxx", // 用户名，可选，（v1.3.1 之后支持）valuse 使用 "${env}" 或者 "$env" 类型的字符串可以引用环境变量 - "password": "xxxxxxxxx", // 密码，可选，（v1.3.1 之后支持）valuse 使用 "${env}" 或者 "$env" 类型的字符串可以引用环境变量 - "insecure": true // registry是否是http服务，如果是，insecure 字段需要为true，默认是false，可选，支持这个选项需要image-syncer版本 > v1.0.1 - }, - "registry.cn-beijing.aliyuncs.com": { - "username": "xxx", - "password": "xxxxxxxxx" - }, - "docker.io": { - "username": "xxx", - "password": "xxxxxxxxxx" - }, - "quay.io/coreos": { - "username": "abc", - "password": "xxxxxxxxx", - "insecure": true - } -} -``` +镜像同步规则文件通过 `--images` 参数传入，具体文件样例可以参考 [images.yaml](./example/images.yaml) 和 [images.json](./example/images.json)，这里以 [images.yaml](./example/images.yaml) 为例。 示例如下： -#### 镜像同步文件 - -```java -{ - // 同步镜像规则字段，其中条规则包括一个源仓库（键）和一个目标仓库（值） - - // 同步的最大单位是仓库（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可以通过命令行参数以及环境变量配置，参考下面的描述 -} +```yaml +quay.io/coreos/kube-rbac-proxy: quay.io/ruohe/kube-rbac-proxy +quay.io/coreos/kube-rbac-proxy:v1.0: quay.io/ruohe/kube-rbac-proxy +quay.io/coreos/kube-rbac-proxy:v1.0,v2.0: quay.io/ruohe/kube-rbac-proxy +quay.io/coreos/kube-rbac-proxy@sha256:14b267eb38aa85fd12d0e168fffa2d8a6187ac53a14a0212b0d4fce8d729598c: quay.io/ruohe/kube-rbac-proxy ``` ### 更多参数 @@ -129,7 +111,7 @@ ACR(Ali Container Registry) 是阿里云提供的容器镜像服务，ACR企业 ``` -h --help 使用说明，会打印出一些启动参数的当前默认值 - + --config 设置用户提供的配置文件路径，使用之前需要创建此文件，默认为当前工作目录下的config.json文件。这个参数与 --auth和--images 的 作用相同，分解成两个参数可以更好地区分认证信息与镜像仓库同步规则。建议使用 --auth 和 --images. @@ -139,8 +121,6 @@ ACR(Ali Container Registry) 是阿里云提供的容器镜像服务，ACR企业 --log 打印出来的log文件路径，默认打印到标准错误输出，如果将日志打印到文件将不会有命令行输出，此时需要通过cat对应的日志文件查看 - --namespace 设置默认的目标namespace，当配置文件内一条images规则的目标仓库为空，并且默认registry也不为空时有效，可以通过环境变量DEFAULT_NAMESPACE设置，同时传入命令行参数会优先使用命令行参数值 - --registry 设置默认的目标registry，当配置文件内一条images规则的目标仓库为空，并且默认namespace也不为空时有效，可以通过环境变量DEFAULT_REGISTRY设置，同时传入命令行参数会优先使用命令行参数值 --proc 并发数，进行镜像同步的并发goroutine数量，默认为5 @@ -152,8 +132,10 @@ ACR(Ali Container Registry) 是阿里云提供的容器镜像服务，ACR企业 --os 用来过滤源 tag 的 os 列表，为空则没有任何过滤要求，只对非 docker v2 schema1 media 类型的镜像格式有效 --arch 用来过滤源 tag 的 architecture 列表，为空则没有任何过滤要求 + + --force 同步已经存在的、被忽略的镜像，这个操作会更新已存在镜像的时间戳 ``` ### FAQs -同步中常见的问题汇总在[FAQs文档](./FAQs.md)中 +同步中常见的问题汇总在[FAQs 文档](./FAQs.md)中