GoCron 定时调度实战:cron 表达式、时区与 DST 夏令时的避坑指南
GoCron 定时调度实战:cron 表达式、时区与 DST 夏令时的避坑指南
GoCron 是一个用 Go + Vue.js 编写的自托管定时任务调度器(task scheduler):你在一份 YAML 文件里用标准 cron 表达式定义重复任务,它就在指定时间执行 shell 命令,并支持每个任务独立的环境变量。本文带你从零跑通 GoCron 定时调度,重点讲清楚 cron 表达式写法、time_zone 时区配置,以及 DST 夏令时切换这类最容易翻车的场景。
一、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 用例)。配置热加载失败时保留旧配置,服务不会挂掉。
三个容易忽略的继承规则:
- 任务不写
cron时继承job_defaults.cron;两者都没有,任务退化为"仅手动触发"(等价于disable_cron: true); - 相同 cron 的任务会被合并到同一个调度分组里批量执行(见 services/jobs.go),所以把多个备份任务设成同一时刻,它们会串行排队,注意总时长别超过间隔;
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确认容器实际时区,比翻文档更快定位问题。
五、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 条建议:
- 避开 02:00–03:00 的 DST 危险窗口:能放到 04:00 之后的批处理尽量后移,天然免疫"被跳过的小时";
- 全局时区统一用业务所在时区或 UTC 二选一,并在任务内部打印
date留痕,方便切换日对账; - 关键任务加
retries与超时:timeout: '30s'、retries: 2(单命令粒度,立即重试、无退避),降低切换日网络抖动导致的失败; - 配置 healthcheck 回调:在
healthcheck段为start/end/failure三个节点发 HTTP 请求,"任务没跑"和"任务失败"都能被外部监控感知(示例见 config/config.example.yaml)。
六、可观测性:在 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)。
七、避坑清单:调度配置上线前逐条核对
| # | 检查项 | 正确姿势 |
|---|---|---|
| 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 回调,你的定时调度在一年四季里都能稳稳跑起来。
相关文件索引
- 参考配置(含全部注释):config/config.example.yaml
- 时区解析与校验逻辑:config/config.go
- cron 调度器封装(robfig/cron v3):internal/scheduler/scheduler.go
- 配置热加载与调度重建:services/jobs.go
- 失败语义与 DST 行为说明:README.md



