asynq不能直接替代cron,因其不解析Cron表达式,仅支持延迟执行和重试;周期性调度需显式启用asynq.Scheduler组件,并确保单实例运行以避免重复触发。

asynq 不能直接替代 cron,它不解析 Cron 表达式
很多人一看到 asynq 就默认它能“定时”,其实不是。asynq 本身是任务队列(类似 Celery),只负责延迟执行(EnqueueIn)或定时重试(RetryPolicy),但**不支持 "0 0 * * *" 这类表达式驱动的周期性调度**。Kratos 里想实现“每天凌晨 1 点同步缓存”,不能只靠 asynq.Client —— 必须搭配一个独立的调度器(比如 asynq.Scheduler 或外部 asynqbeat)。
常见错误现象:
• 直接在服务启动时调用 client.EnqueueIn 设置 24 小时后执行,结果只跑一次就没了
• 把 asynq.ServeMux 当成定时触发器,发现任务从不自动重入
• 误以为 asynq.RedisClientOpt 配置完就能自动扫表调度
-
asynq.Scheduler是可选组件,需显式启动,且依赖 Redis 的 Lua 脚本支持(要求 Redis ≥ 6.0) - 它和
asynq.Server是两个独立进程角色:Scheduler 负责“生成任务”,Server 负责“消费任务” - Kratos 启动时若只初始化了
asynq.Client和asynq.Server,没启asynq.Scheduler,那所有周期性任务都不会触发
Kratos 中正确集成 asynq Scheduler 的三步初始化
关键点在于:Scheduler 必须和 Server 共享同一套 Redis 连接配置,且不能复用 Server 的 asynq.Config(Scheduler 有自己的 asynq.SchedulerConfig)。
- 在
internal/data/data.go初始化时,先创建共享的*redis.Client(别用asynq.RedisClientOpt包一层再传,容易导致连接池错乱) - 分别初始化:
–asynq.NewClient(供业务代码发任务)
–asynq.NewServer(监听并执行任务)
–asynq.NewScheduler(按 Cron 表达式生成任务) - Scheduler 启动必须早于 Server,否则首次调度可能丢失(
scheduler.Start()应在server.Run()前)
示例片段(非完整代码,仅示意关键调用顺序):
// 使用同一 redis client
redisCli := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
<p>client := asynq.NewClient(asynq.RedisClientOpt{Client: redisCli})
server := asynq.NewServer(
asynq.RedisClientOpt{Client: redisCli},
asynq.Config{Concurrency: 10},
)
scheduler := asynq.NewScheduler(
asynq.RedisClientOpt{Client: redisCli},
&asynq.SchedulerConfig{Location: time.UTC},
)</p><p>// 注意顺序:先 scheduler,再 server
scheduler.Start()
go server.Run()
如何定义一个每天执行的 asynq 定时任务
不能把业务逻辑直接写进 asynq.HandlerFunc 并期望它自动周期运行——必须通过 scheduler.Register 绑定 Cron 表达式与任务类型。
- 任务类型名(如
"sync_cache")必须和asynq.NewTask("sync_cache", payload)中的第一个参数完全一致 - payload 必须是 JSON-serializable map 或 struct;
asynq不支持传递闭包或函数引用 - Cron 表达式格式为 Unix cron(5 字段),不是 Quartz(6 字段),所以
"0 0 1 * *"表示每天 1:00,而非"0 0 0 1 * ?" - 如果任务执行失败,Scheduler 默认不会重试该调度点(它只管“生成任务”,不管“执行成败”);重试逻辑需在 Handler 内用
task.Retry或asynq.ProcessError控制
注册示例:
// 在 scheduler.Start() 后调用
scheduler.Register("0 0 1 * *", asynq.TaskHandlerFunc(func(ctx context.Context, t *asynq.Task) error {
// 从 t.Payload 解析参数,例如:
var payload map[string]string
if err := json.Unmarshal(t.Payload(), &payload); err != nil {
return err
}
// 执行实际业务:db 查询、redis 写入等
return syncCacheToRedis(payload["key"])
}))
分布式环境下防重复执行的关键控制点
Kratos 多实例部署时,如果每个实例都启一个 asynq.Scheduler,就会导致每天 1 点生成 10 个重复的 sync_cache 任务——这是最常被忽略的坑。
-
asynq.Scheduler本身**不具备集群选主能力**,它不依赖 ZooKeeper 或 etcd,只靠 Redis 的 SETNX 实现单点写入,但这个锁只保护“同一时刻不重复生成同个任务”,不保护“多个 Scheduler 实例同时启动” - 解决方案只有两个:
– **强制单实例调度**:用 Kubernetes 的job或deployment的replicas: 1+ readiness probe 控制,确保整个集群只有一个 Scheduler 进程
– **改用中心化调度器**:把 Scheduler 剥离 Kratos,单独部署为一个服务,Kratos 实例只作为 Worker 连接它 - 即使用了单 Scheduler,任务 Handler 也必须设计幂等:比如用
SETNX cache:sync:20261009加临时锁,或检查目标数据的 last_updated 时间戳
真正难的从来不是“怎么让任务跑起来”,而是“怎么确认它只跑一次、只跑成功一次”。Scheduler 只解决触发,幂等和可观测性得自己补全。


















