本文提供了搭建一个稳定、可复用的容器镜像服务器（私有镜像仓库），用于存储和管理 Docker 镜像，替代公共仓库（如 Docker Hub），满足内网 / 生产环境的镜像管理需求。基于最成熟的 Docker Registry 2.x，提供完整、可落地的搭建流程，包括基础部署、安全加固、客户端使用和运维技巧。

一、环境前置要求

确保你的服务器满足以下条件：

• 操作系统：Linux（CentOS/Ubuntu/Debian 均可）
• 已安装 Docker（版本 ≥ 20.10，安装教程可参考官方文档）
• 开放 5000 端口（仓库默认端口，可自定义）
• 服务器有至少 10GB 以上可用磁盘空间（存储镜像）

二、分步搭建流程

步骤 1：创建持久化目录（核心）

容器内的镜像数据默认存储在容器内部，删除容器会丢失数据，因此先创建宿主机目录挂载：

# 创建镜像存储目录
mkdir -p /data/registry/images
# 创建认证文件目录（后续用于密码登录）
mkdir -p /data/registry/auth
# 设置目录权限，避免权限不足
chmod -R 755 /data/registry

步骤 2：配置用户认证（生产环境必选）

为仓库添加用户名密码认证，防止匿名访问：

# 安装 htpasswd 工具（生成密码文件）
# CentOS/RHEL
yum install -y httpd-tools
# Ubuntu/Debian
apt update && apt install -y apache2-utils

# 创建管理员账号（示例：用户名 registry-admin，密码 123456Ab！）
# -B：使用 bcrypt 加密（更安全）；-c：创建新文件
htpasswd -Bc /data/registry/auth/htpasswd registry-admin 123456Ab!
# htpasswd -Bbn registry-admin 123456Ab! > auth/htpasswd
# 如需添加更多用户，去掉 -c（避免覆盖）：
# htpasswd -B /data/registry/auth/htpasswd test-user 654321Ba!

步骤 3：启动 Registry 容器

通过 Docker 一键启动私有仓库，整合存储和认证：

docker run -d \
  --name private-registry \
  --restart=always \  # 服务器重启后自动启动
  -p 5000:5000 \      # 宿主机端口:容器端口（可改宿主机端口，如 8080:5000）
  -v /data/registry/images:/var/lib/registry \  # 挂载镜像存储目录
  -v /data/registry/auth:/auth \                # 挂载认证目录
  -e "REGISTRY_AUTH=htpasswd" \                 # 启用 htpasswd 认证
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Private Registry" \  # 认证提示语
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \     # 密码文件路径
  registry:2  # 官方 Registry 2.x 镜像（稳定版）

步骤 4：验证仓库是否启动成功

# 1. 查看容器状态（显示 Up 表示运行正常）
docker ps | grep private-registry

# 2. 测试未认证访问（应返回 401 未授权）
curl http://你的服务器IP:5000/v2/_catalog
# 预期输出：{"errors":[{"code":"UNAUTHORIZED","message":"authentication required"}]}

# 3. 测试认证访问（替换账号密码）
curl -u registry-admin:123456Ab! http://你的服务器IP:5000/v2/_catalog
# 预期输出：{"repositories":[]}（空列表表示仓库已就绪，暂无镜像）

三、客户端使用私有仓库（推送 / 拉取镜像）

步骤 1：客户端配置（允许访问私有仓库）

如果仓库未配置 HTTPS（内网场景），需要在客户端（推送 / 拉取镜像的机器）添加信任：

# 编辑 Docker 配置文件
vi /etc/docker/daemon.json

# 添加以下内容（替换为你的仓库地址）
{
  "insecure-registries": ["你的服务器IP:5000"]
}

# 重启 Docker 生效
systemctl restart docker

步骤 2：登录私有仓库

docker login 你的服务器IP:5000
# 输入步骤2创建的用户名（registry-admin）和密码，提示「Login Succeeded」即成功

步骤 3：推送镜像到私有仓库

# 1. 给本地镜像打标签（格式：仓库地址/镜像名:标签）
# 示例：将本地 nginx:latest 打标签为 192.168.1.100:5000/nginx:v1
docker tag nginx:latest 你的服务器IP:5000/nginx:v1

# 2. 推送镜像
docker push 你的服务器IP:5000/nginx:v1

# 3. 验证推送结果（查看仓库内的镜像列表）
curl -u registry-admin:123456Ab! http://你的服务器IP:5000/v2/_catalog
# 预期输出：{"repositories":["nginx"]}

步骤 4：从私有仓库拉取镜像

# 1. （可选）删除本地镜像，测试拉取
docker rmi 你的服务器IP:5000/nginx:v1

# 2. 拉取镜像
docker pull 你的服务器IP:5000/nginx:v1

# 3. 查看拉取结果
docker images | grep nginx

四、进阶优化（生产环境建议）

1. 配置 HTTPS（避免明文传输）

如果仓库暴露在外网，建议配置 SSL 证书（以 Let’s Encrypt 免费证书为例）：

# 假设证书文件路径：/data/registry/certs/fullchain.pem（公钥）、/data/registry/certs/privkey.pem（私钥）
docker run -d \
  --name private-registry \
  --restart=always \
  -p 443:5000 \  # 改用 443 端口（HTTPS 默认端口）
  -v /data/registry/images:/var/lib/registry \
  -v /data/registry/auth:/auth \
  -v /data/registry/certs:/certs \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.pem" \
  -e "REGISTRY_HTTP_TLS_KEY=/certs/privkey.pem" \
  registry:2

2. 镜像清理（释放磁盘空间）

仓库运行一段时间后会产生无用镜像（如删除标签后的镜像），需定期清理：

# 进入容器执行清理命令
docker exec -it private-registry registry garbage-collect /etc/docker/registry/config.yml

# 建议添加定时任务（每天凌晨 2 点清理）
echo "0 2 * * * docker exec -it private-registry registry garbage-collect /etc/docker/registry/config.yml" >> /var/spool/cron/root

总结

1. 私有镜像仓库核心是基于 registry:2 镜像，通过目录挂载实现数据持久化，通过 htpasswd 实现密码认证。
2. 客户端使用时，需先登录仓库，且镜像标签必须包含「仓库 IP: 端口」才能正常推送 / 拉取。
3. 生产环境需开启认证，外网场景建议配置 HTTPS，同时定期清理无用镜像节省磁盘空间。