Docker镜像仓库Harbor安装部署全流程指南

一、Harbor简介与核心价值

Harbor是由VMware公司开源的企业级Docker镜像仓库，提供基于角色的访问控制（RBAC）、镜像签名、漏洞扫描、审计日志等企业级功能。相较于开源Docker Registry，Harbor通过Web界面、API接口和CLI工具实现更精细化的镜像管理，尤其适合需要合规性要求的企业私有云环境。

核心优势体现在三方面：

1. 安全增强：支持HTTPS加密传输、镜像签名验证和基于OAuth2的认证
2. 管理便捷：提供项目级权限控制、复制策略和垃圾回收机制
3. 扩展性强：支持与LDAP/AD集成、CI/CD工具链对接和分布式部署

二、部署环境准备

硬件配置要求

• 基础版：4核CPU、8GB内存、100GB磁盘（生产环境建议双倍配置）
• 高可用版：需3节点以上集群，每节点配置16核CPU、32GB内存

软件依赖清单

组件	版本要求	安装方式
Docker	19.03+	官方仓库安装
Docker Compose	1.25+	pip安装或二进制包
Python	3.6+	系统包管理器安装
OpenSSL	1.1.1+	系统自带或源码编译

网络拓扑设计

推荐采用三层架构：

1. 前端负载均衡：Nginx或HAProxy实现SSL终止和请求分发
2. 应用服务层：Harbor核心组件（Core、Jobservice、Registry）
3. 数据存储层：独立存储节点部署PostgreSQL和Redis

三、安装部署详细步骤

1. 下载安装包

# 选择稳定版本（以2.5.0为例）
wget https://github.com/goharbor/harbor/releases/download/v2.5.0/harbor-offline-installer-v2.5.0.tgz
tar xvf harbor-offline-installer-v2.5.0.tgz
cd harbor

2. 配置文件修改

编辑harbor.yml核心配置项：

hostname: registry.example.com  # 必须为FQDN
http:
  port: 80
https:
  port: 443
  certificate: /data/cert/server.crt
  private_key: /data/cert/server.key
harbor_admin_password: Harbor12345  # 初始密码
database:
  password: root123
  max_idle_conns: 50
  max_open_conns: 100
storage_driver:
  name: filesystem
  fs_driver:
    rootdirectory: /var/lib/registry

3. 证书配置指南

生成自签名证书（生产环境应使用CA签发证书）：

mkdir -p /data/cert
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /data/cert/server.key \
  -out /data/cert/server.crt \
  -subj "/CN=registry.example.com"

4. 执行安装命令

# 安装前检查依赖
./prepare
# 启动服务（会触发容器拉取和配置初始化）
./install.sh

四、关键组件配置详解

1. 认证系统集成

LDAP集成配置示例：

auth_mode: ldap
ldap:
  url: ldap://ldap.example.com
  search_dn: uid=searchuser,ou=people,dc=example,dc=com
  search_password: searchpass
  base_dn: ou=people,dc=example,dc=com
  uid: uid
  filter: (objectClass=person)
  scope: 2
  timeout: 5

2. 复制策略配置

创建跨区域复制规则：

# 通过API创建复制策略
curl -X POST -u admin:Harbor12345 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-to-dev",
    "projects": [{"project_id": 1}],
    "targets": [{"id": 2}],
    "trigger": {
      "type": "manual"
    },
    "enable_rule": true,
    "replicate_deletion": false
  }' \
  http://registry.example.com/api/v2.0/replication/policies

3. 漏洞扫描配置

启用Clair扫描器：

# 在harbor.yml中启用
clair:
  url: http://clair:6060
  interval: 6h
  threshold:
    critical: 7
    high: 7
    medium: 7
    low: 7
    none: 7

五、运维管理最佳实践

1. 日常维护命令

# 停止服务
docker-compose down
# 升级版本（从2.4.0升级到2.5.0）
./prepare --with-clair --with-trivy
docker-compose pull
docker-compose up -d
# 垃圾回收（每月执行）
docker run -it --name gc --rm --volumes-from registry \
  -e REGISTRY_STORAGE_DELETE_ENABLED=true \
  registry:2.7.1 garbage-collect /etc/registry/config.yml

2. 监控指标收集

Prometheus配置示例：

scrape_configs:
  - job_name: 'harbor'
    metrics_path: '/api/v2.0/metrics'
    static_configs:
      - targets: ['registry.example.com:80']
    basic_auth:
      username: 'prometheus'
      password: 'prompass'

3. 备份恢复方案

完整备份流程：

# 备份配置文件
tar czvf harbor-config-backup-$(date +%Y%m%d).tar.gz \
  /etc/harbor/harbor.yml \
  /data/cert/ \
  /var/lib/registry/
# 数据库备份
docker exec -it harbor-db \
  pg_dump -U postgres -h 127.0.0.1 registry > registry-db-backup.sql

六、常见问题解决方案

1. 登录失败排查

1. 检查/var/log/harbor/core.log日志
2. 验证密码策略配置：

   # 在harbor.yml中
   password_policy:
   min_length: 8
   require_uppercase: true
   require_lowercase: true
   require_number: true
   require_special: true

2. 镜像推送缓慢优化

1. 调整Registry缓存配置：

   registry:
   storage:
    cache:
      blobdescriptor: redis
    redis:
      host: redis:6379
      password: redispass

2. 启用HTTP/2协议（需Nginx 1.13+）

3. 高可用部署架构

推荐采用以下架构：

负载均衡层：F5/Nginx Plus（四层负载均衡）
应用服务层：3节点Harbor集群（使用共享存储）
数据库层：PostgreSQL集群（Patroni+Pgpool）
缓存层：Redis集群（3主3从）
存储层：分布式文件系统（Ceph/GlusterFS）

七、进阶功能应用

1. 与Kubernetes集成

创建镜像拉取Secret：

kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=/root/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson

在Pod定义中引用：

spec:
  containers:
  - name: myapp
    image: registry.example.com/library/nginx:latest
  imagePullSecrets:
  - name: regcred

2. 自动化构建流水线

Jenkinsfile示例片段：

pipeline {
  agent any
  stages {
    stage('Build Image') {
      steps {
        script {
          docker.build("registry.example.com/${env.PROJECT_NAME}/${env.IMAGE_NAME}:${env.BUILD_NUMBER}")
        }
      }
    }
    stage('Push Image') {
      steps {
        script {
          docker.withRegistry('https://registry.example.com', 'harbor-credentials') {
            docker.image("registry.example.com/${env.PROJECT_NAME}/${env.IMAGE_NAME}:${env.BUILD_NUMBER}").push()
          }
        }
      }
    }
  }
}

八、性能调优建议

1. 存储优化参数

# 在harbor.yml中调整
storage:
  redirect:
    disable: false  # 启用重定向减少数据传输
  maintenance:
    upload_purging:
      enabled: true
      age: 168h  # 保留7天未完成上传

2. 并发控制设置

jobservice:
  worker_pool:
    workers: 10  # 根据CPU核心数调整
    backend: "redis"
    redis_pool:
      max_idle: 30
      max_active: 50

3. 网络优化方案

1. 启用TCP BBR拥塞控制算法
2. 调整内核参数：

   # 在/etc/sysctl.conf中添加
   net.core.somaxconn = 65535
   net.ipv4.tcp_max_syn_backlog = 65535
   net.ipv4.tcp_tw_reuse = 1

通过以上详细配置和优化，Harbor可稳定支持每秒1000+的镜像拉取请求，满足中大型企业的生产环境需求。建议每季度进行一次健康检查，包括存储空间分析、证书有效期验证和性能基准测试。