docker/go-tuf-mirror

TUF元数据OCI仓库镜像同步工具镜像

概述

本镜像提供了在OCI（开放容器倡议）容器镜像仓库之间镜像和同步TUF（The Update Framework）元数据的功能。TUF元数据是保障软件更新分发安全性的核心组件，负责验证更新包的完整性、真实性和时效性。通过本镜像，用户可便捷地在多个OCI仓库（如Docker Hub、Harbor、AWS ECR、Google Artifact Registry等）之间实现TUF元数据的双向同步，确保跨环境、跨平台的软件更新流程安全可靠。

核心功能与特性

核心功能

• 双向元数据同步：支持从源OCI仓库向目标仓库单向同步，或实现多仓库间的双向同步
• TUF元数据验证：同步过程中自动验证TUF元数据的签名和完整性，拒绝篡改或无效元数据
• 多OCI仓库支持：兼容主流OCI规范仓库，包括公有云仓库（AWS ECR、GCP GAR等）和私有仓库（Harbor、Nexus等）
• 增量同步：仅同步变更的TUF元数据文件，减少网络传输和存储开销
• 配置驱动：通过环境变量或配置文件灵活定义同步规则、认证方式和调度策略

关键特性

• 安全性：内置TUF规范兼容的验证逻辑，支持私钥加密存储和安全认证
• 可靠性：失败重试机制和同步状态记录，确保同步过程可追溯
• 轻量级：基于Alpine Linux构建，镜像体积小，资源占用低
• 可扩展性：支持自定义钩子脚本，集成告警、日志等外部系统

使用场景

企业多仓库管理

• 企业内部同时维护生产、测试、开发环境的OCI仓库时，通过本镜像同步TUF元数据，确保各环境更新策略一致

跨云环境部署

• 在混合云或多云架构中（如AWS+Azure+私有云），统一管理不同云厂商OCI仓库的TUF元数据，避免更新策略碎片化

备份与容灾

• 将核心TUF元数据从主仓库同步到备用仓库，实现元数据备份，提升系统容灾能力

CI/CD集成

• 在软件发布流程中自动同步TUF元数据至分发仓库，确保新版本更新包与元数据同步上线

使用方法

获取镜像

从Docker Hub或私有仓库拉取镜像：

bash
docker pull [镜像仓库地址]/tuf-mirror-oci:latest

（注：请替换[镜像仓库地址]为实际镜像存放地址，如官方仓库或企业私有仓库）

基本使用命令

通过docker run执行同步任务，需指定源仓库和目标仓库信息：

bash
docker run --rm \
  -e SOURCE_REGISTRY="https://source-registry.example.com" \
  -e SOURCE_USER="source-user" \
  -e SOURCE_PASSWORD="source-pass" \
  -e TARGET_REGISTRY="https://target-registry.example.com" \
  -e TARGET_USER="target-user" \
  -e TARGET_PASSWORD="target-pass" \
  [镜像仓库地址]/tuf-mirror-oci:latest sync

配置参数说明

通过环境变量或挂载配置文件（/app/config.yaml）定义同步参数，常用环境变量如下：

Docker Compose示例

创建docker-compose.yml实现持久化配置和后台运行：

yaml
version: '3.8'
services:
  tuf-mirror:
    image: [镜像仓库地址]/tuf-mirror-oci:latest
    restart: unless-stopped
    environment:
      - SOURCE_REGISTRY=https://primary-harbor.example.com
      - SOURCE_USER=sync-user
      - SOURCE_PASSWORD=${SOURCE_PWD}  # 建议通过.env文件注入敏感信息
      - TARGET_REGISTRY=https://backup-harbor.example.com
      - TARGET_USER=sync-user
      - TARGET_PASSWORD=${TARGET_PWD}
      - SYNC_INTERVAL=1800  # 30分钟同步一次
      - LOG_LEVEL=info
    volumes:
      - ./tuf-root:/app/tuf-root  # 挂载本地TUF根元数据目录
      - ./config.yaml:/app/config.yaml  # 可选：挂载自定义配置文件

启动服务：

bash
docker-compose up -d

常见操作示例

1. 单次从源仓库同步到目标仓库

bash
docker run --rm \
  -e SOURCE_REGISTRY=https://source-registry:5000 \
  -e SOURCE_TOKEN=source-auth-token \
  -e TARGET_REGISTRY=https://target-registry:5000 \
  -e TARGET_TOKEN=target-auth-token \
  -e SYNC_INTERVAL=0 \  # 单次同步
  [镜像仓库地址]/tuf-mirror-oci:latest sync

2. 验证目标仓库元数据与源仓库一致性

bash
docker run --rm \
  -e SOURCE_REGISTRY=https://source-registry:5000 \
  -e TARGET_REGISTRY=https://target-registry:5000 \
  [镜像仓库地址]/tuf-mirror-oci:latest verify

3. 使用自定义配置文件同步

创建config.yaml：

yaml
source:
  registry: https://primary-registry.example.com
  auth:
    type: token
    token: "source-token-here"
targets:
  - registry: https://backup-registry.example.com
    auth:
      type: basic
      user: "backup-user"
      password: "backup-pass"
  - registry: https://dr-registry.example.com  # 支持多个目标仓库
    auth:
      type: token
      token: "dr-token-here"
sync:
  interval: 3600
  verify: true
  include_expired: false  # 不同步已过期的TUF元数据

执行同步：

bash
docker run --rm \
  -v ./config.yaml:/app/config.yaml \
  [镜像仓库地址]/tuf-mirror-oci:latest sync --config /app/config.yaml

注意事项

• 权限要求：同步用户需具备源仓库的读权限和目标仓库的写权限
• 网络连通性：确保容器能够同时访问源仓库和目标仓库（注意防火墙、网络策略限制）
• TUF根元数据：首次同步时需确保TUF根元数据（root.json）可信，建议通过安全渠道获取并验证
• 敏感信息：避免在命令行直接暴露密码/令牌，优先使用环境变量文件（如.env）或密钥管理服务（如Vault）注入
• 版本兼容性：确保源/目标仓库的TUF元数据版本兼容（建议使用TUF 1.0及以上规范）