调度器

Loco 简化了传统且通常繁琐的 crontab 系统，使其能够更轻松、更优雅地调度定时任务（cron jobs）。调度器作业可以执行 Shell 脚本命令或运行已注册的任务。

设置

可以通过 YAML 调度器设置文件或作为环境 YAML 文件的一部分来配置调度器作业。

1. 你的专用文件

使用专用文件提供了一个集中位置来配置所有调度器作业，从而更易于管理和维护。你可以使用 Loco 生成器命令生成一个模板文件来开始：

cargo loco generate scheduler

此命令将在 config 文件夹下创建一个 scheduler.yaml 文件。然后，你可以在此文件中配置你的作业。

2. 环境变量配置文件

你还可以通过将调度器部分添加到你环境的 YAML 配置文件中，为每个环境配置调度器作业：

scheduler:
  # 输出命令 stdout 和 stderr 的位置。
  output: stdout
  # 要调度的作业列表。
  jobs:
    # 作业的名称。
    write_content:
      # 默认值为 false，表示将 run 的值作为任务执行。如果为 true，则将 run 的值作为 shell 命令执行
      shell: true
      # 要运行的命令
      run: "echo loco >> ./scheduler.txt"
      # 定义作业计划的 cron 表达式。
      schedule: run every 1 second
      output: silent
      tags: ['base', 'infra']

    run_task:
      run: "foo"
      schedule: "at 10:00 am"
      run_on_start: true

    list_if_users:
      run: "user_report"
      shell: true
      schedule: "* 2 * * * *"
      tags: ['base', 'users']

调度器配置

调度器配置包含以下元素：

scheduler.output (可选): 设置所有作业的默认输出位置。
- stdout: 输出到控制台 (默认)。
- silent: 抑制所有输出。
scheduler.jobs: 要调度的作业对象，对象键描述作业名称。每个作业都有：
- schedule: 定义作业计划的 cron 表达式。 cron 可以是转换为 cron 语法的英语描述，也可以是 cron 语法本身。
  
  英语转 Cron
  - 示例:
  - every 15 seconds
  - run every minute
  - fire every day at 4:00 pm
  - at 10:00 am
  - run at midnight on the 1st and 15th of the month
  - On Sunday at 12:00
  - 7pm every Thursday
  - midnight on Tuesdays
  Cron 语法格式:
  
  cronjob 应该基于 UTC 时间
```
sec   min   hour   day of month   month   day of week   year
*     *     *      *              *       *             *
```
- run_on_start: 默认值为 false。如果设置为 true，则作业也会在调度器启动时运行。
  - shell: 默认值为 false，表示将 run 的值作为任务执行。如果为 true，则将 run 的值作为 shell 命令执行。
  - run: 要运行的定时任务命令。
    - Task: 任务名称 (带有变量，例如 [TASK_NAME] KEY:VAl。请参考这里查看任务参数)。请注意，shell 字段应为 false。
    - Shell: 运行 shell 命令 (例如 "echo loco >> ./scheduler.txt")。请注意，shell 字段应为 true。
  - tags (可选): 用于分类和管理作业的标签列表。
  - output (可选): 覆盖此作业的全局 scheduler.output 设置。

验证配置

设置好作业后，你可以验证配置以确保一切正确。

1. 当使用专用文件时:

运行以下命令以列出你的调度器文件中的作业：

cargo loco scheduler --config config/scheduler.yaml --list

2. 当使用基于环境的配置时:

要列出环境配置中的作业，请运行：

LOCO_ENV=production cargo loco scheduler --list

运行调度器

验证配置后，你可以删除 --list 标志以开始运行调度器。调度器将根据作业的计划持续执行作业，直到收到关闭信号。当收到信号时，它会优雅地终止所有正在运行的任务并安全关闭。

重要提示:

当作业运行时，Loco 会在一个新进程中生成它，并且所有环境变量都将传播到新的作业进程。
对于任务，请确保通过使用 --environment 标志或设置 LOCO_ENV 环境变量来使用有效的环境运行调度器。这确保为任务加载正确的环境和配置。
你可以使用任务配置中的 vars 对象将变量传递给任务。

按名称运行单个计划任务

要按名称运行特定的调度器作业，请使用 --name 标志。这将执行具有提供名称的单个作业。

LOCO_ENV=production cargo loco scheduler --name 'JOB_NAME'

此命令将在你的 scheduler.yaml 文件中找到名为 "Run command" 的作业并运行它。

按标签运行计划任务

你还可以运行共享相同标签的多个作业。标签对于将相关作业分组在一起很有用。例如，你可能有多个执行不同类型维护任务的作业——例如数据库清理、缓存失效和日志轮换——你想一起运行它们。为它们分配相同的标签，例如 maintenance，允许你一次执行所有这些作业。

LOCO_ENV=production cargo loco scheduler --tag 'maintenance'

此命令运行所有标记为 maintenance 的作业，确保一次执行所有相关作业。

调度器

设置