CI/CD / 系统课时

配置定时任务与时区换算

配置定时任务与时区换算

定时清理、夜间构建和周期检查不需要人工提交代码来触发。GitHub Actions 可以通过 schedule 和 POSIX cron 表达式周期运行工作流,但计划时间按 UTC 解释,因此配置前必须先把业务所在时区的时间正确换算成 UTC。

学习目标

  • 使用 schedule 和 cron 表达式配置周期工作流
  • 将本地计划时间正确换算为 UTC
  • 识别夏令时、默认分支和定时执行延迟等边界

写出一个定时工作流

schedule 配置在 on 下,每个计划使用一个 cron 字段。下面的任务在每天 UTC 01:30 触发,并输出一次维护信息:

yaml
name: Daily Maintenance

on:
  schedule:
    - cron: '30 1 * * *'

jobs:
  maintenance:
    runs-on: ubuntu-latest
    steps:
      - name: Run maintenance
        run: echo "Running scheduled maintenance"

预期输出:

text
Running scheduled maintenance

实际运行时间和日志时间戳属于动态值,可能与计划时刻存在少量偏差。这里的输出只对应示例中的命令,不表示 GitHub 保证任务恰好在秒级准点启动。

读懂 cron 的五个字段

GitHub Actions 的计划表达式按五个字段书写,顺序为“分钟、小时、日、月、星期”。例如 30 1 * * * 表示每天 UTC 01:30,而 0 3 * * 1 表示每周一 UTC 03:00。

text
┌──────── minute (0-59)
│ ┌────── hour (0-23)
│ │ ┌──── day of month (1-31)
│ │ │ ┌── month (1-12 or JAN-DEC)
│ │ │ │ ┌ day of week (0-6 or SUN-SAT)
│ │ │ │ │
30 1 * * *

上面的代码块是 cron 字段位置说明,不是可执行命令;真正生效的是工作流 YAML 中 schedule 下的表达式。

GitHub Actions 的定时工作流最短调度间隔为 5 分钟。需要更高频率的任务时,不应通过编写更密集的 cron 表达式绕过这一限制。

把本地时间换算成 UTC

schedule 按 UTC 解释,不会读取仓库维护者电脑的本地时区。换算时可以使用关系“UTC 时间 = 本地时间 - UTC 偏移量”。例如马来西亚时间 MYT 为 UTC+8,计划每天当地 09:30 执行,就应配置前一天或当天对应的 UTC 01:30;这个例子没有跨日期,因此直接得到 30 1 * * *。

本地时间换算为 GitHub Actions UTC cron

跨越午夜时必须同时调整日期条件。例如某个 UTC+8 场景要求“每周一当地 01:00”运行,对应 UTC 是前一天 17:00,因此星期条件也应落在星期日,而不能只把小时从 1 改成 17。

验证计划而不是等待猜测

提交工作流后,先人工完成三项检查:确认五个 cron 字段的位置、把 UTC 时间反算回目标当地时间、检查换算是否跨越日期或星期。对于关键任务,还应让任务本身记录执行时间,以便之后核对实际调度情况。

可以在维护步骤中同时打印 UTC 时间,帮助排查时区误判:

yaml
- name: Show execution time
  run: date -u '+%Y-%m-%d %H:%M:%S UTC'

预期输出格式:

text
<TIME> UTC

<TIME> 是运行时动态生成的 UTC 日期和时间,实际值取决于任务真正获得 Runner 的时刻。

处理定时任务的运行边界

计划触发并不是实时调度器。GitHub Actions 在负载较高时可能延迟定时任务,尤其应避免把必须秒级准点执行的业务逻辑建立在它之上。定时工作流还与默认分支关联,因此修改工作流文件后,应确认计划配置已经存在于正确的默认分支版本中。

如果同一工作流需要多个周期,可以在 schedule 下声明多个 cron 项。任务需要区分是哪条计划触发时,可读取 github.event.schedule 与配置的 cron 字符串进行判断,而不必复制整份工作流。

对于夜间构建、周期巡检、依赖检查等允许一定启动延迟的工程任务,schedule 很合适;对于要求严格当地时间、需要自动处理夏令时或具有强实时约束的业务调度,应先确认 GitHub Actions 的 UTC cron 与调度特性是否满足要求。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置定时任务与时区换算

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通