一、背景与需求分析

在容器化部署场景中，Harbor 作为企业级镜像仓库已成为 Kubernetes 生态的核心组件。通过 HTTPS 协议集成 Harbor 不仅能保障镜像传输的安全性，还能满足金融、医疗等行业的合规要求。KubeSphere 作为开源的容器管理平台，其可视化界面与 Harbor 的深度集成可显著降低运维复杂度。

1.1 安全风险警示

未加密的 HTTP 协议存在三大隐患：

镜像数据明文传输易被篡改
登录凭证可能被中间人窃取
仓库元数据面临泄露风险

1.2 集成价值体现

HTTPS 集成带来四方面提升：

数据传输层安全（TLS 1.2+）
双向身份认证机制
审计日志完整性保障
符合等保2.0三级要求

二、前置条件准备

2.1 环境要求

组件	版本要求	配置建议
KubeSphere	v3.3.0+	启用 DevOps 功能模块
Harbor	v2.4.0+	配置独立域名并启用 HTTPS
Kubernetes	v1.20+	确保 CoreDNS 正常运行
证书	RSA 2048/ECDSA 256	推荐使用 Let’s Encrypt 或 CA

2.2 证书配置指南

2.2.1 自签名证书生成

# 生成 CA 私钥
openssl genrsa -out ca.key 2048
# 创建 CA 证书
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt \
  -subj "/C=CN/ST=Beijing/L=Haidian/O=DevOps/CN=Harbor-CA"
# 生成服务器证书
openssl genrsa -out harbor.key 2048
openssl req -new -key harbor.key -out harbor.csr \
  -subj "/C=CN/ST=Beijing/L=Haidian/O=DevOps/CN=harbor.example.com"
# 签发证书
openssl x509 -req -in harbor.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out harbor.crt -days 3650 -sha256

2.2.2 证书部署要点

将 harbor.crt 和 harbor.key 部署至 Harbor 服务器的 /etc/harbor/ssl/ 目录

修改 Harbor 的 harbor.yml 配置文件：

https:
certificate: /etc/harbor/ssl/harbor.crt
private_key: /etc/harbor/ssl/harbor.key

重启 Harbor 服务：
```
docker-compose down
docker-compose up -d
```

三、KubeSphere 集成配置

3.1 创建镜像仓库凭证

登录 KubeSphere 控制台，进入「配置中心」→「密钥」
创建类型为「镜像仓库密钥」的新条目：
- 密钥名称：harbor-credential
- 仓库地址：https://harbor.example.com
- 用户名：admin（建议使用专用机器人账号）
- 密码：对应账号的密码或 Token

3.2 添加镜像仓库

进入「平台管理」→「镜像仓库」
点击「添加镜像仓库」，填写以下信息：
- 名称：harbor-https
- 地址：https://harbor.example.com
- 凭证：选择上一步创建的 harbor-credential
- 验证 SSL 证书：根据实际证书情况选择

3.3 项目级配置

在具体项目中可通过「项目设置」→「镜像仓库」添加仓库，支持：

配置命名空间映射
设置镜像拉取策略
定义镜像扫描规则

四、高级配置与优化

4.1 双向 TLS 认证

生成客户端证书：

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
-subj "/C=CN/ST=Beijing/L=Haidian/O=DevOps/CN=kubesphere-client"
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-out client.crt -days 3650 -sha256

将客户端证书转换为 PKCS12 格式：

openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12 -name "kubesphere"

在 KubeSphere 节点配置证书：

mkdir -p /etc/docker/certs.d/harbor.example.com
cp ca.crt /etc/docker/certs.d/harbor.example.com/
systemctl restart docker

4.2 性能优化建议

启用 Harbor 的缓存代理：

# 在 harbor.yml 中配置
proxy:
cache_enabled: true
cache_ttl: 1440

配置 KubeSphere 的镜像拉取并发数：

# 修改 kubelet 配置
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
imageGCHighThresholdPercent: 85
evictionHard:
imagefs.available: "15%"

五、故障排查指南

5.1 常见问题处理

现象	可能原因	解决方案
证书验证失败	CA 证书未正确部署	检查 `/etc/docker/certs.d/` 目录
403 Forbidden 错误	权限配置错误	检查 Harbor 项目成员权限
连接超时	网络策略限制	检查 Kubernetes NetworkPolicy
镜像拉取缓慢	带宽限制或代理配置不当	优化 Harbor 缓存策略

5.2 日志分析技巧

Harbor 服务日志：
```
docker-compose logs -f registry
```

KubeSphere 审计日志：

kubectl logs -n kubesphere-system $(kubectl get pods -n kubesphere-system | grep ks-apiserver | awk '{print $1}') | grep "image repository"

Docker 守护进程日志：
```
journalctl -u docker --no-pager -n 100
```

六、最佳实践建议

证书管理：
- 定期轮换证书（建议每90天）
- 建立证书吊销列表（CRL）机制
- 使用自动化工具（如 cert-manager）管理证书生命周期
权限控制：
- 遵循最小权限原则分配 Harbor 角色
- 为不同项目创建独立的机器人账号
- 启用 Harbor 的审计日志功能
性能监控：
- 部署 Prometheus 监控 Harbor 指标
- 设置镜像拉取失败告警规则
- 定期分析镜像存储使用情况
灾备方案：
- 配置 Harbor 的定期备份策略
- 建立异地双活架构
- 测试镜像仓库故障转移流程

通过以上步骤，企业可以在 KubeSphere 环境中安全、高效地使用 HTTPS 协议集成 Harbor 镜像仓库。这种集成方式不仅提升了数据传输的安全性，还通过 KubeSphere 的可视化界面简化了镜像管理流程，特别适合金融、政务等对安全性要求较高的行业场景。实际部署时，建议先在测试环境验证配置，再逐步推广到生产环境。

KubeSphere 与 Harbor HTTPS 集成全攻略