一、引言：为什么需要 HTTPS 集成 Harbor？

在容器化部署日益普及的今天，镜像仓库的安全性与管理效率成为企业关注的重点。Harbor 作为开源的企业级镜像仓库解决方案，提供基于角色的访问控制、镜像复制、漏洞扫描等功能，而 KubeSphere 作为多云多集群的容器管理平台，支持通过 HTTPS 协议安全地集成 Harbor，实现镜像的集中存储与分发。

核心价值：

数据安全：HTTPS 加密传输防止镜像拉取过程中的数据泄露。
合规性：满足金融、政府等行业对数据传输加密的强制要求。
管理效率：通过 KubeSphere 统一管理多集群镜像，简化运维流程。

本文将分步骤详解集成过程，并提供常见问题解决方案。

二、前置条件与准备工作

1. 环境要求

KubeSphere 版本：v3.3.0 及以上（支持 HTTPS 仓库的完整功能）。
Harbor 版本：v2.0 及以上（需启用 HTTPS 并配置有效证书）。
网络连通性：KubeSphere 集群节点需能访问 Harbor 的 HTTPS 端口（默认 443）。

2. 证书准备

Harbor 的 HTTPS 证书需为受信任的 CA 签发证书或自签名证书（需手动配置信任）。推荐使用 Let’s Encrypt 免费证书或企业内网 CA。

证书文件要求：

证书文件（.crt 或 .pem）
私钥文件（.key）
可选：CA 根证书（用于自签名证书场景）

3. Harbor 配置检查

HTTPS 启用：在 Configuration > HTTPS 中勾选 Enable HTTPS。
域名配置：确保 Harbor 的域名（如 harbor.example.com）已解析至正确 IP。
项目权限：提前创建 KubeSphere 使用的 Harbor 项目，并分配 拉取镜像 权限。

三、KubeSphere 集成 Harbor 的详细步骤

步骤 1：将证书上传至 KubeSphere 节点

若使用自签名证书，需将证书添加至 KubeSphere 节点的信任链。以 Ubuntu 系统为例：

# 将证书文件复制到节点
sudo cp harbor.crt /usr/local/share/ca-certificates/
# 更新证书缓存
sudo update-ca-certificates

验证证书是否生效：

openssl s_client -connect harbor.example.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -noout -issuer

步骤 2：在 KubeSphere 中添加 Harbor 仓库

登录 KubeSphere 控制台，进入 集群管理 → 镜像仓库。
点击创建，选择 HTTPS 协议，填写以下信息：
- 仓库名称：自定义（如 prod-harbor）。
- 仓库地址：https://harbor.example.com（需包含 https:// 前缀）。
- 认证信息：
  - 用户名/密码：Harbor 中具有拉取权限的账号。
  - 访问令牌（可选）：若使用 Token 认证，填写 Harbor 生成的 Token。
高级设置（可选）：
- 跳过 TLS 验证：仅用于测试环境（生产环境禁用）。
- 代理设置：若通过代理访问 Harbor，填写代理地址。

步骤 3：验证仓库连接

在 KubeSphere 中创建一个测试项目，进入 应用负载 → 工作负载。

部署一个使用 Harbor 镜像的 Pod，例如：

apiVersion: v1
kind: Pod
metadata:
name: nginx-test
spec:
containers:
- name: nginx
 image: harbor.example.com/library/nginx:latest
 ports:
 - containerPort: 80

检查 Pod 状态，若显示 Running 则表示集成成功。

四、常见问题与解决方案

问题 1：证书验证失败

现象：添加仓库时提示 x509: certificate signed by unknown authority。
原因：KubeSphere 节点未信任 Harbor 的证书。
解决方案：

确认证书已正确上传至节点（参考步骤 1）。

重启 KubeSphere 相关服务：

kubectl rollout restart deployment ks-apiserver -n kubesphere-system

问题 2：权限不足

现象：Pod 拉取镜像时提示 denied: requested access to the resource is denied。
原因：Harbor 账号未分配对应项目的 拉取 权限。
解决方案：

登录 Harbor，进入目标项目 → 成员 → 添加成员。
为 KubeSphere 使用的账号分配 Guest 或更高权限。

问题 3：网络不通

现象：添加仓库时提示 connection refused。
排查步骤：

检查 Harbor 服务是否运行：
```
curl -v https://harbor.example.com
```
确认防火墙规则允许 443 端口：
```
sudo ufw status | grep 443
```
检查 KubeSphere 节点能否解析 Harbor 域名：
```
ping harbor.example.com
```

五、高级配置：镜像拉取策略优化

1. 使用镜像拉取密钥（Secret）

对于需要频繁拉取镜像的场景，建议创建 Kubernetes Secret 避免重复输入密码：

kubectl create secret docker-registry harbor-secret \
  --docker-server=harbor.example.com \
  --docker-username=<username> \
  --docker-password=<password> \
  --namespace=<namespace>

在 Pod 定义中引用该 Secret：

spec:
  imagePullSecrets:
  - name: harbor-secret

2. 镜像缓存加速

在 KubeSphere 集群中部署镜像缓存服务（如 Dragonfly），减少对 Harbor 的直接拉取压力。

六、总结与最佳实践

1. 安全建议

定期轮换 Harbor 账号密码。
限制 Harbor 项目的公开访问权限。
监控镜像拉取日志，及时发现异常行为。

2. 运维优化

使用 Harbor 的复制功能实现多地域镜像同步。
结合 KubeSphere 的告警策略，监控镜像拉取失败事件。

3. 扩展场景

多集群镜像共享：通过 KubeSphere 的多集群管理功能，将一个集群的 Harbor 镜像同步至其他集群。
CI/CD 集成：在 Jenkins 或 GitLab CI 中配置 KubeSphere 的 Harbor 仓库作为镜像构建目标。

通过本文的指导，您已掌握 KubeSphere 与 Harbor 通过 HTTPS 集成的完整流程。这一方案不仅提升了镜像传输的安全性，还为企业容器化部署提供了高效的管理手段。

KubeSphere 与 Harbor：HTTPS 集成镜像仓库全攻略