cronx —— 定时任务调度(代码注册 + DB 覆盖 + 两层去重)
定时任务要处理两件事:任务本体在代码里(后台只能改频率和启停), 运行侧保证多副本下同一个任务只有一个实例在跑。 cronx 提供代码注册表、DB 覆盖、两层去重、执行记录与优雅停机。
⚠️ Windows 上没有官方 Redis ——
job.lock_mode=redis(生产多副本必须)之前 先装一个:Memurai(Redis 协议兼容, 装成 Windows 服务,默认127.0.0.1:6379、无密码)。 Developer 版仅供开发/测试,不许上生产。 详见 快速开始。
功能
cronx 解决五件事:
- 代码注册表:任务本体只写在代码里(
cronx.Register)。 DB(sys_job表)只能覆盖 cron 表达式和启停,凭空长不出任务 —— 那样长出来的任务没有代码,重启即消失,而且没人知道它曾经存在过。 - DB 覆盖:后台改频率 / 改启停 / 改备注,写
sys_job行; 运行期热更新(Reload)会立刻重注册 cron entry,不用重启进程。 - 两层去重,各挡各的,只上一层都不够:
- Layer 0 查库:
SELECT ... FROM sys_job_run WHERE job_key=? AND status='running'挡住"上一次还没跑完就又跑"。不依赖 Redis —— DB 是所有副本都有的东西, 比任何外部锁服务都少一个失效点,执行记录表本来就要建,去重是白送的。 - Layer 1 加锁:Redis
SETNX+ Lua CAS 释放 + 看门狗续期。 挡住"两个副本在同一毫秒同时开跑" —— robfig 按绝对墙钟触发, 所有副本在同一瞬间醒来,Layer 0 是 check-then-act,关不掉这个窗口。
- Layer 0 查库:
- 降级 fail-open,但降级后仍剩 Layer 0:锁不可用时继续跑 + 大声告警 +
执行记录写
degraded标记。定时任务停摆比偶尔重复执行更难发现 (同步不更新、过期授权不下榜,都是静默的),但重复执行会写坏数据。 折中是把安全性建立在"handler 必须幂等"这条硬契约上, 显式声明NonIdempotent的任务在降级模式下被主动跳过。 - 执行记录 + 崩溃回收 + 优雅停机:每次执行落一条
sys_job_run; 启动时回收进程崩溃遗留的running行;停机时先停止触发、等在跑的任务、 预算耗尽再强杀。
它不解决:
- 不提供"业务定时任务"。业务任务由各业务模块在自己的包里
cronx.Register(约定前缀biz.*),框架层只管调度机制。 - 不做分布式事务、不做任务编排(DAG / 依赖 / 重试补偿)。
- 不管"执行记录保留多久" —— 那是 jobs 里
framework.job_history_purge任务的职责。
配置
yaml 侧(job: 块)
job:
enabled: true # 总开关。false ⇒ 一个 cron entry 都不注册
timezone: Asia/Shanghai # 调度时区。配错的名字会**启动直接失败**
# 去重层 1(分布式锁)的存储:
# auto — 有 Redis 用 Redis,没有退进程内锁 + 降级告警(单副本安全)
# redis — 强制 Redis,没配直接**拒绝启动**(生产多副本必须用这个)
# memory — 强制进程内锁,即使配了 Redis 也不连(仅单副本)
# off — 完全不锁,仅本地开发
lock_mode: auto
lock_ttl: 30s # 锁租约。长任务靠看门狗每 lock_ttl/3 续期
lock_renew: true # 关掉看门狗 = 长任务跑到一半锁过期,别的副本抢进来并发写
default_timeout: 30m # 单次执行超时,任务未单独指定时的兜底
shutdown_timeout: 30s # 优雅停机预算,用完强杀在跑任务(记 failed)
# 执行记录(sys_job_run)清理 —— 由内置任务 framework.job_history_purge 执行
history_retention_days: 30
history_retention_max: 50000
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
job.enabled |
bool | true |
调度总开关。关掉后既不注册也不触发 |
job.timezone |
string | Asia/Shanghai |
调度时区。必须显式配,见下方注意事项 |
job.lock_mode |
string | auto |
auto / redis / memory / off |
job.lock_ttl |
duration | 30s |
锁的故障恢复时间(持锁副本崩溃后别人最多等这么久),不是任务时长上限 |
job.lock_renew |
bool | true |
看门狗续期开关 |
job.default_timeout |
duration | 30m |
Job.Timeout 为 0 时用它 |
job.shutdown_timeout |
duration | 30s |
停机预算,用完强杀 |
job.history_retention_days |
int | 30 |
执行记录保留天数(归 jobs 用) |
job.history_retention_max |
int | 50000 |
执行记录条数上限(同上) |
代码侧(构造选项)
cronx.Register(job Job) // 注册任务(包 init 或 main 装配期调)
cronx.New(cfg Config, store Store, locker Locker) (*Scheduler, error)
cronx.ResolveLocker(mode string, rdb *redis.Client, prefix string) (Locker, error)
cronx.NewStore(db *gorm.DB) Store // gorm 实现;db 为 nil ⇒ 无记录、无 Layer 0
cronx.SetDefault(s *Scheduler) // 登记全局单例
cronx.Default() *Scheduler // 取全局单例;未装配返 nil(不 panic)
cronx.InitMetrics(reg prometheus.Registerer) // 注册指标(重复调用 panic)
Config 字段:Enabled / TimeZone / LockMode / LockTTL / LockRenew /
DefaultTimeout / ShutdownTimeout / OnFinish。
⚠️ Config 刻意没有历史保留期字段 —— 清理执行记录不是调度器的内建行为,
曾经声明过 HistoryKeepDays / HistoryKeepMax 两个字段,一行都没读过。
OnFinish func(ctx context.Context, rec *model.SysJobRun) 是回调,
不是直接 import pkg/push:依赖方向是 cmd/server → cronx,
cronx 自己不知道"事件要推给谁、推成什么形状、哪个 topic 需要哪个权限"。
传 nil = 不通知(零开销)。
使用方法
完整示例:examples/cronx/main.go。
一、注册任务(必须早于 cronx.New / Start)
cronx.Register(cronx.Job{
Key: "framework.demo_purge",
Name: "示例:清理过期数据",
Description: "演示用的框架任务",
Cron: "0 3 * * *",
Enabled: true,
Handler: func(ctx context.Context) error {
// 真实任务在这里做清理
return nil
},
})
Job 的字段:Key / Name / Description / Cron / Timeout / Enabled /
NonIdempotent / Handler。
⚠️ Handler 必须尊重 ctx —— ctx 到 deadline 会取消;不检查 ctx 的任务会一直跑,
而它的锁到期后会被第二个副本抢走,两个副本并发写同一批数据。
二、装配 + 启动 + 停机
// 生产装配:
locker, err := cronx.ResolveLocker(cfg.Job.LockMode, repository.GetRedis(), cronx.DefaultLockKeyPrefix)
if err != nil {
log.Fatal("cronx: 锁模式装配失败,拒绝启动", zap.Error(err))
}
sched, err := cronx.New(cronx.Config{
Enabled: true,
TimeZone: "Asia/Shanghai",
LockMode: "redis",
LockTTL: 5 * time.Minute,
LockRenew: true,
DefaultTimeout: 10 * time.Minute,
ShutdownTimeout: 30 * time.Second,
}, cronx.NewStore(db), locker)
if err != nil {
log.Fatal("cronx: 调度器装配失败,拒绝启动", zap.Error(err))
}
cronx.SetDefault(sched)
if err := sched.Start(context.Background()); err != nil {
log.Error("cronx: 启动失败,定时任务未运行", zap.Error(err))
}
defer sched.Shutdown(ctx)
Start 做三件事:读 DB 覆盖值 + reconcile 残留行 → 回收崩溃遗留的 running 行 →
逐个注册 cron entry。
三、表达式校验与预览
schedule, err := cronx.ParseCron("0 3 * * *") // 用与调度器完全相同的 parser
runs, err := cronx.NextRuns("0 3 * * *", 3, time.Local) // 未来 3 次触发时间
NextRuns 是纯计算,成本极低,用来在后台"改频率"时实时预览"下一次是几点"。
四、触发
// 同步(手动触发,HTTP handler 直接调):
run, err := sched.Trigger(ctx, "framework.demo_purge", cronx.TriggerManual)
// 异步(cron 回调用):
sched.TriggerNow(ctx, "framework.demo_purge", cronx.TriggerSchedule)
Trigger 返回 *model.SysJobRun(本次执行记录),错误有四种语义不同的状态:
| 错误 | 含义 | 运维处置 |
|---|---|---|
ErrJobNotFound |
代码注册表里没这个 key | 查注册 |
ErrJobDisabled |
code.Enabled && DB.Enabled 为 false |
查启停 |
ErrJobRunning |
上一次还在跑 / 锁被别人持有 | 正常 |
ErrDegraded |
去重能力降级,本次主动放弃(仅 NonIdempotent 任务) |
要去查 Redis |
五、查状态 / 热更新
list := sched.List() // 全部任务的生效配置
eff, err := sched.Get("framework.demo_purge")
sched.NextRunAt("framework.demo_purge") // 下次触发时间(未注册则返零值)
sched.Runtime() // RuntimeInfo:锁是否可用、实例 ID、已注册数
sched.Override("framework.demo_purge") // 当前 DB 覆盖行(后台"恢复默认"用)
sched.Reload("framework.demo_purge", ov) // 应用 DB 覆盖 + 立刻重注册 cron entry
Effective 同时带生效值与代码默认值(CronExpr / CronOverridden / DBEnabled),
后台要同时显示两者 —— 否则排查时不知道跑的是哪个。
六、给执行记录带上操作人
ctx = cronx.WithOperator(ctx, "zhangwei") // API 层拿到 Caller 后塞进来
cronx 是 pkg 层,不能 import internal/service(会形成反向依赖环),
操作人只能靠 ctx 传。
注意事项
⚠️
cronx.Register撞 key 会 panic,而且注册必须早于cronx.New/Start。 注册表在Start里被一次性快照(registeredKeys()):快照之后才注册的任务 永远没有 cron entry,NextRunAt是零值,而且没有任何报错、没有日志。 全局只能注册一次 —— 所以RegisterAll这类"注册多个任务"的入口只能由 main 装配期调一次。⚠️ cron 表达式全部避开整点整分。所有副本按绝对墙钟触发,
0 4 * * *意味着每个副本在 04:00:00.000 同时醒来:即使有去重锁, 同时发起 N 个加锁请求本身也是无谓压力,而去重窗口(Layer 0 的 SELECT + Layer 1 的 SETNX)会在那一刻最拥挤。本仓两个框架任务错开在17 4 * * *和23 9 * * *。⚠️
job.timezone必须显式配。容器里 TZ 没设时time.Local == UTC,0 3 * * *会在北京时间 11:00 跑,而配置文件里明明写着Asia/Shanghai—— 看起来配置生效了,实际没生效,因为任务确实跑了,只是跑在了错误的时间。 配错的名字(时区名写错)会启动直接失败,不会带着错时区继续跑。⚠️
job.enabled: false⇒ 一个 entry 都不注册,Start打一行 Info 就返回 nil。 没有错误、没有告警级别,症状是"所有任务永远不跑"。 (yaml 里漏配不会触发这个 —— viper 有job.enabled默认true。)⚠️ 启动日志里的
registered数字会把"已停用的任务"也算进去。Start里failed只统计注册出错的任务,EnabledEffective()为 false 的任务register()直接返 nil、不进entries,但它仍算在len(keys)-failed里。 真实注册数看sched.Runtime().Registered(=len(s.entries))。⚠️ 最终生效 =
code.Enabled && DB.Enabled(AND,不是只看 DB)。 这样做是刻意的:从代码里删掉任务一定等于停用,不会因为 DB 残留行而"复活"。 反过来说,DB 里存在但代码里没有的job_key会在启动时被reconcile置is_active=false并 WARN —— 不是直接删:删掉会丢掉运维当初设的 cron 覆盖值和备注。⚠️
lock_mode=redis而没配 Redis ⇒ 启动失败(ResolveLocker返 error,cmd/server直接 Fatal)。auto没配 Redis 则退进程内锁 + 降级告警 —— 多副本部署下这意味着同一个任务会被多个副本同时跑。 未知lock_mode也直接报错,不静默当auto处理("我配了 X,系统跑的是 Y" 是最难查的一类配置问题)。⚠️ 锁的释放与续期必须是 CAS(Lua)。裸
DEL的路径是: A 跑超时 → 锁 TTL 到期 → B 抢到锁开始跑 → A 结束时裸DEL→ 把 B 的锁删了 → C 立刻抢到并发跑。CAS 是这条路径上唯一的防线。⚠️ owner token 必须每次运行都不同。用固定的 instanceID 的话, 同一副本重试两次会拿到同一个 owner,第一次的 CAS 释放会误删第二次的锁。
⚠️ 看门狗发现锁丢了必须真的
cancel()掉 run ctx,只return不够 —— handler 拿不到任何信号,会照跑到底,于是两个副本真的并发写同一批数据。⚠️ 两层各自独立降级,不能合成一个 degraded 开关。早先把它们合成一个, 结果"DB 查不到"会连带把加锁整段跳过 —— 而 Redis 明明好着, 跨副本互斥恰恰是最该保住的那一层。现在
lockUsable只看锁层,layer0OK只看查库层,degraded只是给执行记录 / 指标用的汇总标记。⚠️
Reload漏掉重注册是最容易犯的错:只写 DB 的话,robfig 里注册的还是旧表达式, 改频率要等进程重启才生效 —— 而且没有报错、没有日志,测试也可能绿 (如果测试只断言 DB 变化、不断言 entry 生效)。Reload失败时会真回滚: 撤销 entry、用旧值重新register,不允许留下"DB 说启用、实际没注册"的状态。⚠️ DB 覆盖行的
Description必须在LoadOverrides里读出来。漏掉的话: 运营在后台写备注,当次生效(Reload拿到的是完整 ov),重启后读回来的Description是空 →merge判ov.Description != ""不成立 → 悄悄回退到代码默认值。症状是"备注自己消失了",没有任何报错。⚠️
cronx.InitMetrics重复调用会 panic(prometheus 不允许重名注册)。 这是刻意的:让"初始化两次"在启动时炸,而不是让第二个 registry 拿到空指标。⚠️
Default()未装配时返nil而不是 panic。API 层要能在job.enabled=false时也把页面正常渲染出来(告诉运维"调度器没开"), 而不是整个后台 500。⚠️
cronx.Config里没有历史保留期字段。清理执行记录是 jobs 的framework.job_history_purge任务的事, 别在cronx.Config里找它。⚠️
Shutdown的预算用cfg.ShutdownTimeout,调用方传的 ctx 没有 deadline 时也一样生效 —— 不是只在 main.go 恰好传对时才有预算。预算耗尽后强杀在跑任务(记 failed)。⚠️
Handler返回的 error 会被截断到 2KB(truncate),panic 的 stack 也是 (走safeInvoke兜住,记成 failed)。手动触发走的是自己的Trigger路径,cron.Recover只兜 robfig 那条路,所以safeInvoke是独立的第二道防线。