🏠 总目录📚 本教程 11 · 长任务与队列 ← →

AI全栈 / 11

任务比一次请求更长时,结果该由谁接住?

先判断是否需要异步,再把任务状态、幂等、重试和死信接成可追踪的过程。

能说明任务已提交与任务已完成之间的差别。

设计可观察的任务状态

📑 本页目录(点开跳转)

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 看一遍。

① 应用提交同一事务保存任务和待发布记录,再返回 202。
② 队列接收转发进程发布任务号,按中间件的确认约定记录已发。
③ Worker 保存结果事务提交摘要与完成状态后,才确认本次投递(ACK)。
④ 页面查询按同一任务号查看排队、运行、完成或失败的状态。

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 0
t=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 ⚠️ 同名不同物:那边的「批处理」是推理引擎内部把多个请求拼进一次前向,毫秒级;本章的「批量任务」是应用层的分钟级排队

✅ 检查点

  1. 给出三条「必须异步」的判断信号。
  2. BackgroundTasks 的三个限制是什么?
  3. 为什么「先 SELECT 一个 queued 的、再 UPDATE 成 running」是错的?为什么「改写成一条语句」还不够?Postgres 上正确的写法长什么样?
  4. jobs 表里 run_after 这一列干什么用?
  5. 为什么不能每次重试重新调用 uuid4() 生成幂等键?首次生成并持久化复用又如何?那段示例投递三次,账上有几笔、多少钱?
  6. 什么是毒药消息?防住它要一起做的三件事是哪三件?
  7. 退避为什么必须加抖动?
  8. 哪些失败应停止自动重试?外部调用超时又要先确认什么?
  9. 队列已接收摘要消息,但转发进程来不及写「已发」就重启。恢复后会怎样?此时页面能把 202 当作完成吗?
👀 答案
  1. 任意三条:可能超过 30 秒(网关硬超时,用户看到 504 但后端还在烧钱)、批量处理、入库 + embedding、定时任务、需要重试的活。
  2. ① 跑在 web 进程里,和请求抢 worker;② 进程重启全丢,而部署 / 扩缩容 / OOM 每天都在重启;③ 状态存进程内存,多进程部署下另一个进程查不到这个 id。
  3. 两条语句之间有一道缝,两个 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 示例之所以安全,靠的是整库一把写锁,理由完全不同。
  4. 延迟执行的时间点。认领语句里有 run_after <= now,重试时写 now + delay,不能直接写退避时长。SQLite例用epoch秒;PostgreSQL时间戳列应使用对应的数据库时间加间隔。
  5. 幂等键应稳定标识同一次业务意图;每次重试新生成UUID会破坏去重,首次生成后持久化复用则可以。服务端还需拒绝同键不同内容,不能把相同内容的两次合法意图永久合并。示例结果是 ['charged','skipped','skipped'],账上 1 笔、30 分。
  6. 永远会失败的任务,没有上限就无限循环、堵死队列。三件事:重试上限(示例 MAX_ATTEMPTS = 5)、指数退避加抖动、死信(要有人看、能重新入队)。
  7. 一次上游抖动会让一批任务同时失败,没抖动它们会在同一秒一起回来,把刚恢复的上游再打挂。代码里是 base * (0.5 + random()),跑出 2.69 / 5.03 / 7.36 / 12.14 秒。
  8. 参数错、凭证无效或被策略拒绝时,停止原样自动重试。暂时故障还要核对预算和可安全重放条件;外部结果未知时先查询原操作,或进入待核对。
  9. 发件箱还显示待发布,所以恢复后可能重复发布同一个任务号。消费端按任务号去重,保存结果并提交成功状态后才确认投递。页面按状态地址查到 succeeded 才显示完成。

本节回顾

⚡ 走神救援

这一章讲「一个请求做不完的活怎么扔到后台」。判据:可能超过网关默认硬超时(那个量级就是几十秒,超时后用户看到 504、后端还在烧钱)、批量处理、入库加 embedding、定时任务、需要重试的活——任意一条就别在请求里做完。⚠️ 单次对话生成不算,那是流式解决的问题。

三档做法,⭐ 关键是别直接跳到第三档。进程内后台任务有三个限制(抢 worker、重启全丢、状态在内存里导致多进程查不到)。⭐ 数据库当队列覆盖中小规模的绝大多数场景,还能让任务状态和业务数据在同一个事务里改。

⚠️⚠️ 认领必须原子,但「写成一条语句」本身并不保证正确,也不是唯一原子认领方式:外层 WHERE 只比对 id、不再检查状态时,并发下要么重复认领要么空转——必须把锁写进子查询(当场锁行 + 让别人跳过去拿下一条)。⚠️ 某些数据库上示例能跑通是因为整库一把写锁,理由完全不同,别照抄结论。

接收与完成分开查。接收时保存任务和所需的待发布记录。队列接收确认只表示到达中间件,页面仍查任务的持久状态;消费端提交结果后才确认投递。

状态怎么让前端知道:默认轮询(无状态、哪台机器都能答)。⚠️ 别把间隔写成几百毫秒——三分钟的任务会发出上千个「好了没」。⭐ 进度报阶段不报百分比(LLM 时长不可预测,百分比可能长时间停在同一数值),而且进度要写在表里不是 worker 内存里,否则它一崩前端永远停在 40%。

⭐ 幂等不是可选项:任务可能重复执行。 键应标识同一次业务意图;随机 UUID 也能当业务幂等键,条件是首次生成后持久化,并在同一请求的重试中复用;不能每次重试重新生成。

下一节 👉 12-限流配额与成本护栏.md

打卡记录保存在你的浏览器里,首页能看到总进度