单机任务队列三选一:七个不报错的失效
单机跑定时任务,最耗时间的从来不是写功能,而是「它到底有没有跑」。我实际在 Windows 11 + CPython 3.13.14 上把 huey 3.5.3、APScheduler 3.11.3、Celery 5.6.3 各跑了一遍,想搞清楚同一件事为什么在三个库里会以三种不同的方式悄悄失败。结论有点反直觉:这三家最容易出问题的地方都不在文档第一页,而在默认值里——默认值不会报错,只会让任务少跑几次。
TL;DR:任务「没报错但没执行」,先查四个地方 —— huey 有没有 consumer 在跑、APScheduler 的 misfire_grace_time 是不是还是默认的 1 秒、Celery 的 broker 是不是 memory://、以及主线程是不是早就退出了。下文每个数字都来自本机实测,脚本可直接复制。本文不含任何联盟推广链接,也不含佣金分成;版本号取自 PyPI 实时数据。
先把三个库放在同一张表上
选型文一上来就比性能,但单机场景里性能通常不是瓶颈,运维面才是。三个库真正的差别在这几行:
| 维度 | huey 3.5.3 | APScheduler 3.11.3 | Celery 5.6.3 |
|---|---|---|---|
| 需要外部服务 | 不需要(SqliteHuey 只用标准库 sqlite3) | 不需要 | 需要 broker(Redis / RabbitMQ) |
| 进程模型 | 独立 consumer 进程 | 进程内后台线程 | 独立 worker 进程 |
| 默认持久化 | 有(SQLite / Redis / PostgreSQL 任选) | 无(内存 jobstore) | result backend 另配 |
| 内建重试 | 有(retries / retry_delay / retry_backoff) | 无,需自己写 | 有(autoretry_for / max_retries) |
| 定时语法 | crontab(minute='*/5') | cron / interval / date 三种 trigger | beat + crontab |
| 能否脱离外部服务跑通 | 能 | 能 | 不能(memory:// 只在线程间传递) |
表格最后一行是全文的起点:Celery 在没有 broker 的机器上,你测不出它的真实行为,只能测出一个近似的替身,而那个替身会给你错误的信心。
huey 的三个静默失效
huey 的设计很朴素:任务序列化后塞进队列存储,另一个进程把消息取出来执行。好处是依赖少,坏处是「队列里有东西」和「事情发生了」之间隔着一个人。
失效一:任务进队了,但没有人执行
@huey.task() 装饰的函数被调用时并不执行,只是入队。没有 consumer 在跑时,队列会一直涨,调用方拿到的 Result 永远是 None:
from huey import SqliteHuey
h = SqliteHuey('q1', filename='q1.db')
@h.task()
def add(a, b):
print('executed')
return a + b
r = add(1, 2)
print(r()) # None
print(h.storage.queue_size()) # 1
本机实测:r() 返回 None,queue_size() 是 1,副作用 0 次,没有任何异常或日志。手动跑一次 h.execute(h.dequeue()) 之后 r() 才变成 3。
容易误判的是:None 在 huey 里只表示「还没执行」,不表示「执行失败」。任务真失败时 Result.get() 抛 TaskException。用 if result is None 做健康检查,接到的是「未就绪」而不是「失败」。
失效二:结果读一次就没了
这个坑我在写测试时踩到:断言写完再打印一次,值就变 None 了。查源码才明白 Result._get() 默认走 huey.get_raw(task_id, peek=False),而 peek=False 落到 storage.pop_data()——读即删除。
官方 API 文档写得很清楚:
> preserve (*bool*) – when set to True, this parameter ensures that the task result will be preserved after having been successfully retrieved. Ordinarily, Huey will discard results after they have been read, to prevent the result store from growing without bounds.
实测对照:
r = mul(6, 7)
h.execute(h.dequeue())
print(r()) # 42
print(h.result(r.id)) # None —— 存储里已经空了
print(r.get(preserve=True)) # 需要保留时必须显式传
同一个 Result 对象第二次还能读到 42,是因为它内部有 _result 缓存;换成新的 Result 就查不到。「本地跑通、换个入口查结果就查不到」,根因往往在读取姿势,不在存储。
失效三:任务名对不上,消息直接消失
滚动发布时新旧代码并存是常态。队列里躺着一个旧版本的任务名、消费端没注册它,huey 不是跳过也不是重试,而是在出队阶段就抛异常,消息已经没了:
huey.exceptions.HueyException: __main__.legacy_name not found in TaskRegistry
实测更值得记:抛异常前 queue_size() 是 1,抛完是 0。原因在 Huey.dequeue() 里——先从存储 pop 出消息,再 deserialize_task(),而 TaskRegistry.string_to_task() 找不到就 raise HueyException。消息已被 pop,没有回滚路径。
consumer 侧也帮不上忙,它的循环长这样:
try:
task = self.huey.dequeue()
except Exception:
self._logger.exception('Error reading from queue')
self.sleep()
记一条 traceback,然后退避重试。任务不会回来。结论很硬:任务名是持久化契约,改名要留别名,不能直接改。
huey 的 SQLite 存储:一个 timeout 参数管两件事
SqliteHuey 有个 timeout 参数,文档没细讲,源码注释是 # Busy timeout in seconds, default is 5.。问题在于它同时是另一件事的时限。
huey 3.5.2 的更新日志有一条:
修复多个进程同时打开新的 sqlite 数据库时出现「database is locked」的问题,参见 #925。
修复写在 storage.py 的 _set_journal_mode() 里:新库切 WAL 需要把读锁升级成写锁,并发时会失败,于是用 deadline = time.monotonic() + self._timeout 做重试窗口,命中 database is locked 就 time.sleep(0.01) 再来,超过 deadline 才抛。
于是 timeout 被两个语义共用:SQLite 忙等秒数,以及建库重试窗口。把它调小(不少性能文章会建议这么做)等于把重试窗口关掉。我用 3 个进程各灌 400 条任务做对照:
timeout | 入库任务数 | 进程结果 |
|---|---|---|
0 | 400(丢 800 条,66.7%) | 2 个进程 rc=1,sqlite3.OperationalError: database is locked |
5(默认) | 1200 | 3 个进程全部 rc=0 |
失败的两个进程是直接退出,不是重试后成功。如果启动脚本用 nohup 或 systemd 拉起多个入队进程,一个报错就少一个写入者,而队列长度还在涨,看上去一切正常。
补一句边界:SQLite 的 WAL 允许读者与单写者共存,huey 把连接设成 isolation_level = None(autocommit),所以能扛多进程写,但扛不住长事务。这和 WAL 热备时的行为是同一套机制,可以对照站内那篇 SQLite 热备 14500 行 一起看。
APScheduler 的三个默认值,全都不报错
APScheduler 更隐蔽,因为它连「队列」概念都没有:任务在进程内线程池里跑,失败与跳过都只写日志。三个默认值可以直接打印:
python -c "from apscheduler.schedulers.background import BackgroundScheduler as B; print(B()._job_defaults)"
# {'misfire_grace_time': 1, 'coalesce': True, 'max_instances': 1}
我在 3.11.1 与 3.11.3 上分别跑过,两个版本的 _job_defaults 完全一致。
默认值一:misfire_grace_time = 1 秒
文档对它的解释是「seconds after the designated runtime that the job is still allowed to be run」,但没说默认 1 秒意味着什么。实测:一个定在 30 秒前的 date 任务,启动调度器后从未执行,并且从 get_jobs() 里消失了(不是留着等下次),只留一条警告:
WARNING apscheduler.executors.default Run time of job "job_a (trigger: date[2026-11-01 21:50:08 CST], next run at: 2026-11-01 21:50:08 CST)" was missed by 0:00:30.006098
同一个任务加 misfire_grace_time=3600 就补跑了。1 秒对「进程内每秒触发」够用,对「机器休眠后恢复」「容器滚动重启」完全不够。
默认值二:coalesce = True
官方 user guide 的说法是「if coalescing is enabled for the job and the scheduler sees one or more queued executions for the job, it will only trigger it once」。这句话的范围常被读宽——它只在同一次唤醒内生效,源码是一行切片:
run_times = (run_times[-1:] if run_times and job.coalesce else run_times)
纯函数口径测最干净,不依赖调度器抖动:interval 2 秒、next_run_time 定在 t0、now = t0 + 11s,Job._get_run_times() 得到 6 个触发点;coalesce=True 提交 1 个,coalesce=False 提交 6 个。
真实调度器上做 pause/resume 对照也吻合:暂停 11 秒后恢复,coalesce=True 补跑 2 次,coalesce=False 补跑 6 次。所以「补跑几次」既不是 5 也不是 1,取决于你数的是哪一段——写告警阈值时不能拿它当固定值。
默认值三:max_instances = 1
官方原文是「By default, only one instance of each job is allowed to be run at the same time」。实测:1 秒间隔、每次执行睡 3 秒,8 秒内只跑了 2 次,同时刷出 6 条:
WARNING apscheduler.scheduler Execution of job "slow (trigger: interval[0:00:01], next run at: 2026-11-01 21:51:12 CST)" skipped: maximum number of running instances reached (1)
这条是 WARNING 级,默认日志配置下很容易被更吵的日志淹掉。它想说的是「你的任务比调度间隔慢」,而多数人的结论是「任务丢了」。
第四个坑:主线程结束,任务就没了
这条不在默认值里,但比上面三个更常见。BackgroundScheduler 的「Background」是相对阻塞式调度器说的,它依然是进程内线程。让脚本 1 秒后退出、任务定在 3 秒后:
- 子进程
rc=0,无任何输出 - 4 秒后检查标记文件:不存在
- 加
sched.shutdown(wait=True)也没用——它只等正在执行的任务,不等还没到期的
如果这个脚本是 docker run 或某个 CI 步骤,你会看到「成功」并且任务从未发生。
Celery 的三个边界
Celery 的失败方式不一样:通常会在启动时报错,只是报错信息看起来像环境问题而不是配置问题。
边界一:memory:// 只在同一个进程的线程之间
kombu 官方文档对 in-memory transport 只写了一句:
> Simple transport using memory for storing messages. Messages can be passed only between threads.
按字面做跨进程实验:生产者进程 send_task() 成功拿到 task id,消费者进程 drain_events() 等到超时,抛 TimeoutError。消息从没离开过第一个进程的堆内存。 用 memory:// 做本地集成测试,测的是「函数能不能被调用」,不是「队列能不能通」。
边界二:没配 broker 的第一个报错
不传 broker 时 app.conf.broker_url 是 None,但连接不会因此直接失败——它会回落到 AMQP 默认地址,然后给出一个看起来毫不相关的错误:
kombu.exceptions.OperationalError: [WinError 10061] 由于目标计算机积极拒绝,无法连接。
Windows 上这条 10061 几乎总是「5672 端口上没有 RabbitMQ」,不是防火墙也不是凭据。先确认 broker_url 到底渲染成什么,比改配置快得多。
边界三:eager 模式下 delay() 不报错
task_always_eager=True 常被用来在单测里绕过 broker,但它不改 task_eager_propagates 的默认值(False),于是失败的 eager 任务不抛异常:
app.conf.task_always_eager = True
r = bad.delay() # 不抛
print(r.state) # FAILURE
print(r.result) # eager boom
r.get() # 这里才抛 ValueError
源码里就一行:throw = app.conf.task_eager_propagates。所以「eager 测试全绿」只证明任务被调用了,不证明它成功。要么把 task_eager_propagates 设成 True,要么测试里断言 r.state == 'SUCCESS'。
版本口径:本机原有 Celery 5.3.1,PyPI 当前最新 5.6.3(2026-03-26)。两个版本在 task_always_eager / task_eager_propagates 的默认值上没有差别,但 5.3.1 已不在维护线上,Python 3.13 下的兼容性建议以 5.6.x 为准。
Troubleshooting:五个真实报错
下面五条都是我在本机复现出来的原文,不是抄来的示例。
报错一:sqlite3.OperationalError: database is locked
现象:多进程同时往同一个 SqliteHuey 文件入队,部分进程 rc=1 退出,队列里少了对应数量的任务。
原因:SqliteStorage._set_journal_mode() 新建库时要执行 pragma journal_mode="wal",把读锁升级为写锁;并发时这一步会失败,重试窗口由 timeout 决定,超过就抛。
解决:不要调小 timeout;确实要并发写就拆库,或改成单点入队。
# 错误:把 timeout 当性能参数调成 0
h = SqliteHuey('q', filename='q.db', timeout=0)
# 正确:保持默认 5 秒,或按写入并发度上调
h = SqliteHuey('q', filename='q.db', timeout=5)
# 复现:3 个进程各灌 400 条,观察 rc 与入库数
for i in 1 2 3; do python enqueue_worker.py p$i 400 & done; wait
python -c "import sqlite3;print(sqlite3.connect('q.db').execute('select count(*) from task').fetchone())"
报错二:HueyException: xxx not found in TaskRegistry
现象:consumer 日志里反复出现 Error reading from queue 的 traceback,队列长度却在下降。
原因:dequeue() 先 pop 消息再反序列化,任务名没注册时抛异常,消息已经不在队列里了。
解决:任务改名时保留旧名别名,等队列排空再删;发布期间不要同时改任务名和删旧代码。
@h.task(name='legacy_name') # 旧名继续可消费
def new_name(x):
return x
报错三:Run time of job ... was missed by 0:00:30.006098
现象:date 任务从未执行,get_jobs() 里也找不到它。
原因:misfire_grace_time 默认 1 秒,超过就判定为错过并移除任务。
解决:按业务容忍度显式设置,跨重启或休眠的场景必须放大。
sched.add_job(job, 'date', run_date=when, misfire_grace_time=3600)
报错四:Execution of job ... skipped: maximum number of running instances reached (1)
现象:固定间隔任务的实际执行次数远少于预期,日志周期性刷这条 WARNING。
原因:max_instances 默认 1,上一次还没跑完,这一轮直接跳过(不是排队)。
解决:确认任务耗时是否真的短于间隔;确实允许并发再调大。
sched.add_job(slow, 'interval', seconds=1, max_instances=3, coalesce=False)
报错五:kombu.exceptions.OperationalError: [WinError 10061]
现象:task.delay() 抛连接被拒。
原因:没配 broker,回落到 AMQP 默认地址 localhost:5672。
解决:显式配置并先验证连通性。
python -c "from celery import Celery; print(Celery('x').conf.broker_url)"
set CELERY_BROKER_URL=redis://127.0.0.1:6379/0
同一台机器上怎么选
把上面的边界条件折成一棵决策树,顺序很重要:
1. 只需要「过 N 秒执行一次」,且进程会一直活着 → 别上队列,threading.Timer 或系统计划任务就够。
2. 单机、要持久化、要重试、可以多起一个进程 → SqliteHuey。不需要额外服务,代价是你必须自己保证 consumer 在跑。
3. 单机、任务都是秒级短任务、讨厌多一个进程 → APScheduler。前提是把三个默认值全部显式写出来。
4. 要多机、要削峰、已经有 Redis 或 RabbitMQ → Celery。反过来说,没有 broker 的机器上它连真实行为都测不出来。
5. 进程生命周期短(CLI、CI、Serverless) → 三个都别用进程内调度,改成事件触发。
实用版本是:先算你的进程能活多久。进程活不过任务间隔,任何进程内调度器都等于没装。
上线前的最小加固清单
不用全做,覆盖你实际踩过的那条就够:
- huey:确认 consumer 是独立进程且在进程管理器里;任务名当契约;
Result别当数据库用(要重复读就preserve=True);SqliteHuey的timeout不低于 5。 - APScheduler:把
misfire_grace_time、coalesce、max_instances写进代码而不是靠默认;用持久化 jobstore 时必须显式id+replace_existing=True,否则每次重启多一份任务;保证主线程活到任务跑完。 - Celery:
memory://只用于单测;broker_url打印出来确认;eager 测试断言state;task_eager_propagates按需打开。
想看同一类「不报错但没干活」的失败模式,站内还有一篇 subprocess 的七个静默失效,讲的是退出码 0 却拿不到输出;n8n Task Runner 的队列模式 则把「执行器外置」之后的三层角色拆开讲,可以当作本篇的上层对照。
常见问题
Q:huey 的 Result() 返回 None,是任务失败了吗?
不是。None 只表示结果还没写进存储(未消费或正在执行)。任务失败时读结果会抛 TaskException,里面带原始异常字符串和 traceback。
Q:APScheduler 为什么任务只跑了一次就不跑了?
先看触发器——date 本来就只跑一次,跑完从 job 列表移除。如果用的是 interval,检查 max_instances 的 WARNING 是否在刷,以及单次耗时是否超过间隔。
Q:Celery 用 memory:// 在本机测通了,能上线吗?
不能。kombu 明确写了「Messages can be passed only between threads」,跨进程收不到,跨机器更收不到。上线前至少用 Redis 或 RabbitMQ 跑一遍真实链路。
Q:这三个库能混用吗?
可以但没必要。典型混用是「APScheduler 负责定时触发、把任务丢给 Celery 执行」,此时 APScheduler 的 misfire 逻辑决定丢不丢,Celery 的 ack 逻辑决定丢了能不能找回,两个语义叠在一起很难排查。
结语
三个库的失败方式,其实是三种设计哲学的副作用:huey 把「执行」交给另一个进程,所以默认不执行;APScheduler 把「准时」看得比「补跑」重要,所以默认只等 1 秒;Celery 把「可靠投递」交给 broker,所以没有 broker 时它连自己是空的都不说。
下次遇到「任务没跑」,按这个顺序查比读文档快:huey 先看 queue_size(),APScheduler 先看 _job_defaults,Celery 先看 broker_url。三个都只要一行命令。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。