企业官网建设流程全解析

简介：本资源是 Harbor 容器镜像仓库 v2.5.0-rc1 版本的离线安装包，面向 DevOps 工程师、容器平台运维人员及 Kubernetes 生态实践者，用于在无外网或受限网络环境中快速部署高可用企业级镜像仓库。压缩包共6个文件，含2个核心Shell脚本（install.sh、common.sh）负责环境校验与服务启停，1个prepare工具用于生成配置与加载镜像，1个harbor.yml.tmpl模板文件支持灵活定制化配置，1个LICENSE协议文件及1个内嵌harbor.v2.5.0.tar.gz镜像归档，整体体积达623.92MB，确保开箱即用。目前已有256人学习下载，读者可直接获取完整离线部署能力：包括预编译二进制、全量依赖镜像、标准化安装流程与配置模板，显著降低内网环境下Harbor部署门槛，避免手动拉取镜像、版本不一致及网络超时等典型问题。

1. Harbor 离线安装包 v2.5.0-rc1：不是“下载即用”，而是「离线环境里能真正跑通 Harbor 的最后一块拼图」

你手头有一台完全断网的生产服务器，没有公网、没有代理、连 yum 源都指向内网镜像，但业务急着要上容器镜像仓库——这时候搜 “harbor 离线安装”，90% 的结果会把你引向一堆零散脚本、手动打包的 Docker 镜像 tar 包、甚至自己 pull + save 的野路子。而harbor-offline-installer-v2.5.0-rc1.tgz这个文件名里的 “offline-installer” 四个字母，是 Harbor 官方唯一承认的、经过 CI 全链路验证的离线交付形态：它不是压缩包里塞几个镜像 tar 就完事，而是把 Harbor 所有组件（core、registry、portal、clair、trivy、notary-server/client、chartmuseum）的二进制、配置模板、预编译的前端资源、甚至适配各版本 Docker/Compose 的启动逻辑，全部静态打包、版本锁死、路径固化，并内置了免联网的证书生成与服务依赖校验机制。它专为金融、能源、政企等强合规离线场景设计，适合那些对部署可重复性、审计可追溯性、升级可控性有硬性要求的 SRE 和平台工程师。如果你正在写离线交付文档、做等保三级镜像仓库备案、或给客户交付一套“拔掉网线也能重启不报错”的 Harbor，这个包就是你该从官网下载并刻盘存档的基准件。

2. 解包即知真相：离线包结构拆解与核心组件定位

Harbor 的离线安装包不是黑匣子。v2.5.0-rc1 的harbor-offline-installer-v2.5.0-rc1.tgz解压后呈现清晰的三层结构：顶层是安装入口和全局配置，中间层是各服务的预制镜像与二进制，底层是运行时依赖与证书工具。理解这个结构，才能在出问题时快速定位到具体文件，而不是盲目重装。

2.1 目录树与关键文件语义解析

解压命令执行后，你会看到如下主干目录：

tar -xzf harbor-offline-installer-v2.5.0-rc1.tgz ls -F # harbor/ # 主程序目录（含 install.sh、prepare、common 目录） # harbor.v2.5.0-rc1.tar.gz # 注意：这是 Harbor 所有服务镜像打包成的单个 tar 文件，非 Docker save 输出，而是 Harbor 构建流水线生成的专用格式 # install.sh # 入口脚本，带参数解析与前置检查 # prepare # 核心配置生成器（Python 实现），负责将 harbor.yml 渲染为 docker-compose.yml 及各服务 config.yaml # common/ # 公共函数库（shell 函数、证书工具集、日志模板）

提示：harbor.v2.5.0-rc1.tar.gz是整个离线包的“心脏”。它不是用docker save生成的普通镜像包，而是 Harbor CI 流水线调用make package-offline产出的定制化归档，内部包含manifest.json描述各镜像 layer 关系，并经skopeo copy --format=v2s2标准化处理，确保在 air-gapped 环境中docker load后镜像 ID 与官方发布版完全一致——这点对后续漏洞扫描报告比对、镜像签名验证至关重要。

2.2harbor.yml：离线部署的唯一配置入口

所有配置必须通过修改harbor.yml完成。v2.5.0-rc1 中该文件已预置完整注释，但以下 5 项是离线环境下必须显式设置且不可留空的：

2.3prepare脚本：配置渲染的幕后引擎

prepare是 Harbor 离线部署的“编译器”。它不启动任何服务，只做三件事：

1. 校验harbor.yml语法与必填项；
2. 根据hostname和https配置生成common/config/core/app.conf、common/config/registry/config.yml等 12 个服务专属配置；
3. 将harbor.v2.5.0-rc1.tar.gz中的镜像加载进本地 Docker daemon（调用docker load < harbor.v2.5.0-rc1.tar.gz）。

其执行逻辑高度依赖 Python 3.6+（系统自带或需提前部署），且不依赖网络——所有证书生成用的是openssl本地命令，所有配置模板硬编码在./prepare二进制中（反编译可见templates/目录结构）。这意味着：只要harbor.yml合法、Docker daemon 正常、磁盘空间充足，./prepare就一定能成功输出docker-compose.yml。

验证 prepare 是否就绪的最简命令：

# 进入 harbor/ 目录后执行 ./prepare --with-notary --with-clair --with-chartmuseum # 输出应为： # Generated configuration file: ./common/config/core/env # Generated configuration file: ./common/config/registry/config.yml # ... # Loaded image: goharbor/harbor-core:v2.5.0-rc1 # Loaded image: goharbor/harbor-db:v2.5.0-rc1 # ... # ----End of preparation----

注意：--with-*参数仅控制是否生成对应服务的配置块，不影响镜像加载——所有镜像均在prepare开头统一加载。若某服务不需要（如不用 Clair），去掉--with-clair即可，docker-compose.yml中将不出现clairservice 定义。

3. 真实离线部署四步走：从解压到可用控制台

离线部署不是“解压 + 运行 install.sh”两步。v2.5.0-rc1 的 install.sh 本质是prepare+docker-compose up -d的封装，但跳过中间检查会埋下深坑。以下是我在某金融客户现场落地 17 套离线 Harbor 的标准流程，每一步都对应一个可验证的状态点。

3.1 步骤一：环境预检（5 分钟，决定成败）

在执行任何./install.sh前，必须人工确认以下 4 项。漏检一项，后续可能卡在core启动失败、registry报 500、或portal白屏：

# 1. Docker 版本必须 ≥ 20.10.0（v2.5.0-rc1 最小要求） docker version --format '{{.Server.Version}}' # 应输出 20.10.x 或更高 # 2. Docker daemon 配置需启用 experimental 功能（Trivy 依赖） grep -q '"experimental": true' /etc/docker/daemon.json && echo "OK" || echo "MISSING" # 3. SELinux 必须 disabled（CentOS/RHEL 默认开启，会导致 /data 挂载拒绝） getenforce # 必须返回 Disabled；若为 Enforcing，执行 setenforce 0 并修改 /etc/selinux/config # 4. 磁盘空间：/data 至少预留 20GB（镜像层 + 日志 + DB WAL） df -h /data | awk 'NR==2 {print $5}' | sed 's/%//' # 使用率 < 80%

提示：install.sh内部的预检只做docker info和基础目录检查，不校验 SELinux 和 experimental。某次客户环境因 SELinux 导致core容器反复 CrashLoopBackOff，日志只显示permission denied on /data/secret/core.key，排查耗时 3 小时——从此我养成了先getenforce的肌肉记忆。

3.2 步骤二：配置生成（2 分钟，静默成功即可靠）

进入harbor/目录，编辑harbor.yml，然后执行：

# 清理上次残留（重要！prepare 不自动清理旧配置） rm -rf common/config/ ./docker-compose.yml # 生成新配置（以启用 Notary 和 ChartMuseum 为例） ./prepare --with-notary --with-chartmuseum # 验证关键配置文件是否存在 ls -l common/config/core/app.conf common/config/registry/config.yml docker-compose.yml # 应全部存在，且 docker-compose.yml 中 services 下有 core, registry, portal, notary-server 等

此步骤无网络请求、无外部依赖，输出 “End of preparation” 即代表配置渲染完成。若报错，99% 是harbor.yml缩进错误（YAML 对空格敏感）或必填项为空。

3.3 步骤三：服务启动（3 分钟，观察日志流）

# 启动所有服务（后台模式） docker-compose up -d # 等待 60 秒，检查核心容器状态 sleep 60 docker-compose ps | grep -E "(Up|Exit)" | head -10 # 正常应显示：core Up 2 minutes, registry Up 2 minutes, portal Up 2 minutes, ... # 查看 core 容器最后 20 行日志（核心服务，启动失败最先暴露） docker-compose logs -n 20 core | tail -10 # 成功标志：出现 "core API server is serving at http://:8080" 或 "starting admin server at :8443"

注意：首次启动时core容器可能因初始化数据库等待 40~90 秒，期间docker-compose ps显示Restarting属正常。若超过 3 分钟仍卡在Restarting，立即docker-compose logs core查看是否报failed to connect to database—— 此时大概率是data_volume路径权限不对（UID 10000 无写权限）。

3.4 步骤四：控制台验证（1 分钟，真金不怕火炼）

打开浏览器，访问https://<your-hostname>（若配置了 HTTPS）或http://<your-hostname>:80（HTTP 模式）。输入默认账号密码：

• 用户名：admin
• 密码：Harbor12345（此密码在harbor.yml中harbor_admin_password字段可修改，但首次部署未改即为此值）

成功登录后，执行两个关键验证动作：

1. 创建项目：点击 “Projects” → “NEW PROJECT”，输入test，勾选 “Public”，点击 “CREATE”。成功后列表应出现test项目。
2. 推送测试镜像：在另一台已配置 Harbor 为 insecure-registry 的机器上执行：

   docker pull alpine:latest docker tag alpine:latest your-hostname/test/alpine:latest docker push your-hostname/test/alpine:latest

   若返回The push refers to repository [your-hostname/test/alpine]且最终显示latest: digest: sha256:... size: ...，则证明 registry 服务完全就绪。

这四步走完，你拥有的不是一个“能启动”的 Harbor，而是一个满足等保 2.0 镜像仓库基线要求、具备完整 RBAC、漏洞扫描（Trivy）、内容信任（Notary）、Helm Chart 管理能力的生产级实例。

4. 避坑指南：离线部署中踩过的 5 个真实血泪坑

离线环境放大了所有配置细节的权重。以下是我在线上环境复现并记录的 5 个高频翻车点，每个都附带现象、根因和可立即执行的解决命令。

4.1 现象：docker-compose up -d后core容器持续 Restarting，docker-compose logs core显示failed to initialize database: pq: password authentication failed for user "postgres"

• 原因：harbor.yml中external_database配置了外部 DB，但password字段为空或与外部 DB 实际密码不符；或使用内置 DB 时，data_volume目录下已有旧版 Harbor 的database/子目录（v2.4 升级 v2.5 时常见）。
• 解决：

  # 方案 A（用内置 DB）：彻底清理 data_volume 下的 database 目录 rm -rf /data/database # 方案 B（用外部 DB）：确认 external_database.password 正确，并在 harbor.yml 中显式写出 # 然后重新 prepare + up ./prepare --with-notary --with-chartmuseum docker-compose down && docker-compose up -d

4.2 现象：浏览器访问https://hostname提示NET::ERR_CERT_INVALID，且地址栏显示“不安全”，点击“高级”也无法继续

• 原因：harbor.yml中https配置了certificate和private_key路径，但文件不存在、权限不足（非 root 可读）、或证书域名与hostname不匹配。
• 解决：

  # 检查证书路径是否存在且可读 ls -l /path/to/your/cert.crt /path/to/your/key.key # 检查证书 CN 是否匹配 hostname openssl x509 -in /path/to/your/cert.crt -text -noout | grep "Subject:" # 若不匹配，重新生成证书（用 prepare 内置工具）： ./prepare --with-notary --with-chartmuseum --https hostname.example.com /path/to/cert /path/to/key # 注意：此命令会覆盖原有 harbor.yml 中的 https 配置

4.3 现象：登录控制台后，“Vulnerability" 标签页空白，Trivy 扫描按钮灰色不可点，docker-compose logs trivy显示failed to download vulnerability database: Get "https://github.com/aquasecurity/trivy-db/releases/download..."

• 原因：Trivy 在离线环境默认尝试联网下载 CVE 数据库，但网络不通导致初始化失败，服务退化为不可用状态。
• 解决：

  # 1. 提前下载 trivy.db（需在有网机器执行）： # wget https://github.com/aquasecurity/trivy-db/releases/download/v1-2023071012/trivy.db.tgz # 2. 解压后拷贝到离线机 /data/trivy-db/ 目录（harbor.yml 中 trivy.db_path 默认为此路径） mkdir -p /data/trivy-db # tar -xzf trivy.db.tgz -C /data/trivy-db/ # 3. 修改 harbor.yml 中 trivy.db_path 为 "/data/trivy-db" # 4. 重启 trivy 服务 docker-compose restart trivy

4.4 现象：docker push报错unauthorized: unauthorized to access repository: test/alpine, action: push: unauthorized to access repository: test/alpine, action: push

• 原因：项目test创建时未勾选 “Public”，且当前用户admin未被显式添加为该项目成员（Harbor v2.5 默认关闭匿名拉取，且新项目无默认成员）。
• 解决：

  # 登录 Web 控制台 → Projects → test → Members → + ADD MEMBER → 输入 admin → Role: Project Admin → SAVE # 或用 Harbor API（需先获取 admin token）： curl -X POST "https://your-hostname/api/v2.0/projects/1/members" \ -H "Authorization: Bearer <admin-jwt-token>" \ -H "Content-Type: application/json" \ -d '{"role_id":1,"member_user":{"username":"admin"}}'

4.5 现象：docker-compose logs notary-server显示failed to connect to database: dial tcp 127.0.0.1:5432: connect: connection refused，但db容器状态为 Up

• 原因：Notary 服务依赖独立的 PostgreSQL 实例（非 Harbor 内置 DB），而离线包中notary-db服务的docker-compose.yml片段未正确挂载/data/notary-db目录，导致容器启动时找不到数据目录而退出。
• 解决：

  # 检查 notary-db 容器是否真的在运行 docker-compose ps notary-db # 若为 Exit，则手动创建挂载目录并赋权 mkdir -p /data/notary-db chown -R 1001:1001 /data/notary-db # notary-db 容器以 UID 1001 运行 # 重启 notary-db docker-compose up -d notary-db # 等待 30 秒后重启 notary-server docker-compose restart notary-server

5. 进阶技巧：离线环境下的 Harbor 升级与配置热更新实战

离线环境最让人头疼的不是首次部署，而是后续升级和配置变更。v2.5.0-rc1 的离线包设计其实预留了平滑演进路径，只是需要你掌握两个关键动作：配置热重载和增量升级包合成。下面以某能源客户的真实需求为例——他们要求“所有配置变更无需重启容器，所有升级必须在 10 分钟内完成且零镜像丢失”。

5.1 配置热更新：不重启容器，让新配置生效

Harbor 的多数配置（如harbor.yml中的log_level、notification、cache）修改后，只需docker-compose exec core kill -s SIGHUP 1即可触发 core 服务重载配置。但有两个例外必须重启对应容器：

验证热重载是否成功：

# 执行 SIGHUP 后，查看 core 日志是否打印 "reloading configuration" docker-compose logs -n 5 core | grep "reloading" # 应输出：time="2023-07-10T08:22:33Z" level=info msg="reloading configuration" # 检查新配置是否已应用（以 log_level 为例） docker-compose exec core cat /etc/core/app.conf | grep log_level # 应显示你刚修改的值，如 log_level = debug

从那以后我每次修改harbor.yml，都强制走一遍./prepare生成新docker-compose.yml，再对比git diff docker-compose.yml确认只有预期变更——因为prepare会重写所有配置文件，手动编辑common/config/下的文件会被覆盖，这是血泪教训。

5.2 构建离线增量升级包：从 v2.5.0-rc1 到 v2.5.0 正式版

官方不提供增量升级包，但你可以用 Harbor CI 的相同工具链自制。核心思路是：只打包变化的镜像和服务二进制，而非全量。适用于带宽受限但允许有限次联网的“准离线”环境（如通过堡垒机上传）。

所需工具（需在有网 Linux 机器安装）：

• docker≥ 20.10
• git、make、golang≥ 1.19
• Harbor 源码：git clone -b v2.5.0 https://github.com/goharbor/harbor.git

构建步骤：

cd harbor # 1. 构建新版离线包（仅差异镜像） make package-offline PKG_VERSION=v2.5.0 # 2. 解包对比，提取增量文件 tar -tzf dist/harbor-offline-installer-v2.5.0.tgz | grep -E "\.(tar\.gz|yml)$" > v2.5.0-files.txt tar -tzf /path/to/v2.5.0-rc1.tgz | grep -E "\.(tar\.gz|yml)$" > v2.5.0-rc1-files.txt diff v2.5.0-rc1-files.txt v2.5.0-files.txt | grep "^>" | cut -d' ' -f2 > incremental-files.txt # 3. 打包增量文件（约 120MB，仅为 rc1 到正式版的镜像差异） tar -czf harbor-v2.5.0-incremental.tgz $(cat incremental-files.txt)

离线机上应用增量包：

# 解压到 harbor/ 目录（覆盖同名文件） tar -xzf harbor-v2.5.0-incremental.tgz -C /path/to/harbor/ # 重新 prepare（会加载新镜像，重写配置） ./prepare --with-notary --with-chartmuseum # 滚动重启（避免服务中断） docker-compose up -d --no-deps --force-recreate core registry portal # 等待 2 分钟，确认新容器 Running 后，再重启依赖服务 docker-compose up -d --no-deps --force-recreate notary-server trivy

此方法将升级时间从全量 45 分钟压缩至 8 分钟内，且所有镜像层复用，存储占用几乎不增。某客户用此法在 32 套离线 Harbor 上完成了 v2.4.3 → v2.5.0 的灰度升级，零业务中断。

希望帮到你。

本文还有配套的精品资源，点击获取