Linux服务器如何部署可用的Harbor镜像仓库?首次推送镜像前要配置什么

发布人:A5数据发布时间:2026-10-27 14:27阅读量:139

Harbor 的最小可用部署,核心不是把所有功能一次打开,而是先让 Linux 服务器上的 Docker、Harbor 服务、持久化目录和访问入口形成闭环。本文以 Ubuntu 22.04/24.04、单台 Linux 服务器、Docker Engine、Docker Compose Plugin 和 Harbor 离线安装包为例,部署一个使用本地存储的 Harbor 实例。

首次推送镜像前至少要配置好四项:Harbor 的可解析主机名、HTTPS 证书及客户端信任、Harbor 项目、Docker 登录凭据。推送地址必须包含项目名称,例如 harbor.example.com/demo/nginx:1.25;仅配置服务器而没有项目或证书信任,通常无法完成第一次推送。

一、准备部署环境

1. 确认适用环境

本文采用以下示例参数:

项目示例值说明
操作系统Ubuntu 22.04/24.04 x86_64其他发行版需调整 Docker 安装命令
Harbor 版本2.10.2 示例生产环境应固定经过验证的版本,不要直接使用 latest
Harbor 主机名harbor.example.com不要写 http:// 或 https://
Harbor 内网地址192.168.10.20仅为示例地址
访问端口TCP 443HTTPS 部署
数据目录/data保存镜像、数据库和 Harbor 数据
示例项目demo首次推送使用
示例镜像nginx:1.25也可以替换为已有本地镜像

小规模测试或内部团队使用时,可以先准备 4 vCPU、8 GB 内存和 SSD 存储。镜像仓库的空间需求取决于镜像层数量、镜像大小和保留策略,示例环境建议为 /data 预留至少 100 GB;这属于部署估算,不是所有场景的固定要求。

Harbor 会在同一台服务器上启动代理、核心服务、Registry、数据库、Redis、任务服务和日志服务。最小部署不需要单独准备 MySQL、Redis 或外部对象存储,但必须保证 Docker Compose 能正常运行,并为镜像数据准备持久化磁盘。

一、准备部署环境|1. 确认适用环境配图

对于需要长期运行 Harbor 的镜像仓库、容器服务和业务后台,A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器资源,覆盖常规 Xeon、AMD EPYC、大内存与 NVMe 存储配置,可为 Registry 镜像数据、数据库及多任务容器运行提供硬件基础。同时,不同地区配有相应的国际或优化线路,便于结合团队分布、访问来源和数据规模构建匹配的 Harbor 部署环境。

2. 检查主机名、磁盘和端口

先在 Harbor 服务器上检查系统版本、磁盘、内存和端口占用:

cat /etc/os-release
uname -m
free -h
df -h /
df -h /data 2>/dev/null || true
sudo ss -lntp | grep -E ':(80|443)\b' || true

预期结果:

  • 系统为 Ubuntu 22.04 或 Ubuntu 24.04;
  • 架构通常为 x86_64;
  • /data 所在文件系统有足够可用空间;
  • 80、443 端口没有被 Nginx、Apache 或其他服务占用。

如果 /data 不存在,可以创建目录。这个操作不会删除已有数据,但不要对已有生产目录执行清空或覆盖操作:

sudo install -d -m 0750 /data
df -h /data

在 DNS 尚未配置时,可以临时在客户端的 /etc/hosts 中增加解析记录。确认没有重复记录后再执行:

192.168.10.20 harbor.example.com

在客户端验证:

getent hosts harbor.example.com

预期能返回 192.168.10.20。如果解析失败,先处理 DNS 或 hosts 配置,不要急于排查 Harbor 容器。

3. 放行访问端口

如果服务器启用了 UFW,只放行实际使用的端口。修改防火墙策略前,应确认当前 SSH 来源和云平台安全组规则,避免误封管理连接。

sudo ufw status verbose
sudo ufw allow 443/tcp
sudo ufw status numbered

如果还需要通过 HTTP 提供访问,才增加 80 端口:

sudo ufw allow 80/tcp

上述命令会改变服务器入站策略。回滚时可以删除对应规则:

sudo ufw delete allow 443/tcp
sudo ufw delete allow 80/tcp

云服务器还需要在云平台安全组中放行相同端口。只修改 UFW 而忽略安全组,客户端仍可能无法连接。

二、安装 Docker Engine 和 Compose

1. 配置 Docker 软件源

如果服务器已经安装 Docker,可以直接检查版本;如果没有安装,Ubuntu 可按以下方式安装 Docker Engine 和 Compose Plugin:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

启动 Docker 并设置为开机启动:

sudo systemctl enable --now docker
sudo systemctl is-active docker

预期返回:

active

检查 Docker 和 Compose:

sudo docker version --format '{{.Server.Version}}'
sudo docker compose version
sudo docker run --rm hello-world

预期能看到 Docker 服务端版本、Compose v2 版本以及 Hello from Docker!。Harbor 不使用旧的 docker-compose 命令作为前提,本文统一使用 docker compose。

具体 Harbor 版本对 Docker Engine 和 Compose 的支持范围可能不同。固定版本后,应检查该版本随附的安装说明或兼容性要求;如果服务器上的 Docker 版本过旧,不要通过忽略检查强行安装。

三、准备 Harbor 安装包和证书

1. 下载固定版本的离线安装包

离线安装包包含 Harbor 所需的镜像,适合首次部署时减少外部依赖。下面使用 2.10.2 作为示例固定版本,实际部署时可替换为已经验证的版本:

export HARBOR_VERSION=2.10.2

cd /tmp
curl -fLO "https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/harbor-offline-installer-v${HARBOR_VERSION}.tgz"

sha256sum "harbor-offline-installer-v${HARBOR_VERSION}.tgz"

sha256sum 输出应与该版本发布页面提供的校验值进行比对。不要使用来源不明的安装包,也不要把未验证的版本直接用于生产环境。

确认 /opt/harbor 不存在或已经完成备份后再解压:

cd /tmp
tar -xzf "harbor-offline-installer-v${HARBOR_VERSION}.tgz"
sudo mv harbor /opt/harbor
sudo ls -la /opt/harbor

如果 /opt/harbor 已经存在,先停止当前 Harbor 并备份配置,不要直接覆盖目录。

2. 为 HTTPS 准备证书

生产环境建议使用企业 CA 或受信任 CA 签发的证书。证书的域名必须包含 harbor.example.com,客户端还必须信任签发该证书的 CA。

如果只是内网验证,可以使用自签名证书。下面的命令生成一个带 SAN 的示例证书:

sudo install -d -m 0750 /opt/harbor/certs

sudo openssl req -x509 -nodes -newkey rsa:4096 \
  -days 825 \
  -keyout /opt/harbor/certs/harbor.key \
  -out /opt/harbor/certs/harbor.crt \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=Example/OU=IT/CN=harbor.example.com" \
  -addext "subjectAltName=DNS:harbor.example.com,IP:192.168.10.20"

sudo chmod 600 /opt/harbor/certs/harbor.key
sudo chmod 644 /opt/harbor/certs/harbor.crt

检查证书中的主题和 SAN:

sudo openssl x509 \
  -in /opt/harbor/certs/harbor.crt \
  -noout -subject -issuer -dates -ext subjectAltName

预期至少能看到:

DNS:harbor.example.com
IP Address:192.168.10.20

如果客户端通过主机名访问,证书必须包含主机名;如果客户端通过 IP 访问,证书还应包含对应 IP。仅把主机名写入 CN、而没有写入 SAN,现代客户端通常仍会提示证书名称不匹配。

3. 让 Docker 客户端信任证书

对于企业 CA 签发的证书,应复制 CA 根证书或完整信任链中的 CA 证书。对于上面的自签名测试证书,可以把 harbor.crt 作为客户端信任证书使用。

在 Harbor 服务器上执行:

sudo install -d -m 0755 /etc/docker/certs.d/harbor.example.com
sudo cp /opt/harbor/certs/harbor.crt \
  /etc/docker/certs.d/harbor.example.com/ca.crt

sudo systemctl restart docker

systemctl restart docker 会影响该主机上的 Docker 容器,执行前应确认没有其他重要容器正在运行。远程 Docker 客户端也要执行同样的信任配置;如果 Harbor 使用非标准端口,目录名必须包含端口,例如:

/etc/docker/certs.d/harbor.example.com:8443/ca.crt

四、配置并启动 Harbor

1. 复制配置模板

进入 Harbor 目录,复制配置模板:

cd /opt/harbor
sudo cp harbor.yml.tmpl harbor.yml
sudo chmod 600 harbor.yml

使用编辑器修改配置:

sudoedit /opt/harbor/harbor.yml

至少确认以下内容。不要把 https:// 写入 hostname:

hostname: harbor.example.com

https:
  port: 443
  certificate: /opt/harbor/certs/harbor.crt
  private_key: /opt/harbor/certs/harbor.key

harbor_admin_password: "请替换为强密码"

database:
  password: "请替换为数据库密码"

data_volume: /data

这里的密码只是配置示意,部署时应替换为独立的强密码,并避免在命令行参数中直接暴露。harbor.yml 中可能还有其他模板字段,首次部署可以保留默认值;不要因为追求“完整配置”而一次打开外部数据库、对象存储、扫描器或额外服务。

对配置做基本检查:

cd /opt/harbor
sudo grep -nE '^(hostname:|harbor_admin_password:|data_volume:|https:|  port:|  certificate:|  private_key:)' harbor.yml
sudo test -r /opt/harbor/certs/harbor.crt
sudo test -r /opt/harbor/certs/harbor.key
sudo test -d /data

如果证书路径、私钥路径或数据目录检查失败,应先修正配置。

2. 执行安装

首次部署使用安装脚本:

cd /opt/harbor
sudo ./install.sh

最小可用部署先不加 --with-trivy,这样可以减少首次启动的组件和资源占用。后续如需漏洞扫描,应按照对应 Harbor 版本的方式单独启用并评估磁盘、CPU 和更新依赖。

安装成功后,检查服务状态:

cd /opt/harbor
sudo docker compose ps

预期各主要服务处于 Up 或健康状态。不同 Harbor 版本显示的容器名称和健康检查字段可能略有差异,重点检查 proxy、core、registry、portal、postgresql、redis 和 jobservice 是否持续运行。

查看监听端口:

sudo ss -lntp | grep -E ':(443)\b'

如果 443 没有监听,先检查容器状态和日志:

cd /opt/harbor
sudo docker compose logs --tail=100 proxy core registry

五、首次启动验证

1. 验证 HTTPS 和 Registry API

使用自签名证书时,测试请求需要指定证书:

curl --cacert /opt/harbor/certs/harbor.crt \
  -I https://harbor.example.com/

企业 CA 证书被系统信任后,可以直接执行:

curl -I https://harbor.example.com/

门户页面通常返回 200 或重定向响应。再检查 Registry API:

curl --cacert /opt/harbor/certs/harbor.crt \
  -sS -o /dev/null -w '%{http_code}\n' \
  https://harbor.example.com/v2/

未登录访问 /v2/ 返回 401 是正常现象,说明 HTTPS、代理和 Registry 已经连通;如果返回 404、502 或连接超时,再继续检查服务和端口。

2. 创建首个项目

浏览器访问:

https://harbor.example.com

使用配置文件中的 admin 和管理员密码登录,进入 Projects,创建项目:

项目名称:demo
可见性:Private

项目创建后,在项目列表中确认 demo 存在。Harbor 的镜像地址通常采用以下格式:

harbor.example.com/<项目名称>/<镜像名称>:<标签>

因此,demo 项目中的 Nginx 镜像地址为:

harbor.example.com/demo/nginx:1.25

项目名称缺失时,例如直接推送到 harbor.example.com/nginx:1.25,通常会因路径或权限不正确而失败。

3. 登录并推送镜像

先确认本地有待推送镜像:

sudo docker image ls

如果没有示例镜像,可以拉取一个公开镜像作为验证对象:

sudo docker pull nginx:1.25

给镜像增加 Harbor 地址和项目路径:

sudo docker tag nginx:1.25 harbor.example.com/demo/nginx:1.25
sudo docker image ls harbor.example.com/demo/nginx

登录 Harbor:

sudo docker login harbor.example.com

输入 admin 和对应密码。预期显示:

Login Succeeded

执行首次推送:

sudo docker push harbor.example.com/demo/nginx:1.25

成功时会显示各镜像层上传进度,并在结尾出现摘要或完成信息。之后可以从 Harbor 页面进入 demo 项目查看该制品。

为了验证仓库不只是“能写入”,还要执行一次拉取验证:

sudo docker pull harbor.example.com/demo/nginx:1.25
sudo docker image inspect harbor.example.com/demo/nginx:1.25 \
  --format '{{.RepoTags}}'

如果条件允许,最好从另一台已配置 DNS 和 CA 信任的 Docker 客户端执行相同的 docker login 和 docker pull。这样可以排除仅本机 hosts、缓存或本机证书配置造成的假成功。

六、首次推送前的配置核对

首次推送前,可以按以下对应关系检查:

检查项必须满足的条件验证方式
主机名客户端能解析 harbor.example.comgetent hosts harbor.example.com
网络端口客户端能访问 TCP 443curl -I https://harbor.example.com/
证书SAN 包含访问用的主机名,客户端信任 CAcurl --cacert ...
Harbor 服务proxy、core、registry 正常运行docker compose ps
项目demo 项目已经创建Harbor 页面检查
登录Docker 凭据有效docker login harbor.example.com
镜像标签包含仓库域名和项目路径docker image ls
存储/data 有可用空间df -h /data

其中,证书信任和 Docker 登录是两个不同问题。证书不受信任时,通常出现 x509: certificate signed by unknown authority;登录失败时,通常出现 unauthorized 或 denied。应根据错误位置分别处理。

七、常见失败处理

1. 出现 x509 证书错误

先确认访问地址与证书 SAN 一致:

openssl s_client -connect harbor.example.com:443 \
  -servername harbor.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -ext subjectAltName

处理顺序如下:

  1. 确认 Docker 客户端的 /etc/docker/certs.d/harbor.example.com/ca.crt 存在;
  2. 确认放入的是正确的 CA 证书,而不是另一套证书;
  3. 执行 sudo systemctl restart docker;
  4. 再执行 docker login。

不要把 docker login 改成忽略证书校验。对于生产环境,应修正证书链或客户端信任配置。

2. 出现 HTTP/HTTPS 协议不匹配

如果日志类似:

server gave HTTP response to HTTPS client

说明 Harbor 实际使用 HTTP,而 Docker 客户端按 HTTPS 访问,或者反过来。检查 harbor.yml 的 http、https 配置以及访问端口:

cd /opt/harbor
grep -nE '^(hostname:|http:|https:)|certificate:|private_key:' harbor.yml
sudo docker compose ps

推荐重新配置 HTTPS,而不是把生产环境改成不安全 Registry。

仅限隔离测试环境使用 HTTP 时,需要同时完成两件事:

  • Harbor 配置为 HTTP;
  • 每个 Docker 客户端在 /etc/docker/daemon.json 的 insecure-registries 中加入 Harbor 地址。

示例配置如下,必须与现有 JSON 合并,不能直接覆盖已有 Docker 配置:

{
  "insecure-registries": [
    "harbor.example.com"
  ]
}

修改 Docker daemon 配置会影响该主机上的 Docker 服务,执行前应备份原文件并确认容器影响范围:

sudo cp -a /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo systemctl restart docker

HTTP 模式不适合承载需要保护的镜像凭据和生产镜像。恢复时删除 insecure-registries 中的条目,恢复备份文件并再次重启 Docker。

3. 页面打不开或返回 502/503

先从外到内排查:

getent hosts harbor.example.com
curl -vk https://harbor.example.com/
sudo ss -lntp | grep -E ':(443)\b'

cd /opt/harbor
sudo docker compose ps
sudo docker compose logs --tail=100 proxy core registry

不同结果通常代表不同问题:

  • 域名无法解析:处理 DNS 或 hosts;
  • TCP 连接超时:检查云安全组、防火墙和路由;
  • 443 无监听:检查 Harbor 容器或端口冲突;
  • proxy 正常但 core、registry 重启:查看对应容器日志;
  • 页面正常但 /v2/ 返回 5xx:重点检查 registry、core 和 /data 磁盘。

如果端口被 Nginx 或 Apache 占用,不要直接停止进程。先确认其业务用途,再选择释放端口、调整 Harbor 端口或将现有反向代理正确转发到 Harbor。

4. 登录成功但推送被拒绝

确认镜像标签和项目路径:

sudo docker image ls harbor.example.com/demo/nginx

正确格式应类似:

harbor.example.com/demo/nginx   1.25

如果镜像名称中没有 demo,重新打标签:

sudo docker tag nginx:1.25 harbor.example.com/demo/nginx:1.25
sudo docker push harbor.example.com/demo/nginx:1.25

还需要确认:

  • demo 项目已经存在;
  • 登录账号拥有推送权限;
  • 使用的是同一个 Harbor 地址;
  • Docker 客户端没有登录到其他域名或端口;
  • Harbor 磁盘空间没有耗尽。

5. 容器反复重启或启动超时

检查资源和日志:

free -h
df -h /data
df -ih /data

cd /opt/harbor
sudo docker compose ps --all
sudo docker compose logs --tail=200 postgresql redis registry core

常见原因包括数据盘空间不足、数据库密码配置不一致、证书路径不可读、主机内存不足以及 80/443 端口冲突。不要直接删除 /data 重新安装,因为该目录保存 Harbor 的镜像和元数据。

八、配置变更与回滚

1. 首次部署前保留配置备份

在修改 Harbor 配置前保存一份副本:

cd /opt/harbor
sudo cp -a harbor.yml "harbor.yml.bak.$(date +%F-%H%M%S)"

证书私钥、管理员密码和数据库密码都属于敏感信息,备份文件应限制读取权限:

sudo chmod 600 /opt/harbor/harbor.yml*
sudo chmod 600 /opt/harbor/certs/harbor.key

2. 仅回滚配置,不删除镜像数据

如果只是证书路径、端口或主机名配置错误,可以恢复备份并重新生成配置:

cd /opt/harbor
sudo cp -a harbor.yml.bak.备份时间 harbor.yml
sudo ./prepare

重新生成配置会影响 Harbor 服务,先停止并再次启动容器:

sudo docker compose down
sudo docker compose up -d
sudo docker compose ps

docker compose down 会造成 Harbor 短暂不可用,默认不会删除 /data 中的镜像数据。不要使用带有删除卷或删除数据目录的命令作为常规回滚手段。

3. 取消本次失败部署

如果是全新部署且尚未推送任何镜像,可以停止 Harbor 容器并保留现场:

cd /opt/harbor
sudo docker compose down --remove-orphans
sudo mv /opt/harbor "/opt/harbor.failed.$(date +%F-%H%M%S)"

--remove-orphans 会清理当前 Compose 项目中不再声明的容器,但不会自动删除 /data。确认不再需要其中的数据后,才可以在经过备份和审批的前提下处理数据目录;生产环境不要直接执行递归删除。

4. 最终验收项

部署完成后逐项确认:

  • harbor.example.com 在所有需要推送的客户端上可解析;
  • HTTPS 证书的 SAN 与访问地址一致;
  • Docker 客户端已信任 CA;
  • sudo docker compose ps 中主要 Harbor 服务持续运行;
  • /v2/ 未登录返回 401,而不是连接失败或 5xx;
  • Harbor 中已创建目标项目;
  • docker login harbor.example.com 返回 Login Succeeded;
  • 镜像能够以 仓库域名/项目/镜像:标签 格式推送;
  • 另一台客户端能够登录并拉取该镜像;
  • /data 有足够空间,且没有把 Harbor 数据目录误当作临时目录;
  • 已保存 harbor.yml、证书、Docker 配置和防火墙变更记录。

完成这些检查后,Harbor 才具备“可访问、可登录、可推送、可拉取、数据可保留”的最小可用条件。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6064.html

相关推荐