1. Harbor项目概述与核心价值如果你在搞容器化尤其是用Kubernetes那Harbor这个名字你肯定不陌生。简单说Harbor就是一个企业级的私有Docker镜像仓库。为什么说“企业级”因为Docker官方的公共仓库Docker Hub对于企业内部使用来说有几个明显的痛点首先是安全把公司的核心业务镜像放到公网上心里总是不踏实其次是效率从海外拉取镜像那个速度尤其是在没有优化网络的情况下简直是开发流程的“血栓”再者是管理团队大了谁都能随便推镜像、删镜像版本混乱、权限不清运维和审计头都大了。Harbor就是来解决这些问题的。它基于开源的Docker Distribution项目构建但增加了非常多企业必需的功能。最核心的我认为是这几点基于角色的访问控制RBAC你可以像管理服务器权限一样精细控制哪个项目组能推拉哪个仓库的镜像镜像漏洞扫描集成了Clair、Trivy等工具能在镜像入库前或入库后自动扫描告诉你里面有没有已知的安全漏洞这简直是安全左移的利器镜像复制支持在多数据中心、多个Harbor实例之间同步镜像对于容灾和多活部署特别有用还有图形化的管理界面让非命令行的同学也能轻松管理镜像。我自己在从开发测试到生产上线的完整CI/CD流水线里Harbor都是那个不可或缺的“镜像枢纽站”所有构建好的镜像在这里汇聚、质检、分发。2. Harbor核心功能与架构拆解要玩转Harbor不能只停留在点击按钮的层面得稍微了解一下它肚子里有哪些“器官”以及它们是怎么协同工作的。这样出了问题你才知道该从哪儿入手排查。2.1 核心组件与数据流一个标准的Harbor安装后会跑起来一堆容器它们各司其职。你可以通过docker-compose ps命令来查看。最重要的几个服务包括Core核心服务这是Harbor的大脑和API网关。我们通过网页或者命令行docker login/push/pull的所有操作最终都会请求到Core服务。它负责处理用户认证、项目管理、策略配置等所有业务逻辑。Registry这就是Docker官方的那个镜像仓库服务Harbor用它来实际存储Docker镜像的层layer和数据。它只负责最底层的存储和分发不管权限。DatabasePostgreSQL存储Harbor所有的元数据。比如用户信息、项目信息、机器人账户、复制策略、扫描任务记录等等。这里有个坑Harbor的数据库里不存镜像本身镜像的二进制数据存在后端存储比如文件系统、S3里但所有镜像的标签tag、摘要digest、属于哪个项目这些信息都在数据库里。所以定期备份数据库至关重要。Redis用作Core和Jobservice等组件之间的缓存和消息队列。比如当你触发一个镜像复制任务时这个任务消息就是通过Redis传递的。Jobservice干“脏活累活”的。像镜像复制、垃圾回收GC、镜像扫描这些耗时、异步的任务都是由Jobservice来执行的。它从Redis里领取任务干完了再更新状态。Portal就是咱们看到的那个漂亮的Web管理界面它主要和Core服务通信。当你执行docker push myharbor.com/library/nginx:latest时数据流大致是这样的Docker客户端先请求Core进行认证认证通过后Core会返回一个临时的令牌并告诉客户端实际把镜像层推送到哪个Registry实例客户端拿着令牌直接把镜像层数据推送到RegistryRegistry存储成功后会回调通知CoreCore再更新数据库在Web界面上你就能看到这个新镜像了。2.2 存储与高可用设计Harbor的存储分为两部分镜像文件存储和数据库存储。对于生产环境这两者的高可用是必须考虑的。镜像文件存储默认是使用本地文件系统。这在单机测试时没问题但生产环境强烈建议配置外部存储。Harbor支持多种后端S3/OSS/COS等对象存储这是目前最推荐的方式。扩展性好天生高可用而且能和Harbor的镜像复制功能很好地结合实现跨区域的镜像同步。配置时需要注意存储桶的权限策略Policy。Azure Blob Storage/GCS对于使用相应云平台的企业是自然选择。SwiftOpenStack环境下的选择。持久化卷如Ceph、NFS在私有云或物理机环境中可以通过Kubernetes的PersistentVolume或者直接挂载网络存储来实现。用NFS要小心需要确保NFS服务端和客户端版本兼容并正确配置no_root_squash等参数否则可能出现权限错误导致镜像推送失败。数据库高可用Harbor的PostgreSQL数据库是单点。生产环境可以通过搭建PostgreSQL的主从复制集群并配合定期的逻辑备份pg_dump来保障。更高级的做法是将Harbor部署在Kubernetes上使用有状态集StatefulSet和云厂商提供的托管数据库服务。无状态组件高可用Core、Portal、Jobservice这些组件本身是无状态的。通过Kubernetes Deployment部署多个副本并前面放一个LoadBalancer如Nginx Ingress就可以轻松实现水平扩展和高可用。需要注意的是多个Jobservice实例需要连接同一个Redis来协同处理任务队列。3. Harbor日常运维核心操作详解了解了架构我们来看看每天都要打交道的基础操作。这些操作可以通过Web界面完成但对于自动化运维和CI/CD集成命令行和API更是必不可少。3.1 用户、项目与权限管理这是Harbor安全体系的基石。权限模型是项目Project - 成员Member - 角色Role的三层结构。创建项目项目是镜像的顶层容器。创建时有几个关键选项公开/私有公开项目下的镜像任何登录用户都可以拉取pull但只有项目成员才能推送push。私有项目则完全隔离。通常公共基础镜像库设为公开业务镜像库设为私有。存储配额可以限制项目能使用的镜像存储空间上限。这对于多团队共享一个Harbor实例时进行成本控制和资源分配非常有用。配额满了就无法推送新镜像。阻止潜在漏洞镜像可以设置安全策略禁止带有“中”、“高”、“致命”级别漏洞的镜像被推送到该项目。这是强制安全标准的好方法。管理用户与权限用户可以被添加到项目中并赋予以下角色之一项目管理员拥有项目的全部管理权限包括添加删除成员、配置Webhook、扫描策略等。维护者可以推送和拉取镜像删除镜像和Helm Chart但不能管理成员。开发者可以推送和拉取镜像。访客只能拉取镜像对于私有项目。限制访客在较新版本中引入权限比访客更小通常只能拉取特定标签的镜像。实操心得不要滥用“项目管理员”角色。建议为每个业务线或团队创建一个专门的“机器人”用户Service Account这个用户只拥有对应项目的“开发者”或“维护者”权限用于CI/CD流水线自动推送镜像。团队的负责人可以作为“项目管理员”。绝对避免使用全局管理员账户去进行日常的镜像推送操作。机器人账户Robot Account这是比普通用户更适合自动化场景的凭证。你可以为某个项目创建一个机器人账户并精细指定它的权限比如只能推送dev-*标签的镜像或者只能拉取。机器人账户的令牌Token是长期有效的也可以设置过期时间并且可以随时吊销比使用个人密码安全得多。3.2 镜像的推送、拉取与清理这是最频繁的操作但里面也有不少细节。推送镜像# 1. 登录到你的Harbor实例 docker login myharbor.com -u username -p password # 2. 给本地镜像打上符合Harbor规范的标签 # 格式Harbor地址/项目名/镜像名[:标签] docker tag nginx:latest myharbor.com/my-project/nginx:latest # 3. 推送镜像 docker push myharbor.com/my-project/nginx:latest常见问题推送失败报错“denied: requested access to the resource is denied”。99%的情况是用户没有登录或登录过期docker login。用户没有目标项目的推送权限。镜像标签中的“项目名”拼写错误或者该项目不存在。拉取镜像docker pull myharbor.com/my-project/nginx:latest对于私有项目同样需要先docker login。在Kubernetes中拉取私有镜像需要创建imagePullSecrets这个Secret的内容就是通过docker login生成的~/.docker/config.json文件。镜像清理与垃圾回收 镜像在Harbor中是通过“标签”来管理的。当你推送一个nginx:latest时实际上创建了一个指向某个镜像摘要Digest的标签。如果你重新构建并推送了新的nginx:latest旧的镜像层并不会被立即删除因为它的摘要还在只是没有标签指向它了。这些“无标签的镜像”就是存储空间的浪费。手动删除在Web界面可以删除单个标签。删除标签后其对应的镜像层就变成了“无标签镜像”。自动清理策略可以配置项目级的策略自动清理早于X天的无标签镜像或者只保留最近Y个版本的标签。这在开发环境非常有用。垃圾回收Garbage Collection, GC这是真正从物理磁盘上删除“无标签镜像”数据的操作。GC是一个需要谨慎对待的操作GC期间Registry会进入只读模式无法推送镜像。所以一定要在业务低峰期进行。GC不会删除任何还有标签引用的镜像层所以是安全的。执行GC前建议先通过“存储使用情况”页面或API查看有多少可回收空间。在Harbor 2.0版本中GC已经做得比较完善通常通过Web界面一键触发即可。3.3 镜像安全扫描与策略安全是Harbor的重头戏。它通过与漏洞扫描器集成来实现。扫描器集成Harbor默认内置或支持Trivy、Clair等扫描器。你需要先在“系统管理”-“漏洞扫描”中配置并设置一个为默认扫描器。手动与自动扫描可以对单个镜像或整个项目手动触发扫描。更推荐配置自动扫描在项目配置中可以设置“在推送时自动扫描镜像”。这样每一张新推送的镜像都会立即接受安全检查。阻止策略这是将扫描结果转化为强制安全门禁的关键。在项目配置中可以创建“阻止策略”。例如你可以设置“阻止严重性为‘高’或‘致命’的漏洞镜像被推送”。当CI/CD流水线尝试推送一个包含高危漏洞的镜像时Harbor会直接拒绝这次推送并在日志中返回具体的漏洞信息。这迫使开发团队必须在构建阶段就修复安全问题。CVE例外列表有时候某个已知漏洞在你的特定环境下确实不可修复或没有影响例如漏洞存在于一个你根本不使用的组件里。你可以将这个CVE ID添加到项目的“例外列表”中扫描器在评估策略时会忽略它避免误拦。3.4 镜像复制功能深入复制功能用于在多个Harbor实例比如北京和上海数据中心或者开发、测试、生产环境之间同步镜像。复制模式推送模式从当前Harbor源复制到另一个Harbor目标。你在这个Harbor上配置一个“目标”并创建复制规则。拉取模式从另一个Harbor源拉取镜像到当前Harbor目标。需要在当前Harbor上配置一个“源”。我个人的经验是通常采用“推送模式”由核心的、权威的Harbor实例比如总部的生产库向边缘实例同步。这样权限管理和策略控制更集中。创建复制规则规则非常灵活。资源过滤器可以按项目名、仓库名、标签名进行过滤。支持通配符*。例如你可以设置只复制production/*项目下标签为release-*的镜像。触发模式事件驱动一旦有镜像被推送或删除立即触发复制。适合对同步实时性要求高的场景。定时每天凌晨同步一次。适合跨地域带宽有限或对实时性要求不高的场景。手动在需要时手动触发。覆盖如果目标仓库已存在同名标签是否覆盖。对于生产环境的同步通常选择覆盖确保目标端与源端一致。网络与性能优化如果两个Harbor实例跨地域网络延迟和带宽可能成为瓶颈。确保它们之间的网络连通性良好。复制大镜像几个GB时可能会超时。可以适当调整Harbor Jobservice组件中关于复制任务的超时时间配置在jobservice的配置文件中。镜像复制走的是Harbor的Jobservice它会从源Registry拉取镜像层再推送到目标Registry。这意味着它会消耗源和目标Harbor实例的流量和计算资源。大量复制时需监控资源使用情况。4. 基于API与命令行的高级管理Web界面适合手动操作但自动化运维必须依赖API和命令行工具。4.1 Harbor REST API使用Harbor提供了完整的Swagger API文档访问https://your-harbor/swagger-ui即可查看。使用API前需要先获取令牌。基础认证与使用# 1. 获取访问令牌 (以V2 API为例) # 使用基本认证获取一个短期有效的JWT token TOKEN$(curl -s -k -u admin:Harbor12345 -X POST https://myharbor.com/api/v2.0/users/login | jq -r .token) # 或者使用机器人账户的令牌更安全 # TOKENrobot$project-nameaccount-name:your-robot-token # 2. 使用令牌调用API例如列出所有项目 curl -s -k -H Authorization: Bearer $TOKEN https://myharbor.com/api/v2.0/projects | jq .常用API场景批量操作比如批量给所有项目设置存储配额批量删除过期标签。集成到CI/CD在Pipeline中通过API检查镜像扫描结果是否通过不通过则失败。信息收集与报表定期拉取所有项目的镜像列表、漏洞统计生成安全报告。动态创建机器人账户为每个新的CI流水线动态创建临时权限的机器人账户流水线结束后自动删除。4.2 使用Harbor命令行客户端Harbor CLI除了直接调用API还可以使用官方社区维护的Harbor命令行客户端helm和harbor-cli后者功能更专注于Harbor资源管理。这里以harbor命令为例需单独安装# 配置客户端连接 harbor config set-endpoint https://myharbor.com harbor config set-username admin harbor config set-password Harbor12345 # 使用命令操作例如列出项目 harbor project ls # 创建一个新项目 harbor project create --name new-project --public false --storage-limit 10GiB # 推送镜像 (harbor-cli通常用于管理元数据镜像推送仍用docker命令) # 但可以用于操作标签如删除旧标签 harbor artifact delete myharbor.com/new-project/nginx:old-tag注意事项命令行工具的本质也是封装了API调用其稳定性和功能完整性取决于工具本身的开发进度。对于生产环境的复杂操作我仍然倾向于自己编写调用API的脚本可控性更强。5. 生产环境部署与故障排查实录5.1 基于Kubernetes的Harbor高可用部署要点现在越来越多的团队选择用Helm Chart在Kubernetes上部署Harbor这能天然获得高可用和弹性伸缩的好处。Helm部署流程# 添加Harbor chart仓库 helm repo add harbor https://helm.goharbor.io helm repo update # 下载values.yaml进行定制 helm show values harbor/harbor harbor-values.yaml # 关键配置修改在harbor-values.yaml中 # - externalURL: https://harbor.mycompany.com # 你的访问地址 # - persistence.persistentVolumeClaim.registry.size: 500Gi # 镜像存储大小 # - persistence.persistentVolumeClaim.registry.storageClass: ceph-rbd # 使用Ceph RBD # - expose.ingress.hosts.core: harbor.mycompany.com # 配置Ingress # - expose.tls.secretName: harbor-tls-secret # TLS证书Secret # - harborAdminPassword: YourStrongAdminPassword123 # - database.type: external # 如果使用外部数据库 # - database.external.host: my-postgresql-svc # - redis.type: external # 如果使用外部Redis # 安装 helm install my-harbor harbor/harbor -f harbor-values.yaml -n harbor --create-namespace关键配置与避坑指南外部数据库和Redis对于生产环境强烈建议使用云厂商的托管数据库服务如RDS和Redis服务。这省去了自己维护数据库高可用的麻烦。配置时注意网络连通性VPC内网或白名单和版本兼容性。Ingress配置Harbor Chart支持多种Ingress ControllerNginx, Contour等。确保你的Ingress Controller已正确安装并配置好TLS证书。证书可以通过Cert-Manager自动申请也可以手动创建Secret挂载。存储类选择镜像存储的PVC一定要用支持ReadWriteMany访问模式的存储类比如CephFS、NFS或者云厂商提供的文件存储服务。因为多个PodJobservice, Registry可能需要同时读写这些数据。误用ReadWriteOnce模式是导致Pod启动失败的常见原因。资源请求与限制别忘了给Harbor的各个组件尤其是Core、Jobservice、Registry设置合适的CPU和内存的requests/limits。特别是当镜像很大或并发任务很多时Jobservice会比较吃资源。5.2 常见问题与排查技巧即使部署顺利运维过程中也难免遇到问题。这里记录几个我踩过的坑和排查思路。问题现象可能原因排查步骤与解决方案docker push失败报错http: server gave HTTP response to HTTPS clientDocker客户端试图用HTTP协议与一个配置了HTTPS的Registry通信或反之。1. 检查Harbor的externalURL配置是否为https://开头。2. 在Docker客户端对于自签名证书的Harbor需要在/etc/docker/daemon.json中添加{ insecure-registries: [myharbor.com] }并重启docker。生产环境强烈建议配置可信的CA证书避免使用insecure-registries。Web界面可以登录但docker login失败1. Harbor的Core服务认证问题。2. 网络或代理问题。3. 客户端Docker版本与Harbor不兼容。1. 查看Harbor Core服务的日志docker logs harbor-core。2. 尝试用curl -u username:password https://myharbor.com/api/v2.0/users/login看API是否正常返回token。3. 检查客户端与Harbor服务器之间的网络是否有防火墙拦截或代理设置错误。镜像扫描任务一直处于“Pending”状态1. 漏洞扫描器服务未正常运行。2. Jobservice没有可用的Worker来执行扫描任务。3. 扫描器适配器配置错误。1. 检查trivy-adapter或clair-adapter的Pod是否Running且健康。2. 查看Jobservice日志看是否有任务分配错误。3. 在Harbor Web界面的“系统管理”-“漏洞扫描”中测试扫描器连接是否正常。镜像复制任务失败报网络错误1. 源和目标Harbor之间的网络不通。2. 复制规则中配置的端点URL或证书错误。3. 目标仓库存储空间不足。1. 在Jobservice的Pod内用curl或wget测试是否能访问对端Harbor的API和Registry服务。2. 检查复制规则中配置的端点地址、用户名密码或访问密钥是否正确。3. 检查目标Harbor的存储使用情况。Harbor Web界面访问非常慢1. 前端资源JS/CSS加载慢。2. 后端API响应慢。3. 数据库查询慢。1. 浏览器开发者工具查看网络请求卡在哪个环节。2. 检查Core、Database的Pod资源使用率CPU、内存是否过高。3. 检查数据库连接池和慢查询日志。对于数据量大的Harbor实例定期清理过期的操作日志表如harbor.audit_log能有效提升性能。执行垃圾回收GC后磁盘空间未释放1. Registry容器内文件已删除但宿主机文件系统未释放常见于容器使用overlay2存储驱动。2. 有其它进程如日志、备份正在占用已删除的文件。1. 在Registry容器内查看存储目录大小确认已减小。2. 在宿主机上使用lsof | grep deleted命令查找是否还有进程持有已删除文件的句柄。通常重启Registry容器可以解决但会导致服务短暂中断。3.根本解决确保Harbor使用的存储卷是独立挂载的而不是直接使用Docker容器的本地存储。一个深度排查案例有一次用户报告推送镜像偶尔超时。从Core日志看认证和授权都很快问题出在客户端与Registry的数据传输阶段。我们排查了网络没有问题。最后发现是Registry Pod所在节点的磁盘I/O等待时间非常高。原因是该节点上同时运行了多个高I/O的数据库Pod与Registry争抢资源。解决方案是将Harbor的Registry组件通过Kubernetes的节点选择器nodeSelector或污点容忍Toleration调度到I/O负载较低的专用节点上问题得以解决。这个案例说明对于Harbor这种有状态服务底层基础设施的性能监控同样重要。
