如何在香港服务器部署Harbor镜像仓库,并验证镜像推送与拉取?
香港服务器部署 Harbor 的核心流程是准备可访问的域名和 HTTPS 证书,安装 Docker Engine 与 Compose 插件,配置并启动 Harbor,再从客户端完成镜像推送和拉取验证。香港机房不会改变 Harbor 的安装方式;需要额外确认的是域名解析、服务器防火墙和云平台安全组是否允许客户端访问,以及服务器到镜像源的出站网络是否可用。
以下以一台运行 Ubuntu 22.04 或 24.04 的香港服务器为例,使用 Harbor 在线安装包、Harbor 内置 Nginx 和 HTTPS 入口。示例域名为 harbor.example.com,请替换成自己持有并已解析到服务器公网 IP 的域名。生产环境不建议将 Harbor 作为无证书的公网 HTTP 服务使用。
A5idc数据提供中国香港物理服务器租用,覆盖入门建站、Xeon Gold与AMD EPYC等配置,并配备SSD或NVMe存储及CN2、国际带宽等线路选择,可为Harbor镜像仓库提供容器运行、镜像分发和业务后台所需的计算、磁盘与网络资源。针对镜像数量、项目规模及访问区域不同,也可结合多核处理器、大内存和存储型服务器构建相应的仓库资源基础。
一、准备服务器、域名和证书
部署前确认以下条件:

- 服务器具备管理员权限,建议至少预留 2 核 CPU、4 GB 内存和 40 GB 磁盘。镜像和日志会持续占用磁盘,实际容量应按镜像大小、版本保留策略和预计增长量规划;镜像较多时应配置更大的数据盘。
- 域名
harbor.example.com的 A 记录指向服务器公网 IP。若使用 AAAA 记录,也要确认服务器和客户端的 IPv6 访问路径正常。 - 准备有效的 TLS 证书及其私钥。证书的 SAN 必须包含
harbor.example.com;使用完整证书链,并确认证书与私钥匹配。 - 安全组和服务器防火墙允许管理用 SSH 端口,以及 Harbor 的 TCP 443。TCP 80 可按需要开放,用于证书签发或 HTTP 到 HTTPS 的跳转;如果不开放,应确认所用证书签发和续期方式不依赖该端口。
- 服务器可以访问用于下载 Harbor 安装包的外部地址。客户端需要能访问 Harbor 域名的 TCP 443;客户端是否能访问镜像源取决于所用基础镜像从哪里获取。
先在服务器核对系统、磁盘和解析结果:
lsb_release -a
df -hT
getent ahosts harbor.example.com
getent 应返回服务器预期的公网 IP。若返回旧 IP、无结果或地址不符,应先修正 DNS,再继续配置证书和安装。
把证书文件放到服务器的固定目录,例如:
sudo install -d -m 0750 /etc/harbor/certs
sudo install -m 0644 fullchain.pem /etc/harbor/certs/harbor.crt
sudo install -m 0600 privkey.pem /etc/harbor/certs/harbor.key
这里的 fullchain.pem 和 privkey.pem 是证书签发方提供的文件名示例。私钥只应由管理员和 Harbor 服务所需的部署流程读取,不要将私钥提交到代码仓库或公开目录。
可使用 OpenSSL 检查证书有效期和 SAN:
openssl x509 -in /etc/harbor/certs/harbor.crt -noout -dates -ext subjectAltName
证书到期时间应在有效期内,SAN 列表应包含 DNS:harbor.example.com。如需确认公钥匹配,可分别计算证书和私钥的公钥摘要;两条命令输出应一致:
openssl x509 -in /etc/harbor/certs/harbor.crt -pubkey -noout \
| openssl pkey -pubin -outform DER \
| sha256sum
openssl pkey -in /etc/harbor/certs/harbor.key -pubout -outform DER \
| sha256sum
二、安装 Docker 并开放入口端口
Harbor 使用容器运行。先确认系统没有已有的生产容器编排或 Docker 配置需要保留;如果机器已经运行 Docker,应先检查现有容器、网络和数据目录,避免调整服务时影响其他业务。
Ubuntu 可按 Docker 官方仓库安装 Docker Engine 和 Compose 插件。安装前应依据当前 Ubuntu 版本配置相应的软件仓库,随后安装以下软件包:
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
若软件包无法定位,先检查 Docker 仓库是否为当前 Ubuntu 版本正确配置,不要通过来源不明的脚本绕过安装错误。安装完成后启用服务并验证版本:
sudo systemctl enable --now docker
sudo systemctl is-active docker
docker --version
docker compose version
systemctl is-active 应返回 active,并且后两条命令能显示版本信息。Harbor 部署需要可用的 Docker Compose 插件;若 docker compose version 不可用,应先解决插件安装问题。
在云平台安全组中放行 TCP 443,并根据需要放行 TCP 80。若使用 UFW,可在确认 SSH 规则已放行后配置:
sudo ufw allow OpenSSH
sudo ufw allow 443/tcp
sudo ufw allow 80/tcp
sudo ufw status verbose
上述规则会开放相应端口,应用前应根据管理入口和网络策略调整。若 SSH 不使用默认端口,需先放行实际 SSH 端口,避免启用防火墙后失去远程管理能力。Docker 会管理自身的网络规则,UFW 规则不能替代云平台安全组的检查;应同时核对两处配置,不要因端口仍不可达而直接关闭防火墙。
三、下载并配置 Harbor 安装包
选择与服务器架构兼容的 Harbor 发布版本,并从 Harbor 官方发布页面获取对应的在线安装包。生产环境应固定具体版本,不要在自动化脚本里使用含义不明确的“最新版”。在线安装包启动时需要从镜像源拉取 Harbor 组件镜像;服务器无法访问这些镜像源时,应评估离线安装包和离线导入流程。
下面用变量表示已选定的版本号,下载地址需按该版本发布页面提供的资产名称核对:
export HARBOR_VERSION='2.x.y'
curl -fL -o "harbor-online-installer-${HARBOR_VERSION}.tgz" \
"https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/harbor-online-installer-v${HARBOR_VERSION}.tgz"
将 2.x.y 替换为已核实存在的版本号。下载后应按发布页面提供的校验和或签名验证安装包,再解压。以下仅在文件名与实际下载文件一致时使用:
sha256sum harbor-online-installer-"${HARBOR_VERSION}".tgz
tar -xzf harbor-online-installer-"${HARBOR_VERSION}".tgz
cd harbor
sha256sum 的输出用于与发布方公布的校验值比对;仅生成摘要而不比对,不能证明文件完整。解压后确认目录中存在 harbor.yml.tmpl 和 install.sh:
test -f harbor.yml.tmpl && test -x install.sh && echo "安装文件已就绪"
复制配置模板并编辑:
cp harbor.yml.tmpl harbor.yml
sudoedit harbor.yml
按实际环境修改配置文件中对应字段。以下是需要重点核对的配置示例;安装包模板可能包含其他必填项,应保留模板结构并按注释补全,不要用这段内容覆盖整个文件:
hostname: harbor.example.com
https:
port: 443
certificate: /etc/harbor/certs/harbor.crt
private_key: /etc/harbor/certs/harbor.key
harbor_admin_password: "替换为独立的强密码"
data_volume: /data/harbor
配置要点如下:
hostname必须与客户端访问的域名和证书 SAN 一致,不要填写https://前缀。- HTTPS 端口应与安全组、防火墙和客户端访问端口一致。使用默认 443 时,访问地址无需显式写端口。
- 证书和私钥路径必须存在,并且部署进程可读取。
harbor_admin_password是初始管理员密码,应使用独立的强密码。部署后按组织的凭据管理要求保存,不要把它写进公开脚本或长期保存在命令历史中。data_volume是 Harbor 数据的持久化位置。若/data位于独立数据盘,应先挂载并确认重启后仍会自动挂载,再进行安装。
检查配置文件中是否还有模板要求填写的数据库密码或其他初始凭据。若有,应一并替换为独立的强密码。配置文件可能包含明文凭据,建议限制读取权限:
chmod 600 harbor.yml
检查目标目录所在文件系统和剩余空间:
df -hT /data
若 /data 尚不存在,应先按服务器实际磁盘布局创建并挂载数据盘,再执行安装。不要在空间不足或挂载未生效时继续部署,否则 Harbor 可能把数据写入系统盘。
四、安装、启动并检查服务
先运行配置准备脚本,再启动 Harbor:
sudo ./prepare
sudo ./install.sh
prepare 会根据 harbor.yml 生成 Harbor 所需的容器配置。若运行失败,先查看输出中具体的配置项、证书路径或权限错误,不要在未修正原因时反复执行。install.sh 完成后,检查容器状态:
sudo docker compose ps
Harbor 相关容器应处于运行状态。若有容器反复退出,进一步查看服务日志:
sudo docker compose logs --tail=100
也可按服务名称查看某个组件,例如:
sudo docker compose logs --tail=100 core
sudo docker compose logs --tail=100 nginx
服务名称可能随 Harbor 版本或 Compose 配置变化;若提示找不到服务,先用 docker compose ps --services 查看实际服务名。
从服务器检查 HTTPS 入口:
curl -fsS https://harbor.example.com/api/v2.0/ping
若返回 Pong,表示 HTTPS 入口和 Harbor API 已能响应。若命令提示证书校验失败,不要用 -k 作为生产环境的长期解决办法;应检查证书链、域名 SAN、系统时间和客户端信任链。也可以从另一台客户端执行同一命令,确认公网路径和云平台安全组规则正常。
使用浏览器访问 https://harbor.example.com,登录后检查项目页面。首次登录使用用户名 admin 和配置的初始密码。若页面无法打开,可先比较服务器本机和外部客户端的 curl 结果:本机可访问而外部不可访问,通常应优先核对 DNS、安全组和服务器防火墙;两处都不可访问,则继续检查 Harbor 容器状态、监听端口和证书配置。
五、创建项目并验证镜像推送、拉取
在 Harbor 页面中创建测试项目,例如 demo。私有项目通常需要登录后才能拉取;如需公开访问,应根据数据敏感性和组织策略决定,不要为了简化测试而将生产镜像仓库设为公开。
在一台 Docker 客户端上先确认能解析并访问 Harbor,再登录。命令会交互式提示输入密码:
docker login harbor.example.com
成功时通常会看到 Login Succeeded。不要把密码直接写在命令参数中,因为它可能进入 shell 历史或进程列表。用于自动化部署的账号应遵循最小权限原则,并通过安全的凭据存储机制提供认证信息。
准备一份测试镜像并打上 Harbor 地址和项目路径标签:
docker pull alpine:3.20
docker tag alpine:3.20 harbor.example.com/demo/alpine:test
确认本地存在目标标签:
docker image ls harbor.example.com/demo/alpine
执行推送:
docker push harbor.example.com/demo/alpine:test
推送成功后,终端应显示镜像层上传或已存在,并完成镜像摘要记录。回到 Harbor 页面打开 demo 项目,应能看到仓库 alpine 和标签 test。若项目名、仓库名或标签不同,检查镜像标签中的路径是否为 harbor.example.com/demo/alpine:test。
随后在同一客户端拉取刚推送的镜像:
docker pull harbor.example.com/demo/alpine:test
成功时 Docker 会显示下载或复用各层,并报告镜像摘要。为避免本机缓存造成“拉取成功但未实际重新获取”的误判,可在另一台已登录 Harbor 的 Docker 客户端执行拉取。若必须在同一台机器验证,可先确认镜像数据已经安全上传,再只删除本地测试标签后重新拉取;这会影响该客户端的本地镜像缓存,不会删除 Harbor 上的远端镜像:

docker image rm harbor.example.com/demo/alpine:test
docker pull harbor.example.com/demo/alpine:test
推送和拉取都通过,且 Harbor 页面能看到目标仓库和标签,说明基础链路已验证。测试镜像本身不代表业务镜像构建流程、镜像扫描策略或 CI 凭据配置已经完成。
六、常见失败及处理顺序
域名无法解析或连接超时。 先在客户端检查 DNS 返回地址,再检查云平台安全组、服务器防火墙和 443 端口监听。域名解析正确但外部连接超时,通常与网络入口配置或监听状态有关;不要先改 Harbor 配置。
getent ahosts harbor.example.com
sudo ss -lntp | grep -E ':(80|443)\b'
若没有 443 监听,检查 Harbor 容器是否启动及 Nginx 日志;若服务器监听正常但公网不通,再检查安全组、路由和客户端出口策略。
证书错误或 Docker 提示证书不受信任。 检查客户端访问的域名是否与证书 SAN 一致、证书是否过期、证书链是否完整,以及客户端系统的 CA 信任库是否正常。私有 CA 签发的证书需要将对应 CA 证书按客户端系统的方式加入信任链。不要将证书校验关闭作为正式解决方案。
Docker 登录失败。 unauthorized 通常表示账号、密码或项目权限有误;先确认项目存在、登录凭据正确,再核对 Harbor 用户和项目角色。若提示连接被拒绝或超时,应转向检查 DNS、端口和入口服务,而不是重复更换密码。
Docker 报 server gave HTTP response to HTTPS client。 这通常意味着客户端连接到的入口没有按预期提供 HTTPS,或域名指向了错误的服务、端口或负载均衡地址。核对 hostname、HTTPS 证书配置、DNS 和入口转发。不要通过将公网仓库长期设置为 Docker 的不安全 HTTP 仓库来掩盖配置问题。
安装后容器反复退出或磁盘空间不足。 查看 docker compose ps 和组件日志,并检查数据盘空间、挂载状态、证书路径和配置文件格式。若 data_volume 所在目录没有挂载到预期磁盘,应先停止排查并确认数据写入位置,避免继续占用系统盘。
七、验收与回滚检查项
上线前逐项核对:
- 域名解析到预期服务器地址,证书 SAN 与 Harbor 域名一致,证书有效且私钥未公开。
- 云平台安全组和服务器防火墙只开放实际需要的入口,SSH 管理端口仍可访问。
- Harbor 容器状态正常,HTTPS API 返回有效响应,浏览器无证书错误。
- 测试项目中能看到推送的仓库和标签;Docker 客户端能够登录、推送并拉取该镜像。
- Harbor 数据目录位于预期的持久化磁盘,磁盘空间足够;管理员密码和业务账号按凭据管理要求保存。
首次部署若未通过验收,优先修正配置并重新执行 Harbor 提供的配置准备和启动流程。需要停止服务时,在 Harbor 安装目录执行:
sudo docker compose down
该命令会停止并移除当前 Compose 创建的容器和网络;不要追加 -v,也不要删除 data_volume 指定的数据目录,否则会丢失 Harbor 镜像、项目及相关持久化数据。回滚前记录当前配置并备份 harbor.yml、证书和 Harbor 数据目录;恢复时确认备份对应的 Harbor 版本和数据状态,再按该版本的部署流程启动。若服务已对外提供业务镜像,停止 Harbor 会中断推送和拉取,应先通知依赖方并安排维护窗口。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/7342.html
