国内 Docker 镜像拉取终极解决方案：GitHub（第一节）

超快路径

代码仓库： 可以直接fork， 然后设置按照 即可

前言

作为国内开发者和运维人员，我们正面临一个日益严峻的挑战：曾经是全球 Docker 镜像中心的 Docker Hub，如今在国内的访问变得异常艰难，甚至完全无法连接。那些曾经为我们提供便利的公共 Docker 镜像加速器，也大多已失去其加速作用，沦为历史。

这不仅仅是下载速度慢的问题，更是 CI/CD 流水线中断、开发效率骤降的根本原因。每一次 docker pull 的超时，每一次 docker build 的失败，都在无情地消耗着我们的耐心和项目进度。

本文将提供一个稳定、高效且完全自动化的解决方案，帮助你彻底摆脱这一困境。我们将利用 GitHub Actions 的全球化执行能力作为“桥梁”，将所需的 Docker 镜像自动化同步到国内可高速访问的 阿里云容器镜像服务 (ACR)。告别网络延迟，享受丝滑的 Docker 体验！

---

1. 引言

1.1 当 Docker 镜像加速节点成为“历史”

在国内进行 Docker 开发和 CI/CD，一个令人头疼的现实是：曾经赖以生存的 Docker Hub 及其他海外镜像源，现在变得越来越难以访问。曾经寄予厚望的各类公共 Docker 镜像加速器（如 DaoCloud、Ustc 等）也大多已成往事，其稳定性和速度已无法满足日常开发和生产环境的需求。

这意味着什么？这意味着你的 docker pull 命令可能长时间卡顿，docker build 任务屡次失败，CI/CD 流水线因基础镜像无法拉取而被迫中断。这些并非短暂的网络波动，而是长期困扰国内开发者和企业用户的普遍性挑战，严重拖慢了项目进度，消耗了宝贵的开发时间。

1.2 构建你的专属高速镜像通道

那么，有没有一个兼顾稳定、高效、自动化，并且符合国内网络环境特点的解决方案呢？

本文将为你揭示并详细实践一个行之有效的方法：利用 GitHub Actions 的全球化执行环境作为“中转站”，将所需的 Docker 镜像自动化同步到国内高速可达的 阿里云容器镜像服务 (ACR)。这不仅能彻底解决镜像拉取慢、无法访问的问题，还能为你的 CI/CD 流水线注入前所未有的稳定性和速度。

1.3 摆脱困境，畅享 Docker 开发

通过阅读本文，你将学会如何：

• 配置 GitHub Actions 与 Aliyun ACR 的无缝集成，搭建安全可靠的自动化通道。
• 编写并优化自动化 Workflow，实现指定 Docker 镜像的基于配置更新或手动同步。
• 为自己或团队构建一个稳定、高速且完全可控的国内 Docker 镜像缓存，彻底摆脱对外部镜像源的依赖。

告别焦急的等待和失败的构建，让我们一起动手，为你的 Docker 开发和 CI/CD 流程重新焕发活力！

---

2. 问题分析与传统解决方案的局限性

在探讨解决方案之前，我们有必要深入剖析 Docker 镜像访问困境的根源，并理解为什么传统方案已无法满足当前需求。

2.1 Docker 镜像访问困境的根源

• 国际网络环境复杂： 国内与海外的网络连接受多种因素影响，导致对 Docker Hub、、Google Container Registry () 等主流海外镜像源的访问不稳定，时常出现连接中断、速度缓慢等问题。
• CI/CD 流水线受阻： 在自动化构建和部署场景中，基础镜像的拉取是第一步。一旦这一步失败，整个流水线将无法继续，导致频繁的构建失败和部署延迟，严重影响开发和交付效率。
• 公共加速器失效： 过去，一些国内的公共 Docker 镜像加速器曾提供便利。然而，由于政策、维护成本或网络环境变化等原因，这些加速器大多已停止服务或效果甚微，不再能提供可靠的加速服务。

2.2 传统解决方案的局限性

面对上述挑战，开发者们曾尝试过多种方案，但它们往往存在各自的局限性：

• 手动下载与导入 (docker save/docker load)：
• 弊端： 极其繁琐，无法自动化，不适用于频繁更新的镜像和 CI/CD 场景。

• 配置 Docker 镜像加速器（如 DaoCloud、Ustc 等）：
• 弊端： 多数已失效或速度不佳，无法提供长期稳定的保障。

• 企业内部搭建 Registry 或 Proxy：
• 弊端： 成本高昂（需要服务器资源和维护人力），部署复杂，且其自身仍然需要解决拉取上游镜像的问题。

• VPN/代理：
• 弊端： 不稳定，速度受限，部分存在合规性和法律风险，最重要的是，难以在无头（Headless）的 CI/CD 环境中稳定、安全地集成和运行。

正是这些传统方案的力不从心，促使我们寻找一个更稳定、高效、自动化且符合国内网络环境的最佳实践。

---

3. 解决方案概览：GitHub Actions + Aliyun ACR

在深入实践之前，我们首先需要理解这个解决方案的核心理念，以及它如何巧妙地规避现有难题，从而带来显著的优势。

3.1 核心理念：跨越网络屏障，构建高速缓存

我们的方案基于以下两个关键组件的协同作用：

1. GitHub Actions 作为“跳板”/“中转站”： GitHub Actions 的执行环境（即 Runner）通常部署在全球各地，特别是海外数据中心。这意味着，GitHub Actions 的 Runner 拥有直接、高速访问 Docker Hub 或其他海外 Docker 镜像源的能力，不受国内网络环境的直接影响。我们正是利用这一点，让 GitHub Actions 代劳，从那些难以访问的源头拉取所需的 Docker 镜像。它就像是你部署在海外的一个“自动化代理”，专门为你去“搬运”镜像。
2. Aliyun ACR 作为“国内高速缓存”： 阿里云容器镜像服务 (ACR) 是阿里云提供的稳定、高性能的容器镜像管理服务。其所有服务节点都部署在中国境内。一旦 GitHub Actions Runner 成功从 Docker Hub 拉取到镜像，我们就可以将其推送到你的专属 ACR 仓库中。这样，当你或你的国内 CI/CD 环境需要这些镜像时，可以直接从国内的 ACR 高速拉取，彻底摆脱了国际网络瓶颈的困扰。ACR 在这里扮演的角色，是一个持久化、高可用的“本地化镜像缓存”。
3. 自动化：一劳永逸的同步机制： 整个同步过程可以通过 GitHub Actions 的灵活触发机制（例如代码推送 push 来触发，尤其是当你更新 images.txt 配置时，或手动触发 workflow_dispatch）来实现高度自动化。一旦配置完成，你只需更新配置文件或手动点击，系统即可自动检查并同步最新的镜像版本。这大大减少了人工维护成本，并确保了镜像的及时更新和可用性。

3.2 流程图

国内使用镜像同步流程触发机制Docker 镜像源Git Push 触发用户点击海外网络拉取GitHub Actions 推送国内高速拉取Docker Hub / Quay.io / GCR.io / 其他源代码提交 / images.txt更新GitHub Actions Runner  海外服务器手动触发 workflow_dispatch阿里云 ACR 个人版开发者 / 国内CI/CD

3.3 方案优势：免费、稳定、自动化

通过 GitHub Actions 和 Aliyun ACR 的强强联合，我们的方案具备以下显著优势：

1. 成本效益：
   

• GitHub Actions： 提供慷慨的免费额度（每月 2000 分钟的 Linux Runner），对于个人项目和小型团队而言，通常足以满足日常同步需求。
• Aliyun ACR： 个人版提供基础功能免费额度，包括一定的存储空间和公网下行流量，对于存储少量常用镜像来说，通常费用极低甚至免费。超出额度或使用高级功能才会产生费用。

1. 稳定可靠： 该方案巧妙地将“海外拉取”和“国内分发”解耦，各司其职。GitHub Actions 解决了国际网络访问问题，ACR 提供了国内高速分发能力。这从根本上绕开了困扰国内开发者的网络限制，确保了镜像访问的稳定性和可靠性，避免了因网络波动或加速器失效导致的构建中断。
2. 高度自动化： 利用 GitHub Actions 的自动化能力，你可以通过更新配置或手动触发来同步镜像，确保你的镜像库始终保持最新状态，让你能够“设置一次，按需同步”。
3. 易于部署与维护： GitHub Actions 和 Aliyun ACR 都是成熟的云服务和 CI/CD 工具，拥有完善的文档和友好的用户界面。你无需搭建复杂的私有镜像代理服务器或维护底层的基础设施，大大降低了部署和后期维护的复杂度和成本。
4. 极佳的可扩展性： 通过简单的配置文件（images.txt），你可以轻松添加、删除或修改需要同步的镜像。无论少量核心镜像还是大量项目依赖，该方案都能灵活应对，方便你根据实际需求进行扩展。
5. 增强的安全性与控制： 你的镜像最终存储在专属的 Aliyun ACR 仓库中，你可以对这些镜像进行精细的权限管理。GitHub Secrets 的使用也确保了认证信息的安全存储。

---

4. Aliyun ACR 设置

4.1 开通服务

访问，如果首次使用，按照指引开通“个人版”实例。个人版实例目前提供免费的存储空间，对于个人和小团队来说基本够用。

4.2 设置访问凭证

ACR 个人版实例，可以设置一个固定密码用于 Docker CLI 登录。进入你的个人版实例，在左侧导航栏找到“访问凭证”或类似选项，设置一个固定的登录密码。

4.3 创建命名空间 (Namespace)：

命名空间用于组织你的镜像。在你的 ACR 实例中，创建一个新的命名空间，例如 my-images 或你的项目名。

4.4 记下你的 ACR 实例的信息

• Registry 地址通常是：registry.cn-hangzhou.aliyuncs.com (根据你选择的地域可能不同)
• 命名空间：3.3中创建的命名空间
• 用户名：访问凭证中的username
• 密码：你设置的固定密码

---

5. GitHub 仓库及 Secrets 配置

5.1. 创建 GitHub 仓库：

如果你还没有专门的仓库，可以创建一个新的 GitHub 仓库 (可以是私有的) 来存放我们的 Workflow 文件。例如，docker-image-sync。

5.2 配置 Secrets

为了安全地在 GitHub Actions 中使用阿里云 ACR 的凭证，我们需要将它们配置为仓库的 Secrets。切勿将密码等敏感信息直接硬编码到 Workflow 文件中！ 进入你的 GitHub 仓库页面，点击 “Settings” → “Secrets and variables” → “Actions”。然后点击 “New repository secret” 添加以下 Secrets：

• ACR_USERNAME: 前面Aliyun ACR中的用户名
• ACR_PASSWORD: 前面Aliyun ACR设置的固定密码
• ACR_REGISTRY: 前面Aliyun ACR中的Registry
• ACR_NAMESPACE: 前面Aliyun ACR中创建的命名空间

---

6. 核心步骤：配置 GitHub Workflow

6.1 拉取 GitHub 创建的仓库代码

首先，将你刚刚在 GitHub 上创建的空仓库克隆到本地：

git clone <你的 GitHub 仓库地址>

6.2 创建 Workflow 文件和配置

接下来，在克隆到本地的仓库中创建所需的文件和目录。最终目录结构如下：

docker-image-sync/├── .github/│   └── workflows/│       └── sync.yml        # GitHub Actions Workflow 定义文件├── README.md               # 仓库说明文件├── config.env              # 镜像同步配置（ACR Registry地址和命名空间）├── images.txt              # 需要同步的 Docker 镜像列表└── sync.sh                 # 实际执行镜像同步的 Shell 脚本

6.3 编写 sync.yml (GitHub Workflow)

将以下内容粘贴到
.github/workflows/sync.yml 文件中。这个 Workflow 定义了何时触发镜像同步以及具体执行哪些步骤。

name: Sync Docker Images to Aliyun ACR # Workflow 的名称run-name: ${{ github.actor }} is syncing Docker images # 在 GitHub Actions 页面显示运行者on:  push: # 当有代码推送到以下分支或路径时触发    branches:      - main # 监听 main 分支的推送    paths:      - 'images.txt' # 只有 images.txt 文件更新才触发      - '.github/workflows/sync.yml' # workflow 文件自身更新也触发  workflow_dispatch: # 允许手动触发 Workflow  jobs:  sync-images: # 定义一个 Job    runs-on: ubuntu-latest # GitHub Actions Runner 运行环境 (Ubuntu 最新版)    steps:      - name: Checkout repository # 步骤1: 拉取 GitHub 仓库代码        uses: actions/checkout@v4 # 使用 actions/checkout@v4 action            - name: Login to Aliyun Container Registry (ACR) # 步骤2: 登录 ACR        uses: docker/login-action@v3 # 使用 docker/login-action@v3 action        with:          registry: ${{ secrets.ACR_REGISTRY }} # 动态构建 ACR Registry 地址          username: ${{ secrets.ACR_USERNAME }} # 使用 GitHub Secrets 中的 ACR 用户名 (RAM AccessKey ID)          password: ${{ secrets.ACR_PASSWORD }} # 使用 GitHub Secrets 中的 ACR 密码 (RAM AccessKey Secret)                - name: Execute sync script # 步骤3: 执行同步脚本        run: |          bash "${{ github.workspace }}/sync.sh" # 运行 sync.sh 脚本        env:          ACR_REGISTRY: ${{ secrets.ACR_REGISTRY }}          ACR_NAMESPACE: ${{ secrets.ACR_NAMESPACE }}              - name: Job status # 步骤4 (可选): 打印 Job 状态        run: echo "This job's status is ${{ job.status }}"

6.4 编写 images.txt (同步镜像列表)

将以下内容粘贴到 images.txt 文件中。每一行代表一个需要同步的 Docker 镜像，格式为 镜像名:标签。

特别注意：此文件最后一定要有一行空行，以确保 Shell 脚本能完整读取所有行。