前置条件#

• Docker Engine ≥ 20.10（Harbor 2.x 要求）
• Docker Compose（Harbor 安装脚本会自动识别 docker compose 插件或老版 docker-compose 二进制）
• 内存 ≥ 4 GB（官方建议，低于 4 GB 部分组件会启动失败）
• 磁盘 ≥ 40 GB（Harbor 自身约 1 GB，其余留给镜像仓库存储）
• 端口 80 / 443（或你自定义的端口）未被其他服务占用
• root 或 sudo 权限

下载安装包#

Harbor Releases：Harbor - Github

建议选择 offline 离线包，安装时自动解压内置的 Docker 镜像，无需在线拉取。

生成自签名 SSL 证书#

1
sudo apt update && sudo apt install -y openssl
2
vim harbor_cert.cnf

1
[req]
2
distinguished_name = req_distinguished_name
3
x509_extensions = v3_req
4
prompt = no
5

6
[req_distinguished_name]
7
C = CN                     # 国家代号
8
ST = Beijing               # 省份
9
L = Beijing                # 城市
10
O = MyOrg                  # 组织
11
OU = DevOps                # 部门
12
CN = harbor.local          # ← 替换为你的 Harbor 域名或 IP
13

14
[v3_req]
15
keyUsage = keyEncipherment, dataEncipherment, digitalSignature
16
extendedKeyUsage = serverAuth
17
subjectAltName = @alt_names
18

19
[alt_names]
20
DNS.1 = harbor.local         # 主域名
21
DNS.2 = *.local              # 可选：泛域名
22
IP.1 = 192.168.2.11          # ← 裸 IP 访问场景必须加，否则 Docker 推镜像会报 "no IP SANs"

1
# 生成私钥 + 自签名证书（有效期 10 年）
2
openssl req -x509 \
3
  -newkey rsa:4096 \
4
  -sha256 \
5
  -days 3650 \
6
  -nodes \
7
  -keyout harbor.key \
8
  -out harbor.crt \
9
  -config harbor_cert.cnf \
10
  -extensions v3_req
11

12
# 把证书放到后续 Harbor 和 Nginx 都方便引用的位置
13
sudo mkdir -p /opt/harbor/crt
14
sudo cp harbor.crt harbor.key /opt/harbor/crt/
15

16
# Docker 客户端信任证书
17
# 注意：目录名必须和 docker login 时用的域名完全一致
18
sudo mkdir -p /etc/docker/certs.d/harbor.local/
19
sudo cp harbor.crt /etc/docker/certs.d/harbor.local/ca.crt

配置 harbor.yml#

1
cp harbor.yml.tmpl harbor.yml
2
vim harbor.yml

关键配置项：

务必修改默认密码 Harbor12345

Harbor12345 是 Harbor 官方文档里的公开默认密码——任何扫描器都会第一时间尝试它。部署完成后第一件事就是改掉：

• 首次部署前：直接在 harbor.yml 里把 harbor_admin_password 改成强密码，再 ./install.sh
• 已经部署完成：Web UI 登录后进 用户管理 → admin → 修改密码

不改就部署、尤其是公网可达的 Harbor，基本等于当场被接管。

推荐在第一次 install.sh 之前就调整好的配置

首次 ./install.sh 之后改部分配置需要重新 ./prepare + 重建容器，一次到位更省事。首次安装前至少检查以下几项：

• hostname：改成 harbor.local（或你的实际域名），要和证书 CN 一致
• harbor_admin_password：改成强密码（见上方 caution）
• data_volume：默认 /data，如果根分区小必须挪到大容量盘挂载点（如 /mnt/storage/harbor）
• https.certificate / https.private_key：指向 /opt/harbor/crt/harbor.crt 和 /opt/harbor/crt/harbor.key
• http.port / https.port：如果宿主机 80/443 被系统 Nginx / Apache 占用，改成 31080 / 31443（或任意非占用端口），再配合下文 Nginx 反向代理做对外映射
• external_url：用非标端口 / Nginx 反代时必配，否则登录认证会走错端口（详见下方 note）

external_url 详解

external_url 是 Harbor 配置文件中的参数，用于定义外部客户端访问该服务的基准 URL。其技术逻辑如下：

优先级：启用该参数后，配置中的 hostname 将失效。

令牌生成：Harbor 的认证服务（Token Service）会根据此参数生成 OAuth 令牌挑战（Challenge）中的 realm 地址。

重定向逻辑：决定 Harbor 在返回 HTTP 重定向或 API 响应时，所携带的协议、域名及端口号。

端口同步：在通过 Nginx 映射非标准端口（如 31001）时，该参数确保后端返回的认证地址与外部监听端口一致，防止客户端因默认访问 443 端口导致连接超时。

配置生效：修改此参数后，必须执行 ./prepare 脚本，以重新生成各个微服务组件内部的配置文件。

安装#

1
./install.sh

修改配置后重新加载：

1
./prepare
2
docker compose down
3
docker compose up -d

1
# 1. 查看所有 Harbor 容器状态（正常应该全部 Up 且 healthy）
2
docker compose ps
3

4
# 2. 检查端口监听
5
ss -lntp | grep -E ':(80|443)\b'
6

7
# 3. 浏览器访问 https://harbor.local（需先配好客户端 hosts，见下一节）
8
#    默认凭据：admin / Harbor12345（若未改）

使用#

1
echo "192.168.2.11 harbor.local" | sudo tee -a /etc/hosts

1
Add-Content -Path "$env:SystemRoot\System32\drivers\etc\hosts" -Value "192.168.2.11 harbor.local"

1
ping harbor.local
2
# 应当解析到 192.168.2.11

1
# 登录（默认 admin / 你在 harbor.yml 设定的密码）
2
docker login harbor.local
3

4
# 打标签
5
docker tag myapp:latest harbor.local/myproject/myapp:v1.0.0
6

7
# 推送
8
docker push harbor.local/myproject/myapp:v1.0.0
9

10
# 拉取
11
docker pull harbor.local/myproject/myapp:v1.0.0

Nginx 反向代理（使用非 80/443 端口时）#

当宿主机的 80/443 已被其他服务占用，可以让 Harbor 监听非标端口（比如 31080/31443），再用外层 Nginx 做 TLS 终结和对外映射。

1
upstream harbor_backend {
2
    server 127.0.0.1:5443;   # ← 对应 harbor.yml 里的 https.port，按实际填写
3
    keepalive 32;
4
}
5

6
server {
7
    listen 443 ssl http2;
8
    server_name harbor.local;
9

10
    # 复用第 3 节生成的自签名证书
11
    ssl_certificate     /opt/harbor/crt/harbor.crt;
12
    ssl_certificate_key /opt/harbor/crt/harbor.key;
13
    ssl_protocols       TLSv1.2 TLSv1.3;
14
    ssl_ciphers         ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
15

16
    client_max_body_size 0;   # 允许无限大镜像上传，必加
17

18
    location / {
19
        proxy_pass https://harbor_backend;
20

21
        # 关键：Harbor 后端也是 HTTPS（自签证书），Nginx 默认会尝试验证且必定失败，要关掉
22
        proxy_ssl_verify off;
23

24
        proxy_set_header Host $host;
25
        proxy_set_header X-Real-IP $remote_addr;
26
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
27
        proxy_set_header X-Forwarded-Proto $scheme;
28
        proxy_buffering off;
29
        proxy_request_buffering off;
30
        proxy_connect_timeout 90s;
31
        proxy_send_timeout    90s;
32
        proxy_read_timeout    90s;
33
    }
34
}
35

36
server {
37
    listen 80;
38
    server_name harbor.local;
39
    return 301 https://$host$request_uri;
40
}

关于双 TLS 架构

上面是 Nginx HTTPS → Harbor HTTPS 的双 TLS 结构（Nginx 和 Harbor 可以共用同一张自签证书，也可以各用各的）。即便两边用同一张证书，proxy_ssl_verify off; 仍然要加——Nginx 作为 TLS 客户端去连后端时，默认会走完整的 CA 链校验，自签证书没有”可信 CA”，所以一定失败。关掉校验后加密仍然在，只是不再做身份验证。

如果嫌双 TLS 麻烦，还有一种更常见的简化架构：Harbor 跑 HTTP（harbor.yml 里注释掉整个 https: 块、只留 http.port），Nginx 做唯一的 TLS 终结。宿主机本地 Docker 网络里的 HTTP 流量不出机器，风险可接受、配置更简单。

NOTE

如果你的 harbor 是非标端口，请使用下面的 nginx 配置

1
location / {
2
    proxy_pass https://harbor_backend; # 指向 Harbor 内部的 30443
3
    proxy_ssl_verify off;
4

5
    proxy_set_header Host $host:31001; # 显式告诉后端外部端口
6
    proxy_set_header X-Real-IP $remote_addr;
7
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
8
    proxy_set_header X-Forwarded-Proto $scheme;
9
    proxy_set_header X-Forwarded-Port 31001; # 必须明确告诉是 31001
10

11
    # 下面两项对大镜像上传至关重要
12
    proxy_buffering off;
13
    proxy_request_buffering off;
14
}

使用 HTTP（不推荐生产环境）#

在 Docker 的 daemon.json 中添加：

1
{
2
  "insecure-registries": ["harbor.local"]
3
}

1
systemctl restart docker

HTTP 模式的真实风险

insecure-registries 模式下，Docker 和 Harbor 之间所有流量都是明文：

• 登录凭据（HTTP Basic Auth）直接在请求头里裸奔——被嗅探就是当场被盗号
• 镜像层数据也走明文，既能被拦截拷贝、也可能被篡改（例如注入恶意二进制）
• 任何链路上的中间人（交换机、路由器、代理、公共 Wi-Fi AP）都能看到并改写

仅适用于完全隔离的实验网络。只要有一点外部访问，或涉及生产凭据，都必须走 HTTPS。

故障排查#

备份与升级#

Harbor 的全部数据都在 data_volume 指定的目录下（默认 /data），包括 PostgreSQL 数据、镜像层存储、Redis、日志等。升级前一定要备份，出问题才有回滚余地。

1
cd /path/to/harbor-installer
2

3
# 1. 停止 Harbor
4
docker compose down
5

6
# 2. 备份数据目录（data_volume 指定的路径）
7
sudo tar czf /backup/harbor-data-$(date +%F).tar.gz /data
8

9
# 3. 备份 harbor.yml（里面有一堆你调过的配置）
10
cp harbor.yml /backup/harbor.yml.$(date +%F)
11

12
# 4. 重启
13
docker compose up -d

1
# 1. 先按上面"备份"节做完备份
2

3
# 2. 下载新版本的离线安装包、解压到新目录
4
tar xvf harbor-offline-installer-v2.x.x.tgz -C /opt/
5
cd /opt/harbor   # 新版本目录
6

7
# 3. 把旧 harbor.yml 拷过来（保留你的所有配置）
8
cp /backup/harbor.yml.<日期> ./harbor.yml
9

10
# 4. 停止旧版本
11
cd /path/to/old-harbor && docker compose down
12

13
# 5. 在新目录安装（会自动检测 data_volume 里已有数据并升级）
14
cd /opt/harbor
15
./install.sh