Harbor 2.15.1 离线部署 + 宿主机Nginx反向代理 最终完整版教程

环境说明

• 操作系统：CentOS / Ubuntu
• Harbor 版本：2.15.1
• 部署架构：宿主机Nginx对外终止HTTPS，Harbor内置Nginx仅提供内网HTTP服务
• 优势：彻底解决80/443端口冲突、页面跳转127.0.0.1、SSL握手失败、Nginx语法报错等问题
• 目录规划
  • Harbor安装目录：/data/harbor/install/harbor
  • Harbor数据目录：/data/harbor/data
  • Harbor日志目录：/data/harbor/logs
  • SSL证书目录：/etc/nginx/ssl

---

一、前置准备

1. 安装 Docker 与 Docker Compose

# CentOS 系列
yum install -y docker docker-compose
systemctl start docker
systemctl enable docker

# Ubuntu 系列
apt update && apt install -y docker docker-compose
systemctl start docker
systemctl enable docker

2. 解压 Harbor 离线安装包

将 harbor-offline-installer-v2.15.1.tgz 上传至服务器，执行解压命令：

mkdir -p /data/harbor/install
tar -zxvf harbor-offline-installer-v2.15.1.tgz -C /data/harbor/install/
mv /data/harbor/install/harbor* /data/harbor/install/harbor
cd /data/harbor/install/harbor

3. 部署 SSL 证书

把域名证书（.pem）、私钥（.key）上传到证书目录，配置权限：

mkdir -p /etc/nginx/ssl
# 示例文件：registry.weychan.top.pem、registry.weychan.top.key
chmod 644 /etc/nginx/ssl/*
chown root:root /etc/nginx/ssl/*

---

二、Harbor 核心配置（关闭自带HTTPS）

1. 生成配置文件

cp harbor.yml.tmpl harbor.yml

2. 编辑 harbor.yml

vim harbor.yml

完整配置，必须注释全部HTTPS段落：

# 仓库访问域名
hostname: registry.weychan.top

# 仅启用HTTP，容器内监听80端口
http:
  port: 8080

# 【重要】整段HTTPS配置全部注释，禁止启用
# https:
#   port: 443
#   certificate: /etc/nginx/ssl/registry.weychan.top.pem
#   private_key: /etc/nginx/ssl/registry.weychan.top.key

# 管理员密码，自行修改
harbor_admin_password: Harbor@123456

# 数据存储目录
data_volume: /data/harbor/data

# 日志配置
log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 300M
    location: /data/harbor/logs

保存退出：Esc → :wq

3. 修改 docker-compose.yml 规避端口冲突

Harbor 默认端口映射会占用宿主机80端口，与宿主机Nginx冲突，修改映射端口：

vim docker-compose.yml

找到 proxy 服务下的 ports 字段，修改如下：

proxy:
  image: goharbor/nginx-photon:v2.15.1
  container_name: nginx
  # 此处省略原有配置...
  ports:
    # 原配置：- 80:8080（冲突根源）
    # 修改为：宿主机8080 映射 容器8080，隔离80/443端口
    - 8080:8080

保存退出。

---

三、初始化并启动 Harbor

1. 执行安装脚本

自动生成容器配置并启动服务：

./install.sh

2. 检查容器运行状态

所有容器状态为 healthy 代表启动正常：

docker compose ps

3. 本地连通性测试

验证Harbor HTTP服务可正常访问：

curl -I http://127.0.0.1:8080

正常返回 HTTP/1.1 200 OK。

---

四、宿主机 Nginx 反向代理配置（重点：严格遵守语法规范）

1. 创建站点配置文件

vim /etc/nginx/conf.d/harbor.conf

# 80端口请求强制跳转HTTPS
server {
    listen 80;
    server_name registry.weychan.top;
    return 301 https://$host$request_uri;
}

# 443端口对外提供HTTPS服务
server {
    listen 443 ssl;
    server_name registry.weychan.top;

    # 替换为你服务器真实证书路径与文件名
    ssl_certificate /etc/nginx/ssl/registry.weychan.top.pem;
    ssl_certificate_key /etc/nginx/ssl/registry.weychan.top.key;

    # 解除镜像上传大小限制
    client_max_body_size 0;

    # 全局转发规则，所有代理指令均在此块内（语法合规）
    location / {
        # 转发至Harbor HTTP服务，协议必须为 http，禁止使用 https
        proxy_pass http://127.0.0.1:8080;

        # 透传请求头，解决跳转到127.0.0.1问题
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        # 超时配置，适配大镜像上传
        proxy_connect_timeout 30s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}

2. 校验Nginx配置并生效

# 语法校验，必须输出 test is successful
nginx -t

# 重载配置
systemctl reload nginx

常见Nginx语法报错说明

1. cannot load certificate
   原因：证书路径、文件名错误，或文件权限不足。
   解决：核对路径，执行 chmod 644 /etc/nginx/ssl/* 修复权限。

---

五、防火墙配置（可选）

服务器开启防火墙时，放行80、443端口：

# CentOS firewalld
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload

# Ubuntu ufw
ufw allow 80/tcp
ufw allow 443/tcp
ufw reload

---

六、功能验证

1. 浏览器访问

地址：https://registry.weychan.top
账号：admin，密码为 harbor.yml 中设置的密码，正常登录即部署成功。

2. Docker 客户端登录仓库

docker login registry.weychan.top
# 依次输入用户名、密码，提示 Login Succeeded 即为正常

---

七、日常运维命令

# 进入Harbor安装目录
cd /data/harbor/install/harbor

# 停止Harbor（保留数据卷）
docker compose down

# 彻底停止+清空容器、数据卷（重置配置时使用）
docker compose down -v

# 重启Harbor服务
docker compose restart

# 查看Harbor内置Nginx日志
docker compose logs nginx

# 查看全局日志
tail -f /data/harbor/logs/harbor.log

---

八、常见问题排错汇总

1. 端口冲突：bind: address already in use
   现象：Harbor启动报错，端口被占用
   解决：修改 docker-compose.yml 中 proxy 的端口映射为 8080:8080。

2. 访问自动跳转到 https://127.0.0.1
   原因：Harbor开启了HTTPS、Nginx未透传请求头
   解决：注释 harbor.yml 全部HTTPS配置，补齐 Host、X-Forwarded-Proto 请求头。

3. 502 错误 + SSL_do_handshake() failed
   原因：Nginx 使用 https:// 协议转发到 Harbor 的HTTP端口
   解决：proxy_pass 固定使用 http://127.0.0.1:8080。

4. Nginx 证书加载失败
   解决：核对证书路径、文件名，修复证书文件权限。