Harbor v2.5.0离线安装实战：CentOS 7内网镜像仓库部署指南

简介Harbor v2.5.0-rc1 离线安装包面向需要在内网、离线或安全隔离环境中搭建容器镜像仓库的运维工程师与平台管理员解决因无法访问公网镜像源而导致的 Harbor 部署困难问题。安装包内含6个文件以 Shell 脚本、配置文件模板、License 许可和离线镜像归档等类型为主整体大小约623.92MB。离线镜像归档已预置 Harbor 各组件镜像配合脚本可依次完成参数生成、配置预处理、镜像加载与容器编排启动帮助使用者在无外网条件下快速拉起一套可用服务。已有256人浏览学习适合具备 Docker 与 docker-compose 基础、需要快速交付私有镜像仓库的中高级技术人员。借助这套资源团队不必自行拼装镜像或编写杂乱的配置即可获得完整的离线安装素材同时通过阅读其中的配置模板与脚本逻辑也能加深对 Harbor 内部组件、端口和存储路径设计的理解为后期升级和排错提供依据。1. 拿到 harbor-offline-installer 先别急着解压它在解决什么问题在一个不能访问外网的 CentOS 7 环境里想搭一个能 push / pull 镜像的私有容器仓库最常见的起点就是同事递过来一个文件名字叫 harbor-offline-installer-v2.5.0-rc1.tgz。这个离线安装包解决的核心问题是没有外网、没有 Docker Hub 连通性、也没有在线 Yum 源的情况下仍然能把 Harbor v2.5.0-rc1 单机实例完整装起来。它把 Harbor 的组件镜像、配置模板、安装脚本打包进一个 tgz 里配合基础环境里的 Docker 与 Docker Compose就能完成从零到可用的镜像仓库搭建。这个包适合三类人第一类是做私有化交付的实施工程师客户机房通常隔离外网第二类是需要在 CentOS 7 上搭建内网镜像仓库的运维第三类是被公网镜像限速逼到必须自建仓库的开发团队。文章后续会讲清楚安装包内部结构、离线环境怎么准备 Docker以及安装完成后最容易出现的翻车点——这些点我基本都踩过一遍照着操作可以少走很多弯路。2. 离线包里的三个关键件以及 v2.5.0-rc1 的代际变化2.1 解压后你看到的是这三类文件拿到 harbor-offline-installer-v2.5.0-rc1.tgz 之后先在服务器上做一次解压。这里的路径建议单独建一个安装目录不要把内容散在根目录或 /root 下后续维护和查找会方便很多。下面这段命令是我在新环境里的固定操作mkdir -p /data/install mv harbor-offline-installer-v2.5.0-rc1.tgz /data/install/ cd /data/install tar -xzvf harbor-offline-installer-v2.5.0-rc1.tgz cd harbor ls -lh参数说明-xzvf 中 x 是解压z 表示通过 gzip 解压v 会打印过程文件列表f 指定归档文件。解压之后进入 harbor 目录用 ls -lh 查看文件大小和权限。正常情况下你会看到三类关键文件一个体积很大的镜像包名字类似 harbor.v2.5.0-rc1.tar.gz这是 Harbor 核心组件的 Docker 镜像导出一个 harbor.yml.tmpl 配置模板install.sh 安装时会读取它生成实际配置还有一个 common.sh它是安装脚本引用的公共函数库。这里需要提醒一个容易误解的地方deb 包里常见的 yum 依赖和编译缓存在这个 tgz 里都不存在Docker 和 Docker Compose 必须由你提前准备好。install.sh 做的事情可以概括为校验 docker 和 docker-compose 版本、把 harbor.v2.5.0-rc1.tar.gz 通过 docker load 导入本地镜像库、基于 harbor.yml 生成 docker-compose.yml最后用 docker-compose up -d 启动全部服务。理解了这三类文件的角色后面遇到报错就能快速判断是哪个环节出了问题。2.2 v2.5.0 和旧版本直观差别Nginx 容器不见了如果你之前部署过 Harbor v1.x 或 v2.0可能会习惯用docker ps看到一个 nginx 容器它负责对外接收 HTTP/HTTPS 流量并转发给 core、registry 等后端服务。但在 v2.5.0 这个代际里Harbor 把 Nginx 的职责合并进了 core 组件对外端口直接由 core 承载安装完成后容器列表里看不到 nginx 是正常现象不是故障。这个变化带来的一个实际影响是排查网络问题时不要再去 container 列表里找 nginx而要从 core 的日志里看请求转发和证书配置相关报错。另一个影响是 harbor.yml 里 http 和 https 的端口配置直接绑定到 core 组件修改端口后要重新执行 install.sh 而不是单独重启某个容器。对于从旧版本迁移过来的用户建议把这套新架构当作黑匣子重新验证一遍端口映射和访问日志不要沿用旧的处理习惯。2.3 用一张表定死环境基线CentOS 7 与 Docker Compose 版本离线安装最怕依赖缺失所以环境基线必须在动手前确认。CentOS 7 是内网存量大户内核版本 3.10Docker 选 20.10.x 兼容性最好能正常使用 overlay2 存储驱动。Docker Compose 这里有个关键版本分水岭Harbor v2.5.0 的安装脚本会检查 compose 的解析能力如果版本低于 1.29.2 或者不是 v2 版本会在开头直接报错退出。环境项最低要求说明操作系统CentOS 7.6 及以上7.x 内核 3.10需确认 iptables 模块完整CPU / 内存4 核 8G 起步同时跑 core、registry、数据库和 Redis数据盘独立分区 100G 以上挂载到 /data 之类路径避免根分区被打满Docker20.10.x旧版本可能不支持 Harbor 用到的配置语法Docker Compose1.29.2 或 v2.x低于此版本时 install.sh 直接终止网络端口80 / 443 可用与现有 nginx 或 httpd 冲突时先停掉旧服务这个表建议贴在安装文档里每次开工前先照表核对。尤其是 Docker Compose 版本这一点很多人习惯用 yum 装一个老版本 docker-compose 就往下走结果在 install.sh 第一步就被拦下白白浪费时间。3. 在 CentOS 7 上先备好 Docker 与 Compose离线环境的最小命令集3.1 用 yumdownloader 拉全 rpm内网 localinstall 装 Docker CE离线环境装 Docker 最可靠的做法是在一台能联网且操作系统版本一致的 CentOS 7 机器上把 docker-ce 及其依赖全部拉成 rpm 文件再拷入内网。这里不要只拉 docker-ce 一个包它依赖 containerd.io、docker-ce-cli、container-selinux 等缺一个在 localinstall 时都会报依赖错误。下面给出一组可复制的命令。# 在能联网的 CentOS 7 机器上执行 yum install -y yum-utils yumdownloader --resolve docker-ce docker-ce-cli containerd.io # 把生成的 rpm 文件全部拷贝到内网机器的同一个目录 cd /path/to/rpms yum localinstall -y *.rpm systemctl enable --now dockeryumdownloader 的 --resolve 参数会连同依赖一起下载这是离线安装 Docker 的关键参数。拷进内网后yum localinstall 会从当前目录查找依赖 rpm不再请求网络源。装完 Docker 之后建议先配置 /etc/docker/daemon.json 再启动服务避免后面因为 daemon 参数反复重启。下面这个配置适合内网镜像仓库场景。{ exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 }, data-root: /var/lib/docker }注意>sudo chmod x docker-compose-linux-x86_64 sudo mv docker-compose-linux-x86_64 /usr/local/bin/docker-compose docker-compose version参数说明chmod x 是给二进制文件加执行权限mv 把它放到 PATH 路径下。docker-compose version 的输出如果你是 v2 版本会显示 “Docker Compose version v2.x.x”如果是 v1会显示 “docker-compose version 1.29.2”。install.sh 检测 compose 版本时同时兼容这两类输出格式。这里要特别强调一个辨别细节如果你在结果里看到 docker-compose 命令找不到说明 PATH 里没有 /usr/local/bin或者文件没搬到指定位置。如果看到版本号低于 1.29.2 又包含 build 字样说明系统里残留了 python 管道的旧版 compose需要先卸载并清理 /usr/bin/docker-compose 这种路径下的软链。3.3 解压安装包并预加载镜像docker load 这一步的作用把 Harbor 离线镜像包导入 Docker 是在跑 install.sh 之前最耗时的一步很多人误以为 install.sh 会自动解包其实它内部确实会尝试加载镜像但如果你手动提前加载可以更早发现磁盘空间和镜像完整性等问题。我习惯在 install.sh 之前先手动做一次 load失败时便于定位。cd /data/install/harbor docker load -i harbor.v2.5.0-rc1.tar.gz docker images | grep goharbordocker load 会把 tar 包里的镜像层展开到 Docker 的>cd /data/install/harbor cp harbor.yml.tmpl harbor.yml cp harbor.yml harbor.yml.bak编辑时最稳妥的方式是直接 vi 修改对应行但为了便于日后追溯我一般会在文件末尾追加注释块记录本次改动。下面这段是经过实践检验的最小可运行配置片段。hostname: 192.168.10.20 http: port: 80 harbor_admin_password: ChangeMe_2024 data_volume: /data/harbor database: password: postgres_StrongPwd max_idle_conns: 50 max_open_conns: 100这里的 max_idle_conns 和 max_open_conns 控制数据库连接池默认值偏保守如果团队并发推送镜像较多可以像上面这样调。注意修改完 harbor.yml 之后install.sh 会基于它生成 harbor.yml 对应的 docker-compose 配置不想覆盖手动改过的 compose 文件就不要在 harbor 目录下手动乱动 docker-compose.yml。还有一个容易漏掉的参数位置在文件末尾的 log 配置段。离线环境常常没有外部日志服务器建议把 log.level 从 info 改成 warn减少磁盘占用量。镜像仓库的日志增长速度比大多数应用都快尤其是并发 push 的时候。4.3 执行 ./install.sh 后的四步验证ps、curl、login、push配置改完直接执行 ./install.sh。这里注意不要用 bash install.sh 以外的命令脚本里可能会读取当前目录的相对路径换目录执行会出问题。整个安装过程包括重新加载镜像如果已加载会跳过、生成配置、启动容器。cd /data/install/harbor ./install.sh执行之后不要立刻 docker-compose ps先看一眼 install.sh 的输出末尾有没有成功的英文提示。常见失败场景是端口被占用或磁盘空间不足。接着按顺序做以下四步验证。docker-compose ps curl -I http://192.168.10.20 docker login 192.168.10.20 -u admin -p ChangeMe_2024 docker tag nginx:latest 192.168.10.20/library/nginx:v1 docker push 192.168.10.20/library/nginx:v1参数说明docker-compose ps 是列出当前目录下的 compose 服务状态只有结果是 Up 才继续。curl -I 用于检查 HTTP 响应头能看到 200 说明 core 已正常接收请求。docker login 使用的地址必须和 harbor.yml 里的 hostname 一致。最后 push 一个测试镜像到 library 项目能成功就说明从 UI 到 registry 的链路是通的。如果 docker login 报错 http: server gave HTTP response to HTTPS client说明 Docker 客户端访问的是 http 端口但默认启用了 TLS 校验解决办法是在 daemon.json 的 insecure-registries 里加入仓库地址再重启 Docker。这是内网环境最常出现的登录失败原因。5. 装完最容易踩的 5 个坑现象、原因、解决5.1 docker-compose 版本太老install.sh 开场就被拦现象执行 ./install.sh 后终端立即输出 Docker Compose 版本过旧或无法解析配置文件的错误脚本没有进入后续安装流程。原因Harbor v2.5.0 的 docker-compose 配置里使用了较新的字段与函数语法旧版 compose 在解析时直接失败。CentOS 7 自带的 epel 源里 docker-compose 版本停留在 1.25 左右恰好不满足要求。解决把 /usr/bin/docker-compose 或 Python 版的 docker-compose 卸载干净然后把 1.29.2 或 v2 版本的二进制放到 /usr/local/bin重新执行 docker-compose version 确认输出。注意如果存在多个 compose 副本which docker-compose 会显示实际生效路径。5.2 hostname 写成 localhostpush 的 tag 全不对现象Harbor UI 能登录但在本机 docker login localhost 也成功最终 docker push 失败报错显示仓库地址不是预期的内网 IP。原因harbor.yml 的 hostname 决定了 UI 上展示的仓库地址、registry 的返回 Location 头以及 jobservice 回调地址。写成 localhost 后核心组件之间通信和外部访问全都会指向本机回环地址。解决把 hostname 改成内网 IP 或正式域名重新 ./install.sh。这里再提醒一下修改 hostname 后原有推送记录要重新 tag不会自动转换。5.3 旧 data_volume 与新密码冲突数据库起不来现象安装完成后 database 容器一直重启docker logs 里看到 password authentication failed同时 core 也在报数据库连接失败。原因第一次安装 Harbor 时data_volume 里的 postgresql 数据目录已经用当时的 database.password 初始化过了。第二次用不同密码重新安装时数据库认证必然失败。解决如果数据不重要可以让 data_volume 目录下的 database 子目录清空再执行 ./install.sh 重新初始化。如果数据很重要必须保留旧密码或者先备份数据库再用新密码启动并执行手工 ALTER USER 变更密码。5.4 df 看着有空间docker load 却报 no space left现象docker load 大镜像包中途报 no space left on device但 df -h 显示 /data 下还有几十 G 空闲。原因docker 的>mkdir -p /data/certs cd /data/certs openssl req -newkey rsa:2048 -nodes -keyout harbor.key -x509 -days 365 -out harbor.crt生成后在 harbor.yml 里取消 https 段注释certificate 和 private_key 指向 /data/certs 下的文件同时把 http.port 注释掉再执行 ./install.sh 重建。注意 docker 客户端那边也要把仓库地址改成 https:// 前缀或者在 daemon.json 的 insecure-registries 里配置否则推送时会遇到证书校验错误。6.2 备份 harbor.yml 与 data_volume 的常用命令Harbor 的 install.sh 没有内置备份功能我会用 tar 直接打包配置与数据目录。为了数据一致性建议先停掉 Harbor 服务再打包否则数据库文件处于热写状态恢复时可能出现不一致。cd /data/install/harbor docker-compose down tar -czf /backup/harbor-$(date %F).tgz harbor.yml /data/harbor/database /data/harbor/redis cd /data/install/harbor docker-compose up -d参数说明docker-compose down 停止但不会删除镜像和 data_volume 内容。tar 打包时带上 harbor.yml恢复时先解压配置再启动 compose能避免很多不必要的重新初始化。6.3 用一个压测镜像验证推送链路备份完成后从已有镜像里挑一个体积偏大的打上仓库 tag 连续推送几次观察磁盘增速和 UI 上的镜像大小统计。docker tag goharbor/harbor-core:latest 192.168.10.20/library/pressure-test:v1 docker push 192.168.10.20/library/pressure-test:v1确认推送成功后到 Harbor UI 的项目里删除这个测试镜像再执行一次垃圾回收观察磁盘空间是否能被正确释放。这一步能顺带验证清理机制的权限设置与存储驱动是否匹配。我现在的习惯是新装的 Harbor 必须完整走一遍 HTTPS、备份、推送压测才交付。RC 版本先跑测试环境正式版再上生产这个顺序不少血泪教训换来的希望帮到你。本文还有配套的精品资源点击获取