← 返回首页

Celery 与 huey 的任务重试:三次执行、一次副作用

Celeryhuey任务队列

任务队列最容易被误判的地方,不是「会不会重试」,而是「重试了几次、副作用跑了几遍」。这两件事在三个主流库里用的是三套不同的计数口径,而且没有一个会在出错时提醒你口径不一致。

我实际把 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.4retries=2未处理异常时重试 2 次3
Celery 5.6.3max_retries=2 + autoretry_for最多重试 2 次3
Celery 5.6.3max_retries 取默认类属性 Task.max_retries = 34(源码推算,未实测)
无重试配置——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 的环境跑:

三次执行总共 10 毫秒。countdown 确实被算出来写进了 Retry 的签名里,但 apply() 拿到 Retry 之后直接就地重跑,没有任何 sleep。同样配置在真实 worker 上是 1 秒再加 2 秒,eager 下是 0 加 0。

结论:eager 模式可以验证「重试了几次」和「最终抛什么异常」,不能验证重试节奏。要测节奏只能上真 worker,或者直接对 get_exponential_backoff_interval() 单测。

重试耗尽抛什么,取决于你传不传 exc

同一组对照:

两者执行次数都是 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 次:

第几次重试采样最小采样最大采样均值理论上限
1010.51
2021.02
3042.04
4084.08

均值刚好是上限的一半,最小值是 0。也就是说,默认配置下你实际等到的延迟,期望值只有文档写的那个上限的 50%。所以「指数退避」的真实形态是「指数上限 + 均匀随机」,不是「指数等待」。

还有一个配置层的细节值得记一笔:DEFAULTS['task_retry_jitter'] 的值是 None,不是 True。真正让默认值变成 True 的是 celery/app/autoretry.py 里这一行 getattr(task, 'retry_jitter', True)。查配置表看到 None 就以为没开 jitter,是查错了地方。

task_id 不是锁

我原以为固定 task_id 能当幂等键用。实测:

两个库都不做去重。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 的参数绑定,看不出和「参数传错类型」的关系,我第一次排查了十几分钟才反应过来。

幂等怎么做:四条按成本排序

反过来,如果你发现某个任务「重试两次就产生了 3 条记录」,先别改重试次数,先看它有没有上面四条里的任意一条。重试次数只影响「重复几遍」,幂等设计才决定「重复了会怎样」。

三个库怎么选,一句话版

三个库的依赖面与静默失效清单,我在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 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页