Celery 与 huey 的任务重试:三次执行、一次副作用
任务队列最容易被误判的地方,不是「会不会重试」,而是「重试了几次、副作用跑了几遍」。这两件事在三个主流库里用的是三套不同的计数口径,而且没有一个会在出错时提醒你口径不一致。
我实际把 huey 3.5.4 和 Celery 5.6.3 装在隔离目录里跑了同一组任务:一个必然失败的任务、一个失败两次后成功的任务、一个固定 id 被投递两次的任务。下面每个数字都是本机 CPython 3.13.12 + Windows 11 跑出来的,不是文档抄的。
TL;DR:默认配置下,huey 的 retries=2 表示总执行 3 次;Celery 的 max_retries=2 也表示总执行 3 次,但不传 countdown 的重试会等 180 秒;两个库都不对 task_id 去重;Celery 的退避默认带 jitter,文档说的「第一次 1 秒」只是上限,实测期望值 0.5 秒。acks_late 换来的不是「不丢」,而是「可能重复」。
三套计数口径,先摆在一张表上
| 库 | 参数 | 文档语义 | 实测总执行次数 |
|---|---|---|---|
| huey 3.5.4 | retries=2 | 未处理异常时重试 2 次 | 3 |
| Celery 5.6.3 | max_retries=2 + autoretry_for | 最多重试 2 次 | 3 |
| Celery 5.6.3 | max_retries 取默认 | 类属性 Task.max_retries = 3 | 4(源码推算,未实测) |
| 无重试配置 | — | — | 1 |
前两行我各跑了 3 轮,次数稳定。第三行是源码常量 Task.max_retries = 3,意思是手动 self.retry() 不指定上限时,最多会跑到第 4 遍,这个我没有单独跑,只做源码取证。
真正会坑人的是第四行:默认就是 1 次。没配重试的任务失败就是失败,队列不会替你兜底。
huey 的 retries 是「还剩几次」
huey 的实现是倒计数。huey/api.py 里的 _requeue_task() 第一行就是 task.retries -= 1,然后把任务重新入队。所以 retries=2 进来,第一次执行失败 → 剩 1 → 第二次失败 → 剩 0 → 第三次失败 → final = not task.retries 成立,错误才写进结果后端。
这就是为什么表里是 3 次而不是 2 次。官方文档的措辞是「number of times to retry the function if an unhandled exception occurs」,字面没错,但读成「总次数」就差了整整一倍。
重试还没结束,错误已经出现在结果里
这是 huey 最容易造成监控误报的一处。SqliteHuey 的 store_intermediate_errors 默认是 True(官方原文:Defaults to True for backwards compatibility),意思是「任务失败了但还有重试次数」时,异常当场写进结果存储。
我实际测了一遍:一个 retries=3, retry_delay=1 的任务,第一次失败后 0.5 秒就去读结果,拿到的是 TaskException 包着 ValueError('attempt-1') —— 而此刻任务还在重试队列里,最终会成功。
如果你的告警规则是「结果后端出现 TaskException 就报警」,那么每一条最终成功的任务都会先报一次警。要么把 store_intermediate_errors 设为 False,要么在告警里读 Error 元数据里的 retries 字段判断是否已经耗尽。
顺带一个反直觉的地方:h.result() 默认 preserve=False,读一次就把结果从存储里 pop 掉。我第一次写探针时读了两次,第二次拿到 None,差点记成「重试把结果弄丢了」。要重复读必须显式 preserve=True。
重试确实耗尽之后,错误形态是 TaskException: ValueError('boom-A'),和中间态长得一样,只能靠 retries 字段区分。
Celery 的 180 秒:你以为在重试,其实在排队
Task.default_retry_delay 的类属性是 180。Task.retry() 的源码里写着:
if not eta and countdown is None:
countdown = self.default_retry_delay
也就是说 raise self.retry() 不传 countdown,任务会等 3 分钟才重新进队列。这不是 bug,是早年为「下游服务过载」设计的默认值,但在今天的心智模型里,「重试」几乎等于「马上再来一次」。
如果你要的是秒级重试,必须显式传 countdown=1,或者用 autoretry_for + retry_backoff。
直接调用 = 没有重试
Task.retry() 开头有这么一段:
if request.called_directly:
raise_with_context(exc or Retry('Task can be retried', None))
我实测:manual("direct") 直接调用,抛出的是 ValueError,不是 Retry,执行次数 1。在 REPL 里手调一次任务函数,你看到的是原始异常,重试逻辑根本没走。
同一段源码的注释写的是「Not in worker or emulated by (apply/always_eager), so just raise the original exception」。但注释和行为对不上:apply() 走的是 is_eager 分支,实测会真的重试 3 次。也就是说,注释把 apply 和「直接调用」混为一谈了,实际只有 called_directly 才不重试。
eager 模式会把退避吃掉
这是「用单测验证重试节奏」的经典陷阱。我把 retry_backoff=True、max_retries=2 的任务放进 task_always_eager=True 的环境跑:
- 执行次数:3
- 总耗时:0.010 秒
三次执行总共 10 毫秒。countdown 确实被算出来写进了 Retry 的签名里,但 apply() 拿到 Retry 之后直接就地重跑,没有任何 sleep。同样配置在真实 worker 上是 1 秒再加 2 秒,eager 下是 0 加 0。
结论:eager 模式可以验证「重试了几次」和「最终抛什么异常」,不能验证重试节奏。要测节奏只能上真 worker,或者直接对 get_exponential_backoff_interval() 单测。
重试耗尽抛什么,取决于你传不传 exc
同一组对照:
raise self.retry(exc=ValueError("mx"))→ 耗尽后state=FAILURE,result是ValueErrorraise self.retry()→ 耗尽后state=FAILURE,result是MaxRetriesExceededError
两者执行次数都是 3。官方文档那句「the current exception will be re-raised if the max number of retries has been exceeded, but this won't happen if an exc argument wasn't given」在这里是准确的 —— 传了 exc 就把原异常重新抛出来,没传就抛 MaxRetriesExceededError。
这条影响的是你的 except 分支:如果代码里 except MaxRetriesExceededError 做兜底,而你恰好传了 exc,这段兜底永远不会执行。
jitter 默认是开的,「第一次 1 秒」只是上限
官方文档写 retry_jitter「By default, this option is set to True」,同时又说 retry_backoff=True 时「the first retry will have a delay of 1 second」。两句都对,合起来容易被读成「第一次一定等 1 秒」。
实际上 full_jitter=True 时,延迟是 random(0, 上限)。我对 get_exponential_backoff_interval() 采样 2000 次:
| 第几次重试 | 采样最小 | 采样最大 | 采样均值 | 理论上限 |
|---|---|---|---|---|
| 1 | 0 | 1 | 0.5 | 1 |
| 2 | 0 | 2 | 1.0 | 2 |
| 3 | 0 | 4 | 2.0 | 4 |
| 4 | 0 | 8 | 4.0 | 8 |
均值刚好是上限的一半,最小值是 0。也就是说,默认配置下你实际等到的延迟,期望值只有文档写的那个上限的 50%。所以「指数退避」的真实形态是「指数上限 + 均匀随机」,不是「指数等待」。
还有一个配置层的细节值得记一笔:DEFAULTS['task_retry_jitter'] 的值是 None,不是 True。真正让默认值变成 True 的是 celery/app/autoretry.py 里这一行 getattr(task, 'retry_jitter', True)。查配置表看到 None 就以为没开 jitter,是查错了地方。
task_id 不是锁
我原以为固定 task_id 能当幂等键用。实测:
- Celery:
ok.apply_async(args=("id1",), task_id="dup-1")连投两次 → 执行 2 次 - huey:
once("C", id="fixed-id-1")连投两次 → 执行 2 次
两个库都不做去重。task_id 只是「这条消息的身份标识」,用于查结果、撤销、追踪,不是「同一个 id 只执行一次」的承诺。想靠它防重复,会在第一次重复消费时发现它什么都没挡住。
acks_late 换来的不是「不丢」,是「可能重复」
Celery 官方文档写得很直白:
the default behavior is to acknowledge the message in advance, just before it's executed, so that a task invocation that already started is never executed again.
默认在执行前就 ack。所以 worker 在执行途中被 kill,消息已经没了,任务不会重投。开 acks_late 之后变成执行后 ack:
This means the task may be executed multiple times should the worker crash in the middle of execution. Make sure your tasks are idempotent.
同一个页面的 FAQ 还有一句更关键的:
if the task raises an exception it's still acknowledged!
任务抛异常也算 ack。 所以「重试」这件事在 Celery 里根本不由 ack 机制负责,只由 retry() 负责。acks_late 管的是「进程死了」,不管「代码报错了」。
源码常量三处(Celery 5.6.3):task_acks_late = False、task_reject_on_worker_lost = None、worker_prefetch_multiplier = 4。第二个是 None 而不是 False,意思是「跟随 acks_late 的语义」,不是「关闭」。
取证边界:本机没有 Redis 与 RabbitMQ,我只做了 eager 模式实测、源码常量取证、官方原文引用,没有跑真实的 redelivery 场景。要知道崩溃后到底会不会重投,得在你自己的 broker 上压一次强制杀进程。
Troubleshooting:三个我真实撞到的报错
AttributeError: 'bytes' object has no attribute 'eta'
我试图绕过 consumer 直接驱动队列:task = h.storage.dequeue() 然后 h.execute(task)。SqliteHuey.dequeue() 返回的是序列化后的 bytes,不是 Task 对象。要先 h.deserialize_task(data),或者干脆用 h.create_consumer()。我最后走的是 consumer 路线,因为那才是生产路径。
ValueError: signal only works in main thread of the main interpreter
把 consumer.run() 放进 threading.Thread 起后台消费者,第一次就崩。huey 的 Consumer.start() 会调 _set_signal_handlers(),而 signal.signal() 只能在主线程注册。测试里要么在子线程里把 _set_signal_handlers 替换成空函数,要么用 multiprocessing 起独立进程 —— 后者更接近生产,也更不会掩盖问题。
ProgrammingError: Error binding parameter 2: type 'Result' is not supported
h.result(r) 我传的是 Result 对象,而它要的是 task_id 字符串。正确写法 h.result(r.id)。这个报错来自 sqlite3 的参数绑定,看不出和「参数传错类型」的关系,我第一次排查了十几分钟才反应过来。
幂等怎么做:四条按成本排序
- 有天然唯一键就用唯一索引。订单号、消息 id、文件路径,直接
INSERT ... ON CONFLICT DO NOTHING,让数据库替你挡第二次。 - 没有唯一键就落「意图」表。执行前先写一行
(task_id, status='started'),唯一索引在task_id上;第二次进来直接命中冲突退出。 - 调外部 API 用供应商的幂等键。支付网关的
out_trade_no、Stripe 的Idempotency-Key,这类接口的幂等由服务端保证,比自己写锁可靠。 - 通知类任务设去重窗口。同一个用户同一类通知,10 分钟内只发一次;窗口存在 Redis 或数据库都行,关键是窗口要比重试周期长。
反过来,如果你发现某个任务「重试两次就产生了 3 条记录」,先别改重试次数,先看它有没有上面四条里的任意一条。重试次数只影响「重复几遍」,幂等设计才决定「重复了会怎样」。
三个库怎么选,一句话版
- 只要重试、不要持久化、进程内能跑完 → 别上队列,
tenacity就够。这层我在10-24 那篇 retry 实测里做过对照。 - 单机、任务量小、能接受 SQLite 的锁边界 →
SqliteHuey,retries记住是「还剩几次」。 - 要跨机器、要 ack 语义、要有 beat 调度 → Celery,但必须自己解决幂等,因为它只保证「至少一次」。
三个库的依赖面与静默失效清单,我在11-01 那篇三库对照里已经逐条跑过;本篇只回答「失败之后会发生什么」,两篇不重叠。
常见问题
Q:retries=0 和 retries=-1 有什么区别?
huey 里 0 是不重试;负数在源码里 task.retries -= 1 会一直往下减,final = not task.retries 对负数恒为 False,等于无限重试。要用无限重试请显式确认这个行为,别靠写 -1 猜。
Q:Celery 的 max_retries=None 是什么语义?
官方原文「A value of None means task will retry forever」。不是「不重试」,是「永不放弃」。想不重试请写 0。
Q:为什么我设了 retry_backoff=True 但任务还是立刻重跑?
先确认是不是跑在 task_always_eager=True 下。eager 模式不 sleep,这是我实测 0.010 秒跑完三次的直接原因。
Q:任务重复执行了,是 acks_late 的锅吗?
先看有没有开 acks_late。默认 task_acks_late = False,执行前就 ack,正常不会因为崩溃重投。重复更可能来自 retry() 被调用,或者上游投递了两次。
结语
这一轮最值钱的不是哪个库更好,而是三个数字:retries=2 等于 3 次执行、默认 countdown 是 180 秒、task_id 不去重。这三个都写在文档里,但没有一个会在你写错时报错。
队列系统的默认值几乎全都是「为可靠性让路」的选择,而可靠性在分布式里的唯一实现方式是「至少一次」。既然至少一次,重复就是常态,幂等才是必答题。
本文不含任何联盟推广链接,所有代码与数字均为本机实测或官方文档原文引用。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。