Docker：使用Github Action转存Docker镜像到阿里云私有堆栈达到国内加速目

一、要解决什么：国外镜像拉不动的绕行思路

从 Docker Hub、gcr.io、ghcr.io 这类境外仓库拉镜像，国内服务器经常慢到超时。绕行思路很直接：在国外能通的时候，把镜像「转存」到国内的私有仓库（比如阿里云容器镜像服务），之后国内机器 pull 自己的私有地址，速度就正常了。

这套做法用的是 GitHub Actions——它天然具备「国外网络能跑」这个条件，由它在国外环境里把镜像推到你的阿里云仓库，国内机器只需从国内地址拉。整个过程免费、可复用，也不需要在自己服务器上常驻任何进程。

二、这个方案能做什么

• 支持任意仓库：Docker Hub、gcr.io、k8s.gcr.io、ghcr.io 等都能转存；
• 支持大镜像：最大可处理 40GB 级别的镜像；
• 走国内线路：转存目标是阿里云，国内服务器拉取走的是国内链路；
• 可定时同步：配好 cron（注意是 UTC 时区）就能定时自动更新，不用手工重推。

三、第一步：在阿里云准备仓库

1. 登录并启用个人实例

登录阿里云容器镜像服务，启用个人版实例，创建一个命名空间（namespace）。

2. 准备四个凭证值

在「访问凭证」里能看到三组变量，加上命名空间一共四个：

• 命名空间：ALIYUN_NAME_SPACE
• 用户名：ALIYUN_REGISTRY_USER
• 密码：ALIYUN_REGISTRY_PASSWORD
• 仓库地址：ALIYUN_REGISTRY（形如 registry.cn-hangzhou.aliyuncs.com）

建议命名空间用公开或权限可控地配好：如果希望拉镜像免登录，把对应仓库设为公开即可。

四、第二步：Fork 转存项目并配置密钥

需要先有一份转存工作流项目（docker_image_pusher），Fork 到自己的账号下，然后三步操作：

1. 启用 Actions

进入自己的项目，点击 Action 页签，启用 GitHub Actions 功能。

2. 设置四个环境变量

路径是 Settings → Secrets and variables → Actions → New repository secret，把上一步的四个值分别建为 Secret（就是那三个变量名加命名空间对应的值）。

用 Secrets 而不是明文写在 images.txt 里，仓库公开也不会泄露阿里云账号密码——这一点必须守住。

3. 在 images.txt 里写要转存的镜像

回到 Code 页签，打开 images.txt 文件添加镜像。这个文件的写法支持几种形式：

# 可加 tag，也可不加（不加默认 latest）
nginx
nginx:1.25-alpine

# 可用 --platform 参数指定镜像架构
--platform=linux/arm64 nginx

# 可用「仓库路径/镜像」格式指定私有仓库来源
k8s.gcr.io/metrics-server/metrics-server

# # 开头是注释行

文件一提交，GitHub Actions 自动触发构建，在 Actions 页签能看到处理进度。

五、第三步：在国内使用镜像

回到阿里云的镜像仓库页面，点任意镜像可查看状态。想让国内拉取免登录，把对应仓库设为公开。

国内服务器 pull 的示例：

docker pull registry.cn-hangzhou.aliyuncs.com/<你的命名空间>/alpine

地址三段对应关系很清楚：

• registry.cn-hangzhou.aliyuncs.com 就是 ALIYUN_REGISTRY（仓库地址）；
• <你的命名空间> 就是 ALIYUN_NAME_SPACE；
• 最后一段 alpine 是阿里云里显示的镜像名。

六、几个进阶点

1. 多架构

需要在 images.txt 里用 --platform=xxxxx 手动指定架构；指定后的架构会以前缀形式加在镜像名前面。

2. 镜像重名

程序会自动判断是否存在同名但属于不同命名空间的情况：如果存在，就把命名空间作为前缀加在镜像名称前，避免互相覆盖。比如：

xhofe/alist
xiaoyaliu/alist

3. 定时执行

修改 .github/workflows/docker.yaml，添加 schedule 即可定时执行。注意此处 cron 用的是 UTC 时区，写时间时要换算——北京时间 = UTC + 8。

七、这套方案的边界和注意

• 依赖上游工作流项目的可维护性：这是一类第三方模板，Fork 之后要自己盯着上游更新，别无脑长期挂定时任务；
• 镜像大小有上限（约 40GB），超大镜像要另想办法（直接走专线或内网镜像仓库同步）；
• credentials 一旦泄露等于阿里云账号可被推镜像：进 Secret 管理，别写进代码；轮换密码后记得同步更新 Secret；
• 这解决的是「拉不到/拉得慢」，不解决合规问题：私有仓库的访问控制、镜像审计仍要按公司规范来配。

八、一句话总结

阿里云开命名空间取四个变量 → Fork 转存项目、把变量配成 Actions Secret → 在 images.txt 里写镜像名 → Actions 自动推到国内仓库 → 国内机器从私有地址 pull。 配好一次，后续加镜像只是往一个文本文件里加一行，定时还能自动更新。

这套流程真正合适的场景是：你有几镜像反复要在国内服务器部署，又不想为了几张镜像专门搭一台同步机。 超过这个规模，就该考虑直接上内网镜像仓库（Harbor 之类）了。

（本文由 qidao123.com企服评测-应用市场 编辑提示整理：内容围绕 Docker 镜像跨境转存与私有仓库实践，适用于云原生环境下的镜像加速与交付链路优化。涉及云账号凭证 please 通过 Secrets 管理。）