多智能体协同不再复杂: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 秒后投递」。常见三种实现:
- 延迟 ZSet + promoter :到期后
XADD进流(推荐); - 消费者读到未到期消息后
sleep或重新入队(浪费投递、放大 PEL); - 外部定时器(复杂、易丢)。
第 1 种把「延迟」和「投递」解耦,故障恢复也简单:promoter 崩溃后,ZSet 里的任务还在。
2.7 消费者组没有自动 rebalance
Redis Streams 不像 Kafka 那样有 partition 分配与 rebalance 协议。任何消费者都可以用 > 读取任意新消息:
- 扩容时,新消费者自然分走一部分新消息,但旧消费者 PEL 里的消息不会自动迁移;
- 缩容时,下线消费者的 PEL 需要
XAUTOCLAIM接管; - 没有 coordinator,也没有「消费者加入即触发再平衡」;
- 空闲消费者不会自动删除,
XINFO CONSUMERS会持续累积。
工程含义:
- 消费者数量不等于吞吐。单 Stream 受单分片 CPU 与单 Key 限制,先分片再加消费者。
- 缩容前先停止读取,等待 PEL 清空;或主动把 PEL 转移给其他消费者。
- 监控每个消费者的
pending与idle,避免一个消费者持有大量未 ACK 消息。 - 不要依赖「消费者名称」做业务分片;消费组只保证消息被某个消费者读到,不保证固定映射。
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
三个关键点:
- 租约要覆盖最大执行时间,并由心跳续租 ,reclaimer 的 idle 阈值要与租约协调:
idle < lease时,reclaimer 在租约有效期内认领会看到running并放弃,恢复慢但不会并发;idle > lease时,租约可能已过期,必须依赖幂等 + fencing 防止旧 worker 继续写。无论哪种,都不能用 P99 当阈值------按定义有 1% 的任务会超过它。 - 失败不要简单删除幂等键 。如果副作用已经发生,重试可能重复下单;应进入
failed,由业务补偿或人工审核决定是否重试。 - 业务副作用仍要有自己的唯一约束。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。
正确做法:
- 持久取消标记 :
SET {tag}:cancel:{task_id} 1 EX 86400,worker 在处理前、每个工具调用边界检查; - 控制面通知:Pub/Sub 只用于「尽快通知在线 worker」,不能作为唯一取消依据;
- 超时 :
deadline_ms在执行前检查,在执行中的工具调用边界检查;不要在 Python 里强杀线程; - 清理 :取消后仍要
XACK,写入审计/死信,释放幂等租约与外部资源; - 幂等:取消与完成可能竞争,状态机用 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 下的坑
- Stream 与去重 Key 必须同槽 :用
{agent:shard:N}hash tag。 - 一个
XREADGROUP里的多个 Stream 必须同槽;跨槽会被客户端拒绝或拆分。多流场景按槽分实例读取。 - Lua 中所有 Key 必须显式声明且同槽 ;不要在脚本里用
KEYS[1] .. id动态拼 Key,Cluster 无法校验。 XINFO/XPENDING是单 Key 命令,按分片逐个查。- 热分片:按租户哈希分片,但大租户仍可能集中;对超级租户单独分片或限流。
- 故障切换可能丢最近写入 :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,长任务续租; - 有
XAUTOCLAIMreclaimer,且处理deleted返回值; -
idle_ms根据 P99 执行时间校准; - 延迟/优先级用 ZSet + promoter,搬运原子;
-
MAXLEN大于最大在途量,或先归档再裁剪; - 死信流有告警与人工处理入口;
- Pub/Sub 只用于控制面,不用于任务;
- 监控
XLEN、lag、pending、deleted、消费者 idle; - 不可丢任务有
WAIT/Outbox/落库兜底,不假设 Redis 故障切换零丢失。
参考资料
- Redis 官方文档:Streams、Consumer groups、
XAUTOCLAIM、XINFO、XPENDING、XTRIM。 - Redis 6.2 / 7.0 release notes:
XAUTOCLAIM、FUNCTION、sharded pub/sub。 - Kafka 官方文档:consumer group、offset、exactly-once semantics。
- AWS SQS 文档:visibility timeout、DLQ、FIFO。
- Martin Kleppmann, How to do distributed locking(fencing token)。