Skip to content

Commit

Permalink
chore: update zh_CN README
Browse files Browse the repository at this point in the history
  • Loading branch information
@hhyasdf
hhyasdf committed Jul 20, 2023
1 parent d093de6 commit 828f2ab
Showing 1 changed file with 59 additions and 77 deletions.
136 changes: 59 additions & 77 deletions README-zh_CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) 页面可下载源码以及二进制文件

### 手动编译

Expand All @@ -38,89 +42,67 @@ cd $GOPATH/github.com/AliyunContainerService/image-syncer
make
```

### 使用用例
### 命令用例

```shell
# 获得帮助信息
./image-syncer -h

# 设置配置文件为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
```

<!--
### 同步镜像到ACR
### 配置文件

ACR(Ali Container Registry) 是阿里云提供的容器镜像服务，ACR企业版(EE)提供了企业级的容器镜像、Helm Chart 安全托管能力，推荐安全需求高、业务多地域部署、拥有大规模集群节点的企业级客户使用。
为了提高配置的灵活性，image-syncer 支持通过 `--auth` 参数以文件的形式传入认证信息，同时通过 `--images` 参数以文件的形式传入镜像同步规则。两种配置文件都同时支持 YAML 和 JSON 两种格式，其中认证信息是可选的，镜像同步规则是必须的。通过两者分离的方式，可以做到认证信息的灵活复用

这里会将quay.io上的一些镜像同步到ACR企业版，作为使用用例。
> 1.2.0 版本之前主要使用的、通过 `--config` 参数以一个配置文件同时传入认证信息和镜像同步规则的格式也是兼容的，可以参考 [config.yaml](./example/config.yaml) 和 [config.json](./example/config.json)
#### 创建企业版ACR
#### 认证信息

1. [创建容器镜像服务]()
2. -->
认证信息中可以同时描述多个 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、registry/repository@digest），但在 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
```

### 更多参数
Expand All @@ -129,7 +111,7 @@ ACR(Ali Container Registry) 是阿里云提供的容器镜像服务，ACR企业

```
-h --help 使用说明，会打印出一些启动参数的当前默认值

--config 设置用户提供的配置文件路径，使用之前需要创建此文件，默认为当前工作目录下的config.json文件。这个参数与 --auth和--images 的
作用相同，分解成两个参数可以更好地区分认证信息与镜像仓库同步规则。建议使用 --auth 和 --images.

Expand All @@ -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
Expand All @@ -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)中

0 comments on commit 828f2ab

Please sign in to comment.