OZ
oceanz.site

无法访问 Docker Hub？用阿里云 ACR 搭建你的私有镜像仓库

Docker 镜像拉取失败？CI/CD 卡在 docker pull？本文提供一套可复制的替代方案：通过阿里云容器镜像服务（ACR）构建个人或团队的私有 Docker 仓库，实现长期稳定拉取、版本控制、多设备共享，彻底告别镜像站频繁失效的烦恼。

Docker 镜像拉取失败docker pull 无响应docker save load 教程Docker 私有镜像仓库阿里云容器镜像服务ACR 使用教程Docker Hub 替代方案国内无法访问 Docker Hub构建私有镜像仓库阿里云 ACR 教程

常见困境

  • 执行 docker pull 拉取基础镜像，却迟迟无响应，提示：docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout，只能黯然中止而倍感烦躁...

  • 昨天还能使用的镜像源，今天突然不可用，不断在网络上搜寻(还要加上“最新可用”关键词)最新可用的镜像地址、配置镜像加速器，消耗大量本不应消耗的时间...

  • 自己的电脑配置了代理可以拉取镜像，而云服务器却处于“断网状态”，每次都得在本地与云上之间重复 docker save → scp → docker load 的繁琐流程，令人身心俱疲。

  • 为 CI/CD 管道中“镜像拉取失败”而卡住上线进度，只能手动跳过测试、跳过部署、心惊胆战地上线修复...

如果你正在经历这些问题，或者曾经被这些问题困扰，那么你并不孤单。

镜像拉取现状

自 2023 年 5 月中旬起，Docker Hub 在国内的访问状况逐渐恶化，大量研发和运维人员不得不配置国内的镜像加速器，以维持日常学习、开发与部署流程。

然而，好景不长。到了 2024 年 6 月，以上海交通大学 Docker Hub 镜像站为代表的一批公共加速源陆续发布公告，宣布终止对 Docker Hub 的镜像服务。这一变动意味着：曾经还能勉强依靠的“救命稻草”，也相继失效。

带来的实际影响与隐性成本

从那之后，许多开发者进入了一个高频操作却低效回报的循环：

搜索新的镜像站 → 配置新的源地址 → 成功几天 → 访问失效 → 重新寻找 → 再次配置……

每一次镜像拉取失败，都会打断开发节奏；每一次重新寻找镜像源，都会消耗精力和时间；每一次配置新源失败，都会加剧焦虑与无力感。

这种“看似有解、实则不可持续”的方式，逐渐成为了困扰国内 Docker 使用者的常态性问题。

解决方案：构建属于自己的私有镜像仓库

为了解决镜像拉取困难、镜像站点频繁失效、不同环境镜像不一致等问题，可以构建属于自己的私有镜像仓库，为个人开发者、小型团队和需要部署在云上但无法使用proxy的系统提供镜像服务：

✅ 满足学习、开发、部署中需要使用的常用基础镜像；

✅ 一次配置，后续较长时间内不再频繁搜索和切换镜像站点；

✅ 在团队内部、个人多设备之间，实现长期、稳定、统一的镜像共享；

💡 方案核心思路

先获取基础镜像，将基础镜像或结合自己的需要构建新的容器镜像，上传至阿里云容器镜像仓库，供没有能力访问 docker hub 的设备使用。

具体做法：

  • 获取基础镜像
    • 利用一台可访问 Docker Hub 的设备（如带代理的个人电脑、海外 VPS 等）拉取所需镜像；
    • 或者访问目前可用的镜像网站，将所需要的基础镜像拉取到本地，
  • 根据自己的需要构建新的容器镜像；
  • 将构建好的镜像上传至阿里云容器镜像服务（ACR）的私有仓库；
  • 在任意设备上配置阿里云容器镜像服务（ACR）的私有仓库地址，拉取对应的镜像。

为什么明明能拉镜像，还需要私有仓库？

你可能会疑惑：既然我已经能访问 Docker Hub，那还需要搭建私有镜像仓库吗？

这正是本方案想解决的核心问题之一 ——
我们关注的不只是“能不能拉镜像”，而是“如何管理镜像更高效、稳定、统一”。

搭建自己的私有镜像仓库，适用于以下典型场景：

  • 多设备间（如本地开发机、云服务器、测试环境）镜像如何复用，避免重复 save/load；
  • 团队内部如何实现统一的镜像来源，避免各自配置镜像源导致版本漂移；
  • CI/CD 流程如何保障镜像拉取的连续性，避免上线时卡在 pull 阶段；
  • 镜像能否版本可控、架构一致，不受镜像源波动影响。

就像你可以手动拷贝代码，但仍然选择用 Git；可以手动部署应用，但选择用 CI/CD 一样，私有镜像仓库就是对混乱镜像使用方式的一次整理与提升。

该方案希望提供的是一套“可以复用、可以推广、可以维护”的实践方案，而不是临时应急的一次性操作。

适用场景与优势

这一方案不仅适用于个人开发者和 DevOps 工程师，也非常适合小规模团队在国内复杂网络环境中构建稳定的开发基础设施（大厂之类的大部分都有自己的私有镜像仓库）。

它聚焦于解决以下典型问题场景：

  • 在云服务器（如阿里云 ECS）上，CI/CD 构建任务经常因无法拉取基础镜像而失败；

  • 在多台机器间（如家用笔记本、公司电脑、测试服务器）切换时，镜像无法统一，环境差异频发；

  • 每次新建项目或部署服务，都需要手动 docker pull，碰上镜像站挂了，就只能另找办法；

  • 团队成员各自配置不同的镜像加速源，难以维护统一性和长期可用性；

  • 时间紧任务急时，花大量时间搜镜像、配环境，极度影响效率与心情；

  • docker image save 导出镜像，docker image load 导入镜像，需要手动操作，且需要手动拷贝到其他设备，操作繁琐。

通过构建一个属于自己的私有镜像仓库，可以有效规避上述问题，带来如下优势：

  • ✅ 一次获取，长期复用 常用镜像只需拉取一次，上传至私有仓库后即可在多台设备中长期使用，不再受限于外部网络状况。特别是在云上环境（如部署脚本、CI/CD 中），“可预测”远比“临时可用”更重要。

  • ✅ 多设备间统一共享 本地开发、云端部署、测试验证，使用同一个镜像源。再也不需要每次都在笔记本上打包、再上传到云服务器，节省大量重复劳动。

  • ✅ 镜像版本可控，构建更稳定 镜像一旦确认可用，便可上传固定版本，避免官方镜像不经意间发生变化（如基础依赖升级、配置变动）导致的兼容性问题，从根源上杜绝“昨天好好的，今天就坏了”的构建隐患。

  • ✅ 支持多架构镜像 可根据设备架构构建并上传不同版本的镜像，如 amd64（主流服务器）与 arm64（如 Apple M 系列芯片），满足本地测试与线上部署的统一性。

  • ✅ 提升 CI/CD 稳定性 不再依赖外部加速器或镜像站点，整个构建流程更加可控、连续、稳定。尤其在敏感场景（如紧急修复、定时部署）下，稳定拉取镜像就是保障交付的底线。

综上，这是一个低成本、高可控性的“镜像隔离 + 镜像池”方案，适合在国内网络环境中长期使用。 不依赖第三方服务、不担心加速器失效、不需要每次都 save/load，真正做到一次配置、长期受益。

前提条件与限制说明

在采用本方案之前，确认以下前提条件是否具备：

  1. 至少一台设备能够访问 Docker Hub 要获取原始官方镜像，至少需要一台可以正常访问 Docker Hub 的设备（如配置了 proxy 的本地开发机、境外 VPS 等），用于初次拉取所需的基础镜像。

    • 若你本人电脑已有代理，可在本地拉取并通过 docker save 导出；

    • 若团队中有人具备此能力，也可将镜像统一导出后上传共享。

  2. 或者具备其他可用镜像拉取渠道

    • 如果无法访问 Docker Hub，也可考虑使用现有的镜像分发平台（如 轩辕镜像）获取基础镜像，再通过 docker tag 与 docker push 上传至私有仓库。

  3. 拥有阿里云账号，已完成个人认证

    • 本方案依赖于阿里云容器镜像服务（ACR），需提前完成以下准备：

    • 拥有阿里云账号；

    • 已完成个人实名认证（可免费使用容器镜像服务）；

    • 建议开通 华东 1（杭州） 或你所在区域的 ACR 实例，以获得更优带宽与访问延迟；

  4. 熟悉 Docker 基础操作 看到这里，相信你对Docker基础操作已经有所了解，如果还不熟悉，可以参考Docker 官方文档。

step by step 流程与最佳实践

📌 接下来涉及阿里云 ACR 创建实例、上传镜像并在其他设备中复用，建议在动手操作前准备好：

  • 一台可联网的机器用于拉取镜像
  • 阿里云账号及实名认证
  • 基础的 Docker CLI 使用能力

1. 阿里云的相关准备

  1. 注册或登录阿里云账号，并完成个人认证；

  2. 进入右上角“控制台”，鼠标移动到左上角，滑出产品与服务，输入“容器镜像”，点击“容器镜像服务 ACR”，进入容器镜像服务控制台；

  3. 在“实例列表”，点击“个人版实例”，在弹出的提示面板中点击“创建个人版实例”；

  4. 在“地域”选择上，考虑到阿里云就在杭州，那边的网络应该最稳定，选择中国->华东1（杭州）,勾选服务协议和使用限制说明，点击立即创建；

  5. 创建完成后，会提示设置Registry登录密码，8-32位，必须包含字母、符合或数字中的至少两项，记好这个密码，后续访问需要使用；

  6. 设置完密码，会进入到镜像仓库页面，在创建仓库之前，我们先搞清楚一些概念和最佳实践：

    🧱 命名空间（Namespace）与仓库（Repository）结构说明

    在阿里云 ACR 中，镜像的地址遵循标准的 Docker 镜像命名结构：

    [registry-domain]/[namespace]/[repository]:[tag]

    例如：

    registry.cn-hangzhou.aliyuncs.com/my-team/node:lts-alpine3.21
    字段说明
    registry镜像仓库地址（阿里云分配的域名）
    namespace命名空间，相当于“组织名”或“所有者”
    repository镜像仓库名，建议每个仓库存放一个应用的多个版本
    tag镜像标签，表示具体的版本号，例如 latest 或 v1.0

    🗂 关于命名空间（Namespace）

    • 命名空间是仓库的逻辑分组，可以用于隔离不同项目或团队；

    • 同一个阿里云账号下，个人版 ACR 最多可创建 3 个命名空间；

    • 建议根据实际场景命名，例如：

      • 公司层级：yourcorp

      • 团队层级：frontend-team

      • 项目层级：ai-service

      • 个人层级：personal-name

    📦 关于镜像仓库（Repository）

    • 一个仓库用于存放某一类镜像（如同一应用、组件或服务）的多个版本；

    • 命名方式可以是：

      • 软件名：nginx、redis、mysql

      • 业务组件名：user-service、admin-panel、event-bot

    • 建议保持仓库粒度合理：一个仓库只管理一类镜像的多个版本，有助于权限管理、版本清晰。

    • 仓库的限额是300；

  7. 在创建仓库前，先设置访问凭据，点击“访问凭据”菜单，刚刚Registry设置的密码就是固定密码，在登录实例中可以看到具体的设置命令，其中--username就是你的用户名，也就是阿里云账号的名称。

docker login --username=[aliyun-account-name] ***.cn-hangzhou.personal.cr.aliyuncs.com

  1. 创建命名空间，由于多人共享同一个Registry地址，所以命名空间会有被占用的情况，尽量输入一个和个人相关的名称，点击确定，其余选项保持默认即可；

  2. 选择“镜像仓库”，点击“创建镜像仓库”，我们以node为例，选择刚刚创建的命名空间，仓库名称输入node，其余保持默认，摘要输入“official 基础镜像 node”，点击下一步；

  3. 在代码源，选择本地仓库，意味着，我们使用本地已构建的镜像，然后点击“创建镜像仓库”；

  4. 至此，已经完成了阿里云的基础配置，在仓库“基本信息”中，有详细的操作指南，会有如何登录，拉取镜像，推送镜像，镜像地址氛围公网地址和专有网络，如果你的设备在阿里云VPN网络中，可以选择使用专有网络地址。

在阿里云配置阶段，总共得到以下需要记录的信息：

  • 阿里云账号名称；
  • 登录Registry的密码；
  • 镜像公网和专有网络地址，可能不一致，以页面显示为准：
    • 公网: ***.cn-hangzhou.personal.cr.aliyuncs.com
    • 专有网络: ***.-vpc.cn-hangzhou.personal.cr.aliyuncs.com
  • 命名空间: my-team-one;
  • 仓库名称: node;

2. 本地镜像准备

  1. 找一台能够访问docker hub的设备，比如你的个人电脑，或者你的海外VPS，或者目前有可用的镜像源；

  2. 以docker hub官方镜像node为例，使用docker pull拉取最新的镜像到本地；

docker pull node:lts-alpine3.21
  1. 查看本地镜像，确保拉取成功，目前的tag是lts-alpine3.21，Image ID是a937d3ed32b0，以你本地显示的为准；
docker images
REPOSITORY                                               TAG               IMAGE ID       CREATED         SIZE
node                                                     lts-alpine3.21    a937d3ed32b0   2 days ago      159MB
  1. 当本地有这个镜像后，需要给现有的镜像打标签（重命名），用于上传至阿里云的Registry；

说明：

  • 该操作不会复制镜像数据，只是给它创建了一个新的reference；

  • 用到如下的命令：

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

其中：

  • SOURCE_IMAGE[:TAG]可以使用本地的Image ID；

  • TARGET_IMAGE[:TAG] 是由多个组件构成用于描述了镜像的存储位置及其身份的地址，格式如下；

[registry/][namespace/]name[:tag]

  • 其中registry是镜像仓库地址，默认是docker.io（即 Docker Hub）；

  • namespace是命名空间，默认是library，在阿里云容器镜像服务中对应刚刚创建的命名空间；

  • name是镜像名称，默认是node，在阿里云容器镜像服务中对应刚刚创建的仓库名称；

  • tag是镜像标签，默认是latest，在里云镜像服务中，你需要定义的版本号；

最终本地需要执行的命令：

# 注意：命令不要 []，[] 只是说明需要替换的内容
# [local-image-id] 替换为本地镜像的 Image ID
# [aliyun-registry-url] 替换为阿里云的镜像仓库地址
# [your-namespace] 替换为刚刚创建的命名空间
# [node] 替换为刚刚创建的仓库名称
# [lts-alpine3.21] 替换为你需要定义的标签
 
docker tag [local-image-id] [aliyun-registry-url]/[your-namespace]/[node]:[lts-alpine3.21]

当你执行完这个命令后，执行docker iamges，可以看到有两个Image ID相同的影响，但是所对应的REPOSITORY不同，一个是node，一个是***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node，前者是本地镜像，后者是阿里云的镜像仓库地址。

REPOSITORY                                                                    TAG               IMAGE ID       CREATED         SIZE
***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node                     lts-alpine3.21    a937d3ed32b0   4 days ago      159MB
node                                                                          lts-alpine3.21    a937d3ed32b0   4 days ago      159MB

至此，本地的镜像文件已经准备完毕，接下来需要上传至阿里云的Registry；

3. 上传镜像至阿里云

  1. 登录阿里云 Containter Registry；
# 注意：命令不要 []，[] 只是说明需要替换的内容
# [aliyun-account-name] 替换为阿里云账号名称
# [aliyun-registry-url] 替换为阿里云的镜像仓库地址
# 具体信息，仓库基本信息-操作指南中有详细说明
 
docker login --username=[aliyun-account-name] [aliyun-registry-url]

  1. 输入刚刚设置的Registry登录密码，登录成功后，会提示Login Succeeded；

  2. 上传镜像至阿里云；

# 注意：命令不要 []，[] 只是说明需要替换的内容
# [aliyun-registry-url] 替换为阿里云的镜像仓库地址
# [your-namespace] 替换为刚刚创建的命名空间
# [node] 替换为刚刚创建的仓库名称
# [lts-alpine3.21] 替换为你需要定义的标签
 
docker push [aliyun-registry-url]/[your-namespace]/[node]:[lts-alpine3.21]
  • 执行成功后，会提示如下类似的信息。
The push refers to repository [***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node]
bc25a8c84974: Pushed 
625f0765efa8: Pushed 
b3c942954ba7: Pushed 
08000c18d16d: Pushed 
lts-alpine3.21: digest: sha256:cb4769335a5b3b23636053dcb5e2ad7c22de01ade9e772a40d5e77b72d659367 size: 1158
  1. 查看阿里云的镜像仓库，在“镜像仓库”-->“镜像版本”，可以看到刚刚上传的镜像信息；

4. 其他设备的使用

  • 在没有能力访问docker hub的设备执行，先登录到阿里云的Container Registry：
docker login --username=[aliyun-account-name] ***.cn-hangzhou.personal.cr.aliyuncs.com

登录成功显示Login Succeeded；

  • 拉取镜像：
docker pull ***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21
lts-alpine3.21: Pulling from my-team-one/node
f18232174bc9: Pull complete
5056ee185863: Pull complete
974362762896: Pull complete
18d8590713a4: Pull complete
Digest: sha256:cb4769335a5b3b23636053dcb5e2ad7c22de01ade9e772a40d5e77b72d659367
Status: Downloaded newer image for ***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21
***.cn-hangzhou.personal.cr.aliyuncs.com/my-team-one/node:lts-alpine3.21
  • 拉取成功后，就可以愉快的使用镜像了；

替代方案补充

✴️ 其他方案说明

或者使用专业的Docker镜像加速平台，如轩辕镜像等，不过这些专业的镜像加速平台需要充值购买流量，入门套餐是5元，50GB流量。若能以较低的成本，满足自己的需求，节省时间，提高效率，也可以考虑使用。

目前像阿里云、腾讯云、华为云等云服务商都提供了自己的镜像仓库服务，和镜像加速器，但是官方提供的镜像制品有限，大部分基于云厂商的系统，如：Alibaba Cloud Linux，对个人开发者来说，选择性较少。

参考资料

暂无目录