Skip to main content

安装前置条件

安装前请确认 Kubernetes 版本、Helm、存储与 CSI 快照能力满足要求，推荐用内置脚本自动核对而不是手工逐项检查。

硬性要求​

项目要求原因
Kubernetes 版本>= 1.25CSI 快照相关 API 在更低版本不稳定
Helm3.xChart 使用 Helm 3 语法
StorageClass至少一个可用用于内置本地备份库（如启用）与还原时的 PVC 供给

建议具备（非硬性，缺失会以功能降级形式体现）​

  • CSI 快照能力：snapshotclasses.snapshot.storage.k8s.io 等 v1 CRD 已安装，snapshot-controller 正常运行，且存在至少一个 VolumeSnapshotClass。缺失时仍可安装 SupKube，但快照类的备份路径不可用，只能走文件系统备份。
  • 已有 Velero：如果集群中已经手工安装过 Velero，建议安装时显式关闭内置 Velero 子 Chart（--set velero.enabled=false），避免两套 Velero 控制器共存冲突。

自动核对：preflight.sh​

仓库自带的检查脚本会依次核对以上各项，并在最后打印一条可以直接使用的 helm install 命令（会根据检查结果自动带上或省略 velero.enabled、localStore.enabled 等参数）：

./hack/preflight.sh

常用参数：

  • --skip-velero：跳过"是否已存在 Velero"检测。
  • --json：以 JSON 格式输出检查结果，便于接入自动化流水线。
  • --verbose：打印更详细的检查过程。

脚本检查的类别包括：API 连通性与版本、Helm 版本、kubectl auth can-i 对创建命名空间/CRD/ClusterRoleBinding/Deployment 的权限、StorageClass 是否存在及是否有默认 StorageClass、CSI 快照相关 CRD 与 Pod、VolumeSnapshotClass 数量、已有 Velero 检测、节点数量与资源、以及本地备份库的适用性评估。脚本以退出码 0/1/2 区分"通过"/"失败"/"存在警告"。

平台差异与降级​

SupKube 没有按 Kubernetes 发行版区分的安装流程——各平台装法一致。但有三件事跟您的存储驱动有关，需要提前知道。

自动适配的 7 个 CSI 驱动​

SupKube 会为下列驱动自动创建合适的 VolumeSnapshotClass：

驱动说明
disk.csi.azure.comAzure 磁盘，自动启用增量快照以节省成本
file.csi.azure.comAzure 文件存储，注意下节的额外步骤
ebs.csi.aws.comAWS EBS
pd.csi.storage.gke.ioGCP 持久磁盘
diskplugin.csi.alibabacloud.com阿里云云盘
com.tencent.cloud.csi.cbs腾讯云 CBS
hostpath.csi.k8s.ioCSI Hostpath，仅供开发测试

表外的驱动会被明确拒绝，而不是猜一个参数试试。 界面上看到「未知驱动」不是缺陷，而是产品拒绝在快照参数上赌博——一个错误的快照类会静默损坏备份，比直接拒绝危险得多。

未知驱动可以在 GET /api/v1/storage/csi-autoconfig 的 unknownDrivers 字段里看到，需要您自行确认并手工创建 VolumeSnapshotClass。

AKS + Azure 文件存储需要一步额外授权​

唯一一个"装完还得手工做一步"的组合

这条的失败形态极具欺骗性：备份会显示成功，但数据永远传不上去。

Azure 文件存储（SMB）不兼容文件系统备份路径，唯一可用的是 CSI 快照 + Data Mover。Data Mover 挂载临时卷时需要调用 Azure 的 listKeys 接口，而 AKS 的 kubelet 托管身份默认没有 Storage Account Key Operator Service Role，调用会返回 403。

结果就是：快照拍成功了，导出环节静默失败。

这个 IAM 授权属于提权操作，SupKube 按安全红线不会自动执行，只会在备份就绪性检查里报出来。请在 Azure 侧手工给 kubelet 托管身份授予该角色。

AWS、GCP、阿里云、腾讯云都没有等价的额外步骤。

没有 CSI 快照能力时怎么办​

K3s 默认的 local-path 的 provisioner 是 rancher.io/local-path，它不是 CSI 驱动，因此走不到快照路径。

一个 StorageClass 被判定为"可做 CSI 快照"需要同时满足两个条件：

   ① provisioner 出现在集群的 CSIDriver 列表里
                  +
   ② 存在一个 VolumeSnapshotClass 的 driver 等于该 provisioner
                  │
          两个都满足 ──▶ 可用 CSI 快照
                  │
          缺 ① ──▶ "Provisioner 不是 CSI 驱动"   ← local-path 落这里
          缺 ② ──▶ "该驱动没有配置 VolumeSnapshotClass"

降级路径是把策略的「数据路径」从 CSI 快照改成文件系统（经 node-agent 直接读卷）。这条路不依赖任何 CSI 能力，K3s 与边缘场景完全可用，代价是备份速度较慢、还原粒度较粗。

预检脚本会提前示警，但这些都是警告而非失败——装得上，只是快照路径不可用。

OpenShift​

未经验证。 产品代码里没有任何针对 OpenShift 的适配：没有 SecurityContextConstraints 配置，也没有 Operator 安装方式。

理论上标准 Helm 安装流程适用，但我们没有在 OpenShift 上实测过，遇到 SCC 相关的权限问题需要您自行处理。

验证方法​

curl -fsSL https://charts.supkube.com/preflight.sh | bash

命令结束时应看到汇总结果与建议的 helm install 命令。

退出码含义容易误读：0 表示关键检查全部通过（只有警告也是 0），1 表示至少一项关键检查失败，2 表示预检工具自身出错（例如找不到 kubectl）而非"存在警告"。

相关文档​