镜像仓库（Docker Registry）：让你的镜像无处不达

前置知识：掌握 docker build 镜像构建、docker run 本地容器运行；本章目标：掌握镜像仓库分层概念、阿里云 ACR 全流程、镜像标签规范、国内网络分层优化、故障排查。

第一周你学会了用 docker build 构建镜像，用 docker run 本地运行。但如果想把镜像部署到另一台服务器（比如云服务器），就需要一个中间仓库来存储和分发镜像。这个仓库就是 Docker Registry。

1.1 为什么需要镜像仓库？

业务场景

在个人笔记本构建 Flask 应用镜像 myapp:v1，需要部署至阿里云 ECS 云服务器。

• 备选方案：docker save+docker load 打包镜像文件传输，方式原始、不利于自动化、版本管理；

• 标准方案：镜像推送至中心仓库，远端服务器从仓库拉取镜像运行，适配 CI/CD 自动化发布。

Docker 术语	说明
Registry（镜像仓库）	整体平台，承载海量项目镜像
Repository（仓库）	单个应用项目目录，同一项目所有版本存放处
Tag（标签）	镜像版本别名，指针映射真实镜像哈希 ID
Image ID	镜像内容哈希，内容不变 ID 永久固定

开发者：打包镜像上传仓库；运维 / 服务端：从远端仓库拉取镜像部署。

1.2 核心概念分层图解

Docker Registry（如 Docker Hub、阿里云 ACR）
│
├── Repository: my-flask-app
│   ├── Tag: v1.0.0  ────→ Image ID: sha256:abc123...
│   ├── Tag: v1.0.1  ────→ Image ID: sha256:def456...
│   └── Tag: latest  ────→ 指向 v1.0.1（浮动指针）
│
├── Repository: my-nginx
│   └── Tag: 1.21
│
└── ...

层级规则

1. 一个 Registry 可包含多个 Repository，Repository 以项目 / 应用名称区分；

2. 一个 Repository 可包含多个 Tag，代表同一个应用的不同迭代版本；

3. Tag 仅为指向 Image ID 的软指针，可被重新指向、删除；生产环境禁止随意变更已有 Tag 指向；

4. Image ID 由镜像文件内容 SHA256 哈希生成，镜像内容不变，ID 永远不变。

1.3 国内可用的镜像仓库选择

仓库方案	地址示例	优点	缺点
Docker Hub	[docker.io/library/nginx](docker.io/library/nginx)	全球镜像最全、海量官方公共镜像	国内拉取速率极低、频繁超时失败
阿里云 ACR（个人免费版）	registry.cn-hangzhou.aliyuncs.com/命名空间 / 仓库名	国内 CDN 加速、免费额度充足、生态完善	需要阿里云实名认证
腾讯云 TCR	ccr.ccs.tencentyun.com/命名空间 / 仓库名	同阿里云，云服务器内网拉取免费高速	需要账号实名
Harbor（自建私有化）	自定义服务器 IP + 端口	企业内网私有部署、数据不外流	自行部署、运维维护成本高

下文所有实操命令基于阿里云 ACR。

1.4 准备工作：创建阿里云 ACR 仓库

1. 登录阿里云【容器镜像服务 ACR】控制台；

2. 创建命名空间（例：devops-demo）：账号级分组目录，统一管理同项目组镜像；

3. 在命名空间内新建镜像仓库（例：my-flask-app），仓库类型选择私有仓库（学习首选，免费）；

4. 进入【访问凭证】→设置固定登录密码（禁用临时 Token，不利于 CI 流水线自动化）；

5. 记录 Registry 域名：registry.cn-hangzhou.aliyuncs.com。

最终完整仓库地址格式

<registry域名>/<命名空间>/<仓库名>
# 示例
registry.cn-hangzhou.aliyuncs.com/devops-demo/my-flask-app

1.5 命令实操：登录→打标→推送→拉取全流程

1.5.1 登录远端镜像仓库

docker login --username=你的阿里云账号 registry.cn-hangzhou.aliyuncs.com

执行后输入 ACR 固定密码（输入无回显，正常现象），登录成功凭证存放路径：~/.docker/config.json。

⚠️ 安全警告：config.json 中账号密码为 Base64 编码（非加密），严禁提交至 Git 代码仓库，防止凭证泄露。

1.5.2 准备本地测试镜像

若无自定义 Flask 镜像，直接拉取 Nginx 作为测试镜像：

docker pull nginx:1.24

1.5.3 镜像打 Tag（重命名绑定私有仓库）

打标原理

原生 nginx:1.24 默认归属 Docker Hub 官方仓库，无法直接推送阿里云私有仓库；必须通过docker tag为镜像新增别名，格式对齐私有仓库地址。

docker tag 不会复制镜像文件，仅新增别名映射，新旧标签共用同一个 Image ID。

# 语法：docker tag 原镜像名:原tag 私有仓库地址:版本号
docker tag nginx:1.24 registry.cn-hangzhou.aliyuncs.com/devops-demo/my-flask-app:1.0.0

执行docker images可查询到两条镜像记录，IMAGE ID 完全一致。

1.5.4 推送镜像至阿里云 ACR

docker push registry.cn-hangzhou.aliyuncs.com/devops-demo/my-flask-app:1.0.0

推送完毕后，可在阿里云 ACR 控制台查看已上传镜像。

1.5.5 跨服务器拉取 + 启动容器

在任意装有 Docker 的云服务器执行如下命令：

# 1.登录同域名ACR仓库
docker login --username=你的阿里云账号 registry.cn-hangzhou.aliyuncs.com
# 2.拉取私有镜像
docker pull registry.cn-hangzhou.aliyuncs.com/devops-demo/my-flask-app:1.0.0
# 3.启动容器
docker run -d -p 80:80 registry.cn-hangzhou.aliyuncs.com/devops-demo/my-flask-app:1.0.0

1.6 镜像标签规范

1.6.1 不推荐：latest 标签（生产环境禁用）

latest是浮动指针标签，弊端：

1. 重复推送同名latest会直接覆盖原有标签指向；

2. 今日latest指向 v1.0，下次推送直接改为 v1.1；服务器重启拉取镜像会意外升级版本；

3. 故障回滚无历史版本溯源，无法确认上一稳定版本对应的镜像 ID。

1.6.2 生产环境不可变标签三种规范方案

方案 1：语义化版本 + Git 短 Commit 哈希

# 主版本+commit短哈希，可读+唯一可溯源
docker build -t myapp:1.0.0 -t myapp:1.0.0-abc123 .

• 1.0.0：语义化版本（主版本。次版本。补丁），人工识别；

• 1.0.0-abc123：附加 Git 提交哈希，绑定源码提交记录，全链路追溯。

方案 2：CI 流水线编号标签（自动化流水线场景）

# CI流水线变量生成唯一标签，每条流水线构建版本不重复
docker build -t myapp:ci-$CI_PIPELINE_ID .

方案 3：纯 Git Commit 短哈希标签

docker build -t myapp:$CI_COMMIT_SHORT_SHA .

1.7 国内 Docker 三层网络分层优化方案

国内 Docker 构建 / 拉取慢分三类网络请求，三层问题独立，需分层针对性优化。

第一层：Dockerfile FROM 基础镜像拉取加速

问题：FROM python:3.9从 Docker Hub 拉取基础镜像超时
解决方案：配置 Docker 守护进程镜像加速器

# Linux路径：/etc/docker/daemon.json
{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

重启 Docker 生效：

sudo systemctl restart docker

Windows/Mac Docker Desktop：设置→Docker Engine 内填入相同 json 配置；可选加速器：DaoCloud 公共加速、阿里云个人专属加速、中科大镜像源。

第二层：构建时依赖包下载加速（pip/npm/maven）

构建阶段RUN执行包管理器下载依赖，走国外源速度差，在 Dockerfile 内指定国内源：

# Python pip 国内源示例
RUN pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt

# Node npm国内源示例
RUN npm config set registry https://registry.npmmirror.com && npm install

# Java Maven示例（指定settings.xml配置阿里云maven源）
RUN mvn clean package -Dmaven.repo.local=/cache/m2 -s /path/to/settings.xml

第三层：构建中 git clone 源码加速

构建脚本拉取 GitHub/GitLab 国外源码缓慢：

1. 备选：代码同步至 Gitee / 极狐 GitLab 国内镜像仓库；

2. 备选：Git 客户端配置代理。

三层加速互不干扰，配置镜像加速器≠pip 下载变快，需逐层配置。

1.8 常见故障排查速查表

报错现象	根因分析	解决步骤
dial tcp: lookup ... timeout	网络受限 / 加速器配置失效	校验 daemon.json 加速器地址，替换国内 Registry 域名
unauthorized: authentication required	登录域名和 push 域名不一致、登录失效	docker login 域名必须和 push 镜像前缀域名完全一致（不要带 https://），重新登录
denied: requested access to the resource is denied	命名空间 / 仓库名错误、账号无仓库权限	核对 ACR 控制台命名空间、仓库名称，确认仓库已创建、账号具备读写权限
no such image	docker tag 源镜像名称书写错误	docker images 查看本地真实镜像名与 Tag，重新执行 tag 打标