Harbor 配置参数详解

目标：系统梳理 Harbor 2.15.4 的核心配置参数。Harbor 的所有部署级参数集中在 harbor.yml（由 ./prepare 生成各组件运行配置），本指南覆盖 hostname / http / https / certificate / database / 配额（quota）/ 审计日志 / 机器人账户（robot account）等维度，每个参数给出实测取值、修改方式与生产建议。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• 系统架构：x86_64
• Harbor 版本：2.15.4
• 配置文件：/opt/harbor-installer/harbor/harbor.yml（源配置）与模板 harbor.yml.tmpl
• 配置分发：./prepare 依据 harbor.yml 生成 common/config/<svc>/ 各组件运行时配置
• 数据目录：/opt/data/harbor
• 管理账号：admin ／ 密码 q1w2e3r4
• 服务器地址：172.17.0.63

💡 说明：本指南"实测取值"均来自本机全新部署的 Harbor 2.15.4（vfs 存储驱动 + 自签 HTTPS + admin/q1w2e3r4）采集，可直接对照。

二、前置条件

• 已部署 Harbor 2.15.4（参考《Ubuntu 22.04 安装 Harbor 指南》）
• 具备 mod 权限（修改 harbor.yml 需重启组件使其生效）

三、参数查看与修改方式

3.1 查看当前 harbor.yml

cd /opt/harbor-installer/harbor
cat harbor.yml

3.2 修改与生效流程

Harbor 的配置变更统一走「改 harbor.yml → 重新 ./prepare → docker compose up -d」三步：

vim harbor.yml            # 修改参数
export TERM=xterm
./prepare                 # 重新生成 docker-compose.yml 与 common/config/
docker compose up -d      # 重建受影响组件使配置生效

⚠️ 注意：只改 harbor.yml 而不重新 ./prepare，或直接改 common/config/，都会被下一次 prepare 覆盖。必须按上述三步执行。

3.3 运行时（Web）参数

Harbor 仍有大量参数在 Web 控制台（/harbor/）维护，与 harbor.yml 并存且不冲突：满额策略、标签、复制规则、机器人账户、项目满额等大多在 UI/API 层配置，落库而非落 yml。harbor.yml 主要管部署级（网络、TLS、存储、日志、基础设施连接）。

四、参数总览

💡 说明：上表"重启"指需执行 ./prepare && docker compose up -d 使组件重建生效。网络/证书/数据库/存储/日志均属此类。

五、核心参数分类详解

5.1 hostname（对外地址）

hostname: 172.17.0.63

• 作用：Harbor 控制台与 registry 对外访问时生成链接所依据的地址/域名。
• 禁止使用 localhost / 127.0.0.1，否则外部客户端无法访问。
• 生产建议使用内网域名或负载均衡 VIP；若经 TLS 还要保证与 server.crt 的 subjectAltName 一致（IP 或 DNS）。

⚠️ 修改 hostname 后需同步更新自签证书的 SAN，并重跑 ./prepare && docker compose up -d。

5.2 http / https（监听端口）

http:
  port: 80

https:
  port: 443
  certificate: /opt/data/harbor/server.crt
  private_key: /opt/data/harbor/server.key

• http.port 开启 HTTP（本部署 80），访问 HTTP 时 Harbor 自动 301 跳转到 HTTPS 端口。
• https.port 默认 443；certificate/private_key 指向服务端证书与私钥。
• 若端口冲突，改这两项后重新 prepare（proxy 端口映射随之更新）。

5.3 certificate（自签 HTTPS）

https:
  certificate: /opt/data/harbor/server.crt
  private_key: /opt/data/harbor/server.key

• 证书由 openssl 生成并放置于数据目录 /opt/data/harbor（见安装指南 4.4），SAN 必须含 hostname 对应的 IP/域名。
• Harbor 内部会把 CA（ca.crt）注入信任库供组件间 TLS 使用（/opt/data/harbor/secret/registry/root.crt 等）。
• 生产建议替换为企业 CA/正式证书，仅需替换 server.crt/server.key 并重跑 prepare。

5.4 database（内置 PostgreSQL）

database:
  password: root123
  max_idle_conns: 100
  max_open_conns: 900
  conn_max_lifetime: 5m
  conn_max_idle_time: 0

• password 为内置 PostgreSQL（postgres 用户）密码，部署时初始化。
• max_idle_conns / max_open_conns 控制连接池，高并发推送大项目时可按需上调 max_open_conns（默认上限 1024）。
• conn_max_lifetime: 5m 限制连接复用时长，避免旧连接泄漏；conn_max_idle_time: 0 表示连接不因闲置主动关闭。
• 生产如需外置数据库，取消注释 external_database 段并填写 Harbor 元数据库连串（host/port/db_name/username/password/ssl_mode）。

5.5 data_volume（数据卷）

data_volume: /opt/data/harbor

• Harbor 的制品、数据库、日志、secret 等全部在该目录下分目录存放（database/、registry/、job_logs/、redis/、secret/、ca_download/）。
• 建议放独立数据盘并做备份。改此路径需重新 prepare，且历史数据不会自动迁移。

5.6 配额（Quota）配置

Harbor 的配额控制主要在 Web / REST API 层（/api/v2.0/projects/{name}/quotas），harbor.yml 中无独立 quota 块。部署级与之相关的仅有该高速推送场景的可选参数（core 段 quota_update_provider）：

# core:
#   # 满额用量统计后端：redis 或 db，默认 db
#   quota_update_provider: db   # 高并发推送同项目时可用 redis 降低 DB 连接尖峰，但有展示延迟

• 默认项目满额在创建项目时设置（storage_limit，如 -1 表示不限）。
• 通过 API 查看某项目满额用量（实测）：

curl -sk -u admin:q1w2e3r4 "https://172.17.0.63/api/v2.0/projects/1/quotas"

💡 说明：满额控制建议：单人/小团队用默认不限即可；多人共享项目建议设 storage_limit 限制（如 10737418240 即 10 GiB），并在满额将满时告警。

5.7 jobservice（异步任务）

jobservice:
  max_job_workers: 10
  max_job_duration_hours: 24
  job_loggers:
    - STD_OUTPUT
    - FILE
  logger_sweeper_duration: 1

• max_job_workers：并发任务数（复制/扫描/GC 等），默认 10，可按 CPU 上调。
• max_job_duration_hours：单任务最长执行时长，默认 24h。
• job_loggers：任务日志后端，默认 STD_OUTPUT + FILE；可加 DB。
• logger_sweeper_duration：日志清理周期（天）。

5.8 审计日志

审计/操作日志由 log 组件统一聚合；本地写路径与轮转在 log 块配置：

log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
    location: /var/log/harbor

• log.level 取值 debug|info|warning|error|fatal。
• /var/log/harbor 是本机日志目录（宿主机视角），配合 rsyslog 集中管理。
• 对外端可启用 log.external_endpoint（tcp/udp，填外部 syslog 服务器 host/port）把日志外送做集中审计。

💡 审计建议：生产开启 external_endpoint 把 Harbor 日志汇入集中日志平台；保留关键操作（登录、满额变更、复制）追踪入口。

5.9 机器人账户（Robot Account）

机器人账户是 Harbor 用于 CI/CD 机器之间的授权凭据，配置在 Web / REST API 层（/api/v2.0/projects/...），不写在 harbor.yml。创建后获得一组 robot$<project>+<name> 用户名与口令。

通过 REST 创建项目级机器人（实测）：

curl -sk -u admin:q1w2e3r4 -X POST \
  "https://172.17.0.63/api/v2.0/projects/myapp/robots" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-build",
    "duration": -1,
    "level": "project",
    "disable": false,
    "permissions": [
      {
        "kind": "project",
        "namespace": "myapp",
        "access": [
          {"resource": "repository", "action": "push"},
          {"resource": "repository", "action": "pull"}
        ]
      }
    ]
  }'

响应要点（实测）： 返回 {"name":"robot$myapp+ci-build","token":"<随机口令>",...}，robot$myapp+ci-build 即登录用户名，token 为一次性明文口令。

用机器人登录并推拉（实测）：

echo "<token>" | docker login 172.17.0.63 -u 'robot$myapp+ci-build' --password-stdin
docker tag alpine:3.20 172.17.0.63/myapp/alpine:1.0
docker push 172.17.0.63/myapp/alpine:1.0
docker pull 172.17.0.63/myapp/alpine:1.0

💡 说明：机器人 = 生产推荐的身份方案。它按项目隔离权限、可设置有效期（duration，-1 永久）、可随时 disable，口令只在创建时明文返回一次。相比在 CI 里写死 admin 密码更安全。

5.10 其他常用参数

trivy:                 # 漏洞扫描器（本质即扫描任务）
  ignore_unfixed: false
  skip_update: false
  skip_java_db_update: false
  db_repository: ghcr.io/aquasecurity/trivy-db
  java_db_repository: ghcr.io/aquasecurity/trivy-java-db
  insecure: false
  timeout: 5m0s

notification:          # Webhook 通知
  webhook_job_max_retry: 3
  webhook_job_http_client_timeout: 3

upload_purging:        # _upload 临时目录清理
  enabled: true
  age: 168h
  interval: 24h
  dryrun: false

cache:                 # Redis 缓存层（高并发拉取优化）
  enabled: false
  expire_hours: 24

• trivy：在安装指南安装时未启用 Trivy（未加 --with-trivy）时扫描会返回 412 Precondition Failed；需要启用 Trivy 请在部署时执行 ./install.sh --with-trivy。
• upload_purging：定时清理未完成的 _upload 临时目录，默认开启。
• cache：Redis 缓存资源（项目/仓库/制品元数据），HA 场景需所有节点一致开启或关闭。

六、生产配置模板（按场景）

6.1 小规模（4GB 内存 / SSD / 单团队）

hostname: harbor.internal
http:
  port: 80
https:
  port: 443
  certificate: /opt/data/harbor/server.crt
  private_key: /opt/data/harbor/server.key
harbor_admin_password: q1w2e3r4
data_volume: /opt/data/harbor
database:
  max_idle_conns: 50
  max_open_conns: 200
jobservice:
  max_job_workers: 5
log:
  level: info

6.2 中等规模（16GB 内存 / NVMe SSD / 多团队共享）

hostname: harbor.corp.example.com
https:
  port: 443
  certificate: /etc/harbor/tls/server.crt
  private_key: /etc/harbor/tls/server.key
data_volume: /opt/data/ssd/harbor
database:
  max_idle_conns: 100
  max_open_conns: 900
  conn_max_lifetime: 5m
jobservice:
  max_job_workers: 20
cache:
  enabled: true
  expire_hours: 24
log:
  level: info
  external_endpoint:
    protocol: tcp
    host: logserver.corp.example.com
    port: 5140

💡 说明：6.2 启用了 Redis 缓存层（改善高并发拉取）与外部审计日志汇聚；数据库吞吐用默认 max_open_conns: 900。此模板面向「多团队共享、需审计」场景。

七、常见问题

7.1 问题 1：改了 harbor.yml 但什么都没变

原因： 未重新执行 ./prepare 就 up -d，或直接改了 common/config/。

解决： 按「三、3.2」三步走：vim harbor.yml → ./prepare → docker compose up -d。

7.2 问题 2：修改 hostname 后 HTTPS 报证书 SAN 不匹配

原因： server.crt 的 subjectAltName 与新的 hostname 不一致。

解决： 用 openssl 重新生成含新 SAN 的服务端证书（见安装指南 4.4），再 ./prepare && docker compose up -d。

7.3 问题 3：漏洞扫描返回 412 Precondition Failed

原因： 安装时未启用 Trivy（./install.sh 未加 --with-trivy）。

解决： 用 ./install.sh --with-trivy 重新部署启用扫描器；或先手动安装 trivy-db 供离线扫描。

7.4 问题 4：docker login 用 admin 密码提示认证失败

原因： Harbor 默认会强制 admin 在首次登录后修改密码，或口令错误。

解决： 用正确的 admin/q1w2e3r4 或在 UI 重置；生产建议改用机器人账户凭据而非 admin 密码（见 5.9）。

7.5 问题 5：数据库连接数被打满（高并发推送）

原因： 大量并发推送导致 PostgreSQL 连接尖峰。

解决： 适当调高 max_open_conns（上限约 1024），或将 core.quota_update_provider 切到 redis 降低写入满额统计的连接占用（见 5.6）。

八、参考链接

• Harbor 官方配置（harbor.yml）文档
• Harbor 官方 HTTPS 配置
• Harbor 官方数据库配置
• Harbor 官方机器人账户文档
• Harbor 官方配额管理

本文档由 www.quzuo.net 平台开发