Velero restore create 命令完全指南：从 Ark 到 Velero 的恢复创建实战详解-平芜编程栈

Velero restore create 命令完全指南：从 Ark 到 Velero 的恢复创建实战详解

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

本篇文章以 Velero 项目早期（v0.6.0，彼时还叫 Ark）的 CLI 参考文档 ark restore create 为骨架，系统讲解恢复（Restore）创建命令的语法、全部参数含义与使用场景，并结合当前仓库的 create.go、create_test.go 以及 restore_types.go 源码，讲清楚每一个参数背后对应的RestoreSpec字段与校验逻辑。读完本文，你将能熟练地通过命令行创建精细化控制的恢复任务，并能读懂恢复对象的底层数据结构。

一、命令定位与历史沿革

ark restore create是 v0.6.0 时代（项目名为Ark）用于创建恢复任务的子命令，挂载在ark restore父命令之下。在 ark_restore.md 中定义，其定位为 "Work with restores"。该项目后续更名为Velero，命令也相应变为velero restore create，但核心语法与参数设计一脉相承。

在当前的仓库源码中，该命令的现代版本实现在 pkg/cmd/cli/restore/create.go，其Short描述仍是 "Create a restore"，由 restore.go 将create、get、logs、describe、delete五个子命令统一挂载到velero restore下。也就是说，v0.6.0 文档描述的这条命令，在今天的 Velero 中依然存在、依然活跃。

二、命令语法（Synopsis）

ark restore create BACKUP [flags]

对应现代 Velero 的完整用法为：

velero restore create [RESTORE_NAME] [--from-backup BACKUP_NAME | --from-schedule SCHEDULE_NAME]

命令的核心职责是：根据一个已存在的备份（Backup）创建恢复（Restore）对象。恢复对象创建后，Velero 服务端会异步执行真正的数据与资源回放，命令本身只负责提交请求并返回结果。

从源码的 NewCreateCommand 可以看到当前用法签名支持三种典型调用形态：

velero restore create restore-1 --from-backup backup-1：显式命名恢复对象，从指定备份恢复；
velero restore create --from-backup backup-1：不指定名称时，命令会自动生成backup-1-<时间戳>形式的默认名（见 Complete 方法，时间戳格式为20060102150405）；
velero restore create --from-schedule schedule-1：从某个调度最近一次成功触发的备份恢复。

v0.6.0 文档中要求BACKUP为必填位置参数，而现代版本将备份来源改为--from-backup/--from-schedule互斥选项，并通过 Validate 方法严格校验"二者必须且只能指定其一"。

三、核心选项详解

v0.6.0 文档列出的选项构成了恢复控制的基础能力。下表逐一说明每个选项的作用，并对照现代源码中的实现字段：

选项	说明	对应`RestoreSpec`字段（见 restore_types.go）
`--exclude-namespaces stringArray`	从恢复中排除的命名空间列表	`ExcludedNamespaces`
`--exclude-resources stringArray`	从恢复中排除的资源，格式为`resource.group`，如`storageclasses.storage.k8s.io`	`ExcludedResources`
`--include-cluster-resources optionalBool[=true]`	是否恢复集群级（cluster-scoped）资源，默认 true	`IncludeClusterResources`
`--include-namespaces stringArray`	要恢复的命名空间，默认`*`（全部命名空间）	`IncludedNamespaces`
`--include-resources stringArray`	要恢复的资源，格式`resource.group`，默认`*`（全部资源）	`IncludedResources`
`--label-columns stringArray`	以标签作为表格列展示（配合输出表格使用）	—（仅影响展示）
`--labels mapStringString`	为恢复对象附加的标签	`ObjectMeta.Labels`
`--namespace-mappings mapStringString`	命名空间映射，格式`src1:dst1,src2:dst2,...`，用于把备份中的命名空间恢复到新命名空间	`NamespaceMapping`
`-o, --output string`	输出格式，`table`/`json`/`yaml`；对 create 类命令，仅打印对象而不提交到服务端	—
`--restore-volumes optionalBool[=true]`	是否从快照恢复卷，默认 true	`RestorePVs`
`-l, --selector labelSelector`	仅恢复匹配该标签选择器的资源，默认`<none>`	`LabelSelector`
`--show-labels`	在最后一列显示标签	—（仅影响展示）

3.1 命名空间与资源的包含/排除

--include-namespaces与--exclude-namespaces是一对互补过滤器；--include-resources与--exclude-resources同理。在 RestoreSpec 中，这些字段被定义为字符串切片，语义为：

对应字段为空时不做限制（如IncludedNamespaces为空表示包含所有命名空间）；
显式给定*表示通配全部；
资源格式采用resource.group，例如storageclasses.storage.k8s.io，这是 Kubernetes API 发现机制下的标准资源标识。

3.2 命名空间映射（namespace-mappings）

--namespace-mappings是最常用的"迁移"利器：当你想把prod命名空间的备份恢复到dev命名空间时，使用：

ark restore create prod-backup --namespace-mappings prod:dev

在源码中该参数通过 flag.NewMap().WithEntryDelimiter(',').WithKeyValueDelimiter(':') 解析，即逗号分隔多组映射、冒号分隔源与目标。最终存入RestoreSpec.NamespaceMapping（map[string]string），未出现在映射中的源命名空间将按原名恢复（见 restore_types.go）。

3.3 标签选择器过滤（selector）

-l, --selector用于在备份范围内做细粒度的对象过滤。例如只恢复带有app=web标签的 Pod：

ark restore create backup-1 -l app=web

对应RestoreSpec.LabelSelector（类型为metav1.LabelSelector），当为空或 nil 时恢复所有对象。

3.4 卷恢复控制（restore-volumes）

--restore-volumes是 optionalBool 类型，默认值为 true，意味着裸写--restore-volumes等价于--restore-volumes=true。这一"裸布尔"设计在现代源码中通过f.NoOptDefVal = cmd.TRUE实现（见 BindFlags）。置为false时，恢复过程将跳过卷数据/快照的恢复，只回放 Kubernetes 资源对象。对应字段为RestorePVs *bool。

3.5 输出格式（-o, --output）

-o table|json|yaml对 create 类命令有特殊语义：只打印将要创建的对象，不真正提交到服务端，适合先做"演练"确认恢复配置是否符合预期，再实际执行。

四、从父命令继承的全局选项

以下选项并非restore create独有，而是所有 Ark/Velero CLI 子命令共享的全局日志与连接配置：

--alsologtostderr 同时输出日志到标准错误与文件 --kubeconfig string kubeconfig 文件路径；未设置时依次尝试环境变量 KUBECONFIG 与集群内配置 --log_backtrace_at traceLocation 当日志命中 file:N 时输出堆栈跟踪（默认 :0） --log_dir string 日志目录（非空时写入文件） --logtostderr 日志输出到标准错误而非文件 --stderrthreshold severity 达到或超过该级别的日志进入 stderr（默认 2） -v, --v Level V 日志级别 --vmodule moduleSpec 按文件的 pattern=N 过滤日志

其中--kubeconfig是最常用的选项：当你在本地机器上操作远端集群时，需显式指定 kubeconfig 路径，否则命令会按默认顺序寻找~/.kube/config或集群内配置。结合 client/config.go 的配置解析逻辑，Velero CLI 会优先使用--kubeconfig显式指定的文件。

五、现代 Velero 的扩展参数（源码级补充）

v0.6.0 之后，velero restore create在保留上述核心参数的基础上，增加了大量能力。以下参数在 BindFlags 中注册，当前仓库源码均可验证：

参数	说明
`--from-backup string`	指定备份来源
`--from-schedule string`	从调度最近一次成功备份恢复
`--allow-partially-failed`	配合`--from-schedule`，允许选择最近一次"部分失败"（PartiallyFailed）的备份
`--preserve-nodeports`	恢复 Service 时是否保留原有 nodePort（对应`PreserveNodePorts`）
`--existing-resource-policy`	恢复策略，取值`none`或`update`，决定对已存在 K8s 资源如何处理（对应`ExistingResourcePolicy`）
`--existing-volume-data-policy`	卷数据恢复策略，取值`none`/`full`/`incremental`（对应`ExistingVolumeDataPolicy`）
`--or-selector`	多个标签选择器以 "or" 连接（如`foo=bar or app=nginx`），与`--selector`互斥（对应`OrLabelSelectors`）
`--resource-modifier-configmap`	恢复前对资源应用 JSON patch 的 ConfigMap（对应`ResourceModifier`）
`--resource-policies-configmap`	引用包含恢复资源过滤策略的 ConfigMap（对应`ResourcePolicy`）
`--skip-default-resource-modifier`	跳过服务端配置的默认资源修改器
`--status-include-resources`/`--status-exclude-resources`	控制恢复哪些资源的 status 字段（对应`RestoreStatusSpec`）
`--item-operation-timeout`	异步插件操作的等待超时时间
`--wait, -w`	阻塞等待恢复完成，期间可通过 Ctrl-C 安全退出，恢复继续在后台执行
`--write-sparse-files`	文件系统恢复时是否以稀疏文件方式写入
`--parallel-files-download`	文件下载并行度，0 表示默认（node agent 所在节点的 CPU 数）
`--delete-extra-files`	文件系统恢复时删除目标卷中备份里不存在的多余文件（仅对 PodVolumeBackup / CSI 文件系统数据移动生效）

其中--existing-resource-policy与--existing-volume-data-policy的取值合法性由 Validate 方法在命令提交前校验，非法取值会直接报错。

六、命令执行流程与源码解读

从 create.go 可以看出，一条restore create命令背后经历了四个阶段：

Complete（补齐默认值）：未指定名称时生成来源名-时间戳的默认恢复名；初始化 k8s 客户端。
Validate（校验）：校验备份/调度来源互斥性、selector 与 or-selector 互斥性、策略取值合法性，并提前检查备份或调度是否存在（从 create_test.go 的 "create a restore from not-existed backup" 用例可以看到，对不存在的备份会返回backups.velero.io "not-exist" not found错误）。
构建 Restore 对象：将各选项映射为api.Restore对象。若指定了--resource-policies-configmap，会构造TypedLocalObjectReference{Kind: "configmap", Name: ...}存入Spec.ResourcePolicy（该行为由 create_test.go 第 207-238 行的测试用例验证）。
Run（执行）：通过o.client.Create(...)提交 Restore 对象到 API Server，打印Restore request "<name>" submitted successfully.；若指定--wait，则启动 informer 监听该 Restore 的状态变化，直到进入Completed/PartiallyFailed/Failed/FailedValidation终态（见 Run 方法）。

特别值得注意的mostRecentBackup逻辑（create.go L265-L299）：当使用--from-schedule --allow-partially-failed时，命令会把该调度触发的所有备份按开始时间倒序排列，选取最近一个Completed或PartiallyFailed的备份作为恢复来源；对应单测 TestMostRecentBackup 验证了排序与阶段过滤逻辑的正确性。

七、典型使用场景汇总

场景一：全量恢复一个备份

ark restore create backup-1

等价于现代写法：

velero restore create restore-1 --from-backup backup-1

默认恢复所有命名空间、所有资源，并从快照恢复卷。

场景二：仅恢复 PVC 与 PV

velero restore create --from-backup backup-2 --include-resources persistentvolumeclaims,persistentvolumes

该示例直接取自源码 NewCreateCommand 的 Example，用于只恢复持久卷数据而不动工作负载。

场景三：恢复到新命名空间（迁移/环境复制）

ark restore create backup-prod --namespace-mappings prod:staging

将prod命名空间的全部资源恢复到staging命名空间，实现环境克隆。

场景四：按标签选择性恢复

ark restore create backup-1 -l tier=frontend

只恢复备份中带有tier=frontend标签的对象。

场景五：从调度恢复

velero restore create --from-schedule daily-backup velero restore create --from-schedule daily-backup --allow-partially-failed

前者使用调度最近一次成功（Completed）的备份；后者在最近一次备份部分失败时也允许基于它进行恢复。

场景六：先预览后执行

ark restore create backup-1 -o yaml

仅输出将要创建的 Restore YAML 对象，不提交到集群，便于审查与版本管理。

八、恢复后的检查与排障

恢复请求提交成功后，建议按顺序执行以下命令确认结果（相关子命令见 restore.go）：

ark restore get：查看恢复列表及当前阶段状态；
ark restore describe <RESTORE_NAME>：查看恢复的详细配置与每个资源的处理结果；
ark restore logs <RESTORE_NAME>：查看恢复过程的详细日志。

v0.6.0 文档在 SEE ALSO 中给出了指向 ark restore 的导航；而当前仓库中与恢复排障相关的更完整资料还可参考 debugging-restores.md。

九、注意事项与最佳实践

备份与调度只能二选一：--from-backup与--from-schedule同时指定或都不指定都会报错，这是 Validate 的强制约束。
selector 与 or-selector 互斥：二者不可同时使用（create.go L226-L228）。
集群级资源默认恢复：--include-cluster-resources默认 true，若恢复目标集群与源集群配置差异较大（如 StorageClass、Namespace 本身），建议先评估集群级资源的影响。
卷恢复默认开启：--restore-volumes默认 true；若仅需要恢复资源清单而不恢复数据（例如灾备演练），可显式传--restore-volumes=false。
恢复是异步的：命令成功返回只代表恢复请求被受理，真正的执行状态需通过restore get/describe/logs跟踪；需要同步等待时可使用-w/--wait。