手把手教你搭建镜像仓库并上传/下载镜像

2025年11月15日 互联网

在容器化技术广泛应用的今天，私有镜像仓库已成为企业开发者保障代码安全、提升部署效率的核心基础设施。本文将以Docker Registry为核心工具，通过分步骤实操指南，详细讲解如何从零搭建私有镜像仓库，并完成镜像的上传与下载操作。无论您是初次接触容器技术的开发者，还是需要优化CI/CD流程的技术团队，本文都将提供可落地的解决方案。

一、环境准备：搭建前的必要条件

1.1 服务器环境选择

私有镜像仓库对服务器配置要求较低，建议选择Linux系统（如CentOS 8/Ubuntu 22.04），硬件配置方面：

  • 基础版：2核CPU/4GB内存/50GB磁盘（适合中小团队）
  • 生产环境：4核CPU/8GB内存/200GB以上磁盘（支持高并发）

1.2 Docker安装与验证

通过官方脚本快速安装Docker：

  1. curl -fsSL https://get.docker.com | sh
  2. systemctl enable --now docker
  3. docker --version  # 应输出版本信息

1.3 防火墙配置要点

开放5000端口（默认Registry端口）：

  1. # CentOS
  2. firewall-cmd --add-port=5000/tcp --permanent
  3. firewall-cmd --reload
  5. # Ubuntu
  6. ufw allow 5000/tcp

二、镜像仓库搭建：三种方案详解

2.1 基础版：本地Registry服务

  1. docker run -d -p 5000:5000 --restart=always --name registry registry:2

验证服务状态：

  1. curl http://localhost:5000/v2/_catalog
  2. # 应返回 {"repositories":[]}

2.2 进阶版：带认证的Registry

生成密码文件：

  1. mkdir -p /auth
  2. docker run --entrypoint htpasswd httpd:2 -Bbn admin password123 > /auth/htpasswd

启动带认证的Registry：

  1. docker run -d -p 5000:5000 \
  2.   --name registry-auth \
  3.   -v /auth:/auth \
  4.   -e REGISTRY_AUTH=htpasswd \
  5.   -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
  6.   -e REGISTRY_AUTH_HTPASSWD_PATH="/auth/htpasswd" \
  7.   -e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry \
  8.   --restart=always \
  9.   registry:2

2.3 企业版：Harbor高可用部署

  1. 下载Harbor安装包：

    1. wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz
    2. tar xvf harbor-offline-installer-v2.9.0.tgz

  2. 修改配置文件：

    1. # harbor.yml
    2. hostname: registry.example.com
    3. http:
    4. port: 80
    5. https:
    6. certificate: /path/to/cert.pem
    7. private_key: /path/to/key.pem

  3. 执行安装脚本：

    1. ./install.sh --with-trivy --with-chartmuseum

三、镜像操作全流程指南

3.1 镜像标记与上传

  1. 标记本地镜像：

    1. docker tag nginx:latest localhost:5000/my-nginx:v1

  2. 推送镜像到私有仓库：

    1. docker push localhost:5000/my-nginx:v1
    2. # 带认证的推送：
    3. docker login localhost:5000
    4. Username: admin
    5. Password: 
    6. docker push localhost:5000/my-nginx:v1

3.2 镜像下载与验证

  1. 拉取镜像：

    1. docker pull localhost:5000/my-nginx:v1

  2. 验证镜像完整性：

    1. docker inspect localhost:5000/my-nginx:v1 | grep "RepoDigests"
    2. # 应返回镜像的digest值

3.3 仓库管理命令

查看仓库中的镜像：

  1. curl http://localhost:5000/v2/_catalog
  2. # 查看特定镜像的标签：
  3. curl http://localhost:5000/v2/my-nginx/tags/list

删除镜像（需Registry 2.4+）：

  1. # 1. 停止Registry容器
  2. docker stop registry
  4. # 2. 配置存储驱动（filesystem为例）
  5. # 3. 手动删除存储目录中的镜像
  6. rm -rf /var/lib/registry/docker/registry/v2/repositories/my-nginx
  8. # 4. 启动容器并运行垃圾回收
  9. docker start registry
  10. docker exec registry bin/registry garbage-collect /etc/registry/config.yml

四、生产环境优化建议

4.1 存储方案选择

存储类型 适用场景 配置要点
本地存储 开发测试环境 定期备份/var/lib/registry目录
NFS存储 多节点访问 配置软挂载（soft/noexec选项）
S3兼容存储 生产环境 配置endpoint/access_key/secret_key

4.2 性能调优参数

在Registry启动时添加以下环境变量：

  1. -e REGISTRY_STORAGE_DELETE_ENABLED=true \
  2. -e REGISTRY_CACHE_BLOBDESCRIPTOR=inmemory \
  3. -e REGISTRY_HTTP_SECRET=your_secret_key \
  4. -e REGISTRY_STORAGE_FILESYSTEM_MAXTHREADS=100

4.3 安全加固措施

  1. 启用TLS加密：

    1. openssl req -newkey rsa:4096 -nodes -sha256 \
    2. -keyout domain.key -x509 -days 365 \
    3. -out domain.crt -subj "/CN=registry.example.com"

  2. 配置Nginx反向代理：

    1. server {
    2.  listen 443 ssl;
    3.  server_name registry.example.com;
    5.  ssl_certificate /path/to/domain.crt;
    6.  ssl_certificate_key /path/to/domain.key;
    8.  location / {
    9.      proxy_pass http://localhost:5000;
    10.      proxy_set_header Host $host;
    11.  }
    12. }

五、常见问题解决方案

5.1 推送镜像报错”denied: requested access to the resource is denied”

原因：未正确标记镜像或认证失败
解决方案：

  1. 确认镜像标签格式为<registry_host>:<port>/<namespace>/<image>:<tag>
  2. 执行docker login重新认证

5.2 仓库访问404错误

排查步骤：

  1. 检查Registry服务状态：docker ps | grep registry
  2. 验证端口连通性：telnet registry_host 5000
  3. 查看日志：docker logs registry

5.3 存储空间不足

清理方案：

  1. 启用自动删除：

    1. # config.yml
    2. storage:
    3. delete:
    4.  enabled: true

  2. 手动清理未引用的层：

    1. docker exec registry bin/registry garbage-collect /etc/registry/config.yml

六、进阶应用场景

6.1 多项目镜像隔离

通过Harbor的项目功能实现：

  1. 创建独立项目：http://harbor_host/harbor/projects/new
  2. 推送镜像时指定项目： 
    1. docker tag nginx:latest harbor_host/project1/nginx:v1
    2. docker push harbor_host/project1/nginx:v1

6.2 镜像扫描集成

Harbor内置Trivy扫描器配置：

  1. 在harbor.yml中启用：

    1. trivy:
    2. enabled: true
    3. ignore_unfixed: false
    4. skip_update: false
    5. insecure: false

  2. 执行扫描：

    1. curl -u admin:password123 -X POST "http://harbor_host/api/v2.0/projects/1/artifacts/nginx%3Av1/scan"

6.3 跨区域同步

配置Harbor复制规则：

  1. 在目标Harbor创建项目
  2. 在源Harbor设置：System Management > Replications
  3. 添加复制规则：
    • 模式：Push-based
    • 目标URL：http://target_harbor/api/v2.0
    • 触发方式：Manual/Scheduled

通过本文的详细指导，您已掌握从基础Registry部署到企业级Harbor管理的完整技能链。实际生产环境中，建议结合CI/CD工具链（如Jenkins、GitLab CI）实现镜像的自动化构建与推送，同时通过Prometheus+Grafana监控仓库性能指标。对于超大规模部署，可考虑采用分布式存储方案（如Ceph）作为后端存储，确保镜像仓库的高可用性与扩展性。

最新文章
热门标签