备份与还原操作

本文介绍策略（Policies）、存储位置、还原三个核心工作流的实际行为边界，包括哪些能力已经完整可用、哪些仍是预检（Preflight）阶段。

前置条件

已完成认证配置与许可证安装（新建备份/策略需要有效许可证，参见下文）。

策略（Policies）：计划备份

策略本质上是一个或两个 Velero Schedule 资源的聚合视图：

单模式（L1）：一个 Schedule，仅产出快照类恢复点。
双模式（L2，Snapshot + Export）：两个 Schedule——快照半区（本地 CSI 快照，短保留期）与导出半区（Data Mover / 文件系统上传到 BSL，长保留期）。两者共享 supkube.io/policy-name 标签。触发时只会先启动快照半区，SupKube 内置的配对控制器（policypair）在快照半区完成后约 30 秒自动触发导出半区——这是为了让两个恢复点在时间上尽量靠近，本身没有对外 REST 接口，纯后台运行。

保留期（TTL）使用 Go 语言的 duration 格式（例如 720h 表示 30 天），不是"天数"这种直观单位，创建/编辑策略时请按小时换算。

许可证会拦截这三个操作

POST /api/v1/backups、POST /api/v1/schedules、POST /api/v1/schedules/:name/run-once 在许可证状态不是 licensed/grace 时会返回 402。详见许可证管理。

备份顾问与 DR 评分

Backup Advisor（GET /api/v1/backup-advisor）：基于命名空间内是否存在 PVC、StatefulSet、supkube.io/tier 标签等透明规则打分，给出 High/Medium/Low/Skip 四档建议及配套的 Cron 与保留期建议。不调用大语言模型。
DR Scores（GET /api/v1/ai/scores，界面在 Observability 页的 DR 评分标签）：另一套独立的确定性规则引擎，按覆盖度、韧性、不可变性与安全、可靠性四个维度评分。这两套评分是两套并存的独立实现，服务于不同页面，不是同一套逻辑的两个入口。

存储位置（Storage Locations）

对象存储（BackupStorageLocation，BSL）创建接口目前只接受两种 provider：

provider	说明	认证方式
`aws`	S3 协议兼容存储（含自建 MinIO、腾讯云 COS、阿里云 OSS 等）	Access Key / Secret Key
`azure`	Azure Blob 存储	仅支持 Storage Account Key；Azure AD/服务主体认证尚未实现

GCP 暂不支持

界面的存储位置创建向导中会看到 GCP 选项，但当前版本标记为"规划中"并禁用；后端创建接口收到 provider 不是 aws/azure 时会直接拒绝。

卷快照位置（VolumeSnapshotLocation，VSL）与 BSL 是两个独立概念：VSL 只描述"如何做 CSI/云原生卷快照"，provider 字段不做后端校验（csi 用于任意 CSI 驱动，aws/gcp/azure 用于云原生快照），因此云厂商快照的可用性实际取决于集群是否装好对应 CSI 驱动，而不是 SupKube 本身的限制。

除云端 BSL 外，还可以启用内置本地备份库（localStore.enabled=true，集群内 MinIO），作为"先快后稳"的第一落点，可选开启 Object Lock（WORM，写一次读多次）防篡改。

还原（Restore）

界面入口

还原不是通过侧边栏单独的"还原"页面发起的——该路由目前重定向到 Observability 的活动标签。实际发起还原的方式是在 Backups（备份/恢复点）列表页对某条记录使用行操作菜单中的"还原"，会打开一个还原抽屉（Restore Drawer）。

整条还原链路如下，注意 Preflight 是只读诊断，不会改动任何东西：

   Backups 页 ──▶ 行操作菜单「还原」──▶ 还原抽屉
                                            │
                          配置：namespaceMapping / cleanupBeforeRestore
                                / targetCluster
                                            │
                                            ▼
                              ┌──────────────────────────┐
                              │  权限校验                 │
                              │  源命名空间 + 每一个映射   │
                              │  目标命名空间都要有权限    │
                              └────────────┬─────────────┘
                                           ▼
                              ┌──────────────────────────┐
                              │  Preflight（只读诊断）     │
                              ├──────────────────────────┤
                              │ 1 Service 端口/IP 冲突     │
                              │ 2 StorageClass 不存在      │
                              │ 3 Ingress host 被占用      │
                              │ 4 PVC 仍绑旧 volumeName    │
                              │ 5 镜像仓库 DNS（需 deepCheck）│
                              └────────────┬─────────────┘
                                           ▼
                                     冲突分级
                            ┌──────────────┴──────────────┐
                            ▼                             ▼
                      ┌──────────┐                  ┌──────────┐
                      │ blocker  │                  │ warning  │
                      │ 会失败    │                  │ 可能部分  │
                      │          │                  │ 成功      │
                      └────┬─────┘                  └────┬─────┘
                           │ 先修复                       │ 可继续
                           └──────────────┬───────────────┘
                                          ▼
                                   创建 Restore 资源

还原支持以下能力，均已在后端确认实现：

跨命名空间还原：通过 namespaceMapping（源命名空间 → 目标命名空间）字典重映射。
还原前清空目标命名空间：cleanupBeforeRestore=true 会先删除目标命名空间并等待其完全终止（最长等待 60 秒）后再执行还原；velero、supkube、kube-system、kube-public、kube-node-lease、default 六个命名空间受保护，不会被这样清空。
跨集群还原：指定 targetCluster（已在多集群注册表中登记的集群）时，SupKube 会先把源 BSL 及其凭据 Secret 镜像到目标集群，再在目标集群上创建 Restore 资源。
权限校验会同时检查源命名空间与每一个映射目标命名空间的访问权限，避免 editor 角色借还原之名把数据"搬"到自己无权访问的命名空间。

**还原前置检查（Preflight）**会在保存前对以下类别做只读诊断（POST /api/v1/restores/preflight）：

Service 的 nodePort / clusterIP / loadBalancerIP 冲突。
PVC 的 storageClassName 在目标集群不存在。
Ingress 的 host 已被目标集群其它 Ingress 占用。
PVC 仍绑定旧 volumeName（应清空以便绑定新 PV）。
（可选，需请求体 deepCheck: true）镜像仓库域名 DNS 可达性检测。

冲突分为 blocker（会导致还原失败）与 warning（可能部分成功）两级。

暂未提供的能力

Preflight 尚不检查目标命名空间是否已存在同名冲突资源、ResourceQuota 是否够用、或所需 CRD 是否已安装；冲突条目里的"自动匹配可修复的 Transform Set"字段目前也总是空的（该自动匹配逻辑尚未实现）。需要重写字段/名称时，请在 Transforms / TransformSet 页面手工选择并关联。

Transform 与 TransformSet（还原时的资源改写）

Transform 是对 Velero 原生 ResourceModifierDoc（条件+JSON Patch）的封装，保存在一个 ConfigMap 里；TransformSet 则是把多个 Transform 按顺序组合，并允许用 ${VAR} 占位符在应用时统一替换取值（例如把命名空间前缀、域名后缀一次性替换）。保存时会编译成一份供 Velero resourceModifierRef 直接读取的合并 ConfigMap。

跨存储位置复制（Backup Copy，Layer 4）

当前仅预检，尚未支持真正搬运数据

POST /api/v1/backup-copy/preflight（列出哪些备份可以做 BSL → BSL 复制、哪些因为是纯 CSI 快照而被拒绝，错误码 ERR_LAYER4_SNAPSHOT_UNSUPPORTED）已经可用。但真正执行复制的 POST /api/v1/backup-copy 在当前版本会直接返回 HTTP 501 Not Implemented。请勿在生产流程中依赖这一步"自动跨云复制"，如需异地副本，请为策略配置导出到异地 BSL，或手工搬运。

一键快照

Applications 页面每一行都有"一键快照"按钮（POST /api/v1/applications/:namespace/snapshot），固定使用 CSI 快照（不支持切换为文件系统备份）、默认 TTL=24h、默认写入名为 default 的存储位置，不受许可证状态限制，也不能对 velero、supkube、kube-system、kube-public、kube-node-lease、default 这些受保护命名空间使用。

排错辅助入口

GET /api/v1/backups/:name/errors：聚合 DataUpload/PodVolumeBackup 的失败信息，以及 Velero 备份结果包（results.gz）中的引擎级/命名空间级消息。
GET /api/v1/restores/:name/results：还原的错误、告警计数与详细消息（同样来自 Velero 的结果包），但不提供"按资源种类"的逐项统计。
卡住的备份可以用备份行菜单的"强制删除"（POST /api/v1/backups/:name/force-delete）跳过级联 DeleteBackupRequest 流程直接清除 finalizer；这会跳过正常清理，可能在对象存储上留下未清理的数据文件。

验证方法

# 确认策略产出的两个 Schedule（双模式会看到 <name> 与 <name>-export 两个）
kubectl get schedules -n supkube -l supkube.io/policy-name=<policy-name>

# 确认某次还原的详细结果
curl -s -H "Authorization: Bearer <token>" \
  http://<your-supkube-host>/api/v1/restores/<restore-name>/results

前置条件​

策略（Policies）：计划备份​

备份顾问与 DR 评分​

存储位置（Storage Locations）​

还原（Restore）​

Transform 与 TransformSet（还原时的资源改写）​

跨存储位置复制（Backup Copy，Layer 4）​

一键快照​

排错辅助入口​

验证方法​

相关文档​