一、背景与需求分析

在容器化部署环境中，镜像仓库的安全性直接关系到整个应用交付链的可靠性。Harbor 作为开源的企业级镜像仓库解决方案，通过 HTTPS 协议传输可有效防止镜像在传输过程中被篡改或窃取。KubeSphere 作为全栈化的容器管理平台，与 Harbor 的深度集成能够实现：

镜像拉取的加密传输
细粒度的访问权限控制
镜像扫描与漏洞管理
审计日志的完整记录

二、前置条件准备

2.1 Harbor 端配置

证书生成：

# 生成私钥
openssl genrsa -out harbor.key 2048
# 生成证书签名请求
openssl req -new -key harbor.key -out harbor.csr \
  -subj "/CN=harbor.example.com/O=DevOps Team"
# 生成自签名证书（生产环境应使用CA签发）
openssl x509 -req -days 365 -in harbor.csr -signkey harbor.key -out harbor.crt

Harbor 配置：

修改 harbor.yml：

https:
  certificate: /path/to/harbor.crt
  private_key: /path/to/harbor.key
harbor_admin_password: StrongPassword123!

执行 ./install.sh 重新部署

2.2 KubeSphere 端准备

确保集群节点可访问 Harbor 的 443 端口
准备 ServiceAccount 用于镜像拉取（可选）

三、集成实施步骤

3.1 证书导入配置

将证书添加到集群信任链：

# 将证书复制到所有节点
scp harbor.crt node1:/etc/docker/certs.d/harbor.example.com/
scp harbor.crt node2:/etc/docker/certs.d/harbor.example.com/
# 创建证书目录（如不存在）
mkdir -p /etc/docker/certs.d/harbor.example.com

KubeSphere 配置方式：

方法一：通过 UI 配置
1. 进入「集群管理」→「配置中心」→「密钥」
2. 创建类型为 Opaque 的密钥，内容为：
```
apiVersion: v1
kind: Secret
metadata:
  name: harbor-cert
type: Opaque
data:
  .dockerconfigjson: <base64-encoded-config>
```

方法二：通过 kubectl 创建：

kubectl create secret generic harbor-cert \
  --from-file=harbor.crt=/path/to/harbor.crt \
  -n kube-system

3.2 创建镜像仓库凭证

在 KubeSphere 控制台：
- 进入「项目设置」→「镜像仓库」
- 选择「添加镜像仓库」
- 填写参数：
  - 仓库地址：https://harbor.example.com
  - 认证模式：选择「用户名密码」
  - 用户名：admin（或具有读取权限的账号）
  - 密码：对应密码
  - 证书：选择之前创建的 harbor-cert

命令行方式：

kubectl create secret docker-registry regcred \
  --docker-server=harbor.example.com \
  --docker-username=admin \
  --docker-password=StrongPassword123! \
  --docker-email=admin@example.com \
  -n <namespace>

3.3 验证集成效果

测试镜像拉取：

# 创建测试Pod
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
  - name: busybox
    image: harbor.example.com/library/busybox:latest
  imagePullSecrets:
  - name: regcred
EOF

查看拉取日志：

kubectl describe pod test-pod | grep "Pulling image"

四、高级配置选项

4.1 项目级镜像仓库

在项目设置中创建专用凭证

通过 imagePullSecrets 字段指定：

spec:
  template:
    spec:
      imagePullSecrets:
      - name: project-regcred

4.2 自动证书更新

使用 cert-manager 实现证书自动轮换：

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: harbor-cert
spec:
  secretName: harbor-tls
  issuerRef:
    name: letsencrypt-prod
  dnsNames:
  - harbor.example.com

4.3 网络策略控制

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-harbor
spec:
  podSelector: {}
  policyTypes:
  - Egress
  egress:
  - to:
    - ipBlock:
        cidr: <harbor-ip>/32
    ports:
    - protocol: TCP
      port: 443

五、故障排查指南

5.1 常见问题处理

证书错误：
- 现象：x509: certificate signed by unknown authority
- 解决：检查证书是否完整导入所有节点
认证失败：
- 现象：Unauthorized
- 检查：
  - 用户名密码是否正确
  - 用户是否有对应项目的读取权限
  - Harbor 是否开启了「阻止未授权访问」
连接超时：
- 检查：
  - 网络策略是否放行 443 端口
  - Harbor 服务是否正常运行
  - 负载均衡器配置是否正确

5.2 日志分析

Kubelet 日志：

journalctl -u kubelet -f | grep "image pull"

Harbor 访问日志：
```
tail -f /var/log/harbor/access.log
```

六、最佳实践建议

证书管理：
- 生产环境使用商业 CA 签发的证书
- 设置证书自动轮换机制
- 将证书存储在 Secret 而不是 ConfigMap 中
权限控制：
- 遵循最小权限原则
- 为不同项目创建独立的服务账号
- 定期审计用户权限
性能优化：
- 在同一区域部署 Harbor 和 KubeSphere
- 配置 Harbor 的缓存代理
- 使用对象存储作为后端存储
备份策略：
- 定期备份 Harbor 的数据库
- 备份所有自定义证书
- 测试备份恢复流程

通过以上步骤，您可以在 KubeSphere 环境中安全可靠地集成 Harbor 镜像仓库，为容器化应用提供坚实的镜像管理基础。实际部署时，建议先在测试环境验证所有配置，再逐步推广到生产环境。

KubeSphere 与 Harbor HTTPS 集成：安全镜像管理实践指南