手把手从零到落地部署企业级私有Harbor仓库HTTPS证书

一、文档概述

1.1 文档目的

本文档为企业生产级标准部署手册，针对私有化部署的Harbor镜像仓库，从零完成SSL/TLS证书生成、HTTPS协议配置、服务重启、客户端适配、异常排查全流程落地。彻底解决Harbor默认HTTP明文传输的安全风险，满足企业容器镜像仓库安全合规、内网安全访问、K8s集群镜像拉取、CI/CD流水线对接等生产刚需场景。

文档所有步骤经过生产环境验证，适配主流Linux系统、Docker/Docker Compose、Kubernetes集群，可直接用于企业标准化落地、新人运维培训、生产环境变更上线。

1.2 适用范围

适用环境：私有化部署Harbor（2.0+全版本，离线/在线安装包）、CentOS 7/8、Ubuntu 18.04/20.04
适用场景：企业内网私有镜像仓库安全加固、K8s集群镜像仓库对接、Jenkins等CI/CD工具HTTPS访问、禁止HTTP明文传输的合规环境
适用人员：运维工程师、容器工程师、DevOps工程师、运维实习生

1.3 前置依赖

服务器已安装Docker、Docker Compose（Harbor运行必备）
已部署正常运行的私有Harbor仓库（HTTP可正常访问）
服务器可联网（可选，仅系统依赖更新使用）
拥有服务器root超级管理员权限
服务器已配置固定内网域名/IP（推荐域名访问，证书适配性更佳）

1.4 技术规范

加密协议：TLS 1.2/1.3（禁用老旧SSLv3、TLS1.0/1.1）
密钥算法：RSA 4096（企业生产安全标准）
证书有效期：10年（内网自建CA证书，规避短期过期频繁更替问题）
证书类型：自建CA根证书+服务器域名证书（适配所有内网客户端，无浏览器不信任告警）

二、环境信息规划

为统一部署标准，本文档固定环境参数，用户可根据自身实际环境替换

参数名称	说明	备注说明
Harbor服务器IP	192.48.75.165	私有内网服务器IP
Harbor访问域名	harbor.company.local	内网DNS/hosts解析域名，生产必须使用域名
Harbor安装目录	/opt/harbor	默认离线包安装路径，自定义路径需对应修改
证书存储目录	/opt/harbor/cert	专属证书目录，统一管理，权限严格管控
系统版本	Rocky Linux 10	主流企业服务器系统
Harbor版本	2.10+	全2.x版本配置逻辑通用

三、环境预处理与依赖检查

3.1 安装OpenSSL工具

OpenSSL为证书生成核心工具，系统默认预装，若无则手动安装

Rocky系统：

bash 复制代码

dnf install -y openssl openssl-devel

Ubuntu系统：

bash 复制代码

apt update && apt install -y openssl

检查版本（确认可用）：

bash 复制代码

openssl version

3.2 域名解析校验

所有客户端（Docker、K8s、浏览器）必须通过域名访问Harbor，先配置解析

1、服务端配置hosts解析

bash 复制代码

echo "192.48.75.165 harbor.company.local" >> /etc/hosts

2、测试解析连通性

bash 复制代码

ping harbor.company.local -c 2

生产建议：内网DNS服务器统一添加域名解析，无需每台机器配置hosts

四、企业级SSL/TLS证书生成（自建CA全流程）

生产内网环境推荐自建CA证书（免费、可控、永久有效、适配内网所有设备），公网环境可替换为阿里云/腾讯云可信CA证书。本节全程手动生成根证书、服务器证书，支持域名+IP双重适配。

4.1 创建证书专属目录

bash 复制代码

# 创建证书目录并授权
mkdir -p /opt/harbor/cert
chmod 700 /opt/harbor/cert
cd /opt/harbor/cert

4.2 生成CA根证书（自签名根证书）

根证书为内网信任基石，所有客户端需导入该根证书实现免信任告警访问

1、生成CA私钥（4096位加密）

bash 复制代码

# 生成CA私钥
[root@node cert]# openssl genrsa -out ca.key 4096

# 文件名
[root@node cert]# ll
total 4
-rw-------. 1 root root 3272 Aug 10 17:30 ca.key

2、生成CA根证书（有效期10年）

bash 复制代码

openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt -subj "/C=CN/ST=Beijing/L=Beijing/O=Company/OU=DevOps/CN=harbor-ca.company.local"

#  文件名
[root@node cert]# ll
total 8
-rw-r--r--. 1 root root 2074 Aug 10 17:32 ca.crt

参数说明：C=国家、ST=省份、L=城市、O=企业名称、OU=部门、CN=根证书域名，可自定义修改

4.3 生成Harbor服务器证书

核心步骤：配置SAN扩展（解决证书域名不匹配、IP访问报错问题，企业必备）

1、创建SAN扩展配置文件，支持域名+IP双重验证

2、生成Harbor服务器私钥

bash 复制代码

# 创建SAN扩展配置文件，支持域名+IP双重验证
[root@node cert]# cat > server.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = DNS:harbor.company.local,IP:192.48.75.165
EOF

bash 复制代码

# 生成Harbor服务器私钥
[root@node cert]# openssl genrsa -out server.key 4096

# 文件名
[root@node cert]# ll
total 16
-rw-------. 1 root root 3272 Aug 10 17:35 server.key

3、生成证书请求文件（CSR）

bash 复制代码

# 生成证书请求文件（CSR）
[root@node cert]# openssl req -new -key server.key -out server.csr -subj "/C=CN/ST=Beijing/L=Beijing/O=Company/OU=DevOps/CN=harbor.company.local"

# 文件名
[root@node cert]# ll
total 20
-rw-r--r--. 1 root root 1712 Aug 10 17:36 server.csr

4、CA签发服务器证书（有效期10年）

bash 复制代码

[root@node cert]#  openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650 -sha256 -extfile server.ext

# 执行结果
Certificate request self-signature ok
subject=C=CN, ST=Beijing, L=Beijing, O=Company, OU=DevOps, CN=harbor.company.local
------------------------------------------------------------------------------------

[root@node cert]# ll
total 28
-rw-r--r--. 1 root root 2163 Aug 10 17:37 server.crt

4.4 证书文件校验

执行完成后，cert目录下生成5个核心文件，确认文件存在无缺失

bash 复制代码

ll  /opt/harbor/cert

核心文件说明：

ca.crt：CA根证书（客户端信任必备）
ca.key：CA根私钥（涉密，严格保密）
server.crt：Harbor服务端证书
server.key：Harbor服务端私钥（涉密）
server.csr：证书请求文件（备用留存）

五、Harbor核心配置HTTPS（生产核心步骤）

5.1 修改Harbor配置文件

进入Harbor安装目录，编辑核心配置文件harbor.yml

bash 复制代码

cd /opt/harbor
vim harbor.yml

1、注释原有HTTP配置（必须注释，防止端口冲突、协议冲突）

bash 复制代码

# http:
#   port: 80

2、开启HTTPS配置，填写证书路径与443端口

bash 复制代码

https:
  # https port
  port: 443
  # 服务端证书文件路径
  certificate: /opt/harbor/cert/server.crt
  # 服务端私钥文件路径
  private_key: /opt/harbor/cert/server.key

3、修改hostname为配置的内网域名（必须与证书CN一致）

bash 复制代码

hostname: harbor.company.local

5.2 初始化配置并重启Harbor服务

Harbor通过prepare脚本加载证书配置，重新生成Nginx代理配置

1、停止现有Harbor服务

bash 复制代码

docker compose down

2、重新初始化配置（加载HTTPS证书）

bash 复制代码

./prepare

3、后台启动Harbor服务

bash 复制代码

docker compose up -d

4、检查容器运行状态（确保所有容器正常启动）

bash 复制代码

docker compose ps

六、服务端HTTPS有效性验证

6.1 命令行访问验证

bash 复制代码

# 验证HTTPS访问，返回200正常
curl -I https://harbor.company.local

验证会报错

如何解决呢

故障根因 ：Rocky Linux 10 系统未导入自建CA根证书、系统信任库未刷新，curl/系统层级无法识别内网自建证书签发机构，属于自建HTTPS证书最常见报错。并非证书配置错误，是系统全局证书信任缺失。

适配Rocky10 一键修复步骤（生产可用）

1、将Harbor CA根证书移入系统全局信任目录

bash 复制代码

cp /opt/harbor/cert/ca.crt /etc/pki/ca-trust/source/anchors/

2、刷新系统证书信任库（Rocky10 专属命令）

bash 复制代码

update-ca-trust extract

3、重启Docker，刷新容器层证书信任

bash 复制代码

systemctl restart docker

4、验证修复结果

bash 复制代码

curl -I https://harbor.company.local

输出以上结果，就代表成功了

6.2 浏览器访问验证

浏览器输入https://harbor.company.local，

默认输入域名是不能解析的，需要在Windows 里面配置

Shell 复制代码

# Windows 路径    注意： 需要管理员的方式才可以修改
C:\Windows\System32\drivers\etc\hosts

# 在文件中添加如下内容
192.48.75.165 harbor.company.local

修改之后，就可以用域名访问了

点击高级

然后就会进入harbor界面

虽然显示不安全，但是，真实Linux 系统中是绝对安全的

能不能显示安全呢

导入根证书后无不安全告警、可正常登录后台即为配置成功。

根证书导入方法：浏览器设置-隐私安全-证书管理-导入ca.crt，选择信任该根证书。

无痕模式下，再次打开

6.3、镜像测试

在Harbor 中创建一个项目

此时一个镜像都没有

先到官方拉取镜像

Shell 复制代码

# 先拉取镜像
[root@node ~]# docker pull nginx:1.19

# 查看镜像
[root@node ~]# docker images | grep nginx:
nginx:1.19                              df13abe416e3        197MB         53.7MB

给镜像打标签

Shell 复制代码

# 打标签
[root@node ~]# docker tag nginx:1.19 harbor.company.local/test/nginx:v1

# 检查
[root@node ~]# docker images | grep nginx:v1
harbor.company.local/test/nginx:v1      df13abe416e3        197MB         53.7MB

Docker 登录Harbor

Shell 复制代码

[root@node ~]# docker login harbor.company.local

push 镜像

Shell 复制代码

[root@node ~]# docker push harbor.company.local/test/nginx:v1

浏览器查看

再来一个 pull 镜像
- 测试之前，先删除本地镜像
  Shell 复制代码
```
[root@node ~]# docker rmi harbor.company.local/test/nginx:v1
```
  检查是否还存在
- 从本地 Harbor pull 镜像
- 终端执行
  Shell 复制代码
```
[root@node ~]# docker pull harbor.company.local/test/nginx@sha256:eba373a0620f68ffdc3f217041ad25ef084475b8feb35b992574cd83698e9e3c
```
  这里有一个小坑，直接复制就是，镜像的id ，会很长，所以建议 pull，写上版本
  Shell 复制代码
```
[root@node ~]# docker pull harbor.company.local/test/nginx:v1
```
  这样明显更好区分

七、客户端全场景适配（企业核心落地步骤）

Harbor配置HTTPS后，所有Docker客户端、K8s节点必须配置证书信任，否则镜像拉取、推送报错。

7.1 Linux Docker客户端适配

所有需要访问Harbor的Linux服务器执行以下操作

1、创建Docker证书信任目录

bash 复制代码

mkdir -p /etc/docker/certs.d/harbor.company.local

2、拷贝服务端CA根证书至客户端信任目录

3、重启Docker服务生效

bash 复制代码

systemctl restart docker

bash 复制代码

scp root@192.48.75.165:/opt/harbor/cert/ca.crt /etc/docker/certs.d/harbor.company.local/

4、测试登录与镜像推送

bash 复制代码

[root@docker ~]# docker login harbor.company.local
Username: admin
Password: 
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

---------------------------------------------------------------------------------
# 测试推送镜像
[root@docker ~]# docker tag redis:7.2 harbor.company.local/redis/redis:v7.2
[root@docker ~]# docker push harbor.company.local/redis/redis:v7.2

7.2 Kubernetes集群节点适配

所有K8s Master、Node节点均需配置证书信任，步骤同上，同时将根证书加入系统信任列表

bash 复制代码

# CentOS系统
cp ca.crt /etc/pki/ca-trust/source/anchors/
update-ca-trust

# Ubuntu系统
cp ca.crt /usr/local/share/ca-certificates/
update-ca-certificates

# 重启Docker
systemctl restart docker

八、生产环境故障排查手册

8.1 报错：x509: certificate signed by unknown authority

故障原因：客户端未导入CA根证书，未信任自建证书

解决方案：严格按照第七章客户端适配步骤，导入ca.crt并重启Docker

8.2 报错：certificate does not match hostname / IP

故障原因：SAN扩展未配置或配置错误，域名/IP与访问地址不匹配

解决方案：重新修改server.ext文件，添加对应访问域名/IP，重新签发证书并重启Harbor

8.3 浏览器访问提示不安全

故障原因：浏览器未导入根证书、证书过期、hostname配置不匹配

解决方案：导入ca.crt根证书，核对harbor.yml的hostname与证书CN一致

8.4 Harbor容器启动失败

故障原因：证书文件路径错误、文件权限过高/过低、私钥与证书不匹配

解决方案：核对harbor.yml证书路径，证书目录权限700，文件权限600，重新生成证书

8.5 核心报错：curl: (60) SSL certificate problem: unable to get local issuer certificate

适配Rocky10 一键修复步骤（生产可用）

1、将Harbor CA根证书移入系统全局信任目录

bash 复制代码

cp /opt/harbor/cert/ca.crt /etc/pki/ca-trust/source/anchors/

2、刷新系统证书信任库（Rocky10 专属命令）

bash 复制代码

update-ca-trust extract

3、重启Docker，刷新容器层证书信任

bash 复制代码

systemctl restart docker

4、验证修复结果

bash 复制代码

curl -I https://harbor.company.local

补充兜底方案（仍报错时执行）

单独给curl配置信任证书，临时兜底验证服务可用性：

bash 复制代码

curl --cacert /opt/harbor/cert/ca.crt -I https://harbor.company.local

关键注意事项 ：该报错仅影响系统本机curl、Docker、服务调用，不代表Harbor Nginx证书配置错误；所有访问该Harbor的Rocky10客户端节点，均需执行上述系统证书信任步骤。

九、企业级运维规范与安全加固

9.1 证书安全规范

CA私钥、服务端私钥禁止外传、禁止权限开放，目录权限严格设置700
证书文件定期备份，留存证书生成配置文件，便于过期更替
禁止使用过期证书、弱加密算法（RSA2048及以下）

9.2 服务运维规范

证书更新操作需走企业变更流程，停机窗口操作，更新后全客户端验证
定期巡检HTTPS状态、证书有效期，提前30天更新证书
生产环境永久关闭HTTP明文访问，杜绝安全漏洞

9.3 日志监控规范

监控Harbor Nginx证书访问日志，及时发现证书异常、非法访问请求，日志路径：/opt/harbor/logs/