regsync 镜像文档

镜像概述和主要用途

regsync 是一款 OCI 兼容容器注册表同步工具，用于实现镜像仓库之间的自动同步与更新。其核心功能是根据配置规则将源注册表中的镜像（或仓库）同步至目标注册表，适用于企业内部镜像仓库管理、多区域镜像分发、第三方依赖镜像备份等场景。

核心功能和特性

• OCI 兼容性：全面支持符合 OCI 规范的容器注册表（如 Docker Hub、Harbor、AWS ECR、Google GCR 等）。
• 多类型同步：支持单镜像（image）和整个仓库（repository）两种同步模式，满足不同规模的同步需求。
• 灵活的标签管理：通过正则表达式筛选需同步的镜像标签，支持精细化标签控制。
• 智能速率限制：内置速率限制机制，可配置最小剩余请求数和重试间隔，避免触发源注册表 API 限制。
• 并行与定时同步：支持多任务并行处理，提升同步效率；服务模式下可配置定时同步间隔，实现自动化运维。
• 凭据管理：支持环境变量、文件、TLS 配置等多种凭据方式，适配不同注册表的认证需求。
• 轻量级镜像选项：提供基于 scratch（最小镜像，无额外依赖）和 alpine（含基础工具及云服务商凭据助手）的镜像版本，适配不同部署环境。

使用场景和适用范围

• 企业内部镜像仓库同步：将外部公共镜像（如 Docker Hub）同步至内部私有仓库，降低外部依赖，提升访问速度。
• 跨区域镜像分发：在多区域部署的注册表间同步镜像，实现就近访问，减少跨区域网络延迟。
• 第三方镜像备份：定期同步关键依赖镜像（如基础操作系统、工具链镜像）至本地仓库，防止第三方注册表故障或镜像删除导致的业务中断。
• CI/CD 流水线集成：作为构建前置步骤，确保流水线所需镜像已同步至本地，加速构建过程并保障环境一致性。

镜像标签说明

regsync 提供以下镜像标签，用于区分版本和基础镜像类型：

注意：scratch 镜像不含 shell 和凭据助手，仅适用于简单同步场景；alpine 镜像基于发布时的最新 alpine 版本构建，包含 AWS 和 Google Cloud 的凭据助手，适用于云环境部署。

快速开始指南

前提条件

• Docker 引擎（20.10+）
• 本地或远程 OCI 兼容容器注册表（如 Docker Registry、Harbor 等）

步骤 1：部署本地测试注册表

首先创建本地 Docker 注册表用于验证同步功能：

shell
# 创建专用网络（用于 regsync 与注册表通信）
docker network create registry

# 启动注册表容器（支持删除操作和禁用验证，便于测试）
docker run -d --restart=unless-stopped --name registry --net registry \
  -e "REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry" \
  -e "REGISTRY_STORAGE_DELETE_ENABLED=true" \
  -e "REGISTRY_VALIDATION_DISABLED=true" \
  -v "registry-data:/var/lib/registry" \
  -p "127.0.0.1:5000:5000" \
  registry:2

步骤 2：创建同步配置文件

创建 regsync.yml 配置文件，定义同步规则（示例配置同步 Docker Hub 镜像至本地注册表）：

yaml
version: 1  # 配置文件版本（当前仅支持 1）
creds:  # 注册表凭据列表
  - registry: registry:5000  # 目标注册表（本地测试注册表）
    tls: disabled  # 本地注册表默认不启用 TLS，需禁用
    scheme: http  # 使用 HTTP 协议
  - registry: docker.io  # 源注册表（Docker Hub）
    user: "{{env \"HUB_USER\"}}"  # 从环境变量获取 Docker Hub 用户名
    pass: "{{file \"/var/run/secrets/hub_token\"}}"  # 从文件获取 Docker Hub 密码或访问令牌
defaults:  # 全局默认配置（可被同步规则局部覆盖）
  ratelimit:  # 速率限制
    min: 100  # 最小剩余请求数，低于此值时触发限流
    retry: 15m  # 限流后重试间隔
  parallel: 2  # 并行同步任务数
  interval: 60m  # 定时同步间隔（服务模式下生效）
  backup: "bkup-{{.Ref.Tag}}"  # 目标镜像更新前的备份标签格式（Go 模板语法）
sync:  # 同步规则列表
  # 同步单镜像
  - source: busybox:latest  # 源镜像（Docker Hub 的 busybox:latest）
    target: registry:5000/library/busybox:latest  # 目标镜像（本地注册表）
    type: image  # 同步类型：单镜像
  # 同步仓库（筛选标签）
  - source: alpine  # 源仓库（Docker Hub 的 alpine）
    target: registry:5000/library/alpine  # 目标仓库（本地注册表）
    type: repository  # 同步类型：仓库
    tags:  # 标签筛选规则
      allow:  # 允许同步的标签（支持正则表达式）
      - "latest"  # 最新标签
      - "3"  # 主版本 3
      - "3\\.\\d+"  # 次版本 3.x（如 3.18、3.19 等）
  # 同步工具镜像
  - source: regclient/regctl:latest  # 源镜像（Docker Hub 的 regctl:latest）
    target: registry:5000/regclient/regctl:latest  # 目标镜像（本地注册表）
    type: image  # 同步类型：单镜像

步骤 3：准备 Docker Hub 凭据

创建 hub_token 文件，存入 Docker Hub 密码或个人访问令牌（PAT，推荐使用 PAT 并限制权限）：

shell
echo "your_docker_hub_password_or_pat" > hub_token
chmod 600 hub_token  # 限制文件权限，防止敏感信息泄露

步骤 4：测试同步（一次性模式）

使用 once 模式运行 regsync，执行单次同步验证配置：

shell
docker run -it --rm --net registry \
  -v "$(pwd)/regsync.yml:/home/appuser/regsync.yml:ro" \  # 挂载配置文件
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \  # 挂载凭据文件
  -e "HUB_USER=your_docker_hub_username" \  # 传入 Docker Hub 用户名环境变量
  regclient/regsync:latest -c /home/appuser/regsync.yml once  # 指定配置文件，运行一次性同步

说明：命令将从 Docker Hub 拉取配置的源镜像并同步至本地注册表。若 Docker Hub 速率限制（免费用户有拉取限制），工具会根据 ratelimit 配置自动限流和重试。

步骤 5：部署为服务（定时同步）

确认一次性同步正常后，部署 regsync 为后台服务，启用定时同步：

shell
docker run -d --restart=unless-stopped --name regsync --net registry \
  -v "$(pwd)/regsync.yml:/home/appuser/regsync.yml:ro" \
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \
  -e "HUB_USER=your_docker_hub_username" \
  regclient/regsync:latest -c /home/appuser/regsync.yml server  # 以服务模式运行（定时同步）

查看服务日志：

shell
docker logs regsync

注意：服务模式下，日志默认仅在同步任务执行时输出。根据 defaults.interval 配置，每 60 分钟执行一次同步。

验证同步结果

从本地注册表拉取同步后的镜像，验证同步效果：

shell
docker run -it --rm localhost:5000/library/busybox echo "同步成功"

配置文件详解

regsync 通过 YAML 配置文件定义同步规则，核心结构如下：

version

• 类型：整数
• 说明：配置文件版本，当前仅支持 1。

creds

• 类型：数组
• 说明：注册表凭据列表，配置源和目标注册表的访问信息。每个凭据项包含：
  • registry：注册表域名或地址（如 docker.io、registry:5000）。
  • scheme：协议类型，可选 http 或 https（默认 https）。
  • tls：TLS 配置，可选 enabled（默认）或 disabled。
  • user：用户名，支持模板语法（如 {{env "USER"}} 从环境变量获取）。
  • pass：密码或访问令牌，支持模板语法（如 {{file "/path/to/token"}} 从文件获取）。

defaults

• 类型：对象
• 说明：全局默认配置，可被同步规则中的局部配置覆盖。包含：
  • ratelimit：速率限制
    • min：最小剩余请求数，低于此值时暂停同步。
    • retry：重试间隔（如 15m、1h）。
  • parallel：并行同步任务数（默认 1）。
  • interval：定时同步间隔（服务模式下，如 30m、2h）。
  • backup：目标镜像更新前的备份标签格式，使用 Go 模板语法（如 "backup-{{.Ref.Tag}}"）。
  • timeout：单次同步任务超时时间（如 10m）。

sync

• 类型：数组
• 说明：同步规则列表，每个规则定义一组源到目标的同步配置。包含：
  • source：源镜像/仓库，格式为 [registry/][namespace/]name[:tag]（如 busybox:latest、docker.io/library/alpine）。
  • target：目标镜像/仓库，格式同上。
  • type：同步类型，可选 image（单镜像）或 repository（仓库，同步匹配标签的所有镜像）。
  • tags：标签筛选规则（仅 type: repository 时生效），包含：
    • allow：允许同步的标签列表（支持正则表达式，如 "3\\.\\d+"）。
    • deny：拒绝同步的标签列表（优先级高于 allow）。
  • interval：局部定时同步间隔，覆盖全局 defaults.interval。
  • parallel：局部并行任务数，覆盖全局 defaults.parallel。

部署示例

一次性同步模式（测试用）

shell
docker run -it --rm \
  --net registry \  # 连接到注册表所在网络（若注册表在同一网络）
  -v "$(pwd)/regsync.yml:/regsync.yml:ro" \  # 挂载配置文件
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \  # 挂载凭据文件
  -e "HUB_USER=your_username" \  # 传入环境变量
  regclient/regsync:latest -c /regsync.yml once  # 指定配置文件，运行一次性同步

服务模式（后台定时同步）

shell
docker run -d --restart=unless-stopped --name regsync \
  --net registry \
  -v "$(pwd)/regsync.yml:/regsync.yml:ro" \
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \
  -e "HUB_USER=your_username" \
  regclient/regsync:latest -c /regsync.yml server  # 以服务模式运行

Docker Compose 部署示例

创建 docker-compose.yml：

yaml
version: "3.8"
services:
  regsync:
    image: regclient/regsync:latest
    container_name: regsync
    restart: unless-stopped
    networks:
      - registry-net  # 连接到注册表所在网络
    volumes:
      - ./regsync.yml:/regsync.yml:ro  # 挂载配置文件
      - ./hub_token:/var/run/secrets/hub_token:ro  # 挂载凭据文件
    environment:
      - HUB_USER=your_docker_hub_username  # Docker Hub 用户名
    command: -c /regsync.yml server  # 服务模式启动

networks:
  registry-net:
    external: true  # 假设已创建名为 registry 的网络（同步骤 1）

启动服务：

shell
docker-compose up -d

环境变量和凭据管理

regsync 支持通过模板语法动态获取凭据，常用方式：

• 环境变量：{{env "VAR_NAME"}}，从容器环境变量中获取值（如 HUB_USER）。
• 文件内容：{{file "/path/to/file"}}，读取文件内容作为值（如 Docker Hub 访问令牌文件）。
• 云服务商凭据：alpine 镜像内置 AWS 和 Google Cloud 凭据助手，可自动从环境变量或实例元数据服务获取凭据（需配置对应云服务 IAM 权限）。

重要链接

• 项目官网：regclient.org
• 安装指南：regclient.org/install/
• 命令行参考：regclient.org/cli/regsync/
• 源代码：github.com/regclient/regclient
• 发布版本：github.com/regclient/regclient/releases
• 贡献指南：github.com/regclient/regclient/blob/main/CONTRIBUTING.md