简介Harbor 是开源的企业级容器镜像仓库这份离线资源包主要面向需要在隔离内网中部署 Harbor v2.5.0-rc1 的运维、开发与容器平台建设人员解决因网络受限导致无法在线拉取镜像和依赖的常见问题。资源共 6 个文件整体约 623.92MB除核心的离线镜像压缩包外还包含两个 shell 脚本、准备工具、配置文件模板以及 LICENSE 许可文件覆盖校验、配置、导入和启动等多个部署环节。目前已有 254 人学习下载适合具备一定容器基础、希望绕开在线安装繁琐步骤的中高级使用者。借助安装脚本与准备工具可快速完成环境检查和配置生成配置文件模板支持按需调整端口、存储、数据库等关键参数减少手工干预。整套资源对离线交付、镜像分发和后台上线后的排查都有直接帮助能够明显节省收集组件和排错的时间帮助读者更稳妥地完成 Harbor 服务部署。 拿到harbor-offline-installer-v2.5.0-rc1.tgz这个包的时候我第一反应是先看一眼里面的时间戳和版本号。v2.5.0-rc1这是 Harbor 2.5 系列的发布候选版本对强迫症来说可能有点纠结但在实际交付场景里它往往意味着新功能落地前的最后一次完整验证。这年头只要做容器化绕不开镜像仓库而 Harbor 又是国内团队最常用的开源方案离线安装包用起来比在线拉镜像省心太多尤其在内网环境、弱网环境跑一遍就懂它的价值。这篇文章我会结合自己在 Ubuntu 服务器上部署 Harbor 的实际过程把这个离线包从解压、配置、部署到把 HTTP 改成 HTTPS 的完整链路拆开讲清楚。适合刚接触 Harbor 的运维新手也适合已经在用 Harbor 但想搞明白离线安装内部逻辑的人。里面会涉及到不少踩坑记录尤其是http改https这个环节网上资料很多但都不够细我把自己验证过的步骤和参数直接写出来照着做基本能一把过。1. 这个离线安装包到底是什么1.1 离线包的结构与用途harbor-offline-installer-v2.5.0-rc1.tgz从命名就能读出三个关键信息项目是harbor模式是offline-installer版本是v2.5.0-rc1。所谓离线安装包就是 Harbor 官方已经把部署所需的所有 Docker 镜像、配置文件、安装脚本全部打进了一个压缩包里不需要从 Docker Hub 在线拉取镜像断网环境下也能完整部署。解压之后你会看到大概下面这几类东西install.sh核心安装脚本负责校验环境、加载镜像、编排容器harbor.yml.tmpl配置模板需要复制并改名为harbor.yml才能用harbor.v2.5.0-rc1.tar.gz所有 Harbor 组件镜像的打包文件common.sh、prepare辅助脚本和配置生成工具Harbor 本身不是一个单体应用它是由多个容器组件组合而成的harbor-core核心业务、harbor-registry镜像存储基于 Docker Registry、harbor-db数据库默认是 PostgreSQL、harbor-portalWeb 界面、harbor-log日志收集、nginx反向代理。离线包里这个tar.gz文件就是把所有这些镜像打包成一坨安装时一条龙导入。1.2 为什么推荐用离线安装包在线安装看着简单curl ... | bash一条命令搞定但实际生产交付往往不是这么回事。内网环境没有外网、公司源镜像拉不动、Docker Hub 被限速——这些问题碰到任何一个都能让人原地崩溃。离线包把镜像一次性带到内网之后所有的操作基本不依赖外网稳定性强太多。而且离线安装包还有一个隐性优势版本可控。在线方式可能会因为镜像标签变动、源仓库更新导致装出来不是你想要的那个版本。离线包锁死了版本所有组件一起打包校验通过后行为一致对后续排障和升级都很友好。注意rc1是 Release Candidate 的缩写意思是发布候选版功能和正式版基本一致但可能仍存在少量未发现的问题。如果用在正式生产环境建议等stable正式版或者至少先在测试环境完整跑一轮。2. 安装前的环境准备与配置解析2.1 基础依赖Docker 与 Docker ComposeHarbor 安装靠的是 Docker 容器编排所以宿主机必须装好 Docker 和 Docker Compose。Harbor 2.5 官方要求 Docker 版本高于 17.06Docker Compose 高于 1.18。我这边用的是 Ubuntu 20.04 LTSDocker 版本是 20.10.xCompose 是 2.x 的独立二进制实测没有问题。检查环境docker --version docker compose version如果是比较老的 Ubuntu 版本Docker 可能没装或者版本偏低先把这一步补齐。装 Docker 可以直接用官方脚本但在内网环境就得提前准备离线包这里不展开。另外建议提前确认tar、openssl这些基础命令存在因为安装脚本和后面对证书的配置都会用到。2.2 解压安装包与配置模板把安装包传到服务器后先解压到/opt或者其他你有权限的目录tar -zxvf harbor-offline-installer-v2.5.0-rc1.tgz cd harbor进目录后第一件事是复制配置模板cp harbor.yml.tmpl harbor.ymlharbor.yml是整个部署的核心配置文件所有关键参数都在这里。Harbor 2.x 之后用的都是 YAML 格式不再支持老的harbor.cfg。2.3 核心配置项逐个拆解用编辑器打开harbor.yml里面最关键的几个配置项hostname: registry.example.com http: port: 80 https: port: 443 certificate: /your/certificate/path private_key: /your/private/key/path harbor_admin_password: Harbor12345 database: password: root123 data_volume: /data/harborhostname对外访问的地址可以是 IP 也可以是域名。这个值会被写进 Docker 的insecure-registries或者证书的 CN 里。用 IP 部署的话后续客户端拉镜像时也要用这个 IP 访问。http.portHTTP 监听端口默认 80。https.portHTTPS 监听端口默认 443需要配置证书和私钥路径。harbor_admin_password管理员密码这个一定要改掉默认是Harbor12345尤其公网环境不改等于裸奔。data_volume持久化数据存放目录镜像数据、数据库文件都在这里建议放到大容量磁盘上。刚解压时默认配置里https段落是注释掉的如果暂时只想用 HTTP 访问把http段留着即可。不过我建议从一开始就规划好 HTTPS省得后面再折腾一次重新部署。3. 完整部署流程与实操记录3.1 执行 install.sh配置改完后直接运行安装脚本./install.sh脚本会先检查环境包括 Docker 是否运行、Compose 是否存在、端口是否被占用。有问题它会直接红色提示并退出。环境检查通过后脚本会做三件事从本地harbor.v2.5.0-rc1.tar.gz加载所有镜像根据harbor.yml生成 Docker Compose 编排文件启动所有容器并等待健康检查通过第一次跑的时候加载镜像阶段会比较慢观察输出可以看到Loading docker images...这个步骤。镜像数量多体积也不小耐心等就行。装完后查看容器状态docker compose ps正常情况下应该有 10 个左右的容器在运行全部显示Up状态。3.2 验证安装结果浏览器访问http://hostname能跳到登录页就说明宕了。默认账号是admin密码就是你配置的harbor_admin_password。命令行验证推荐用curlcurl -I http://127.0.0.1返回200 OK说明 Web 服务正常。如果要测登录 API可以这样curl -u admin:你的密码 http://127.0.0.1/api/v2.0/projects能返回 JSON 数组就说明 API 也通了。3.3 首次登录与基础设置登录后第一件事是改密码harbor_admin_password只影响初始密码进去之后最好在用户设置里再改一遍并开启两步验证如果版本支持。然后是建项目Harbor 里项目就是命名空间用来区分不同的镜像库。建议把公开/私有策略提前规划好。团队内部共享镜像可以设为公开省去每个客户端配置凭据的麻烦涉及敏感业务镜像就设私有拉取时先docker login。4. HTTP 改成 HTTPS证书生成与重新部署4.1 为什么一定要切到 HTTPS很多人觉得反正是内网HTTP 够用了。但有一个关键痛点Docker 客户端默认强制 HTTPS 访问仓库除非你在每个客户端上配置insecure-registries。如果仓库走 HTTPS客户端配置会省事很多也更安全。另外浏览器访问时不会老是弹安全警告审计合规也说得过去。我实际处理过的一个场景是内网有一堆服务器要拉镜像之前用 HTTP结果每一台都要改/etc/docker/daemon.json漏掉一台就报server gave HTTP response to HTTPS client。切到 HTTPS 之后这个问题直接消失整体运维成本降低不少。4.2 生成自签名证书不是所有公司都有正规 CA 签发的域名证书内网环境最常见的做法是自签名。用openssl一把梭生成证书mkdir -p /data/cert cd /data/cert # 生成私钥 openssl genrsa -out ca.key 4096 # 生成 CA 自签名证书 openssl req -x509 -new -nodes -sha256 -days 3650 \ -subj /CNharbor.example.com \ -key ca.key -out ca.crt # 生成服务器私钥 openssl genrsa -out server.key 4096 # 生成证书签名请求 openssl req -new -sha256 -key server.key -subj /CNharbor.example.com -out server.csr # 配置 SAN 扩展把 IP 也加进去 cat ext.cnf EOF subjectAltNameIP:192.168.1.100,DNS:harbor.example.com EOF # 签发服务器证书 openssl x509 -req -sha256 \ -in server.csr \ -CA ca.crt -CAkey ca.key -CAcreateserial \ -out server.crt -days 3650 -extfile ext.cnf这里有个细节必须提醒如果你要么用域名访问要么用 IP 访问一定要在ext.cnf里同时写好IP和DNS的 SAN。只填 IP那以后折腾域名访问时会校验证书失败只填 DNSIP 访问又不行。我踩过这个坑一把泪。4.3 修改 harbor.yml 并重新部署证书生成后编辑harbor.yml把https段打开https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key接着执行./install.sh --with-trivy这里用--with-trivy是因为我插件了漏洞扫描组件重启部署时会一起加载。如果不需要扫描功能直接./install.sh也行。脚本会自动检测到已有容器和数据执行更新配置并重启不会清掉已有的镜像数据。如果遇到配置没有生效的情况需要先停掉再重新部署docker compose down ./prepare ./install.sh./prepare这个命令会根据harbor.yml重新生成 Nginx 和核心组件的配置在改了协议或端口后这一步是关键的缺了它可能会出现旧配置残留。4.4 客户端配置与验证服务器端切到 HTTPS 后客户端需要把自签 CA 加入信任或配置insecure-registries。如果局域网内所有机器都信任你的自签 CA那最干净的方案是把ca.crt分发到每台机器sudo cp ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates如果是临时测试直接在/etc/docker/daemon.json里加{ insecure-registries: [192.168.1.100] }然后重启 Docker。验证登录curl -k https://192.168.1.100/api/v2.0/projects返回正常就说明 HTTPS 配置完成。5. 常见问题与排查技巧实录5.1 端口被占用导致启动失败Ubuntu 上最常见的问题是 80 或 443 端口被系统自带的 Nginx 或者其他 Web 服务占用。Harbor 的 Nginx 和系统 Nginx 会冲突表现就是容器反复重启或者直接启动失败。排查方式很简单ss -tlnp | grep -E :80|:443看到有进程监听先停掉它或者把 Harbor 的端口改到别的值http: port: 8080如果改端口后续访问地址也要跟着变客户端daemon.json里的insecure-registries也要改成对应的端口号。5.2 客户端报“server gave HTTP response to HTTPS client”这个报错几乎成了 Harbor HTTP 部署的默认拦路虎。原因就是 Docker 客户端默认要求 HTTPS而服务器只提供 HTTP。解决办法两个方向服务器端切 HTTPS前面已经讲了客户端配置insecure-registries后重启 Docker注意配置完一定要执行sudo systemctl restart docker不重启 Docker配置不会生效。另外虽然 Docker 支持热加载某些配置但insecure-registries必须重启。5.3 镜像数据存储目录容量不够Harbor 的data_volume默认是/data/harbor如果你没有单独分盘跟系统根分区共用磁盘。镜像一多几十 GB 几百 GB 就没了。我遇到过一台服务器因为镜像库写满导致整个系统只读服务全挂。建议在初始化部署之前df -h确认/data或你要用的数据目录所在分区有足够空间。如果已经部署了再迁移数据比较麻烦最好一开始就规划好。5.4 常见错误速查表现象可能原因解决方向浏览器访问拒绝连接端口未监听 / 防火墙拦截ss -tlnp检查端口ufw放行端口Docker login 报 x509 错误证书未信任 / 证书 CN 不匹配分发ca.crt到客户端检查 SAN容器反复重启配置错误 / 端口冲突查看docker compose logs nginx检查端口占用上传镜像时报 413Nginx 上传大小限制调整 Nginxclient_max_body_size配置密码忘了数据库密码与配置不一致重置postgres库密码或直接重装数据可保留5.5 数据库与备份的注意事项Harbor 的 PostgreSQL 数据在data_volume下的database目录。日常备份建议直接冷备份整个数据目录或者用pg_dump逻辑备份。我个人习惯是定期执行docker exec harbor-db pg_dump -U postgres registry registry_$(date %F).sql恢复时把 SQL 文件导入新库即可。镜像数据本身在data_volume的registry目录下备份时优先考虑这两个目录比全量打快照省空间。最后的经验之谈Harbor 离线安装看着是个一次性工作但后续的协议切换、证书轮换、备份恢复才是真正考验人的地方。我在实际部署中最深的体会是初始配置阶段就把 HTTPS、数据目录、密码策略定好比后期来回折腾要省心得多。v2.5.0-rc1这个版本虽然整体稳定但生产环境我还是建议等正式版或者至少把rc1在测试环境跑成熟了再上生产。最后再分享一个小技巧离线包本身是很好的离线镜像源你甚至可以用它来一键部署一套 Harbor 后把常用的基础镜像推上去形成一个内部加速仓库。这样以后新机器拉镜像直接从内网仓库走速度比外网快几个量级。离线安装包的价值说到底不只是装一次 Harbor而是搭起了整个内网容器生态的底座。本文还有配套的精品资源点击获取 Harbor 2.5离线安装与HTTPS配置实战指南
简介Harbor 是开源的企业级容器镜像仓库这份离线资源包主要面向需要在隔离内网中部署 Harbor v2.5.0-rc1 的运维、开发与容器平台建设人员解决因网络受限导致无法在线拉取镜像和依赖的常见问题。资源共 6 个文件整体约 623.92MB除核心的离线镜像压缩包外还包含两个 shell 脚本、准备工具、配置文件模板以及 LICENSE 许可文件覆盖校验、配置、导入和启动等多个部署环节。目前已有 254 人学习下载适合具备一定容器基础、希望绕开在线安装繁琐步骤的中高级使用者。借助安装脚本与准备工具可快速完成环境检查和配置生成配置文件模板支持按需调整端口、存储、数据库等关键参数减少手工干预。整套资源对离线交付、镜像分发和后台上线后的排查都有直接帮助能够明显节省收集组件和排错的时间帮助读者更稳妥地完成 Harbor 服务部署。 拿到harbor-offline-installer-v2.5.0-rc1.tgz这个包的时候我第一反应是先看一眼里面的时间戳和版本号。v2.5.0-rc1这是 Harbor 2.5 系列的发布候选版本对强迫症来说可能有点纠结但在实际交付场景里它往往意味着新功能落地前的最后一次完整验证。这年头只要做容器化绕不开镜像仓库而 Harbor 又是国内团队最常用的开源方案离线安装包用起来比在线拉镜像省心太多尤其在内网环境、弱网环境跑一遍就懂它的价值。这篇文章我会结合自己在 Ubuntu 服务器上部署 Harbor 的实际过程把这个离线包从解压、配置、部署到把 HTTP 改成 HTTPS 的完整链路拆开讲清楚。适合刚接触 Harbor 的运维新手也适合已经在用 Harbor 但想搞明白离线安装内部逻辑的人。里面会涉及到不少踩坑记录尤其是http改https这个环节网上资料很多但都不够细我把自己验证过的步骤和参数直接写出来照着做基本能一把过。1. 这个离线安装包到底是什么1.1 离线包的结构与用途harbor-offline-installer-v2.5.0-rc1.tgz从命名就能读出三个关键信息项目是harbor模式是offline-installer版本是v2.5.0-rc1。所谓离线安装包就是 Harbor 官方已经把部署所需的所有 Docker 镜像、配置文件、安装脚本全部打进了一个压缩包里不需要从 Docker Hub 在线拉取镜像断网环境下也能完整部署。解压之后你会看到大概下面这几类东西install.sh核心安装脚本负责校验环境、加载镜像、编排容器harbor.yml.tmpl配置模板需要复制并改名为harbor.yml才能用harbor.v2.5.0-rc1.tar.gz所有 Harbor 组件镜像的打包文件common.sh、prepare辅助脚本和配置生成工具Harbor 本身不是一个单体应用它是由多个容器组件组合而成的harbor-core核心业务、harbor-registry镜像存储基于 Docker Registry、harbor-db数据库默认是 PostgreSQL、harbor-portalWeb 界面、harbor-log日志收集、nginx反向代理。离线包里这个tar.gz文件就是把所有这些镜像打包成一坨安装时一条龙导入。1.2 为什么推荐用离线安装包在线安装看着简单curl ... | bash一条命令搞定但实际生产交付往往不是这么回事。内网环境没有外网、公司源镜像拉不动、Docker Hub 被限速——这些问题碰到任何一个都能让人原地崩溃。离线包把镜像一次性带到内网之后所有的操作基本不依赖外网稳定性强太多。而且离线安装包还有一个隐性优势版本可控。在线方式可能会因为镜像标签变动、源仓库更新导致装出来不是你想要的那个版本。离线包锁死了版本所有组件一起打包校验通过后行为一致对后续排障和升级都很友好。注意rc1是 Release Candidate 的缩写意思是发布候选版功能和正式版基本一致但可能仍存在少量未发现的问题。如果用在正式生产环境建议等stable正式版或者至少先在测试环境完整跑一轮。2. 安装前的环境准备与配置解析2.1 基础依赖Docker 与 Docker ComposeHarbor 安装靠的是 Docker 容器编排所以宿主机必须装好 Docker 和 Docker Compose。Harbor 2.5 官方要求 Docker 版本高于 17.06Docker Compose 高于 1.18。我这边用的是 Ubuntu 20.04 LTSDocker 版本是 20.10.xCompose 是 2.x 的独立二进制实测没有问题。检查环境docker --version docker compose version如果是比较老的 Ubuntu 版本Docker 可能没装或者版本偏低先把这一步补齐。装 Docker 可以直接用官方脚本但在内网环境就得提前准备离线包这里不展开。另外建议提前确认tar、openssl这些基础命令存在因为安装脚本和后面对证书的配置都会用到。2.2 解压安装包与配置模板把安装包传到服务器后先解压到/opt或者其他你有权限的目录tar -zxvf harbor-offline-installer-v2.5.0-rc1.tgz cd harbor进目录后第一件事是复制配置模板cp harbor.yml.tmpl harbor.ymlharbor.yml是整个部署的核心配置文件所有关键参数都在这里。Harbor 2.x 之后用的都是 YAML 格式不再支持老的harbor.cfg。2.3 核心配置项逐个拆解用编辑器打开harbor.yml里面最关键的几个配置项hostname: registry.example.com http: port: 80 https: port: 443 certificate: /your/certificate/path private_key: /your/private/key/path harbor_admin_password: Harbor12345 database: password: root123 data_volume: /data/harborhostname对外访问的地址可以是 IP 也可以是域名。这个值会被写进 Docker 的insecure-registries或者证书的 CN 里。用 IP 部署的话后续客户端拉镜像时也要用这个 IP 访问。http.portHTTP 监听端口默认 80。https.portHTTPS 监听端口默认 443需要配置证书和私钥路径。harbor_admin_password管理员密码这个一定要改掉默认是Harbor12345尤其公网环境不改等于裸奔。data_volume持久化数据存放目录镜像数据、数据库文件都在这里建议放到大容量磁盘上。刚解压时默认配置里https段落是注释掉的如果暂时只想用 HTTP 访问把http段留着即可。不过我建议从一开始就规划好 HTTPS省得后面再折腾一次重新部署。3. 完整部署流程与实操记录3.1 执行 install.sh配置改完后直接运行安装脚本./install.sh脚本会先检查环境包括 Docker 是否运行、Compose 是否存在、端口是否被占用。有问题它会直接红色提示并退出。环境检查通过后脚本会做三件事从本地harbor.v2.5.0-rc1.tar.gz加载所有镜像根据harbor.yml生成 Docker Compose 编排文件启动所有容器并等待健康检查通过第一次跑的时候加载镜像阶段会比较慢观察输出可以看到Loading docker images...这个步骤。镜像数量多体积也不小耐心等就行。装完后查看容器状态docker compose ps正常情况下应该有 10 个左右的容器在运行全部显示Up状态。3.2 验证安装结果浏览器访问http://hostname能跳到登录页就说明宕了。默认账号是admin密码就是你配置的harbor_admin_password。命令行验证推荐用curlcurl -I http://127.0.0.1返回200 OK说明 Web 服务正常。如果要测登录 API可以这样curl -u admin:你的密码 http://127.0.0.1/api/v2.0/projects能返回 JSON 数组就说明 API 也通了。3.3 首次登录与基础设置登录后第一件事是改密码harbor_admin_password只影响初始密码进去之后最好在用户设置里再改一遍并开启两步验证如果版本支持。然后是建项目Harbor 里项目就是命名空间用来区分不同的镜像库。建议把公开/私有策略提前规划好。团队内部共享镜像可以设为公开省去每个客户端配置凭据的麻烦涉及敏感业务镜像就设私有拉取时先docker login。4. HTTP 改成 HTTPS证书生成与重新部署4.1 为什么一定要切到 HTTPS很多人觉得反正是内网HTTP 够用了。但有一个关键痛点Docker 客户端默认强制 HTTPS 访问仓库除非你在每个客户端上配置insecure-registries。如果仓库走 HTTPS客户端配置会省事很多也更安全。另外浏览器访问时不会老是弹安全警告审计合规也说得过去。我实际处理过的一个场景是内网有一堆服务器要拉镜像之前用 HTTP结果每一台都要改/etc/docker/daemon.json漏掉一台就报server gave HTTP response to HTTPS client。切到 HTTPS 之后这个问题直接消失整体运维成本降低不少。4.2 生成自签名证书不是所有公司都有正规 CA 签发的域名证书内网环境最常见的做法是自签名。用openssl一把梭生成证书mkdir -p /data/cert cd /data/cert # 生成私钥 openssl genrsa -out ca.key 4096 # 生成 CA 自签名证书 openssl req -x509 -new -nodes -sha256 -days 3650 \ -subj /CNharbor.example.com \ -key ca.key -out ca.crt # 生成服务器私钥 openssl genrsa -out server.key 4096 # 生成证书签名请求 openssl req -new -sha256 -key server.key -subj /CNharbor.example.com -out server.csr # 配置 SAN 扩展把 IP 也加进去 cat ext.cnf EOF subjectAltNameIP:192.168.1.100,DNS:harbor.example.com EOF # 签发服务器证书 openssl x509 -req -sha256 \ -in server.csr \ -CA ca.crt -CAkey ca.key -CAcreateserial \ -out server.crt -days 3650 -extfile ext.cnf这里有个细节必须提醒如果你要么用域名访问要么用 IP 访问一定要在ext.cnf里同时写好IP和DNS的 SAN。只填 IP那以后折腾域名访问时会校验证书失败只填 DNSIP 访问又不行。我踩过这个坑一把泪。4.3 修改 harbor.yml 并重新部署证书生成后编辑harbor.yml把https段打开https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key接着执行./install.sh --with-trivy这里用--with-trivy是因为我插件了漏洞扫描组件重启部署时会一起加载。如果不需要扫描功能直接./install.sh也行。脚本会自动检测到已有容器和数据执行更新配置并重启不会清掉已有的镜像数据。如果遇到配置没有生效的情况需要先停掉再重新部署docker compose down ./prepare ./install.sh./prepare这个命令会根据harbor.yml重新生成 Nginx 和核心组件的配置在改了协议或端口后这一步是关键的缺了它可能会出现旧配置残留。4.4 客户端配置与验证服务器端切到 HTTPS 后客户端需要把自签 CA 加入信任或配置insecure-registries。如果局域网内所有机器都信任你的自签 CA那最干净的方案是把ca.crt分发到每台机器sudo cp ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates如果是临时测试直接在/etc/docker/daemon.json里加{ insecure-registries: [192.168.1.100] }然后重启 Docker。验证登录curl -k https://192.168.1.100/api/v2.0/projects返回正常就说明 HTTPS 配置完成。5. 常见问题与排查技巧实录5.1 端口被占用导致启动失败Ubuntu 上最常见的问题是 80 或 443 端口被系统自带的 Nginx 或者其他 Web 服务占用。Harbor 的 Nginx 和系统 Nginx 会冲突表现就是容器反复重启或者直接启动失败。排查方式很简单ss -tlnp | grep -E :80|:443看到有进程监听先停掉它或者把 Harbor 的端口改到别的值http: port: 8080如果改端口后续访问地址也要跟着变客户端daemon.json里的insecure-registries也要改成对应的端口号。5.2 客户端报“server gave HTTP response to HTTPS client”这个报错几乎成了 Harbor HTTP 部署的默认拦路虎。原因就是 Docker 客户端默认要求 HTTPS而服务器只提供 HTTP。解决办法两个方向服务器端切 HTTPS前面已经讲了客户端配置insecure-registries后重启 Docker注意配置完一定要执行sudo systemctl restart docker不重启 Docker配置不会生效。另外虽然 Docker 支持热加载某些配置但insecure-registries必须重启。5.3 镜像数据存储目录容量不够Harbor 的data_volume默认是/data/harbor如果你没有单独分盘跟系统根分区共用磁盘。镜像一多几十 GB 几百 GB 就没了。我遇到过一台服务器因为镜像库写满导致整个系统只读服务全挂。建议在初始化部署之前df -h确认/data或你要用的数据目录所在分区有足够空间。如果已经部署了再迁移数据比较麻烦最好一开始就规划好。5.4 常见错误速查表现象可能原因解决方向浏览器访问拒绝连接端口未监听 / 防火墙拦截ss -tlnp检查端口ufw放行端口Docker login 报 x509 错误证书未信任 / 证书 CN 不匹配分发ca.crt到客户端检查 SAN容器反复重启配置错误 / 端口冲突查看docker compose logs nginx检查端口占用上传镜像时报 413Nginx 上传大小限制调整 Nginxclient_max_body_size配置密码忘了数据库密码与配置不一致重置postgres库密码或直接重装数据可保留5.5 数据库与备份的注意事项Harbor 的 PostgreSQL 数据在data_volume下的database目录。日常备份建议直接冷备份整个数据目录或者用pg_dump逻辑备份。我个人习惯是定期执行docker exec harbor-db pg_dump -U postgres registry registry_$(date %F).sql恢复时把 SQL 文件导入新库即可。镜像数据本身在data_volume的registry目录下备份时优先考虑这两个目录比全量打快照省空间。最后的经验之谈Harbor 离线安装看着是个一次性工作但后续的协议切换、证书轮换、备份恢复才是真正考验人的地方。我在实际部署中最深的体会是初始配置阶段就把 HTTPS、数据目录、密码策略定好比后期来回折腾要省心得多。v2.5.0-rc1这个版本虽然整体稳定但生产环境我还是建议等正式版或者至少把rc1在测试环境跑成熟了再上生产。最后再分享一个小技巧离线包本身是很好的离线镜像源你甚至可以用它来一键部署一套 Harbor 后把常用的基础镜像推上去形成一个内部加速仓库。这样以后新机器拉镜像直接从内网仓库走速度比外网快几个量级。离线安装包的价值说到底不只是装一次 Harbor而是搭起了整个内网容器生态的底座。本文还有配套的精品资源点击获取