Harbor私有镜像仓库离线部署实战：从安装配置到权限管理与运维调优-北京尧图网络

1. 为什么私有化镜像仓库是团队协作的必经之路做过容器化部署的人大概都有过这样的经历本地docker build出来的镜像推到公共仓库吧担心内部业务代码和配置泄露不推吧测试环境和生产环境又没法统一拉取。团队规模小的时候靠一台机器docker save导出 tar 包再scp到另一台机器docker load勉强能撑一阵子。但只要超过三个人协作这套土办法立刻崩盘——版本对不上、tar 包满天飞、谁改了哪个镜像根本说不清。私有镜像仓库就是来解决这个问题的。它本质上是一个自建的、只对内部网络开放的镜像存储与分发中心具备权限控制、镜像版本管理、漏洞扫描、存储配额等能力。而 Harbor 是目前在私有化场景里落地最广的开源方案之一它基于 Docker Registry 做了大量企业级增强把认证、授权、审计、复制、扫描这些能力都集成到了一个 Web 控制台里。这篇文章面向的是需要在内网环境搭建镜像仓库的运维人员、后端开发者和 DevOps 工程师。不管你是第一次接触 Harbor还是之前装过但被一堆配置项绕晕了我都会从实际落地的角度把安装、配置、踩坑、调优这条链路完整讲一遍。文中涉及的操作步骤和参数都是基于常见生产实践总结出来的你可以直接对照着做。需要提前说明的是Harbor 的部署方式有好几种在线安装、离线安装、Helm 部署到 K8s 集群等。本文主要围绕离线安装包 Docker Compose这条最经典、最容易在单机或小集群内网落地的路线展开因为它在没有外网的环境里最省心依赖最少出问题也最好排查。2. 部署前的环境盘点与依赖确认2.1 硬件与操作系统的底线要求Harbor 对资源的要求不算高但也不能太寒酸。我见过有人拿 1 核 1G 的机器去装结果docker-compose up之后容器反复重启查日志发现是 PostgreSQL 和 Redis 抢内存。所以下面这套配置建议当作底线资源项最低配置推荐配置说明CPU2 核4 核镜像扫描和复制任务比较吃 CPU内存4 GB8 GB低于 4G 时数据库容易 OOM磁盘40 GB100 GB 以上取决于镜像数量和保留策略操作系统主流 Linux 发行版主流 Linux 发行版内核版本建议 4.x 以上磁盘这块要特别提醒一句Harbor 默认把镜像数据存在/data目录下如果你系统盘空间有限最好在安装前就把一块独立的数据盘挂载到/data否则后期镜像越堆越多迁移存储目录会很麻烦。我个人的习惯是安装前先df -h看一眼根分区剩余空间低于 50G 就先处理存储再动手。2.2 Docker 与 Docker Compose 的版本匹配Harbor 的离线安装包依赖 Docker 和 Docker Compose 来编排容器。这里有个很容易被忽略的点Docker Compose 的版本兼容性。Harbor 2.x 系列对 Compose 的版本有明确要求用太老的docker-compose比如 1.18 以下会在解析docker-compose.yml时报语法错误。安装 Docker 的步骤这里不展开主流发行版的官方文档都很清楚。重点确认两件事docker --version docker-compose --version前者建议 20.10 以上后者建议 1.28 以上。如果你的系统里docker-compose是通过 pip 装的旧版本建议卸载后换成官方二进制包避免各种奇怪的兼容问题。提示有些发行版自带的docker-compose是 Python 版本性能和兼容性都不如 Go 版本的二进制包。生产环境建议直接用官方发布的二进制文件放到/usr/local/bin/下。2.3 网络与端口规划Harbor 默认会占用几个端口安装前必须确认这些端口没有被占用否则容器起不来。核心端口如下80Harbor 的 HTTP 访问端口Web 控制台和镜像拉取都走这里443HTTPS 访问端口配置证书后使用4443Harbor 内部组件通信用的端口部分版本如果你打算用域名访问还需要提前规划好 DNS 解析或者在本机/etc/hosts里加一条记录。比如计划用harbor.internal.example这个域名那就要确保所有需要拉取镜像的机器都能解析到它。这里有个实操经验不要用 IP 直接访问 Harbor虽然技术上可行但 Docker 客户端在推送镜像时对仓库地址的格式有要求用域名会省去很多麻烦。而且后期如果要做 HTTPS 证书域名也是必须的。3. 离线安装包的获取与配置文件的定制3.1 离线包的结构与选择逻辑Harbor 的离线安装包在官方发布页可以下载文件名通常形如harbor-offline-installer-vX.Y.Z.tgz。选版本的时候有个原则不要盲目追最新版。新版本可能引入了新的依赖或者配置项变更而你的内网环境未必能及时跟上。我一般建议选比最新版落后一个小版本的稳定版社区踩坑的人多遇到问题也容易搜到解决方案。下载完成后把压缩包传到目标服务器上解压tar -xzf harbor-offline-installer-vX.Y.Z.tgz -C /opt/ cd /opt/harbor解压后你会看到几个关键文件harbor.yml.tmpl配置模板文件需要复制成harbor.yml后修改install.sh安装脚本prepare环境准备脚本会生成docker-compose.ymlcommon.sh公共函数库3.2 harbor.yml 里必须改的几个字段把模板复制成正式配置cp harbor.yml.tmpl harbor.yml然后打开harbor.yml下面这几个字段是必须根据你的环境调整的hostname这是最关键的配置。填你的域名或者主机名比如harbor.internal.example。注意不要带http://或https://前缀也不要带端口号。http / https如果暂时没有证书先把https段整段注释掉只保留http段并设置端口。等后续配好证书再启用 HTTPS。harbor_admin_password管理员初始密码。默认是Harbor12345生产环境务必改掉。密码复杂度建议至少包含大小写字母、数字和特殊字符。data_volume镜像数据存储路径默认/data。如果你挂载了独立数据盘这里改成对应的挂载点。database.password内部数据库密码同样建议修改不要用默认值。下面是一个精简后的配置示例只保留了核心字段hostname: harbor.internal.example http: port: 80 harbor_admin_password: YourStrongPassword123! data_volume: /data database: password: YourDBPassword456! max_idle_conns: 100 max_open_conns: 9003.3 存储驱动的选择与注意事项Harbor 默认使用本地文件系统存储镜像这对单机部署来说完全够用。但如果你计划后续扩展到多节点或者对数据可靠性有更高要求可以考虑对接对象存储。不过在初次安装阶段我强烈建议先用本地存储把整套流程跑通确认没问题后再考虑迁移。本地存储的配置在harbor.yml里对应的是data_volume字段不需要额外指定存储驱动。如果你确实要用对象存储配置段会复杂不少涉及 access key、secret key、bucket 名称等这些信息一旦填错Harbor 启动时会直接报错退出。注意修改harbor.yml后每次重新部署都需要先执行./prepare重新生成docker-compose.yml否则配置不会生效。这是新手最容易漏掉的一步。4. 执行安装与验证服务状态4.1 安装脚本到底做了什么很多人直接跑./install.sh就完事了但搞清楚它背后干了什么出问题时才能快速定位。这个脚本的执行链路大致是这样的检查harbor.yml是否存在不存在就报错退出调用prepare脚本根据配置生成docker-compose.yml和各个组件的配置文件拉取离线包场景下是加载所需的 Docker 镜像通过docker-compose up -d启动所有容器等待各组件就绪输出访问地址和默认账号信息整个过程涉及的核心容器包括harbor-core主服务、harbor-portalWeb 前端、harbor-dbPostgreSQL、harbor-redis缓存、harbor-registry镜像存储、harbor-jobservice任务服务、nginx反向代理等。任何一个容器起不来整个 Harbor 都可能不可用。4.2 安装过程中的常见报错与处理报错一端口被占用Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use这说明 80 端口被别的服务占了。用ss -tlnp | grep :80查一下是谁占的要么停掉那个服务要么改 Harbor 的 HTTP 端口。报错二data_volume 目录权限不足mkdir /data: permission denied如果你把data_volume设成了一个需要 root 权限才能写的目录而 Docker 守护进程以非 root 用户运行就会报这个错。解决办法是提前创建目录并设置合适的权限mkdir -p /data chmod 755 /data报错三镜像加载失败离线包里的镜像文件如果传输过程中损坏加载时会报校验失败。重新下载离线包并核对 MD5 值即可。4.3 验证安装是否成功安装脚本跑完后用下面几条命令确认服务状态cd /opt/harbor docker-compose ps正常情况下所有容器的状态都应该是Up或healthy。如果有容器显示Exit或Restarting用docker-compose logs 服务名查看具体日志。接着在浏览器里访问http://harbor.internal.example应该能看到 Harbor 的登录页面。用harbor.yml里设置的管理员账号和密码登录能进控制台就说明核心服务没问题了。最后做一次端到端的验证在另一台能访问 Harbor 的机器上用 Docker 客户端登录并推送一个测试镜像。docker login harbor.internal.example docker pull alpine:latest docker tag alpine:latest harbor.internal.example/library/alpine:test docker push harbor.internal.example/library/alpine:test推送成功后在 Harbor 控制台的library项目下能看到这个镜像整个链路就算通了。5. 项目与用户权限体系的落地配置5.1 项目Project的划分逻辑Harbor 里的“项目”是镜像的逻辑隔离单元类似于代码仓库里的组织或命名空间。镜像的完整地址格式是harbor域名/项目名/镜像名:标签。所以项目怎么划分直接决定了后续的权限管理和镜像组织方式。常见的划分策略有两种按团队划分每个开发团队一个项目比如team-alpha、team-beta。适合组织架构清晰、团队间镜像不共享的场景。按环境划分dev、test、prod各一个项目。适合需要严格控制镜像晋级流程的场景。我个人的建议是按团队划分项目在项目内部用镜像标签区分环境。比如team-alpha/webapp:dev、team-alpha/webapp:prod。这样权限管理更简单一个团队的人只需要对一个项目有读写权限。创建项目的入口在控制台的Projects菜单下点New Project即可。创建时有两个选项值得注意访问级别公开项目任何人可拉取私有项目只有授权用户可访问。内部业务镜像一律选私有。镜像代理如果 Harbor 需要从外部仓库拉取镜像并缓存可以开启代理缓存功能。内网环境一般用不上。5.2 用户角色与权限粒度Harbor 的权限模型是“用户项目角色”三层结构。角色有五种角色权限范围项目管理员管理项目配置、成员、镜像可删除项目维护人员推送、拉取、删除镜像管理标签和扫描开发者推送、拉取镜像访客只读只能拉取受限访客只能拉取指定仓库的镜像实际配置时最常见的做法是给 CI/CD 流水线用的账号分配“开发者”角色只允许推送给测试和运维人员分配“访客”角色只允许拉取项目负责人分配“项目管理员”。用户创建可以在控制台的Administration - Users里手动添加也可以通过 LDAP/AD 对接。如果团队规模不大手动管理完全够用超过几十人的话建议对接企业已有的目录服务省去逐个维护的麻烦。5.3 机器人账号在自动化流水线中的使用在 CI/CD 场景里用真人账号去登录 Harbor 推送镜像是不合适的——密码会暴露在流水线配置里人员离职后还要改密码。Harbor 提供了“机器人账号”Robot Account机制来解决这个问题。机器人账号是绑定到项目上的每个账号有一组独立的用户名和 Token可以精确控制权限范围。创建路径是进入项目 -Robot Accounts-New Robot Account。创建时可以勾选这个账号能执行的操作比如只勾选push和pull。创建完成后Token 只会显示一次务必当场保存。后续在流水线里这样使用docker login harbor.internal.example -u robot$项目名账号名 -p 生成的Token提示机器人账号的 Token 如果泄露可以在控制台里直接禁用或重新生成不会影响其他账号。这是它比共用真人账号安全得多的核心原因。6. HTTPS 证书配置与客户端信任链打通6.1 为什么必须上 HTTPS用 HTTP 访问 Harbor 在功能上没问题但 Docker 客户端默认只信任 HTTPS 仓库。如果你坚持用 HTTP就需要在每一台客户端的 Docker 配置里加insecure-registries这在机器数量少的时候还行一旦规模上去就是运维噩梦。更重要的是镜像推送和拉取过程中会传输认证凭据HTTP 明文传输存在被截获的风险。所以只要条件允许都应该配置 HTTPS。6.2 证书的获取与放置证书来源有两种一是从正规 CA 机构申请适合有公网域名的场景二是自签名证书适合纯内网环境。内网场景下自签名证书完全够用只是需要把根证书分发到所有客户端。生成自签名证书的步骤大致如下openssl req -newkey rsa:4096 -nodes -sha256 \ -keyout harbor.key -x509 -days 3650 \ -out harbor.crt \ -subj /CCN/STBeijing/LBeijing/OInternal/CNharbor.internal.example \ -addext subjectAltNameDNS:harbor.internal.example生成后得到harbor.key和harbor.crt两个文件。把它们放到一个固定目录比如/opt/harbor/certs/然后在harbor.yml里配置https: port: 443 certificate: /opt/harbor/certs/harbor.crt private_key: /opt/harbor/certs/harbor.key配置完成后重新执行./prepare和docker-compose up -d让配置生效。6.3 客户端信任自签名证书的完整操作服务端配好 HTTPS 只是第一步客户端如果不信任这个自签名证书docker login依然会报x509: certificate signed by unknown authority。解决办法是把harbor.crt分发到每台客户端的系统信任目录里。以主流 Linux 发行版为例sudo cp harbor.crt /usr/local/share/ca-certificates/harbor.crt sudo update-ca-certificates sudo systemctl restart docker注意最后一步重启 Docker 是必须的因为 Docker 守护进程在启动时加载系统证书链不重启不会生效。这个坑我踩过不止一次——证书明明装好了docker login还是报错折腾半天才发现是忘了重启 Docker。验证证书是否被信任curl -v https://harbor.internal.example如果输出里没有证书相关的报错并且能看到 Harbor 的响应内容就说明信任链打通了。7. 日常运维中的高频问题与调优思路7.1 磁盘空间告警的处理策略Harbor 跑一段时间后最常见的告警就是磁盘空间不足。镜像层是累积存储的同一个镜像的不同版本如果共享基础层实际占用会比想象中小但长期不清理依然会撑爆磁盘。处理策略分三步第一步配置保留策略。在项目的Policy标签下可以设置“保留最近 N 个标签”或“保留最近 N 天”的规则。Harbor 会定期执行清理任务把不满足保留条件的镜像标记为可删除。第二步执行垃圾回收。保留策略只是标记删除实际磁盘空间不会立即释放。需要在Administration - Garbage Collection里手动触发垃圾回收任务或者在配置里设置定时执行。垃圾回收会扫描所有镜像层把没有被任何镜像引用的层真正删掉。第三步监控磁盘水位。建议对/data目录做磁盘使用率监控超过 80% 就告警。不要等到 100% 才处理那时候 Harbor 可能已经无法写入新镜像了。注意垃圾回收任务执行期间Harbor 会进入只读模式无法推送新镜像。所以建议把执行时间安排在业务低峰期比如凌晨。7.2 镜像扫描与漏洞管理Harbor 集成了 Trivy 作为默认的镜像扫描器可以自动扫描镜像里的操作系统包和语言依赖漏洞。开启方式是在项目配置里勾选“自动扫描”这样每次推送镜像后都会自动触发扫描。扫描结果会在镜像详情页里展示按严重程度分为 Critical、High、Medium、Low 四级。实际使用中我的建议是Critical 和 High 级别的漏洞必须处理要么升级基础镜像要么替换有问题的依赖。Medium 和 Low 可以定期批量处理不必每次推送都卡。可以在项目配置里设置“阻止推送含严重漏洞的镜像”从源头卡住有问题的镜像进入仓库。不过要提醒一句扫描结果里很多漏洞来自基础镜像本身比如某个老版本的 Alpine 或 Ubuntu。这种情况下升级基础镜像版本往往能一次性解决大量漏洞比逐个修依赖效率高得多。7.3 日志排查的切入点Harbor 出问题时日志是最直接的线索。核心组件的日志可以通过docker-compose logs查看cd /opt/harbor docker-compose logs -f harbor-core docker-compose logs -f harbor-registry docker-compose logs -f nginx常见的排查路径登录失败先看harbor-core日志通常是数据库连接问题或密码错误。推送镜像报 500看harbor-registry日志多半是存储目录权限或磁盘空间问题。页面打不开看nginx日志检查反向代理配置和证书是否正常加载。任务卡住不执行看harbor-jobservice日志可能是 Redis 连接异常。日志文件本身也会占用磁盘空间如果 Harbor 运行时间长了/var/log或者容器日志目录可能会很大。可以在docker-compose.yml里配置日志轮转限制单个日志文件的大小和保留数量。7.4 备份与恢复的基本思路Harbor 的备份分两部分配置数据和镜像数据。配置数据存在 PostgreSQL 数据库里包括用户、项目、权限、策略等。备份方式是定期导出数据库docker exec harbor-db pg_dump -U postgres registry harbor_backup_$(date %Y%m%d).sql镜像数据存在data_volume指定的目录下直接对整个目录做快照或增量备份即可。如果镜像数量很大全量备份成本高可以考虑只备份数据库镜像数据依赖存储层的快照能力。恢复的时候先恢复数据库再把镜像数据目录挂回去重新执行./install.sh即可。需要注意的是数据库版本和 Harbor 版本要匹配跨大版本恢复可能会失败。8. 我在多次部署中总结的几条实操心得第一安装前一定要把harbor.yml里的默认密码全部改掉。我见过不止一个环境用着默认的Harbor12345而且 Harbor 直接暴露在内网里任何能访问到的人都能以管理员身份登录。这个风险完全没必要承担。第二离线包的版本和 Docker 版本要匹配。Harbor 2.x 的某些版本对 Docker 的最低版本有要求用太老的 Docker 会在启动容器时报 API 版本不兼容。安装前花两分钟看一眼官方文档的兼容性说明能省掉后面几个小时的排查。第三./prepare这一步不能省。每次改完harbor.yml都必须重新执行./prepare再docker-compose up -d。直接改docker-compose.yml是没用的因为下次prepare会把它覆盖掉。第四客户端信任证书后记得重启 Docker。这个坑前面提过但值得再强调一次因为它太容易被忽略了。第五垃圾回收要定期做但不要在业务高峰期做。回收期间 Harbor 只读如果有流水线正在推送镜像会直接失败。设置定时任务时避开 CI/CD 的高峰时段。第六机器人账号的 Token 要当密码一样管理。虽然可以重新生成但泄露期间的风险是实实在在的。建议把 Token 存在流水线的密钥管理里不要硬编码在脚本中。这套 Harbor 的安装配置流程从环境准备到权限体系再到日常运维基本覆盖了内网私有镜像仓库落地的完整链路。实际部署时环境和需求千差万别遇到本文没覆盖到的问题优先看容器日志大部分答案都在里面。

Harbor私有镜像仓库离线部署实战：从安装配置到权限管理与运维调优

相关推荐

燃烧系统数字孪生：从离线CFD到在线替代模型的工程落地

ComfyUI+WorkBuddy：构建本地批量出图自动化流水线实战

AI漫剧出海全链路实战：从剧本本地化到批量生成与变现

更多资讯

PyTorch线性回归实战：从数据构造到训练闭环

REA分析框架：识别、评估、执行三步法提升效率

AI Agent记忆持久化实战：FileSystem中间件如何实现跨会话状态恢复

数据安全与隐私保护：探索合规数据工具与实践

AI知识库实战：从材料筛选到提问，打造高质量个人知识底座

Flutter for OpenHarmony表单验证实战：二手置换App开发踩坑与模块化设计

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？