明知山没虎

一个游手好闲的人

首页

Docker私有镜像仓库搭建指南

2025-12-24

概述

私有镜像仓库允许你在内网环境中安全地存储和分发Docker镜像，适用于以下场景：

  • 企业内部应用部署

  • 敏感代码的镜像存储

  • 减少外网依赖

  • 提高镜像拉取速度

方案对比

方案

复杂度

功能

适用场景

Docker Registry

简单

基础镜像存储

个人项目、小型团队

Harbor

中等

企业级功能、Web UI

中大型团队、企业

云服务商

简单

托管服务、高可用

商业项目、快速上线

方案一：Docker Registry

1. 快速启动

最简单的方式：

docker run -d \
  --name registry \
  -p 5000:5000 \
  -v /opt/registry:/var/lib/registry \
  --restart=always \
  registry:2

2. 使用Docker Compose部署

创建项目目录：

mkdir docker-registry
cd docker-registry

创建 docker-compose.yml：

version: '3.8'

services:
  registry:
    image: registry:2
    container_name: private-registry
    ports:
      - "5000:5000"
    volumes:
      - ./data:/var/lib/registry
      - ./auth:/auth
      - ./certs:/certs
      - ./config.yml:/etc/docker/registry/config.yml
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: 'true'
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
      REGISTRY_HTTP_TLS_KEY: /certs/domain.key
    restart: unless-stopped

  registry-ui:
    image: joxit/docker-registry-ui:latest
    container_name: registry-ui
    ports:
      - "8080:80"
    environment:
      SINGLE_REGISTRY: 'true'
      REGISTRY_TITLE: My Private Registry
      DELETE_IMAGES: 'true'
      SHOW_CONTENT_DIGEST: 'true'
      NGINX_PROXY_PASS_URL: http://registry:5000
      SHOW_CATALOG_NB_TAGS: 'true'
      CATALOG_MIN_BRANCHES: 1
      CATALOG_MAX_BRANCHES: 1
      TAGLIST_PAGE_SIZE: 100
      REGISTRY_SECURED: 'false'
    depends_on:
      - registry
    restart: unless-stopped

3. 配置认证

创建认证文件：

# 创建目录
mkdir auth

# 安装htpasswd工具
sudo apt-get update
sudo apt-get install apache2-utils

# 创建用户（用户名：admin，密码：password123）
htpasswd -Bbn admin password123 > auth/htpasswd

# 添加更多用户
htpasswd -Bb auth/htpasswd user1 password1
htpasswd -Bb auth/htpasswd user2 password2

4. 配置HTTPS

使用自签名证书：

# 创建证书目录
mkdir certs

# 生成自签名证书
openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout certs/domain.key \
  -x509 -days 365 \
  -out certs/domain.crt \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=MyCompany/CN=registry.local"

使用Let's Encrypt证书：

# 安装certbot
sudo apt-get install certbot

# 获取证书
sudo certbot certonly --standalone -d your-registry.com

# 复制证书到项目目录
sudo cp /etc/letsencrypt/live/your-registry.com/fullchain.pem certs/domain.crt
sudo cp /etc/letsencrypt/live/your-registry.com/privkey.pem certs/domain.key
sudo chown $USER:$USER certs/*

5. 自定义配置文件

创建 config.yml：

version: 0.1
log:
  accesslog:
    disabled: false
  level: info
  formatter: text
  fields:
    service: registry
    environment: production

storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false

http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
    Access-Control-Allow-Origin: ['*']
    Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS', 'DELETE']
    Access-Control-Allow-Headers: ['Authorization', 'Accept', 'Cache-Control']

health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3

proxy:
  remoteurl: https://registry-1.docker.io
  username: your-dockerhub-username
  password: your-dockerhub-password

6. 启动服务

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 检查服务状态
docker-compose ps

方案二：Harbor

Harbor是一个开源的企业级Docker Registry，提供了丰富的功能。

1. 系统要求

  • Docker 17.06.0-ce+ 或更高版本

  • Docker Compose 1.18.0+ 或更高版本

  • 至少4GB内存

2. 下载安装

# 下载Harbor离线安装包
cd /opt
wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz

# 解压
tar xvf harbor-offline-installer-v2.9.0.tgz
cd harbor

3. 配置Harbor

复制配置文件：

cp harbor.yml.tmpl harbor.yml

编辑 harbor.yml：

# Harbor的访问地址
hostname: harbor.example.com

# HTTP配置
http:
  port: 80

# HTTPS配置（推荐）
https:
  port: 443
  certificate: /opt/harbor/certs/harbor.example.com.crt
  private_key: /opt/harbor/certs/harbor.example.com.key

# 管理员密码
harbor_admin_password: Harbor12345

# 数据库配置
database:
  password: root123
  max_idle_conns: 100
  max_open_conns: 900

# 数据存储位置
data_volume: /data/harbor

# 日志配置
log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
    location: /var/log/harbor

# 其他配置
trivy:
  ignore_unfixed: false
  skip_update: false
  offline_scan: false

jobservice:
  max_job_workers: 10

notification:
  webhook_job_max_retry: 3

chart:
  absolute_url: disabled

_version: 2.9.0

# Trivy扫描器配置
trivy:
  ignore_unfixed: false
  skip_update: false
  offline_scan: false
  security_check: vuln
  insecure: false

4. 生成证书

# 创建证书目录
mkdir -p certs

# 生成CA私钥
openssl genrsa -out certs/ca.key 4096

# 生成CA证书
openssl req -new -x509 -days 365 -key certs/ca.key -out certs/ca.crt -subj "/C=CN/ST=Beijing/L=Beijing/O=Harbor/CN=Harbor CA"

# 生成服务器私钥
openssl genrsa -out certs/harbor.example.com.key 4096

# 生成证书请求
openssl req -new -key certs/harbor.example.com.key -out certs/harbor.example.com.csr -subj "/C=CN/ST=Beijing/L=Beijing/O=Harbor/CN=harbor.example.com"

# 生成服务器证书
openssl x509 -req -days 365 -in certs/harbor.example.com.csr -CA certs/ca.crt -CAkey certs/ca.key -CAcreateserial -out certs/harbor.example.com.crt

# 设置权限
chmod 600 certs/*

5. 安装Harbor

# 准备环境
sudo ./prepare

# 安装Harbor（包含Trivy漏洞扫描）
sudo ./install.sh --with-trivy

# 或者安装完整版（包含所有组件）
sudo ./install.sh --with-trivy --with-chartmuseum

6. 管理Harbor

# 停止Harbor
sudo docker-compose down -v

# 启动Harbor
sudo docker-compose up -d

# 查看Harbor服务状态
sudo docker-compose ps

# 查看日志
sudo docker-compose logs -f

方案三：云服务商方案

阿里云容器镜像服务（ACR）

个人版（免费）

# 登录
docker login --username=your-aliyun-username registry.cn-hangzhou.aliyuncs.com

# 推送镜像
docker tag my-app:latest registry.cn-hangzhou.aliyuncs.com/namespace/my-app:latest
docker push registry.cn-hangzhou.aliyuncs.com/namespace/my-app:latest

# 拉取镜像
docker pull registry.cn-hangzhou.aliyuncs.com/namespace/my-app:latest

企业版配置

# 登录企业版
docker login --username=your-username your-registry.cn-hangzhou.cr.aliyuncs.com

# 使用专有网络
docker pull your-registry-vpc.cn-hangzhou.cr.aliyuncs.com/namespace/my-app:latest

腾讯云容器镜像服务（TCR）

# 登录TCR
docker login ccr.ccs.tencentyun.com --username=your-username

# 推送镜像
docker tag my-app:latest ccr.ccs.tencentyun.com/namespace/my-app:latest
docker push ccr.ccs.tencentyun.com/namespace/my-app:latest

客户端配置

1. 配置不安全的Registry

对于HTTP协议的私有仓库，需要配置Docker daemon。

编辑 /etc/docker/daemon.json：

{
  "insecure-registries": [
    "registry.local:5000",
    "192.168.1.100:5000"
  ],
  "registry-mirrors": [
    "https://registry.local:5000"
  ]
}

重启Docker服务：

sudo systemctl restart docker

2. 配置自签名证书

# 创建证书目录
sudo mkdir -p /etc/docker/certs.d/registry.local:5000

# 复制CA证书
sudo cp certs/ca.crt /etc/docker/certs.d/registry.local:5000/ca.crt

# 重启Docker服务
sudo systemctl restart docker

3. 使用私有仓库

# 登录私有仓库
docker login registry.local:5000

# 推送镜像
docker tag nginx:latest registry.local:5000/nginx:latest
docker push registry.local:5000/nginx:latest

# 拉取镜像
docker pull registry.local:5000/nginx:latest

# 查看仓库中的镜像
curl -u admin:password123 http://registry.local:5000/v2/_catalog

高级配置

1. Nginx反向代理

创建 nginx.conf：

upstream registry {
    server registry:5000;
}

server {
    listen 80;
    server_name registry.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name registry.example.com;

    ssl_certificate /etc/ssl/certs/registry.example.com.crt;
    ssl_certificate_key /etc/ssl/private/registry.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    client_max_body_size 0;
    chunked_transfer_encoding on;

    location /v2/ {
        proxy_pass http://registry;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 900;
        
        # 禁用缓存
        proxy_buffering off;
        proxy_request_buffering off;
    }

    location / {
        proxy_pass http://registry-ui;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. 备份策略

创建备份脚本 backup.sh：

#!/bin/bash

BACKUP_DIR="/backup/registry"
DATE=$(date +%Y%m%d_%H%M%S)
REGISTRY_DATA="/opt/registry/data"

# 创建备份目录
mkdir -p $BACKUP_DIR

# 停止Registry服务
docker-compose stop registry

# 创建数据备份
tar -czf $BACKUP_DIR/registry_data_$DATE.tar.gz -C $REGISTRY_DATA .

# 启动Registry服务
docker-compose start registry

# 清理7天前的备份
find $BACKUP_DIR -name "registry_data_*.tar.gz" -mtime +7 -delete

echo "Backup completed: registry_data_$DATE.tar.gz"

设置定时备份：

# 编辑crontab
crontab -e

# 添加每天凌晨2点备份
0 2 * * * /opt/registry/backup.sh >> /var/log/registry_backup.log 2>&1

3. 监控配置

使用Prometheus监控Registry：

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'docker-registry'
    static_configs:
      - targets: ['registry:5000']
    metrics_path: /metrics
    scrape_interval: 30s

最佳实践

1. 安全配置

  • 启用HTTPS：生产环境必须使用HTTPS

  • 用户认证：配置强密码和定期更换

  • 网络隔离：使用防火墙限制访问

  • 定期更新：及时更新Registry版本

2. 性能优化

  • 存储优化：使用SSD存储提高性能

  • 缓存配置：合理配置缓存大小

  • 网络优化：使用CDN加速镜像分发

  • 垃圾清理：定期清理未使用的镜像

3. 运维管理

  • 日志管理：配置日志轮转和集中收集

  • 监控告警：设置服务监控和异常告警

  • 备份恢复：制定完整的备份恢复方案

  • 文档维护：维护详细的操作文档

故障排除

常见问题

1. 无法推送镜像

# 检查Docker daemon配置
sudo cat /etc/docker/daemon.json

# 检查Registry服务状态
docker-compose ps

# 查看Registry日志
docker-compose logs registry

2. HTTPS证书问题

# 检查证书有效性
openssl x509 -in certs/domain.crt -text -noout

# 验证证书链
openssl verify -CAfile certs/ca.crt certs/domain.crt

# 测试HTTPS连接
curl -v https://registry.local:5000/v2/

3. 认证失败

# 检查htpasswd文件
cat auth/htpasswd

# 重新生成密码文件
htpasswd -Bbn admin newpassword > auth/htpasswd

# 重启Registry服务
docker-compose restart registry

4. 存储空间不足

# 查看磁盘使用情况
df -h

# 清理未使用的镜像
docker system prune -a

# 运行Registry垃圾收集
docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

日志分析

Registry日志级别：

  • error：错误信息

  • warn：警告信息

  • info：一般信息

  • debug：调试信息

查看特定类型的日志：

# 查看错误日志
docker-compose logs registry | grep -i error

# 查看访问日志
docker-compose logs registry | grep "GET\|POST\|PUT\|DELETE"

# 实时监控日志
docker-compose logs -f registry

总结

根据不同的使用场景选择合适的方案：

  • 个人开发/小型项目：使用Docker Registry + Docker Compose

  • 中小型企业：推荐使用Harbor

  • 大型企业/商业项目：考虑云服务商的企业级方案

无论选择哪种方案，都要注意安全配置、定期备份和持续监控，确保私有镜像仓库的稳定运行。