Harbor私有镜像仓库高可用搭建指南：零基础实现双节点容灾

为什么生产环境需要高可用 Harbor

单个 Harbor 节点一旦宕机，
整个团队都无法拉取或推送镜像，
直接影响 CI/CD 流水线。Harbor私有镜像仓库高可用 的核心思路是：
让多个 Harbor 实例共享同一套后端存储和数据库，
并用负载均衡器统一入口，
即使其中一台节点故障，
流量会自动切换到健康节点，
业务零中断。

准备三台服务器与共享存储

硬件最低要求：两台运行 Harbor 的应用节点（建议 4 核 8G 以上），一台负责承载外部数据库（PostgreSQL）和缓存（Redis），也可将数据库和 Redis 单独部署。
这里为了演示简洁，把数据库和 Redis 放在第三台机器上。

1. 共享存储：推荐使用 NFS 或云存储（如 MinIO/ S3）。以 NFS 为例，在存储服务器上安装 nfs-kernel-server，导出目录 /data/harbor，并确保所有 Harbor 节点都能挂载。
2. 外部数据库：PostgreSQL 12+，建议单独部署。创建库 harbor_db 和用户 harbor，并授予权限。
3. 外部 Redis：版本 4.0 以上，用于存储 session 和 job 状态。不需要密码时保持为空。

所有节点必须安装 Docker 和 Docker Compose（建议 1.25+）。

配置 harbor.yml 指向外部组件

下载 Harbor 离线安装包（版本选 2.x 以上），解压后编辑 harbor.yml。
关键改动如下：

hostname: your-harbor-domain  # 所有节点使用相同域名，通过负载均衡解析

# 禁用内置数据库
database:
  type: external
  external:
    host: 192.168.1.100        # PostgreSQL 服务器 IP
    port: 5432
    db_name: harbor_db
    username: harbor
    password: strongpassword
    ssl_mode: disable

# 禁用内置 Redis
redis:
  type: external
  external:
    addr: 192.168.1.100:6379   # Redis 地址，无密码留空
    # password: ""

# 数据存储指向共享目录
data_volume: /nfs/harbor       # 所有节点必须挂载同一个 NFS 路径

# 设置 admin 密码
harbor_admin_password: admin123

注意：所有节点上的 harbor.yml 内容必须完全一致，尤其是 hostname、data_volume 和外部组件地址。

启动双节点并接入负载均衡

在两台应用节点上分别执行以下命令（按顺序执行）：

# 1. 挂载共享目录（假设 NFS 服务器 IP 为 192.168.1.200）
mount -t nfs 192.168.1.200:/data/harbor /nfs/harbor

# 2. 生成配置文件
./prepare --conf harbor.yml

# 3. 启动 Harbor（后台运行）
docker-compose up -d

启动后可通过 docker-compose ps 确认所有服务（nginx、core、portal 等）处于 Up 状态。

然后配置负载均衡器。
以 Nginx 为例，将两台 Harbor 节点的 IP（例如 192.168.1.10 和 192.168.1.11）加入 upstream，并设置反向代理到 443 端口（Harbor 默认 HTTPS）：

upstream harbor_backend {
    server 192.168.1.10:443 max_fails=3 fail_timeout=30s;
    server 192.168.1.11:443 max_fails=3 fail_timeout=30s;
}

server {
    listen 443 ssl;
    server_name harbor.example.com;
    ssl_certificate /etc/nginx/ssl/harbor.pem;
    ssl_certificate_key /etc/nginx/ssl/harbor.key;

    location / {
        proxy_pass https://harbor_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

如果使用云负载均衡（如阿里云 SLB），直接在控制台添加两台节点 443 端口的实例健康检查即可。

常见报错与验证方法

问题 1：启动时提示数据库连接失败

• 检查 PostgreSQL 是否允许远程连接（pg_hba.conf 添加 host 行），并确认防火墙放行 5432 端口。

问题 2：镜像推送到一半报错 502

• 多半是共享存储权限问题：NFS 目录拥有者必须为 10000:10000（Harbor 的默认 uid/gid），执行 chown -R 10000:10000 /data/harbor。

问题 3：两台节点 session 不同步，登录后频繁跳转登录页

• 确认所有节点的 harbor.yml 中 Redis 地址完全一致，且 Redis 没有绑定仅本机（注释掉 bind 127.0.0.1）。

验证高可用：
在任一节点执行 docker-compose stop core 模拟 core 服务故障，
然后从负载均衡器 IP 登录 Harbor Web 界面，
应能正常操作，
请求被转发到另一台健康节点。

最后，建议保留至少一个备用节点时刻准备替换。
遇到异常时优先检查数据库连接、存储挂载和防火墙，三项全对 Harbor私有镜像仓库高可用 就算落地成功了。