[infra] Container Registry：Harbor 私有映像庫

cover

架構概覽

flowchart LR
    CI[CI Pipeline<br/>docker build] -->|docker push| Registry[Harbor Registry<br/>harbor.example.com]
    Registry -->|自動掃描| Scan[Trivy 漏洞掃描]
    Scan -->|通過| OK[允許 Pull]
    Scan -->|Critical CVE| Block[禁止 Pull]
    OK -->|docker pull| DevHost[Dev 環境部署]
    OK -->|docker pull| ProdHost[Prod 環境部署]
    Admin[Admin] -->|管理策略| Retention[Retention Policy<br/>自動清理舊映像檔]

Container Registry：映像檔的集中管理站

當團隊有多個服務、多個環境時，Docker 映像檔需要一個集中的存放位置。Harbor 是開源的私有 Container Registry，除了基本的 push/pull 功能，還提供映像檔安全掃描、存取控制、映像簽章、以及自動清理策略。比起直接用 Docker Hub 或 GitLab Registry，Harbor 在企業級功能和控制力上更完整。

架構概覽

flowchart LR
  CI[CI Pipeline] -->|docker push| Harbor[Harbor Registry\nharbor.example.com]
  Harbor -->|vulnerability scan| Trivy[Trivy Scanner]
  Harbor -->|docker pull| DevHost[Dev Host]
  Harbor -->|docker pull| ProdHost[Prod Host]

  Admin[Admin] -->|manage| HarborUI[Harbor Web UI]
  HarborUI --> Projects[Projects / RBAC]
  HarborUI --> Policies[Retention / Replication]

CD pipeline build 完映像檔後 push 到 Harbor，Harbor 自動觸發安全掃描（Trivy）。各環境的 Docker Host 從 Harbor pull 映像檔部署。Admin 透過 Harbor Web UI 管理專案、權限和清理策略。

核心概念

Project 隔離：Harbor 用 Project 來分組映像檔，例如 ec/ 放電商相關服務、infra/ 放基礎建設服務。每個 Project 有獨立的存取控制，可以設定誰能 push、誰只能 pull。這比把所有映像檔丟在一個 namespace 下清楚很多，也方便按團隊或產品線分權管理。
安全掃描：Harbor 整合了 Trivy 掃描器，每次 push 新映像檔時自動掃描已知漏洞（CVE）。可以設定策略：Critical 或 High 漏洞的映像檔禁止 pull，強制開發者修復後才能部署。這是在 CI 之外多加一層安全閘門。
映像檔保留策略（Retention Policy）：如果不清理，Registry 的儲存空間會無限增長。Harbor 支援保留策略，例如「每個 tag 只保留最近 10 個版本」或「超過 30 天的 untagged manifest 自動刪除」。這在 CI 頻繁 build 的環境特別重要。
Robot Account：CI pipeline 需要推送映像檔到 Harbor，但不應該用個人帳號（離職後就失效）。Harbor 的 Robot Account 是專門給自動化流程用的服務帳號，可以限制只有 push 權限、只能操作特定 Project，而且有獨立的 token 過期機制。

使用情境

CI/CD 整合：GitLab CI 的 build stage 完成後，用 Robot Account 把映像檔推到 Harbor。Harbor 自動掃描，如果有 Critical CVE，deploy stage 會因為 pull 被拒絕而失敗，強制開發者回去修依賴。
多環境 Pull：Dev 環境可以 pull 任何版本的映像檔（包含 develop 和 feature-* tag）；Prod 環境只能 pull v* tag 的映像檔。透過 Harbor 的 Immutable Tag 規則，確保 prod 的映像檔不會被覆蓋。
儲存空間管理：每天 CI 跑 50 次 build，每個映像檔 200MB，一個月就 300GB。設定 Retention Policy 只保留每個 tag 最近 5 個版本，自動清理舊的映像檔。

實作範例 / 設定範例

Harbor 部署（docker-compose）

# 下載 Harbor installer
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar xvf harbor-offline-installer-v2.10.0.tgz
cd harbor
 
# 修改設定
cp harbor.yml.tmpl harbor.yml

# harbor.yml 關鍵設定
hostname: harbor.example.com
https:
  port: 443
  certificate: /etc/harbor/certs/fullchain.pem
  private_key: /etc/harbor/certs/privkey.pem
 
harbor_admin_password: ChangeMeToStrongPassword
 
database:
  password: ChangeMeToStrongPassword
  max_idle_conns: 50
  max_open_conns: 1000
 
data_volume: /data/harbor
 
trivy:
  ignore_unfixed: false
  security_check: vuln
  severity: CRITICAL,HIGH,MEDIUM
 
log:
  level: info
  rotate_count: 50
  rotate_size: 200M

# 安裝並啟動
./install.sh --with-trivy
docker compose ps  # 確認所有服務正常

CI Pipeline 推送映像檔

# .gitlab-ci.yml - Harbor push
build:
  stage: build
  variables:
    HARBOR_HOST: harbor.example.com
    HARBOR_PROJECT: ec
  before_script:
    - docker login -u $HARBOR_ROBOT_USER -p $HARBOR_ROBOT_TOKEN $HARBOR_HOST
  script:
    - docker build -t ${HARBOR_HOST}/${HARBOR_PROJECT}/api:${CI_COMMIT_SHA} .
    - docker push ${HARBOR_HOST}/${HARBOR_PROJECT}/api:${CI_COMMIT_SHA}
    # 如果是 tag，也推一份帶版本號的
    - |
      if [ -n "$CI_COMMIT_TAG" ]; then
        docker tag ${HARBOR_HOST}/${HARBOR_PROJECT}/api:${CI_COMMIT_SHA} \
                   ${HARBOR_HOST}/${HARBOR_PROJECT}/api:${CI_COMMIT_TAG}
        docker push ${HARBOR_HOST}/${HARBOR_PROJECT}/api:${CI_COMMIT_TAG}
      fi

常見問題與風險

儲存空間爆滿：Harbor 的 data volume 滿了會導致所有 push 失敗，連帶影響 CI pipeline。避免方式：設定 Retention Policy 自動清理；監控磁碟使用率，80% 時告警。
映像檔被覆蓋：同一個 tag（例如 latest）被不同 commit 覆蓋，導致正在運行的版本和 Registry 裡的版本不一致。避免方式：用 commit SHA 作為 tag，設定 Immutable Tag 規則讓 v* tag 不可覆蓋。
安全掃描誤報：某些 CVE 在你的使用場景下不會被觸發，但掃描器不知道。如果每次都因為誤報卡住部署，團隊會開始忽略所有掃描結果。避免方式：建立 CVE 白名單機制，經過安全 review 的誤報可以豁免。
Harbor 本身掛掉：Harbor 一掛，所有環境都拉不到映像檔。已經在跑的服務不受影響（因為映像檔已經在本地），但新部署和更新會失敗。避免方式：定期備份 Harbor 資料庫和映像檔儲存；考慮 Harbor 的 Replication 功能做異地備份。

優點

完整的存取控制和稽核紀錄
安全掃描整合，在部署前攔截漏洞
Retention Policy 自動管理儲存空間

缺點 / 限制

Harbor 本身需要資源（建議至少 4GB RAM、50GB disk）
初始設定和維護有一定複雜度
需要自己管理 TLS 憑證和 HTTPS

Terry Yao's Blog

分類

目錄