📑 本页目录(点开跳转)
11 · 长任务与队列
⏱ 52 分钟 | ⭐ 别一上来就上 Celery —— 中间那一档「数据库当队列」被严重低估
🎯 一句话
只要一个请求可能超过几十秒,它就不该在请求里做完;但「扔到后台」有三档做法,绝大多数人直接跳到了最重的那一档。 把任务交给后台后,还要能追查它的状态、处理重复投递,并让失败有明确的出口。
🧩 一、什么时候必须异步
别凭感觉。满足任意一条,就不要在请求里做完:
| 信号 | 为什么 |
|---|---|
| ⭐ 可能超过 30 秒 | 很多网关的默认超时就在这个量级(🗓️ 查你那层网关的配置)。超时后用户看到 504,后端还在跑,钱照花,结果没人收 |
| 批量处理 | 「把这 800 篇文档都总结一遍」,用户不可能挂着页面等 |
| ⭐ 入库 + embedding | 一个 PDF 切成几百块、每块调一次 embedding,天然是分钟级 |
| 定时任务 | 凌晨重建索引、跑重训练流水线 —— 压根没有「请求」这个东西 |
| 要重试的活 | 请求活不过重试。第三方挂了要 10 分钟后再试,只有后台能做 |
⚠️ 单次对话生成不属于这一类。它慢,但用户就坐在那儿等,流式已经解决了体感问题 —— 别拿队列去套。
🧩 二、三档做法
| 档 | 是什么 | 适用边界 | ⭐ 该升级的信号 |
|---|---|---|---|
① BackgroundTasks |
响应发出去后,在同一进程里接着干 | 几秒到几十秒、丢了也无所谓的活:发通知、写日志、清临时文件 | 出现「丢了用户会投诉」的活,或需要重试 / 看进度 |
| ⭐ ② 数据库当队列 | 一张 jobs 表 + 一条原子认领语句 |
中小规模几乎全覆盖:分钟级任务、每分钟几十到几百个 job、少数几个 worker | 积压到轮询压力明显 / 要扇出到几十个 worker / 要复杂的优先级调度 |
| ③ 专用队列 | Redis / RabbitMQ + worker 进程 | 高吞吐、多任务类型、要现成的路由和监控面板 | —— |
⭐ 第 ② 档被严重低估:你已经有一个数据库了,把队列也放进去 —— 少一个中间件、少一套部署、少一处会不一致的状态。而且任务状态能和业务数据在同一个事务里改,这一点 Redis 队列给不了。
① BackgroundTasks
形状是:先把 job 记下来、立刻返回一个 id,真正的活挂在响应之后跑。FastAPI 里这东西叫 BackgroundTasks。
import uuid, time
from fastapi import FastAPI, BackgroundTasks
from fastapi.testclient import TestClient
app = FastAPI()
JOBS = {} # ⚠️ 状态只在进程内存里:进程一重启,任务和进度一起蒸发
def slow_work(jid, text):
for i in range(1, 5):
time.sleep(0.02)
JOBS[jid].update(status="running", progress=i * 25) # ⭐ 进度写在前端查得到的地方
JOBS[jid].update(status="done", result=text.upper())
@app.post("/jobs", status_code=202) # ⭐ 202 = 「收到了,还没做完」
def create(text: str, bg: BackgroundTasks):
jid = str(uuid.uuid4())
JOBS[jid] = {"status": "queued", "progress": 0}
bg.add_task(slow_work, jid, text) # 响应写完之后才执行
return {"job_id": jid}
@app.get("/jobs/{jid}") # 前端拿这个轮询
def status(jid: str):
return JOBS.get(jid, {"status": "unknown"})
c = TestClient(app)
jid = c.post("/jobs", params={"text": "hi"}).json()["job_id"]
print(c.get("/jobs/" + jid).json())
⚠️ 三个限制:① 跑在你的 web 进程里,CPU 密集的活会和请求抢 worker;② ⭐ 进程重启就全丢,而部署、扩缩容、OOM 每天都在重启;③ JOBS 这个字典在多进程部署下,另一个进程查不到这个 id。
⭐ ② 数据库当队列
把「谁在干这个 job」落到磁盘,上面三个毛病一起没了。
核心只有一件事:认领必须原子 ——「先 SELECT 一个 queued 的、再 UPDATE 成 running」中间那道缝,就是两个 worker 抢到同一行的原因。
⚠️⚠️ 把两步拼成一条语句仍不足以保证安全;也可以在正确持锁事务中分步认领。 下面这条在 Postgres 上就不安全:
-- 🗓️ 未实跑 —— 需要 Postgres。⚠️ 这是【错误示范】,别抄
UPDATE jobs SET status='running', worker=$1
WHERE id = (SELECT id FROM jobs WHERE status='queued' ORDER BY run_after LIMIT 1)
RETURNING id, kind, payload;
两个并发事务的子查询会选中同一行:第二个先卡在行锁上排队等(吞吐直接塌掉),等前一个提交之后,外层 WHERE 只比对 id、不再检查 status='queued' —— 于是这次认领要么把同一个 job 认领第二次,要么空转一次什么也没拿到。⚠️ 具体落到哪一种取决于隔离级别和 WHERE 被重新求值的细节,但两种都是 bug。
⭐ 正确写法是把锁的语义写进子查询:
-- 🗓️ 未实跑 —— 需要 Postgres
UPDATE jobs SET status='running', attempts=attempts+1, worker=$1
WHERE id IN (SELECT id FROM jobs
WHERE status='queued' AND run_after <= now()
ORDER BY run_after
LIMIT 1
FOR UPDATE SKIP LOCKED) -- ⭐ 当场锁住选中的行;被别人锁住的直接跳过,不排队等
RETURNING id, kind, payload;
FOR UPDATE 让子查询当场把选中的行锁住,SKIP LOCKED 让别的 worker 跳过这些行去拿下一条 —— 避免多个事务同时认领这条已锁行,而不是承诺任务永不重投;表级锁等仍可能等待。⚠️ 事务边界也是这条语句的一部分:它要在一个事务里跑,提交之后这个 job 才算真归你;没走到提交就崩(进程被 kill),事务回滚、行锁释放,这一行自动回到可认领状态。
下面用 SQLite 演示这套形状里能当场跑的那一半。⚠️ SQLite 没有 FOR UPDATE SKIP LOCKED,它靠的是整库一把写锁(同一时刻只有一个写事务),所以下面这条语句在 SQLite 上确实是安全的 —— 但它安全的理由和 Postgres 完全不是一回事,别把这段 SQL 原样搬过去:
import sqlite3, json, time, uuid
db = sqlite3.connect(":memory:")
db.execute("""CREATE TABLE jobs(
id TEXT PRIMARY KEY, kind TEXT, payload TEXT,
status TEXT DEFAULT 'queued', -- queued / running / done / dead
attempts INTEGER DEFAULT 0,
run_after REAL DEFAULT 0, -- ⭐ 延迟重试全靠这一列
worker TEXT)""")
db.execute("CREATE INDEX idx_pick ON jobs(status, run_after)")
def enqueue(kind, payload, delay=0.0):
jid = str(uuid.uuid4())
db.execute("INSERT INTO jobs(id,kind,payload,run_after) VALUES(?,?,?,?)",
(jid, kind, json.dumps(payload), time.time() + delay))
db.commit()
return jid
def claim(worker):
# ⭐ 认领必须原子:查到和改状态之间留了缝,两个 worker 就会拿到同一行
# ⚠️ 但「一条语句」不等于安全 —— 这里安全是靠 SQLite 的整库写锁;
# Postgres 上同样的写法必须配 FOR UPDATE SKIP LOCKED(见上)
cur = db.execute("""UPDATE jobs SET status='running', attempts=attempts+1, worker=?
WHERE id = (SELECT id FROM jobs WHERE status='queued' AND run_after<=?
ORDER BY run_after LIMIT 1)
RETURNING id, kind, payload""", (worker, time.time()))
row = cur.fetchone()
db.commit()
return row
enqueue("embed", {"doc": "A"})
enqueue("embed", {"doc": "B"})
print([None if (j := claim(w)) is None else (j[0][:8], w) for w in ["w1", "w2", "w1"]])
输出 [('…','w1'), ('…','w2'), None] —— 两个 worker 各拿到不同的一行,第三次没活了。
⚠️ 要配三件事:(status, run_after) 上要有索引(否则每次认领全表扫);worker 空转别 100ms 一轮(1–2 秒足够,或用 Postgres 的 LISTEN/NOTIFY 让入队方叫醒它);必须有清扫语句把 status='running' 却超过 N 分钟没动静的行改回 queued —— worker 被 kill 时来不及改状态。超时不等于旧 worker 已停止,重新入队前还要设计租约与副作用的重复防护,见下面的可选深入。
只实现本章主线时可以继续;遇到 worker 失联、重复执行或消息确认问题,再看 可跳过的队列与租约深入。
③ 专用队列
到了每秒几百个 job、十几种任务类型、需要优先级路由和现成监控面板时才值得引入。⚠️ 代价是真实的:多一个要运维的中间件、多一处可能和数据库不一致的状态、本地开发要多起一个服务。
可跳过:用设备心跳与百万定时任务检查可靠性条件
千万设备先给间隔与大小。设备数N=1000万,若每台每T秒一条心跳、负载P字节,均匀假设下平均输入是N/T条每秒、NP/T字节每秒。仅作教学假设T=60、P=200,则约16.67万条/秒、33.33MB/秒负载;这两个值不是题干给定的固定QPS,也未计重连集中发送、协议头、复制及索引。设备数也不等于同时维持的TCP连接数,取决于协议和连接方式。
给每条记录稳定的设备ID、设备启动代次/序号(重启归零要区分),在明确的设备端持久缓冲与服务端持久化边界后才承诺接受。确认丢失可用同ID重传、去重;服务重启按分区恢复游标/未确认记录。若心跳在设备持久化前就断电,或设备离线超过本地保留容量,“队列可靠”不能替它找回。端到端不丢必须写明故障模型、保留期、复制与确认条件,不能由一张队列图推出。
验证设计也要对应边界:列出设备落盘前后、服务器持久确认前后、消费副作用前后断电/断网的注入点;恢复后按设备代次/序号对账,检查缺口、重复与延迟。确认已接受的集合与最终持久结果要能对上;指标总数相等不代表逐条无缺失。本页仅给验证计划和故障轨迹,没有执行真实设备或分区故障注入。
百万定时任务按稳定分片与到期负载拆。父任务与子任务用稳定ID,持久记录分片键、到期时间和状态;到期索引/小批原子认领沿用前文。教学假设固定64个逻辑分片时,100万条平均每片15625条,但任务成本不同、集中到期的峰值也不同。逻辑分片到worker的映射重平衡要带分配代次,旧owner失效/新owner认领遵守前文租约与fencing/幂等,不把调整取模数当作无缝迁移。
失败自动重试3次,在本例明确定义为初次+最多3次重试:claim时持久增加attempt,失败的第1、2、3次写queued与now+有界退避,第4次转最终失败入口;重启不清零预算。租约失效重领、SDK内部重试和人工重放也要有统一计数/授权规则,不能无限绕开上限。稳定业务ID与下游副作用核验继续有效,重试不等于再产生一次业务意图。
任务状态、attempt、更新时间、最后错误/结果、lease和分片位置要持久可追踪;监控排队深度、到期延迟、运行超时、重投/失败率及死信处理。所谓“实时”应定义允许的状态更新/查询延迟,不意味着零延迟;监控不能只靠worker内存。父任务汇总要识别部分失败,不只统计完成数量。这里没有百万任务运行、吞吐SLO或恢复验收,相关机制的有限说明不自动闭合整题。
可跳过:零点集中到期时,怎样分片、恢复和看状态?
参考对象与预算。用业务日期/时区与任务定义版本生成稳定run_id,大任务的子任务ID与预期清单在入队时持久冻结。同一批100万子任务映射到64个固定逻辑片,平均每片15625条;逻辑片不等于worker数量。以下选择PostgreSQL17作为任务/租约/本地结果的权威库,沿用前文原子认领机制。
集中到期先算N/W。若希望100万条在零点后W=600秒内启动,仅平均认领速率就至少约1667条/秒。假设每条平均占用2秒,理想并发下界约3334;候选128个worker×32并发=4096,理想吞吐2048条/秒。若只有64×32并发,理想1024条/秒已不够。这里忽略了重试与开销,都是容量筛选算例,不是实测。
真实预算还受数据库认领/写回、CPU、内存和下游配额限制,须留重试与峰值余量。超过硬上限时,本参考保留已接收任务排队、暴露逾期并按业务调整窗口/错峰;新增超预算批次可拒绝。不能靠无限并发承诺零点立即执行全部任务。
有限认领。按片、状态与next_due建立到期索引;事务先锁定片租约行并核对owner、代次及数据库时钟下的有效期,再用FOR UPDATE SKIP LOCKED取有界小批到期任务,持久写running、唯一claim_token、租约和attempt+1后提交,计算时不长期占行锁。SKIP LOCKED是队列分工手段,不是完整一致快照。
一次owner故障轨迹:A持有片0、代次42、租约到t=10,已认领子任务j,attempt=1;t=8暂停。t=11,B在数据库事务中确认租约过期,把片所有权改成B、代次43。B按持久状态跳过已完成子任务,查询未知副作用,再有界重认领需要重做的j,产生新claim_token并把attempt增到2;不重建任务ID、不清空预算。
t=12,旧A恢复。续租、确认与结果写入都必须同时匹配当前片owner/代次、任务claim_token和有效租约;旧42或旧token被拒绝。本地业务结果、任务完成与去重记录可在同库事务中提交,并锁定片租约行让代次校验与写入不分离。外部服务仍须实际支持fencing或稳定业务ID幂等/结果查询,仅拒绝本地完成状态不能撤回已经发生的外部效果。
初次+3次重试就是最多4次认领尝试。本参考把崩溃/失联后重领也计入同一持久attempt;失败的第1至3次写下一绝对到期时间,第4次明确失败转dead,不再发第5次。关闭SDK隐式重试,需要重试须回状态机计数。若第4次结果未知,只查询/对账或转needs_review,不凭超时再执行;人工重放另建获准批次并关联原记录。
监控用权威状态,不只靠推送。保存queued/running/retry_wait/succeeded/dead/needs_review、attempt、owner/代次、心跳、最后更新时间及错误/结果。此参考要求状态变化5秒内可查询是待测目标。报告due到首次start的lag分位数,并同时看未启动的最老逾期年龄,另看重试率、重领、最终失败与未知结果积压。
父任务按冻结的子任务清单核对:全部succeeded才成功,任何dead则标失败/部分完成,needs_review单独显式暴露;重复完成不能重复加计数。轮询/SSE只改变展示,断线后按权威状态恢复。验收应注入认领后崩溃、代次切换、完成确认丢失,核对旧代次拒写、重复结果只记一次、attempt重启不重置与父子状态一致。
依据:PostgreSQL17事务、行锁与SKIP LOCKED。这是有限参考设计;百万调度、真实跨机故障与5秒状态/启动lag的SLO均未实测。
一份长文档从已接收到已完成
用户提交长文档摘要,页面立即显示「已接收」。如果服务器刚返回就重启,重新打开页面还能查到这份任务吗?答案取决于返回前已经保存了什么。先沿着同一个任务号 job-17 看一遍。
POST /api/summary-jobs 接收 {"doc_id":"doc-17"}。本例在认证与文档授权后,按当前租户、操作和幂等键确定任务号,保存后返回 202 Accepted 与 {"job_id":"job-17","status":"queued","status_url":"/api/jobs/job-17"}。页面从收到 202 起就可查询,轮询与 worker 并行,服务端每次查询都检查读取权限。202 表示请求已被接收处理,HTTP 状态码本身没有承诺落盘或最终完成。本接口额外承诺数据库提交后才返回接收。若响应在路上丢失,用同一个幂等键重试可取回原任务;同键对应不同内容应拒绝。
如果用数据库当队列,worker 直接在 jobs 表认领,任务记录本身就可以作为待办。如果还要发给外部消息中间件,只写任务表后就可能在发布前崩溃,先发布则可能让 worker 收到尚未提交的任务。将任务记录与待发布记录写进同一个数据库事务,一起提交或一起回滚,这叫事务发件箱(Transactional Outbox)。转发进程稍后读取已提交的发件箱,把任务号送进队列。任务已入库、消息中间件已接收、摘要已完成是三个分别可查的状态。
发布后若还没标记已发就中断,恢复后同一个任务号可能发布两次。worker 保存结果后若还没发出 ACK 就断线,也可能再次收到消息。下面的 SQLite 示例用结果表的任务号唯一约束防止重复保存,且将保存结果和更新成功状态放在同一事务。用 Python 3 运行这段标准库代码。内存数据库模拟同库事务,列表模拟已送达的消息,运行期间没有真实队列或模型调用。
import sqlite3
from contextlib import closing
def accept(db, job_id, doc_id, fail=False):
with db:
created = db.execute(
"INSERT INTO jobs VALUES (?, ?, 'queued') "
"ON CONFLICT(job_id) DO NOTHING", (job_id, doc_id),
).rowcount
if created:
if fail:
raise RuntimeError("模拟提交前中断")
db.execute("INSERT INTO outbox VALUES (?, 0)", (job_id,))
elif db.execute(
"SELECT doc_id FROM jobs WHERE job_id = ?", (job_id,),
).fetchone()[0] != doc_id:
raise ValueError("同一任务号对应了不同文档")
def relay(db, deliveries, mark_sent):
pending = db.execute("SELECT job_id FROM outbox WHERE sent = 0")
for (job_id,) in pending.fetchall():
deliveries.append(job_id) # 模拟中间件已接收
if mark_sent:
with db:
db.execute("UPDATE outbox SET sent = 1 WHERE job_id = ?", (job_id,))
def consume(db, job_id):
doc_id, = db.execute("SELECT doc_id FROM jobs WHERE job_id = ?", (job_id,)).fetchone()
with db:
created = db.execute(
"INSERT INTO results VALUES (?, ?) ON CONFLICT(job_id) DO NOTHING",
(job_id, f"{doc_id} 的模拟摘要"),
).rowcount
if created:
db.execute("UPDATE jobs SET status = 'succeeded' WHERE job_id = ?", (job_id,))
return bool(created) # 此后才允许确认投递
with closing(sqlite3.connect(":memory:")) as db:
db.executescript("""
CREATE TABLE jobs (job_id TEXT PRIMARY KEY, doc_id TEXT, status TEXT);
CREATE TABLE outbox (job_id TEXT PRIMARY KEY, sent INTEGER);
CREATE TABLE results (job_id TEXT PRIMARY KEY, summary TEXT);
""")
try:
accept(db, "job-failed", "doc-17", fail=True)
except RuntimeError:
pass
assert db.execute("SELECT COUNT(*) FROM jobs").fetchone() == (0,)
assert db.execute("SELECT COUNT(*) FROM outbox").fetchone() == (0,)
print("提交前失败:任务 0,待发布 0")
accept(db, "job-17", "doc-17")
accept(db, "job-17", "doc-17") # 模拟 202 丢失后的同意图重试
try:
accept(db, "job-17", "doc-99")
except ValueError:
pass
else:
raise AssertionError("同一任务号改用其他文档时应拒绝")
assert db.execute("SELECT COUNT(*) FROM jobs").fetchone() == (1,)
assert db.execute("SELECT COUNT(*) FROM outbox").fetchone() == (1,)
print("已接收:queued")
deliveries = []
relay(db, deliveries, mark_sent=False) # 发出后中断,没标记已发
relay(db, deliveries, mark_sent=True)
assert deliveries == ["job-17", "job-17"]
print("发布记录:", deliveries)
assert consume(db, deliveries[0])
# 第一次结果已提交,ACK 前断线;先重投,再处理重复发布的另一份。
assert not consume(db, deliveries[0])
assert not consume(db, deliveries[1])
assert db.execute("SELECT COUNT(*) FROM results").fetchone() == (1,)
assert db.execute("SELECT status FROM jobs").fetchone() == ("succeeded",)
print("任务成功:保存摘要 1 条")依次看到「提交前失败:任务 0,待发布 0」、「已接收:queued」、「发布记录:['job-17', 'job-17']」和「任务成功:保存摘要 1 条」。同一个任务号两次发布、三次模拟消费,数据库中仍只有一条完成结果。
实际系统可在调用模型前先检查任务是否完成,减少重复工作;并发时还要用上文的认领和下文的租约控制。SQLite 示例只证明本地结果提交的去重,模型调用与计费不会随数据库事务一起回滚。若外部尝试是否成功无法确定,先按稳定操作号查询或进入待核对,按 第 04 章的重试条件和第 12 章的账本规则决定下一步。
协议与模式依据见 RFC 9110 的 202、事务发件箱及 RabbitMQ 的发布确认与消费确认。
🧩 三、状态怎么让前端知道
| 轮询 | SSE 推送 | |
|---|---|---|
| 后端 | ⭐ 无状态,哪台机器都能答 | ⚠️ 连接钉死在某台机器上,扩容和滚动更新都要处理 |
| 延迟 | 一个轮询间隔 | 近实时 |
| 选它 | ⭐ 默认。分钟级任务,2–5 秒轮一次完全够 | 秒级进度条,或任务本身就有流式输出 |
⚠️ 最常见的错:轮询间隔写成 200 毫秒 —— 一个跑 3 分钟的任务就发了 900 个「好了没」。用退避式轮询:前 10 秒 1 秒一次,之后拉到 5 秒。
⭐ 进度报阶段,别报百分比。LLM 任务时长不可预测,百分比可能长时间停在同一数值,而卡住的进度条比没有进度条更让人焦虑。给可数的:「已处理 3 / 12 个分片」。⚠️ 进度要写在 jobs 表的一列里;写在 worker 内存里,worker 一崩前端就永远停在 40%。
🧩 四、幂等:任务可能被重复执行
⚠️ 客户端超时后重试、worker 完成副作用但确认前崩溃、失效租约重新入队,都可能造成重复。要按可能重复执行设计,不等于每项任务都会执行两次;投递和确认保证取决于队列配置。依据 AWS 幂等重试设计说明。
⭐ 代价很具体:用户被扣两次钱、同一段文本在向量库里存两份(检索时占掉两个 top-k 名额)、同一封邮件发两遍。
先定义一次业务意图的稳定标识,同一意图的重试复用它;再用内容指纹核对“同标识、不同内容”。下面保留一个同库教学简例:假设相同用户/类型/内容就是同一件事,仅演示唯一键与本地记账同事务。真实业务中,两次合法的相同请求未必是同一次意图,金额等关键字段也须纳入指纹;不要直接把这个简例当支付接口。
import sqlite3, hashlib
db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE billing(user TEXT, cents INTEGER)")
db.execute("CREATE TABLE idem(key TEXT PRIMARY KEY)") # ⭐ 主键就是那把锁
def charge(user, kind, payload, cents):
# 教学简化:同输入视作同一意图;真实任务应持久化业务ID,重试复用并核验指纹
key = hashlib.sha256(f"{user}|{kind}|{payload}".encode()).hexdigest()[:16]
try:
with db: # ⭐ 写键和扣款在同一个事务,中间崩了不会一边有一边没有
db.execute("INSERT INTO idem VALUES(?)", (key,))
db.execute("INSERT INTO billing VALUES(?,?)", (user, cents))
return "charged"
except sqlite3.IntegrityError: # 键撞了 = 这件事已经做过
return "skipped"
print([charge("u1", "summarize", "doc-42", 30) for _ in range(3)])
print("扣了", db.execute("SELECT COUNT(*), SUM(cents) FROM billing").fetchone())
投三次,输出 ['charged', 'skipped', 'skipped'],账上只有 1 笔 30 分。
⚠️ 两个边界:① UUID 可以在首次创建业务意图时生成并持久化,同一意图的所有重试原样复用;不能每次重试新生成。客户端传 Idempotency-Key 也要由服务端按租户/操作范围验证及保存结果,完整契约见 原幂等节。② 简例中的去重标记与记账都在同一 SQLite 事务,能一起提交/回滚;调用外部支付、邮件或向量库时不在此事务内,仍需下游幂等、结果查询和未知结果对账,不能据此声称端到端 exactly-once。
🧩 五、重试、死信、毒药消息
⚠️ 毒药消息:一个永远会失败的任务(payload 少了字段、文档编码坏了)。没有上限,它会被无限取出、无限失败、无限放回 —— 堵死队列,顺便刷爆日志。三件事一起做:上限、退避、死信。
import random
MAX_ATTEMPTS = 5
random.seed(0)
def backoff(attempt):
base = min(60.0, 2.0 ** attempt) # 指数退避 1,2,4,8,16…,封顶 60 秒
return round(base * (0.5 + random.random()), 2) # ⭐ 抖动:不加,失败任务会同一秒一起回来
def on_fail(job, err):
if job["attempts"] >= MAX_ATTEMPTS: # ⚠️ 没有上限,毒药消息会永远循环
return "dead", err
return "retry", backoff(job["attempts"]) # 返回的是delay秒;调用方用同一时间口径的now + delay写回run_after
job = {"id": "j1", "attempts": 0}
while True:
job["attempts"] += 1
state, info = on_fail(job, "ValueError: payload 缺 doc_id")
print(job["attempts"], state, info)
if state == "dead":
break
seed(0) 固定,退避秒数依次是 2.69 / 5.03 / 7.36 / 12.14,第 5 次转成 dead。
⭐ 抖动不是可选项:一次上游抖动会让 200 个任务同时失败,没有抖动它们会在同一秒一起回来,把刚恢复的上游再打挂一次。
⭐ 死信是待办箱,不是垃圾桶 —— 要看得见(后台页面或告警),并且能改完 payload 重新入队。没人看的死信队列 = 静默丢数据。
先决定错误能否恢复,再决定能否安全重做。参数有误或策略拒绝时,当前任务直接记为终态失败,必要时转死信供排查。凭证无效先修复凭证。暂时限流或服务故障可以在预算内退避,遵守适用的等待约定;若超时发生在外部操作发出之后,结果可能未知,先查原操作号,确认可安全重放再重试。需要改动输入时,通过新的或经审批的操作重新提交。
可选深入:认领之后,谁还有权完成任务?
数据库行锁保护认领事务;任务通常在提交后才慢慢执行,此时行锁早已释放。下面的时间线是手工可复核的模型,未启动 Redis、PostgreSQL、RabbitMQ 或 Kafka 服务。
从两个 worker 到一份有期限的租约
以 Redis 7.2.0 单实例为例,SET lock:job1 owner_A NX PX 10000 把“尚无锁才设置、记录所有者、10秒到期”放进一次命令。先 SETNX、再单独设置过期会留下崩溃窗口。所有者值要在不同认领间唯一;释放时也必须在一个原子操作中比较所有者后删除,不能先 GET 再 DEL:
-- Redis 7.2.0的所有者比较释放形状;未实跑
if redis.call('get', KEYS[1]) == ARGV[1] then
return redis.call('del', KEYS[1])
end
return 0t=0:A取得10秒租约,owner_A,操作代次42
t=8:A暂停(进程仍活着,不等于租约会续期)
t=10:A租约到期;t=11:B取得新租约owner_B,代次43并完成写入
t=12:A恢复:旧owner不能删除B的锁,但旧A仍可能继续写外部系统所有者 token 防止误删新锁,不自动阻止旧 worker 的副作用。若受保护存储支持 fencing,可在每次操作携带单调递增代次;存储已接受43后拒绝42。递增权威与校验必须可靠,不能把随机 owner 值当可比较代次,也不能忽略生成器故障转移/回退。另一条路线是下游按稳定业务ID幂等、核验当前状态并查询结果;锁续期也须校验所有者,续期失败就不能继续假设独占。
SET NX PX 的这条单实例轨迹没有解决异步复制切主丢锁、长暂停或时钟变化等全部故障。选择锁方案前先明确容忍偶发重复还是要求严格互斥;不要把单 Redis 锁、数据库认领或“有唯一键”各自扩大为跨系统 exactly-once。原子认领 SQL 依据 PostgreSQL 17 锁条款;外部结果未知时回到 稳定操作号与故障恢复原节。
延迟队列:到期读取只是入口
本章 SQLite 的 run_after 是 epoch 秒的绝对时间点,backoff 返回时长。假设调度时刻 now=1000、退避2.69秒,应写1002.69;若误写2.69,就会被当前时间立即判为到期。PostgreSQL时间戳列则用同一权威时钟下的时间戳加间隔,别混用秒/毫秒或把进程内单调计时值跨进程持久化。
Redis ZSet 也能用到期时间作 score、任务ID作成员,按 score≤now 取一小批到期ID;分值/排名机制见 缓存深入的三人榜。查到不等于认领:多个 worker 会读到同一ID;仅从 ZSet 删除再执行,删除后崩溃会丢任务。需要把“待执行→处理中+所有者/租约截止”放进一个原子移交,工作完成后再确认;失联项到期可重投,用原业务ID防重复。Redis Cluster多key操作还须满足同槽等部署条件。
pending(due≤now) → 原子认领 → processing(owner, lease_until)
processing → 副作用/结果记录成功 → 条件确认 → done
processing → 租约失效/失联 → 按策略重新queued(同一业务ID)
失败可重试 → run_after=now+delay;超过总尝试上限 → dead超时恢复可能与旧 worker 并行,因此仍需上一段的 fencing/幂等/状态核验,不能只“扫超时行改queued”。本章原例 MAX_ATTEMPTS=5 是总尝试5次;若需求是“初次失败后重试3次”,通常是总尝试4次,必须在合同中定清,不沿用5冒充已满足。
沿一条消息分清丢失、重复与确认
| 崩溃位置 | 风险 | 需要补的协议 |
|---|---|---|
| 业务库提交后,发布前崩溃 | 数据库有意图、队列无消息 | 同库事务记outbox,后台可靠投递;投递也可能重复 |
| broker已接受/持久化,生产者没收到确认 | 重发可能出现重复;没确认也不等于broker没收到 | 生产确认、可追踪消息ID,按所选broker的持久化/复制与路由设置核验 |
| 消费者先确认,再执行副作用时崩溃 | broker认为完成,业务却没完成 | 把确认放到可恢复的业务完成点之后 |
| 副作用成功,消费确认前崩溃 | 失联重投,副作用可能重复 | 同库事务去重,或下游稳定ID幂等/查询;未知不能盲目重做 |
以 RabbitMQ 4.1 为例:publisher confirm 只确认生产者与broker侧接收路径,不是消费者已处理;持久消息、持久队列、路由、复制策略与确认要分别配合检查。消费者手动ACK用于告知处理完成,连接失联的未确认消息可能重新投递。可靠不等于无限保存,故障模型和保留/容量上限仍影响结果。
以 Redis 7.2 的常用机制为界:PubSub 是至多一次推送,订阅者断线的消息没有可靠补发;Streams消费组有待确认记录、XACK与重新认领机制,但仍需配置持久化/复制、保留期和故障恢复,不能把换成Stream当作端到端不丢的证明。这里不使用后续版本新增的幂等生产命令。
推拉、背压和“顺序完成”
推送把到达节奏更多交给broker,消费者要用有界在途量和信用/预取控制,例如 RabbitMQ 手动ACK配合有限 prefetch;否则业务线程池后面仍会堆积。拉取消费由消费者决定何时取、取多少,空队列要用等待/退避,批量也要受内存和处理能力限制。push/pull 不是可靠/不可靠的同义词,积压仍受存储、保留期限与告警约束。
Kafka 4.0 的顺序单位是分区日志,不是所有分区的全局时间;同一业务key进入稳定的同一分区,才有可利用的局部顺序。即使按偏移10、11依次取出,丢进两个并行worker后,11也可能先完成。需要业务key内串行、序号校验或有序提交;失败重试/跳过毒消息的规则也要明确。producer幂等、Kafka事务或提交offset,不自动把外部数据库/邮件等副作用纳入同一原子边界。
群聊可沿会话分配持久序号、保存消息并按客户端游标补拉/去重;“服务端已接收”“设备已接收”“用户已读”是不同确认。队列分区顺序不能单独保证离线设备补全或读回执。本合同给的是这些基础机制,没有闭合百万定时推送的分片、监控SLO和整套容量约束,也未实测群聊服务。
依据:Redis 分布式锁、PubSub 交付语义、Streams 消费组、RabbitMQ 4.1 确认、Kafka 4.0 消费设计。
🔁 换个栈怎么对应
| 概念 | Python / FastAPI | Node(Express / Hono) | Go |
|---|---|---|---|
| 请求内的后台活 | BackgroundTasks |
响应后继续 / setImmediate |
go func() |
| ⚠️ 这一档的通病 | 进程重启就丢 | 一样会丢 | 一样会丢 |
| 数据库当队列 | 自己写 + SKIP LOCKED |
pg-boss |
River |
| 专用队列 | Celery / RQ / arq | BullMQ | asynq |
| 定时任务 | APScheduler | node-cron | robfig/cron |
⭐ 名字全不一样,四件事完全一样:一张带状态的表、一条原子认领语句、一个同一业务意图重试复用的幂等键、一套带抖动和上限的重试。这四件事不过期,上面那些包名会。
🔗 这一章连到哪里
| 去哪 | 为什么 |
|---|---|
| Agent 长时任务的骨架 | 那边讲一个 Agent 自己怎么跑很久,本章讲后端怎么托住这种活。做「跑半小时的 Agent 任务」两边都要看 |
| 05 · 流式输出 | ⭐ 另一条岔路:单次对话生成也慢,但用户就坐在那儿等 —— 那是流式解决的问题,能流式就不要上队列。本章管的是另一类:用户等不了、必须先走人的活 |
| ⭐ 03c · 幂等与条件请求 | 本章第四节解决的是队列侧的幂等(同一个任务被消费两次)。⭐ 那一章解决接口侧的:本章答案里提过一句「更稳的是让客户端传 Idempotency-Key 头」——服务端拿到这个头之后该怎么办在那里(同键不同 body、并发同键、要不要重放原响应、存多久) |
| ⭐ 03b · 接口的形状 | 本章第三节那张「状态怎么让前端知道」的表只给了轮询和 SSE 两条路 —— ⚠️ 它的上游是一个建模问题:长任务该不该有自己的资源(202 Accepted + 一个 jobs 资源)。那一章讲这个 |
| 重训练 | 定时任务里最典型的一种:那边讲什么时候该重训,本章讲这条流水线怎么被调度和重试 |
| 连续批处理与 PagedAttention | ⚠️ 同名不同物:那边的「批处理」是推理引擎内部把多个请求拼进一次前向,毫秒级;本章的「批量任务」是应用层的分钟级排队 |
✅ 检查点
- 给出三条「必须异步」的判断信号。
BackgroundTasks的三个限制是什么?- 为什么「先
SELECT一个 queued 的、再UPDATE成 running」是错的?为什么「改写成一条语句」还不够?Postgres 上正确的写法长什么样? jobs表里run_after这一列干什么用?- 为什么不能每次重试重新调用
uuid4()生成幂等键?首次生成并持久化复用又如何?那段示例投递三次,账上有几笔、多少钱? - 什么是毒药消息?防住它要一起做的三件事是哪三件?
- 退避为什么必须加抖动?
- 哪些失败应停止自动重试?外部调用超时又要先确认什么?
- 队列已接收摘要消息,但转发进程来不及写「已发」就重启。恢复后会怎样?此时页面能把 202 当作完成吗?
👀 答案
- 任意三条:可能超过 30 秒(网关硬超时,用户看到 504 但后端还在烧钱)、批量处理、入库 + embedding、定时任务、需要重试的活。
- ① 跑在 web 进程里,和请求抢 worker;② 进程重启全丢,而部署 / 扩缩容 / OOM 每天都在重启;③ 状态存进程内存,多进程部署下另一个进程查不到这个 id。
- 两条语句之间有一道缝,两个 worker 会认领同一行。⚠️ 但只把它并成一条语句还不够:Postgres 上
UPDATE ... WHERE id = (SELECT ... LIMIT 1)的外层WHERE只比对id、不再检查status,并发时第二个事务先卡在行锁上等,等到之后要么重复认领要么空转。正确写法是把锁写进子查询 ——UPDATE ... WHERE id IN (SELECT id ... ORDER BY run_after LIMIT 1 FOR UPDATE SKIP LOCKED) RETURNING ...:FOR UPDATE当场锁行,SKIP LOCKED让别的 worker 跳过去拿下一条。本章那段 SQLite 示例之所以安全,靠的是整库一把写锁,理由完全不同。 - 延迟执行的时间点。认领语句里有
run_after <= now,重试时写now + delay,不能直接写退避时长。SQLite例用epoch秒;PostgreSQL时间戳列应使用对应的数据库时间加间隔。 - 幂等键应稳定标识同一次业务意图;每次重试新生成UUID会破坏去重,首次生成后持久化复用则可以。服务端还需拒绝同键不同内容,不能把相同内容的两次合法意图永久合并。示例结果是
['charged','skipped','skipped'],账上 1 笔、30 分。 - 永远会失败的任务,没有上限就无限循环、堵死队列。三件事:重试上限(示例
MAX_ATTEMPTS = 5)、指数退避加抖动、死信(要有人看、能重新入队)。 - 一次上游抖动会让一批任务同时失败,没抖动它们会在同一秒一起回来,把刚恢复的上游再打挂。代码里是
base * (0.5 + random()),跑出 2.69 / 5.03 / 7.36 / 12.14 秒。 - 参数错、凭证无效或被策略拒绝时,停止原样自动重试。暂时故障还要核对预算和可安全重放条件;外部结果未知时先查询原操作,或进入待核对。
- 发件箱还显示待发布,所以恢复后可能重复发布同一个任务号。消费端按任务号去重,保存结果并提交成功状态后才确认投递。页面按状态地址查到
succeeded才显示完成。
本节回顾
⚡ 走神救援
这一章讲「一个请求做不完的活怎么扔到后台」。判据:可能超过网关默认硬超时(那个量级就是几十秒,超时后用户看到 504、后端还在烧钱)、批量处理、入库加 embedding、定时任务、需要重试的活——任意一条就别在请求里做完。⚠️ 单次对话生成不算,那是流式解决的问题。
三档做法,⭐ 关键是别直接跳到第三档。进程内后台任务有三个限制(抢 worker、重启全丢、状态在内存里导致多进程查不到)。⭐ 数据库当队列覆盖中小规模的绝大多数场景,还能让任务状态和业务数据在同一个事务里改。
⚠️⚠️ 认领必须原子,但「写成一条语句」本身并不保证正确,也不是唯一原子认领方式:外层
WHERE只比对 id、不再检查状态时,并发下要么重复认领要么空转——必须把锁写进子查询(当场锁行 + 让别人跳过去拿下一条)。⚠️ 某些数据库上示例能跑通是因为整库一把写锁,理由完全不同,别照抄结论。接收与完成分开查。接收时保存任务和所需的待发布记录。队列接收确认只表示到达中间件,页面仍查任务的持久状态;消费端提交结果后才确认投递。
状态怎么让前端知道:默认轮询(无状态、哪台机器都能答)。⚠️ 别把间隔写成几百毫秒——三分钟的任务会发出上千个「好了没」。⭐ 进度报阶段不报百分比(LLM 时长不可预测,百分比可能长时间停在同一数值),而且进度要写在表里不是 worker 内存里,否则它一崩前端永远停在 40%。
⭐ 幂等不是可选项:任务可能重复执行。 键应标识同一次业务意图;随机 UUID 也能当业务幂等键,条件是首次生成后持久化,并在同一请求的重试中复用;不能每次重试重新生成。
下一节 👉 12-限流配额与成本护栏.md