GitHub Actions实现Docker Hub到ACR镜像自动同步方案

1. 项目概述

在容器化部署的现代开发流程中，镜像仓库的同步管理是个高频痛点。我最近用GitHub Actions配合image-syncer工具搭建了一套从Docker Hub到Azure Container Registry（ACR）的自动化同步方案，完美解决了跨国镜像拉取慢、多环境部署一致性的问题。这个方案特别适合需要同时使用公有和私有镜像仓库的团队，下面就把完整实现过程拆解给大家。

2. 核心组件解析

2.1 GitHub Actions 工作流

GitHub Actions的自动化触发机制是我们的流水线基础。通过监听代码仓库的push事件或定时任务，可以自动执行镜像同步操作。其优势在于：

• 与GitHub生态无缝集成
• 每月2000分钟的免费额度足够中小规模使用
• 支持矩阵构建等高级特性

2.2 image-syncer 工具选型

对比过skopeo、docker pull/push等方案后，最终选择阿里开源的image-syncer主要因为：

• 单二进制文件部署简单
• 支持多架构镜像同步
• 内置重试机制应对网络波动
• 配置文件驱动，易于版本化管理

2.3 仓库服务对比

3. 完整实现步骤

3.1 环境准备

首先在Azure Portal创建ACR实例：

bash复制az acr create --resource-group myRG --name myRegistry --sku Basic

获取ACR管理员密码（后续配置用）：

bash复制az acr credential show --name myRegistry --query "passwords[0].value"

3.2 配置文件编写

创建sync-config.yaml定义同步规则：

yaml复制auth:
  docker.io: 
    username: $DOCKERHUB_USER
    password: $DOCKERHUB_PASS
  myregistry.azurecr.io:
    username: $ACR_USER
    password: $ACR_PASS

images:
  "library/nginx":
    - "myregistry.azurecr.io/library/nginx"
  "grafana/grafana":
    - "myregistry.azurecr.io/third-party/grafana"

安全提示：永远不要在配置文件中硬编码密码，应该使用GitHub Secrets

3.3 GitHub Actions 工作流

在.github/workflows/sync-images.yml中定义：

yaml复制name: Sync DockerHub to ACR

on:
  schedule:
    - cron: '0 3 * * *'  # 每天UTC时间3点执行
  workflow_dispatch:     # 支持手动触发

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Download image-syncer
        run: |
          wget https://github.com/AliyunContainerService/image-syncer/releases/download/v1.3.0/image-syncer-v1.3.0-linux-amd64.tar.gz
          tar -xzf image-syncer*.tar.gz
          
      - name: Run sync
        env:
          DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}
          DOCKERHUB_PASS: ${{ secrets.DOCKERHUB_TOKEN }}
          ACR_USER: ${{ secrets.ACR_USER }}
          ACR_PASS: ${{ secrets.ACR_PASS }}
        run: |
          ./image-syncer --proc=4 --retries=3 --config=sync-config.yaml

4. 高级配置技巧

4.1 增量同步优化

通过--records参数记录同步状态，下次运行时只同步新版本：

bash复制./image-syncer --records=records.txt --config=config.yaml

4.2 网络调优

对于大镜像同步，建议：

1. 使用Azure香港区域ACR（网络延迟最低）
2. 在Actions中设置超时时间：

yaml复制timeout-minutes: 30

4.3 安全加固方案

• 为ACR创建专用服务主体（非管理员账号）
• 使用Docker Hub的Access Token代替密码
• 配置ACR网络规则限制IP访问范围

5. 常见问题排查

5.1 认证失败

错误现象：

code复制failed to authorize: failed to fetch oauth token: unexpected status: 401 Unauthorized

解决方案：

1. 检查ACR密码是否过期（默认180天）
2. 确认Docker Hub账号未启用2FA

5.2 网络超时

错误现象：

code复制Get "https://registry-1.docker.io/v2/": net/http: request canceled

优化方案：

1. 增加重试次数 --retries=5
2. 使用代理服务器（需符合企业网络政策）

5.3 存储空间不足

ACR基础版默认10GB存储，可通过以下命令查看用量：

bash复制az acr show-usage --name myRegistry --output table

清理旧镜像策略：

yaml复制# 在sync-config.yaml中添加
cleanup: true
keep: 3  # 保留最近3个版本

6. 生产环境建议

经过三个月的生产环境运行，总结出以下最佳实践：

1. 镜像标签尽量使用语义化版本（避免latest）
2. 为不同业务线创建独立的同步任务
3. 监控同步任务耗时（超过15分钟需优化）
4. 定期清理测试镜像（可设置保留策略）

对于需要同步上百个镜像的大型项目，建议：

• 使用Go模板批量生成sync-config.yaml
• 按镜像类型分批次同步
• 考虑使用Azure Pipeline增加并发能力