如何使用 GitHub Actions + image-syncer 实现 Docker Hub 到 Azure ACR 的自动化镜像同步

背景/引言HagiCode 项目使用 Docker 镜像作为核心运行时组件主要镜像托管在 Docker Hub。随着项目发展和 Azure 环境部署需求的增加我们遇到了以下痛点镜像拉取速度慢Docker Hub 在国内及部分 Azure 区域访问受限依赖单一镜像源存在单点故障风险Azure 环境下使用 Azure Container Registry 能获得更好的网络性能和集成体验为解决这些问题我们需要建立一个自动化的镜像同步机制将 Docker Hub 的镜像定期同步到 Azure ACR确保用户能够在 Azure 环境中获得更快的镜像拉取速度和更高的可用性。关于 HagiCode我们正在开发 HagiCode——一款 AI 驱动的代码智能助手让开发体验变得更智能、更便捷、更有趣。智能——AI 全程辅助从想法到代码让编码效率提升数倍。便捷——多线程并发操作充分利用资源开发流程顺畅无阻。有趣——游戏化机制和成就系统让编码不再枯燥充满成就感。项目正在快速迭代中如果你对技术写作、知识管理或者 AI 辅助开发感兴趣欢迎来 GitHub 看看。技术方案对比在制定解决方案时我们对比了多种技术方案1. image-syncer最终选择增量同步仅同步变更的镜像层显著减少网络传输断点续传网络中断后可恢复同步并发控制支持配置并发线程数提升大镜像同步效率完善的错误处理内置失败重试机制默认 3 次轻量级部署单二进制文件无依赖多仓库支持兼容 Docker Hub、Azure ACR、Harbor 等2. Docker CLI不支持增量同步每次都需要拉取完整的镜像内容效率较低网络传输量大时间长简单易用使用熟悉的 docker pull/push 命令3. Azure CLI复杂度高需要配置 Azure CLI 认证功能限制az acr import 功能相对单一原生集成与 Azure 服务集成良好架构设计决策决策 1同步频率设置为每日 UTC 00:00平衡镜像新鲜度和资源消耗避开业务高峰期减少对其他操作的影响Docker Hub 镜像通常在每日构建后更新决策 2同步所有镜像标签保持与 Docker Hub 的完全一致性为用户提供灵活的版本选择简化同步逻辑避免复杂的标签过滤规则决策 3使用 GitHub Secrets 存储认证信息GitHub Actions 原生支持安全性高配置简单易于管理和维护支持仓库级别的访问控制风险评估与缓解风险 1Azure ACR 认证信息泄露使用 GitHub Secrets 加密存储定期轮换 ACR 密码限制 ACR 用户权限为仅推送监控 ACR 访问日志风险 2同步失败导致镜像不一致image-syncer 内置增量同步机制自动失败重试默认 3 次详细的错误日志和失败通知断点续传功能风险 3资源消耗过大增量同步减少网络传输可配置并发线程数当前设置为 10监控同步的镜像数量和大小在非高峰时段运行同步核心解决方案我们采用 GitHub Actions image-syncer 的自动化方案实现从 Docker Hub 到 Azure ACR 的镜像同步。实施步骤1. 准备阶段在 Azure Portal 中创建或确认 Azure Container Registry创建 ACR 访问密钥用户名和密码确认 Docker Hub 镜像仓库访问权限2. 配置 GitHub Secrets在 GitHub 仓库设置中添加以下 SecretsAZURE_ACR_USERNAME: Azure ACR 用户名AZURE_ACR_PASSWORD: Azure ACR 密码3. 创建 GitHub Actions 工作流在 .github/workflows/sync-docker-acr.yml 中配置工作流定时触发每天 UTC 00:00手动触发支持 workflow_dispatch额外触发publish 分支推送时触发用于快速同步4. 工作流执行流程Azure ACRDocker Hubimage-syncerGitHub ActionsAzure ACRDocker Hubimage-syncerGitHub Actions触发工作流增量同步仅传输变更的镜像层下载并执行 image-syncer获取镜像 manifest 和标签列表返回镜像元数据获取已存在的镜像信息返回目标镜像信息对比差异识别变更的镜像层拉取变更的镜像层返回镜像层内容推送变更的镜像层到 ACR返回推送结果返回同步统计信息记录同步日志并上传 artifactGitHub Actions 工作流实现以下是实际运行的工作流配置.github/workflows/sync-docker-acr.ymlname: Sync Docker Image to Azure ACRon:schedule:- cron: 0 0 * * * # 每天 UTC 00:00workflow_dispatch: # 手动触发push:branches: [publish]permissions:contents: readjobs:sync:runs-on: ubuntu-lateststeps:- name: Checkout codeuses: actions/checkoutv4- name: Download image-syncerrun: |# 下载 image-syncer 二进制文件wget https://github.com/AliyunContainerService/image-syncer/releases/download/v1.5.5/image-syncer-v1.5.5-linux-amd64.tar.gztar -zxvf image-syncer-v1.5.5-linux-amd64.tar.gzchmod x image-syncer- name: Create auth configrun: |# 生成认证配置文件 (YAML 格式)cat auth.yaml EOFhagicode.azurecr.io:username: ${{ secrets.AZURE_ACR_USERNAME }}password: ${{ secrets.AZURE_ACR_PASSWORD }}EOF- name: Create images configrun: |# 生成镜像同步配置文件 (YAML 格式)cat images.yaml EOFdocker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicodeEOF- name: Run image-syncerrun: |# 执行同步 (使用新版 --auth 和 --images 参数)./image-syncer --auth./auth.yaml --images./images.yaml --proc10 --retries3- name: Upload logsif: always()uses: actions/upload-artifactv4with:name: sync-logspath: image-syncer-*.logretention-days: 7配置说明1. 触发条件定时触发cron: 0 0 * * * - 每天 UTC 00:00 执行手动触发workflow_dispatch - 允许用户在 GitHub UI 手动运行推送触发push: branches: [publish] - 发布分支推送时触发用于快速同步2. 认证配置 (auth.yaml)hagicode.azurecr.io:username: ${{ secrets.AZURE_ACR_USERNAME }}password: ${{ secrets.AZURE_ACR_PASSWORD }}3. 镜像同步配置docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode此配置表示将 docker.io/newbe36524/hagicode 的所有标签同步到 hagicode.azurecr.io/hagicode4. image-syncer 参数--auth./auth.yaml: 认证配置文件路径--images./images.yaml: 镜像同步配置文件路径--proc10: 并发线程数为 10--retries3: 失败重试 3 次GitHub Secrets 配置清单在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置Secret 名称描述示例值获取方式AZURE_ACR_USERNAMEAzure ACR 用户名hagicodeAzure Portal → ACR → Access keysAZURE_ACR_PASSWORDAzure ACR 密码xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxAzure Portal → ACR → Access keys → Password使用说明1. 手动触发同步访问 GitHub 仓库的 Actions 标签页选择 Sync Docker Image to Azure ACR 工作流点击 Run workflow 按钮选择分支并点击 Run workflow 确认2. 查看同步日志在 Actions 页面点击具体的工作流运行记录查看各个步骤的执行日志在页面底部的 Artifacts 区域下载 sync-logs 文件3. 验证同步结果# 登录到 Azure ACRaz acr login --name hagicode# 列出镜像及其标签az acr repository show-tags --name hagicode --repository hagicode --output table注意事项和最佳实践1. 安全建议定期轮换 Azure ACR 密码建议每 90 天使用专用的 ACR 服务账户限制权限为仅推送监控 ACR 的访问日志及时发现异常访问不要在日志中输出认证信息不要将认证信息提交到代码仓库2. 性能优化调整 --proc 参数根据网络带宽调整并发数建议 5-20监控同步时间如果同步时间过长考虑减少并发数定期清理日志设置合理的 retention-days当前为 7 天3. 故障排查问题 1认证失败Error: failed to authenticate to hagicode.azurecr.io解决方案检查 GitHub Secrets 是否正确配置验证 Azure ACR 密码是否过期确认 ACR 服务账户权限是否正确问题 2网络超时Error: timeout waiting for response解决方案检查网络连接减少并发线程数--proc 参数等待网络恢复后重新触发工作流问题 3镜像同步不完整Warning: some tags failed to sync解决方案检查同步日志识别失败的标签手动触发工作流重新同步验证 Docker Hub 源镜像是否正常4. 监控和告警定期检查 Actions 页面确认工作流运行状态设置 GitHub 通知及时获取工作流失败通知监控 Azure ACR 的存储使用情况定期验证镜像标签一致性常见问题和解决方案Q1: 如何同步特定标签而不是所有标签修改 images.yaml 配置文件# 仅同步 latest 和 v1.0 标签docker.io/newbe36524/hagicode:latest: hagicode.azurecr.io/hagicode:latestdocker.io/newbe36524/hagicode:v1.0: hagicode.azurecr.io/hagicode:v1.0Q2: 如何同步多个镜像仓库在 images.yaml 中添加多行配置docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicodedocker.io/newbe36524/another-image: hagicode.azurecr.io/another-imageQ3: 同步失败后如何重试自动重试image-syncer 内置重试机制默认 3 次手动重试在 GitHub Actions 页面点击 Re-run all jobsQ4: 如何查看同步的详细进度在 Actions 页面查看实时日志下载 sync-logs artifact 查看完整日志文件日志文件包含每个标签的同步状态和传输速度Q5: 同步需要多长时间首次全量同步根据镜像大小通常需要 10-30 分钟增量同步如果镜像变更小通常 2-5 分钟时间取决于网络带宽、镜像大小和并发设置扩展功能建议1. 添加同步通知在工作流中添加通知步骤- name: Notify on successif: success()run: |echo Docker images synced successfully to Azure ACR2. 实现镜像标签过滤在工作流中添加标签过滤逻辑- name: Filter tagsrun: |# 仅同步以 v 开头的标签echo docker.io/newbe36524/hagicode:v* : hagicode.azurecr.io/hagicode:v* images.yaml3. 添加同步统计报告- name: Generate reportif: always()run: |echo ## Sync Report $GITHUB_STEP_SUMMARYecho - Total tags: $(grep -c synced image-syncer-*.log) $GITHUB_STEP_SUMMARYecho - Sync time: ${{ steps.sync.outputs.duration }} $GITHUB_STEP_SUMMARY总结通过本文介绍的方法我们成功实现了从 Docker Hub 到 Azure ACR 的自动化镜像同步。这个方案利用 GitHub Actions 的定时触发和手动触发功能结合 image-syncer 的增量同步和错误处理机制确保了镜像的及时同步和一致性。我们还讨论了安全最佳实践、性能优化、故障排查等方面的内容帮助用户更好地管理和维护这个同步机制。希望本文能够为需要在 Azure 环境中部署 Docker 镜像的开发者提供有价值的参考。参考资料HagiCode 项目 GitHub 仓库image-syncer 官方文档Azure Container Registry 官方文档GitHub Actions 官方文档互动引导感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮,让更多的人看到本文。