该指南介绍 Sentry 的 hybrid cloud outbox 机制:数据变更与 outbox 行在同一数据库事务内写入,事务提交后排空 outbox 并触发 RPC、墓碑传播或审计日志等副作用。常见用途是跨 silo 复制(CellOutbox 从 Cell 推向 Control,ControlOutbox 从 Control 按 cell_name 推向一个或多个 Cell),也适用于事务提交后需可靠执行的任意操作。
主要能力与约束:必须与数据变更同事务写入,模型混入 ReplicatedCellModel/ReplicatedControlModel 会通过 prepare_outboxes() 自动处理;处理器必须幂等,因可重试且被合并,只保证最新载荷送达;drain_shard() 不得在事务内运行;每个 OutboxCategory 须注册到恰好一个 OutboxScope,否则导入报错;批量操作须用 CellOutboxProducingManager/ControlOutboxProducingManager,原始 queryset 不创建 outbox;雪花 ID 模型不能用 bulk_create。
使用方式分步:为新模型加复制、新增 OutboxCategory、手写信号接收器、迁移既有模型、配置回填、用 outbox_runner() 等工具测试、排查卡住 outbox。Control 模型需实现 outbox_cell_names() 选定目标 cell。
适用场景为 Sentry 混合云跨 silo 最终一致性复制;限制在于幂等要求、合并语义与事务边界,具体回填与调试细节见 references 文档。