实战｜腾讯云助手处理 SCF 死信队列故障（一）：死信日志解析与投递轨迹还原

系列导航：

• 第一篇（本篇）：事件驱动架构下的死信全景、死信原始日志结构解析、投递轨迹还原
• 第二篇：从死信日志定位业务缺陷——三类典型缺陷的归因实战
• 第三篇：安全消息重放脚本——幂等去重、限速灰度、断点续放

一、死信队列：事件驱动架构的"急诊室"

我们的订单履约链路跑在 SCF（云函数）+ 消息队列上：下单 → 订单服务 → 履约函数 → 通知函数。这套架构跑顺了很优雅，出问题了很要命——一条消息在链路上某处"死了"，没有任何界面告诉你它为什么死、死在哪。

死信产生的三大来源：

1. 消费失败：函数抛异常超过最大重试次数，消息进死信队列（DLQ）；
2. 消费超时：函数执行超过配置的超时时间被强制终止，消息进了 DLQ 但函数可能已执行一半（最危险的一类，第三篇重放的大坑）；
3. 投递失败：消息本身格式非法（schema 不符、payload 损坏），永远不可能消费成功。

麻烦在于三点：

• 死信队列里躺着的是压缩+base64 的原始消息体 + 元数据，人眼直接看基本是天书；
• 一条死信的"病历"分散在多处：队列的投递记录、函数日志、DLQ 消息体本身，没有现成的视图把它们串起来；
• 死信堆积是慢性病——每天死 20 条不痛不痒，两个月后突然发现积压 8,000 条，其中一半已经过了业务时效。

本篇解决"看得懂"：怎么把死信的原始日志解析成人类可读、AI 可分析的结构。第二篇解决"查得准"，第三篇解决"放得安全"。

二、死信日志到底长什么样

以 CKafka / CMQ 触发 SCF 的场景为例，一条死信消息的原始结构（简化）：

{"Topic":"order-fulfillment","Partition":3,"Message":"eyJvcmRlcklkIjogIk9SRC0yMDI2MDkyMS0wMDAxIiwgInNrdUlkIjogIlNLVS05O...","MsgKey":"ORD-20260921-0001","TryCount":3,"ErrorCode":"SCF_TIMEOUT","ErrorMsg":"Task timed out after 30 seconds","FirstFailsTime":1758421200000,"DeadLetterTime":1758421560000,"ClientToken":"cl-7f3a2b"}

逐字段解读（这些字段是后续 AI 分析的关键特征）：

三个第一眼容易看错的点：

1. Message里的内容不一定和业务方日志里的请求体一致——中间可能经过队列端的序列化/压缩封装，直接 base64 解码出来还是乱码的情况很常见（要先识别压缩算法，gzip/snappy/zstd 的 magic number 不同）；
2. TryCount是队列侧的重试，函数内部的业务级重试（比如代码里自己写了 for retry）不在此列——排查时两本账要分开对；
3. ErrorCode: SCF_TIMEOUT的消息可能已经执行了一半业务逻辑（写库写了一半才超时），这是重放时重复污染的高危来源。

三、让腾讯云助手解析：从天书到结构化病历

我们让腾讯云助手写的第一个工具就是死信日志解析器，输入死信消息，输出"病历卡"：

importbase64,gzip,json,iodefsniff_compression(raw:bytes)->str:ifraw[:2]==b"\x1f\x8b":return"gzip"ifraw[:1]==b"\x00":return"snappy"ifraw[:4]==b"\x28\xb5\x2f\xfd":return"zstd"return"plain"defparse_dead_letter(dlq_msg:dict)->dict:raw=base64.b64decode(dlq_msg["Message"])algo=sniff_compression(raw)ifalgo=="gzip":payload=gzip.decompress(raw)elifalgoin("snappy","zstd"):raiseNeedExternalLib(algo)# 让 AI 提示需要哪个解压库，别静默猜else:payload=raw body=json.loads(payload)return{"msg_key":dlq_msg["MsgKey"],"try_count":dlq_msg["TryCount"],"error_class":classify(dlq_msg["ErrorCode"]),"retry_window_s":(dlq_msg["DeadLetterTime"]-dlq_msg["FirstFailsTime"])/1000,"business_context":{"order_id":body.get("orderId"),"sku_id":body.get("skuId"),"event_type":body.get("eventType"),"occurred_at":body.get("ts"),},"age_hours":hours_since(dlq_msg["FirstFailsTime"]),}defclassify(code:str)->str:ifcode.startswith("SCF_TIMEOUT"):return"timeout"# 高危：可能半执行ifcode.startswith("PAYLOAD"):return"invalid"# 永久性，重放无用return"invoke_error"# 业务异常，可修可放

两个设计决策值得强调：

决策 1：压缩算法用 magic number 嗅探，不靠试错。AI 初版写的是try: gzip / except: try snappy / except: ...的连环 try——能跑，但出错时你不知道是格式不支持还是数据损坏。嗅探 + 显式报错让解析失败时的信息量完全不同。

决策 2：error_class三分类直接决定第三篇重放策略。timeout 类要按"可能半执行"处理（先补偿再重放）；invalid 类重放一万次也不会成功（进人工分析流程）；invoke_error 类修完 bug 后是重放的主力。

四、投递轨迹还原：把三个数据源串成一条时间线

单条死信的解析只是"验尸"，定位问题需要还原它生前走过的路。三个数据源：

1. DLQ 消息本身（上文结构）——死亡现场；
2. SCF 函数日志（CLS）——按MsgKey检索该消息每次触发的执行日志；
3. 业务库的操作流水——消息处理到哪一步。

让腾讯云助手做时间线拼接（提示词要点）：

你是分布式系统故障分析助手。给定三个数据源： A. 死信消息病历卡（结构化） B. 该 MsgKey 在 CLS 中的全部函数日志（含每次重试） C. 业务库中该订单的操作流水（脱敏） 任务：还原这条消息的完整生命周期时间线： 1. 消息产生 → 每次投递 → 每次失败 → 进入 DLQ，逐条带时间戳； 2. 标注每次失败发生在函数执行的第几毫秒、卡在哪个业务步骤（以日志为准）； 3. 明确指出"最后一次执行中已完成的写操作"（对重放至关重要）； 4. 输出结论三选一：永久性失败（schema/数据问题）/ 瞬时性失败（下游抖动）/ 代码缺陷（可复现）。 硬约束： - 时间线只基于给定日志，禁止推测未出现的时间段发生了什么； - "已完成的写操作"必须引用具体日志行，不确定就标 UNKNOWN。

一条真实死信还原出来的时间线（脱敏简化）：

14:20:00.128 消息产生（order-fulfillment topic, ORD-...-0001） 14:20:00.512 第 1 次投递 → 函数启动 14:20:12.903 日志：库存预占成功（DB 写入 #1） 14:20:30.001 函数超时被杀（30s），未走到"发货单创建"步骤 14:23:00.311 第 2 次投递（重试） 14:23:12.500 日志：库存预占再次执行（DB 写入 #2 ← 重复！） 14:23:30.002 再次超时 14:26:00.xxx 第 3 次投递 → 同样模式 → 进入 DLQ

这条时间线一眼暴露两个问题：库存预占逻辑不幂等（重试导致重复预占）+下游发货接口偶发慢（每次都卡在 12 秒后）。前者是第二篇的主题（业务缺陷定位），后者是容量问题。而"已完成的写操作 = 3 次库存预占"这个事实，直接决定了第三篇重放脚本必须先做补偿再重放。

五、本篇小结

1. 死信三大来源里，TIMEOUT 类最危险——函数可能半执行，重放前必须搞清它写过什么；
2. 死信消息体要经过 base64 + 压缩双层解码，压缩算法用 magic number 嗅探而非连环 try；
3. error_class三分类（timeout / invalid / invoke_error）直接决定重放策略，解析时就要分好；
4. 投递轨迹还原要把 DLQ、函数日志、业务流水三个源串成时间线，AI 提示词的硬约束是禁止推测 + 不确定的写操作标 UNKNOWN。

下一篇用 4 个真实死信案例讲业务缺陷定位：非幂等写、异常吞噬、消息 schema 漂移、下游限流雪崩——每个案例都从死信日志的特征字段讲起。

做事件驱动架构的同学欢迎评论区交流你们的 DLQ 积压现状。