CI/CD / 系统课时
配置定时任务与时区换算
配置定时任务与时区换算
定时清理、夜间构建和周期检查不需要人工提交代码来触发。GitHub Actions 可以通过 schedule 和 POSIX cron 表达式周期运行工作流,但计划时间按 UTC 解释,因此配置前必须先把业务所在时区的时间正确换算成 UTC。
学习目标
- 使用
schedule和 cron 表达式配置周期工作流 - 将本地计划时间正确换算为 UTC
- 识别夏令时、默认分支和定时执行延迟等边界
写出一个定时工作流
schedule 配置在 on 下,每个计划使用一个 cron 字段。下面的任务在每天 UTC 01:30 触发,并输出一次维护信息:
name: Daily Maintenance
on:
schedule:
- cron: '30 1 * * *'
jobs:
maintenance:
runs-on: ubuntu-latest
steps:
- name: Run maintenance
run: echo "Running scheduled maintenance"预期输出:
Running scheduled maintenance实际运行时间和日志时间戳属于动态值,可能与计划时刻存在少量偏差。这里的输出只对应示例中的命令,不表示 GitHub 保证任务恰好在秒级准点启动。
读懂 cron 的五个字段
GitHub Actions 的计划表达式按五个字段书写,顺序为“分钟、小时、日、月、星期”。例如 30 1 * * * 表示每天 UTC 01:30,而 0 3 * * 1 表示每周一 UTC 03:00。
┌──────── 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 * * *。

跨越午夜时必须同时调整日期条件。例如某个 UTC+8 场景要求“每周一当地 01:00”运行,对应 UTC 是前一天 17:00,因此星期条件也应落在星期日,而不能只把小时从 1 改成 17。
验证计划而不是等待猜测
提交工作流后,先人工完成三项检查:确认五个 cron 字段的位置、把 UTC 时间反算回目标当地时间、检查换算是否跨越日期或星期。对于关键任务,还应让任务本身记录执行时间,以便之后核对实际调度情况。
可以在维护步骤中同时打印 UTC 时间,帮助排查时区误判:
- name: Show execution time
run: date -u '+%Y-%m-%d %H:%M:%S UTC'预期输出格式:
<TIME> UTC<TIME> 是运行时动态生成的 UTC 日期和时间,实际值取决于任务真正获得 Runner 的时刻。
处理定时任务的运行边界
计划触发并不是实时调度器。GitHub Actions 在负载较高时可能延迟定时任务,尤其应避免把必须秒级准点执行的业务逻辑建立在它之上。定时工作流还与默认分支关联,因此修改工作流文件后,应确认计划配置已经存在于正确的默认分支版本中。
如果同一工作流需要多个周期,可以在 schedule 下声明多个 cron 项。任务需要区分是哪条计划触发时,可读取 github.event.schedule 与配置的 cron 字符串进行判断,而不必复制整份工作流。
对于夜间构建、周期巡检、依赖检查等允许一定启动延迟的工程任务,schedule 很合适;对于要求严格当地时间、需要自动处理夏令时或具有强实时约束的业务调度,应先确认 GitHub Actions 的 UTC cron 与调度特性是否满足要求。