1. 环境要求

项目	最低	建议
CPU	2 核	4 核
内存	4 GB	8 GB（Trivy 需 8 GB+）
磁盘	40 GB	100 GB+
Docker	20.10+	24.x
Docker Compose	v2 插件版	最新

2. 下载与解压

# 下载（慢的话浏览器下完 SCP 上传到 /tmp）
wget https://github.com/goharbor/harbor/releases/download/v2.10.3/harbor-offline-installer-v2.10.3.tgz

# 解压
cd /tmp
tar xzf harbor-offline-installer-v2.10.3.tgz
cd harbor

3. 配置（只改一个文件）

3.1 复制模板

cp harbor.yml.tmpl harbor.yml

3.2 编辑 `harbor.yml`

vi harbor.yml

i 进入编辑 → Esc → :wq 保存退出。

必改项：

# 1. 域名（用于 docker login / push，不要加 http://）
hostname: <YOUR_DOMAIN>

# 2. 只开 HTTP，关闭 HTTPS（证书由 Nginx 统一处理）
http:
  port: 8080                   # 仅监听 127.0.0.1，不对外暴露

# https 整段注释掉，避免 443 端口冲突：
# https:
#   port: 443
#   ...

# 3. 管理员密码（必须改！）
harbor_admin_password: <YOUR_ADMIN_PASSWORD>

# 4. 数据目录
data_volume: /opt/harbor/data

# 5. 数据库密码（必须改！）
database:
  password: <YOUR_DB_PASSWORD>

为什么这样配置：Harbor 不直接占用 443，而是跑在 127.0.0.1:8080。Nginx 监听 443 做 SSL 终止，再把流量转发到 Harbor。一套证书管所有服务，没有端口冲突。

4. 启动前准备

4.1 创建数据目录

sudo mkdir -p /opt/harbor/data
sudo chown -R 1000:1000 /opt/harbor/data

5. 执行安装

cd /tmp/harbor
sudo ./install.sh --with-trivy

内存不足 8 GB 则去掉 --with-trivy。

5.1 预期输出

[Step 0]: checking if docker is installed ...
[Step 1]: checking docker compose version ...
[Step 2]: loading Harbor images ...
[Step 3]: preparing environment ...
[Step 4]: starting Harbor ...
✔ ----Harbor has been installed and started successfully.----

5.2 验证

sudo docker compose ps

所有服务状态应为 running (healthy)。

5.3 本地验证

# Harbor 在 127.0.0.1:8080
curl http://127.0.0.1:8080
# 应返回 Harbor HTML

5.4 修正 `EXT_ENDPOINT`（重要！）

./install.sh 内置的 prepare 会根据 harbor.yml 的 hostname 和 http.port 自动生成 EXT_ENDPOINT，但它不知道前面还有 Nginx 反代，生成的地址通常是 http://<YOUR_DOMAIN>:8080 而不是 https://<YOUR_DOMAIN>。

不修的话，docker login 会拿到错误的 token 地址，导致 Client.Timeout exceeded。

检查当前值

cd /tmp/harbor

# 查看两处可能配置的位置
grep -r "EXT_ENDPOINT" common/config/core/env docker-compose.yml 2>/dev/null

修正

# 修正 env 文件中的 EXT_ENDPOINT（prepare 生成的主要位置）
sudo sed -i 's|EXT_ENDPOINT=.*|EXT_ENDPOINT=https://<YOUR_DOMAIN>|' \
  common/config/core/env

# 同时确认 docker-compose.yml 中 core 服务的 environment 也正确
# 如果该行不存在，追加以防 env 文件被覆盖
grep -q "EXT_ENDPOINT" docker-compose.yml || \
  sudo sed -i '/core:/,/ports:/{/environment:/a\      - EXT_ENDPOINT=https://<YOUR_DOMAIN>\n}' docker-compose.yml

以上两条命令中 <YOUR_DOMAIN> 要替换成实际域名，如 ps.hd0530.com。

生效

sudo docker compose down
sudo docker compose up -d

验证修复

# 检查容器运行态（正确值不带端口号）
sudo docker inspect harbor-core --format='{{.Config.Env}}' \
  | tr ',' '\n' | grep EXT_ENDPOINT
# 应输出：EXT_ENDPOINT=https://<YOUR_DOMAIN>

# 测试 token 端点响应的 realm 地址
curl -k -I https://<YOUR_DOMAIN>/v2/
# 应包含：Www-Authenticate: Bearer realm="https://<YOUR_DOMAIN>/service/token"...

realm= 后面必须是 https://...，不能是 http://...:8080。

6. Nginx 反向代理 + HTTPS

Harbor 跑在 127.0.0.1:8080（HTTP），Nginx 在 443 端口做 SSL 终止。

6.1 安装 Nginx

# Ubuntu / Debian
sudo apt install -y nginx

# CentOS / RHEL
sudo yum install -y nginx

6.2 放置证书

# 将证书放到统一目录（根据实际情况调整路径）
sudo mkdir -p /etc/nginx/ssl/<YOUR_DOMAIN>

# 上传证书文件到该目录，确保：
ls /etc/nginx/ssl/<YOUR_DOMAIN>/fullchain.pem
ls /etc/nginx/ssl/<YOUR_DOMAIN>/privkey.pem

6.3 创建 Harbor 反代配置

sudo vi /etc/nginx/conf.d/harbor.conf

写入以下内容：

# HTTP → HTTPS 重定向
server {
    listen 80;
    server_name <YOUR_DOMAIN>;
    return 301 https://$host$request_uri;
}

# HTTPS 反代到 Harbor
server {
    listen 443 ssl;
    http2 on;
    server_name <YOUR_DOMAIN>;

    ssl_certificate     /etc/nginx/ssl/<YOUR_DOMAIN>/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/<YOUR_DOMAIN>/privkey.pem;

    # 现代 SSL 配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 上传大镜像时的必要参数
    client_max_body_size 0;
    proxy_request_buffering off;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 $scheme;

        # WebSocket（Harbor 部分功能需要）
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

6.4 生效

sudo nginx -t                    # 测试配置语法
sudo systemctl reload nginx      # 重载

6.5 验证 HTTPS

curl -k https://<YOUR_DOMAIN>
# 应返回 Harbor HTML

浏览器打开 https://<YOUR_DOMAIN>，应看到 Harbor 登录页面。

7. 功能验证

# 登录
docker login <YOUR_DOMAIN>
# 用户名: admin  密码: 你设的密码

# 推送测试 (先在 Harbor 面板创建项目 "test")
docker pull alpine:latest
docker tag alpine:latest <YOUR_DOMAIN>/test/alpine:v1
docker push <YOUR_DOMAIN>/test/alpine:v1

8. 常见排错

8.1 查看日志

cd /tmp/harbor
docker compose ps                          # 哪些不正常
docker compose logs --tail=50 core         # 核心服务日志
docker compose logs --tail=50 db           # 数据库日志

8.2 错误速查表

日志关键字	原因	修复
`rsyslog` 循环报 `-2103` / `1514: connection refused`	rsyslog 配置缺失，日志驱动不可用	改 `docker-compose.yml`，`driver: syslog` → `driver: json-file`，删 `syslog-address` 行，然后 `docker compose up -d`
`not a directory`	配置文件被 Docker 自动创建为目录	`rm -rf` 那个路径，重跑 `./prepare`
`permission denied`	数据目录权限不对	`chown -R 1000:1000 /opt/harbor/data`
`exit code 137`	OOM 内存不足	去掉 `--with-trivy`，调小内存
`pull access denied`	离线包镜像未载入	`docker load -i harbor.*.tar.gz`

8.3 rsyslog 修复（一步到位）

如果 harbor-log 反复报 -2103 且 harbor-core 连 1514 失败：

cd /tmp/harbor

# 备份
sudo cp docker-compose.yml docker-compose.yml.bak

# 替换日志驱动
sudo sed -i 's/driver: syslog/driver: json-file/' docker-compose.yml
sudo sed -i '/syslog-address:/d' docker-compose.yml
sudo sed -i '/tag:.*harbor/d' docker-compose.yml

# 重启
sudo docker compose up -d

8.4 重新生成配置

cd /tmp/harbor
rm -rf common/
sudo ./prepare --with-trivy
sudo docker compose up -d

9. 日常运维

9.1 启停

cd /tmp/harbor
sudo docker compose stop      # 停止
sudo docker compose start     # 启动
sudo docker compose down      # 停止 + 删除容器

9.2 备份

# 配置备份
sudo tar -czf harbor-backup-$(date +%Y%m%d).tar.gz /tmp/harbor/{harbor.yml,common/}

# 数据库备份
sudo docker exec harbor-db pg_dump -U postgres registry > registry-backup.sql

9.3 升级

cd /tmp/harbor
sudo docker compose down                          # 停旧版本
sudo cp harbor.yml /tmp/harbor.yml.bak            # 备份配置

# 下载新版离线包 → 解压到 /tmp/harbor-v2.xx
# 把旧 harbor.yml 复制过去
cp /tmp/harbor.yml.bak /tmp/harbor-v2.xx/harbor.yml
cd /tmp/harbor-v2.xx
sudo ./install.sh --with-trivy

最后提醒：所有 <YOUR_DOMAIN>、<YOUR_ADMIN_PASSWORD>、<YOUR_DB_PASSWORD> 等占位符务必替换为真实值。安全第一。

Harbor 私有镜像仓库部署手册

1. 环境要求

2. 下载与解压

3. 配置（只改一个文件）

3.1 复制模板

3.2 编辑 `harbor.yml`

4. 启动前准备

4.1 创建数据目录

5. 执行安装

5.1 预期输出

5.2 验证

5.3 本地验证

5.4 修正 `EXT_ENDPOINT`（重要！）

检查当前值

修正

生效

验证修复

6. Nginx 反向代理 + HTTPS

6.1 安装 Nginx

6.2 放置证书

6.3 创建 Harbor 反代配置

6.4 生效

6.5 验证 HTTPS

7. 功能验证

8. 常见排错

8.1 查看日志

8.2 错误速查表

8.3 rsyslog 修复（一步到位）

8.4 重新生成配置

9. 日常运维

9.1 启停

9.2 备份

9.3 升级

评论区

Harbor 私有镜像仓库部署手册

1. 环境要求

2. 下载与解压

3. 配置（只改一个文件）

3.1 复制模板

3.2 编辑 harbor.yml

4. 启动前准备

4.1 创建数据目录

5. 执行安装

5.1 预期输出

5.2 验证

5.3 本地验证

5.4 修正 EXT_ENDPOINT（重要！）

检查当前值

修正

生效

验证修复

6. Nginx 反向代理 + HTTPS

6.1 安装 Nginx

6.2 放置证书

6.3 创建 Harbor 反代配置

6.4 生效

6.5 验证 HTTPS

7. 功能验证

8. 常见排错

8.1 查看日志

8.2 错误速查表

8.3 rsyslog 修复（一步到位）

8.4 重新生成配置

9. 日常运维

9.1 启停

9.2 备份

9.3 升级

评论区

Harbor 私有镜像仓库部署手册

3.2 编辑 `harbor.yml`

5.4 修正 `EXT_ENDPOINT`（重要！）