OutBox模式：解决分布式事务中本地消息可靠投递的工程实践

在分布式系统里摸爬滚打这些年我见过太多业务数据写进去了消息却没发出去或者消息发出去了本地事务却回滚了的糟心事。这类问题往往不会在测试环境暴露偏偏挑大促、秒杀、对账这些要命的时刻跳出来排查起来还特别费劲——因为日志里两边看起来都正常只是数据对不上。OutBox模式就是专门治这个病的它把改本地库和发消息这两件事绑成一个原子操作让下游系统要么收到消息、要么什么都收不到中间不存在半拉子状态。这篇内容我会从它到底解决什么问题讲起把表结构、投递链路、幂等设计、清理策略这些落地细节全部拆开适合正在做订单、支付、库存、通知这类需要数据变更即通知下游场景的后端同学参考也适合被最终一致性问题折磨过的朋友对照排查。1. 先搞清楚OutBox到底在治什么病1.1 一个真实的对账事故长什么样先说个我亲身经历的场景。某次做订单履约系统下单成功后要同时做两件事往订单库写一条记录再往消息队列发一条订单已创建的消息让库存、积分、通知几个下游去消费。代码写得很标准def create_order(order): db.insert(order) # 步骤一写本地库 mq.send(order_created, order) # 步骤二发消息 db.commit()看着没问题对吧问题出在步骤一和步骤二之间。如果db.insert执行完、mq.send还没执行时进程被kill或者mq.send抛了异常那订单数据在库里、消息却没出去库存永远不扣、积分永远不加。反过来如果先发消息再提交事务事务回滚了但消息已经投递下游就会收到一条根本不存在的订单。这就是典型的双写不一致本地数据库和消息中间件是两个独立系统没有共享事务你没法让它们一起成功或一起失败。有人会说用两阶段提交2PC啊但2PC在跨中间件场景下性能差、协调者单点、部分中间件根本不支持生产环境基本不敢用。1.2 OutBox的核心思路把消息当成业务数据一起写OutBox模式的破局点非常朴素既然本地库的事务是可靠的那就把要发的消息也当成一条业务数据和订单记录写在同一个本地事务里。这样写订单和记录待发消息天然原子——要么都进库要么都不进。具体做法是建一张额外的表通常叫outbox或者message_outbox业务写库时顺手往这张表插一条记录内容就是我待会儿要发什么消息。真正的消息投递交给一个独立的**中继Relay**组件它去轮询这张表把没发出去的消息捞出来投递到MQ投递成功后再标记为已发送。整个链路变成业务事务内写业务表 写outbox表一次commit。Relay异步扫描outbox表里未发送的记录投递到MQ。投递成功后更新该记录状态为已发送或直接删除。这样一来只要业务事务提交成功消息就一定会被Relay捞到并投递**至少一次at-least-once**的语义就成立了。至于重复投递那是下游幂等要解决的问题后面会专门讲。1.3 它和事务消息是什么关系很多人第一次接触OutBox会问这不就是RocketMQ的事务消息吗两者目标一致都是解决本地事务与消息发送的一致性但实现路径不同。RocketMQ的事务消息依赖Broker端的**半消息half message**机制先发一条对消费者不可见的半消息执行本地事务再根据本地事务结果提交或回滚半消息。它把协调逻辑放在了MQ侧对业务代码侵入小但强绑定特定MQ产品。OutBox模式则是把协调逻辑放在业务侧用一张普通表 一个Relay搞定不依赖MQ的任何特殊能力MySQL、PostgreSQL、甚至本地文件都能当outbox存储。代价是你得自己维护Relay和清理逻辑。选哪个我的经验是如果团队已经深度使用支持事务消息的MQ优先用它如果是多MQ混用、或者想保持技术栈中立OutBox更稳妥。2. OutBox表怎么设计才不给自己挖坑2.1 字段清单与每个字段的用意表设计看着简单但字段少一个后面就可能要改表。下面是我实际项目里沉淀下来的字段清单逐条说用意字段名类型作用备注idbigint / uuid主键也是消息唯一标识建议用有序ID便于扫描aggregate_typevarchar聚合类型如order、payment便于按业务分类投递aggregate_idvarchar聚合根ID如订单号下游幂等键的重要来源event_typevarchar事件类型如order_created决定路由到哪个topicpayloadtext / jsonb消息体建议存JSON别存二进制statustinyint状态0待发送、1已发送、2失败状态机核心retry_countint重试次数配合退避策略created_atdatetime创建时间扫描排序、清理依据updated_atdatetime更新时间排查问题用next_retry_atdatetime下次重试时间支持延迟重试这里有几个设计决策值得展开。主键用有序ID还是UUID如果outbox表数据量大、Relay要按顺序扫描有序ID自增或雪花能利用索引顺序读性能好很多UUID虽然全局唯一但随机写入会导致索引页分裂。payload存JSON还是序列化二进制强烈建议JSON出问题时能直接肉眼读排查成本天差地别代价只是存储稍大。2.2 状态机设计别只用已发送/未发送两态新手最容易犯的错是只设计两个状态待发送、已发送。结果一旦投递失败这条记录就卡在待发送里被无限重试或者被误判成已发送而丢失。我推荐至少三态PENDING待发送→ SENT已发送/ FAILED失败。Relay扫描时只捞PENDING和到期的FAILED。投递成功置SENT投递异常置FAILED并累加retry_count、设置next_retry_at。当retry_count超过阈值比如10次可以转入一个死信状态或者告警人工介入避免一条坏消息拖垮整个Relay。注意状态更新本身也要考虑并发。如果多个Relay实例同时扫到同一条PENDING记录会重复投递。解决办法是用SELECT ... FOR UPDATE SKIP LOCKEDMySQL 8.0、PostgreSQL支持或者乐观锁带version字段更新保证一条记录同一时刻只被一个Relay持有。2.3 索引与分区数据量上来后的保命符outbox表是典型的写多读多、且会持续增长的表。没有合适的索引Relay扫描会全表扫数据库很快扛不住。必备索引idx_status_next_retry (status, next_retry_at)Relay扫描的核心索引只查PENDING和到期FAILED。idx_created_at (created_at)清理历史数据时按时间删除。idx_aggregate (aggregate_type, aggregate_id)按业务排查时用。数据量再大比如日均千万级单表会撑不住这时候要上分区。按created_at做range分区每天或每周一个分区清理时直接DROP PARTITION比DELETE快几个数量级还不会产生大量binlog。我见过有团队用DELETE FROM outbox WHERE created_at ?清理结果大表删除锁表、主从延迟飙升血的教训。3. Relay投递链路从轮询到确认的完整闭环3.1 轮询式Relay的基本工作循环Relay是整个模式的心脏它的工作循环可以概括为捞一批、发一批、标一批。伪代码大致如下def relay_loop(): while True: # 1. 捞一批待发送记录加锁防止并发 records db.query( SELECT * FROM outbox WHERE status IN (0, 2) AND next_retry_at NOW() ORDER BY id LIMIT 100 FOR UPDATE SKIP LOCKED ) if not records: sleep(1) # 空轮询退避别把CPU和DB打满 continue for r in records: try: mq.send(topicr.event_type, bodyr.payload, keyr.aggregate_id) db.update(UPDATE outbox SET status1, updated_atNOW() WHERE id?, r.id) except Exception as e: retry r.retry_count 1 db.update( UPDATE outbox SET status2, retry_count?, next_retry_atDATE_ADD(NOW(), INTERVAL ? SECOND) WHERE id?, retry, backoff(retry), r.id ) db.commit()几个关键点批量大小LIMIT 100要权衡太小吞吐不够太大单次事务持有锁时间长空轮询退避必须有否则Relay空转会把数据库QPS打满**SKIP LOCKED**保证多实例并行时不会互相阻塞。3.2 投递语义为什么一定是至少一次Relay的投递语义天然是至少一次原因在于投递成功和标记成功之间也存在一个窗口。假设Relay把消息发到了MQ但在更新status1之前进程崩了重启后这条记录还是PENDING会被再发一次。你没法消除这个窗口除非MQ支持幂等投递事务确认但那又回到强绑定MQ的老路。所以正确的姿势是接受至少一次把去重责任交给消费端。这不是妥协而是分布式系统的常态。Kafka、RocketMQ、RabbitMQ在默认配置下都是至少一次语义下游本来就该做幂等。3.3 用CDC替代轮询更实时但更复杂轮询的缺点是延迟——取决于轮询间隔通常几百毫秒到几秒。如果业务对实时性要求高可以用**CDCChange Data Capture**方案监听数据库binlog一旦outbox表有新记录插入立刻触发投递。主流做法是用Debezium这类工具订阅binlog把outbox表的insert事件转成消息直接投递。优点是延迟低毫秒级、不用轮询、对数据库压力小。缺点是架构复杂度上升要维护CDC组件、处理binlog位点、应对schema变更。我的建议是中小规模、延迟容忍度高秒级用轮询简单可靠大规模、延迟敏感用CDC。别一上来就上CDC运维成本会让你怀疑人生。3.4 投递顺序同一聚合的消息要保序如果同一个订单先发创建再发取消下游却先收到取消再收到创建业务就乱了。OutBox表里同一aggregate_id的记录是有序的按id但Relay批量投递多线程时可能打乱顺序。保序的做法有两种一是单分区单线程把同一aggregate_id的消息路由到MQ的同一个分区/队列且Relay对同一聚合串行投递二是在payload里带版本号或序列号下游按序处理乱序的暂存等待。前者简单但吞吐受限后者复杂但吞吐高。实践中订单类业务通常用第一种因为单订单的消息量不大。4. 幂等、重试与清理三个绕不开的工程问题4.1 消费端幂等用业务唯一键兜底既然投递是至少一次消费端就必须幂等。最通用的做法是用业务唯一键做去重。比如订单创建消息消费端在处理前先查这个订单ID是否已处理过处理过就直接ack。具体实现有几种唯一索引在消费端的处理记录表上对message_id或aggregate_id event_type建唯一索引重复插入直接报冲突捕获后跳过。Redis去重用SETNX message_id做短期去重适合允许极少量重复的场景注意设置合理过期时间。状态机判断如果业务本身有状态如订单从待支付到已支付可以用状态流转的合法性来天然幂等重复消息因状态不匹配被忽略。提示幂等键的选择很关键。用message_id最精确但要求Relay把outbox的id带进消息体用aggregate_id event_type更业务化但要注意同一聚合同一事件类型是否真的只会发生一次比如订单修改可能发生多次就不能用它做幂等键。4.2 重试策略指数退避 抖动投递失败的原因五花八门MQ临时不可用、网络抖动、消息体过大被拒。无脑立即重试会把MQ打垮正确做法是指数退避 随机抖动。退避公式可以简单写成delay base * 2^retry_count比如base1秒那么重试间隔是1s、2s、4s、8s……但纯指数退避有个问题如果大量消息同时失败它们会在同一时刻集体重试形成重试风暴。所以要加抖动jitter在计算出的delay上叠加一个随机值把重试时间打散。import random def backoff(retry_count, base1, cap300): delay min(base * (2 ** retry_count), cap) return delay * (0.5 random.random()) # 50%~150%抖动设置cap上限如300秒是为了避免重试间隔无限增长导致消息迟迟发不出去。4.3 清理策略分区删除优于DELETEoutbox表的数据在投递成功后就没用了但如果不清理表会无限膨胀。清理策略有几种定时DELETE简单但大表删除慢、锁表、产生大量binlog不推荐用于大数据量。分区DROP按时间分区定期ALTER TABLE ... DROP PARTITION秒级完成几乎无锁强烈推荐。归档后删除先把老数据同步到冷存储如对象存储、数据仓库再删除适合有审计需求的场景。清理的时机要选好别在业务高峰期做。我一般配置成每天凌晨低峰期跑一次保留最近7~30天的数据取决于业务对账和排查需要。5. 落地时的几个真实坑与应对5.1 坑一业务事务里写outbox事务变长了把outbox写入放进业务事务意味着事务多了一次insert。如果业务事务本来就长比如涉及多表更新再加一次写会进一步拉长事务持有锁的时间高并发下可能引发锁等待。应对办法outbox表的写入要尽量轻。payload别存超大对象大对象放对象存储outbox只存引用索引别建太多写多读少的表索引是负担必要时把outbox表放到独立的库或实例避免和核心业务表争抢资源。5.2 坑二Relay和业务库抢连接Relay高频轮询会占用数据库连接。如果Relay和业务共用一个连接池高峰期Relay可能把连接占满导致业务请求拿不到连接。应对办法给Relay配独立的连接池或只读从库。轮询查询走从库注意主从延迟可能导致刚写入的outbox记录读不到需要评估或者至少给Relay的连接池设一个较小的上限别让它抢业务资源。5.3 坑三消息体里带了不该带的字段outbox的payload是业务方自己拼的很容易把整个实体序列化进去包括一些敏感字段手机号、身份证、金额明细。这些字段一旦进了MQ可能被多个下游消费、落盘、进日志泄露风险陡增。应对办法payload只放下游真正需要的字段敏感信息做脱敏或只传ID让下游回查。这条不是技术问题是安全意识问题但踩坑的人特别多。5.4 坑四忘了监控outbox积压outbox表里PENDING记录的数量是最重要的健康指标。如果Relay挂了或者MQ故障PENDING会持续增长业务数据在写、消息却发不出去下游数据越来越不一致。必须配的监控PENDING记录数超过阈值告警、最老PENDING记录的年龄比如超过5分钟没发出去就告警、FAILED记录数、Relay投递成功率。这几个指标一上问题基本能在影响业务前被发现。6. 什么场景该用OutBox什么场景别硬上6.1 适合的场景OutBox最适合**本地数据变更必须可靠通知下游**的场景订单创建/状态变更后通知库存、积分、物流。支付成功后通知账务、对账、风控。用户注册后通知营销、推荐、消息推送。任何需要数据改了下游必须知道的最终一致性场景。判断标准很简单如果消息丢了会导致业务数据不一致且你无法接受这种不一致就该考虑OutBox。6.2 不适合的场景反过来以下场景别硬上OutBox消息丢了无所谓比如纯日志上报、埋点丢了就丢了用OutBox纯属增加复杂度。强一致要求如果下游必须和上游实时强一致比如扣款和记账必须同时成功OutBox的异步投递满足不了得用分布式事务或同步调用。超高频、超低延迟每秒几十万条消息、要求毫秒级延迟的场景轮询式OutBox会成为瓶颈得评估CDC方案或者干脆换架构。6.3 和Saga、TCC的关系OutBox经常和Saga、TCC一起出现在分布式事务的讨论里。它们不是竞争关系而是互补Saga负责编排多个服务的补偿逻辑TCC负责资源预留和确认而OutBox负责每一步的状态变更如何可靠地通知下一步。一个完整的分布式事务方案里OutBox往往是底层的消息可靠性保障Saga/TCC是上层的业务编排。理解这层关系选型时就不会纠结到底用哪个了。7. 我踩过之后总结的几条实操心得第一条outbox表一定要和业务表在同一个库、同一个事务里。有人图省事把outbox放到另一个库那就又变成跨库双写了OutBox的意义直接归零。这是最容易被忽略、后果最严重的一条。第二条Relay的幂等和消费端的幂等要分开设计。Relay保证消息至少发一次消费端保证重复消息只处理一次两者职责不同别混在一起想。我见过有人试图让Relay做到精确一次折腾半天发现根本做不到最后还是回到消费端幂等。第三条上线前一定要做故障演练。手动kill掉Relay进程、手动断开MQ连接、手动制造投递失败观察outbox积压、重试、恢复的全过程。这套演练能暴露90%的隐藏问题比看一百遍代码都管用。第四条别把OutBox当成银弹。它解决的是本地事务与消息发送的原子性不解决消息顺序、不解决消费失败、不解决业务补偿。把它放在正确的位置上它才发挥价值。最后分享一个排查小技巧当怀疑消息丢失时先查outbox表里对应aggregate_id的记录状态。如果是PENDING说明Relay没发出去查Relay日志和MQ连通性如果是SENT但下游没收到查MQ的投递记录和消费端日志如果压根没有这条记录说明业务事务没提交成功回去查业务代码。按这个顺序查基本十分钟内能定位到问题出在哪一环。