基于Docker与Docker-Compose的Harbor私有镜像仓库搭建指南

2025年11月1日 互联网

基于Docker与Docker-Compose的Harbor私有镜像仓库搭建指南

一、Harbor私有镜像仓库的核心价值

在容器化部署成为主流的今天，企业对于镜像管理的安全性、可控性和效率提出了更高要求。Harbor作为CNCF（云原生计算基金会）毕业项目，提供了以下核心功能：

  1. 基于角色的访问控制（RBAC）：支持细粒度的权限管理，可按项目、仓库或标签分配权限
  2. 镜像复制与同步：支持多区域镜像分发，构建高可用镜像架构
  3. 漏洞扫描：集成Clair或Trivy进行镜像安全检测
  4. 审计日志：完整记录所有操作行为，满足合规要求
  5. LDAP集成：与企业现有身份认证系统无缝对接

相较于公有云镜像服务，私有Harbor仓库具有数据主权可控、网络延迟低、成本可预测等优势，特别适合金融、医疗等对数据安全要求严格的行业。

二、环境准备与前置条件

2.1 硬件配置建议

组件 最低配置 推荐配置
服务器 2核4G 4核8G+
磁盘空间 40GB（系统盘） 200GB+（数据盘）
网络带宽 10Mbps 100Mbps+

2.2 软件依赖检查

  1. # 检查Docker版本（需19.03+）
  2. docker --version
  4. # 检查Docker-Compose版本（需1.27+）
  5. docker-compose --version
  7. # 启用IPv4转发（关键配置）
  8. echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
  9. sudo sysctl -p

2.3 域名与证书准备

建议使用正式域名（如registry.example.com），并准备以下证书文件：

  • ca.crt：CA根证书
  • registry.example.com.crt：域名证书
  • registry.example.com.key：私钥文件

三、Docker-Compose部署实战

3.1 基础配置文件解析

  1. # docker-compose.yml 核心配置
  2. version: '3.8'
  3. services:
  4.   registry:
  5.     image: goharbor/registry-photon:v2.9.0
  6.     container_name: registry
  7.     restart: always
  8.     volumes:
  9.       - /data/registry:/storage
  10.       - ./common/config/registry:/etc/registry:z
  11.     environment:
  12.       - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/storage
  13.     networks:
  14.       - harbor
  16.   postgresql:
  17.     image: goharbor/harbor-db:v2.9.0
  18.     container_name: harbor-db
  19.     restart: always
  20.     volumes:
  21.       - /data/database:/var/lib/postgresql/data
  22.     environment:
  23.       - POSTGRESQL_DATABASE=registry
  24.       - POSTGRESQL_USER=harbor
  25.       - POSTGRESQL_PASSWORD=Harbor12345
  26.     networks:
  27.       - harbor
  29.   # 其他服务（core、jobservice、portal等）配置省略...

3.2 关键配置优化

  1. 存储卷配置：

    • 建议使用独立数据盘（如/dev/sdb）并格式化为ext4
    • 创建专用目录结构： 
      1. mkdir -p /data/{registry,database,chartmuseum,trivy}
      2. chown -R 10000:10000 /data

  2. 内存限制设置：

    1. # 在每个服务配置中添加资源限制
    2. deploy:
    3.   resources:
    4.     limits:
    5.       cpus: '1.5'
    6.       memory: 2048M
    7.     reservations:
    8.       memory: 1024M

  3. 网络配置优化：

    1. networks:
    2.   harbor:
    3.     driver: bridge
    4.     ipam:
    5.       config:
    6.         - subnet: 172.20.0.0/16
    7.           gateway: 172.20.0.1

四、Harbor高级配置指南

4.1 HTTPS安全配置

  1. 创建证书目录：

    1. mkdir -p /etc/harbor/ssl
    2. chmod 700 /etc/harbor/ssl

  2. 修改harbor.yml配置：

    1. hostname: registry.example.com
    2. https:
    3.   certificate: /etc/harbor/ssl/registry.example.com.crt
    4.   private_key: /etc/harbor/ssl/registry.example.com.key
    5. harbor_admin_password: Harbor12345

  3. 生成配置并启动：

    1. ./prepare
    2. docker-compose up -d

4.2 镜像复制规则配置

  1. 创建复制目标：

    1. curl -X POST -u admin:Harbor12345 \
    2.   -H "Content-Type: application/json" \
    3.   -d '{
    4.     "name": "remote_registry",
    5.     "url": "https://remote-registry.example.com",
    6.     "username": "remote_user",
    7.     "password": "remote_pass"
    8.   }' \
    9.   "http://localhost/api/v2.0/replication/policies"

  2. 设置复制策略：

    • 触发模式：定时/事件触发
    • 复制模式：推送/拉取
    • 过滤器：按项目、标签或仓库过滤

五、运维管理最佳实践

5.1 日常维护命令集

  1. # 服务状态检查
  2. docker-compose ps
  3. docker-compose logs -f registry
  5. # 数据库备份
  6. docker exec -it harbor-db pg_dump -U harbor registry > backup.sql
  8. # 磁盘空间清理
  9. docker run --rm -v /var/lib/registry:/var/lib/registry alpine sh -c \
  10.   "find /var/lib/registry/docker/registry/v2/repositories -type f -name 'link' -delete"

5.2 性能监控方案

  1. Prometheus配置：

    1. # 在docker-compose中添加exporter
    2. exporter:
    3.   image: prom/node-exporter
    4.   ports:
    5.     - "9100:9100"
    6.   networks:
    7.     - harbor

  2. Grafana仪表盘：

    • 导入Harbor专用仪表盘（ID：13639）
    • 关键监控指标：
      • 镜像拉取速率
      • 存储空间使用率
      • 复制任务成功率

六、故障排查与解决方案

6.1 常见问题处理

  1. 502 Bad Gateway错误：

    • 检查Nginx容器日志：docker logs harbor-nginx
    • 验证后端服务状态：curl -v http://harbor-core:8080/api/v2.0/health

  2. 镜像上传失败：

    • 检查存储配额：df -h /data/registry
    • 验证认证信息：docker login registry.example.com

  3. 数据库连接失败：

    • 检查PostgreSQL日志：docker logs harbor-db
    • 验证连接参数：psql -h 127.0.0.1 -U harbor -d registry

6.2 升级与回滚策略

  1. 版本升级流程：

    1. # 备份当前配置
    2. cp harbor.yml harbor.yml.bak
    3. cp docker-compose.yml docker-compose.yml.bak
    5. # 下载新版本安装包
    6. wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-online-installer-v2.10.0.tgz
    8. # 执行升级
    9. ./install.sh --with-trivy --with-chartmuseum

  2. 回滚操作指南：

    • 恢复配置文件
    • 执行docker-compose down
    • 启动旧版本服务

七、企业级部署建议

  1. 高可用架构：

    • 主从数据库配置
    • 共享存储方案（NFS/iSCSI）
    • 负载均衡器配置（HAProxy/Nginx）

  2. 安全加固措施：

    • 定期更新基础镜像
    • 启用双因素认证
    • 实施网络分段策略

  3. 扩展性设计：

    • 水平扩展Worker节点
    • 实施分区域部署
    • 建立镜像生命周期管理策略

通过本文的详细指导，开发者可以快速构建一个安全、高效的Harbor私有镜像仓库。实际部署中，建议先在测试环境验证配置，再逐步推广到生产环境。对于大型企业，可考虑结合Kubernetes Operator实现更灵活的运维管理。

最新文章