Docker 搭建本地Harbor私有鏡像倉庫

一、Harbor 核心價值與企業級特性解析

在容器化技術普及的背景下，鏡像倉庫作為容器生命周期的核心組件，其可靠性直接影響開發效率與生產穩定性。Docker 官方的 Registry 雖能實現基礎鏡像存儲，但存在明顯短板：無可視化界面、缺乏權限管控、無安全掃描等企業級功能，無法滿足企業對鏡像管理的精細化需求。

從企業實際需求出發，私有鏡像倉庫的部署具有不可替代的價值：

• 安全隔離：企業核心業務鏡像無需暴露在公共倉庫，降低源碼泄露與惡意篡改風險；
• 效率提升：內部網絡環境下鏡像傳輸速度遠高于公共倉庫，減少部署等待時間；
• 合規可控：支持操作審計、權限細化管理，滿足金融、政務等行業的監管要求。

Harbor 作為 VMware 推出的開源企業級鏡像倉庫，針對性解決了這些問題，其核心企業級特性包括：

• 權限管理體系：基于 RBAC（角色基礎訪問控制）實現多用戶、多項目的權限隔離，支持 LDAP 集成實現統一身份認證；
• 安全防護能力：集成 Clair、Trivy 等漏洞掃描工具，可自動檢測鏡像中的安全風險，同時支持鏡像簽名與驗真，確保鏡像完整性；
• 可視化與易用性：提供直觀的 Web 管理界面，支持中文顯示，降低運維門檻；
• 高可用支撐：內置鏡像復制功能，為跨節點數據同步提供基礎，支持多節點部署；
• 本地化適配：針對國內用戶設計鏡像跨倉庫復制功能，滿足多地域鏡像同步需求。

二、高可用方案選型與架構設計

2.1 高可用方案核心目標

容器鏡像倉庫的高可用本質是減少服務中斷時間，確保開發人員能穩定推送鏡像、業務集群能正常拉取鏡像。對于中小型企業，通常可接受 “分鐘級” 故障恢復（即故障發生后，通過手動操作在幾分鐘內恢復服務），無需追求金融級 “秒級” 高可用（需復雜集群架構支撐）。

2.2 方案選型：雙主復制 + Nginx 代理

本次采用 “雙主復制 + Nginx 代理” 的高可用方案，架構示意圖如下：

外部訪問 → Nginx代理節點 → Harbor A節點/Harbor B節點（雙向復制）

該方案的核心邏輯是：通過兩個 Harbor 節點的雙向復制實現數據冗余，通過 Nginx 代理提供統一訪問入口，節點故障時手動切換 Nginx 代理目標。

方案選型理由：

• 架構簡單易維護：無需復雜的集群編排工具，中小型企業運維人員可快速上手；
• 適配云環境限制：云服務商通常不支持自定義外網虛擬 IP（keepalived 依賴虛擬 IP 實現自動切換），而手動切換 Nginx 配置可規避此問題；
• 平衡成本與可用性：雙節點部署成本低，且 “分鐘級恢復” 可滿足內部開發場景的可用性需求。

不選擇 keepalived 的原因：

• 云環境限制：主流云廠商（如阿里云、騰訊云）不允許自定義外網可訪問的虛擬 IP，keepalived 的 “虛擬 IP 漂移” 功能無法生效；
• 操作復雜度：內網環境雖可使用 keepalived，但需額外配置 VRRP 協議、健康檢查腳本，增加運維成本。

三、環境準備與前置依賴配置

3.1 服務器硬件與系統配置

本次部署使用 3 臺 CentOS-7.9 虛擬機，具體配置如下表所示，各節點角色與資源要求均經過實踐驗證：

系統版本	IP 地址	節點角色	CPU 要求	內存要求	Hostname	核心作用
CentOS-7.9	192.168.10.101	Nginx 代理節點	≥2 核	≥2G	Nginx	提供統一訪問入口，轉發請求到 Harbor 節點
CentOS-7.9	192.168.10.102	Harbor1 節點	≥2 核	≥2G	Docker01	主鏡像倉庫節點，存儲與管理鏡像
CentOS-7.9	192.168.10.103	Harbor2 節點	≥2 核	≥2G	Docker02	備用鏡像倉庫節點，與 Harbor1 雙向同步數據

資源要求說明：

• CPU≥2 核：Harbor 運行時需啟動多個核心組件（API 服務、數據庫、緩存、日志等），單核 CPU 會導致組件競爭資源，出現響應緩慢問題；
• 內存≥2G：Docker 容器、Harbor 核心服務（如 API Server、Registry）均需占用內存，內存不足會導致服務頻繁崩潰。

3.2 前置依賴安裝：Docker

所有節點必須提前安裝 Docker，因為 Harbor 的所有組件均以 Docker 容器形式運行。安裝步驟參考 Docker 官方文檔（https://docs.docker.com/engine/install/centos/），核心驗證命令：

# 檢查Docker是否安裝成功
docker --version  
# 確保Docker服務正常運行
systemctl status docker  

四、Harbor 節點部署全流程（以 Harbor1 為例）

4.1 下載與解壓 Harbor 安裝包

Harbor 提供離線安裝包（包含所有依賴鏡像），適合內網環境部署。本次選擇 v2.4.3 版本，下載地址：
https://github.com/goharbor/harbor/releases/tag/v2.4.3，具體步驟：

# 上傳離線安裝包到服務器
[root@localhost ~]# ls  
harbor-offline-installer-v2.4.3.tgz  # 解壓安裝包
[root@localhost ~]# tar -zxvf harbor-offline-installer-v2.4.3.tgz  
[root@localhost ~]# cd harbor  
[root@localhost harbor]# ls  
common.sh  harbor.v2.4.3.tar.gz  harbor.yml.tmpl  install.sh  LICENSE  prepare  

4.2 核心配置文件修改（harbor.yml）

Harbor 的配置依賴harbor.yml文件，需從模板拷貝并修改關鍵參數：

# 拷貝配置模板
[root@localhost harbor]# cp harbor.yml.tmpl harbor.yml  # 編輯配置文件
[root@localhost harbor]# vim harbor.yml  

關鍵配置項說明：

# 節點唯一標識（必須為當前節點IP，用于鏡像訪問與復制）
hostname: 192.168.10.102  # 管理員初始密碼（生產環境需設置強密碼，如包含大小寫、數字、特殊字符）
harbor_admin_password: pwd123  # 臨時關閉HTTPS（后續由Nginx統一處理，生產環境需啟用HTTPS）
#https:# https port for harbor, default is 443
#  port: 443# The path of cert and key files for nginx
#  certificate: /your/certificate/path
#  private_key: /your/private/key/path

配置注意事項：

• hostname必須正確配置為節點 IP 或域名，否則鏡像 tag 會包含錯誤地址，導致拉取失敗；
• HTTPS 配置暫時注釋的原因：簡化初期部署，后續可通過 Nginx 統一配置 HTTPS，避免每個 Harbor 節點單獨配置證書的麻煩。

4.3 安裝 docker-compose 依賴

Harbor 由多個關聯容器（如 API 服務、數據庫、Registry、日志服務等）組成，需通過docker-compose實現容器編排與生命周期管理。安裝步驟：

# 下載docker-compose二進制文件
[root@localhost ~]# curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose  # 賦予執行權限
[root@localhost ~]# chmod 755 /usr/local/bin/docker-compose  # 驗證安裝
[root@localhost ~]# docker-compose --version  
docker-compose version 1.26.2, build eefe0d31  

4.4 啟動 Harbor 服務

通過官方安裝腳本啟動 Harbor，腳本會自動完成鏡像加載、配置生成、容器啟動等流程：

[root@localhost harbor]# ./install.sh  

啟動流程解析：

1. 環境檢查：驗證 Docker 與 docker-compose 是否安裝成功；
2. 鏡像加載：將離線包中的harbor.v2.4.3.tar.gz鏡像導入本地 Docker；
3. 配置生成：根據harbor.yml生成各組件（Nginx、Core、DB 等）的配置文件；
4. 容器啟動：通過docker-compose創建并啟動所有服務容器。

啟動成功驗證：

? ----Harbor has been installed and started successfully.----  

此時通過瀏覽器訪問http://192.168.10.102，可看到 Harbor 登錄界面，使用默認用戶名admin和配置的密碼pwd123即可登錄。

五、Nginx 代理節點部署與配置

Nginx 節點的核心作用是提供統一訪問入口，并在 Harbor 節點故障時通過修改配置實現手動切換。

5.1 拉取 Nginx 鏡像與創建配置文件

# 拉取指定版本的Nginx鏡像（版本穩定性經過生產驗證）
[root@m1 ~]# docker pull nginx:1.13.12  # 創建配置文件目錄并編寫配置
[root@m1 ~]# mkdir nginx  
[root@m1 ~]# cd nginx  
[root@m1 nginx]# vim nginx.conf  

5.2 Nginx 核心配置解析

user nginx;
worker_processes 1;  # 單進程足夠支撐中小型企業內部訪問需求error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;events {worker_connections 1024;  # 最大并發連接數，可根據實際訪問量調整
}# 使用stream模塊實現四層TCP代理（適配Docker鏡像的TCP協議傳輸）
stream {# 定義上游服務組（初始代理到Harbor1節點）upstream hub{server 192.168.10.102:80;  }# 代理服務配置server {listen 80;  # 監聽80端口，與Harbor節點端口保持一致proxy_pass hub;  # 轉發請求到上游服務組proxy_timeout 300s;  # 長連接超時時間（適配大鏡像傳輸）proxy_connect_timeout 5s;  # 連接超時時間}
}

配置關鍵點說明：

• 使用 stream 模塊：Docker 鏡像拉取 /push 基于 TCP 協議，需用 stream 模塊而非 http 模塊；
• 僅代理單節點的原因：Harbor 節點間鏡像同步存在延遲（尤其是大型鏡像），若代理兩個節點會出現 “推送至 A 節點后，Nginx 轉發請求到 B 節點導致拉取失敗” 的問題；
• 手動切換邏輯：當192.168.10.102故障時，修改upstream hub為server 192.168.10.103:80;，重啟 Nginx 即可切換到備用節點。

5.3 啟動 Nginx 容器

通過腳本快速啟動 Nginx 容器，確保配置文件正確掛載：

# 創建啟動腳本
[root@m1 nginx]# vim restart.sh  
#!/bin/bash
# 停止并刪除舊容器（若存在）
docker stop harbor-nginx  
docker rm harbor-nginx  # 啟動新容器：使用宿主機網絡，掛載本地配置文件
docker run -itd --net=host --name harbor-nginx -v /root/nginx/nginx.conf:/etc/nginx/nginx.conf nginx:1.13.12  # 執行腳本啟動Nginx
[root@m1 ~/nginx]# sh restart.sh  

啟動參數說明：

• --net=host：讓 Nginx 直接使用宿主機網絡，避免端口映射導致的協議適配問題；
• -v /root/nginx/nginx.conf:/etc/nginx/nginx.conf：將本地配置文件掛載到容器內，修改配置后無需重建鏡像，重啟容器即可生效。

六、Harbor 節點雙向復制配置（核心高可用保障）

雙向復制是實現數據冗余的關鍵，確保任一節點的鏡像變更能同步到另一節點，避免單節點故障導致數據丟失。

6.1 配置 Harbor1 到 Harbor2 的復制規則

步驟 1：添加目標倉庫（Harbor2 節點）

登錄 Harbor1 的 Web 界面（http://192.168.10.102），進入 “倉庫管理”→“新建目標”，配置如下：

• 提供者：選擇 “Harbor”（目標為另一 Harbor 節點）；
• 目標名：192.168.10.103（清晰標識目標節點 IP）；
• 目標 URL：http://192.168.10.103（Harbor2 節點的訪問地址）；
• 訪問 ID：admin（Harbor2 的管理員用戶名）；
• 訪問密碼：pwd123（Harbor2 的管理員密碼）；
• 點擊 “測試連接”，提示 “連接成功” 后保存。

步驟 2：創建復制規則

進入 “復制管理”→“新建規則”，配置如下：

• 名稱：to192.168.10.103（標識復制方向）；
• 復制模式：Push-based（本地鏡像新增 / 刪除時主動推送到目標）；
• 源資源過濾器：默認復制全部鏡像（可按名稱、Tag 過濾，如僅復制prod-*標簽鏡像）；
• 目標倉庫：選擇步驟 1 創建的目標（192.168.10.103）；
• 目標名稱空間：選擇 “替換 1 級”（保持與源倉庫一致的項目結構）；
• 觸發模式：事件驅動（鏡像推送 / 刪除時自動觸發復制）；
• 點擊 “保存” 完成配置。

6.2 配置 Harbor2 到 Harbor1 的復制規則

重復 6.1 的步驟，在 Harbor2 節點（http://192.168.10.103）中添加目標倉庫（Harbor1 節點http://192.168.10.102），并創建復制規則to192.168.10.102，實現 “雙向復制”。

6.3 復制規則核心參數說明

• 復制模式：Push-based（主動推送）適合鏡像源節點，確保本地變更及時同步；若需從目標節點拉取鏡像，可選擇Pull-based（被動拉取）；
• 觸發模式：事件驅動可實時同步，適合頻繁更新場景；若鏡像更新頻率低，也可選擇 “定時觸發”（如每天凌晨同步）；
• 資源過濾器：通過名稱、Tag 過濾可減少無效同步（如僅同步生產環境鏡像，忽略測試鏡像）。

6.4 復制效果驗證

步驟 1：在 Harbor1 創建項目并推送鏡像

• 登錄 Harbor1，進入 “項目”→“新建項目”，名稱為kubernetes（公開項目）；

• 在客戶端配置 Docker 信任私有倉庫（需在所有訪問 Harbor 的 Docker 主機上操作）：

  [root@localhost ~]# vim /etc/docker/daemon.json  
  {"insecure-registries": ["192.168.10.101"]  # Nginx代理節點IP
  }  
  [root@localhost ~]# systemctl daemon-reload  
  [root@localhost ~]# systemctl restart docker  
  

• 登錄倉庫并推送鏡像：

  [root@localhost ~]# docker login 192.168.10.101  # 登錄Nginx代理地址
  Username: admin  
  Password: pwd123  
  Login Succeeded  # 標記并推送鏡像
  [root@localhost ~]# docker pull cirros  
  [root@localhost ~]# docker tag cirros 192.168.10.101/kubernetes/cirros:v1  
  [root@localhost ~]# docker push 192.168.10.101/kubernetes/cirros:v1  
  

步驟 2：檢查 Harbor2 的同步結果

登錄 Harbor2 的 Web 界面（http://192.168.10.103），進入 “項目”，可看到自動同步的kubernetes項目及項目下的cirros:v1鏡像，表明復制成功。

七、全流程功能驗證與故障切換演練

7.1 基礎功能驗證

• 登錄驗證：通過 Nginx 代理地址（http://192.168.10.101）登錄 Harbor，確認可正常訪問；
• 推送驗證：客戶端推送鏡像到192.168.10.101/kubernetes，確認 Harbor1 節點可接收；
• 拉取驗證：另一客戶端從192.168.10.101/kubernetes拉取鏡像，確認成功下載；
• 復制驗證：檢查 Harbor2 節點是否同步到推送的鏡像。

7.2 故障切換演練（模擬 Harbor1 節點故障）

• 步驟 1

  ：手動停止 Harbor1 節點的服務（模擬故障）：

  [root@localhost harbor]# docker-compose down  
  

• 步驟 2

  ：修改 Nginx 配置，切換代理目標到 Harbor2：

  [root@m1 nginx]# vim nginx.conf  
  stream {upstream hub{server 192.168.10.103:80;  # 改為Harbor2節點IP}# 其他配置不變
  }  
  

• 步驟 3

  ：重啟 Nginx 生效配置：

  [root@m1 ~/nginx]# sh restart.sh  
  

• 步驟 4：驗證切換效果：客戶端從192.168.10.101拉取kubernetes/cirros:v1鏡像，確認可正常拉取（數據來自 Harbor2 節點）。

八、方案總結與生產環境優化建議

8.1 方案優勢與適用場景

• 優勢：架構簡單、部署成本低、數據冗余可靠，適合中小型企業內部鏡像管理；
• 適用場景：內部開發 / 測試環境、非核心生產環境，可接受分鐘級故障恢復的場景。

8.2 生產環境優化建議

• 啟用 HTTPS：在 Nginx 層配置 SSL 證書，將stream模塊改為http模塊并啟用 HTTPS，避免鏡像傳輸過程中被竊聽；
• 增加監控告警：通過 Prometheus 監控 Harbor 節點狀態與磁盤使用率，配置告警避免磁盤滿導致服務異常；
• 定期備份：定期備份 Harbor 的數據庫與鏡像存儲目錄，防止復制失效導致的數據丟失；
• 權限細化：通過 “用戶管理” 與 “項目成員” 配置，實現開發、測試、運維人員的權限隔離，避免誤操作；
• 鏡像清理策略：配置定時 GC（垃圾回收）任務，刪除過期鏡像釋放存儲空間。