docker四步搭建本地私有镜像仓库

2025年11月15日 互联网

Docker四步搭建本地私有镜像仓库：从零到一的完整指南

在容器化技术快速发展的今天，Docker已成为企业级应用部署的核心工具。然而，公有镜像仓库（如Docker Hub）存在网络延迟、安全风险及镜像泄露等隐患，尤其是对金融、医疗等敏感行业而言，私有镜像仓库的搭建已成为刚需。本文将通过四步操作，详细讲解如何基于Docker Registry快速构建本地私有镜像仓库，覆盖安装、配置、认证及使用全流程，助力开发者实现镜像管理的安全与高效。

一、环境准备：基础条件与依赖检查

1.1 系统环境要求

搭建私有镜像仓库需满足以下条件：

  • 操作系统：Linux（推荐CentOS 7/8或Ubuntu 20.04+），Windows/macOS需通过WSL2或Docker Desktop实现。
  • Docker版本：建议使用Docker Engine 20.10+（支持Registry 2.0协议）。
  • 存储空间：至少预留20GB磁盘空间（根据镜像数量动态扩展）。
  • 网络配置：确保服务器有固定IP或域名，并开放5000端口（HTTP默认）或443端口（HTTPS推荐）。

1.2 依赖安装

以CentOS 8为例，执行以下命令安装Docker：

  1. # 添加Docker官方仓库
  2. sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  3. # 安装Docker Engine
  4. sudo dnf install docker-ce docker-ce-cli containerd.io
  5. # 启动并设置开机自启
  6. sudo systemctl enable --now docker

验证安装：

  1. docker version
  2. # 输出应包含Client和Server版本信息

二、第一步：部署Docker Registry容器

2.1 基础Registry部署

通过Docker官方Registry镜像快速启动：

  1. docker run -d \
  2.   --name registry \
  3.   -p 5000:5000 \
  4.   --restart=always \
  5.   registry:2.7.1
  • -d：后台运行
  • -p 5000:5000：映射主机5000端口到容器
  • --restart=always：容器崩溃时自动重启
  • registry:2.7.1：指定Registry版本（最新稳定版）

2.2 验证Registry状态

  1. docker ps | grep registry
  2. # 输出应显示registry容器状态为"Up"
  3. curl -I http://localhost:5000/v2/
  4. # 返回200 OK表示服务正常

2.3 存储配置优化

默认情况下，Registry数据存储在容器内，重启后数据丢失。需挂载主机目录：

  1. mkdir -p /data/registry
  2. docker run -d \
  3.   --name registry \
  4.   -p 5000:5000 \
  5.   -v /data/registry:/var/lib/registry \
  6.   --restart=always \
  7.   registry:2.7.1
  • -v /data/registry:/var/lib/registry：将主机目录挂载到容器存储路径

三、第二步：配置HTTPS安全访问

3.1 生成自签名证书

使用OpenSSL生成证书（以域名registry.example.com为例）：

  1. mkdir -p /certs
  2. openssl req -newkey rsa:4096 -nodes -sha256 -keyout /certs/domain.key \
  3.   -x509 -days 365 -out /certs/domain.crt \
  4.   -subj "/CN=registry.example.com"
  • -x509：生成自签名证书
  • -days 365：证书有效期
  • -subj：指定证书主题（CN需与访问域名一致）

3.2 启动支持HTTPS的Registry

  1. docker run -d \
  2.   --name registry \
  3.   -p 443:443 \
  4.   -v /certs:/certs \
  5.   -v /data/registry:/var/lib/registry \
  6.   -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  7.   -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  8.   -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  9.   --restart=always \
  10.   registry:2.7.1
  • -e REGISTRY_HTTP_TLS_*：指定证书路径
  • -p 443:443：使用标准HTTPS端口

3.3 客户端信任配置

将自签名证书添加到客户端信任链（以Ubuntu为例）：

  1. sudo mkdir -p /etc/docker/certs.d/registry.example.com
  2. sudo cp /certs/domain.crt /etc/docker/certs.d/registry.example.com/ca.crt
  3. sudo systemctl restart docker

验证HTTPS访问：

  1. curl -k https://registry.example.com/v2/
  2. # 返回200 OK表示HTTPS配置成功

四、第三步：实现基础认证机制

4.1 生成认证文件

使用htpasswd生成用户名密码（需安装apache2-utils）：

  1. sudo apt install apache2-utils
  2. mkdir -p /auth
  3. htpasswd -Bc /auth/htpasswd admin
  4. # 输入密码后生成加密文件
  • -B：使用bcrypt加密（推荐）
  • -c：创建新文件（后续添加用户时去掉此参数）

4.2 配置Registry认证

启动带认证的Registry：

  1. docker run -d \
  2.   --name registry \
  3.   -p 443:443 \
  4.   -v /certs:/certs \
  5.   -v /auth:/auth \
  6.   -v /data/registry:/var/lib/registry \
  7.   -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
  8.   -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  9.   -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  10.   -e REGISTRY_AUTH=htpasswd \
  11.   -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
  12.   -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  13.   --restart=always \
  14.   registry:2.7.1

4.3 测试认证功能

  1. # 登录测试
  2. docker login registry.example.com
  3. # 输入用户名admin和密码，成功则返回"Login Succeeded"
  5. # 推送镜像测试
  6. docker tag alpine:latest registry.example.com/myapp/alpine:v1
  7. docker push registry.example.com/myapp/alpine:v1
  8. # 成功推送表示认证配置正确

五、第四步：镜像管理与高级配置

5.1 镜像清理策略

Registry默认不自动清理未被引用的镜像层，需手动配置垃圾回收：

  1. # 进入Registry容器
  2. docker exec -it registry sh
  3. # 执行垃圾回收
  4. registry garbage-collect /etc/docker/registry/config.yml

建议通过Cron定时任务执行（如每周日凌晨3点）：

  1. 0 3 * * 0 docker exec registry registry garbage-collect /etc/docker/registry/config.yml

5.2 镜像存储优化

  • 分层存储：Registry 2.0支持分层存储，相同镜像层仅存储一次。
  • 存储驱动：可通过-e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY指定存储路径。
  • S3兼容存储：支持将镜像存储到AWS S3或MinIO对象存储： 
    1. -e REGISTRY_STORAGE=s3 \
    2. -e REGISTRY_STORAGE_S3_ACCESSKEY=your-access-key \
    3. -e REGISTRY_STORAGE_S3_SECRETKEY=your-secret-key \
    4. -e REGISTRY_STORAGE_S3_BUCKET=your-bucket \
    5. -e REGISTRY_STORAGE_S3_REGION=us-east-1

5.3 监控与日志

  • 日志收集：通过-v /var/log/registry:/var/log/registry挂载日志目录。
  • Prometheus监控：启用Registry的Prometheus指标端点： 
    1. -e REGISTRY_HTTP_HEADERS_ACCESS_CONTROL_ALLOW_ORIGIN='[*]' \
    2. -e REGISTRY_METRICS_ENABLED=true

    配置Prometheus抓取/metrics端点数据。

六、常见问题与解决方案

6.1 推送镜像报错x509: certificate signed by unknown authority

原因：客户端未信任自签名证书。
解决方案：

  1. 将证书复制到/etc/docker/certs.d/<域名>/ca.crt。
  2. 或在docker push时添加--insecure-registry参数（不推荐生产环境使用）。

6.2 认证失败401 Unauthorized

检查项：

  • 确认htpasswd文件路径和权限正确（需644权限）。
  • 验证REGISTRY_AUTH_HTPASSWD_PATH环境变量是否指向正确文件。

6.3 存储空间不足

解决方案：

  1. 扩展磁盘空间或挂载新存储卷。
  2. 执行垃圾回收清理未使用的镜像层。

七、总结与最佳实践

7.1 核心步骤回顾

  1. 部署Registry容器：基础服务启动与存储挂载。
  2. 配置HTTPS：自签名证书生成与客户端信任。
  3. 实现认证：htpasswd文件生成与Registry集成。
  4. 高级管理：垃圾回收、存储优化与监控配置。

7.2 生产环境建议

  • 高可用部署：通过Kubernetes或Docker Swarm实现Registry集群。
  • 备份策略：定期备份/var/lib/registry目录或S3存储。
  • 网络隔离：限制Registry访问IP范围，仅允许内网或VPN访问。

通过以上四步操作，开发者可快速搭建一个安全、高效的Docker私有镜像仓库，满足企业级应用对镜像管理的核心需求。实际部署中，需根据业务规模动态调整存储、认证及监控配置，确保系统长期稳定运行。

最新文章