一、背景与需求分析

在容器化开发中，镜像管理是核心环节。企业使用公有云镜像仓库（如Docker Hub）存在安全风险、网络依赖和速率限制等问题。私有镜像仓库可实现：

1. 安全控制：通过权限管理限制镜像访问
2. 性能优化：避免跨国网络延迟
3. 合规要求：满足金融、政府等行业的敏感数据存储规范
   Harbor作为VMware开源的企业级Registry解决方案，提供RBAC权限控制、镜像复制、漏洞扫描等高级功能，是构建私有仓库的理想选择。

二、环境准备与依赖安装

2.1 服务器要求

• 操作系统：CentOS 7/8或Ubuntu 20.04+
• 硬件配置：建议4核8G内存以上（生产环境）
• 存储空间：根据镜像存储量规划（建议SSD）

2.2 Docker安装

# CentOS 7示例
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker
# 验证安装
docker --version
docker run hello-world

2.3 Harbor依赖检查

• Docker Compose 1.18+
• Python 3.6+（可选，用于脚本处理）
• OpenSSL（用于生成证书）

三、Harbor安装配置全流程

3.1 下载安装包

wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-online-installer-v2.9.0.tgz
tar xvf harbor-online-installer-v2.9.0.tgz
cd harbor

3.2 配置文件修改

编辑harbor.yml核心配置项：

hostname: reg.example.com  # 需与DNS解析一致
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_open_conns: 1000
  max_idle_conns: 100

3.3 HTTPS证书配置（生产环境必备）

# 生成自签名证书（测试用）
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=reg.example.com/O=MyCompany/C=CN"
# 证书权限设置
chmod 400 /data/cert/server.key
chmod 644 /data/cert/server.crt

3.4 安装执行

# 安装前检查
./prepare
# 执行安装（需root权限）
sudo ./install.sh
# 验证服务状态
docker-compose ps

四、Harbor核心功能配置

4.1 项目管理

1. 登录Web控制台（默认https://reg.example.com）
2. 创建项目：library（公开）、dev-team（私有）
3. 配置项目属性：
   • 镜像自动清理策略
   • 漏洞扫描级别
   • 复制策略（跨区域同步）

4.2 用户与权限管理

-- 示例：通过API创建用户（需管理员权限）
POST /api/v2.0/users
{
  "username": "dev_user",
  "email": "dev@example.com",
  "password": "SecurePass123",
  "realname": "Developer"
}
-- 分配项目角色
PUT /api/v2.0/projects/{project_id}/members/{user_id}
{
  "role_id": 1  # 1=项目管理员, 2=开发者, 3=访客
}

4.3 存储后端配置

支持多种存储驱动：

• 本地存储：/data/registry（默认）
• S3兼容存储：

  storage_service:
  s3:
    accesskey: AKIAIOSFODNN7EXAMPLE
    secretkey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    region: us-west-1
    bucket: harbor-registry
    regionendpoint: https://s3.example.com

五、镜像推送实战操作

5.1 Docker客户端配置

# 登录Harbor
docker login reg.example.com
Username: admin
Password: Harbor12345
# 标记镜像
docker tag nginx:latest reg.example.com/library/nginx:v1
# 推送镜像
docker push reg.example.com/library/nginx:v1

5.2 镜像拉取测试

# 从其他机器拉取（需先登录）
docker pull reg.example.com/library/nginx:v1
# 验证镜像完整性
docker inspect reg.example.com/library/nginx:v1 | grep "RepoDigests"

5.3 自动化构建集成

示例GitLab CI配置：

build_image:
  stage: build
  script:
    - docker build -t reg.example.com/$CI_PROJECT_PATH:$CI_COMMIT_SHA .
    - docker push reg.example.com/$CI_PROJECT_PATH:$CI_COMMIT_SHA
  only:
    - master

六、运维与故障排查

6.1 常见问题处理

1. 502 Bad Gateway：

   • 检查Nginx容器日志：docker logs harbor-nginx
   • 验证后端服务状态：docker-compose ps

2. 证书错误：

   • 更新客户端证书存储：

     sudo cp /data/cert/server.crt /etc/docker/certs.d/reg.example.com/ca.crt
     sudo systemctl restart docker

3. 存储空间不足：

   • 执行GC清理：

     docker exec -it harbor-registry /bin/sh
     registry garbage-collect /etc/registry/config.yml

6.2 性能优化建议

1. 缓存配置：

   # 在harbor.yml中启用
   cache:
     enabled: true
     layer_cache_size: 10GB

2. 并发控制：

   # 调整registry并发数
   registry:
     storage:
       delete:
         enabled: true
       cache:
         blobdescriptor: inmemory
       maintenance:
         uploadpurging:
           enabled: true
           age: 168h
           interval: 24h
           dryrun: false
       redis:
         addr: "harbor-redis:6379"
         db_index: 0
         dial_timeout: 10s
         read_timeout: 30s
         write_timeout: 30s
         pool:
           max_idle: 30
           max_active: 100
           idle_timeout: 300s

七、安全加固最佳实践

1. 网络隔离：

   • 限制Harbor管理端口（80/443）仅允许内网访问
   • 使用VPN或零信任网络架构

2. 审计日志：

   • 启用操作日志：

     # 在harbor.yml中
     audit_logger:
     enabled: true
     destination: file
     path: /var/log/harbor/audit.log

3. 镜像签名验证：

   # 生成GPG密钥
   gpg --full-generate-key
   # 导出公钥
   gpg --export --armor > pubkey.gpg
   # 在Harbor中配置信任密钥

八、进阶功能扩展

1. 与K8s集成：

   # 创建secret
   kubectl create secret docker-registry regcred \
     --docker-server=reg.example.com \
     --docker-username=admin \
     --docker-password=Harbor12345 \
     --docker-email=admin@example.com
   # 在Pod中使用
   imagePullSecrets:
     - name: regcred

2. 多集群镜像同步：

   # 配置复制规则
   replication:
     - name: sync-to-prod
       disabled: false
       projects:
         - name: "library"
       target_projects:
         - name: "library"
           project_id: 2
       triggers:
         - type: "manual"
       dest_registry:
         url: "https://reg-prod.example.com"
         insecure: false
         username: "admin"
         password: "ProdPass123"

通过本指南的系统学习，开发者可掌握从环境搭建到高级运维的全流程技能。实际部署时建议先在测试环境验证配置，再逐步迁移到生产环境。持续关注Harbor官方文档（https://goharbor.io/docs/）获取最新功能更新。