harbor x509: certificate signed by unknown authority【20251222】

零基础完整搭建 Harbor 私有仓库（IP 访问+彻底解决 x509 错误）

结合官方文档、你的实践经验及之前的配置需求，整理一份IP 访问优先、证书链合并、客户端信任全覆盖的完整教程，从依赖安装到功能验证，零基础也能一步步落地，重点解决自签名证书导致的x509: certificate signed by unknown authority错误，同时集成 Trivy 漏洞扫描。

一、前置说明（必看）

• 适用场景：无域名，用服务器 IP 访问 Harbor（本文以192.168.90.245为例，需替换为你的服务器实际 IP）；
• 核心逻辑：通过「合并证书链（服务器证+根 CA 证）+ 客户端预置根 CA」，打通完整信任路径；
• 系统兼容：CentOS 7/8、Ubuntu 20.04+/22.04+（均提供对应命令）；
• 最终效果：Docker 登录无 x509 报错、镜像正常推送/拉取、Trivy 自动扫描漏洞。

二、Step 1：环境准备（安装依赖）

Harbor 基于 Docker 和 Docker Compose 运行，必须先完成这两个工具的安装。

1. 安装 Docker（分系统）

👉 CentOS 系统

# 卸载旧版本（如有）yum remove -y docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine# 安装依赖包yuminstall-y yum-utils device-mapper-persistent-data lvm2# 配置阿里云 Docker 源yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo# 安装指定稳定版（避免版本兼容问题）yuminstall-y docker-ce-20.10.24 docker-ce-cli-20.10.24 containerd.io# 启动并设置开机自启systemctl start docker&&systemctlenabledocker# 验证：输出版本号即成功docker --version

👉 Ubuntu 系统

# 卸载旧版本（如有）apt-getremove -y docker docker-engine docker.io containerd runc# 安装依赖包apt-getupdate&&apt-getinstall-y ca-certificatescurlgnupg lsb-release# 配置阿里云 Docker 源curl-fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg|gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpgecho"deb [arch=$(dpkg --print-architecture)signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu$(lsb_release -cs)stable"|tee/etc/apt/sources.list.d/docker.list>/dev/null# 安装指定稳定版apt-getupdate&&apt-getinstall-y docker-ce-20.10.24 docker-ce-cli-20.10.24 containerd.io# 启动并设置开机自启systemctl start docker&&systemctlenabledocker# 验证docker --version

2. 安装 Docker Compose（全系统通用）

# 下载 Docker Compose（国内源加速）curl-L"https://github.com/docker/compose/releases/download/v2.23.3/docker-compose-$(uname-s)-$(uname-m)"-o /usr/local/bin/docker-compose# 赋予执行权限chmod+x /usr/local/bin/docker-compose# 验证：输出版本号即成功docker-compose --version

三、Step 2：下载 Harbor 安装包（国内源加速）

选择稳定版v2.14.1（兼容 Trivy 最新特性，与之前配置一致）：

# 创建 Harbor 根目录mkdir-p /data/harbor&&cd/data/harbor# 下载离线安装包（阿里云源，避免官网下载慢）wgethttps://mirrors.aliyun.com/docker-hub-public/harbor/harbor-offline-installer-v2.14.1.tgz# 解压安装包tar-zxvf harbor-offline-installer-v2.14.1.tgz# 进入解压目录（后续所有配置均在此目录操作）cdharbor

四、Step 3：生成自签名证书（核心：合并证书链）

这是解决 x509 错误的关键步骤，需按顺序生成「根 CA 证书 → 服务器证书 → 合并证书链」，确保信任路径完整。

1. 创建证书工作目录

# 在 Harbor 安装目录下创建 cert 文件夹（统一管理证书）mkdir-p /data/harbor/harbor/cert&&cd/data/harbor/harbor/cert

2. 生成根 CA 证书（信任起点）

根 CA 是自签名场景的「信任锚点」，客户端必须预置此证书才能验证服务器身份：

# 1. 生成 CA 私钥（无密码，避免 Harbor 启动需输入密码）openssl genrsa -out ca.key2048# 2. 生成 CA 根证书（有效期 5000 天，适配 IP 访问）openssl req -x509 -new -nodes -key ca.key\-subj"/C=CN/ST=Beijing/L=Beijing/O=Harbor-CA/OU=DevOps/CN=Harbor-Root-CA"\-days5000\-out ca.crt

3. 生成服务器证书（Harbor 服务使用）

服务器证书需绑定 Harbor 的 IP，且由根 CA 签名，确保与客户端访问地址一致：

# 1. 生成服务器私钥openssl genrsa -out server.key2048# 2. 生成服务器证书请求（CSR，明确绑定 IP）openssl req -new -key server.key\-subj"/C=CN/ST=Beijing/L=Beijing/O=Harbor/OU=Server/CN=192.168.90.245"\-out server.csr# 3. 用根 CA 签名服务器证书（有效期 3650 天）openssl x509 -req -days3650\-in server.csr\-CA ca.crt\-CAkey ca.key\-CAcreateserial\-out server.crt

4. 合并证书链（服务器证 + 根 CA 证）

服务器端提供合并后的证书链，确保客户端在 TLS 握手时能获取完整信任路径：

# 合并命令：将服务器证书和根 CA 证书拼接为一个文件catserver.crt ca.crt>combined.crt# 验证合并结果（查看文件行数，应大于单个证书行数）wc-l server.crt ca.crt combined.crt

5. 验证证书有效性（必做！避免证书不合规）

# 1. 验证证书链完整性（输出 OK 即合规）openssl verify -CAfile ca.crt combined.crt# 2. 验证服务器证书绑定的 IP（确保与 Harbor 访问 IP 一致）openssl x509 -text -noout -in server.crt|grep"Subject.*CN"# 成功输出：Subject: C=CN, ST=Beijing, L=Beijing, O=Harbor, OU=Server, CN=192.168.90.245

五、Step 4：配置 Harbor（harbor.yml）

基于官方模板修改核心配置，重点绑定 IP、证书链和启用 Trivy。

1. 复制默认配置文件

# 进入 Harbor 安装目录cd/data/harbor/harbor# 复制官方模板为正式配置文件cpharbor.yml.tmpl harbor.yml

2. 编辑配置文件（核心参数修改）

vimharbor.yml

保留以下关键配置（其他参数默认即可，按实际 IP 替换）：

# 1. Harbor 访问地址（必须是证书绑定的 IP）hostname:192.168.90.245# 2. HTTP 配置（默认 80 端口，可保留，访问时会自动跳转 HTTPS）http:port:80# 3. HTTPS 配置（核心！绑定合并后的证书链）https:port:443certificate:/data/harbor/harbor/cert/combined.crt# 合并后的证书链private_key:/data/harbor/harbor/cert/server.key# 服务器私钥# 4. 管理员初始密码（首次登录使用，后续建议修改）harbor_admin_password:Harbor12345# 5. 数据存储目录（默认即可，镜像、漏洞库等数据存于此）data_volume:/data/harbor/data# 6. Trivy 漏洞扫描配置（自动启用，无需额外安装）trivy:enabled:trueignore_unfixed:trueseverity:["CRITICAL","HIGH"]timeout:10mdb_repository:registry.cn-hangzhou.aliyuncs.com/acs/trivy-db# 国内源，避免下载超时

六、Step 5：安装并启动 Harbor

1. 生成 Harbor 配置文件

# 执行 prepare 脚本，根据 harbor.yml 生成部署配置./prepare

2. 启动 Harbor（后台运行）

# 用 Docker Compose 启动所有组件（-d 表示后台运行）docker-compose up -d# 验证启动状态（所有容器状态为 Up 即成功）docker-composeps

3. 访问 Harbor 控制台（验证服务器端正常）

打开浏览器，输入https://192.168.90.245（注意是 HTTPS）：

• 登录账号：admin
• 登录密码：Harbor12345
• 成功标志：无证书警告（或仅提示「自签名证书」，可忽略），能进入 Harbor 管理界面。

七、Step 6：客户端信任配置（彻底解决 x509 错误）

客户端（需要推送/拉取镜像的机器）必须预置根 CA 证书，才能信任 Harbor 的自签名证书链。

👉 Linux 客户端（CentOS/Ubuntu 通用）

# 1. 先获取根 CA 证书（从 Harbor 服务器复制 ca.crt 到客户端，示例用 scp 命令）scproot@192.168.90.245:/data/harbor/harbor/cert/ca.crt ./# 2. 安装根 CA 到系统信任库（确保系统级信任）## CentOS 系统cpca.crt /etc/pki/ca-trust/source/anchors/harbor-ca.crt update-ca-trust extract## Ubuntu 系统cpca.crt /usr/local/share/ca-certificates/harbor-ca.crt update-ca-certificates# 3. 配置 Docker 单独信任（关键！Docker 有独立的证书信任机制）# 创建 Docker 信任目录（格式：/etc/docker/certs.d/HarborIP:端口）mkdir-p /etc/docker/certs.d/192.168.90.245:443# 复制根 CA 到该目录，文件名必须为 ca.crt（Docker 固定读取）cpca.crt /etc/docker/certs.d/192.168.90.245:443/ca.crt# 4. 赋予证书读取权限（避免 Docker 无权限访问）chmod644/etc/docker/certs.d/192.168.90.245:443/ca.crt# 5. 重启 Docker 生效配置systemctl restart docker# 6.daemon.json配置Harbor服务器的IP或者域名[root@swarm43 ~]# cat /etc/docker/daemon.json{"registry-mirrors":["https://672tq9h17eavbw.xuanyuan.run","https://672tq9h17eavbw.xuanyuan.dev","https://docker.xuanyuan.me"],"insecure-registries":["192.168.90.245","672tq9h17eavbw.xuanyuan.run","672tq9h17eavbw.xuanyuan.dev","docker.xuanyuan.me"],"dns":["119.29.29.29","114.114.114.114"]}

👉 注意事项

• 若客户端与 Harbor 服务器是同一台机器，无需用scp，直接使用ca.crt路径即可；
• 登录时若仍报错，尝试加sudo（Docker 权限问题）：sudo docker login 192.168.90.245。

八、Step 7：功能验证（全流程测试）

1. Docker 登录 Harbor（验证 x509 错误已解决）

# 登录命令（无端口时默认访问 443）docker login192.168.90.245 -u admin -p Harbor12345# 成功标志：Login Succeeded（无任何 x509 报错）

2. 推送镜像到 Harbor（验证仓库功能）

# 1. 拉取一个测试镜像（如 nginx）docker pull nginx:alpine# 2. 给镜像打标签（格式：HarborIP/项目名/镜像名:版本）# 注意：Harbor 需先创建项目（如 test-project，公开项目即可）docker tag nginx:alpine192.168.90.245/test-project/nginx:alpine# 3. 推送镜像docker push192.168.90.245/test-project/nginx:alpine# 成功标志：推送进度条完成，输出 digest 和 size 信息

3. Trivy 漏洞扫描（验证安全功能）

1. 登录 Harbor 控制台，进入test-project项目；
2. 找到推送的nginx:alpine镜像，点击右侧「扫描」按钮；
3. 扫描完成后，查看「漏洞」标签页，会显示CRITICAL/HIGH级别的漏洞（Trivy 正常工作）。

九、常见问题排查（避坑指南）

1. 登录仍报错x509: certificate signed by unknown authority

• 检查客户端是否复制了ca.crt到 Docker 信任目录，且文件名是ca.crt；
• 检查 Docker 是否重启：systemctl restart docker；
• 尝试用sudo登录：sudo docker login 192.168.90.245。

2. Harbor 启动失败（部分容器 Exited）

• 检查证书路径是否正确（harbor.yml中certificate和private_key路径）；
• 检查证书权限：chmod 600 /data/harbor/harbor/cert/server.key（私钥必须 600 权限）；
• 查看日志排查：docker-compose logs -f core（查看核心组件日志）。

3. Trivy 扫描无结果（或扫描失败）

• 检查 Trivy 容器是否启动：docker-compose ps trivy；
• 查看 Trivy 日志：docker-compose logs -f trivy；
• 若漏洞库下载超时，手动下载国内源漏洞库：

  mkdir-p /data/harbor/data/trivy/dbwget-O /data/harbor/data/trivy/db/trivy.db https://registry.cn-hangzhou.aliyuncs.com/acs/trivy-db/trivy.db:latestwget-O /data/harbor/data/trivy/db/metadata.json https://registry.cn-hangzhou.aliyuncs.com/acs/trivy-db/metadata.json:latestchmod-R777/data/harbor/data/trivy/db docker-compose restart trivy

十、总结

本教程通过「合并证书链（服务器端）+ 预置根 CA（客户端）」彻底解决了自签名证书的 x509 错误，同时集成了 Trivy 漏洞扫描，实现了 Harbor 从搭建到实用的全流程。

核心要点：

1. 证书链合并是服务器端的关键，确保客户端获取完整信任路径；
2. 客户端需同时配置「系统信任库 + Docker 信任目录」，避免 Docker 独立信任机制导致的问题；
3. 所有 IP 需保持一致（Harbor 配置、证书绑定、客户端访问），是避免错误的基础。

按此流程操作后，你将拥有一个稳定、安全的私有镜像仓库，支持镜像推送/拉取和自动漏洞扫描，可直接用于测试或生产环境。