Docker 镜像加速终极指南：巧用 GitHub Actions 实现免费、不限速拉取

在国内直接从 Docker Hub 拉取镜像时常会遇到网络问题，这给开发和学习带来了极大不便。本文将介绍一种稳定、免费且无拉取数量限制的解决方案，让您告别镜像拉取的烦恼。

核心优势

稳定性高：一次配置，长期稳定使用。
零经济成本：无需购买海外服务器或梯子。
无数量限制：短时间内可拉取任意数量的镜像。
使用便捷：配置完成后，使用自定义的 docker_pull 命令即可，体验与原生命令类似。

现有方案对比

方法/方案	实现难度	使用便捷性	需要海外服务器	需要梯子	稳定性	限额
本文方案	★★	★★★★★	❌	❌	极高	无
更换 Docker 源	★	★★★★★	❌	❌	极差 (需频繁更换)	不限
使用公开镜像站	★	★★ (部分镜像找不到)	❌	❌	中	不限
配置 `proxychains`	★★	★★★★	❌	✔️	高	10/h
自建 Docker 代理	★★★★	★★★★★	✔️	❌	高	10/h

方案原理

本方案巧妙地利用了 GitHub Actions 和 阿里云容器镜像服务 (ACR) 作为桥梁，实现镜像的自动化同步。

工作流程如下：

触发：您在本地执行 docker_pull <image_name> 命令。
提交：脚本自动将您想拉取的镜像名称（如 mysql:5.7.44）写入 images.txt 文件，并提交变更到您的 GitHub 仓库。
构建：GitHub Actions 监听到代码提交，自动触发预设的工作流。
同步：工作流中的虚拟机从官方 Docker Hub 拉取指定镜像。
推送：工作流将拉取到的镜像推送到您的私有阿里云镜像仓库。
拉取：本地脚本检测到镜像已推送到阿里云后，立即从阿里云仓库将其高速拉取到本地。
重命名：脚本自动将拉取下来的镜像标签（Tag）重命名为原始的官方镜像标签。

环境准备

在开始配置前，请确保您的电脑已安装以下软件：

Git：并已配置好账号密码或 SSH 密钥。
Docker：并处于运行状态。
阿里云账号：并完成实名认证。

配置步骤

整个配置过程分为三大部分：阿里云配置、GitHub 仓库配置和本地脚本配置。

第一步：配置阿里云容器镜像服务 (ACR)

开通服务
- 访问阿里云容器镜像服务控制台。
- 如果首次使用，系统会提示您开通服务。选择离您最近的地理区域，勾选同意服务条款后点击“立即创建”。
设置仓库登录密码
- 在左侧导航栏点击“访问凭证”。
- 点击“设置 Registry 登录密码”并设置一个专用密码。（注意：此密码将公开配置在 GitHub，请勿使用您的阿里云账户登录密码）
创建命名空间 (Namespace)
- 在左侧导航栏点击“命名空间”。
- 点击“创建命名空间”，输入一个独一无二的名称（例如，您的名字拼音或随机字符）。
记录凭证信息
- 回到“访问凭证”页面。
- 记下 公网地址（即仓库地址）和您刚刚创建的 命名空间名称，后续步骤将会用到。

第二步：配置 GitHub 仓库

Fork 项目仓库
- 访问并 Fork 项目 you8023/docker_images_sync 到您自己的 GitHub 账户下。
- （可选）如果希望拉取的镜像列表保密，可以创建一个 private 私有仓库，然后将 Fork 的代码克隆并推送到您的私有仓库中。
配置仓库 Secrets
- 进入您 Fork 后的仓库，点击 Settings -> Secrets and variables -> Actions。
- 点击 New repository secret 按钮，依次添加以下 4 个仓库变量：
  - DOCKER_USER：您的阿里云账户用户名（非登录邮箱，通常是一串 aliyunid 或者您自定义的用户名）。
  - DOCKER_PWD：您在 第一步第 2 点 中为镜像仓库设置的专用登录密码。
  - DOCKER_REGISTRY：您在 第一步第 4 点 中记录的阿里云仓库公网地址。
  - DOCKER_NS：您在 第一步第 3 点 中创建的命名空间名称。
克隆仓库到本地
- 复制您自己仓库的地址，使用 git clone 命令将其克隆到本地电脑。

第三步：配置本地脚本

创建并编辑配置文件

进入您刚刚克隆到本地的仓库目录。
将 cmd/conf.yaml.default 文件复制一份，并重命名为 cmd/conf.yaml。

编辑 cmd/conf.yaml 文件，填入以下信息：

# 你的阿里云镜像仓库地址
registry: "registry.cn-hangzhou.aliyuncs.com"
# 你的阿里云镜像仓库命名空间
namespace: "your-unique-namespace"
# 你本地 Git 仓库的路径 (注意路径格式)
images_dir: "E:\\Git\\docker_images_sync"
# 拉取镜像重试次数，默认为60
max_retries: 60
# 拉取镜像尝试间隔（秒），默认为1
retry_delay: 1
# 提交 tag 后等待多久开始尝试拉取（秒），默认为20
first_delay: 20

重要提示：images_dir 必须是您本地 Git 仓库的绝对路径。

登录阿里云 Docker 仓库
- 打开终端（CMD 或 PowerShell），执行以下命令登录一次，让 Docker 记住密码。将 <你的仓库地址> 替换为实际地址。
```
docker login <你的仓库地址>
```
将脚本添加到环境变量
- 将 cmd 目录的绝对路径添加到系统的 Path 环境变量中，以便在任何路径下都能调用 docker_pull 命令。
- Windows:
  1. 右键点击“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
  2. 在“系统变量”中找到 Path，点击“编辑”。
  3. 点击“新建”，并将 cmd 目录的完整路径（例如 E:\Git\docker_images_sync\cmd）粘贴进去。
  4. 一路确定保存，然后重启您的终端工具。
- Linux / macOS:
  1. 为脚本添加执行权限（请替换为您的实际路径）：
```
chmod +x /path/to/your/docker_images_sync/cmd/docker_pull
```
  2. 编辑您的 shell 配置文件（如 ~/.bashrc, ~/.zshrc）：
```
vim ~/.bashrc
```
  3. 在文件末尾添加以下行（请替换为您的实际路径）：
```
export PATH=$PATH:/path/to/your/docker_images_sync/cmd
```
  4. 执行以下命令使配置立即生效：
```
source ~/.bashrc
```

如何使用

配置完成后，您可以在任意目录打开终端，像使用原生命令一样拉取镜像。

拉取单个镜像：

docker_pull mysql:8.0.1

一次性拉取多个镜像（用空格隔开）：

docker_pull mcr.microsoft.com/mssql/server:2022-latest bitnami/redis:8.0.2

脚本会自动完成所有后台操作，您只需稍等片刻，镜像即可成功拉取到本地。

故障排查

如果长时间拉取失败，您可以前往您 GitHub 仓库的 Actions 页面，查看工作流的运行日志，定位失败原因。最常见的问题是拉取了一个不存在的镜像标签。

核心优势#

现有方案对比#

方案原理#

环境准备#

配置步骤#

第一步：配置阿里云容器镜像服务 (ACR)#

第二步：配置 GitHub 仓库#

第三步：配置本地脚本#

如何使用#

故障排查#