GoCron 定时调度实战:cron 表达式、时区与 DST 夏令时的避坑指南

原创2026-11-13 11:27:191,690 阅读

GoCron 定时调度实战:cron 表达式、时区与 DST 夏令时的避坑指南

GoCron 是一个用 Go + Vue.js 编写的自托管定时任务调度器(task scheduler):你在一份 YAML 文件里用标准 cron 表达式定义重复任务,它就在指定时间执行 shell 命令,并支持每个任务独立的环境变量。本文带你从零跑通 GoCron 定时调度,重点讲清楚 cron 表达式写法、time_zone 时区配置,以及 DST 夏令时切换这类最容易翻车的场景。

GoCron 定时任务调度器任务列表界面,展示各任务的 cron 表达式与执行耗时

一、GoCron 是什么?30 秒了解核心能力

GoCron 解决的是"在服务器/容器里优雅地跑定时任务"这个老问题,核心特性包括:

  • YAML 驱动:任务、cron 调度、环境变量全部集中在一个配置文件里,改完自动热加载,无需重启;
  • 标准 5 字段 cron 表达式:底层使用成熟的 robfig/cron 调度库(见 internal/scheduler/scheduler.go);
  • 每任务独立环境变量:支持 ${VAR} 变量展开,任务级变量覆盖默认值;
  • Web UI:查看任务、手动触发、实时看日志,运行历史持久化在 SQLite 中;
  • 健康检查回调:任务开始、结束、失败三个节点都能发 HTTP 请求,方便接入告警。

参考配置(带完整注释)在 config/config.example.yaml 中,首次启动会自动生成。

二、最快启动方法:一条命令跑起来

直接用 Docker 运行,GoCron 会在首次启动时自动生成带示例任务的默认配置:

docker run -it --rm \
  --name gocron \
  -p 8156:8156 \
  -v ./config/:/app/config/ \
  ghcr.io/flohoss/gocron:latest

打开 http://localhost:8156 即可在 Web 界面查看任务、手动触发运行。编辑 ./config/config.yaml 添加你自己的任务,改动会被自动感知(日志中出现一条 Configuration reloaded 即生效),无需重启容器。

最小可用的配置文件长这样:

time_zone: 'UTC'        # 所有调度都按此时区执行
job_defaults:
  cron: '0 3 * * 0'     # 未单独指定 cron 的任务继承该默认值
jobs:
  - name: 'Nightly Backup'
    cron: '0 5 * * 0'   # 覆盖默认值:每周日凌晨 5 点
    timeout: '30s'
    retries: 2
    commands:
      - restic backup /data

几个和调度直接相关的机制(完整语义见 README.md 的 Failure semantics 一节):

  • 单飞(single-flight):同一时间只有一个任务在跑,新到的调度会被跳过而不是排队;
  • 错过不补跑:容器停机期间到点的任务,重启后不会补执行,也没有 @reboot 语义;
  • 优雅退出:收到 SIGTERM/SIGINT 时停止调度、取消运行中的命令,并把记录标记为 Canceled。

三、cron 表达式写法:5 个字段 + 默认值继承

GoCron 使用标准 5 字段 cron 表达式:分 时 日 月 星期。

表达式 含义
*/5 * * * * 每 5 分钟一次
0 9 * * 1-5 工作日每天 9:00
0 0 1 * * 每月 1 号零点
0 5 * * 0 每周日 5:00(示例配置中的夜间备份)

写错会发生什么?表达式会在配置加载阶段被校验拒绝(validate:"omitempty,cron",见 config/config.go),非法表达式会直接给出报错而不是静默跳过任务;调度器层面也会再次拒绝非法 cron(见 internal/scheduler/scheduler_test.go 中的 not a cron 用例)。配置热加载失败时保留旧配置,服务不会挂掉。

三个容易忽略的继承规则:

  1. 任务不写 cron 时继承 job_defaults.cron;两者都没有,任务退化为"仅手动触发"(等价于 disable_cron: true);
  2. 相同 cron 的任务会被合并到同一个调度分组里批量执行(见 services/jobs.go),所以把多个备份任务设成同一时刻,它们会串行排队,注意总时长别超过间隔;
  3. disable_cron: true 的任务只出现在 UI 里供手动触发,很适合放耗时的运维操作。

四、时区配置:time_zone 一个字段定乾坤

这是新手最容易踩的第一类坑:"任务怎么不在我预期的时间跑?"答案通常是时区没配。

time_zone: 'Europe/Berlin'
  • 必须使用 IANA 时区名(如 UTC、Asia/Shanghai、Europe/Berlin)。写 Mars/Olympus_Mons 这种不存在的值会在启动时报 unknown time zone 错误(用例见 config/config_test.go);
  • 不配置 time_zone 时回落到容器/系统时区(time.Local,见 config/config.go)。Docker 容器默认是 UTC——这是"北京时间零点任务在早上八点才跑"这类诡异现象的元凶。生产环境强烈建议显式写死 time_zone,别依赖宿主机的 TZ;
  • 时区改动支持热加载:修改 time_zone 后调度器会整体重建到新时区(见 services/jobs.go),日志打印 Configuration reloaded 即生效;
  • 时区不仅影响调度,还会通过 TZ 环境变量注入到每条任务命令中(见 config/config_test.go),任务里 date 打印的时间与调度时间保持一致,排查问题时很好用;
  • 时区数据库随 Go 运行时内嵌(time/tzdata),即使精简版镜像缺少系统 tzdata,任意 IANA 时区也能正确解析。

⏰ 小技巧:在 Web 终端里跑一条 date 确认容器实际时区,比翻文档更快定位问题。

GoCron 定时任务执行日志界面,展示每条命令的执行时间与完整输出

五、DST 夏令时避坑:切换当天任务可能"消失"或"重复"

配置了 time_zone 之后,还有一个更隐蔽的坑:夏令时(DST)切换日。官方文档(README.md 的 "Time zones and DST" 一节)明确说明了标准 cron 语义下的行为:

  • 春季"往前拨"(如欧洲 3 月最后一周,凌晨 2:00 直接跳到 3:00):那一小时根本不存在,你的 cron 表达式如果恰好指向被跳过的小时(比如 0 2 * * *),那天就一次都不会触发,且不会补跑;
  • 秋季"往回拨"(10 月最后一周,3:00 又回到 2:00):被重复的那个小时内到点的任务,可能触发一次或两次;
  • GoCron 不做任何"补跑/去重"魔法,行为与标准 cron 一致——请在 DST 切换前后主动测试你的调度。

给生产环境的 4 条建议:

  1. 避开 02:00–03:00 的 DST 危险窗口:能放到 04:00 之后的批处理尽量后移,天然免疫"被跳过的小时";
  2. 全局时区统一用业务所在时区或 UTC 二选一,并在任务内部打印 date 留痕,方便切换日对账;
  3. 关键任务加 retries 与超时:timeout: '30s'、retries: 2(单命令粒度,立即重试、无退避),降低切换日网络抖动导致的失败;
  4. 配置 healthcheck 回调:在 healthcheck 段为 start/end/failure 三个节点发 HTTP 请求,"任务没跑"和"任务失败"都能被外部监控感知(示例见 config/config.example.yaml)。

GoCron 任务筛选与批量选择界面,可按调度状态筛选 cron 任务

六、可观测性:在 Web UI 里验证你的调度

配好 time_zone 和 cron 之后,验证闭环都在 Web 界面里完成:

  • 任务详情页:每条命令的执行时间戳、退出状态一目了然,任务历史存于 SQLite,保留天数由 delete_runs_after_days 控制(0 为永久保留);
  • 实时流式日志:运行输出通过 Server-Sent Events 推送,无需轮询刷新;
  • 任务筛选:可按 All / Scheduled / Non-Scheduled 等维度批量选择任务,手动触发验证(对应 web/src/components/JobSelectModal.vue);
  • 受限终端:UI 内置终端受 terminal.allowed_commands 白名单控制,适合跑 date、restic version 这类只读排查命令(见 config/config.example.yaml)。

GoCron Web 界面内置受限终端,可用于执行白名单内的排查命令

七、避坑清单:调度配置上线前逐条核对

# 检查项 正确姿势
1 时区是否显式配置 time_zone: 'Asia/Shanghai',不依赖容器默认 UTC
2 时区名是否为合法 IANA 名 非法值启动即报 unknown time zone
3 cron 是否为标准 5 字段 非法表达式在加载阶段被拒绝
4 任务是否落在 DST 危险小时 避开当地 02:00–03:00,切换日前后实测
5 同 cron 任务总数时长 单飞串行执行,总量别超过调度间隔
6 停机期间是否需要补跑 GoCron 不补跑,重要业务用 healthcheck 兜底
7 改配置是否要重启 任务、cron、time_zone 均热加载生效

GoCron 的设计哲学很克制:标准 cron 语义、不藏私、行为可预测。把 time_zone 显式写死、把关键任务移出 DST 窗口、再配一条 healthcheck 回调,你的定时调度在一年四季里都能稳稳跑起来。

相关文件索引

登录后查看全文
gocron