ByteNote

slug: hub-mirror topic: open-source-tools title: hub-mirror - 基于 GitHub Actions 的 Docker 镜像加速代理

在国内开发环境中，拉取 Docker Hub 等国外镜像仓库的镜像一直是一个痛点。hub-mirror 是一个巧妙的开源项目，它利用 GitHub Actions 作为中转，将 docker.io、gcr.io、registry.k8s.io、k8s.gcr.io、quay.io、ghcr.io 等国外镜像自动同步到国内镜像仓库，实现了零成本的镜像加速方案。该项目在 GitHub 上已获得超过 1.2k Star，被众多云原生开发者所采用。

项目简介

hub-mirror 是一个基于 GitHub Actions 的 Docker 镜像代理工具，核心思路是通过 Fork 项目并在自己仓库中配置镜像仓库凭据，然后通过提交 Issue 的方式触发自动同步。整个流程无需自建服务器，完全依赖 GitHub 提供的免费 Actions 运行时，非常适合个人开发者和小团队使用。

GitHub 地址: https://github.com/togettoyou/hub-mirror
Stars: 1.2k+
Forks: 778+
License: MIT
语言: YAML (GitHub Actions) + Shell

核心特性

多源镜像支持: 支持 docker.io、gcr.io、registry.k8s.io、k8s.gcr.io、quay.io、ghcr.io 等主流国外镜像仓库
零成本运行: 完全基于 GitHub Actions，无需购买或维护任何服务器
Issue 驱动同步: 通过提交特定格式的 Issue 触发镜像同步，操作简单直观
多国内镜像仓库: 支持腾讯云 CCR、阿里云 ACR 等国内主流镜像仓库
自动标签同步: 支持同步指定标签或全量标签
状态反馈: 同步完成后自动在 Issue 上标记成功或失败状态

技术栈

GitHub Actions: 自动化工作流引擎，负责拉取和推送镜像
Docker: 容器镜像拉取和推送工具
GitHub Issues: 作为触发器和工作状态展示界面
Shell 脚本: 镜像同步的核心逻辑

hub-mirror 的技术架构非常简洁，核心是利用 GitHub Actions 的 Docker 支持能力，在工作流中完成镜像的 pull、tag 和 push 操作。通过 Issue 模板约束用户输入，解析出源镜像地址和目标标签，然后执行同步。

安装指南

前置条件

GitHub 账号
国内镜像仓库账号（阿里云 ACR 或腾讯云 CCR 等）

部署步骤

第一步：Fork 项目

在 GitHub 上 Fork hub-mirror 项目到自己的账号下，后续所有操作均在 Fork 的仓库中进行。

第二步：配置镜像仓库凭据

进入 Fork 仓库的 Settings > Secrets and variables > Actions，添加以下 Repository Secrets：

DOCKER_USERNAME: 镜像仓库登录名
DOCKER_TOKEN: 镜像仓库密码
DOCKER_REPOSITORY: 镜像仓库地址

DOCKER_REPOSITORY 的格式示例：

腾讯云: ccr.ccs.tencentyun.com/[namespace]
阿里云: registry.cn-hangzhou.aliyuncs.com/[namespace]

第三步：开启 Issues 功能

进入 Settings > General > Features，确保 Issues 功能已启用。

第四步：配置 Actions 权限

进入 Settings > Actions > General，在 Workflow permissions 中选择 Read and write permissions，允许 Actions 修改 Issue 状态。

第五步：添加 Issue Labels

进入 Issues > Labels，依次添加以下三个标签：

hub-mirror - 用于标识镜像同步类型的 Issue
success - 用于标记同步成功的 Issue
failure - 用于标记同步失败的 Issue

第六步：启用 Workflow

进入 Actions 页面，选择 hub-mirror workflow，在右上角菜单中选择 Enable Workflow。

快速开始

完成上述配置后，即可开始同步镜像。

在 Fork 仓库的 Issues 页面点击 New issue
选择 hub-mirror 模板
按照模板格式填写需要同步的镜像信息
提交 Issue 后，GitHub Actions 会自动触发同步流程
同步完成后，Issue 会自动被标记为 success 或 failure

同步成功后，即可通过国内镜像仓库地址拉取对应的镜像，拉取速度将大幅提升。

使用示例

假设需要同步 nginx:latest 镜像到阿里云杭州区域的镜像仓库：

提交一个 hub-mirror 类型的 Issue，按照模板填写源镜像信息
GitHub Actions 会自动拉取 docker.io/library/nginx:latest
重新标记为 registry.cn-hangzhou.aliyuncs.com/your-namespace/nginx:latest
推送到阿里云镜像仓库
之后在服务器上即可直接使用国内地址拉取：

bash

docker pull registry.cn-hangzhou.aliyuncs.com/your-namespace/nginx:latest

对于 Kubernetes 集群用户，可以将镜像地址批量替换为国内镜像仓库地址，从而解决节点拉取镜像超时或失败的问题。

注意事项

GitHub Actions 有每月 2000 分钟的免费额度，大镜像同步会消耗较多时间
国内镜像仓库可能有存储配额限制，建议定期清理不再使用的旧镜像
部分镜像可能包含多架构（amd64、arm64 等），同步时需注意架构兼容性
建议不要将包含敏感信息的私有仓库凭据泄露

适用场景

国内 Kubernetes 集群部署，需要快速拉取国外镜像
CI/CD 流水线中需要频繁拉取基础镜像
企业内部镜像仓库的 upstream 同步
开发环境中拉取 gcr.io、k8s.gcr.io 等被墙的 Google 镜像
需要在离线或半离线环境中预置 Docker 镜像

项目链接

GitHub 仓库: https://github.com/togettoyou/hub-mirror
License: MIT
微信公众号: gopher云原生

字节笔记本

Hub Mirror - GitHub 仓库 Docker 镜像加速工具