简介：面向容器镜像仓库部署与运维场景的 Harbor 离线安装资源，适合需要在无外网或内网环境中搭建私有镜像仓库的运维工程师、DevOps 人员及云原生学习者使用，可解决离线环境下组件拉取困难、部署流程繁琐的问题。压缩包共 6 个文件，以 sh 安装与公共脚本、tmpl 配置模板、prepare 预处理文件及 license 许可说明为主，另含核心镜像归档，整体约 623.92MB，离线镜像与安装脚本一并打包，省去逐项下载依赖的步骤。已有 258 人学习下载，具备一定参考基础。借助其中的配置模板与安装脚本，读者可快速完成 Harbor v2.5.0-rc1 的离线部署与参数调整，理解镜像仓库的初始化流程与组件构成，并据此排查安装过程中的常见问题，适合作为内网私有仓库搭建的实操起点。
1. 离线环境里把 Harbor 跑起来：一个 tgz 包能省掉多少折腾
内网机房里最怕的不是装不上，而是装到一半发现某个镜像拉不下来。Harbor 作为企业级镜像仓库，在线安装时安装脚本会去公网拉一堆镜像，网络一抖就前功尽弃。harbor-offline-installer-v2.5.0-rc1.tgz这个包的价值就在这儿：它把 Harbor 运行所需的全部镜像和组件预先打包，解压、改配置、执行安装脚本，全程不依赖外网。适合谁？手里有台能装 Docker 和 Docker Compose 的 Linux 机器、需要在内网或隔离环境搭私有镜像仓库的运维和开发。这篇不聊 Harbor 是什么，只聊这个包怎么落地、参数怎么改、哪几个地方最容易翻车。
2. 拆包看结构：离线包到底装了什么
拿到 tgz 先别急着解压执行，花两分钟看清楚里面有什么，后面改配置和排错会省很多事。离线安装包本质是一个自包含的部署单元，理解它的目录布局，等于拿到了这套系统的地图。
2.1 解压后的目录布局与各文件职责
解压命令很朴素，但解压位置有讲究，建议放在空间充足的分区，Harbor 的数据卷后续会长得很快：
# 解压到指定目录，避免落在根分区 mkdir -p /opt/harbor-pkg tar -xzf harbor-offline-installer-v2.5.0-rc1.tgz -C /opt/harbor-pkg cd /opt/harbor-pkg/harbor ls -lh解压后你会看到几个关键文件，职责各不相同：
| 文件/目录 | 作用 | 是否需要改 |
|---|---|---|
harbor.yml.tmpl | 配置模板，安装脚本读取的是harbor.yml | 必须复制并修改 |
install.sh | 主安装脚本，负责加载镜像、渲染配置、启动容器 | 一般不改 |
prepare | 环境预检与配置生成，install.sh会调用它 | 一般不改 |
common.sh | 脚本公共函数库 | 不改 |
harbor.v2.5.0.tar.gz | 全部组件镜像的离线包 | 不改，安装时自动加载 |
docker-compose.yml | 由 prepare 根据配置生成，不要手改 | 不直接改 |
这里有个血泪经验：很多人直接改harbor.yml.tmpl，结果安装脚本读的是harbor.yml，改了半天没生效。正确做法是先复制再改：
cp harbor.yml.tmpl harbor.ymlharbor.yml是唯一需要你动手的配置文件，其余都是脚本和镜像资产。理解这一点，后面所有参数调整都围绕它展开。
2.2 前置依赖：Docker 与 Compose 的版本边界
离线包不负责装 Docker，这是第一个容易忽略的前提。Harbor 2.5 对 Docker Engine 和 Docker Compose 有最低版本要求，版本太低会在 prepare 阶段直接报错退出。常见做法是先确认版本：
docker version --format '{{.Server.Version}}' docker compose version # 老版本可能是 docker-compose version判断标准：Docker Engine 建议 20.10 及以上，Compose 用 v2 插件形式（docker compose）更稳，v1 的docker-compose在部分发行版上已停止维护。如果机器上只有 v1，安装脚本仍可能跑通，但后续排错时命令对不上，容易把自己绕进去。另一个隐性依赖是磁盘：镜像包解压加载后占用不小，加上数据卷，建议预留至少 40GB 可用空间，用df -h先看一眼再动手。
3. 改配置再安装：harbor.yml 里真正要动的几个参数
配置文件改错是离线安装翻车的高发区。这一章把必须改的、建议改的、千万别乱改的分开讲清楚，照着改完再执行安装，成功率会高很多。
3.1 hostname、端口与数据目录的最小改动集
harbor.yml里字段很多，但首次部署真正必须动的不超过五个。最小改动集如下：
# harbor.yml 关键片段 hostname: registry.internal.example # 改成你的访问地址，IP 或域名 http: port: 80 # 对外 HTTP 端口 # https: # port: 443 # certificate: /your/cert.pem # private_key: /your/key.pem harbor_admin_password: ChangeMe_12345 # 初始管理员密码，务必改 data_volume: /data/harbor # 数据落盘目录，指向大分区逐项说明。hostname是客户端docker login时用的地址，填 IP 或内网域名都行，但一旦定下来后续改起来麻烦，因为镜像的 tag 前缀会绑这个值，建议一开始就想清楚。http.port是访问端口，80 被占用就换 8080 之类。HTTPS 段默认是注释掉的，内网首次验证可以先走 HTTP，等跑通再补证书，别一上来就卡在证书配置上。harbor_admin_password是 admin 账号初始密码，模板里是占位值，不改等于把门敞开。data_volume决定镜像和数据库落在哪，默认在安装目录下，生产环境一定要指到独立大分区。
提示：
hostname不要填localhost或127.0.0.1，否则其他机器无法通过该地址推送镜像，客户端会报证书或连接错误。
3.2 执行 install.sh：从加载镜像到容器起来的完整链路
配置改完就可以执行安装。这一步脚本做的事比看起来多：校验配置、加载离线镜像、渲染 compose 文件、拉起容器。命令本身简单，但要盯着输出：
cd /opt/harbor-pkg/harbor sudo ./install.sh脚本执行过程中会依次打印prepare base dir is set to ...、Loaded image: ...、Creating network ...、Creating container ...等日志。重点看两处：镜像加载阶段有没有Loaded image逐条出现，容器创建阶段有没有done。全部走完后，脚本末尾会打印访问地址和默认账号提示。
安装完成后验证服务状态：
docker compose ps # 期望看到 harbor-core、harbor-db、harbor-redis、harbor-portal、 # registry、registryctl、harbor-jobservice、nginx 等容器状态为 running如果某个容器反复重启，先看它的日志，别急着重装：
docker compose logs --tail=100 harbor-coreharbor-core起不来最常见的原因是数据库没就绪或配置里的密码与数据库不匹配，日志里会有明确的连接失败信息。确认所有容器 running 后，浏览器访问http://你的hostname:端口，用 admin 和刚设的密码登录，能进控制台就说明这套离线部署立住了。
3.3 客户端侧：docker login 与推送第一个镜像
服务端起来只是半程，客户端能不能推拉才是验收标准。先在客户端机器上配置信任（HTTP 场景必须做，否则 docker 会拒绝非 HTTPS 仓库）：
# 编辑 /etc/docker/daemon.json，加入 insecure-registries { "insecure-registries": ["registry.internal.example:80"] } # 重启 docker 使配置生效 sudo systemctl restart docker然后登录并推送一个测试镜像：
docker login registry.internal.example:80 -u admin docker pull busybox:latest docker tag busybox:latest registry.internal.example:80/library/busybox:test docker push registry.internal.example:80/library/busybox:testinsecure-registries里要写完整的hostname:port，只写 hostname 不写端口在非 80 端口场景下会失效。推送成功后回控制台看项目列表，能看到library项目和刚推的镜像，整条链路就闭环了。这一步别跳过，很多“装好了但用不了”的问题都出在客户端信任配置上。
4. 避坑与排查：离线安装最常见的五个翻车点
离线安装的坑大多集中在配置、端口和磁盘三块，下面五条是按实际排错频率排的，每条都给出可操作的定位手段。
4.1 现象：install.sh 报端口被占用，容器起不来
原因：80 或 443 已被宿主机上的 nginx、apache 或其他服务占用，Harbor 的 nginx 容器绑定失败。解决：先查占用ss -lntp | grep ':80'，要么停掉占用服务，要么改harbor.yml里的http.port为 8080 等空闲端口，改完重新执行./install.sh。注意改端口后客户端insecure-registries和docker login的地址都要同步带端口。
4.2 现象：prepare 阶段报 hostname 相关错误或安装后无法访问
原因：hostname填了localhost、127.0.0.1，或填了客户端解析不了的域名。解决：改成客户端能解析到的内网 IP 或域名，确认客户端ping得通。已经装错的话，改harbor.yml后重新执行./install.sh，脚本会重建配置，但已推送的镜像数据在data_volume里，不会丢。
4.3 现象：镜像加载到一半失败，提示 no space left on device
原因：/var/lib/docker或安装目录所在分区空间不足，离线镜像包解压加载很吃空间。解决：df -h确认分区，清理无用镜像docker image prune -a，或把data_volume指到大分区后重装。血泪经验是别把安装目录和数据目录都塞在根分区，跑一段时间镜像一多就爆。
4.4 现象：docker push 报http: server gave HTTP response to HTTPS client
原因：客户端没配insecure-registries，docker 默认走 HTTPS 去连 HTTP 仓库。解决：按 3.3 节在/etc/docker/daemon.json加insecure-registries并重启 docker。注意 JSON 格式别写错，多一个逗号都会导致 docker 起不来，改完用docker info确认配置已加载。
4.5 现象：容器全部 running，但登录报 502 或页面白屏
原因：harbor-core与数据库连接异常，或 nginx 上游未就绪。解决：docker compose logs harbor-core看是否有数据库连接拒绝，再docker compose logs harbor-db看数据库是否正常初始化。常见诱因是harbor.yml里数据库密码被改过但数据卷里还是旧密码，导致认证失败。这种情况要么改回原密码，要么清空数据卷重装（会丢数据，谨慎）。
5. 进阶：升级、备份与离线包的复用姿势
跑通之后，真正决定这套仓库能不能长期用的是升级和备份策略。离线包的价值不只在首次安装，更在于它让升级过程也可控——不依赖外网，版本切换可回退。
升级的基本思路是：下载新版本离线包，解压到新目录，把旧目录的harbor.yml和data_volume沿用过来，停旧服务、启新服务。关键动作是先备份数据库：
# 备份 Harbor 数据库（PostgreSQL 容器内） docker exec -e PGPASSWORD=your_db_password harbor-db \ pg_dump -U postgres registry > /backup/harbor_db_$(date +%F).sql # 备份配置文件 cp /opt/harbor-pkg/harbor/harbor.yml /backup/harbor.yml.$(date +%F)pg_dump的-U postgres是默认库用户，密码取自harbor.yml的database.password。备份完再执行新版本的./install.sh，脚本会做数据迁移。升级前务必确认新旧版本跨度不要太大，跨多个大版本时按官方升级路径逐级走，别一步到位。
另一个实用技巧是离线包的镜像复用：harbor.v2.5.0.tar.gz里的镜像可以用docker load -i单独加载到其他机器，做多节点部署或灾备时不用重复下载。加载后docker images能看到goharbor/前缀的一批镜像，按需docker tag和push到目标仓库即可。
我自己的习惯是每次动 Harbor 之前，先把harbor.yml和数据库备份各存一份带日期的副本，升级完立刻推一个测试镜像验证推拉链路。这套动作看着繁琐，但真出问题时能省掉重装和丢数据的后悔药。从那以后我每次升级前都强制走一遍备份加验证，没再因为升级翻过车。希望帮到你。
本文还有配套的精品资源，点击获取
