一、背景与核心价值

在 Kubernetes 容器化部署中，镜像仓库的安全性与可靠性直接影响集群稳定性。Harbor 作为开源的企业级镜像仓库，提供基于角色的访问控制（RBAC）、镜像签名、漏洞扫描等功能，而 HTTPS 协议则通过 SSL/TLS 加密保障数据传输安全。KubeSphere 作为开源的容器平台，支持通过可视化界面或 YAML 配置集成外部镜像仓库。本文将重点阐述如何在 KubeSphere 3.x 版本中，通过 HTTPS 协议无缝集成 Harbor，解决企业在镜像管理中的安全合规与效率痛点。

二、前置条件与准备工作

1. 环境要求

KubeSphere 版本：3.0.0 及以上（需启用“应用商店”与“DevOps”功能）
Harbor 版本：2.0.0 及以上（支持 HTTPS 的自定义证书部署）
证书类型：需准备由受信任 CA 签发的域名证书（如 Let’s Encrypt）或自签名证书（需手动信任）

2. 证书配置

自签名证书场景

若使用自签名证书，需将证书文件（.crt）上传至 KubeSphere 节点，并执行以下操作：

# 将证书复制到系统信任目录（以Ubuntu为例）
sudo cp harbor-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

域名证书场景

若 Harbor 使用域名（如 harbor.example.com），需确保：

域名已解析至 Harbor 服务器 IP
证书的 Common Name (CN) 或 Subject Alternative Name (SAN) 包含该域名

3. 网络连通性验证

通过 curl 测试 HTTPS 访问是否正常：

curl -v https://harbor.example.com/v2/_catalog
# 预期输出：返回200状态码及镜像列表

三、KubeSphere 集成步骤

1. 登录 KubeSphere 控制台

以 admin 用户登录，进入 “平台管理” → “集群设置” → “镜像仓库”。

2. 创建镜像仓库凭证

点击 “创建”，填写以下信息：
- 凭证类型：选择 用户名密码
- 用户名/密码：Harbor 的管理员账号（如 admin/Harbor12345）
- 描述：标注为 Harbor-HTTPS-Credential
点击 “确定” 保存凭证。

3. 添加 Harbor 镜像仓库

在镜像仓库列表页，点击 “添加”，填写配置：
- 仓库名称：自定义（如 harbor-prod）
- 仓库地址：HTTPS 协议的 Harbor 地址（如 https://harbor.example.com）
- 凭证：选择上一步创建的凭证
- 认证模式：选择 Basic Auth
高级配置（可选）：
- 跳过 TLS 验证：若使用自签名证书且未配置系统信任，可勾选此项（不推荐生产环境使用）
- 代理设置：若 Harbor 通过代理访问，需填写代理地址
点击 “验证”，确认连接成功后点击 “确定”。

4. 验证集成结果

方法一：通过 KubeSphere 界面

进入 “应用管理” → “应用模板”，尝试从 Harbor 拉取镜像部署应用。
在部署表单的 “容器镜像” 字段中输入 Harbor 镜像路径（如 harbor.example.com/library/nginx:latest），若能正常解析则集成成功。

方法二：通过 Kubectl 命令行

# 创建测试Pod引用Harbor镜像
kubectl run test-nginx --image=harbor.example.com/library/nginx:latest --restart=Never
# 若Pod状态变为"Running"，则说明镜像拉取成功

四、常见问题与解决方案

1. 证书错误（`x509: certificate signed by unknown authority`）

原因：KubeSphere 节点未信任 Harbor 的自签名证书。
解决方案：
1. 将证书文件复制至所有节点的 /etc/docker/certs.d/harbor.example.com/ 目录。
2. 重启 Docker 服务：
```
sudo systemctl restart docker
```

2. 权限拒绝（`401 Unauthorized`）

原因：凭证信息错误或 Harbor 项目未授权。
解决方案：
1. 登录 Harbor 控制台，检查用户权限是否包含目标项目的 读取 权限。
2. 在 KubeSphere 中重新生成凭证并更新。

3. 连接超时（`Timeout after 30 seconds`）

原因：网络策略或防火墙阻止了 443 端口通信。
解决方案：
1. 检查 KubeSphere 节点与 Harbor 之间的网络连通性：
```
telnet harbor.example.com 443
```
2. 调整 Kubernetes 的 kubelet 配置，增加镜像拉取超时时间：
```
# 在 /etc/kubernetes/kubelet-conf.yaml 中添加
imagePullProgressDeadline: 5m
```

五、最佳实践建议

证书管理：使用自动化工具（如 Cert-Manager）动态管理 Harbor 证书，避免手动更新。
项目隔离：在 Harbor 中为不同团队创建独立项目，配合 KubeSphere 的命名空间实现权限隔离。

镜像清理：定期通过 Harbor 的 API 清理未使用的镜像，释放存储空间：

curl -X DELETE "https://harbor.example.com/api/v2.0/projects/1/repositories/library%2Fnginx/artifacts/latest" -u "admin:Harbor12345"

监控告警：通过 Prometheus + Grafana 监控 Harbor 的存储使用率与请求延迟，设置阈值告警。

六、总结

通过 HTTPS 协议集成 Harbor 镜像仓库，KubeSphere 用户可实现镜像管理的全流程安全可控。本文从环境准备、证书配置到故障排查提供了完整指导，帮助企业快速落地生产级镜像仓库解决方案。实际部署中，建议结合 CI/CD 流水线（如 Jenkins）实现镜像的自动构建与推送，进一步提升 DevOps 效率。

KubeSphere 与 Harbor 安全集成：HTTPS 协议下的镜像仓库配置指南