4. Harbor 安装与部署：环境要求、Docker Compose 部署、Helm Chart 部署、TLS 配置

Harbor 作为企业级容器镜像仓库，支持多种部署方式。本章将系统讲解 Harbor 的安装前置条件、两种主流部署路径（Docker Compose 与 Helm Chart）以及生产环境必须的 TLS 安全配置。无论你选择哪种方式，理解底层组件依赖和配置参数都是保障 Harbor 稳定运行的关键。

4.1 环境要求与前置检查

在开始部署前，请确保目标主机满足以下最低要求。生产环境建议按推荐配置准备。

4.2 Harbor 组件架构概览

Harbor 由多个微服务组件构成，理解其架构有助于后续排障和性能调优。下图展示了核心组件及其交互关系。

4.3 Docker Compose 部署 Harbor

Docker Compose 方式适合单机或小规模测试环境。Harbor 官方提供离线安装包，内置所有组件镜像和配置模板。

4.3.1 下载与解压

# 下载 Harbor 离线安装包（以 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

4.3.2 配置 harbor.yml

复制模板并修改关键参数：

cp harbor.yml.tmpl harbor.yml

# 编辑 harbor.yml，重点关注以下字段：
# hostname: reg.example.com          # 替换为实际域名或 IP
# http.port: 80
# https.port: 443
# https.certificate: /path/to/cert.pem
# https.private_key: /path/to/key.pem
# harbor_admin_password: Harbor12345  # 初始管理员密码
# data_volume: /data/harbor           # 镜像持久化路径

4.3.3 执行安装脚本

# 执行安装（自动拉取镜像并启动所有容器）
sudo ./install.sh

# 安装完成后检查服务状态
docker-compose ps

# 输出示例（部分）：
#       Name                     Command               State                Ports
# ---------------------------------------------------------------------------------------------
# harbor-core         /harbor/entrypoint.sh            Up (healthy)
# harbor-db           /docker-entrypoint.sh            Up (healthy)
# harbor-jobservice   /harbor/entrypoint.sh            Up (healthy)
# harbor-portal       nginx -g daemon off;             Up (healthy)
# harbor-registry     /entrypoint.sh                   Up (healthy)
# nginx               nginx -g daemon off;             Up      0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp
# redis               redis-server /etc/redis.conf     Up (healthy)

4.3.4 验证部署

浏览器访问 https://reg.example.com，使用 admin / Harbor12345 登录。若看到 Harbor 仪表盘，则部署成功。

4.4 Helm Chart 部署 Harbor

在 Kubernetes 集群中，推荐使用 Helm Chart 部署 Harbor，便于版本管理和配置热更新。

4.4.1 添加 Helm 仓库

helm repo add harbor https://helm.goharbor.io
helm repo update

4.4.2 创建 values.yaml 覆盖配置

生产环境建议自定义 values 文件，避免直接修改 Chart 默认值。

cat <<EOF > harbor-values.yaml
expose:
  type: ingress
  tls:
    enabled: true
    certSource: secret
    secret:
      secretName: harbor-tls
  ingress:
    hosts:
      core: reg.example.com
    annotations:
      kubernetes.io/ingress.class: nginx

externalURL: https://reg.example.com

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

harborAdminPassword: "YourStrongPassword"

metrics:
  enabled: true
EOF

4.4.3 部署 Harbor

# 创建命名空间
kubectl create namespace harbor

# 部署 Harbor
helm install harbor harbor/harbor \
  --namespace harbor \
  --values harbor-values.yaml \
  --version 1.14.0

# 查看部署状态
kubectl get pods -n harbor
# 预期输出：所有 pod 处于 Running 或 Completed 状态

4.4.4 访问 Harbor

配置 DNS 或本地 hosts 解析后，通过 Ingress 地址访问。若使用 NodePort 暴露，可执行：

kubectl get svc -n harbor
# 找到 harbor-portal 的 NodePort 端口，通过节点 IP + 端口访问

4.5 TLS 配置详解

TLS 是 Harbor 生产部署的必选项。以下分别介绍自签名证书和 Let's Encrypt 证书的配置方法。

4.5.1 自签名证书（测试环境）

# 生成 CA 私钥和证书
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=DevOps/CN=reg.example.com" \
  -key ca.key -out ca.crt

# 生成服务端私钥和证书请求
openssl genrsa -out reg.example.com.key 4096
openssl req -sha512 -new \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=DevOps/CN=reg.example.com" \
  -key reg.example.com.key -out reg.example.com.csr

# 生成 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=reg.example.com
DNS.2=*.example.com
EOF

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

4.5.2 在 harbor.yml 中配置 TLS

# harbor.yml 中 HTTPS 相关配置
https:
  port: 443
  certificate: /data/cert/reg.example.com.crt
  private_key: /data/cert/reg.example.com.key

4.5.3 在 Helm 中配置 TLS Secret

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

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

4.5.4 配置 Docker 客户端信任自签名 CA

所有需要推送/拉取镜像的节点，必须信任 Harbor 的 CA 证书：

# Linux 节点
sudo cp ca.crt /etc/docker/certs.d/reg.example.com/ca.crt
sudo systemctl restart docker

# macOS 节点
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ca.crt

4.6 部署方式对比总结

选择哪种部署方式取决于你的基础设施现状。如果团队已深度使用 Kubernetes，Helm Chart 是更优选择；若仅需快速验证 Harbor 功能，Docker Compose 足以胜任。无论哪种方式，TLS 配置都是保障镜像传输安全的第一道防线，务必在生产环境严格执行。