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集群跨了几个 Region跨区拉镜像又慢又贵手工搬运扛不住了。Zot 的 sync 扩展就是干这个的它把上游仓库的镜像持续同步进本地仓库让每个站点都能就近拉取。定时同步和按需同步都支持两者可以在同一个上游上同时开启。手工搬运镜像的三个死穴你大概率干过这种事在构建机上docker pull、docker tag、docker push逐个 Region 重复一遍。镜像一多痛苦就来了。第一网络抖动直接断流程哪一步失败要人肉判断重跑。第二多架构 index、签名和 SBOM 这类 referrers手工链路很容易漏各站点内容对不齐。第三没有基线两个仓库之间差了什么没人说得清只能逐个 tag 比对。Zot 的镜像同步把扫上游目录 → 过滤 → 复制 → 提交这整条链路自动化了规则全部写在配置里同步行为可预期、可复查。5 分钟跑通 Zot 镜像同步基于仓库里的 examples/config-sync.json最小可跑配置长这样extensions: { sync: { enable: true, registries: [{ urls: [https://registry-1.docker.io], pollInterval: 6h, content: [{ prefix: library/nginx }] }] } }这一份配置只做一件事每 6 小时扫一遍上游的library/nginx新 tag 自动落到本地。三个核心参数速查参数含义一句话备注enable开启 sync 扩展必须为trueregistries[].urls上游地址列表可写多个按顺序故障切换pollInterval定时轮询间隔不写就不会跑定时同步 注意这里pollInterval要生效前提是content里至少有一条规则。content是双重身份——定时同步靠它圈定范围按需同步靠它做准入过滤。定时同步还是按需同步一张表讲清两种模式不互斥同一个 registry 条目可以同时开启。维度定时同步按需同步触发方式调度器按周期主动扫上游用户拉取本地不存在的镜像时触发关键参数pollIntervalcontentonDemand: true本地表现预先就位拉取永远命中本地首次拉取要等回源同步适用场景镜像集明确、拉取频繁长尾镜像、拉取集合不可预知典型用法边缘 Region 缓存CI 拉取任意基础镜像定时同步整仓扫描tag 用规则过滤。{ urls: [https://registry1:5000], pollInterval: 6h, content: [{ prefix: /repo1/repo, tags: { regex: 4.*, semver: true } }] }为什么这么配镜像集小而明确只要 v4 系且符合语义化版本双过滤能把 dev 系 tag 挡在生产仓库外。按需同步不圈定具体镜像来什么补什么。{ urls: [https://index.docker.io], onDemand: true, maxRetries: 5, retryDelay: 1s, syncTimeout: 10m }为什么这么配长尾镜像数不过来交给按需兜底按需是阻塞式回源网络一抖用户就等超时所以配上maxRetriesretryDelay。注意配了maxRetriesretryDelay就是必填项。如何只同步一部分镜像过滤与路径改写规则全部写在content数组里每条是前缀 可选 tag 过滤 可选目标路径的组合。前缀过滤——什么时候用某个 namespace 下的子路径全要。写{ prefix: /repo3/** }。带**是递归匹配所有子仓库不带只匹配名字本身这是新手最容易搞混的一点。tag 正则 semver——什么时候用只想要某个版本系列。{ prefix: /repo1/repo, tags: { regex: 4.*, semver: true } }semver: true额外要求 tag 是合法的语义化版本能挡住4-rc-local这种正则误伤。排除正则——什么时候用上游堆了一堆架构后缀 tag只想留 index。{ prefix: /repo4/**, tags: { excludeRegex: .*-(amd64|arm64)$ } }路径改写——什么时候用上游和本地的命名规范对不上。{ prefix: /repo2/repo, destination: /repo, stripPrefix: true }⚠️ 容易配错的两处stripPrefix: true会把源路径里被前缀匹配到的部分切到**通配符为止剥掉再拼上destination。前缀不带**时本地仓库名就是destination本身不会保留任何子路径。想保留源路径要么stripPrefix: false结果是destination 完整源路径要么把前缀写成/repo2/**让子路径留在剥掉的部分里。镜像同步的底层执行链路不贴源码按谁在什么时候做什么走一遍启动时service.go 按registries[]逐条构建 sync Service凭证从credentialsFile读入。content.go 解析过滤规则回答三个问题同步哪些仓库、保留哪些 tag、落到本地叫什么名。定时同步调度器按pollInterval触发sync.go 里的任务生成器从远端/v2/_catalog逐个取仓库SyncRepo整仓同步失败会加倍等待再试。按需同步API 层发现本地没有该 manifest 时调用 on_demand.go 的SyncImage回源SyncReferrers顺带把签名、SBOM 一并拉回。复制不直接写正式存储先进 oci_layout.go 建的 OCI layout 临时区成功后由 destination.go 的CommitAll提交失败则清理临时区。临时区这套设计的价值正式存储里不会出现半成品进程中途挂掉也只留下可丢弃的临时目录。进阶参数默认值与生产建议参数默认值作用生产建议tlsVerifytrue是否校验上游 TLS 证书保持true私有 CA 用certDir指定certDirDocker 默认证书目录上游 CA 证书路径内部 CA 环境显式指定maxRetries不重试瞬时错误的最大重试次数3~5retryDelay未设置配maxRetries时必填初始重试间隔1s配maxRetryDelay做退避maxRetryDelay同retryDelay指数退避上限30s网络不稳的上游值得配syncTimeout3h单次同步操作总超时用默认即可别设得比上游自身超时还大onlySignedfalse定时 tag 同步只同步上游已签名的镜像有签名流水线的生产环境设trueplatforms空全平台定时同步只复制指定 OS/arch 的子节点只需 amd64 就设[linux/amd64]带宽直接减半manifestCheckInterval未设置每次查按需模式下同一 repo:tag 上游校验的最小间隔上游稳定时设1h省掉重复回源 按需高并发场景还有三个联动调优项reqConcurrent每主机并发默认 3、reqPerSec每主机限速默认不限、disableHTTP2。三者要配合才有效果具体组合关系在 config.go 的字段注释里写得很细。两个可以直接抄的生产场景场景 A3 Region 镜像分发拓扑。背景主 Region 跑权威 zot两个边缘 Region 需要就近缓存。 关键配置边缘侧urls指向主 Region两个边缘的pollInterval分别设1h和1h30m错峰避免同一时刻一起打主库的 catalog 接口。 效果边缘始终保有本地缓存跨区链路中断时业务照常拉取。场景 B生产只进已签名镜像。背景发布流水线要求 cosign 签名作为准入门槛同步层再兜一道。 关键配置onlySigned: true, content: [{ prefix: prod/**, tags: { regex: ^v[0-9]\\.[0-9]\\.[0-9]$ } }]效果没签名的镜像在同步层进不了生产且只有正式 semver 发布 tag 能通过。踩坑 FAQQpollInterval设成1m会怎样A它不是实时推送而是一分钟跑一轮全量扫描——遍历远端 catalog对每个 tag 做 HEAD 比对判断要不要同步。上游仓库上千时高频轮询纯属浪费而且单轮跑不完时实际频率还会自动降。生产建议1h起步配合标签过滤把扫描面压小。QdestinationstripPrefix为什么总得到意料之外的路径AstripPrefix: true时源路径被剥掉前缀切到通配符为止再拼destination。前缀不带**意味着整段被剥光本地仓库名就是destination。想保留子路径要么设false要么前缀写成/repo2/**。QonlySigned会不会把按需的 digest 拉取也挡掉A不会。只有定时的 tag 同步要求签名按需场景下客户端拿到 digest 后的拉取会跳过该检查因为签名通常盖在 index 上而不是每个架构子 manifest这样多架构的 tag→digest 流程才走得通。Q按需同步首次拉取太慢有优化手段吗A三档可选。onDemandInBackground: true让请求立刻返回 404、后台慢慢同步stream: true边下载边把流推给客户端要求 https且与maxRetries/retryDelay不兼容manifestCheckInterval减少重复查上游。默认是阻塞式这是体验最差但最稳的一档。Q私有仓库的凭证怎么给AcredentialsFile指向一个 JSON 文件以上游地址为 key、用户名密码为 value仓库里 examples/sync-auth-filepath.json 就是样例。云厂商的临时 token 不要手工维护用credentialHelper如 ecr、gcp或oauth2CredentialHelper自动续期。sync 扩展的定位就一条上游到本地的单向同步管道定时模式保存在按需模式兜长尾。想深入的话读 examples/README.md 里的 Sync 章节或者直接翻 pkg/extensions/sync/ 目录每个文件都对应链路里的一环。下一步建议在你的按需场景里把stream: true试起来首拉体验能差出秒和分钟的区别。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考