4. 搭建私有Harbor仓库：架构、部署与配置

在Kubernetes生产环境中，镜像拉取速度与仓库可用性直接影响应用交付效率。Harbor作为企业级容器镜像仓库，提供镜像复制、漏洞扫描、RBAC权限控制及审计日志等核心能力。本节从架构设计出发，逐步完成Harbor的安装部署、HTTPS证书配置及多租户管理。

4.1 Harbor架构概览

Harbor采用微服务架构，核心组件包括：

4.2 安装部署：docker-compose 方式

适用于单机测试或小规模团队。Harbor官方提供离线安装包，内置docker-compose编排文件。

4.2.1 下载与配置

# 下载离线安装包（以v2.10.0为例）
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar xzf harbor-offline-installer-v2.10.0.tgz
cd harbor

# 复制配置模板
cp harbor.yml.tmpl harbor.yml

# 编辑核心配置
vi harbor.yml

4.2.2 关键配置项

4.2.3 执行安装

# 执行安装脚本（自动生成docker-compose.yml并启动）
sudo ./install.sh

# 验证所有容器运行状态
docker-compose ps

# 访问 https://harbor.example.com 登录
# 默认管理员：admin / Harbor12345

4.3 安装部署：Helm 方式（Kubernetes原生）

适用于已有Kubernetes集群的团队，利用Helm Chart实现声明式部署与版本管理。

4.3.1 添加Helm仓库与配置

# 添加Harbor Helm仓库
helm repo add harbor https://helm.goharbor.io
helm repo update

# 创建命名空间
kubectl create namespace harbor

# 导出默认配置进行定制
helm show values harbor/harbor > harbor-values.yaml

4.3.2 核心values配置

# harbor-values.yaml 关键片段
expose:
  type: ingress
  tls:
    enabled: true
    secretName: harbor-tls
  ingress:
    hosts:
      core: harbor.example.com
    annotations:
      kubernetes.io/ingress.class: nginx

externalURL: https://harbor.example.com

persistence:
  enabled: true
  persistentVolumeClaim:
    registry:
      size: 200Gi
    database:
      size: 20Gi
    redis:
      size: 5Gi

database:
  type: internal
  internal:
    password: "changeMe123"

redis:
  type: internal

trivy:
  enabled: true

4.3.3 部署与验证

# 部署Harbor
helm install harbor harbor/harbor -f harbor-values.yaml -n harbor

# 查看部署状态
helm status harbor -n harbor
kubectl get pods -n harbor -w

# 获取Ingress地址
kubectl get ingress -n harbor

4.4 HTTPS证书配置

Harbor强制要求HTTPS访问，证书配置是部署成功的关键步骤。以下为自签名证书生成流程（生产环境请使用CA签发证书）。

4.4.1 生成CA与服务器证书

# 1. 创建CA私钥
openssl genrsa -out ca.key 4096

# 2. 生成CA根证书
openssl req -x509 -new -nodes -sha512 -days 3650 \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=DevOps/CN=HarborCA" \
  -key ca.key -out ca.crt

# 3. 创建服务器私钥与证书签名请求
openssl genrsa -out harbor.example.com.key 4096
openssl req -sha512 -new \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=DevOps/CN=harbor.example.com" \
  -key harbor.example.com.key -out harbor.example.com.csr

# 4. 创建x509 v3扩展文件
cat > v3.ext <<-EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1=harbor.example.com
DNS.2=*.harbor.example.com
EOF

# 5. 使用CA签发服务器证书
openssl x509 -req -sha512 -days 3650 \
  -extfile v3.ext \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in harbor.example.com.csr -out harbor.example.com.crt

4.4.2 配置到Harbor

docker-compose方式：将证书与私钥复制到 ./cert/ 目录，在 harbor.yml 中指定路径。

# harbor.yml 证书配置
https:
  port: 443
  certificate: /data/cert/harbor.example.com.crt
  private_key: /data/cert/harbor.example.com.key

Helm方式：创建TLS Secret并配置Ingress。

# 创建TLS Secret
kubectl create secret tls harbor-tls \
  --cert=harbor.example.com.crt \
  --key=harbor.example.com.key \
  -n harbor

# values.yaml 中引用
expose:
  tls:
    secretName: harbor-tls

4.4.3 客户端信任CA

所有需要从该Harbor拉取镜像的节点，必须信任CA根证书：

# 将ca.crt复制到Docker证书目录
sudo mkdir -p /etc/docker/certs.d/harbor.example.com
sudo cp ca.crt /etc/docker/certs.d/harbor.example.com/ca.crt

# 重启Docker守护进程
sudo systemctl restart docker

# 验证登录
docker login harbor.example.com -u admin -p Harbor12345

4.5 项目与用户管理

Harbor通过“项目”实现镜像隔离，通过“用户+角色”实现细粒度权限控制。

4.5.1 项目类型

4.5.2 角色权限矩阵

4.5.3 创建项目与用户（Web UI）

1. 创建项目：登录Harbor → 项目 → 新建项目 → 填写名称、选择公开/私有 → 确认。
2. 创建用户：系统管理 → 用户管理 → 新建用户 → 填写用户名、邮箱、密码 → 确认。
3. 添加成员：进入项目 → 成员 → 添加成员 → 选择用户并分配角色 → 确认。

4.5.4 使用Robot Account（自动化场景）

Robot Account适用于CI/CD流水线，支持细粒度权限与过期时间设置。

# 通过Harbor API创建Robot Account（示例）
curl -X POST "https://harbor.example.com/api/v2.0/robots" \
  -H "Authorization: Bearer ${ADMIN_}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cicd-robot",
    "duration": 2592000,
    "level": "project",
    "permissions": [
      {
        "kind": "project",
        "namespace": "my-app",
        "access": [
          {"resource": "repository", "action": "push"},
          {"resource": "repository", "action": "pull"}
        ]
      }
    ]
  }'

4.6 镜像复制与拉取加速

Harbor的“复制”功能支持跨地域、跨实例的镜像同步，是镜像拉取加速的核心手段。

4.6.1 复制规则配置

# 通过API创建复制规则（示例）
curl -X POST "https://harbor.example.com/api/v2.0/replication/policies" \
  -H "Authorization: Bearer ${ADMIN_}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sync-to-edge",
    "src_registry": {"id": 1},
    "dest_registry": {"id": 2},
    "filters": [
      {"type": "project", "value": "production"},
      {"type": "tag", "value": "v[0-9]+\\.[0-9]+\\.[0-9]+"}
    ],
    "trigger": {"type": "event_based"},
    "deletion": false,
    "override": true
  }'