Zot 镜像同步实战指南：跨区域镜像复制的完整配置方法-开发者社区

Zot 镜像同步实战指南：跨区域镜像复制的完整配置方法

【免费下载链接】zotzot - A scale-out production-ready vendor-neutral OCI-native container image/artifact registry (purely based on OCI Distribution Specification)项目地址: https://gitcode.com/GitHub_Trending/zo/zot

Zot 是一款基于 OCI Distribution Specification 的容器镜像与制品仓库，其内置的镜像同步能力（Zot 镜像复制）支持定时同步与按需同步两种模式。本文带你从最小可用配置出发，逐步配好跨区域同步，并讲清内容过滤、路径转换和高级参数的原理与用法。

多区域分发，为什么要让仓库自己干活

如果你的镜像被多地的集群消费，靠手工docker pull / push既慢又容易漏。常见的诉求有三类：

多区域分发：在边缘区域维护一份就近的镜像副本，缩短拉取链路。
镜像备份：把关键镜像定期复制到其他仓库，故障时可直接恢复。
环境隔离：开发侧持续产出，生产侧只放行特定版本，避免未验证的镜像流入生产。

Zot 的 sync 扩展就是为解决这类问题设计的：它运行在 extensions/sync/ 目录下，由配置文件驱动，无需额外的复制工具。

⚡ 跑通一份最小的同步配置

同步配置全部位于extensions.sync节点下。先看一份最小可用的配置：

{ "extensions": { "sync": { "enable": true, "credentialsFile": "./examples/sync-auth-filepath.json", "registries": [ { "urls": ["https://registry1:5000"] } ] } } }

顶层三个参数，一个都不能少：

enable：总开关，置为true后同步扩展才会加载。
credentialsFile：访问源仓库的凭证文件，格式与 Docker 凭证文件一致。
registries：源仓库列表，每个元素描述一个同步源，可配置多条。

每个源仓库条目下的常用配置项：

urls：源仓库地址，可写多个，Zot 会依次尝试。
pollInterval：定时同步轮询周期，如"6h"表示每 6 小时拉取一次目录清单。
onDemand：是否对该源开启按需同步，默认false。
tlsVerify：是否校验源仓库 TLS 证书，生产环境建议保持true。
content：内容过滤规则数组，控制同步哪些仓库、哪些标签。

完整示例可对照 config-sync.json，其中四种典型配置（定时、多源、按需、混合）都有覆盖。

定时同步：按 pollInterval 批量拉取

定时同步是"仓库主动干活"。Zot 按pollInterval轮询远端/v2/_catalog，发现新仓库或新标签后逐个复制。

执行入口是SyncRepo方法，实现位于 sync.go，它会把指定仓库的全部标签与引用（签名、SBOM 等 artifacts）一起复制进来。
周期任务由内置调度器驱动，任务生成逻辑也在sync.go的TaskGenerator中，一轮同步结束后会重置目录游标，等待下一轮。

{ "urls": ["https://registry1:5000"], "onDemand": false, "pollInterval": "6h", "content": [ { "prefix": "/repo1/repo" } ] }

pollInterval写得越长，远端压力越小，但新镜像到达本地的延迟也越大，按业务节奏取舍即可。

按需同步：请求 miss 时自动回源

按需同步是"谁要谁取"。客户端向本地 Zot 拉取一个不存在的镜像时，Zot 会实时从远端仓库抓取并落到本地，调用方拿到的是正常返回。

在源仓库条目中设置"onDemand": true即可启用。
核心实现在 on_demand.go 的syncImage方法，镜像的 referrers（签名、附加制品）由syncReferrers同步补齐。
回源耗时与稳定性靠这三个参数兜底：
maxRetries：回源失败后的最大重试次数。
retryDelay：重试间隔，失败后按此间隔再次尝试。
syncTimeout：单次同步的超时时间，防止慢回源长期占用请求。

{ "urls": ["https://index.docker.io"], "onDemand": true, "tlsVerify": true, "maxRetries": 5, "retryDelay": "1s", "syncTimeout": "10m" }

同一源也可以把pollInterval和onDemand同时配上：周期任务负责兜底刷新，按需请求负责即时补充。

只同步 4.x 标签，还能改写仓库路径

content数组决定"同步什么"，支持按仓库前缀和标签两个维度过滤：

prefix：仓库前缀匹配，**表示匹配所有子路径，如"/repo3/**"。
tags.regex：只同步匹配正则的标签。
tags.semver：按语义化版本解析标签，便于做版本比较。
tags.excludeRegex：排除匹配正则的标签，如跳过带架构后缀的标签。

"content": [ { "prefix": "/repo1/repo", "tags": { "regex": "4.*", "semver": true } }, { "prefix": "/repo4/**", "tags": { "excludeRegex": ".*-(amd64|arm64)$" } } ]

如果希望同步后的仓库路径与源不同，用路径转换：