InvenTree 插件开发实战：使用 APICallMixin 集成外部 API
2026/9/16 15:40:39
Velero 定时备份命令参考：create schedule 从 Cron 表达式到 Schedule CRD 的完整解析
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
本文基于 Velero v0.5.0 时期文档ark create schedule（CLI 参考页）编写，完整覆盖该命令的用法、全部选项及其继承的全局选项，并结合当前仓库的 create.go 与 schedule_types.go 源码，讲清该命令如何把命令行参数映射为 Schedule CRD 对象、以及定时备份的生命周期机制。读完后你可以直接用该命令创建周期性备份，并理解每个选项在 API 对象中的落点。
1. 命令概述：从 ark 到 velero
在 Velero 0.5.0 时代，CLI 二进制名为ark，创建定时备份的命令为ark create schedule。随着项目更名，当前仓库中该命令的等价形式是velero create schedule，命令实现位于 pkg/cmd/cli/schedule/create.go。
命令的基本用法为：
velero create schedule NAME [flags]（v0.5.0 文档中写作ark create schedule NAME [flags]，见 ark_create_schedule.md。）
从源码结构看，cobra 命令的Use字段声明为use + " NAME --schedule"（create.go#L42），且Args校验为cobra.ExactArgs(1)（create.go#L69），即必须且只能提供一个 Schedule 名称；--schedule表达式则是必填项，Validate中若其长度为 0 会直接报错"--schedule is required"（create.go#L110-L116）。
2. 完整选项参考（v0.5.0 文档版）
以下为 v0.5.0 官方文档中create schedule的全部选项，逐项继承不删减。stringArray、optionalBool等类型标记来自 pflag/cobra 的自动文档生成：
| 选项 | 类型 | 说明 | 默认值 |
|---|---|---|---|
--exclude-namespaces | stringArray | 要从备份中排除的命名空间 | — |
--exclude-resources | stringArray | 要从备份中排除的资源，格式为 resource.group，如storageclasses.storage.k8s.io | — |
-h, --help | — | schedule 的帮助信息 | — |
--include-cluster-resources | optionalBool | 在备份中纳入集群级（cluster-scoped）资源 | true（optionalBool[=true]） |
--include-namespaces | stringArray | 要纳入备份的命名空间（用*表示全部） | * |
--include-resources | stringArray | 要纳入备份的资源，格式为 resource.group，如storageclasses.storage.k8s.io（用*表示全部资源） | — |
--label-columns | stringArray | 以列形式展示的标签的逗号分隔列表 | — |
--labels | mapStringString | 应用到备份上的标签 | — |
-o, --output | string | 输出显示格式。对 create 类命令：仅打印对象但不提交到服务端。可用格式为table、json、yaml | — |
--schedule | string | 以 cron 表达式指定该备份的周期性计划 | — |
-l, --selector | labelSelector | 仅备份匹配该标签选择器的资源 | <none> |
--show-labels | — | 在最后一列显示标签 | — |
--snapshot-volumes | optionalBool | 备份时是否对 PersistentVolume 做快照 | true（optionalBool[=true]） |
--ttl | duration | 备份在被垃圾回收之前可以存活多久 | 24h0m0s |
2.1 继承自父命令的选项
v0.5.0 文档列出的继承自父命令的全局选项如下（均为 glog 日志与 kubeconfig 相关）：
| 选项 | 说明 | 默认值 |
|---|---|---|
--alsologtostderr | 日志同时输出到标准错误与文件 | — |
--kubeconfig | 与 Kubernetes apiserver 通信所用 kubeconfig 文件路径。若未设置，则尝试环境变量KUBECONFIG以及集群内配置 | — |
--log_backtrace_at | 当日志命中 file:N 这一行时输出堆栈跟踪 | :0 |
--log_dir | 若非空，日志文件写入该目录 | — |
--logtostderr | 日志输出到标准错误而非文件 | — |
--stderrthreshold | 达到该阈值及以上的日志写入 stderr | 2 |
-v, --v | V 级别日志的日志等级 | — |
--vmodule | 用于文件级过滤日志的pattern=N逗号分隔列表 | — |
2.2-o选项的行为印证
文档说明-o对 create 命令“打印对象但不提交服务端”。这一点在源码中得到印证：Run中先调用output.PrintWithFormat(c, schedule)，若printed为 true 则直接return，不再执行后续的crClient.Create（create.go#L184-L191）。因此velero create schedule daily -o yaml是一个安全的“干跑”方式，可用于审查即将创建的 Schedule 对象。
3. 调度表达式：cron 五段式与 @every
命令的 Long 描述（create.go#L44-L56）明确了两点：cron 表达式使用 UTC 时间，且支持@every <duration>语法。
3.1 cron 表达式字段
| 字符位置 | 字段含义 | 可接受值 |
|---|---|---|
| 1 | 分钟 (Minute) | 0-59, * |
| 2 | 小时 (Hour) | 0-23, * |
| 3 | 日 (Day of Month) | 1-31, * |
| 4 | 月 (Month) | 1-12, * |
| 5 | 星期 (Day of Week) | 0-6, * |
3.2 @every 语法
除标准 cron 外，表达式还可以写成@every <duration>形式，duration 由秒（s）、分（m）、时（h）组合而成，例如@every 2h30m。
3.3 官方示例
以下 4 个示例直接取自命令实现的Example字段（create.go#L58-L68），覆盖两种表达式风格与过滤、TTL 组合：
# 每 6 小时创建一次备份（cron 五段式）。 velero create schedule NAME --schedule="0 */6 * * *" # 用 @every 记法实现同样的每 6 小时一次。 velero create schedule NAME --schedule="@every 6h" # 每天备份 web 命名空间。 velero create schedule NAME --schedule="@every 24h" --include-namespaces web # 每周备份一次，每个备份保留 90 天（2160 小时）。 velero create schedule NAME --schedule="@every 168h" --ttl 2160h0m0s4. 源码级实现：选项如何变成 Schedule 对象
4.1 选项结构：复用 backup 的 CreateOptions
create schedule的选项结构体CreateOptions内嵌了备份命令的BackupOptions（create.go#L87-L93）。这正是第 2 节那些 namespace/resource/labels/ttl 等选项与backup create完全一致的原因——调度命令本质上是一个“带模板的备份工厂”：
type CreateOptions struct { BackupOptions *backup.CreateOptions SkipOptions *SkipOptions Schedule string UseOwnerReferencesInBackup bool Paused bool }BindFlags（create.go#L102-L108）在复用备份选项之外额外绑定三个调度专属参数：
| 新增选项 | 类型 | 说明 |
|---|---|---|
--schedule | string | cron 表达式，指定周期性计划 |
--use-owner-references-in-backup | bool | 是否为该 Schedule 生成的 Backup 设置 OwnerReferences。注意：设为 true 后，删除 schedule 会连带删除其生成的备份 |
--paused | bool | 新建的 schedule 是否处于暂停状态 |
备份侧选项的完整绑定逻辑见 backup/create.go#L144-L181，例如--snapshot-volumes与--include-cluster-resources都通过NoOptDefVal = cmd.TRUE实现了“单独写出--snapshot-volumes即等价于=true”的 optionalBool 语义（backup/create.go#L163-L175），与 v0.5.0 文档中optionalBool[=true]的类型标记相互印证。
4.2 执行流程：组装 spec 并提交
Run函数（create.go#L122-L195）的核心流程：
- 从
client.Factory获取 kubebuilder client； - 将各选项值逐一映射进
api.Schedule.Spec：--include-namespaces→Template.IncludedNamespaces，--exclude-namespaces→Template.ExcludedNamespaces，--include-resources/--exclude-resources→Template.IncludedResources/Template.ExcludedResources，-l选择器 →Template.LabelSelector，--snapshot-volumes→Template.SnapshotVolumes，--ttl→Template.TTL，以及命名空间固定为 factory 的f.Namespace()（即 velero 部署所在命名空间，通常为velero，v0.5.0 时代为ark）； - 将
--schedule表达式写入Spec.Schedule，同时写入UseOwnerReferencesInBackup与Paused； - 支持
-o干跑后直接返回；否则调用crClient.Create提交，成功时打印Schedule %q created successfully.（create.go#L193）。
其中Template的类型就是BackupSpec（create.go#L143-L166），也就是说 Schedule 的 spec 模板与一次普通备份的 spec 完全同构——定时备份每次触发时，服务端即按此模板实例化出一个具体的 Backup。
5. Schedule CRD：字段、阶段与打印列
调度资源的 API 定义在 pkg/apis/velero/v1/schedule_types.go。
5.1 ScheduleSpec 字段
| 字段 | 类型 | 说明（源码注释摘译） |
|---|---|---|
template | BackupSpec | 将在给定计划上执行的备份定义（schedule_types.go#L28-L30） |
schedule | string | 定义备份运行时间的 Cron 表达式 |
useOwnerReferencesInBackup | *bool | 是否为生成的备份使用 OwnerReferences |
paused | bool | 该 schedule 是否被暂停 |
skipImmediately | *bool | 新建或取消暂停时若已到期是否跳过本次、顺延到下个计划时间；为空时跟随服务端配置（默认 false）（schedule_types.go#L46-L51） |
5.2 生命周期阶段与状态
SchedulePhase为枚举类型，取值三个（schedule_types.go#L56-L71）：
New：Schedule 已创建，但尚未被 ScheduleController 处理；Enabled：已通过校验，将按计划触发备份；FailedValidation：未通过控制器校验，不会触发备份。
ScheduleStatus记录phase、lastBackup（上次运行备份的时间）、lastSkipped（上次跳过时间）与validationErrors（schedule_types.go#L74-L94）。
5.3 kubectl 打印列与命名规则
从 kubebuilder 注解可见，kubectl get sched会额外展示 Status、Schedule、LastBackup、Age、Paused 五列，且资源短名为sched（schedule_types.go#L102-L107）。另有一个值得注意的实现细节：由 schedule 派生的备份命名通过TimestampedName生成，格式为<schedule名>-<YYYYMMDDHHMMSS>（schedule_types.go#L138-L141），这解释了为什么每次定时触发的备份名都带 14 位 UTC 时间戳后缀。
6. v0.5.0 文档与当前仓库的差异说明
v0.5.0 文档反映的是ark时期的选项集；当前仓库实现（veleroCLI）在其上做了扩展，阅读旧文档对照源码时需注意：
- 新增调度选项：
--paused、--use-owner-references-in-backup，以及SkipOptions引入的--skip-immediately（create.go#L102-L108）； - 新增备份模板选项：
--storage-location、--volume-snapshot-locations（并注册了名称补全函数，create.go#L81-L82）、细粒度资源过滤（--include-cluster-scoped-resources等与旧参数互斥，互斥校验见 backup/create.go#L235-L239）、--ordered-resources、--resource-policies-configmap等； - 默认值演变：v0.5.0 文档标注
--ttl默认24h0m0s；当前源码中该 flag 以CreateOptions的零值作为默认绑定（backup/create.go#L145），因此以当前仓库为准的默认行为可能不同，使用时建议显式指定--ttl； - 选项归属变化：
--label-columns、--show-labels属于 v0.5.0 文档中的 get 类展示选项，当前 create 命令并未绑定。
7. 相关命令（SEE ALSO）
按 v0.5.0 文档的 SEE ALSO 指向，调度相关的命令族包括（均以仓库根目录相对路径给出）：
- ark create — 创建 ark 资源；
- ark schedule — 管理 schedules；
- ark schedule create — 创建 schedule；
- ark schedule get / ark schedule delete — 查看与删除 schedule。
结合当前仓库，创建后还可通过velero backup create --from-schedule <name>立即按该模板手动触发一次备份（见 backup/create.go#L291-L293 的--from-schedule定义）。
8. 小结
create schedule命令的价值在于把“备份范围选项”与“调度策略”合并成一个声明式资源：所有过滤选项（namespaces/resources/selector/labels/ttl）原样落入spec.template，调度表达式落入spec.schedule，最终由服务端控制器按 cron（UTC）周期实例化 Backup。掌握第 2 节的完整选项表、第 3 节的两种表达式写法，以及第 5 节的 CRD 阶段与状态字段，即可独立完成从创建、干跑校验（-o yaml）、查看阶段（kubectl get sched）到暂停/删除的全流程操作。
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考