一、教程简介
Docker 原生 Registry 是官方提供的 轻量级私有镜像仓库工具，无需复杂配置，仅需一行命令即可启动，适合快速搭建测试环境、小型团队内部镜像共享，或对仓库功能无复杂需求的场景。
本教程将完整覆盖：Registry 仓库部署、镜像推送 / 拉取、跨机器访问、常见问题排查，全程基于 Ubuntu 16.04+/20.04+ 系统实操。
二、前提准备
1. 环境要求
- 操作系统：Ubuntu 64 位（16.04 及以上版本，Debian 系通用）；
- 已安装 Docker：确保 Docker 引擎正常运行（建议版本 18.09+）；
- 权限要求：全程使用 sudo 或 root 权限操作；
- 网络要求：服务器需开放 5000 端口（Registry 默认端口），跨机器访问需网络互通。
2. 验证 Docker 环境
# 查看 Docker 版本
docker --version
# 验证 Docker 服务状态
sudo systemctl status docker
- 若未安装 Docker，可先执行以下命令快速安装：
sudo apt update && sudo apt install -y docker.io
sudo systemctl enable docker && sudo systemctl start docker
三、核心步骤：搭建原生 Registry 私有仓库
1. 启动 Registry 容器（一键部署）
# 创建并启动 Registry 私有仓库容器
sudo docker run -d \
-p 5000:5000 \
--restart=always \
--name registry \
-v /data/registry:/var/lib/registry \ # 数据持久化（可选，推荐）
registry
- 核心参数详解：
| 参数 | 作用说明 |
|---|---|
| -d | 容器后台运行（守护进程模式） |
| -p 5000:5000 | 端口映射：主机 5000 端口 → 容器 5000 端口（Registry 默认监听 5000 端口） |
| --restart=always | 容器异常退出 / 服务器重启后自动重启，保证服务可用性 |
| --name registry | 容器命名为 registry，便于后续管理（如启动、停止、查看日志） |
| -v /data/registry:/var/lib/registry | 数据卷挂载：将镜像数据存储到主机 /data/registry 目录，避免容器删除后数据丢失 |
| registry | 拉取官方 Registry 镜像（默认最新版，如需指定版本可加标签，如 registry:2） |
2. 验证 Registry 服务启动成功
# 查看 Registry 容器状态
sudo docker ps | grep registry
# 成功输出示例（状态为 Up 表示运行正常）：
# abc123456789 registry "/entrypoint.sh /etc…" 5 minutes ago Up 5 minutes 0.0.0.0:5000->5000/tcp registry
四、镜像操作：推送 / 拉取 / 验证
假设本地已构建好镜像（示例：react-admin-server:v1），以下操作实现镜像与私有仓库的交互：
1. 标记本地镜像（适配私有仓库格式）
Docker 推送镜像到私有仓库时，需按「仓库地址 / 镜像名：版本」格式标记镜像，否则会默认推送到 Docker Hub 官方仓库。
# 格式：docker tag 本地镜像名:版本 仓库地址:端口/镜像名:版本
# 本地访问标记（仅本机使用）
sudo docker tag react-admin-server:v1 127.0.0.1:5000/react-admin-server:v1
# 远程访问标记（供其他机器访问，替换为服务器实际IP）
sudo docker tag react-admin-server:v1 192.168.0.1:5000/react-admin-server:v1
2. 解决非 HTTPS 推送限制（关键配置）
Docker 默认禁止非 HTTPS 方式推送镜像到私有仓库，需配置 daemon.json 允许当前 Registry 为「不安全仓库」：
# 编辑 Docker 配置文件
sudo vim /etc/docker/daemon.json
# 写入以下配置（添加 insecure-registries 字段）
{
"registry-mirrors": [ # 镜像加速器（可选，优化拉取速度）
"https://hub-mirror.c.163.com",
"https://mirror.baidubce.com"
],
"insecure-registries": [
"192.168.0.1:5000", # 服务器IP:端口（远程访问必须配置）
"127.0.0.1:5000" # 本地IP:端口（本地访问可选）
]
}
# 重载配置并重启 Docker，使配置生效
sudo systemctl daemon-reload
sudo systemctl restart docker
# 重启 Registry 容器（确保配置同步）
sudo docker restart registry
3. 推送镜像到私有仓库
# 推送本地标记的镜像（本地访问格式）
sudo docker push 127.0.0.1:5000/react-admin-server:v1
# 推送远程访问格式镜像（供其他机器拉取）
sudo docker push 192.168.0.1:5000/react-admin-server:v1
- 成功输出示例（显示 Pushed 表示推送完成）：
The push refers to repository [192.168.0.1:5000/react-admin-server]
abcdef123456: Pushed
7890abcd1234: Pushed
v1: digest: sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx size: 1234
4. 验证仓库中的镜像（curl 测试）
通过 Registry 提供的 HTTP API 查看仓库中的镜像列表，确认推送成功：
# 查看仓库中所有镜像
curl 127.0.0.1:5000/v2/_catalog
# 成功输出（repositories 数组中包含推送的镜像名）：
# {"repositories":["react-admin-server"]}
# 查看指定镜像的所有版本标签
curl 127.0.0.1:5000/v2/react-admin-server/tags/list
# 成功输出（tags 数组中包含镜像版本）：
# {"name":"react-admin-server","tags":["v1"]}
5. 从私有仓库拉取镜像（测试可用性）
# 先删除本地已有的镜像（避免冲突，验证拉取效果）
sudo docker image rm 127.0.0.1:5000/react-admin-server:v1
sudo docker image rm 192.168.0.1:5000/react-admin-server:v1（若已标记）
# 从私有仓库拉取镜像
sudo docker pull 127.0.0.1:5000/react-admin-server:v1
# 查看拉取结果（确认镜像已恢复）
sudo docker images
五、跨机器访问：其他机器拉取私有仓库镜像
假设需要从另一台 Ubuntu 机器访问 192.168.0.1:5000 私有仓库，步骤如下：
1. 配置客户端 Docker（关键）
在客户端机器上执行以下配置，允许访问非 HTTPS 私有仓库：
# 编辑客户端 Docker 配置文件
sudo vim /etc/docker/daemon.json
# 添加服务器 IP:端口 到 insecure-registries
{
"insecure-registries": ["192.168.0.1:5000"]
}
# 重载配置并重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker
2. 拉取远程私有仓库镜像
# 客户端直接拉取服务器私有仓库的镜像
sudo docker pull 192.168.0.1:5000/react-admin-server:v1
# 验证拉取结果
sudo docker images
六、Registry 仓库管理常用命令
1. 容器生命周期管理
# 启动 Registry 容器
sudo docker start registry
# 停止 Registry 容器
sudo docker stop registry
# 重启 Registry 容器
sudo docker restart registry
# 强制删除 Registry 容器（数据会丢失，需先备份 /data/registry）
sudo docker rm -f registry
2. 日志查看与问题排查
# 实时查看 Registry 容器日志（推送/拉取失败时排查）
sudo docker logs -f registry
3. 清理仓库无用镜像（释放磁盘空间）
Registry 不会自动清理无标签镜像（dangling images），需手动执行清理命令：
# 进入 Registry 容器
sudo docker exec -it registry /bin/sh
# 执行垃圾回收命令（清理无标签镜像）
registry garbage-collect /etc/docker/registry/config.yml
# 退出容器
exit
七、安全优化（生产环境必看）
原生 Registry 默认无认证、无加密，仅适用于内网测试环境，生产环境建议做以下优化：
1. 配置用户名密码认证
# 1. 安装 htpasswd 工具（用于生成密码文件）
sudo apt install -y apache2-utils
# 2. 创建密码存储目录
sudo mkdir -p /etc/registry/auth
# 3. 生成用户密码文件（示例用户：admin，密码：test123）
sudo htpasswd -Bc /etc/registry/auth/htpasswd admin
# 4. 重启 Registry 容器，挂载密码文件（替换原启动命令）
sudo docker run -d \
-p 5000:5000 \
--restart=always \
--name registry \
-v /data/registry:/var/lib/registry \
-v /etc/registry/auth:/auth \
-e REGISTRY_AUTH=htpasswd \
-e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
registry
# 5. 登录私有仓库（后续推送/拉取需先登录）
sudo docker login 192.168.0.1:5000
# 输入用户名 admin 和密码 test123
2. 启用 HTTPS 加密（替代 insecure-registries）
使用 Let's Encrypt 免费证书配置 HTTPS，避免非加密传输风险：
# 假设已获取 SSL 证书（fullchain.pem 和 privkey.pem），存储在 /etc/registry/certs 目录
sudo docker run -d \
-p 443:5000 \
--restart=always \
--name registry \
-v /data/registry:/var/lib/registry \
-v /etc/registry/certs:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.pem \
-e REGISTRY_HTTP_TLS_KEY=/certs/privkey.pem \
registry
- 访问格式改为：https://192.168.0.1/react-admin-server:v1，无需配置 insecure-registries。
3. 限制访问 IP（防火墙规则）
仅允许指定网段访问 Registry 端口，减少攻击面：
# Ubuntu 防火墙放行规则（仅允许 192.168.0.0/24 网段访问 5000 端口）
sudo ufw allow from 192.168.0.0/24 to any port 5000
sudo ufw reload
八、常见问题排查
1. 推送镜像提示「http: server gave HTTP response to HTTPS client」
- 原因：未配置 insecure-registries，Docker 强制要求 HTTPS；
- 解决：按步骤 4 配置 daemon.json，重载配置并重启 Docker。
2. 跨机器拉取提示「connection refused」
- 原因：服务器防火墙未放行 5000 端口，或 Registry 容器未启动；
- 解决：
-
- 服务器执行 sudo ufw allow 5000/tcp 开放端口；
-
- 确认 Registry 容器状态：sudo docker ps | grep registry。
3. 推送成功但 curl 无法查看镜像
- 原因：Registry 镜像版本过低，或数据卷挂载异常；
- 解决：
-
- 拉取指定版本镜像：sudo docker pull registry:2；
-
- 检查数据卷挂载：sudo docker inspect registry | grep Mounts，确认 /var/lib/registry 已挂载到主机目录。
4. 登录提示「Error response from daemon: Get "https://192.168.0.1:5000/v2/": http: server gave HTTP response to HTTPS client」
- 原因：已配置认证，但未启用 HTTPS，且未添加 insecure-registries；
- 解决：要么配置 HTTPS，要么在客户端添加 insecure-registries（测试环境临时方案）。
九、总结
Docker 原生 Registry 是「轻量、快速、零配置」的私有仓库方案，适合：
- 测试环境镜像共享；
- 小型团队内部镜像管理；
- 快速验证私有仓库功能。
若需要权限管理、镜像复制、审计日志等企业级功能，可参考 Harbor 私有仓库教程。本教程覆盖从部署到优化的全流程，按步骤操作即可快速搭建可用的私有镜像仓库～
