Harbor 云原生镜像仓库完全指南核心功能、架构解析与安装部署实战【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harborHarbor 是一个开源的可信云原生容器镜像仓库项目集存储、签名与安全扫描能力于一身。本文以 Harbor 官方 README 为主线结合仓库源码与配置模板系统讲解 Harbor 的功能体系、组件架构、基于 harbor.yml 的安装配置流程以及 v2.15.0 起引入的 Cosign 发布签名验证方案帮助读者在真实环境中完成 Harbor 的部署、加固与日常运维。Harbor 是什么Harbor 的定位是开源的可信云原生注册中心trusted cloud native registry官方描述其核心能力为三个动词存储stores、签名signs、扫描scans。它在开源 Docker Distribution 之上进行了扩展补齐了生产环境通常需要的安全、身份认证与管理能力将镜像仓库部署在离构建与运行环境更近的位置可以显著提升镜像传输效率支持在多个 registry 实例之间复制同步镜像提供用户管理、访问控制、活动审计等高级安全特性。Harbor 由云原生计算基金会Cloud Native Computing FoundationCNCF托管当前仓库版本为 v2.16.0见 VERSION官方建议生产环境使用 Releases 发布的稳定版本而非处于开发状态的main分支。架构总览Harbor 由哪些组件构成Harbor 是一个典型的容器化多组件系统。从仓库的镜像构建目录 make/photon 可以看出其运行时组件构成组件职责core核心业务服务负责 API、认证、项目管理、审计等见 src/core/main.gojobservice异步任务调度服务承载扫描、复制、GC、备份等任务见 src/jobserviceregistry基于 Docker Distribution 的镜像存储与分发引擎registryctlregistry 的管控入口见 src/registryctlnginx统一反向代理对外暴露 80/443 端口portal图形化用户界面Angular 应用见 src/portaldbPostgreSQL 数据库schema 演进记录在 make/migrations/postgresql从 0001 到 0190 共数十个迁移脚本valkey缓存与队列存储Redis 协议兼容trivy-adapter对接 Trivy 漏洞扫描引擎exporterPrometheus 指标导出log日志收集与轮转rsyslog logrotateprepare安装前的配置生成器Python 实现见 make/photon/prepare/main.py在源码层面核心逻辑集中在 src 下的core、controller、jobservice、pkg、server等模块。其中 src/controller 定义了 artifact、replication、scan、quota、retention 等领域控制器的统一入口是理解 Harbor 功能实现的关键目录。核心功能特性详解README 中列出的每一项功能都能在源码中找到对应的实现模块以下逐一展开。云原生注册中心镜像与 Helm ChartHarbor 同时支持容器镜像与 Helm Chart 的存储与分发服务于容器运行时与编排平台。仓库内 src/pkg/chart 保留了 chart 相关代码而 make/install.sh 中明确说明--with-chartmuseum参数已被废弃移除当前以原生方式管理 Chart。基于项目的角色访问控制RBAC用户通过项目project访问不同的仓库在同一项目下对不同镜像或 Chart 可以拥有不同权限。RBAC 的权限模型定义在 src/common/rbac 与 src/pkg/rbac 中涵盖项目级与系统级两种粒度权限类型定义见 src/pkg/permission/types。基于策略的复制Replication镜像与 Chart 可依据策略在多个 registry 实例之间复制同步策略支持按仓库repository、标签tag、标签label三类过滤器筛选内容复制过程中遇到错误会自动重试。复制能力可用于负载均衡、高可用以及混合云/多云场景下的多数据中心部署。从源码看复制策略控制器位于 src/controller/replication/policy.go支持按策略 ID 创建、查询、启动复制执行并可通过 scheduler 注册定时回调REPLICATION_CALLBACK实现计划任务。复制流程的完整执行管线在 src/controller/replication/flow 中实现。Harbor 提供了极其丰富的复制适配器从 src/pkg/reg/adapter 目录可以看到原生支持的目标端包括aliacr阿里云 ACR、awsecr、azurecr、dockerhub、dtr、githubcr、gitlab、googlegcr、harborHarbor 对 Harbor、huawei、jfrog、native原生 registry、quay、tencentcr、volcenginecr等十余家主流容器服务。漏洞扫描Vulnerability ScanningHarbor 会定期扫描镜像漏洞并通过策略检查阻止存在漏洞的镜像被部署。扫描能力的核心实现在 src/controller/scan/base_controller.go负责扫描任务的编排、报告生成与缓存以及 src/pkg/scan扫描引擎接口、报告模型。默认扫描引擎为 Trivy其行为由 make/harbor.yml.tmpl 中的trivy配置块控制关键参数如下参数默认值说明ignore_unfixedfalse仅显示已修复的漏洞skip_updatefalse跳过从 GitHub 下载 Trivy 漏洞数据库离线/CI 环境可开启并手动挂载trivy.dbskip_java_db_updatefalse跳过 Java 漏洞库下载需手动挂载trivy-java.dbdb_repositoryghcr.io/aquasecurity/trivy-dbTrivy 漏洞数据库的 OCI 仓库地址offline_scanfalse离线扫描模式不发送 API 请求识别依赖需与skip_update配合用于隔离环境security_checkvuln检测类型可选vuln、config、secret逗号分隔insecurefalse跳过 registry 证书校验timeout5m0s扫描超时时间任务上限为 30 分钟github_token无提高漏洞库下载的 GitHub 速率限制匿名限 60 次/小时LDAP/AD 与 OIDC 企业身份集成LDAP/AD与现有企业 LDAP/AD 集成支持用户认证、用户管理并可将 LDAP 组导入 Harbor 后授权给指定项目。实现位于 src/core/auth/ldap 与 src/pkg/ldap。OIDC借助 OpenID Connect 验证由外部授权服务器/身份提供方认证的用户身份可启用单点登录直接进入 Harbor 门户。实现位于 src/core/auth/oidc 与 src/pkg/oidc。除两者之外src/core/main.go 的初始化中还注册了db本地数据库、uaaCloud Foundry UAA与authproxyHTTP 反向代理认证三类认证后端共同构成 Harbor 的认证体系。镜像删除与垃圾回收GC系统管理员可运行垃圾回收任务删除悬空 manifest 与未被引用的 blob周期性释放存储空间。GC 控制器见 src/controller/gc相关回调与模型定义callback.go、model.go支撑其作为后台任务被 jobservice 调度执行。图形化门户与审计门户portal基于 Angular 的前端应用src/portal用户可以浏览、搜索仓库并管理项目。审计Auditing所有针对仓库的操作都会通过日志被跟踪记录。审计模块见 src/pkg/audit 与 src/pkg/auditext覆盖登录、用户、项目、成员等事件的审计扩展。RESTful API 与 Swagger UIHarbor 提供完善的 RESTful API 以支持管理操作与外部系统集成并内置 Swagger UI 供探索与测试。API 规范定义在 api/v2.0/swagger.yaml超过一万行的 OpenAPI 2.0 定义basePath 为/api/v2.0对应的服务端 Handler 实现在 src/server/v2.087 个文件。API 支持 basic 认证并提供/health健康检查、/search搜索等无需认证即可访问的公开端点。安装与运行系统要求操作系统Linux 主机Docker20.10.10-ceDocker Compose1.18.0。获取安装包安装包分为离线offline与在线online两种形式均以harbor-{installer}-{version}.tgz命名如harbor-offline-installer-v2.15.0.tgz。安装包由 Makefile 中的package_online/package_offline目标生成通过make package_offline -e DEVFLAGfalse可打生产离线包。离线包内置全部镜像适合隔离网络环境。配置 harbor.yml安装前需在解压目录中创建harbor.ymlmake/harbor.yml.tmpl 提供了完整模板。以下为生产环境必须关注的核心配置项基础与网络# 访问 admin UI 与 registry 服务的 IP 或主机名 # 严禁使用 localhost 或 127.0.0.1因为 Harbor 需要被外部客户端访问 hostname: reg.mydomain.com http: port: 80 # http 端口若启用 https 则该端口重定向到 https 端口 https: port: 443 certificate: /your/certificate/path private_key: /your/private/key/path # strong_ssl_ciphers: false # 是否启用强 SSL 加密套件 # 如需启用组件间内部 TLS # internal_tls: # enabled: true # dir: /etc/harbor/tls/internal # 如需启用外部代理 # external_url: https://reg.mydomain.com:8433管理员密码与数据库# 仅首次安装时生效启动后请在 UI 中及时修改 admin 密码 harbor_admin_password: Harbor12345 database: password: root123 # 默认 postgres 用户的密码生产环境务必修改 max_idle_conns: 100 # 连接池空闲连接上限0 表示不保留空闲连接 max_open_conns: 900 # 最大打开连接数0 表示不限制postgres 默认 1024 conn_max_lifetime: 5m # 连接可复用的最大时长duration 字符串如 5m、2h45m conn_max_idle_time: 0 # 连接最大空闲时长0 表示不因空闲关闭数据卷与外部存储data_volume: /data # 默认使用本地文件系统 /data如需外部存储可配置 # storage_service: # ca_bundle: # 自签名证书存储的自定义 CA # filesystem: # maxthreads: 100 # redirect: # disable: falsejobservice 与通知jobservice: max_job_workers: 10 # 任务服务最大并发 worker 数 max_job_duration_hours: 24 # 任务最大执行时长小时 job_loggers: # 任务日志后端STD_OUTPUT / FILE / DB - STD_OUTPUT - FILE logger_sweeper_duration: 1 # 日志清理周期天 notification: webhook_job_max_retry: 3 # webhook 任务最大重试次数 webhook_job_http_client_timeout: 3 # webhook HTTP 客户端超时秒日志log: level: info # debug / info / warning / error / fatal local: rotate_count: 50 # 轮转保留份数0 表示直接删除旧版本 rotate_size: 200M # 轮转阈值支持 100k / 100M / 100G location: /var/log/harbor # 宿主机日志目录 # external_endpoint: # 外部 syslog 端点 # protocol: tcp # tcp / udp # host: localhost # port: 5140代理、指标与追踪proxy: # 全局代理用于复制功能时必须为 core 和 jobservice 开启 http_proxy: https_proxy: no_proxy: components: - core - jobservice - registry - trivy # metric: # enabled: false # port: 9090 # path: /metrics # trace: # 同一时间只能启用 jaeger 或 otel 一种 provider # enabled: true # sample_rate: 1 # 1 表示 100% 采样 # jaeger: # endpoint: http://hostname:14268/api/traces # agent_host: hostname # agent_port: 6831 # otel: # endpoint: hostname:4318 # url_path: /v1/traces上传临时目录清理与缓存层upload_purging: enabled: true age: 168h # 清理存在超过该时长的 _upload 目录文件默认一周 interval: 24h # 清理任务执行间隔 dryrun: false # 试运行模式 cache: # 在 redis 中缓存 project/metadata/repository/artifact/manifest enabled: false # 可显著提升高并发 manifest 拉取性能 expire_hours: 24 # 注意HA 模式下所有实例必须一致地开启或关闭此外模板还提供了external_database、external_redis支持redis与redissentinel可配置 TLS、uaa证书、core.quota_update_providerredis或db高并发推送同一项目时可切换为 redis等扩展配置。模板末尾的_version: 2.15.0字段用于 migrator 检测配置文件版本请勿修改。执行安装解压安装包后运行sudo ./install.shmake/install.sh 的实际执行流程为校验harbor.yml中已设置 hostname且不得为 localhost/127.0.0.1检查 docker 与 docker-compose 是否已安装若当前目录存在harbor*.tar.gz执行docker load -i加载离线镜像运行./preparePython 配置生成器生成各组件配置与 docker-compose 文件停止已存在的 Harbor 实例docker-compose down -vdocker-compose up -d启动全部服务。如需启用漏洞扫描安装时添加--with-trivy参数sudo ./install.sh --with-trivy。注意--with-chartmuseum与--with-notary已废弃移除不要使用。Kubernetes 部署生产环境如需部署在 Kubernetes 上官方提供 Harbor Helm Chart 支持并可结合 Harbor Operator 实现更完善的运维管理。从源码构建开发者可从仓库源码自行构建镜像与安装包Makefile 提供了完整目标make prepare准备环境、make compile编译 core 与 jobservice、make build构建 Harbor 镜像、make install编译构建安装、make package_online/make package_offline打包、make pushimage推送镜像到指定 registry以及make clean清理二进制、镜像与安装包。发布签名验证v2.15.0自 Harborv2.15.0起官方发布产物安装包使用Cosign进行无密钥keyless签名用户可以在下载后验证产物的真实性与完整性。详细指南见 docs/signature-verification.md。为什么要验证确认文件来自 Harbor 官方构建流水线检测文件是否被修改或篡改防范恶意下载与供应链攻击。前提安装 Cosignv2.0# macOS brew install sigstore/tap/cosign # Linux从 sigstore 官方发布页下载 cosign-linux-amd64 # 并安装到 /usr/local/bin/cosignchmod x 后 # Windows (PowerShell) Invoke-WebRequest -Uri ... -OutFile cosign.exe # 验证安装 cosign version验证离线安装包# 1. 从 Harbor 官方 Releases 页面下载安装包及其签名文件示例 v2.15.0 wget release-url/harbor-offline-installer-v2.15.0.tgz wget release-url/harbor-offline-installer-v2.15.0.tgz.sigstore.json # 2. 验证签名 cosign verify-blob \ --bundle harbor-offline-installer-v2.15.0.tgz.sigstore.json \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp ^https://github.com/goharbor/harbor/.github/workflows/publish_release.ymlrefs/tags/v.*$ \ harbor-offline-installer-v2.15.0.tgz预期输出Verified OK验证在线安装包在线安装包的验证命令完全一致只需替换文件名wget release-url/harbor-online-installer-v2.15.0.tgz wget release-url/harbor-online-installer-v2.15.0.tgz.sigstore.json cosign verify-blob \ --bundle harbor-online-installer-v2.15.0.tgz.sigstore.json \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp ^https://github.com/goharbor/harbor/.github/workflows/publish_release.ymlrefs/tags/v.*$ \ harbor-online-installer-v2.15.0.tgz常见问题排障现象原因解决方案证书身份不匹配验证命令中仓库名写错确保--certificate-identity-regexp中使用goharbor/harbor找不到签名签名文件与安装包不在同一目录确保.tgz与.tgz.sigstore.json位于当前工作目录签名错误Bad signature下载文件损坏或不完整从官方 Releases 页面重新下载安装包与签名文件版本不支持验证的是 v2.15.0 之前的版本签名验证仅适用于 Harbor v2.15.0 及之后版本验证了什么文件真实性由 Harbor 官方 CI/CD 工作流publish_release.yml签名文件完整性签名之后未被修改构建来源provenance签名记录被写入公开的 Sigstore 透明日志可公开审计。README 中的 Verifying Release Signatures 一节即是对上述流程的精简版演示Quick Verification完整操作与排障请参考 docs/signature-verification.md。OCI Distribution 一致性测试Harbor 持续通过OCI Distribution Conformance TestsOCI 分发规范一致性测试验证其对 OCI 镜像分发协议的兼容性。仓库内的 tests/ci/conformance_test.sh 即用于在 CI 中运行该一致性测试套件相关 badge 也展示在 README 顶部。这意味着用户可以将 Harbor 作为符合 OCI 规范的 registry 与各类符合标准的客户端、工具链配合使用。兼容性与生态Harbor 官方维护三类兼容性清单分别覆盖复制适配器Replication adapters与上述 src/pkg/reg/adapter 目录中十余种目标 registry 一一对应OIDC 适配器OIDC adapters支持的外部身份提供方扫描器适配器Scanner adapters可对接的第三方漏洞扫描引擎。这些兼容清单保证 Harbor 在企业异构环境中的可集成性社区使用者名录可参考 ADOPTERS.md。安全与社区治理安全审计Harbor 曾于 2019 年 10 月委托第三方安全公司 Cure53 进行安全审计并出具完整报告详见 docs 目录相关文档与 README Security 章节。报告安全漏洞发现安全相关问题或潜在漏洞时不要提交公开 issue而应通过私密渠道报告。Harbor 的安全团队会在确认后跟进处理完整的安全发布流程见 SECURITY.md。开源许可Harbor 采用 Apache 2.0 许可证 发布并遵循 CNCF 社区的协作与治理模式双周社区例会、用户组、开发者组等沟通渠道。结语Harbor 以一个统一的平台整合了镜像存储、RBAC、策略复制、漏洞扫描、企业身份集成、GC、审计与完整的 RESTful API配合 Docker Compose 与 Helm Chart 两种部署路径已成为云原生环境下值得优先评估的 registry 方案。从 v2.15.0 起的 Cosign 签名验证机制更进一步将供应链安全实践落到了安装包分发环节。希望本文能帮助你在理解 Harbor 架构与功能全景的基础上顺利完成部署、加固与日常运维。【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考