企业官网建设流程全解析

Velero（前身 Heptio Ark）命令行参考完全指南：备份、恢复、定时任务与插件管理

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

本篇技术指南以 site/content/docs/v0.8.1/cli-reference/README.md 及其所在 CLI 参考目录为核心，系统讲解 Ark 客户端命令行（ark）的全部命令、全局标志、集群凭据解析顺序，以及备份、恢复、定时备份、插件、客户端配置等操作细节。读完本文，你将掌握arkCLI 的完整命令树与关键参数，并了解这些命令在当前 Velero 仓库中的源码级实现对应关系，可直接用于日常备份恢复操作与二次排查。

版本说明：v0.8.1 时代项目仍名为Heptio Ark，命令行工具为ark，默认命名空间为heptio-ark；当前仓库已更名为Velero，命令行工具为velero（源码入口见 cmd/velero/velero.go）。文中命令以 v0.8.1 文档为准，并给出与当前实现的对应说明。

一、CLI 参考文档的定位与使用方式

Ark 客户端提供了一套 CLI，允许你对 Kubernetes 集群发起临时备份（ad-hoc backups）、定时备份（scheduled backups）和恢复（restores）。仓库中 site/content/docs/v0.8.1/cli-reference/ 目录下的每一个文档文件，对应枚举了每条ark命令及其全部标志（flags）。

同时，这些信息随时可以通过 CLI 自带的--help标志查看，因此本文档既是手册，也是命令行内建帮助的静态化呈现。例如：

ark backup create --help ark restore create --help ark schedule create --help

二、获取并运行客户端

官方推荐的方式是下载预编译的 release 二进制，也可以从源码自行构建并运行ark可执行文件。在当前仓库中，CLI 的主入口位于 cmd/velero/velero.go，构建产物即velero命令；而 v0.8.1 文档对应的二进制名为ark。

运行客户端时，绝大多数命令都需要能够访问 Kubernetes API Server，因此正确的集群凭据是执行任何操作的前提。

三、Kubernetes 集群凭据的解析顺序

Ark 会按照以下顺序查找集群凭据（依次尝试，命中即止）：

1. --kubeconfig命令行标志：显式指定的 kubeconfig 文件路径，优先级最高；
2. $KUBECONFIG环境变量：未指定--kubeconfig时，读取该环境变量指向的配置文件；
3. 集群内凭据（in-cluster credentials）：仅当 Ark 运行在 Pod 内部时生效，此时使用 ServiceAccount 自动挂载的凭据访问集群。

这一顺序在当前仓库的源码中有直接印证：pkg/client/client.go 中的Config()函数通过loadingRules.ExplicitPath = kubeconfig实现显式路径优先，并在找不到任何配置时返回错误：error finding Kubernetes API server config in --kubeconfig, $KUBECONFIG, or in-cluster configuration——可见三种来源的解析逻辑至今仍是 CLI 的骨架。

全局标志速查

以下标志继承自根命令ark（见 ark.md），对所有子命令生效：

需要说明的是，v0.8.1 文档中的默认命名空间是heptio-ark；当前 Velero 实现中命名空间默认值已变为velero，例如 pkg/cmd/cli/completion_functions_test.go 中的测试数据即以velero命名空间构造 Backup 对象。实际使用时以你所安装版本的--help输出为准。

四、命令树总览：从ark根命令出发

ark根命令的简介是"Back up and restore Kubernetes cluster resources."（备份和恢复 Kubernetes 集群资源），完整的子命令树如下（来源：ark.md 的 SEE ALSO 部分）：

与kubectl类似，Ark 支持两种等价语法：既可以执行ark get backup、ark create schedule，也可以执行ark backup get、ark schedule create。两种写法的效果完全一致，用户可按习惯选用。

五、备份相关命令详解

5.1 创建备份：ark backup create

用法（见 ark_backup_create.md）：

ark backup create NAME [flags]

当前仓库中该命令的实现位于 pkg/cmd/cli/backup/create.go，CreateOptions结构体完整承载了上述参数，例如IncludeNamespaces默认初始化为flag.NewStringArray("*")、SnapshotVolumes使用flag.NewOptionalBool(nil)（即三态布尔），BindFlags逐一把ttl、include-namespaces、include-resources等注册到 pflag。从 同一文件的 Example 可以看到当前 Velero 版本给出的实战示例：

# 备份包含所有资源 velero backup create backup1 # 仅备份 nginx 命名空间 velero backup create nginx-backup --include-namespaces nginx # 排除 velero 和 default 两个命名空间 velero backup create backup2 --exclude-namespaces velero,default # 不拍卷快照，且仅输出 YAML 而不真正创建（dry-run） velero backup create backup3 --snapshot-volumes=false -o yaml # 等待备份完成后再返回 velero backup create backup4 --wait

5.2 查看与描述备份

ark backup get（见 ark_backup_get.md）以表格形式列出备份，支持--label-columns、-l/--selector、-o/--output（默认table）和--show-labels。

ark backup describe [NAME1] [NAME2] [NAME...]（见 ark_backup_describe.md）可一次描述多个备份，也支持-l/--selector按标签选择。

从当前源码看，velero backup get通过f.Namespace()确定查询命名空间，再以kbClient.Get/List读取api.BackupList（见 pkg/cmd/cli/backup/get.go），标签选择器经labels.Parse解析后交给ListOptions——这解释了--selector为什么必须符合 Kubernetes 标签选择器语法。

5.3 删除备份：ark backup delete

ark backup delete NAME [flags]

（见 ark_backup_delete.md）删除操作需要显式追加--confirm标志确认，属于破坏性操作的安全护栏。

5.4 下载备份：ark backup download

ark backup download NAME [flags]

（见 ark_backup_download.md）：

下载得到的是该备份的完整数据归档包，可用于离线归档或跨环境迁移。

5.5 查看备份日志：ark backup logs

ark backup logs BACKUP [flags]

（见 ark_backup_logs.md）支持--timeout（默认1m0s），用于在备份失败或部分失败时定位问题。

六、恢复相关命令详解

6.1 创建恢复：ark restore create

用法（见 ark_restore_create.md）：

ark restore create [RESTORE_NAME] --from-backup BACKUP_NAME [flags]

文档给出的示例：

# 从 backup-1 恢复，命名为 restore-1 ark restore create restore-1 --from-backup backup-1 # 不指定名称，自动生成默认名 "backup-1-<timestamp>" ark restore create --from-backup backup-1

当前仓库的 pkg/cmd/cli/restore/create.go 在此基础上还支持--from-schedule（从某定时备份的最近一次成功备份恢复）以及按资源类型细粒度过滤，例如：

# 只恢复备份中的 persistentvolumeclaims 和 persistentvolumes velero restore create --from-backup backup-2 --include-resources persistentvolumeclaims,persistentvolumes

6.2 查看、描述、删除、日志

• ark restore get（见 ark_restore_get.md）：列出恢复任务，支持--label-columns、-l/--selector、-o/--output、--show-labels；
• ark restore describe [NAME1] [NAME2] ...（见 ark_restore_describe.md）：描述恢复任务的详细状态，支持标签选择；
• ark restore delete NAME（见 ark_restore_delete.md）：删除恢复对象；
• ark restore logs RESTORE（见 ark_restore_logs.md）：获取恢复过程日志，支持--timeout（默认1m0s）。

七、定时备份命令详解

7.1 创建定时备份：ark schedule create

用法（见 ark_schedule_create.md）：

ark schedule create NAME --schedule [flags]

--schedule标志必填，采用标准的五段式 cron 表示法：

文档示例（每 6 小时执行一次）：

ark create schedule NAME --schedule="0 */6 * * *"

除了--schedule，其余标志与ark backup create基本一致（--include-namespaces、--exclude-resources、--snapshot-volumes、--ttl、--selector、--labels等），因为定时备份本质上就是"按 cron 反复触发相同的备份定义"。

7.2 查看、描述、删除定时备份

• ark schedule get（见 ark_schedule_get.md）：列出定时备份；
• ark schedule describe [NAME1] [NAME2] ...（见 ark_schedule_describe.md）：查看定时备份详情；
• ark schedule delete NAME（见 ark_schedule_delete.md）：删除定时备份（注意：删除 schedule 不会删除其已经产生的历史备份，历史备份按各自--ttl到期后被垃圾回收）。

八、通用资源操作命令

ark create、ark get、ark delete、ark describe是面向"备份、恢复、定时备份"三类资源的统一入口，例如：

• ark get backups（ark_get_backups.md）与ark backup get等价；
• ark get restores（ark_get_restores.md）、ark get schedules（ark_get_schedules.md）同理；
• ark create backup（ark_create_backup.md）、ark create restore、ark create schedule（ark_create_schedule.md）；
• ark describe backups（ark_describe_backups.md）、ark describe restores（ark_describe_restores.md）、ark describe schedules；
• ark delete backup、ark delete restore、ark delete schedule。

当前仓库中，"按名称 / 按--all/ 按--selector"三种选取方式被抽象为统一的SelectOptions校验逻辑（见 pkg/cmd/cli/select_option.go）：Validate()要求三者必须且只能指定其一，否则报错you must specify exactly one of: specific <type> name(s), the --all flag, or the --selector flag。这保证了资源选择语义的确定性。

九、插件管理命令

插件机制用于扩展 Ark/Velero 的备份存储与卷快照能力（详见 plugins.md）。

9.1 添加插件：ark plugin add

ark plugin add IMAGE [flags]

（见 ark_plugin_add.md）以容器镜像的方式注册插件，支持：

9.2 移除插件：ark plugin remove

ark plugin remove [NAME | IMAGE] [flags]

（见 ark_plugin_remove.md）通过插件名称或镜像名将其从部署中移除。

十、客户端配置文件：ark client config

ark client config用于读取和设置客户端配置文件的值（见 ark_client_config.md）：

ark client config get [KEY 1] [KEY 2] [...] [flags] ark client config set KEY=VALUE [KEY=VALUE]... [flags]

这组命令把高频参数持久化到本地配置文件，避免每条命令都重复输入。

在当前 Velero 仓库中，客户端配置文件位于$HOME/.config/velero/config.json（v0.8.1 时代为 Ark 对应的配置文件），实现见 pkg/client/config.go。从源码可确认其支持的配置键包括：

LoadConfig在配置文件不存在时返回空 map 而非报错，SaveConfig会自动创建目录并以0600权限写回，兼顾了无配置可用的容错性与敏感信息保护。

十一、Shell 自动补全：ark completion

（见 ark_completion.md）支持 bash 与 zsh，将补全代码输出到 STDOUT：

# 为当前 bash 会话加载补全 source <(ark completion bash) # 为当前 zsh 会话加载补全 source <(ark completion zsh)

十二、服务端与版本命令

12.1ark server

ark server [flags]

（见 ark_server.md）在集群内运行 Ark 服务端，负责执行备份、恢复、定时备份与垃圾回收等控制器逻辑：

12.2ark version

ark version [flags]

（见 ark_version.md）打印 Ark 客户端版本及与之关联的镜像版本，用于快速核对客户端与服务端是否匹配。

十三、深入当前仓库的对应实现

如果想从文档走向源码，建议按以下路径继续阅读：

• CLI 根命令与构建入口：cmd/velero/velero.go，以及pkg/cmd/cli下各子命令包；
• 备份创建实现：pkg/cmd/cli/backup/create.go，CreateOptions与BindFlags完整对应--include-namespaces、--ttl、--snapshot-volumes等全部参数；
• 恢复创建实现：pkg/cmd/cli/restore/create.go，含--from-backup、--namespace-mappings、--restore-volumes的绑定；
• 凭据解析与命名空间解析：pkg/client/client.go（--kubeconfig→$KUBECONFIG→ in-cluster 的三级回退）、pkg/client/config.go（客户端配置文件与namespace-mode: auto）；
• 资源选择校验：pkg/cmd/cli/select_option.go；
• 服务端命令：pkg/cmd/server目录（对应ark server/velero server）。

结语

ark/veleroCLI 的设计与kubectl一脉相承：顶层命令 + 资源子命令 + 丰富的过滤与输出标志，同时提供ark get backup与ark backup get两种等价写法以照顾不同习惯。掌握凭据解析顺序、全局标志，以及备份/恢复/定时备份三条主线命令的参数语义，即可覆盖 Kubernetes 应用与持久化卷备份恢复的绝大多数日常操作。遇到任何不确定的标志或取值，ark <command> --help（或当前版本的velero <command> --help）始终是最权威的即时参考。

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