从 Velero 备份恢复命名空间或整集群，确认 PV 数据、处理部分失败并安全回滚

适用场景

• 命名空间或资源被误删、错误发布破坏了工作负载，需要从 Velero 备份回到之前的资源状态。
• 集群迁移或灾难恢复：在目标集群重建 API 对象，并按备份能力恢复 PersistentVolume 中的数据。
• 只需要恢复单个命名空间、部分资源或指定标签选择的对象，而不是整份备份全量覆盖。
• 需要先用命名空间映射在隔离环境验证，再决定是否切到生产。

Velero 不是 etcd 快照的替代品，也不能凭空恢复没有被备份的数据。恢复动作不是事务：Pod、Service、PVC 可能部分创建成功、部分失败。因此先恢复到一个新命名空间或新集群，验证通过后再切换，是默认做法；直接在原命名空间覆盖只应在有当前状态备份和明确回滚方案时进行。

前置检查

1. 确认当前上下文和目标集群。生产恢复最常见的危险操作是切错 kubeconfig：

kubectl config current-context
kubectl get nodes
velero backup-location get

2. 检查 BackupStorageLocation（BSL）是否可用。Available 只说明 Velero 能访问对象存储，不代表备份内容完整：

kubectl -n velero describe backupstoragelocation <bsl-name>
velero backup get
velero backup describe <backup-name> --details
velero backup logs <backup-name> | tail -100

重点看备份阶段、错误数、包含的命名空间、资源数量、卷备份或 CSI 快照数量。Completed 也可能没有包含卷数据，必须看 --details 和日志。PartiallyFailed 的备份不是完全不可用，但要先判断缺的是关键资源还是可重建资源。

3. 确认备份没有过期或被清理。检查对象存储的 TTL、生命周期规则、对象锁和凭据有效期。备份文件被生命周期规则删除、但 Velero 里还保留记录时，恢复会在读取阶段失败。

4. 检查恢复组件。确认 Velero 服务端、CLI 和插件相互兼容，Velero 命名空间中的 Pod 正常；如果用文件系统备份，node-agent DaemonSet 必须在目标节点运行：

kubectl -n velero get pods
kubectl -n velero get ds node-agent
kubectl -n velero get backuprepositories.velero.io

5. 检查目标集群的前置条件。跨集群恢复时，StorageClass 名称、默认 StorageClass、CSI 驱动、VolumeSnapshotClass、镜像仓库、IngressClass、CRD、Secret 和外部 DNS 都可能不同。提前执行：

kubectl get sc
kubectl get volumesnapshotclass
kubectl get crd | wc -l
kubectl get resourcequota,limitrange -A

如果目标集群没有源集群同名的 StorageClass，PVC 会一直 Pending；没有对应镜像时 Pod 会 ImagePullBackOff。不要等恢复开始后才发现这些依赖。

6. 保护当前状态。即使是恢复到新命名空间，也先记录目标端的现有对象；如果要在原命名空间执行 update，先创建当前状态备份：

velero backup create pre-restore-app-$(date +%Y%m%d%H%M) \
  --include-namespaces app \
  --default-volumes-to-fs-backup --wait
kubectl -n app get deploy,sts,svc,cm,secret,pvc -o yaml > app-before.yaml

7. 冻结写入并确定验收人。恢复期间暂停会写同一批数据的生产者和消费者，避免旧工作负载和恢复出的工作负载同时写外部数据库或消息队列。业务方要明确哪些接口、数据条数和查询结果算恢复成功。

恢复步骤

1. 先做隔离命名空间恢复

不要一上来覆盖生产。使用命名空间映射恢复到临时命名空间，验证资源和数据：

velero restore create app-restore-$(date +%Y%m%d%H%M) \
  --from-backup app-20261018 \
  --include-namespaces app \
  --namespace-mappings app:app-restore \
  --existing-resource-policy=none \
  --wait

命名空间映射会改变资源的命名空间归属，但 ConfigMap、Secret 和启动参数中硬编码的旧命名空间、数据库地址、外部域名不会自动修改，验证时要逐项检查。

2. 整集群恢复

整集群恢复应针对新建的目标集群或经过验证的空环境，并使用明确的排除项：

velero restore create cluster-restore-$(date +%Y%m%d%H%M) \
  --from-backup full-cluster-20261018 \
  --include-cluster-resources=true \
  --exclude-resources nodes,events,events.events.k8s.io \
  --exclude-namespaces kube-system,kube-public,kube-node-lease,velero \
  --existing-resource-policy=none \
  --wait

nodes、events、租约和系统命名空间带有源集群的节点名、IP 和运行时状态，恢复到目标集群通常只会污染状态。目标集群的 CNI、CSI、DNS、Ingress Controller 和监控代理应先由集群自身安装好，再恢复业务资源。若备份包含 CRD 和 Webhook，确认目标集群版本与 schema 兼容；failurePolicy: Fail 的 Webhook 后端未就绪时，可能拦截后续资源创建。

3. 跟踪恢复过程

velero restore get
velero restore describe <restore-name> --details
velero restore logs <restore-name> > restore.log
kubectl -n app-restore get pods,pvc,svc
kubectl -n app-restore get events --sort-by=.lastTimestamp

--wait 返回不代表每个资源都成功，仍要看 Phase、错误和警告。恢复出的资源可能先于 CRD 或控制器恢复，导致工作负载无法创建其依赖对象；遇到 no matches for kind 要先补齐 CRD。

4. 处理 PV 数据

Velero 恢复资源清单不等于恢复卷内容。先确认备份的卷模式：

• 文件系统备份：备份中包含 PodVolumeBackup，目标集群的 node-agent 把数据写回新建的 PVC。查看 kubectl -n velero get podvolumerestores 和恢复详情中的卷恢复状态。
• CSI 快照：目标集群必须具备相同 CSI 驱动、VolumeSnapshotClass 和可访问的快照位置；跨集群时还要确认快照数据是否被移动到对象存储，而不是只存在于源存储系统。
• 没有卷数据：PVC 会绑定到空卷，数据库或文件服务可能能启动，但数据是空的。这种“恢复成功”比直接失败更危险。

恢复通常创建新的 PVC/PV 绑定，而不是把数据挂回原来的卷。确认 StorageClass 能动态供应，或提前创建好静态 PV；数据量大时，卷恢复可能远晚于 Pod 启动，业务验证要等卷恢复完成后再做。

5. 覆盖已有资源

默认 --existing-resource-policy=none 会跳过已存在的对象。只有在当前状态已备份、资源差异已确认、回滚路径明确时，才使用 update：

velero restore create app-inplace-$(date +%Y%m%d%H%M) \
  --from-backup app-20261018 \
  --include-namespaces app \
  --existing-resource-policy=update \
  --wait

覆盖式恢复仍可能保留目标端新增的对象，不会把命名空间变成备份时的精确副本。数据库、PVC、Service 和外部资源要单独核对，不能把“恢复命令成功”当成“业务状态一致”。

验证

• 恢复的 Phase 为 Completed；若为 PartiallyFailed，逐条查看错误，不要忽略警告。
• 备份详情中的资源数量和恢复后的对象数量能对上；关键 Deployment/StatefulSet 的副本数、镜像和配置正确。
• 所有 PVC 为 Bound，Pod 为 Running/Ready，卷恢复任务完成；对数据库或文件数据做行数、校验和或抽样读取。
• Service Endpoints 有地址，Ingress/Gateway 路由可达，ConfigMap/Secret 中的地址与命名空间映射一致。
• 应用完成只读探针、登录、查询和一次可回滚的写操作；消费者恢复后 lag 没有异常增长。
• 确认没有旧工作负载和恢复出的工作负载同时消费同一队列或写同一数据库。
• 集群级恢复还要检查节点 Ready、CoreDNS、CNI、CSI、Ingress Controller 和 CRD 控制器，不能只看业务命名空间。

失败与回滚

恢复状态为 PartiallyFailed。 先查看 velero restore describe --details 和日志中的具体资源，按类型处理：

• already exists：默认被跳过。确认目标对象是否要保留；要覆盖时先备份，再用受控的 update 或只对失败资源重试。
• no matches for kind：目标集群缺少 CRD 或 API 版本不一致。先恢复 CRD 或安装对应控制器，再重试 CR。
• PVC 一直 Pending：检查 StorageClass 是否存在、CSISnapshot/VolumeSnapshotClass 是否可用、容量和配额是否足够。
• PodVolumeRestore 超时：检查 node-agent、对象存储凭据、网络带宽、目标磁盘空间和备份仓库维护状态。
• Webhook 拦截：先恢复 Webhook 后端和证书，或在隔离环境暂时排除 Webhook 配置，等工作负载就绪后再单独恢复。
• 镜像拉取失败、RBAC 拒绝、配额不足：分别修复仓库凭据、ServiceAccount/RoleBinding 和 ResourceQuota，不要用放宽全局权限来绕过。

只重试失败资源，不要在没有备份的情况下重新执行整份 update 恢复：

velero restore create retry-app-$(date +%Y%m%d%H%M) \
  --from-backup app-20261018 \
  --include-namespaces app \
  --include-resources deployments,services,configmaps \
  --existing-resource-policy=update \
  --wait

隔离命名空间恢复失败。 保留日志和恢复出的 PVC，删除临时命名空间前先确认没有需要保留的数据。删除测试命名空间是低风险回滚；不要顺手删除源备份或共享快照。

原命名空间覆盖恢复失败。 Velero 没有“撤销恢复”命令。优先从刚才创建的 pre-restore 备份恢复，或用 GitOps 的上一个提交重新同步；不要手工删除不确定归属的对象。若恢复出的 PV 已写入脏数据，先停应用、隔离存储，再从更早的快照恢复。

误删了生产数据。 立即停止所有写入方，保留现场，确认最近一次可用备份和 RPO。不要用 --existing-resource-policy=update 反复覆盖同一批资源；每次重试都要记录时间、命令和影响范围。

需要回切。 先把恢复端缩容或断流，再切回原集群，确保不会出现双写。若原集群在故障后已继续接收写入，回切前要核对数据差异，不能只改 DNS 或 Service 指向。

相关命令

• velero — 备份、恢复、命名空间映射与卷数据模式
• backup-strategy — TTL、对象锁、演练与备份监控
• cluster-backup — etcd、CRD、PV 与集群配置的备份边界
• volume-snapshot — CSI 快照、VolumeSnapshotClass 与恢复约束
• build-velero-backup — 从零安装并验证 Velero 备份链路
• pv — PVC/PV 绑定与存储类
• crd — CRD 与自定义资源的恢复顺序
• disaster-recovery — RTO/RPO、恢复顺序与演练方法
• lab-velero-restore — 在 kind 集群中用 MinIO 演练备份、误删恢复与 PVC 校验。

参考链接

• Velero: Restore reference
• Velero: Resource filtering
• Velero: Troubleshooting

读完自测

合上页面，先回答，再展开对照。

1. Velero 备份显示 Completed，为什么还不能直接断定 PV 数据可以恢复？
2. 整集群恢复为什么要排除节点、事件和系统命名空间？
3. 恢复进入 PartiallyFailed 时，第一步应该做什么，什么时候才重试？