1、Harbor 2.2.1 配置文件harbor.yml详解

Harbor 是一个开源的企业级容器镜像仓库，提供镜像存储、签名、扫描、管理等功能。其核心配置通过 harbor.yml 文件管理，该文件定义了 Harbor 各组件的运行参数、依赖服务（数据库、Redis 等）的连接方式、存储路径、认证方式等关键信息。

本文将详细解析 Harbor 2.2.1 的核心配置文件 harbor.yml 及相关配置逻辑。

一、配置文件基本信息

1.1 默认路径与作用

Harbor 2.2.1 的核心配置文件为 harbor.yml，默认位于 Harbor 安装目录下（如 /opt/harbor/harbor.yml）。该文件是 Harbor 初始化和运行的 “总开关”，所有核心配置均通过此文件定义。

Harbor 启动时，会通过 prepare 脚本读取 harbor.yml，生成各组件（如 Nginx、Registry、PostgreSQL、Redis 等）的具体配置文件（输出到 common/config 目录），并基于这些配置启动容器。

1.2 配置文件加载流程

1. 初始化阶段：执行 install.sh 或 prepare 脚本时，harbor.yml 被解析，生成适配各组件的配置（如 common/config/nginx/nginx.conf、common/config/registry/config.yml 等）。
2. 运行阶段：Docker Compose 基于生成的配置启动容器，组件运行时读取各自的配置文件。
3. 配置更新：若修改 harbor.yml，需重新执行 prepare 脚本生成新配置，再重启 Harbor（docker-compose down && docker-compose up -d）使配置生效。

二、核心配置文件 harbor.yml 详解

harbor.yml 按功能可分为 全局配置、存储配置、依赖服务配置、功能模块配置 等几大模块，以下逐一解析。

2.1 全局基础配置

全局配置定义 Harbor 的访问方式、核心标识等基础信息，是必须正确配置的部分。

配置项	含义	默认值 / 示例	注意事项
hostname	Harbor 的访问主机名 / IP（必填）	reg.example.com 或 192.168.1.100	不可用 localhost 或 127.0.0.1（否则其他机器无法访问）；支持域名或 IP。
http	HTTP 协议配置（用于非加密访问）	-	生产环境建议禁用，仅测试用。
http.port	HTTP 端口	80	若启用，需确保端口未被占用。
https	HTTPS 协议配置（推荐生产环境启用）	-	需配置证书和私钥，否则无法启用。
https.port	HTTPS 端口	443	标准端口，可自定义（如 8443）。
https.certificate	HTTPS 证书路径	./cert/server.crt	需为 PEM 格式，路径可绝对或相对（相对 Harbor 安装目录）。
https.private_key	HTTPS 私钥路径	./cert/server.key	需与证书匹配，权限建议设为 600（避免权限过高导致 Nginx 启动失败）。
external_url	外部访问 Harbor 的完整 URL（如通过反向代理时） 当 Harbor 部署在反向代理（如 Nginx、HAProxy）或负载均衡器后面时，需要使用此参数来正确配置外部访问地址。	-	格式：https://reg.example.com:8443，用于生成正确的回调链接。

external_url 是 Harbor 配置文件 harbor.yml 中的一个重要参数，用于指定 Harbor 服务对外暴露的完整 URL。当 Harbor 部署在反向代理（如 Nginx、HAProxy）或负载均衡器后面时，需要使用此参数来正确配置外部访问地址。

主要作用

1. 覆盖 hostname 设置：当启用 external_url 后，Harbor 将忽略 hostname 参数，转而使用 external_url 作为服务的访问地址。
2. 处理复杂网络环境：适用于 Harbor 内部地址与外部访问地址不一致的场景，如容器内部使用私有 IP，而外部通过公网域名访问。
3. 确保 API 和 UI 路径正确：影响 Harbor 生成的链接（如令牌、镜像拉取地址），避免路径错误。

external_url地址配置跟nginx servername配置一致，前面加上https或者http，取决于nginx是否启用https或者http；如果后端有两个harbor，两个harbor的external_url是一致的，都指向同一外部域名。

2.2 存储配置

Harbor 的数据（镜像、数据库、日志等）存储路径及后端存储配置在此定义。

2.2.1 本地数据存储

yaml

data_volume: /data/harbor  # Harbor 所有数据的根目录（镜像、数据库文件、日志等）

• 作用：默认存储路径，包含镜像数据（/data/harbor/registry）、数据库文件（/data/harbor/database）、Redis 数据（/data/harbor/redis）等。
• 注意：需确保该目录有足够权限（建议 755），且磁盘空间充足（镜像存储可能占用大量空间）。

2.2.2 镜像存储后端配置（storage_service）

Harbor 支持多种镜像存储后端（默认使用本地文件系统，也可配置 S3、GCS 等对象存储），配置如下：

yaml

storage_service:
  # 存储后端类型：filesystem（默认）、s3、gcs、azure、swift 等
  type: filesystem
  # 文件系统存储配置（当 type=filesystem 时生效）
  filesystem:
    rootdirectory: /var/lib/registry  # 镜像数据实际存储路径（默认映射到 data_volume/registry）
  # S3 存储配置（当 type=s3 时生效）
  s3:
    endpoint: s3.amazonaws.com  # S3 服务端点
    bucket: harbor-registry     # 存储桶名称
    accesskey: AKIAJxxxxxxxxxx  # 访问密钥
    secretkey: secretkey        # 密钥
    region: us-west-1           # 区域
    # 其他可选：encrypt=true, secure=true（是否启用 HTTPS）等

• 说明：生产环境中，若镜像量大，建议使用对象存储（如 S3）替代本地文件系统，避免单点存储风险。

2.3 依赖服务配置

Harbor 依赖 PostgreSQL（数据库）、Redis（缓存 / 会话），支持内置或外部服务配置。

2.3.1 数据库配置（database）

Harbor 使用 PostgreSQL 存储用户、项目、权限等元数据，默认启用内置数据库，也可配置外部数据库。

yaml

database:
  type: postgresql  # 数据库类型（仅支持 postgresql）
  host: db          # 数据库主机（内置为容器名 `db`，外部为 IP/域名）
  port: 5432        # 端口（默认 5432）
  user: postgres    # 用户名
  password: root123 # 密码（内置默认，外部需与实际一致）
  db_name: registry # 数据库名
  ssl_mode: disable # SSL 模式（disable/enable/verify-ca/verify-full）
  # 连接池配置
  max_idle_conns: 50    # 最大空闲连接数
  max_open_conns: 1000  # 最大打开连接数
  conn_max_lifetime: 5m # 连接最大存活时间

• 注意：若使用外部数据库，需提前创建数据库（registry）并授权用户权限，且确保 Harbor 可网络访问数据库。

2.3.2 Redis 配置（redis）

Redis 用于缓存镜像元数据、存储会话及任务队列（如垃圾回收、镜像复制），默认内置，支持外部配置。

yaml

redis:
  host: redis          # Redis 主机（内置为容器名 `redis`，外部为 IP/域名）
  port: 6379           # 端口（默认 6379）
  password: ""         # 密码（无密码则留空）
  db_index: 0          # 数据库编号（默认 0，建议不同模块用不同编号避免冲突）
  ssl: false           # 是否启用 TLS
  # 各模块 Redis 配置（可选，默认复用上述配置）
  registry_db_index: 1 # Registry 模块使用的数据库编号
  jobservice_db_index: 2 # Jobservice 模块使用的数据库编号
  core_db_index: 3     # Core 模块使用的数据库编号

• 说明：Redis 数据库编号（db_index）范围为 0-15，建议不同模块使用不同编号，避免 key 冲突。

2.4 日志配置（log）

定义 Harbor 各组件的日志输出级别、轮转策略等。

yaml

log:
  level: info  # 日志级别：debug/info/warn/error/fatal
  # 日志轮转配置
  rotate:
    maxsize: 200  # 单个日志文件最大大小（MB）
    maxbackups: 10 # 保留日志文件最大数量
    maxage: 30    # 日志文件最大保留天数（天）
    compress: true # 是否压缩旧日志
  # 日志输出路径（默认映射到 data_volume/logs）
  location: /var/log/harbor
  # 可选：发送日志到 syslog
  # syslog:
  #   address: 127.0.0.1:514
  #   protocol: udp

• 建议：生产环境日志级别设为 info（避免 debug 日志占用过多空间），并配置合理的轮转策略。

2.5 认证配置（auth）

Harbor 支持多种认证方式，默认使用内置数据库（db_auth），也可集成 LDAP/AD、OIDC。

2.5.1 内置数据库认证（默认）

yaml

auth:
  mode: db_auth  # 认证模式：db_auth/ldap_auth/oidc_auth
  # 令牌有效期（默认 30 分钟）
  token_expiration: 30
  # 令牌 issuer（需与 hostname 一致）
  token_issuer: harbor-token-issuer

2.5.2 LDAP/AD 认证

yaml

auth:
  mode: ldap_auth
  ldap:
    url: ldap://ldap.example.com:389  # LDAP 服务器地址
    # LDAP 管理员 DN（用于查询用户）
    search_dn: cn=admin,dc=example,dc=com
    search_password: admin123        # 管理员密码
    # 用户搜索基础 DN
    base_dn: ou=users,dc=example,dc=com
    # 用户过滤规则（{0} 替换为登录用户名）
    filter: (objectClass=person)
    uid: sAMAccountName  # LDAP 用户名属性（AD 常用 sAMAccountName）
    # 可选：用户邮箱属性
    email_attribute: mail

2.5.3 OIDC 认证（如集成 Keycloak）

yaml

auth:
  mode: oidc_auth
  oidc:
    issuer_url: https://keycloak.example.com/auth/realms/harbor  # OIDC  issuer URL
    client_id: harbor-client                                    # 客户端 ID
    client_secret: secret                                       # 客户端密钥
    scope: openid,email,profile                                 # 请求的权限范围
    # 用户名映射（从 OIDC claims 中提取）
    username_claim: preferred_username
    email_claim: email

2.6 项目与镜像管理配置

2.6.1 项目配置（project）

yaml

project:
  # 默认项目可见性：public（公开）/private（私有）
  default_visibility: private
  # 是否允许创建公开项目
  enable_public: true
  # 默认存储配额（GB，0 表示无限制）
  default_quota: 0

2.6.2 镜像扫描配置（clair）

Clair 是 Harbor 的镜像漏洞扫描组件，配置如下：

yaml

clair:
  # 漏洞数据库更新间隔（默认 12 小时）
  updater_interval: 12h
  # Clair 数据库配置（默认内置，支持外部）
  database:
    type: postgresql
    host: clair-db
    port: 5432
    user: postgres
    password: root123
    db_name: clair

• 说明：扫描依赖漏洞数据库，需确保 Clair 可联网更新（或配置离线更新）。

2.6.3 垃圾回收配置（gc）

镜像垃圾回收用于清理未被引用的镜像层（如删除标签后残留的层），配置如下：

yaml

gc:
  # 是否启用自动垃圾回收
  enabled: true
  # 自动执行时间（Crontab 表达式，默认每天 00:00）
  crontab: "0 0 * * *"
  # 回收模式：dryrun（仅检查不删除）/delete（实际删除）
  mode: delete

• 注意：首次执行建议用 dryrun 模式确认清理内容，避免误删。

2.7 其他配置

2.7.1 metrics 监控

yaml

metrics:
  enabled: true  # 是否启用 Prometheus metrics
  port: 9090     # metrics 暴露端口
  path: /metrics # metrics 路径

• 说明：启用后可通过 http://hostname:9090/metrics 收集监控数据。

2.7.2 分布式追踪（trace）

yaml

trace:
  enabled: false  # 是否启用追踪
  # 追踪后端（如 Jaeger）
  jaeger:
    endpoint: http://jaeger:14268/api/traces
    sampler: 1.0  # 采样率（0-1）

三、常见配置问题与注意事项

1. hostname 配置错误：若设为 localhost 或 127.0.0.1，其他机器无法访问 Harbor，需改为实际 IP 或域名。

2. HTTPS 证书问题：证书 / 私钥路径错误、权限过高（如 777）会导致 Nginx 启动失败，建议权限设为 600，且证书需包含完整链。

3. 存储路径权限：data_volume 目录需确保 Harbor 容器有读写权限（如属主设为 10000:10000，与容器内用户一致）。

4. 外部服务连接失败：配置外部数据库 / Redis 时，需检查网络连通性、端口开放、账号密码正确性。

5. 配置更新不生效：修改 harbor.yml 后必须执行 ./prepare 重新生成配置，再重启 Harbor。

四、总结

harbor.yml 是 Harbor 的核心配置入口，涵盖访问方式、存储、依赖服务、认证、安全等所有关键参数。配置时需根据实际场景（开发 / 生产）调整，例如生产环境建议启用 HTTPS、使用外部存储和数据库、配置合理的日志和垃圾回收策略。修改配置后需严格遵循 “修改→prepare→重启” 流程，确保配置生效。

如需进一步优化，可结合 Harbor 官方文档（2.2.1 版本文档）调整参数，平衡安全性、性能与可用性。