多智能体协同不再复杂:Redis Stream 消费者组、幂等与故障恢复

多智能体协同不再复杂:Redis Stream 消费者组、幂等与故障恢复

一句话结论 :多 Agent 协同的核心不是「发消息」,而是投递语义。List 会在崩溃时丢在途任务,Pub/Sub 会在离线时丢消息,只有 Stream 消费者组提供「至少一次 + 可认领 + 可追溯」;而至少一次必然带来重复,所以幂等不是可选项,是协议的一部分。

版本基线 :Redis 7.0+(XAUTOCLAIM 的三元组返回值)/ Redis 8.x / redis-py 6.x / Python 3.12。若使用 Redis 6.2--6.x,XAUTOCLAIM 只返回两元组,不能解包第三个 deleted 列表。

前置阅读 :03 · 语义缓存


1. 先选投递语义,再选数据结构

方案 投递语义 崩溃恢复 多消费者 延迟消息 适用
List(LPUSH/BRPOP) 至多一次(取走即消失) ❌ 在途丢失 竞争消费 ❌ 可丢的轻量任务
List + processing list(LMOVE) 至少一次 ✅ 需超时清扫 ✅ ❌ 老系统、简单场景
Pub/Sub 至多一次 ❌ 离线即丢 广播 ❌ 控制面通知、实时流
Stream 单消费者 至少一次(需 ACK) ✅ PEL ❌ ❌ 审计、事件日志
Stream 消费者组 至少一次 ✅ PEL + XAUTOCLAIM ✅ 负载均衡 ❌(需外置延迟队列) 生产任务调度
ZSet + 调度器 取决于落点 取决于落点 ✅ ✅ 优先级/延迟队列

结论 :任务分发用 Stream 消费者组;延迟/优先级用 ZSet 做前置调度,再把任务 XADD 进 Stream;Pub/Sub 只做控制面。
#mermaid-svg-5YGLtUIz39bF5yFp{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-5YGLtUIz39bF5yFp .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-5YGLtUIz39bF5yFp .error-icon{fill:#552222;}#mermaid-svg-5YGLtUIz39bF5yFp .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-5YGLtUIz39bF5yFp .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-5YGLtUIz39bF5yFp .marker{fill:#333333;stroke:#333333;}#mermaid-svg-5YGLtUIz39bF5yFp .marker.cross{stroke:#333333;}#mermaid-svg-5YGLtUIz39bF5yFp svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-5YGLtUIz39bF5yFp p{margin:0;}#mermaid-svg-5YGLtUIz39bF5yFp .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-5YGLtUIz39bF5yFp .cluster-label text{fill:#333;}#mermaid-svg-5YGLtUIz39bF5yFp .cluster-label span{color:#333;}#mermaid-svg-5YGLtUIz39bF5yFp .cluster-label span p{background-color:transparent;}#mermaid-svg-5YGLtUIz39bF5yFp .label text,#mermaid-svg-5YGLtUIz39bF5yFp span{fill:#333;color:#333;}#mermaid-svg-5YGLtUIz39bF5yFp .node rect,#mermaid-svg-5YGLtUIz39bF5yFp .node circle,#mermaid-svg-5YGLtUIz39bF5yFp .node ellipse,#mermaid-svg-5YGLtUIz39bF5yFp .node polygon,#mermaid-svg-5YGLtUIz39bF5yFp .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-5YGLtUIz39bF5yFp .rough-node .label text,#mermaid-svg-5YGLtUIz39bF5yFp .node .label text,#mermaid-svg-5YGLtUIz39bF5yFp .image-shape .label,#mermaid-svg-5YGLtUIz39bF5yFp .icon-shape .label{text-anchor:middle;}#mermaid-svg-5YGLtUIz39bF5yFp .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-5YGLtUIz39bF5yFp .rough-node .label,#mermaid-svg-5YGLtUIz39bF5yFp .node .label,#mermaid-svg-5YGLtUIz39bF5yFp .image-shape .label,#mermaid-svg-5YGLtUIz39bF5yFp .icon-shape .label{text-align:center;}#mermaid-svg-5YGLtUIz39bF5yFp .node.clickable{cursor:pointer;}#mermaid-svg-5YGLtUIz39bF5yFp .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-5YGLtUIz39bF5yFp .arrowheadPath{fill:#333333;}#mermaid-svg-5YGLtUIz39bF5yFp .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-5YGLtUIz39bF5yFp .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-5YGLtUIz39bF5yFp .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-5YGLtUIz39bF5yFp .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-5YGLtUIz39bF5yFp .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-5YGLtUIz39bF5yFp .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-5YGLtUIz39bF5yFp .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-5YGLtUIz39bF5yFp .cluster text{fill:#333;}#mermaid-svg-5YGLtUIz39bF5yFp .cluster span{color:#333;}#mermaid-svg-5YGLtUIz39bF5yFp div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-5YGLtUIz39bF5yFp .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-5YGLtUIz39bF5yFp rect.text{fill:none;stroke-width:0;}#mermaid-svg-5YGLtUIz39bF5yFp .icon-shape,#mermaid-svg-5YGLtUIz39bF5yFp .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-5YGLtUIz39bF5yFp .icon-shape p,#mermaid-svg-5YGLtUIz39bF5yFp .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-5YGLtUIz39bF5yFp .icon-shape rect,#mermaid-svg-5YGLtUIz39bF5yFp .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-5YGLtUIz39bF5yFp .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-5YGLtUIz39bF5yFp .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-5YGLtUIz39bF5yFp :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Lua: 幂等入队
promoter
超过重试
XACK
XACK
认领超时消息
API / 编排器
Stream

tasks
ZSet

delayed/priority
Worker A

consumer group
Worker B
Stream

dead-letter
Reclaimer

XAUTOCLAIM


2. Stream 的语义细节:必须知道的六件事

2.1 消息 ID 不是业务时间

XADD key * field value 让 Redis 生成 <毫秒时间>-<序号>。同一毫秒内多条消息靠序号递增;即使系统时钟回拨,Redis 也会保证 ID 单调(在现有最大 ID 基础上递增)。

不要把消息 ID 当作业务时间戳做计费或排序。业务时间放在字段里,ID 只用于流内定位。

2.2 PEL 是「已投递未确认」,不是「正在处理」

消费者组为每个消费者维护 PEL(Pending Entries List)。XREADGROUP ... > 投递后,消息进入该消费者的 PEL;XACK 后移除。

关键推论:

  • 消费者崩溃后,消息仍在 PEL 里,但不会自动重新投递;
  • 必须由 XAUTOCLAIM(或 XCLAIM)在空闲超时后认领;
  • 没配 reclaimer,崩溃消费者的消息会永久悬挂。

#mermaid-svg-Dgi3zhsjz4OUFhe7{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .error-icon{fill:#552222;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .marker.cross{stroke:#333333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 p{margin:0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-Dgi3zhsjz4OUFhe7 g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-Dgi3zhsjz4OUFhe7 g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Dgi3zhsjz4OUFhe7 .edgeLabel .label text{fill:#333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .label div .edgeLabel{color:#333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 #statediagram-barbEnd{fill:#333333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .cluster-label,#mermaid-svg-Dgi3zhsjz4OUFhe7 .nodeLabel{color:#131300;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .note-edge{stroke-dasharray:5;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-note text{fill:black;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram-note .nodeLabel{color:black;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagram .edgeLabel{color:red;}#mermaid-svg-Dgi3zhsjz4OUFhe7 #dependencyStart,#mermaid-svg-Dgi3zhsjz4OUFhe7 #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-Dgi3zhsjz4OUFhe7 .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Dgi3zhsjz4OUFhe7 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} XADD
XREADGROUP
成功 + XACK
租约超时 / XAUTOCLAIM
超过最大重试
Pending
Delivered
Done
Dead

2.3 XAUTOCLAIM 会返回「已删除的消息 ID」

如果消息在 PEL 中被 XDEL,或流被 XTRIM 截断,XAUTOCLAIM 的第三个返回值会包含这些 ID:

text 复制代码
XAUTOCLAIM stream group consumer 60000 0-0 COUNT 10
→ [next-start-id, [[id, fields], ...], [deleted-id, ...]]

这是任务丢失的强信号,必须告警。很多实现只读前两个返回值,导致任务静默消失。

版本差异:第三个返回值(deleted IDs)是 Redis 7.0 才加入的;Redis 6.2 的 XAUTOCLAIM 只返回 [next-start-id, entries]。如果你的基线是 6.2,要么升级到 7.x,要么在应用层接受「无法感知 PEL 指向已删除消息」这一盲区,并通过 XINFO STREAM 的 first-entry 与 XPENDING 对账来补。

2.4 裁剪不能裁掉在途消息

XADD ... MAXLEN ~ 10000 只保证「大约」保留最近 N 条。如果消费者严重落后,或 PEL 里还有旧消息,裁剪可能把未 ACK 的任务从流里删掉------PEL 里只剩一个指向不存在消息的 ID。

生产规则:

  • MAXLEN 必须显著大于「最大在途消息数 + 最大重试窗口」;
  • 对不可丢任务,先归档到冷存储,再裁剪;
  • 定期用 XINFO STREAM 的 first-entry / last-entry 与 XPENDING 对比,确认没有 PEL ID 早于 first-entry。

2.5 消费者组不会自动删除空闲消费者

XINFO GROUPS 会显示消费者数量与 pending 数。消费者下线后,其名称仍保留,PEL 也保留。需要:

  • 监控每个消费者的 pending 与 idle;
  • 用 reclaimer 接管超时消息;
  • 定期 XGROUP DELCONSUMER 清理已下线且 PEL 为空的消费者(有 PEL 时慎用)。

2.6 没有原生延迟消息

Stream 不支持「N 秒后投递」。常见三种实现:

  1. 延迟 ZSet + promoter :到期后 XADD 进流(推荐);
  2. 消费者读到未到期消息后 sleep 或重新入队(浪费投递、放大 PEL);
  3. 外部定时器(复杂、易丢)。

第 1 种把「延迟」和「投递」解耦,故障恢复也简单:promoter 崩溃后,ZSet 里的任务还在。

2.7 消费者组没有自动 rebalance

Redis Streams 不像 Kafka 那样有 partition 分配与 rebalance 协议。任何消费者都可以用 > 读取任意新消息:

  • 扩容时,新消费者自然分走一部分新消息,但旧消费者 PEL 里的消息不会自动迁移;
  • 缩容时,下线消费者的 PEL 需要 XAUTOCLAIM 接管;
  • 没有 coordinator,也没有「消费者加入即触发再平衡」;
  • 空闲消费者不会自动删除,XINFO CONSUMERS 会持续累积。

工程含义:

  1. 消费者数量不等于吞吐。单 Stream 受单分片 CPU 与单 Key 限制,先分片再加消费者。
  2. 缩容前先停止读取,等待 PEL 清空;或主动把 PEL 转移给其他消费者。
  3. 监控每个消费者的 pending 与 idle,避免一个消费者持有大量未 ACK 消息。
  4. 不要依赖「消费者名称」做业务分片;消费组只保证消息被某个消费者读到,不保证固定映射。

3. 任务模型:先把协议定清楚

python 复制代码
from dataclasses import dataclass, asdict
import orjson

@dataclass(frozen=True)
class Task:
    task_id: str            # ULID,全局唯一,幂等键
    tenant: str
    kind: str               # refund_lookup / doc_index / notify ...
    payload: dict
    priority: int = 0       # 越大越优先
    attempt: int = 0
    deadline_ms: int = 0    # 绝对截止时间;过期任务直接进死信
    trace_id: str = ""
    idempotency_key: str = ""

    def to_json(self) -> bytes:
        return orjson.dumps(asdict(self))

协议约束:

  • task_id 由生产者在入队前生成,不能由消费者生成;
  • idempotency_key 用于业务副作用去重(如「退款单号 + 操作类型」);
  • deadline_ms 是绝对时间,避免重试时无限延后;
  • tenant 用于分片、限流、隔离,不能只放在 payload 里。

3.1 任务 schema 的演进

任务会跨版本共存:旧 worker 还在跑,新 producer 已经在写新字段。协议要能向前/向后兼容:

变更 做法 风险
新增可选字段 消费者给默认值 旧消费者忽略新字段
新增必填字段 先双写/灰度,再切读 旧消费者解析失败
删除字段 先停写,再删读,最后清理 新旧混跑读到空值
改字段类型 新字段名 + 双读 隐式类型转换导致脏数据
大 payload 外置对象存储,Stream 只放 URI + hash 消息体积、内存、网络

payload 里带 schema_version;未知 kind 不要让 worker 崩溃,直接进死信并告警,避免一条毒消息拖垮整个消费组。


4. 入队:幂等 + 原子

4.1 为什么需要入队幂等

上游超时重试、编排器重复触发、用户双击,都会产生重复任务。如果只靠消费者幂等,重复消息仍会占用队列、触发无谓的认领与重试。入队时用 SET NX 去重更便宜:

lua 复制代码
-- KEYS[1] = 去重 Key(与 Stream 同槽)
-- KEYS[2] = Stream
-- ARGV[1] = task_id
-- ARGV[2] = 去重 TTL 毫秒
-- ARGV[3] = Stream 近似上限(MAXLEN ~)
-- ARGV[4..] = field/value 对
if redis.call('SET', KEYS[1], '1', 'NX', 'PX', ARGV[2]) == false then
  return 0
end
local fields = {}
for i = 4, #ARGV do
  fields[#fields + 1] = ARGV[i]
end
-- XADD 失败时必须回滚去重 Key,否则任务无法重试,直到 TTL 到期。
-- Lua 没有事务回滚,只能用 pcall 显式补偿。
local ok = redis.pcall('XADD', KEYS[2], 'MAXLEN', '~', ARGV[3], '*',
                       unpack(fields))
if type(ok) == 'table' and ok.err then
  redis.call('DEL', KEYS[1])
  return redis.error_reply(ok.err)
end
return 1
python 复制代码
ENQUEUE_LUA = """
-- 同上,实际项目放独立文件
"""

async def enqueue(r, task: Task, shard: str = "0") -> bool:
    tag = f"{{agent:shard:{shard}}}"
    dedup_key = f"{tag}:idem:enqueue:{task.task_id}"
    stream = f"{tag}:tasks"
    fields = {
        "task_id": task.task_id,
        "tenant": task.tenant,
        "kind": task.kind,
        "payload": task.to_json(),
        "priority": str(task.priority),
        "attempt": str(task.attempt),
        "deadline_ms": str(task.deadline_ms),
        "trace_id": task.trace_id,
        "idempotency_key": task.idempotency_key,
    }
    # 上限必须远大于「最大在途 + 重试窗口」,否则可能裁掉未 ACK 的消息
    args: list[str] = [task.task_id, "86400000", "100000"]
    for k, v in fields.items():
        args.extend([k, v])
    ok = await r.eval(ENQUEUE_LUA, 2, dedup_key, stream, *args)
    return bool(ok)

同槽要求 :dedup_key 与 stream 都带 {agent:shard:0},在 Cluster 下同槽。分片键用租户哈希,避免所有任务挤在一个槽:

python 复制代码
import hashlib


def shard_of(tenant: str, n: int = 16) -> str:
    return str(int(hashlib.sha256(tenant.encode()).hexdigest()[:8], 16) % n)

4.2 去重 TTL 怎么定

TTL > 任务最大生命周期 + 重试窗口。太短会让重复任务穿透;太长会阻止合法的「同 ID 重放」(通常不应该有)。一般 24 h 起步,按业务调整。


5. Worker:至少一次 + 幂等执行

5.1 主循环

python 复制代码
import asyncio
import logging
import random
import time
from dataclasses import replace

import redis.asyncio as redis

log = logging.getLogger(__name__)


def now_ms() -> int:
    return int(time.time() * 1000)


async def alert(event: str, **fields) -> None:
    # 生产中接告警系统;这里用结构化日志占位
    log.error(event, extra=fields)


class TaskInProgress(Exception):
    """同一 task 已有消费者在租约内执行。"""


def decode_task(fields: dict) -> Task:
    raw = fields.get(b"payload") or fields.get("payload")
    if raw is None:
        raise ValueError("missing payload")
    return Task(**orjson.loads(raw))


async def schedule_retry(r, task: Task, attempt: int, exc: Exception) -> None:
    shard = shard_of(task.tenant)
    tag = f"{{agent:shard:{shard}}}"
    due = now_ms() + min(300_000, 1000 * (2 ** attempt)) + random.randint(0, 500)
    retry = replace(task, attempt=attempt)
    # 生产上建议用 Lua 把 ZADD + HSET + EXPIRE 一次原子写入;
    # MULTI/EXEC 只保证隔离,不保证运行时错误回滚,半写状态要靠对账修复。
    async with r.pipeline(transaction=True) as pipe:
        pipe.zadd(f"{tag}:delayed", {task.task_id: due})
        pipe.hset(f"{tag}:payloads", task.task_id, retry.to_json())
        pipe.expire(f"{tag}:payloads", 86400)
        await pipe.execute()


CAS_STATE_LUA = """
local v = redis.call('GET', KEYS[1])
if v ~= ARGV[1] then return 0 end
redis.call('SET', KEYS[1], ARGV[2], 'EX', tonumber(ARGV[3]))
return 1
"""


async def cas_state(r, key: str, expected: str, new: str, ex: int = 300) -> bool:
    return bool(await r.eval(CAS_STATE_LUA, 1, key, expected, new, ex))


async def worker_loop(
    r: redis.Redis,
    *,
    stream: str,
    group: str,
    consumer: str,
    handler,
    dlq: str,
    max_attempts: int = 5,
):
    while True:
        resp = await r.xreadgroup(
            group, consumer, {stream: ">"},
            count=1, block=5000,
        )
        if not resp:
            continue

        for _, messages in resp:
            for msg_id, fields in messages:
                task = decode_task(fields)
                if task.deadline_ms and now_ms() > task.deadline_ms:
                    await r.xadd(dlq, {
                        **fields,
                        "error": "deadline_exceeded",
                    })
                    await r.xack(stream, group, msg_id)
                    continue

                try:
                    await execute_idempotent(r, task, handler)
                    await r.xack(stream, group, msg_id)
                except TaskInProgress:
                    # 不 ACK:消息留在 PEL,等租约过期后由 reclaimer 接管
                    continue
                except Exception as exc:
                    attempt = task.attempt + 1
                    if attempt >= max_attempts:
                        await r.xadd(dlq, {
                            **fields,
                            "attempt": str(attempt),
                            "error": str(exc)[:500],
                        })
                        await r.xack(stream, group, msg_id)
                    else:
                        await schedule_retry(r, task, attempt, exc)
                        await r.xack(stream, group, msg_id)

注意顺序:先完成副作用,再 XACK。如果反过来(先 ACK 再执行),进程崩溃会直接丢任务。

5.2 幂等执行:状态机,不是布尔标记

只用一个 SETNX 标记「处理过」是不够的:进程可能在某一步崩溃,标记存在但副作用只完成一半。用状态机:

text 复制代码
(none) --claim--> running --success--> done
                     |
                     +--failure--> failed --retry--> running
python 复制代码
IDEM_TTL = 7 * 86400

async def execute_idempotent(r, task: Task, handler) -> None:
    key = f"{{agent:shard:{shard_of(task.tenant)}}}:idem:task:{task.task_id}"
    # 1) 抢占执行权;running 的 TTL 是租约,不是最终状态
    claimed = await r.set(key, "running", nx=True, ex=300)
    if not claimed:
        state = await r.get(key)
        if isinstance(state, bytes):
            state = state.decode()
        if state == "done":
            return
        if state == "running":
            # 另一个消费者正在执行:不并发执行,直接让本次投递留在 PEL,
            # 由 reclaimer 在租约过期后再次认领。
            raise TaskInProgress()
        if state == "failed":
            # 明确失败且允许重试时,用 CAS 重新抢
            if not await cas_state(r, key, "failed", "running", ex=300):
                raise RuntimeError("task_state_conflict")
        else:
            raise RuntimeError(f"unknown_state:{state}")

    try:
        await handler(task)
        await r.set(key, "done", ex=IDEM_TTL)
    except Exception:
        # 不直接 DEL:副作用可能已部分发生,交给人工/补偿流程判断
        await r.set(key, "failed", ex=IDEM_TTL)
        raise

三个关键点:

  1. 租约要覆盖最大执行时间,并由心跳续租 ,reclaimer 的 idle 阈值要与租约协调:idle < lease 时,reclaimer 在租约有效期内认领会看到 running 并放弃,恢复慢但不会并发;idle > lease 时,租约可能已过期,必须依赖幂等 + fencing 防止旧 worker 继续写。无论哪种,都不能用 P99 当阈值------按定义有 1% 的任务会超过它。
  2. 失败不要简单删除幂等键 。如果副作用已经发生,重试可能重复下单;应进入 failed,由业务补偿或人工审核决定是否重试。
  3. 业务副作用仍要有自己的唯一约束。Redis 幂等键只覆盖「同一 task_id」;如果同一业务操作换了 task_id,仍需数据库唯一索引/去重表兜底。

5.3 续租与 fencing token

长任务在租约过期后可能被另一个 worker 认领,出现「双执行」。除了幂等,还需要 fencing token 保护外部资源:

text 复制代码
INCR resource:{id}:epoch  → 42
写入下游时携带 epoch=42
下游只接受 >= 当前最大 epoch 的写入

这样即使旧 worker 在租约过期后恢复,它的写也会被下游拒绝。锁只能降低并发概率,fencing 才能阻止过期持有者造成破坏。

5.4 取消、超时与清理

任务取消不是 XDEL:消息可能已经被投递到某个消费者,删流只会让 PEL 里留下一个不存在的 ID。

正确做法:

  1. 持久取消标记 :SET {tag}:cancel:{task_id} 1 EX 86400,worker 在处理前、每个工具调用边界检查;
  2. 控制面通知:Pub/Sub 只用于「尽快通知在线 worker」,不能作为唯一取消依据;
  3. 超时 :deadline_ms 在执行前检查,在执行中的工具调用边界检查;不要在 Python 里强杀线程;
  4. 清理 :取消后仍要 XACK,写入审计/死信,释放幂等租约与外部资源;
  5. 幂等:取消与完成可能竞争,状态机用 CAS 决定最终状态,不能两个都成功。

取消是「协作式」的。没有在代码里插入检查点,任何外部信号都无法安全停止一个正在运行的 handler。


6. Reclaimer:处理崩溃与超时

python 复制代码
async def reclaim_loop(
    r: redis.Redis,
    *,
    stream: str,
    group: str,
    consumer: str,
    handler,
    dlq: str,
    idle_ms: int = 60_000,
    max_attempts: int = 5,
):
    start = "0-0"
    while True:
        result = await r.xautoclaim(
            stream, group, consumer,
            min_idle_time=idle_ms,
            start_id=start,
            count=10,
        )
        if len(result) == 3:          # Redis 7.0+
            next_id, messages, deleted = result
        else:                          # Redis 6.2: 没有 deleted 列表
            next_id, messages = result
            deleted = []
        if deleted:
            # 被裁剪/删除的 PEL 条目:任务数据已不可恢复,必须告警
            await alert("stream_pending_deleted", ids=deleted)

        for msg_id, fields in messages:
            task = decode_task(fields)
            try:
                await execute_idempotent(r, task, handler)
                await r.xack(stream, group, msg_id)
            except TaskInProgress:
                continue
            except Exception as exc:
                attempt = task.attempt + 1
                if attempt >= max_attempts:
                    await r.xadd(dlq, {**fields, "attempt": str(attempt),
                                       "error": str(exc)[:500]})
                else:
                    await schedule_retry(r, task, attempt, exc)
                await r.xack(stream, group, msg_id)

        start = next_id
        # decode_responses=False 时 next_id 是 bytes
        if start in ("0-0", b"0-0"):
            await asyncio.sleep(1)
            start = "0-0"

reclaimer 要用独立的消费者名 (例如 worker-1-reclaimer),不要和 worker 共用身份:XAUTOCLAIM 会把消息认领到指定消费者的 PEL,共用身份会让旧 worker 的 XACK 清掉 reclaimer 正在重试的条目,pending/idle 指标也会混在一起。

idle_ms 的取值要与租约协调,而不是套一个 P99:

text 复制代码
lease_ttl >= 最大执行时间 + 余量(长任务心跳续租)
idle_ms 与 lease_ttl 的取舍:
  idle_ms < lease_ttl  → 恢复慢,但 reclaimer 会在租约有效期内看到 running 并放弃
  idle_ms > lease_ttl  → 恢复快,但租约过期后可能出现双执行,必须靠幂等 + fencing 兜底

太小会反复认领正在执行的消息;太大故障恢复慢。用最大执行时间、心跳间隔和真实故障演练校准,不要拍脑袋写 60 秒。


7. 延迟队列与优先级:ZSet 做调度,Stream 做投递

7.1 延迟队列

text 复制代码
ZADD agent:shard:0:delayed <available_at_ms> <task_id>
HSET agent:shard:0:payloads <task_id> <task_json>

promoter 到期搬运,整个过程用 Lua 保证「取出 + 入流 + 删除」原子:

lua 复制代码
-- KEYS[1] delayed ZSet, KEYS[2] payloads Hash, KEYS[3] stream
-- ARGV[1] now_ms, ARGV[2] batch, ARGV[3] stream maxlen
local ids = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1],
                       'LIMIT', 0, tonumber(ARGV[2]))
for _, id in ipairs(ids) do
  local payload = redis.call('HGET', KEYS[2], id)
  if payload then
    redis.call('XADD', KEYS[3], 'MAXLEN', '~', ARGV[3], '*',
               'task_id', id, 'payload', payload)
    redis.call('HDEL', KEYS[2], id)
  end
  redis.call('ZREM', KEYS[1], id)
end
return #ids

同一个 task_id 的延迟任务与入队去重 Key 共享生命周期,避免「已入流但 ZSet 未删」造成重复。promoter 崩溃后,ZSet 未删的任务会在下一轮再次搬运;消费者幂等能吸收重复。

7.2 优先级:避免饥饿

直接在 ZSet 里按 priority 取最高,会让低优先级任务永远排在后面。生产上至少加一种公平机制:

  • 老化 :score = priority + wait_ms / aging_window,等待越久分数越高;
  • 多队列加权:P0/P1/P2 三个 Stream,worker 按 6:3:1 的权重读取;
  • 每租户配额:同一租户不能占满队列(令牌桶,第 5 篇)。

一个原子的「优先级 ZSet → Stream」搬运:

lua 复制代码
-- KEYS[1] ready ZSet, KEYS[2] payloads Hash, KEYS[3] stream
-- ARGV[1] stream maxlen
local ids = redis.call('ZREVRANGE', KEYS[1], 0, 0)
if #ids == 0 then return 0 end
local id = ids[1]
local payload = redis.call('HGET', KEYS[2], id)
if not payload then
  redis.call('ZREM', KEYS[1], id)
  return 0
end
-- 先写 Stream,再删除 ZSet/Hash:即使后续命令失败,任务也不会凭空消失;
-- 反之(先删再 XADD)一旦 XADD 失败,任务就永久丢失。
redis.call('XADD', KEYS[3], 'MAXLEN', '~', ARGV[1], '*',
           'task_id', id, 'payload', payload)
redis.call('ZREM', KEYS[1], id)
redis.call('HDEL', KEYS[2], id)
return 1

不要在消费者里用 ZPOPMAX 直接取任务:取走即从 ZSet 删除,进程崩溃就丢。先搬到 Stream,再由消费者组保证至少一次。


8. Pub/Sub 的正确位置:控制面,不是数据面

Pub/Sub 的语义是至多一次、不持久化、无 ACK、无背压。它适合:

场景 为什么适合 注意
配置/开关广播 丢一条也能靠下一次拉取纠正 版本号 + 定期全量拉取
取消信号 迟到无意义,丢了由超时兜底 与任务状态机配合
实时 token 流多端分发 允许丢帧/重连 不用于计费/审计
缓存失效通知 TTL 兜底 失效失败要能对账

不适合:

  • 任务分发(离线消费者直接丢任务);
  • 计费/审计事件(不能丢);
  • 需要重放的协同(无历史)。

Cluster 下用 SSUBSCRIBE 做分片发布订阅,避免广播到所有节点;普通 PUBLISH 在 Cluster 中会被广播到全集群,规模大时成本显著。

python 复制代码
# 控制面示例:配置版本广播 + 定期拉取兜底
async def publish_config(r, version: int):
    await r.publish("agent:config", str(version))

async def watch_config(r, on_change):
    pubsub = r.pubsub()
    await pubsub.subscribe("agent:config")
    async for msg in pubsub.listen():
        if msg["type"] == "message":
            await on_change(int(msg["data"]))

9. 能力匹配:Set 做索引,负载做决策

text 复制代码
SADD agent:cap:refund a1 a2 a3
SADD agent:cap:zh     a2 a4
SINTER agent:cap:refund agent:cap:zh   # a2

但「有能力」不等于「应该派给它」:

  • a2 可能已经满载;
  • a2 可能心跳过期;
  • a2 可能在同一租户上被限流。

综合决策:

lua 复制代码
-- KEYS[1] capability Set, KEYS[2] load ZSet, KEYS[3] heartbeat Hash
-- ARGV[1] now_ms, ARGV[2] heartbeat_ttl_ms
local members = redis.call('SMEMBERS', KEYS[1])
local best, best_load = nil, nil
for _, id in ipairs(members) do
  local hb = tonumber(redis.call('HGET', KEYS[3], id) or '0')
  if hb + tonumber(ARGV[2]) >= tonumber(ARGV[1]) then
    local load = tonumber(redis.call('ZSCORE', KEYS[2], id) or '0')
    if best == nil or load < best_load then
      best, best_load = id, load
    end
  end
end
if best == nil then return nil end
redis.call('ZINCRBY', KEYS[2], 1, best)  -- 预留负载
return best

SMEMBERS 是 O(N) 。能力集合通常很小(几十到几百),可接受;如果达到数万,改用 SSCAN 分页或按能力再分桶(cap:refund:available / cap:refund:busy)。

负载计数必须闭环:脚本里的 ZINCRBY +1 只是预留,任务完成、失败、超时都要在 finally 里 ZINCRBY -1,并用定期重算修正漂移。只加不减的负载 ZSet 会在几小时内把所有 Agent 标成「满载」。


10. 背压与容量:队列不是无限缓冲区

必看指标:

bash 复制代码
XLEN agent:shard:0:tasks
XINFO GROUPS agent:shard:0:tasks
XPENDING agent:shard:0:tasks workers
INFO memory
指标 含义 告警阈值(示例)
XLEN 积压长度 持续 > 可消费量 × 5 min
lag 组落后消息数 持续增长
pending 已投递未确认 > 消费者数 × 并发 × 2
idle(消费者) 消费者空闲时间 > 2 × 心跳间隔
deleted(XAUTOCLAIM) PEL 指向已删除消息 > 0 立即告警
Redis 内存 Stream + PEL + 延迟队列 接近 maxmemory 前扩容

背压策略:

  • 入队前检查 XLEN,超过硬上限直接拒绝(返回 429),不要无限堆积;
  • 消费者 count 保持小(1--10),避免一次预取过多导致 PEL 膨胀;
  • 按租户分片,防止单租户打满全局队列;
  • 对不可丢任务设置 deadline_ms,过期进死信而不是无限重试。

10.1 消费者数量怎么估

text 复制代码
单消费者吞吐 ≈ batch_size / (平均处理时间 + RTT)
所需消费者数 ≈ 目标吞吐 / 单消费者吞吐 × (1 + 余量)

算例(假设):目标 500 任务/s,单任务平均 200 ms,batch=10,RTT=1 ms:

text 复制代码
单消费者吞吐 ≈ 10 / 0.201 ≈ 49.8 任务/s
所需消费者 ≈ 500 / 49.8 × 1.3 ≈ 14

但这只是起点。还要检查:

  • 单个 Stream 分片的 CPU 与内存是否撑得住;
  • PEL 峰值是否超过 MAXLEN 的安全边界;
  • 下游依赖(模型、数据库、外部 API)是否能承受并发;
  • 消费者扩容后,Redis 连接数与 maxclients 是否足够。

吞吐瓶颈通常不在消费者数量,而在下游依赖或单分片。 先压测,再加机器。


11. Cluster 下的坑

  1. Stream 与去重 Key 必须同槽 :用 {agent:shard:N} hash tag。
  2. 一个 XREADGROUP 里的多个 Stream 必须同槽;跨槽会被客户端拒绝或拆分。多流场景按槽分实例读取。
  3. Lua 中所有 Key 必须显式声明且同槽 ;不要在脚本里用 KEYS[1] .. id 动态拼 Key,Cluster 无法校验。
  4. XINFO/XPENDING 是单 Key 命令,按分片逐个查。
  5. 热分片:按租户哈希分片,但大租户仍可能集中;对超级租户单独分片或限流。
  6. 故障切换可能丢最近写入 :Stream 消息也可能丢。对不可丢任务,XADD 后配合 WAIT 1 <timeout>(增加延迟)或落库 Outbox,再异步投递。

12. 与 Kafka / SQS 的取舍

维度 Redis Streams Kafka SQS
投递语义 至少一次(PEL + ACK) 至少一次/事务内 exactly-once 至少一次
保留 内存,按长度/时间裁剪 磁盘,按时间/大小保留 最长 14 天
重放 有限(未裁剪范围内) 强 无
分区 按 Key 分片,无自动再平衡 Partition + Consumer Group 无顺序(FIFO 队列有)
延迟消息 需外置 ZSet 需外置/定时 原生 Delay Queue
运维 已有 Redis 则极低 高 低
适用规模 中低延迟、短保留、任务型 高吞吐、长保留、事件溯源 简单任务、云原生

选型建议:已有 Redis、任务生命周期短、需要低延迟与简单运维 → Streams;需要长保留、强重放、跨团队事件总线 → Kafka。不要用 Redis Streams 硬扛 Kafka 的职责。

12.1 与工作流引擎的边界

Redis Streams 适合「短生命周期、可重试、至少一次」的任务;以下需求不要硬扛:

需求 更适合
跨天/跨周的持久定时器 工作流引擎(Temporal/Cadence)或调度服务
人工审批、长时间等待 工作流引擎 + 持久状态
复杂分支/补偿/Saga 工作流引擎或编排服务
事件溯源、长保留回放 Kafka 等日志系统
简单任务分发、低延迟 Redis Streams

用 Redis 做工作流不是不行,但你要自己实现定时器、状态机、补偿、审计与可视化;这些正是工作流引擎的核心价值。不要把「能跑」当成「该用」。


13. 失效模式清单

症状 根因 修复
任务静默消失 流被裁剪到 PEL 之前 MAXLEN 留足余量;监控 deleted
同一任务执行两次 至少一次投递 幂等键 + 业务唯一约束 + fencing
消费者挂了任务不动 无 reclaimer XAUTOCLAIM + 告警
双执行 租约过期后旧 worker 恢复 续租 + fencing token
重试风暴 立即重试无退避 指数退避 + 抖动 + 最大次数
延迟任务不触发 promoter 崩溃 ZSet 持久化;promoter 多实例 + 幂等
低优先级饿死 严格优先级 老化/加权/配额
单槽打满 所有租户共用一个 Stream 按租户哈希分片
内存暴涨 无上限积压 MAXLEN + 入队背压 + 死信
重复入队 上游重试 入队 SET NX 去重
任务过期仍执行 无 deadline 检查 执行前校验绝对截止时间

14. 生产检查清单

  • 任务协议包含 task_id、tenant、deadline、idempotency_key、trace_id;
  • 入队用 Lua 做「去重 + XADD」原子操作,Key 同槽;
  • 消费者先执行副作用再 XACK;
  • 幂等状态机覆盖 running/done/failed,长任务续租;
  • 有 XAUTOCLAIM reclaimer,且处理 deleted 返回值;
  • idle_ms 根据 P99 执行时间校准;
  • 延迟/优先级用 ZSet + promoter,搬运原子;
  • MAXLEN 大于最大在途量,或先归档再裁剪;
  • 死信流有告警与人工处理入口;
  • Pub/Sub 只用于控制面,不用于任务;
  • 监控 XLEN、lag、pending、deleted、消费者 idle;
  • 不可丢任务有 WAIT/Outbox/落库兜底,不假设 Redis 故障切换零丢失。

参考资料

  1. Redis 官方文档:Streams、Consumer groups、XAUTOCLAIM、XINFO、XPENDING、XTRIM。
  2. Redis 6.2 / 7.0 release notes:XAUTOCLAIM、FUNCTION、sharded pub/sub。
  3. Kafka 官方文档:consumer group、offset、exactly-once semantics。
  4. AWS SQS 文档:visibility timeout、DLQ、FIFO。
  5. Martin Kleppmann, How to do distributed locking(fencing token)。
相关推荐
倔强的胡萝卜1 小时前
基于STM32F103C8T6的温湿度报警器设计
数据库·stm32·mongodb
Decay__9 小时前
PostgreSQL 数据库全栈运维实战系列 — 合集索引(24 篇)
运维·数据库·sql·mysql·架构
VIP_CQCRE9 小时前
GPT Image 2.6 商品图换背景后悬浮?接触阴影、透明区域与反射验收
图像处理·人工智能·ai·电商
泯泷10 小时前
别再傻傻地喂文件了,大厂都在偷偷给AI建这种“专属图书馆”
人工智能
oak隔壁找我10 小时前
一款运行在 DSH(DeepSeek Harness)中的类 Postman HTTP 接口调试插件
人工智能·程序员
高洁0110 小时前
数字孪生与计算机视觉:让机器看懂现场
人工智能·python·机器学习·transformer·迁移学习
Csvn11 小时前
如果明天供应商涨价 3 倍?三层解耦,换模型只改一行配置(C05)
人工智能·aigc·agent
zhuangzhao11911 小时前
第一性原理大模型课程 · 第 21 课:从 Prompt 到 Agent:四件套、错误累积与 ReAct 手算
大模型·react·ai agent·错误累积·大模型课程
在所不辞兄12 小时前
为什么数字孪生驱动的产线标定需要在线更新机制,而不能一次标定后长期沿用?
人工智能·神经网络·其他·算法·机器学习