分布式 on Renxin's Blog

第六话｜数据的存与算：Doris 的架构与机制

Fri, 18 Sep 2026 00:00:00 +0000

笔者在工作中同时使用过 MySQL 和 Doris。MySQL 是事务型数据库，面向 OLTP（Online Transaction Processing）场景——比如订单处理、用户登录、库存扣减这类需要高并发、低延迟、强一致性的业务操作。Doris 是分析型数据库，面向 OLAP（Online Analytical Processing）场景——比如用户行为分析、销售报表、数据仓库这类需要扫描大量历史数据、按维度聚合统计的分析需求。

Doris 最早是百度在 2017 年开源的（当时叫 Palo），后来捐赠给 Apache 基金会，定位为高并发、低延迟的 MPP（Massively Parallel Processing，大规模并行处理）分析型数据库。它不是 MySQL 的升级版，而是从存储到计算都为分析场景重新设计的系统。这篇文章以 MySQL 为参照系，讲 Doris 的架构与原理。

版本与口径：下面的机制都以 Apache Doris 2.1.x 为准，出自 2.1 官方文档；涉及真实生产使用的地方标【生产经验】。3.x 起的存算分离形态不在此文讨论范围。

一、两种负载：OLTP 与 OLAP

以订单表 orders（字段：order_id BIGINT（主键）, user_id BIGINT, region VARCHAR, category VARCHAR, amount DECIMAL, status VARCHAR, created_at DATETIME，几百万行）为例。

业务后端每秒执行的是这类查询：

SELECT order_id, status FROM orders WHERE order_id = 1024;
UPDATE orders SET status = 'paid' WHERE order_id = 1024;

单次查询只涉及一行，走 order_id 索引，毫秒级返回。

分析师每月执行的是这类查询：

SELECT region, category, SUM(amount)
FROM orders
WHERE created_at >= '2026-08-01' AND created_at < '2026-09-01'
GROUP BY region, category;

需要扫描几百万行、按区域和类目分组求和，最后只返回几十行。扫描范围大，聚合计算重。

两者需求差异显著。数据库领域用两个术语区分：

OLTP（Online Transaction Processing，在线事务处理）：处理「单行数据的正确提交」。重点是事务、并发、单行性能。业务系统普遍采用。
OLAP（Online Analytical Processing，在线分析处理）：处理「大量数据的扫描与聚合」。重点是扫描、聚合、吞吐。报表和数据分析场景的首选。

主要差异体现在以下几个方面：

维度	OLTP（MySQL 的主场）	OLAP（Doris 的主场）
典型操作	单行/小批量的读取与更新	全表/大范围的扫描与聚合
访问方式	走索引点查，一次命中目标行	只读用到的列，跨大量行扫描
并发	高并发，大量短事务	大查询少，但单个查询计算量大
一致性	强一致，ACID 事务，出错可回滚	单批导入原子可见；几乎不做交互式跨行/跨表强事务
写入	随时小量写，靠行锁保证并发正确	攒批后大批量导入
指标	每秒事务数（TPS）、单次延迟	每秒扫描行数、整批处理吞吐
数据形态	当前状态（正在处理的订单）	长期历史（几个月到几年的明细）

InnoDB 适合 OLTP，主要在下面这几处：

存储结构：InnoDB 把整张表按主键组织成一棵 B+ 树（聚簇索引）：叶子节点就是存放数据的页（Page，默认 16KB，落在表空间文件 .ibd 里），每行的各列连续存在同一页内，主键即索引、索引即数据。

查询执行：InnoDB 维护一个缓冲池（Buffer Pool），把频繁访问的页缓存在内存中。执行 WHERE order_id = 1024 时，沿根节点 → 中间节点 → 叶子页逐层向下，走过的页数等于 B+ 树高度（几百万行通常 3 层左右）；根节点和上层索引页一般已命中缓冲池，真正落盘的往往只有叶子页那一次，再从中取出目标行。

二级索引：主键之外的列也建 B+ 树，叶子只存「索引列 + 主键值」，命中后回聚簇索引取整行，这就是回表。联合索引只能按最左前缀用：WHERE col1 = 1 AND col2 = 2 能用 (col1, col2) 索引，WHERE col2 = 2 则不行（官方手册：只有左前缀能被优化器用于查找）。

事务与并发：行级锁只锁被改动的行（官方特性表：锁粒度是 row）；多版本并发控制（MVCC）用回滚日志（undo log）保留旧版本，让读不阻塞写。默认隔离级别可重复读（REPEATABLE READ），保证同一事务内前后读取一致。

水平扩展：InnoDB 本质是单机存储引擎，一张表的数据完整在一个实例里，引擎自身不做单表分片（官方特性表：InnoDB 的 Cluster database support 为 No）。要多机承载，只能靠主从复制做高可用与读写分离，或靠中间件分库分表——都不是 InnoDB 单表原生的水平扩展。

分析查询在 MySQL 上的表现，可以逐条对应：

索引失效，只能全表扫描：报表常按日期、状态、类目这些列过滤分组，往往跟主键顺序对不上，B+ 树的快速定位用不上，只能逐页读取所有叶子页。
行存读取整行数据：一行所有列连续存放在同一个页内。即使只查询 amount 字段，也需要将整个页读入缓冲池。
分组、排序需要额外开销：当聚合或 ORDER BY 无法用索引顺序直接满足时，MySQL 要借助内存或临时磁盘文件做排序、分组（官方管这类操作叫 filesort）。
计算资源受限于单机：所有查询共享同一个实例的 CPU、内存和缓冲池。分析大查询会挤占缓冲池空间，影响其他查询的性能。

一条聚合查询可能同时触发多个瓶颈：全表扫描占用大量缓冲池 + 逐页读取产生大量磁盘 I/O + 排序/分组占用内存或临时文件 + 长时间占用实例资源。这是生产环境中「报表查询导致主库 CPU 告警」的典型场景【生产经验】。

边注：MySQL 在隔离级别设计上也考虑了报表场景。官方文档在说明降低一致性以提升性能时，以批量报表为例。MySQL 对分析查询的特性有清晰认识，但其设计优先级是事务处理。

Doris 是分布式的 MPP 分析型数据库，节点分两类：FE（Frontend）与 BE（Backend）。两类节点都多节点部署以消除单点，对外通过兼容 MySQL 协议的接口接入查询（官方架构文档）。这和 MySQL 相反：MySQL 的解析、优化、存储、执行全部在单个实例的进程内完成，也不做这种角色拆分。

FE（Frontend）：接收连接、解析并规划查询，并管理集群的元数据。库、表，以及分区、分桶这样的数据分布与副本位置——这一整套元数据只保存在 FE，并持久化到 FE 本地（每次元数据变更顺序写进 edit log，周期性把整份内存元数据落成 image 快照，重启时按快照加日志回放恢复）；BE 只存数据本身；节点存活与副本状态由 FE 负责心跳检测与副本修复。FE 分 Master、Follower、Observer 三种角色：Master 写元数据并调度副本，Follower 同步元数据、可在 Master 故障时接替，Observer 只读以分担读压力，多个 FE 由此保证管理层高可用。

BE（Backend）：真正存数据、算数据的一方。数据分片以列存文件落在 BE 上、各存多副本；BE 执行 FE 下发的计算算子（扫描、聚合等）。计算是向量化执行——一次处理一批列数据而不是逐行处理（官方口径：列式内存布局 + SIMD 加速）；并以 Pipeline 方式调度，把查询切成可由有限线程轮转执行的任务，避免一个查询占满线程。

存算一体：在 2.1 里，存储与计算发生在同一台 BE 上——数据分片存在哪台 BE，相关计算就在哪台 BE 上做，不必先把数据搬到别处（3.x 起的存算分离不在本文范围）。

数据分布：Doris 把一张表分两级切开。第一级是分区（Partition），常按时间这类列做 Range 划分——比如 orders 表按 created_at 每月一个分区，查询限定在某段时间时只扫对应分区、其余跳过。第二级是分桶（Bucket），在分区内再按某个键取哈希打散——比如按 order_id 哈希分成若干桶。两级切到最后，每个桶就是一个 tablet：它是 Doris 存数据、做副本、调度（迁移与均衡）的最小单位。于是一张表被摊成「若干分区 × 每分区若干 tablet」，分布到多台 BE 上、每台各管一部分，tablet 又各存多副本（默认 3 副本）以防节点宕机丢数据——这是 InnoDB 单实例没有的能力，Doris 由引擎自己把单表分布出去。

列式存储：tablet 内部按列存放，查询只读用到的列、跳过无关列，不像行存那样即使只用一列也要把整行读进来。

MPP 并行：Doris 把一个查询切成执行片段，下推到持有相关 tablet 的多个 BE 上并行扫描、聚合，最后汇总，而不是由单台机器串行执行完。

二、数据的存：tablet、列存与版本合并

一条数据从导入到可查询，在 Doris 里走的路径是：按分区、分桶落到某个 tablet；以列存格式写成一个不可变的 rowset，里面是一个个 segment 文件；tablet 的多副本分布在不同 BE 上；多数副本写入成功后，FE 提交事务，数据对外可见。此后每次导入都追加新的 rowset 和版本，由后台的 Compaction 把版本收敛回去。查询则反向使用这些结构：先裁剪分区，再用前缀索引定位数据块，最后只读所需的列。

tablet：数据落在哪台 BE 上

第一章说过，一张表先按分区、再按分桶切开。落到存储层，官方给的关系式是：Tablet 数 = 分区数 × 桶数 × 副本数。以 orders 表为例：按 created_at 每月一个分区、按 order_id 哈希成 10 个桶、默认 3 副本，那么每个月就是 10 × 3 = 30 个 tablet，分散在不同 BE 上。tablet 是 Doris 存数据、做副本、做调度迁移的最小单位——副本往哪台机器放、哪个副本坏了要补，都以它为单位。

这三个乘数落在建表语句里就是三行，本章后面反复用到的这张表长这样：

CREATE TABLE orders (
 created_at DATETIME NOT NULL, -- 排序键第 1 列
 region VARCHAR(32), -- 排序键第 2 列
 category VARCHAR(32), -- 排序键第 3 列
 order_id BIGINT NOT NULL, -- 只做分桶列，不在排序键里
 user_id BIGINT,
 amount DECIMAL(10, 2),
 status VARCHAR(16)
) ENGINE = OLAP
DUPLICATE KEY(created_at, region, category) -- 排序键：必须是列定义的前 K 列
PARTITION BY RANGE(created_at) ( -- 分区：决定去哪个分区
 PARTITION p202608 VALUES [("2026-08-01"), ("2026-09-01"))
)
DISTRIBUTED BY HASH(order_id) BUCKETS 10 -- 分桶：决定落在哪个 tablet
PROPERTIES ("replication_num" = "3"); -- 副本：每个 tablet 存 3 份

注意列的顺序和第一章那张表不一样：created_at、region、category 提到了最前面——不是排版偏好，排序键只能取列定义的前 K 列。分区、分桶、副本三行各给出一个乘数，上面这一个分区就是 10 × 3 = 30 个 tablet；SHOW TABLETS FROM orders 能把这 30 个逐条列出来，含每个副本在哪台 BE、当前版本、行数和大小。本文写作时在单机 Docker 里跑的就是这张表，单台 BE 只能存一份副本，那一行写的是 "1"，tablet 数相应是每分区 10 个——其余行为与 3 副本一致。

桶数不是随手填的。官方建表最佳实践的参考指标是：单个 tablet 的数据量保持在 1G–10G。太小（桶切得过碎），每片都要单独写文件、单独记元数据，聚合效果差、FE 的元数据管理压力也大；太大（桶不够多），副本迁移和补齐的代价高，改表结构（Schema Change）、建物化视图这类要重写数据的操作，失败重试的代价也跟着单个 tablet 变大。维表这类小表，官方建议 tablet 数控制在 3–5 个，既保住一定并发，又不制造小文件。分区列方面，官方建议事实表用 date/datetime、一般每日一个分区（本例按月是为了数字好算），缓慢增长的维表可以单分区。分桶列要选高基数（取值种类多）且分布均衡的列，比如 order_id；选了低基数列，数据会挤在少数几个桶里，等于白分。不想绑定某个键时也可以用 RANDOM 分桶（不指定分桶列、随机撒），官方口径是它适合整体聚合分析、不适合高并发点查。

segment：按列存放与编码

官方把 tablet 内部的存储层级概括为 Tablet → Rowset → Segment → Column → Page，它们各自的用途是：rowset 是一次导入产出的文件集合；segment 是 rowset 里真正装数据的文件，一个 rowset 可以有一个或多个；column 指 segment 内每一列单独组织，同一列的值连续排在一起；page 是把一列的值按约 64KB 切出的小块，它是读取和压缩的最小单位——查询要么整页跳过，要么整页读进来解压。

按列存放带来的第二个好处是：同一列的相邻字节长得很像，可以针对性地换一种更省的记法，这就是编码。行存做不到这点——一行的各列挤在一起，相邻字节一会儿是字符串、一会儿是金额、一会儿是时间，没有规律可榨。编码和压缩是两道工序：编码挑一种适合这一列数据规律的表示方式，压缩在编码后的字节流上再跑一道通用无损压缩。Doris 按列的类型和取值分布自动挑编码：

编码	适合什么样的列	省在哪
PLAIN	没有规律可榨的列（官方口径：一般数值）	原样存
DICT（字典）	低基数列，即不同取值很少（`status` 只有几个状态、`region` 只有几十个地区）	建一张「值 → 编号」字典，数据里只存短编号，不再重复存整个字符串
RLE（游程）	连续重复值多的列（官方举的例子是布尔列）	记「值 + 连续出现次数」，而不是把同一个值写很多遍
BIT_SHUFFLE	整数列（`order_id`、时间戳）	把所有值的第 1 个字节放在一起、第 2 个字节放在一起；整数高位往往相同，于是相同字节连成大片，后面压缩特别有效
FOR（frame-of-reference，基准值）	日期列	只存「减掉一个基准时间后的差值」，用更少的位表示

编码之后才轮到通用压缩，默认 LZ4F，可以换成 ZSTD 等，官方给的口径是 ZSTD 典型能把表压到原来的 1/5 到 1/10；反过来，一道 page 压缩后省不到 10%，Doris 就干脆不压，免得解压白烧 CPU。

收益直接落在读取上：查询只碰涉及列的 page，表越宽、查询涉及的列越少，省得越多。每个 page 带一份 zone map——这一页该列的最大值、最小值、是否含 NULL，条件跟这个范围不沾边的页不解压就整页跳过，这一份是内建的、每列都有。等值查询还想跳得更狠，就得自己加索引了：bloom filter 索引不是自动的，要在建表属性里点名（"bloom_filter_columns" = "user_id, order_id" 这类写法），Doris 才为这几列逐 page 各建一个 bloom filter。有了它，= 和 IN 就能先问一句「这一页里可能有这个值吗」，回答「肯定没有」的页直接跳过。bloom filter 只有假阳性、没有假阴性，说「没有」就是真没有，所以拿它跳页是安全的；代价是对高基数列（user_id、订单号这类）跳过率高，对低基数列基本没用，Tinyint、Float、Double 三类还建不了。属性一旦写上，查询用到时自动生效、SQL 不用改写法，但它对 = 和 IN 之外的条件不帮忙。

代价也要如实说：取一整行要把所有列各读一次，每列一次独立 I/O，官方文档直言宽表按主键点查会付出 N 倍 I/O，高频 SELECT * 点查是列存的弱项。

排序键与前缀索引：tablet 内部怎么找到那一段数据

一提到索引，从 MySQL 过来的人默认是 B+ 树：多层节点、叶子之间互相串联、每个二级索引各是一棵树、按查询条件一个个建。Doris 的前缀索引形状简单得多，也单薄得多，它就是一份排好序的定长数组，每项存两样东西：一小段拼接起来的排序键值，和这一段值所在的起始行号。查找时在这个有序数组上二分，定位到目标值落在哪一块，拿到起止行号，其余块不读。它不长成树，也不为每个查询条件各建一套——一张表只有这一套，代价是能力比 B+ 树窄很多。

它挂在「行」这个维度上，容易和上一节的 page 混：page 是一列的值按 64KB 切出来的，每列各切各的；前缀索引的逻辑数据块是按行数划的，跨所有列共同。两者粒度不重合。

排序键就是建表时 Key 子句里那几列，官方明确 Key 列必须是表定义的前 K 列（从第一列开始连续声明），单个 tablet 内的数据按这几列整体排序。有序是这一切的前提：一个条件对应的行必然连续成一段，才谈得上「记住每段起点、只读那一段」；无序就只能是全读之后逐行判断。官方对这套存储结构的说法是「类似 SSTable」——按键有序、写完不改、后台合并的不可变文件格式，Java 生态里 RocksDB、LevelDB、HBase 用的都是这一类。

数组每项存的那段值叫短 key（short key），取法是把排序键按声明顺序拼接，累加到 36 字节为止。上限只到 36 字节，是为了让整份索引小到能常驻内存：一亿行按每块若干行算下来仍有几万条索引项，每项再宽就成了查索引本身要扫一遍的大对象。每块到底多少行，2.1 的文档只写了「按行数划成逻辑数据块」，没给具体数字，这里也就不猜。碰到变长列时规则收紧：VARCHAR 可以进短 key，但只截取它自己的头几个字节，且到此为止，后面的列一概不再进入前缀索引。官方给的两组数正好说明这条的分量：

user_id BIGINT, age INT, message VARCHAR(100)：短 key = user_id 的 8 字节 + age 的 4 字节 + message 的头 20 字节，凑满 36；
user_name VARCHAR(20), user_id BIGINT：短 key 只有 user_name 这 20 字节，没到 36 也停，因为 VARCHAR 之后的 user_id 已经进不来了。

对照 tablet 那节贴出的建表语句还有一个容易找错地方的地方：整份 DDL 里找不到「前缀索引」这个词，也没有任何子句能调它——短 key 完全由 DUPLICATE KEY(created_at, region, category) 那一行推出来，排查「我的前缀索引建成了什么样」时，要看的是表定义，不是索引列表。

这条规则决定了 Key 的排列纪律，也就是最左匹配的实际含义：条件里出现排序键连续的前几列才走得通前缀索引，跳过中间一列，后面的列就匹配不上——这一点和 MySQL 的联合索引同构，直觉可以照搬。所以官方的建议是把最常过滤的定长列（尤其时间列）排在最前面，且不必贪多，超过三四列基本是白写。

这条纪律落到 orders 表上有个不好听但必须说的结论。前面把它排成 created_at、region、category，created_at 是 DATETIME、定长，进得来；region 是 VARCHAR，只能以头几个字节的形式参与；category 则完全不在前缀索引里，WHERE category = 'food' 走不到它。也就是说这条查询从前缀索引得到的只有时间那一段。剩下两段要靠对某一列单独建的索引来补。另外，排序键放这三列不干涉分桶：明细模型不要求分桶列与 Key 列一致（那是聚合、主键模型的约束），分桶仍然可以用 order_id。

Key 在聚合和主键模型里还兼作聚合键、去重键，那是另一层语义；本章只用到它的排序作用。前缀索引到底过滤掉多少行，可在查询 profile 的 RowsKeyRangeFiltered 指标里核对。

索引体系：哪些内建，哪些要自己建

上一节那份前缀索引是自动来的，建表时不用写任何东西。Doris 还有几种索引必须你点名，实际用表时最常碰到的就是「给某一列开 bloom filter」这类设置。它们和自动的那两种放在一起是这样：

索引	建在哪些列上	作用粒度	怎么建	只加速什么
前缀索引	排序键（Key）的前 36 字节	每个逻辑数据块一项	内建，自动	覆盖连续最左前缀的等值、范围条件
ZoneMap 索引	所有列，无一例外	每个 page 一份 min / max / 是否含 NULL	内建，自动	等值、范围、`IS NULL` 的整页跳过
BloomFilter 索引	你点名的若干列	每个 page 一个	表属性 `bloom_filter_columns`	只有 `=` 和 `IN` 的整页跳过
NGram BloomFilter 索引	你点名的字符串列	每个 page 一个	`INDEX ... USING NGRAM_BF`，可配 `gram_size`、`bf_size`	只有字符串 `LIKE '%…%'` 的整页跳过
倒排索引	你点名的字符串、数值、日期、数组列	值或词项 → 命中的行号	`INDEX ... USING INVERTED`	等值、范围、关键词匹配，能定位到行

这条分界决定了你能优化什么。内建的两种没得选，能调整的只有「数据按什么顺序排」，也就是上一节；要自己建的三种是在排序之外再为个别列补一份结构，所以选择全在「给哪一列、建哪一种」上，代价也全在这里——每补一份，这一列就多占空间、每次写入都要跟着维护，所以每一种都把自己限制在能真正省下读取的那几种条件上，表里「只加速什么」那一栏写的就是这条边界。

要自己建的这三种里，前两种属于跳数索引（skip index，ClickHouse 里同名同义的那个说法）。它不告诉你数据在哪，只对「这一页」回答一个是或否：这里头肯定没有，于是整块跳过。所以它的收益完全取决于数据分布和条件形状。分析型扫描的瓶颈通常是「读了太多不相关的页」而不是「找不到那一行」，这也是分析型表不必像 OLTP 那样按查询模式铺一串二级索引的原因——ZoneMap 是同一思路的内建版本，BloomFilter 是你手动加强的那一版。加强版也有自己的边界：BloomFilter 只对高基数列有意义，低基数列（只有几个取值的 status）几乎每页都含目标值，一个也跳不掉；Tinyint、Float、Double 这三种类型官方直接不让建。

BloomFilter 只认完整值，所以帮不了模糊查询。NGram BloomFilter 补的就是这个洞：把字符串按 N 个连续字符滑窗切开，shanghai 在 gram_size = 3 时切成 sha、han、ang、ngh、gha、hai 这一串片段，每个片段作为一个值塞进这一页的 BloomFilter；查询 LIKE '%ang%' 时把 ang 也照切一遍，逐个问「在不在过滤器里」，只要有一个不在，这一页就整块跳过。官方那条限制由此而来——LIKE 里连续的字符数要够到 gram_size，短于 N 就切不出一个完整片段，索引无从问起。它和上一段那个按完整值建的 BloomFilter 抢的是同一个位置，同一列上两者只能有一个。

倒排索引是这几种里能力最宽的，因为它不走「跳过整块」那条路，而是直接给出哪些行命中。「哪些行含某个值」这张表按值组织，等值、范围、IN / NOT IN 都查得动它，数组列可以按元素过滤。字符串列加上分词器才有全文能力：parser 取 english / chinese / unicode，中文还能选 fine_grained（细粒度）或 coarse_grained（粗粒度）；之后 WHERE 里可以写 MATCH_ANY（含任一关键词）、MATCH_ALL（每个关键词都得有，不管顺序）、MATCH_PHRASE（这些词得挨着、且按这个顺序出现）。它也有建不了的时候：聚合模型，以及没开 Merge-on-Write（主键表的一种写入模式，写入时就把同键的行合并掉）的主键表，只有 Key 列能建倒排索引；FLOAT、DOUBLE 因为精度问题不支持。BITMAP 索引官方说已被倒排索引取代，不必再单独学。

它到底能快多少，官方给的对比是关键词检索比等价的 LIKE '%…%' 快 7–13 倍，样本是一百万行 HackerNews 数据，同一份数据建索引本身花了一两秒——这两个数得一起看才知道量级。这个量级我在本地一套单 FE、单 BE 的 2.1.11 上复现过：三百万行，title 平均 121 字节、合计约 363 MB，八个桶，其中 1% 的行含一个生造词。同一个条件，WHERE title LIKE '%那个词%' 的服务端耗时稳定在 36–54 ms，写成 MATCH_ANY 是 5–6 ms，约 7 倍。另外两个对照数才说清这钱花在哪：把 LIKE 里的词换成一个必然不命中的，耗时不变，还是 33 ms，和强制把整列扫一遍的 sum(length(title))（29–35 ms）基本相等——LIKE 的成本就是全列扫描的成本，跟命中多少无关；而把关键词换成每行都出现的 doris，LIKE 28 ms、MATCH_ANY 12 ms，差距缩到两倍出头：命中面铺满时，索引省下的扫描抵不掉它为命中行逐个产出行号的开销——后半句是按机制推的，我测到的只有那两个数本身。倒排索引的收益来自命中少，不是无条件快，选列的时候这条比任何倍数都重要。

最后是怎么补上去。三种索引的建法长在三个不同的地方，对照着 orders 表看一眼就分清了：

-- BloomFilter：表属性，列名列表。没有这一行，这一列就没有 bloom filter
ALTER TABLE orders SET ("bloom_filter_columns" = "user_id, order_id");

-- NGram BloomFilter：INDEX 子句，只服务字符串列的 LIKE
CREATE INDEX idx_region ON orders (region) USING NGRAM_BF
 PROPERTIES ("gram_size" = "3", "bf_size" = "1024");

-- 倒排索引：同一个 INDEX 子句换一种类型；事后加的要对已有数据补建一次
CREATE INDEX idx_status ON orders (status) USING INVERTED;
BUILD INDEX idx_status ON orders;

第一条是表属性，所以它不会出现在任何 CREATE INDEX 里；后两条是 INDEX 子句，ALTER TABLE orders ADD INDEX idx_status (status) USING INVERTED 与 CREATE INDEX 等价。字符串列要做全文检索，再在 PROPERTIES 里加 "parser" = "chinese" 这类分词器，纯等值和范围过滤不用加。

这里有个容易踩的坑。改 bloom_filter_columns 不是改一行元数据就完事，Doris 会为它起一个 schema change 作业——所谓 schema change 是 Doris 的在线改表流程：数据是一个个不可变文件，改结构就得由 FE 调度、BE 把这些文件重写或补齐，所以它是异步的。在 2.1.11 上，改完立刻到 SHOW ALTER TABLE COLUMN 里能看到一个 PENDING 的作业，表停在 SCHEMA_CHANGE 状态，这期间再发 CREATE INDEX 会被直接拒掉（Table[orders]'s state(SCHEMA_CHANGE) is not NORMAL），作业跑完属性才生效；小表是几秒，大表就是分钟级的事。倒排索引建完还要对已有数据跑一次 BUILD INDEX，漏了这一步，只有新写入的数据带着索引。

核对的时候还有一处容易找错：SHOW INDEX FROM orders 只列 INDEX 子句建的东西（上面两个 INVERTED、那个 NGRAM_BF），bloom_filter_columns 不在里面，得回 SHOW CREATE TABLE orders 看表属性。

物化视图：把聚合提前算好

索引省的是「读」，还有一类开销索引帮不上：同样的聚合，每次查询都重算一遍。报表每天按地区、类目出一次销售额，明细有几亿行，每天都要把这几亿行重扫重聚一次。物化视图的思路是把这类查询的结果提前算好存下来，查询来了直接取。Doris 2.1 里它有两种形态，分界在「谁来维护这份预计算数据、什么时候维护」。

同步物化视图：跟着导入走。建法是一条 CREATE MATERIALIZED VIEW，定义里只写想提前算什么：

CREATE MATERIALIZED VIEW mv_region_amt AS
SELECT region, category, sum(amount)
FROM orders
GROUP BY region, category;

本文在 2.1.11 上对 orders 表执行，SHOW ALTER TABLE MATERIALIZED VIEW 里能看到一个 FINISHED 的作业，输出里有一栏 RollupIndexName——它的实现就是基表上的一个预聚合副本，导入时同步更新，官方的口径是「只有同步完成后，相关命令才会结束」，无需人工维护。代价也在这里：每一张同步物化视图都让导入多写一份、多聚一次，官方直言单表上物化视图过多会拖慢导入。

它生效的方式是透明改写：查询照常写基表的名字，Doris 自动匹配能否用物化视图回答。把上一节那条不带时间条件的聚合拿来 EXPLAIN，扫描节点显示 TABLE: demo.orders(mv_region_amt)——语句里写的是 orders，实际读的是物化视图。验证命中与否看的也是 EXPLAIN，文档把改写结果分了三种标记（MaterializedViewRewriteSuccessAndChose 命中且选用、MaterializedViewRewriteSuccessButNotChose 命中但按成本未选、MaterializedViewRewriteFail 未命中），排查「为什么没命中」时到计划里找它们。

透明改写有一条本文实测撞出来的边界。同一条聚合加上 WHERE created_at >= '2026-08-01' AND created_at < '2026-09-01' 之后，计划回落到基表：这份物化视图里没有 created_at 这一列，带时间条件的查询它回答不了。提前算好的口径必须盖得住查询的过滤条件——分组列决定哪些谓词能落到这份预计算数据上，建视图时把常用于过滤的列一并考虑，否则存储白付、改写永不命中。它的能力边界也来自同一个原因：只支持单表（官方明确不支持 JOIN），聚合形式限于 sum 这类常规聚合和 bitmap_union（用它可以把 count(distinct) 变快，官方给的标准做法）；它也不像普通表那样能直接 SELECT——本文实测对它查询返回 Unknown table，这是它与异步物化视图最直观的一个区别。

异步物化视图是 2.1 引入的另一种形态：它自己就是一张内表（底层是 Duplicate 模型），定义里可以写多表 JOIN，基表模型不限，数据靠创建时注册的刷新任务重算。本文实测的一条：

CREATE MATERIALIZED VIEW amv_orders_region
BUILD IMMEDIATE REFRESH AUTO ON MANUAL -- 创建即构建；手动刷新
PROPERTIES ("replication_num" = "1") -- 单 BE 环境的限制，多 BE 集群不必写
AS SELECT region, sum(amount) AS amt, count(*) AS cnt
FROM orders GROUP BY region;

建完 10 秒内直接 SELECT 已有数据。刷新方式三种，写在建表语句里：ON MANUAL 手动触发（REFRESH MATERIALIZED VIEW … AUTO）、ON SCHEDULE 定时（EVERY 2 HOUR 这类）、ON COMMIT 基表数据一变就刷。它同样支持透明改写（官方称基于 SPJG——SELECT-PROJECT-JOIN-GROUP-BY——模式的改写算法），代价是数据与基表最终一致：官方口径是「无法实时同步」，通常用于对时效性要求不高的场景，「一般是 T+1 的数据」。

两种形态的选型其实是三个问题：口径是单表还是多表——单表才能用同步，多表只能异步；结果要实时还是容忍延迟——导入即更新是同步的语义，异步是最终一致；写入放大付在何时——同步的每个导入都多写一份，异步把代价挪到刷新时刻。它和聚合模型的关系也在这里收拢：聚合模型在建模时就锁定了数据的聚合口径，物化视图是在已有表上给某几个固定口径补一份预计算——两者都是拿空间和写入换查询时间。索引省下的「读」，物化视图省的是「算」。

每次导入产生一个新版本：rowset

Doris 的写入属于 LSM 树那一套路子：写操作从不原地修改已有文件，每次导入产生一个新的、不可变的 rowset，带一个版本号。于是一个 tablet 的数据就是一串按版本排开的 rowset。

代价落在读取上：查询要把这些 rowset 在读取时合并起来看——新版本、被删掉的旧版本，都靠版本号和删除标记判断，这就是读时合并。rowset 少时无所谓，但 Stream Load、Group Commit 这类高频导入会让版本数涨得很快。官方给了硬限制：单 tablet 版本数超过 max_tablet_version_num（默认 500）后导入直接失败，报 -235，官方自己说这是用户群里最常见的生产事故之一。版本堆积还有两笔账：查询要合并的路径变长；被删除的行不会立刻消失，它们以 tombstone（删除标记） 的形式留在旧 rowset 里，每次读都要额外过滤。

Compaction：把版本收敛回去

把一串小 rowset 合并成少数几个大 rowset 的后台动作就是 Compaction。理解它的关键是一条分界线 cumulative point：cumulative compaction 高频、轻量，只合并 cumulative point 以上的新进小 rowset，先把刚灌进来的碎片归拢；base compaction 低频、重量，把 cumulative point 以下的所有 rowset 合并成一个 base rowset（这个 tablet 的底座数据）。cumulative 的合并结果一旦超过 promotion size（默认 1GB），下一轮就有资格并进 base。

BE 给每个 tablet 打一个「乱」的分数来决定先合并谁，分数大致等于查询在这个 tablet 上要走的合并路径数，谁最乱先处理谁。合并完成后，读时合并的路径变短、小文件数回落、tombstone 也随旧 rowset 一起被清掉。

副本：多数派成功才算成功

导入时，数据并行写入各副本所在的 BE，每个 BE 写完后向 FE 确认。FE 统计成功写入的副本数，超过总副本数的一半即视为导入成功——三副本的表，至少 2 个副本写成功。随后 FE 提交导入事务，数据对外可见，这就是第一章说的「单批导入原子可见」的由来。

没写成功的副本不会永久缺数据，由后台异步复制补齐，最终各副本一致；副本的检测与修复由 FE 负责，就是第一章「节点管理」那条职责。

查询怎么用这套结构

回到第一章那条聚合查询。它在存储层依次经过三道收缩：

分区裁剪：created_at 的范围条件把扫描目标收窄到 8 月这一个分区，其余分区不碰。这一步 EXPLAIN 里看得见：这条查询的计划里写着 partitions=1/3 (p202608)，三个分区只有这一个进了扫描范围；
前缀索引：排序前缀把分区内的扫描范围缩到少数数据块；
列裁剪与 zone map：只读 region、category、amount 三列的 page，zone map 再把条件不沾边的 page 整页跳过。

读取量从「全表、所有列」收缩到「一个分区里、若干数据块的三列」。数据在磁盘上已经被摆成利于这种扫描的形状：分布开的 tablet、按列存放并逐列编码、按排序键有序、按版本追加再由 Compaction 收敛。

但一条查询要同时在几十上百个 tablet 上执行这三步、再把结果汇总，光靠存储层的组织还不够，得有一整套把计算铺到多机上的执行机制。

三、数据的算：fragment、向量化与 pipeline

存储层摆好数据只是回答了一半。本章沿一条 SQL 的执行过程走完另一半：计划怎么拆成并行单元、单元之间怎么交换数据、算子在什么线程模型上跑、以及这份计划是谁做的决定。主角仍是第一章那条聚合查询，中途引入一张几行的维表 regions 来承载 join 的例子。本章的语句证据都来自作者在本机 Docker 里跑的 2.1.11 单 FE 单 BE 集群，EXPLAIN 的原文为节选、行内注释为本文所加。

先把计划拆开：fragment 与两阶段聚合

拿到 SQL，Doris 不是直接开跑，而是先编译出一份执行计划。计划的基本单位叫 fragment：FE 把一条 SQL 拆成若干个 fragment，每个 fragment 是发给 BE 的最小执行单元；fragment 之间的数据传递经过 exchange（数据交换节点）。这些结构在 EXPLAIN 的输出里全部可见——上一章那张 orders 表、那条八月聚合，计划的关键部分长这样（原文列名后的 [#N] 内部编号已略去）：

PLAN FRAGMENT 2
PARTITION: HASH_PARTITIONED: order_id -- 这个单元处理的数据分布：分桶列
 0:VOlapScanNode -- 扫描节点
 partitions=1/3 (p202608) -- 三个分区只有 8 月进入计划
 tablets=10/10, tabletList=11127,11129, ... -- 该分区 10 个 tablet 全部参与
 1:VAGGREGATE (update serialize) -- 局部聚合：扫完数据就地先加一遍
 output: partial_sum(amount)
 group by: region, category
 STREAM DATA SINK
 EXCHANGE ID: 02
 HASH_PARTITIONED: region, category -- 部分和按分组键重分布

PLAN FRAGMENT 1
PARTITION: HASH_PARTITIONED: region, category -- 接收方按同样的键接收
 3:VAGGREGATE (merge finalize) -- 最终聚合：把各处的部分和合并
 output: sum(partial_sum(amount))

先看 PARTITION 那一行：fragment 声明自己处理哪一份分布，扫描 fragment 的分布就是分桶列 order_id——第二章说 tablet 按分桶列哈希散开，这一行就是那句话在计划里的样子。partitions=1/3 和 tablets=10/10 也都是第二章的旧相识：分区裁剪和 tablet 列表，FE 在计划阶段就把扫描范围定到了这 10 个 tablet 上。

VAGGREGATE 出现了两次，这件事比看起来重要。聚合被拆成两阶段执行：扫描完每个 tablet，先就地按 region, category 求一遍部分和（update serialize，输出列叫 partial_sum），再把部分和按分组键重分布，由另一个 fragment 合并出最终结果（merge finalize）。为什么要两阶段？分布式的聚合必须有人把散在各处的中间结果收拢，直接把明细行全部传走，网络传的就是全部行；先局部聚合再传，网络上传的是「每个分组一行部分和」。拿本章实测的 bench 表算这笔账：300 万行、8 个桶，若分组数是 1 万，两阶段聚合让网络上跑的是 1 万 × BE 数行，而不是 300 万行——传输量从行数级降到分组数级，这一步省不出意义时（分组数接近行数，比如按用户 ID 分组），优化器可以退回单阶段，这也是它按成本选优的一部分。整个计划还有第三个 fragment（编号 0），负责把各处的最终结果收拢返回客户端，不再展开。

join 怎么执行：build、probe 与三种数据分发

聚合讲完讲 join。两张表 join 的标准动作是哈希连接：把其中一侧的连接键逐行读出、在内存里建一张哈希表——就是 Java 里 HashMap.put 那一下；另一侧的每行拿着键去查这张表——HashMap.get。前一步叫 build，后一步叫 probe。哪侧 build 不是任意的：build 侧的数据要整体进内存，probe 侧按流逐批读，所以倾向选小的一侧。

多机执行让 join 多了一层问题：两张表的行分散在不同 BE 上，任意两行都可能满足连接条件，得先让相关的行碰面。Doris 有三种让它们碰面的办法，下面三种计划形状都来自本章的实测——broadcast 来自 orders JOIN regions，shuffle 和 bucket shuffle 来自 bench 库里两张 300 万行的大表（posts，分桶列 id；visits，分桶列 uid）之间的 join：

broadcast：小表整表复制到每个相关 BE，各处各自完成 join。orders JOIN regions 的计划里写着 INNER JOIN(BROADCAST)。代价是小表大小乘以 BE 数，所以这条路只对维表这类小表成立。
shuffle（PARTITIONED）：两侧都大、谁都复制不起时，把两侧都按连接键哈希重分布，同一个键的行落到同一台 BE 再 join。用非分桶列的表达式把 posts 和 visits 相连，计划给出 INNER JOIN(PARTITIONED)，两侧各挂一个重分布的 exchange——两份数据都得动。
bucket shuffle：如果连接键恰好是某张表的分桶列，这张表的数据本来就按连接键分布着，一行都不必移动——让另一侧按它的分桶规则重排即可。把 join 键换成 visits 的分桶列后，计划给出 INNER JOIN(BUCKET_SHUFFLE)，大表一侧扫描节点直接接 join、中间没有任何 exchange，小表一侧的输出写着 BUCKET_SHFFULE_HASH_PARTITIONED（SHFFULE 是官方输出的原样拼写）。算一笔账：大表 3 亿行时，broadcast 要把小表复制 BE 数份，普通 shuffle 要把大表 3 亿行按连接键重排一遍，bucket shuffle 只把小表按大表的分桶规则重排一次，大表一行都不动。

第四种是更彻底的：建表时就用 "colocate_with" = "group_name" 声明两张表同分布，数据落盘时对应的分桶就落在同一台 BE 上，join 时连重排都省了（计划里显示 colocate: true）。约束也在这里：同组的表分桶列的类型和数量、桶数、副本数必须一致（分区数不必一致）；副本修复或迁移期间组状态不稳定时，会退化成普通 join 并在计划里注明原因。colocate 的分布效果本机单 BE 验证不了，以上按 2.1 官方文档口径陈述。

默认选哪种由优化器定；认为它选错了，可以在 SQL 里用 [broadcast]、[shuffle] 两个 hint 指定 join 右表的分发方式，再用 EXPLAIN SHAPE PLAN 对比前后的计划。

分发解决「碰面」，解决不了「不均」：某个连接键的行数远大于其他键，处理它的任务就成了长尾，其余任务干完只能等它。2.1 引入了 local shuffle：单个 BE 内部、在聚合前把数据在并行任务之间再重排一遍，把不均摊平。它与自适应并行扫描一起，是 2.1.0 发布说明里执行引擎一项的主要改进。

向量化：按批处理，一次 4064 行

上面计划里每个算子都带 V 前缀——VOlapScanNode、VAGGREGATE、VEXCHANGE。V 指 vectorized。要讲清它替代了什么，得先说旧模型。业界通称的火山模型（Volcano）里，每个算子实现成一个迭代器：上层算子调下一层的 next()，一次取一行。这是 Java 工程师最熟悉的 Iterator 接口的形状，它的问题也是同一个：调用太密。一条 SQL 十几个算子、扫描几百万行时，算子之间「一行一次」的函数调用要发生几千万次，真正的计算反而不是时间大头。

Doris 2.1 默认向量化执行，算子改成一次处理一批，批大小默认 batch_size = 4064 行（本文实测的默认值）。一批数据按列连续存放——和第二章的列存一脉相承，同一列的值类型一致、排在一起，CPU 才能上 SIMD 指令：单条指令对一批数据做同一运算（Java 里 Vector API 的设计目标就是把它暴露给应用）。第二章的列裁剪也在这里兑现最后一层收益：查询没引用的列，从扫描那一步起就不进入批次。算一笔调用次数的账：300 万行、十几个算子，火山模型是行数乘算子数量级的 next() 调用，向量化是行数除以 4064 再乘算子数——差了四千倍。

Pipeline：算子谁来跑

fragment 拆好、算子也向量化了，还剩一个问题：这些算子由哪些线程跑。早期的做法是每个 fragment 实例独占一组线程，查询一多线程数跟着涨。2.1 的执行引擎文档把新模型要解决的问题直接写作线程爆炸（thread explosion）。

2.1 起默认执行引擎是 pipeline 模型（本文实测 experimental_enable_pipeline_engine 默认为 true）。它把 fragment 里的算子链按阻塞点切开：聚合、排序这类算子必须收齐全部输入才能产出，算子链在这些位置断开，每段是一个 pipeline。Join 算子拆成 JoinBuildOperator 和 JoinProbeOperator 两段，聚合、排序同理拆成 Sink 与 Source 两段。pipeline 是逻辑概念，真正执行的是它实例化出来的 PipelineTask，全部提交到一个 BE 级的固定线程池——线程数不再随查询数量增长，这是与旧模型的分界线。

断开的位置用依赖（Dependency）接起来：build 侧的 pipeline 建完哈希表，调用 set_ready 唤醒等在依赖上的 probe 侧 pipeline。每个任务跑到时间片用完、或者被依赖挡住时让出线程，线程马上转去执行其他就绪任务——少数线程在大量任务之间流转，而不是大量线程各自守着一个 fragment。

并行度由 parallel_pipeline_task_num 控制，默认 0，语义是取 BE 核数的一半（2.1 文档口径），在单查询延迟和并发吞吐之间取平衡：16 核的 BE，一个 fragment 默认开 8 个并行任务。2.1 还拆掉了一道历史限制——此前并行度受 tablet 数封顶，桶切少了并行度就上不去；2.1 起对明细模型和 Merge-on-Write 主键模型支持分片内并发读，官方口径的线程上限是 48。本地实测还有一层版本事实：experimental_enable_pipeline_x_engine 也默认为 true。PipelineX 是这一代 pipeline 引擎改进版的名称，local shuffle 和自适应并行扫描都算它的组成部分；开关还挂在 experimental_ 前缀下，这个前缀本身值得读出来——生产上动它之前先想一下。

Nereids：计划是谁做的决定

前面所有的决定——拆几个 fragment、哪一侧 build、聚合要不要两阶段、扫描定到哪些分区——都是优化器做的。Doris 2.1 默认使用新优化器 Nereids：本地实测 experimental_enable_nereids_planner 默认 true，每份 EXPLAIN 的第一行也自报 Explain String(Nereids Planner)；enable_fallback_to_original_planner 默认 true，Nereids 处理不了的语句退回旧规划器执行。

Nereids 的工作分四步：把 SQL 文本解析成语法树（AST）；做语义分析，检查表、列、函数是否存在、用法是否合法；用一组固定的规则重写计划，这一步称 RBO——列裁剪、谓词下推、分区裁剪都在这里，读者已经见过它们的产物；最后基于成本选优（CBO），在等价的计划集合里逐个估算执行成本，取最低者。RBO 的改写是确定性的，CBO 的估算靠统计信息：表和列的行数、每列不同值的个数（NDV，number of distinct values）、最大最小值、NULL 数。

统计信息的收集默认也是开着的（enable_auto_analyze 默认 true），后台自动对内部表做采样收集，结果存进一张内部表；要手动触发，ANALYZE TABLE orders WITH SAMPLE ROWS 100000;。统计过期或缺失时，CBO 的成本估算只能建立在猜测上——查询突然变慢时，统计信息健康度应该在排查清单的前几项。规划本身也有开销：Nereids 默认 30 秒超时（nereids_timeout_second），因为规划过程要对涉及的表加读锁，超时是为了不让复杂查询长期占着锁不放。

Runtime filter：join 现场生成的过滤器

第二章讲过 bloom filter 索引：建表时点名某几列，存储层为它们逐 page 建过滤器。这一节的 runtime filter 名字里也有 bloom filter，是另一回事——它不在建表时创建，而是 join 执行到现场动态生成、查询结束即弃。

机制是这样的：build 侧读数据建哈希表时，顺手把连接键的值收集起来做成过滤器，推给 probe 侧的扫描节点——扫描阶段就把肯定 join 不上的行丢掉。省下的不只是 probe 的计算，还有这些行的磁盘 I/O 和到算子的传输。过滤器有四种：IN（值集合小而精确）、Bloom（大集合的近似版，回答「没有」就真没有，回答「可能有」可能只是哈希碰撞）、MIN_MAX（只记最大最小值，适合范围条件）、IN_OR_BLOOM（按实际行数在 IN 和 Bloom 之间自动选）。默认启用后两类：runtime_filter_type 默认值 12，对应 MIN_MAX 加 IN_OR_BLOOM——本文实测 SHOW VARIABLES 显示 IN_OR_BLOOM_FILTER,MIN_MAX，是同一件事的两种写法。多机时每个 join 实例只见过一部分数据，系统会选一个节点当 manager，把各实例生成的过滤器合并成全局的再统一下推。

它同样写在计划里。visits 表（300 万行）join 一张 10 行的维表、维表侧带过滤条件时，join 节点那一行是 runtime filters: RF000[min_max] <- uid, RF001[in_or_bloom] <- uid，扫描节点对应一行 runtime filters: RF000[min_max] -> uid, RF001[in_or_bloom] -> uid——<- 是生成，-> 是下推；EXPLAIN SHAPE PLAN 里则写作 build RFs:RF0 uid->[uid] 与 apply RFs: RF0 RF1。

但它的收益不是必然兑现的。我把同一条 join 开关 runtime filter 各跑了几遍，扫描耗时没有可分辨的差别：这张表的 uid 每 1000 行循环一轮，每个 page 都包含全部取值，过滤器只能逐行丢行，一个 page 也跳不掉——数据的分布又一次决定了优化结构的收益，和第二章低基数列用不好 bloom filter 是同一类教训。另外两个边界：build 侧本身没有过滤条件时，过滤器覆盖全部值、什么也省不下，优化器默认会把它裁掉；扫描节点等过滤器只等 1 秒（runtime_filter_wait_time_ms 默认 1000），等不到就先扫，join 的 build 慢时过滤器可能根本没赶上用。

一条查询的全链路

把两章拼在一起，那条聚合查询的完整旅程是：SQL 文本进入 Nereids，解析、重写、按成本选出计划；计划拆成 fragment 发给相关 BE；每个 BE 把 fragment 切成 pipeline、实例化成并行任务、提交固定线程池；扫描节点完成第二章的三道收缩，读出第一批数据；算子按 4064 行一批向量化地执行聚合和 join；局部结果按分组键 shuffle、汇总、返回。

存储层决定哪些数据不必读，执行层决定读进来的数据怎么算得快、传得少，优化器决定按哪份计划执行。排查一条慢查询，也就从这三层分别去问：多读了什么、多算了什么、计划为什么这么选。

四、数据的契约：数据模型

前两章有几处话只说了一半：宽表点查是列存的弱项，「怎么缓解」没有讲；索引体系表里出现过「Merge-on-Write」，只给了一句话解释；聚合模型、主键模型的名字多次出现，语义始终没展开。本章把这些收拢到同一个概念上——数据模型：建表时选定的 Key 子句与列定义，签下一份同时约束存储语义和查询能力的契约。它决定 Compaction 对数据做什么、读时合并是否存在、谓词能不能下推、UPDATE 和 DELETE 支不支持，甚至 avg() 返回什么。

同一个键、同一批数据、三种答案

Doris 有三种数据模型，区别只在建表语句的 Key 子句和值列写法上。三种都建出来，喂同一批两行数据（同一个键的两笔订单），观察各自的结果：

-- 聚合模型：值列必须声明聚合方式
CREATE TABLE agg_demo (
 dt DATETIME NOT NULL,
 order_id BIGINT NOT NULL,
 amount BIGINT SUM, -- 同键相加
 status VARCHAR(16) REPLACE -- 同键取后写的
) AGGREGATE KEY(dt, order_id)
DISTRIBUTED BY HASH(order_id) BUCKETS 3 PROPERTIES ("replication_num" = "1");

-- 明细模型：值列就是普通列
CREATE TABLE dup_demo (
 dt DATETIME NOT NULL,
 order_id BIGINT NOT NULL,
 amount BIGINT,
 status VARCHAR(16)
) DUPLICATE KEY(dt, order_id)
DISTRIBUTED BY HASH(order_id) BUCKETS 3 PROPERTIES ("replication_num" = "1");

-- 主键模型
CREATE TABLE uni_demo (
 dt DATETIME NOT NULL,
 order_id BIGINT NOT NULL,
 amount BIGINT,
 status VARCHAR(16)
) UNIQUE KEY(dt, order_id)
DISTRIBUTED BY HASH(order_id) BUCKETS 3 PROPERTIES ("replication_num" = "1");

然后是同一批写入（三张表各来一遍）和同一个查询：

INSERT INTO agg_demo VALUES ('2026-08-01 10:00:00', 1001, 50, 'new'),
 ('2026-08-01 10:00:00', 1001, 30, 'paid');
-- dup_demo、uni_demo 吃完全相同的两行

SELECT * FROM agg_demo; -- 三个模型各跑一次

同一个键的两行数据，三个模型给出三种答案（本文实测）：

模型	`SELECT *` 返回
聚合模型	1 行：`amount = 80, status = 'paid'`——SUM 把 50 与 30 相加，REPLACE 取后写的
明细模型	2 行：50/new 与 30/paid 全部保留
主键模型	1 行：`amount = 30, status = 'paid'`——后写覆盖前写

列结构完全相同，答案不同，差别全部来自建表时选的模型。

这份契约的特别之处是签定后不可改：官方文档明确「建表之后，表模型的属性就已确定，不能修改」，主键模型的实现模式同样「在创建时固定、不能通过 schema 变更改变」。Java 工程师对这个处境不陌生：选错模型不是改配置，是换表重灌。

明细模型：Key 只是排序

三种模型里最朴素的是明细模型（Duplicate Key）：Key 列只代表排序，没有任何唯一性约束——官方文档的说法是「Key 列用于排序，没有唯一性约束」，存储层原样保留写入的每一行。第二章讲的排序键、前缀索引、列存编码，落在明细模型上就是它的全部：Key 决定数据怎么摆，仅此而已。

它适合两类场景：必须保留全部原始记录（审计、对账）；查询维度事先不定、任何列都可能出现在 WHERE 和 GROUP BY 里（ad-hoc 分析）——明细都在，怎么切都行。对照表里它还有一个容易忽略的差异：DELETE 语句只算「部分支持」。

聚合模型：落盘即聚合

**聚合模型（Aggregate Key）**的 Key 列负责分组，非键的值列必须声明聚合方式，可选的有 SUM（累加）、MAX、MIN、REPLACE（后写替换前写）、REPLACE_IF_NOT_NULL（非 NULL 才替换）、HLL_UNION（HyperLogLog，近似去重计数）、BITMAP_UNION（位图并集）。聚合方式写进列定义本身，SHOW CREATE TABLE 能直接看到：

`amount` bigint SUM NULL,
`status` varchar(16) REPLACE NULL
AGGREGATE KEY(`dt`, `order_id`)

聚合发生在三个时机，每个都在前两章出现过：导入时，每个批次生成一个新版本（第二章的 rowset 和版本号），版本内同键数据先聚一次；后台 Compaction 合并多个版本时，同键数据再聚一次；查询时，系统对跨版本的同键数据做最后的合并，保证结果正确——「读时合并」这个第二章的概念，在聚合模型上的含义就是第三步。所以聚合模型不是查询时才算，而是能提前聚的都提前聚了，落盘的数据已经是聚合后的形态，原始明细不复存在。

这带来聚合模型最大的收益和最大的坑，是同一件事的两面。收益：存储省了、聚合查询的计算量小了。坑：表里的行数不等于业务行数。继续用刚才的表，再来一笔新订单，然后对两种模型跑同一个统计：

INSERT INTO agg_demo VALUES ('2026-08-02 10:00:00', 1002, 10, 'paid');
INSERT INTO dup_demo VALUES ('2026-08-02 10:00:00', 1002, 10, 'paid');

SELECT count(*), sum(amount), avg(amount) FROM agg_demo;
SELECT count(*), sum(amount), avg(amount) FROM dup_demo;

三笔订单（50、30、10），两个模型的结果（本文实测）：

模型	count	sum	avg
明细模型	3	90	30
聚合模型	2	90	45

sum 完全一致，count 与 avg 已经分道扬镳：聚合表里那张 50/30 的订单合成了一行，avg(amount) 算出的是「部分和的平均」，不是「订单的平均」。官方文档把这条写成了通则：聚合模型「对聚合查询友好，但对 count(*) 类查询不友好」，其他聚合语义的正确性需要使用者自行考量。报表场景（固定按天、按地区求和）天然匹配 SUM 语义，没问题；把聚合模型当明细表用，avg、count distinct 这类查询会安静地给你一个错误的数——不报错，只是不对。

主键模型：写入即 upsert

**主键模型（Unique Key）**的 Key 列同时承担排序和唯一性约束：每个键只保留一行，最新写入的生效。这个语义 Java 工程师可以直接映射成 INSERT ... ON DUPLICATE KEY UPDATE——存在就整行更新，不存在就插入。

实现上它分成两种模式。Merge-on-Write（MoW，写时合并）：写入时就地合并同键数据，存储层只保留每个键的最新版本——2.1 起它是主键模型的默认模式（本文实测建表回显里有 "enable_unique_key_merge_on_write" = "true"）。Merge-on-Read（MoR，读时合并）：写入只追加，同键保留多个版本，查询或 Compaction 时再按键合并。第二章讲的「读时合并」在主键模型上的代价形态就是 MoR：版本越积越多、查询要合并的路径越长，而且谓词无法下推到存储层；MoW 换来读侧干净（无合并、谓词可下推），代价是写入时多做合并。官方的建议是多数场景用 MoW，MoR 留给写多读少的场景。两种模式同样在建表时固定。它与聚合模型 REPLACE 的区别值得点一句：REPLACE 只替换挂了它的那一列，其余列各按各的聚合方式走；主键模型是整行覆盖。

对照表里主键模型独占的几项能力都挂在这条契约上：UPDATE 语句只有主键模型支持；导入时部分列更新（只更新某几列、其余列保持原值）也只有主键模型支持，且要求 MoW 模式。另有一条容易踩的约束：分区列必须包含在 Key 列中，否则数据唯一性保证不了。

兑现第二章的欠条：点查的短路径

第二章说过列存的代价：取一整行要把所有列各读一次，宽表高频点查付出 N 倍 I/O。当时欠的「怎么缓解」，答案现在可以拼出来了，而且是主键模型契约的一部分：

MoW 是前提：点查要在存储层快速定位「那个键的最新行」，读时合并的多版本形态撑不起这条路径；
store_row_column：建表时开启，表里额外存一份按行组织的副本（官方口径：多花磁盘换点查的 I/O），键等值查询直接从行存取整行，不必逐列凑；
light_schema_change 必须开：短路径依赖每列的唯一编号。

三个条件凑齐，单表的键等值查询走一条短路径，一次 RPC 返回，EXPLAIN 的输出里会出现 SHORT-CIRCUIT 字样（本文在 MoW + 行存表上实测确认）。再配 JDBC 的 useServerPrepStmts=true 用 PreparedStatement，省掉 FE 逐条解析 SQL 的 CPU（官方口径 CPU 瓶颈时可提效 4 倍以上），服务化高并发点查的整条链路就齐了。行存副本对应的行缓存默认是关的（BE 配置 disable_storage_row_cache），要做高并发点查时记得打开。这套东西只对「按订单号查详情」这类服务场景有意义，纯分析查询用不上，也别为它付行存的存储成本。

契约的选型

三种模型各自的领地，官方对照表加上本文的实测可以收成三句话：固定口径的报表和指标（按天、按地区求和计数）→ 聚合模型，落盘即预计算；有唯一性约束、要更新、要做服务点查 → 主键模型 + MoW；原始明细要保留、查询维度不定 → 明细模型。

回头看这四章的骨架：第二章讲数据在磁盘上怎么摆，第三章讲摆好的数据怎么算，本章的契约签在两者中间——它决定 Compaction 帮你把数据聚到什么形态、读时有没有合并、点查有没有短路径，也决定 count 和 avg 返回的数是不是你想的那个数。建表语句里的每一个子句，都是在给这份契约签字。

五、数据的写入：Stream Load 的完整旅程

机制讲完了，最后看数据怎么进来的。第一章承诺过两件事：单批导入原子可见、多数派副本写成功才算成功；第二章出现过 rowset、版本号和 -235 事故。本章沿一条真实的 Stream Load 请求走完全程，把这些承诺逐一兑现。本章所有请求与响应都在本机 2.1.11 集群实跑，输出原文照录。

一条 HTTP 请求的旅程

Stream Load 不走 SQL 通道，走 HTTP：把一个 CSV/JSON 文件用 PUT 推给 Doris。请求发往 FE 的 8030 端口：

curl -s -u root: \
 -H "label:load_demo_001" -H "column_separator:," -H "Expect:100-continue" \
 -T /tmp/sl2.csv \
 http://127.0.0.1:8030/api/loadtest/load_demo/_stream_load

第一条响应是 HTTP 307 Temporary Redirect，Location 指向某台 BE 的 8040 端口——FE 按轮询挑一台 BE 当本次导入的 coordinator（协调节点），由它接收数据并分发给其他副本所在的 BE，FE 借此在多台 BE 间摊负载。文档同样允许跳过 FE 直接把请求发给某台 BE，两种姿势都合法。本机实测时撞上了这个机制的经典坑：重定向里的地址是 BE 的容器内网 IP，跨网络环境跟过去就是连接失败——官方为此单独写了一页「复杂网络环境 Stream Load」，常见解法就是直连 BE。改直连后导入成功，返回的 JSON 值得一屏屏看：

{
 "TxnId": 40,
 "Label": "load_demo_001",
 "TwoPhaseCommit": "false",
 "Status": "Success",
 "NumberTotalRows": 2,
 "NumberLoadedRows": 2,
 "NumberFilteredRows": 0,
 "NumberUnselectedRows": 0,
 "LoadBytes": 69,
 "CommitAndPublishTimeMs": 63
}

TxnId 是这次导入对应的事务号——导入从进门的第一个响应就是事务语义的。底部还有一串时间分解：BeginTxnTimeMs（开事务）、StreamLoadPutTimeMs（FE 定计划）、ReadDataTimeMs、WriteDataTimeMs（写数据）、CommitAndPublishTimeMs（提交并发布版本），几段相加基本就是总耗时——排查导入慢时，它直接告诉你时间花在哪一段。

事务：从 begin 到 publish version

刚才那个 TxnId 40 在 FE 日志里能找到完整的生命周期，三行原文按顺序是：

beginTransaction: txn id 40 with label load_demo_001
 from coordinator BE: 172.30.80.3
commitTransaction: [TransactionState. transaction id: 40, label: load_demo_001 ...]
PUBLISH_VERSION finishTransaction [transaction id: 40, label: load_demo_001 ...]

三行正好对应第一章承诺的兑现路径：begin——coordinator BE 收到数据后向 FE 开事务；数据并行写入各副本 BE，多数派写成功后，coordinator 调 commit；FE 再把版本发布（publish version），数据对外可见。发布完成之前有一个窗口：事务已提交但数据还查不到，对应返回 JSON 里的另一种状态 Publish Timeout——导入本身已完成，只是可见性有延迟。上一节那个 CommitAndPublishTimeMs 计时的，就是最后这两步。

Label：重试的安全网

第一次提交的 JSON 里有个 Label: load_demo_001，它是导入的身份标识，规则只有一条：同一个 label 不能被导入两次。实测把同一请求原样重发：

Status: Label Already Exists
Message: [LABEL_ALREADY_EXISTS] Label [load_demo_001] has already been used,
 relate to txn [40], status [VISIBLE].

报错原文把三个概念的关系一次讲全：label 关联着事务号，事务有自己的状态（VISIBLE 表示已发布可见）。客户端网络超时后重试时，带着同一个 label 再来，Doris 会发现这批数据已经导入过、直接拒绝——于是重试不会产生重复数据，官方把这个保证写作 At-Most-Once，并强烈建议「同一批数据使用同一个 label」。label 默认保留三天（label_keep_max_second 可调），期间都能查到某一批数据的导入状态；状态为 CANCELLED（失败取消）的 label 可以复用。

数据质量：零容忍与 ErrorURL

导入对脏数据的默认态度是零容忍：max_filter_ratio 默认为 0（取值 0 到 1），错误行比例一超，整批失败。实测把一个只有 4 列的 CSV 推给 7 列的表，返回 Status: Fail、[DATA_QUALITY_ERROR] too many filtered rows，NumberFilteredRows = 2——两行全被过滤，一行没进。响应里附了一个 ErrorURL，用 curl 访问就能看到逐行的坏行原因：

Reason: actual column number in csv file is less than schema column number.
 actual number: 4, schema column number: 7

容忍比例调大后（比如 max_filter_ratio:0.4），错误行不超比例的批次会成功入库，被丢弃的行数记在 NumberFilteredRows 里。注意区分：查询里 WHERE 条件过滤掉的行记在 NumberUnselectedRows，不算错误、不占容忍额度——前者是「数据不合格」，后者是「按规则不要」。

两阶段提交

有些接入场景希望「数据先放进来、先别让下游看见」，等上游确认后再放行——Stream Load 用两阶段提交支持这个语义。实测全程：

# 第一阶段：加 two_phase_commit 头，数据写入但不发布
curl -s -u root: -H "label:tpc_demo_001" -H "two_phase_commit:true" \
 -H "column_separator:," -T /tmp/sl2.csv \
 http://127.0.0.1:8040/api/loadtest/load_demo/_stream_load
# 返回 Status: Success, TwoPhaseCommit: true —— 事务处于 pre-commit 状态

# 此时查询：行数不变（实测 2 → 2），pre-commit 的数据不可见

# 第二阶段：确认后提交
curl -s -u root: -X PUT -H "txn_operation:commit" -H "label:tpc_demo_001" \
 http://127.0.0.1:8040/api/loadtest/load_demo/_stream_load_2pc
# 提交后查询：行数 2 → 4，数据可见

「写入成功」和「对外可见」在两阶段提交下被拆成两个独立的决定，中间的窗口留给上游业务。这条路径的端点和参数在 2.1 的 Stream Load 手册正文里没有展开，本节流程以本地实测为准。

高频写入的答案：Group Commit

Stream Load 的默认行为是「一次导入 = 一个独立事务 = 一个新版本」。这个模型干净，但高频小批量写入会把两头压垮：FE 要为每次导入解析、定计划，版本数飞涨——第二章那个 -235（单 tablet 版本数超 500 拒绝导入）的源头就在这里。2.1 给出的答案是 Group Commit：官方文档对它的定位是「不是新的导入方式，而是对已有导入方式的优化扩展」——把多个小批量导入在后台合并成一个大事务提交。

它有三种模式（本文实测确认 2.1 没有「自动选」的第四种）：

off_mode（默认）：关闭，行为同上；
sync_mode：合并攒批，但事务提交后才返回——写入慢一点，数据立即可见；
async_mode：数据先写 WAL（Write Ahead Log，预写日志）立即返回，后台按阈值攒批提交。

攒批的触发条件是时间或量先到者：group_commit_interval 默认 10 秒、group_commit_data_bytes 默认 64 MB。可见性的代价用一次实测看：

SET group_commit = async_mode;
INSERT INTO load_demo VALUES ('2026-08-03 09:00:00', 3001, 1.0, 'new');
SELECT count(*) FROM load_demo; -- 立即查：4 行，刚插入的不可见
-- 等 12 秒
SELECT count(*) FROM load_demo; -- 5 行，攒批提交后可见

async_mode 的代价也要如实说：数据先落在单台 BE 的 WAL 文件里，官方明确「磁盘损坏或误删文件可能造成数据丢失」，运维下线 BE 时要按文档流程走；单条数据量太大、WAL 空间吃紧时自动转 sync_mode。另外它不是处处生效：显式事务、带 label 的导入、两阶段提交这些场景会自动绕过——需要精确控制批次边界的功能，和攒批天然冲突。

从 curl 到可见

到这里，第一章立下的承诺全部兑现。一条 Stream Load 的完整时间线：HTTP 请求到 FE，307 重定向给一台 coordinator BE；coordinator 向 FE 开事务（begin），label 校验通过；数据分发到各副本 BE，写进 MemTable、刷成 rowset——第二章的版本号在这里 +1；多数派写成功，事务提交（commit）；FE 发布版本（publish），数据对外可见；下游从此能在这条数据上跑出第二章的扫描收缩、第三章的并行执行和第四章契约定义的语义。写入的可靠性靠 label 兜住重试，靠 max_filter_ratio 和 ErrorURL 暴露脏数据，靠两阶段提交把「写入」和「可见」拆成两个决定，靠 Group Commit 把高频小批量的版本代价摊平。

五个章节走完，从一次 OLTP 与 OLAP 的对比开始，到一条数据在集群里的完整一生结束。

第五话｜RabbitMQ 集群的架构与高可用：一条消息从发到收走了哪些节点

Sun, 22 Feb 2026 00:00:00 +0000

这篇文章讲 RabbitMQ 的集群架构，以及它如何靠这套架构实现高可用。要看清这套架构，得先拆掉「集群把消息复制了三份」这个最常见的误解——集群真正复制的其实只有两类：集群元数据和队列内容。 而客户端和某个节点之间的连接状态，根本不进集群，只握在客户端自己手里。搞清楚这三样东西各自由谁负责、出故障时各自怎么表现，就理解了这套高可用架构到底可靠在哪、又会在哪里失效。

第一话在单台节点上把一条消息的一生走了一遍，那时队列类型之间的差别只体现在消费语义上；连成集群之后，同一个差别会变成两种完全不同的故障表现——这正是集群高可用要解决的那一层。

正文里会碰到一个具体的矛盾：客户端连的是节点 A，队列的 Leader 在节点 B，消息为什么还能发成功？ 这个问题在第四节和第六节会拆开讲，答案正是上面那三类数据的分工——客户端状态留在原地，队列内容在集群内部被定位与复制，两者各走各的通道。

全文以 RabbitMQ 4.3.5 为准（Erlang 27.3.4.17、amqp-client 5.30.0、JDK 21）。集群是三台容器里的节点，同宿主机、仅面向本机实验——它不构成任何生产容量或性能结论，文中给出的秒数与条数只对这个环境负责。凡是本机没有跑过的机制，正文会写明它来自官方文档或源码，不当成已证实的结论。

边注：标为「边注」的段落是限定与例外，不影响主线，第一遍可以跳过；其中几条会改变边界，真用到那一节时值得回头看。

一、AMQP 模型：消息不直接进队列，而是先到交换机

讲集群之前，先把 RabbitMQ 在单机上的那套对象模型立住。生产者与消费者之间隔着三样东西：vhost、交换机（exchange）、队列（queue），消息要经过一次路由才会落进队列。

vhost 是逻辑隔离层。 一个 vhost 里有自己一套独立的交换机、队列和绑定，权限也按 vhost 划分。默认开箱即有一个 vhost（名字是 /）。本文的所有操作都发生在默认 vhost 里，不提 vhost 就是指它。

生产者把消息发到交换机，不是直接发到队列。 每发一条消息都要带一个 routing key（路由键），交换机根据自身类型和 binding（绑定）决定把它投给哪些队列。消息在交换机这一层完成路由，之后才落到队列里。

队列是消息最终落点，消费者从队列取。 队列通过 binding 挂到交换机上，binding 规定了「什么样的 routing key 投到这个队列」。消费者订阅的是队列，不是交换机。

%%{init: {'theme':'neutral'}}%%
flowchart LR
 P[生产者
发消息 + routing key] --> E{交换机
按类型和 binding 路由}
 E -->|binding 命中| Q1[队列 1]
 E -->|binding 命中| Q2[队列 2]
 Q1 --> C1[消费者 1]
 Q2 --> C2[消费者 2]

交换机类型决定路由规则，最常见的是四种：

direct：routing key 和 binding key 精确相等才投；
topic：用 . 分段的通配匹配（* 匹配一段、# 匹配零或多段）；
fanout：忽略 routing key，广播给所有绑定队列；
headers：按消息头匹配，几乎不用。

四种里本文只会在两处用到 fanout——第六节「一条消息路由命中多个队列」和第八节「confirm 由所有命中队列共同决定」，都依赖 fanout 把一条消息同时投进多个队列。其余三种类型与本文的集群主题无关。

一句话立住这个模型：生产者 → 交换机 →（binding 路由）→ 队列 → 消费者。集群要做的事，就是把这条链上「交换机、队列、绑定的定义」和「队列里的消息」这两样，在多个节点之间正确地复制与同步。下面先看复制靠什么机制，再回到这条链本身。

二、三种队列类型：classic、quorum 与 stream

第一节里的「队列」在 RabbitMQ 里不是一个铁板一块的东西，而是分三种类型。它们共享同一套 AMQP 模型（都要挂到交换机上、都由消费者订阅），差别在于一份数据存几份、以什么方式存。后面全文反复出现的「classic / quorum 两类」指的就是其中两种，这里先一次说清，免得读到中途才去猜。

classic queue：一份数据，只存在属主那台节点上。 这是 RabbitMQ 最老、默认的队列类型，消息只在属主（owner）节点落一份。它适合不需要跨节点复制、追求简单与低延迟的场景；代价是一旦属主节点离线，队列就不可用——因为数据没有第二份。

quorum queue：三份数据，靠 Raft 复制到多数节点。 它把队列实现为一组 Raft 副本（典型三副本，也可配其它奇数），消息被复制到多数节点，靠多数派保证可用性与不丢。它适合要求「挂掉一个节点还能继续收发」的高可用场景；代价是每次写入要走一轮复制确认，比 classic 多一次网络往返。

stream：按追加日志存，适合大吞吐的连续流。 它面向的不是经典的生产/消费队列语义，而是「可以反复重放、按偏移量读」的日志型数据，消息不会被消费即删。它的副本也是多数派复制，但副本管理、确认边界都和 quorum 有细微差别。

三种类型在应用里只差一个 x-queue-type 参数，其余声明姿势完全一样（amqp-client 的 Channel 接口）：

// 三种队列的声明只差 x-queue-type 这一个参数
channel.queueDeclare("orders.classic", true, false, false, null);
channel.queueDeclare("orders.quorum", true, false, false,
 Map.of("x-queue-type", "quorum"));
channel.queueDeclare("orders.stream", true, false, false,
 Map.of("x-queue-type", "stream"));

不写 x-queue-type，拿到的是默认的 classic。类型在声明那一刻就锁死——之后再用一个不同的 x-queue-type 去声明同一个队列，broker 会拒绝这次声明，而不会把队列改掉。

三种类型落在同一套 AMQP 模型上，差别只在「一份数据存几份、怎么存」：classic 只有一份数据，属主节点离线队列就不可用；quorum 把数据复制成三份，靠多数派保证可用；stream 也是三份，但按追加日志存、可反复重放。副本数是「高可用」的地基，这个地基在这一节先立住，后面几节再讲它怎么被多数派与选举用起来。

三种类型里，本文的主线只有 classic 和 quorum 两类——因为这一话的主题是「集群高可用」，而 classic 与 quorum 正好是一副最干净的对照：一份数据 vs 三份数据、单点 vs 多数派。stream 只在文末第十三节选型时出现一次，作为第三种选项补全决策维度，不进入正文的机制叙述。需要知道的是，两类队列在 AMQP 模型上是完全等价的：同一个 fanout 可以把一条消息同时投进一个 classic 和一个 quorum，两边各自按自己的规则接不接受、各确认各的，互不相干。

有了这个分类，后面每一节里「classic 一个副本 / quorum 三个副本」的说法就有了出处。下面先看这些副本靠什么机制复制——也就是 Raft。

三、Raft 的最小模型：角色、任期、日志、多数派与选举

RabbitMQ 集群的高可用，底层靠的是一套叫 Raft 的共识算法：把一份状态复制成多份，靠内部选举与复制，保证其中几台挂了整体还能服务。要理解它，不需要读完 Raft 教科书，只需要下面这个最小模型——一个副本组内部在做什么。模型到「能推出后续行为」为止，术语只保留最少的几个。

角色。 一个组里有一个 Leader 和若干 Followers。所有写操作先到 Leader。这里的「操作」是泛称：任何需要多个副本达成一致的变更都算，不必限定成某一种。

任期与日志。 Leader 更替会更换任期。选举只允许日志足够新的候选者获胜，所以新 Leader 本身就带着既有日志，不是从零开始；它要处理的是上任期可能遗留的未提交尾部，把这些尾部在新任期里提交或覆盖，组内就「已提交到哪」达成一致之后继续服务。每个操作以日志条目的形式追加在 Leader 上，Leader 负责把条目复制给 Followers。

多数派。 这是模型里最要紧的一条：Raft 组只在多数副本可达时可用。三成员组里一个节点故障还剩两个，多数派成立；再故障一个就只剩一个，多数派不成立。多个 Raft 组可以并存，各自独立地选举与判定多数派。

提交点。 多数派接受并确认之后，这条日志才算提交，此时才向客户端返回。所以确认的语义是「多数派已经收下」，它并不要求每个副本都写完。

组大小与容错。 三个成员支撑一个节点故障，五个支撑两个。为什么用奇数：四成员和它小一号的三成员一样只能容忍一个故障，却要多复制一份，纯亏。也正因如此，两节点集群不可取——两个成员里任何一个故障都会让多数派消失，容错能力为零，代价却照付。

成员不共享节点：同一个组的几个成员分布在几台不同节点上，否则一台机器挂掉会同时带走两个成员。规模也不是越大越好，超过五个成员之后性能下降、不建议超过七个。

四、三台节点连成集群：一条消息从发到收，走了哪些节点

三台 RabbitMQ 节点组成集群后，客户端连接其中任意一台即可声明队列、收发消息，无论这个队列实际由哪台节点持有。本节沿一条消息的完整路径，说明发布、消费各经过哪些节点，以及集群在节点间同步了哪些数据。

发布：客户端只连一台，其余由集群内部完成。 客户端连接的那台节点称为接入节点，它只作为入口，不必然持有目标队列。队列的写操作由 Leader 承担（classic queue 中称属主），Leader 可以位于集群内任意节点。发布时，消息先到达接入节点上的 Channel 进程；Channel 根据队列元数据，在 broker 内部直接定位到队列 Leader（而不是先投到一个本地队列再等转发）。Leader 将其追加为日志条目，再复制给该队列的其余副本（Follower）。多数派副本确认后，确认沿原路返回客户端。整个过程客户端只与接入节点通信，无需感知 Leader 的位置——「接入节点」与「Leader」之间的那一步是 broker 内部寻址，不是客户端另建连接。

同步：集群复制的只有两类数据。 上述路径中，真正在节点间复制的数据分两类，机制相互独立：

元数据：队列定义、binding 等声明性内容，由 Khepri 维护，全体节点共享同一份。在任一节点声明队列，其余节点立即可见。
队列内容：消息本体。副本数量取决于队列类型——classic queue 仅 Leader 持有一份；quorum queue 有 Leader 与两个 Follower 共三份。

除此以外的状态——客户端与某节点的连接、信道上未完成的命令——不进入集群，只保留在客户端侧。因此「部署三台节点」不等于「消息自动复制三份」：元数据确有三份，队列内容按类型而定，客户端状态则一份都没有。

消费：同样先到 Leader。 消费并不从接入节点直接读取。消费者连接某接入节点后，投递由队列的 Leader 发起，Leader 将消息推送（或由消费者拉取），消费者确认后再返回 Leader。因此无论发布还是消费，队列的读写都由 Leader 仲裁，接入节点上的 Channel 进程只负责在 broker 内部把请求直接定位到 Leader，本身不持有队列数据。

一句话收口：发布与消费都经过「接入节点上的 Channel → 队列 Leader」这条 broker 内部路径——客户端始终只连接入节点这一台，节点间定位 Leader 是集群内部完成的；集群所做的是把 Leader 上的变更同步给 Follower，同步范围仅限元数据与队列内容两类。

读完本文，读者应能对一个具体队列自行判断：

这个队列是什么类型、它当前有几个副本在线、是否仍有多数派、以及 Publisher Confirm 在这个队列类型上确认到了哪一步。

边界在这里可以直接量一下：只连一个节点声明两个队列，三个节点都查到了同一份定义（两条），exchange 与 binding 也一样；但两类队列的成员数立刻分开了——classic 只有一个成员，quorum 有三个（raw-scope-of-replication.log）。

本文所有实测读数来自同一套三节点集群，先交代它的边界：三个节点跑在同一台宿主机上，都是 RabbitMQ 4.3.5。同宿主机意味着节点间没有真实网络分区，只有进程被杀与容器被停两种故障，所以本文能说明「节点消失时集群怎么反应」，不能说明「网络抖动或分区时怎么反应」，也不构成任何生产容量或性能结论。节点间的 net_ticktime 在本机设成 10 秒（默认 60），后面出现的超时数字都基于这个值。集群的起停步骤收在 GYD 仓库该模块的 README 里，正文不复现；跑不通或读数可疑时，翻文末的排错索引。凡本机没有跑过的机制，正文会写明它来自官方文档或源码，不当成已证实的结论。

五、元数据：集群里唯一全局共享的一份

元数据是最容易被顺手想成「也是数据、也是复制三份」的那个范围。它确实在复制，但它复制的是「有哪些队列」，不是「队列里有什么」。

4.x 里这套元数据存储的实现叫 Khepri，基于 Raft，保存的是定义类的东西：用户与权限、vhost、exchange 和 queue 的定义、binding、policy。它不保存消息，也不保存队列的运行状态。一条消息是否已落盘，在它这里查不到。

元数据与队列内容是两个独立的 Raft 组。这一点在磁盘上看得最直接：同一个数据目录下 coordination/ 与 quorum/ 并列，前者装集群级元数据，后者装每个队列自己的 Raft 日志。既然是两个组，各自的 Leader 也可以不是同一台节点——本机实测里元数据 Raft 的 Leader 落在 rabbitmq2，而集群名节点是 rabbitmq1，两者没有必要一致。

这套元数据存储在 4.3 里由 Khepri 独家接管。演进线是：3.13 实验性支持，4.2 成为新集群默认，到 4.3 它已是唯一受支持的元数据存储——Mnesia 连同配套的分区处理策略一起被彻底移除。本机实测印证了这一点：数据目录里没有 schema.DAT，mnesia 相关的 schema 命令数为零（env-baseline.log）。

六、一次发布从发出到确认，经历了什么

前面提出过一个具体矛盾：客户端连在节点 A，队列 Leader 在节点 B，消息仍然发送成功。这一节把一次发布从头到尾走一遍，说明它为什么成立。

%%{init: {'theme':'neutral'}}%%
flowchart LR
 subgraph A["节点 A（客户端连这里）"]
 CH[Channel 进程
持有 Leader 位置]
 end
 CH -->|① broker 内部直接寻址| X{路由
fanout}
 X -->|② 一份| Q1[classic 队列
Leader 在节点 B
单副本，直接确认]
 X -->|② 另一份| Q2[quorum 队列
Leader 在节点 B]
 Q2 -->|③ 复制| F[Follower ×2
多数派确认]
 F -.->|④ confirm 返回| CH

第一步，客户端确定目标：Channel 持有的是 Leader 的位置，不是队列的位置。 连接建立后，客户端从集群取得每个目标队列的 Leader 位置，发布时直接按这个位置投递。关键在于「直接寻址」发生在节点 A 内部：客户端仍只连 A 这一台，但 A 上的 Channel 进程根据队列元数据，在 broker 内部直接定位到队列 Leader 所在节点 B，并不经过「先投到一个本地队列、再等转发」这一步。所以「Leader 在 B、客户端连的是 A」并不构成障碍——消息走的是 A 内 Channel 到 B 的 broker 内部通道，不是客户端另建一条网络连接。Leader 换届会改变这个位置，客户端在下一次操作时取得新值，按新值继续发送。

第二步，路由可能分叉：一个 fanout 会同时命中多个队列。 消息到达后先做路由。这一步可能把一条消息复制为多份、投给多个队列，此后每一份走各自的目标队列，各自决定接不接受。整条路径上不存在「整条消息落一次盘」这样的全局动作：一个 fanout 同时绑了 classic 与 quorum 时，同一条消息分别进入两个队列的判定，两边的确认也互不相干。

第三步，写入是异步的：客户端不逐条等待确认。 客户端不是「发一条、等确认、再发下一条」，而是连续发出，确认异步返回。多数派副本确认后，confirm 沿原路返回客户端。这是跨节点发布仍能维持吞吐的原因。

发布这一侧在应用里就是「发消息」+「开 confirm」两件事。发消息用 basicPublish，开 confirm 用 confirmSelect，确认结果由回调异步送达：

// 打开 publisher confirm，之后每条 basicPublish 都会收到一个 ack 或 nack
channel.confirmSelect();

channel.basicPublish("", "orders.quorum", null, "一条订单".getBytes());

channel.addConfirmListener(
 (sequenceNumber, multiple) -> {
 // 成功：这条（或这几条）消息已被 broker 确认接收
 System.out.println("confirmed: " + sequenceNumber);
 },
 (sequenceNumber, multiple) -> {
 // 失败：这条消息没有落地，需要重发
 System.out.println("nack-ed: " + sequenceNumber);
 });

confirmSelect 之后发的每一条消息都会对应一个确认序号（sequenceNumber），回调里拿到这个序号就能知道是哪一条被确认或拒绝。这就是后面第八节要展开的「消息不丢」的第一块拼图——没有 confirm，消息在落盘前丢了，生产者完全无从察觉。

这套步骤不依赖接入节点与 Leader 的关系。实测中，把 Leader 置于不同节点、把客户端连到不同节点轮换，九种排列组合全部拿到确认；其中客户端所连节点既非 Leader、也非副本成员时，发布依然成功。也就是说，客户端连到集群里任意一台节点，消息都能走完上面三步、到达目标队列。

边注：这组实验的一个变体使用两个成员的队列（与前面默认的三成员队列不同），让客户端所连节点落在副本组之外，单独验证。每批 100 条、单组 0.099–0.136 秒（raw-non-leader-publish.log）。

七、两类队列在磁盘上各是什么样子

前面说 classic queue 一个副本、quorum queue 三个副本，落到磁盘上是什么样，把三台节点各自的数据目录摆在一起就看得清。

三类目录并列在同一个数据目录下，各装一种东西，各自的「有几份」也一眼可见：coordination/ 装集群元数据（Khepri 存储），每台节点各一份；msg_stores/ 装 classic queue 的消息本体，只在属主节点 1 有一份（本轮约 252 KB，另外两台根本不存在这个目录）；quorum/ 装每个 quorum queue 自己的 Raft 日志，每台节点各一份（各约 552 KB）。这就是「元数据全体共享、队列内容按类型而定、客户端状态一份都没有」在磁盘目录上的落点。

classic queue 的消息只有一份，且只在属主节点上。 声明在节点 1 的 classic 队列，消息目录就只在节点 1 出现，另外两台节点的数据目录里找不到它。这就是「一个副本」在磁盘上的样子：不是「复制了三份但只标了一份」，是根本没有第二份。

quorum queue 的 Raft 日志每台节点各一份。 同一个队列在三台节点上各有一份日志目录。每份目录的路径形如 quorum/<节点名>/<前缀_编码名>/，节点名那一层就说明了它是谁持有的副本。

边注：msg_stores/ 与 quorum/ 管的是「消息在哪里」。队列自己的定义在另一处，即元数据里（Khepri 那一份）。一个队列因此在两个地方同时留下痕迹：定义在 Khepri 的 Raft 组里，内容在由队列类型决定的那个组里。

classic 的落盘目录内部还能看到更细的形态：属性文件、索引文件与段文件分开，索引按队列内的序号命名。把队列里的消息消费干净之后，大部分文件会消失，只剩属性文件（raw-classic-owner-failure.log）。

边注：这些文件形态是观察到的样子，不是对内部结构的解释。某一时刻目录里有几个文件、多大，取决于当时的段划分与写入量，不必当成稳定特征。

八、发布的可靠性：RabbitMQ 拿什么保证消息不丢

一条消息从生产者发出，到它在 broker 里「真正安全」落地，中间可能在哪几处丢？RabbitMQ 给出的不是单一机制，而是四个可以叠加的手段，每个手段防住一类丢失。这一节把这四个手段讲清，再说明把它们全用上之后，仍然有两种丢失要生产者自己兜底。

手段一：路由退回（mandatory），防「消息根本没进队列」。 默认情况下，一条消息如果路由不到任何队列，broker 会直接丢弃它，生产者拿不到任何提示。发布时带上 mandatory 标志，broker 就会在发现消息不可路由时，用 basic.return 把它退回给生产者，附带原因码。这样「消息没进队列」这件事不再静默。

手段二：持久化（队列 durable、消息 persistent），防「broker 重启后消息没了」。 队列要声明成 durable（重启后队列本身还在），消息要以 persistent 投递模式发出（重启后消息还在）。两者缺一不可：只持久化队列，重启后消息丢；只持久化消息，重启后队列连同消息一起没。持久化消息投到非持久化队列时，按非持久化处理——所以「队列 durable」是前提，不是可选项。即便两者都设了，消息也只在落盘之后才算持久；broker 为了减少 fsync 次数会批量写盘，落盘前节点挂掉，消息仍会丢。这正是它必须和手段三配合的原因。

手段三：Publisher Confirm，防「生产者不知道消息丢了」。 Confirm 是一条消息拿到一个确认的机制，有肯定结果 basic.ack 和否定结果 basic.nack。它解决的是上一段那个「落盘前挂掉」的问题：不用 Confirm，消息在落盘前丢失时生产者无从得知；用了 Confirm，broker 会在消息真正落地后才回 basic.ack，落地前就挂掉的消息不会收到 ack，生产者因此能察觉并决定是否重发。同一个 basic.ack，在不同路径上「落地」的含义不同：

手段四：副本（quorum queue 的多数派），防「单台节点挂掉消息就没了」。 前三个手段保证的是「消息在某一台节点上落稳了」，但经典队列只有一个副本，那台节点一旦永久损坏，落盘的消息照样丢。quorum queue 把消息复制到多数派副本，basic.ack 意味着多数派已经接受，单台节点故障不影响消息存在。这就是「发布可靠性」和前面几章讲的「集群高可用」交汇的地方：副本机制让持久化的消息不再依赖单一节点。

四个手段在应用里不是四段分散的代码，而是落进同一次声明、同一条发布调用里：

// 手段二 + 四：队列 durable=true、类型选 quorum（多数派副本）
channel.queueDeclare("orders.quorum", true, false, false,
 Map.of("x-queue-type", "quorum"));

// 手段三：打开 publisher confirm
channel.confirmSelect();
channel.addConfirmListener(
 (seq, multiple) -> { /* 落地成功，可清理重发缓存 */ },
 (seq, multiple) -> { /* 落地失败，按 seq 重发这条消息 */ });

// 手段一 + 二：mandatory=true（不可路由则退回）、deliveryMode=2（持久化）
AMQP.BasicProperties props =
 new AMQP.BasicProperties.Builder().deliveryMode(2).build();
channel.basicPublish("", "orders.quorum", true, props,
 "一条订单".getBytes());
channel.addReturnListener(returned -> {
 // mandatory 退回：这条消息没有进任何队列
 System.out.println("returned: " + new String(returned.getBody()));
});

四行注释各对上一个手段：queueDeclare 里的 durable=true 和 x-queue-type=quorum 是手段二和四，confirmSelect 是手段三，basicPublish 里的 mandatory=true 和 deliveryMode=2 是手段一和二。缺任何一样，「消息不丢」就断掉一环。

四个手段各有覆盖，但没有一个是「消费确认」。 上面四件事做完，basic.ack 保证的是「这条可路由消息已被所有命中队列接受、且按各自类型的确认边界落了地」。它不代表消息被消费——本文几组发布实验全程没有消费者，确认数与队列留存条数一致，消息一直躺在队列里，直到收尾阶段才被逐条取回。多队列那组的基线 10 条在阶段 1 就拿到了 basic.ack，到阶段 5 才被消费掉，中间五十多秒无人处理。消费侧的确认与幂等是另一篇的事。

两个手段合起来仍有两个洞，要生产者自己兜。 一是重复：多队列场景下 basic.ack 是 AND——只要一个命中队列没接受，整条消息就拿不到 ack。实测让一个 fanout 同时绑 classic 与 quorum，把 quorum 的 Leader 摆到节点 2，SIGKILL 节点 1（classic 的属主），再从节点 2 发布 10 条：

客户端侧：10 条全部失败，客户端库报 NackError，耗时 0.00–0.01 秒；
服务端侧同时读 quorum queue 的条数：从 10 涨到 20，正好增加 10；
同一时刻只往 quorum 发 5 条（对照）：5/5 拿到确认，排除「客户端连不上」或「quorum 不可用」这两个解释；
节点 1 恢复后：classic queue 里仍然只有基线那 10 条，故障中那 10 条一条也没进去（raw-fanout-per-queue.log）。

这几组读数说明三件事，缺一句都会误判：basic.ack 是 AND 不是 OR（一个队列没接受就整体 nack）；basic.nack 不等于哪儿都没进去（quorum 侧已收下 10 条，只是不能替 classic 回答）；客户端从结局里看不出是哪个队列拒绝的（返回的只是一个 NackError，没按队列拆开）。后两条合起来就是重复的来源：拿到 basic.nack 就整条重投，会在已经接受它的那些队列里再写一遍，而 Confirm 机制本身不消重。

二是不可路由的语义陷阱：不可路由消息同样会收到 basic.ack（交换机为它做了判定），但这条路径上的 basic.ack 说的不是「进了队列」。这条本文没有实测，只引官方口径——对 quorum queue 而言，成功返回 basic.ack 的可路由消息，在托管该队列的多数节点没有永久不可用的前提下，RabbitMQ 才给出相应保证；这个保证不覆盖不可路由消息，不覆盖 classic queue。

classic 侧还有一个更硬的证据：属主节点被 SIGKILL 之后，队列里那 51 条持久化消息在节点恢复后一条不少，逐条消费取回验证通过；而故障期间往同一个队列发的 20 条一条都没拿到 basic.ack，恢复后队列里也没有多出这 20 条（raw-classic-owner-failure.log）。本节与相邻几节的读数分别出自 raw-non-leader-publish.log、raw-failover-timeline.log、raw-classic-owner-failure.log、raw-fanout-per-queue.log。

九、消费的可靠性：ack、prefetch 与交付语义

第八节讲消息如何从生产者侧可靠进入，这一节讲它如何从队列侧可靠出去。两侧用的是两套完全独立、互不知晓的机制：Publisher Confirm 只关心消息是否被所有命中队列接受，不关心是否有消费者；Consumer Ack 只关心消费者是否处理完成，不关心消息如何进来。消息不丢，靠的是两侧各自守住自己的一端。

消费确认：basic.ack、basic.nack、basic.reject。 消费者处理完一条消息，需要通过消费确认（consumer acknowledgement）把结果回给 broker，broker 据此决定删除还是保留。三种方法分别表达三种结果：basic.ack 是正向确认，表示处理成功、消息可删除；basic.nack 是否定确认，表示处理失败，可携带 requeue 参数决定是否放回队列，并支持批量；basic.reject 同样是否定确认，但每次只能拒绝一条，不能批量。basic.nack 的能力覆盖了 basic.reject，因此多数实现只用 ack 与 nack。

消息在 broker 侧有两种状态。 队列统计里的 ready 和 unacknowledged 是消息的两种状态：刚入队、尚未投递给任何消费者的消息处于 ready；已投递给消费者、消费者尚未 ack 的处于 unacknowledged，两者之和是队列的总消息数 total。发布时消息从无到有进入 ready；投递时从 ready 转入 unacknowledged；消费者 ack 后才从 unacknowledged 移除。异常路径则往回走：消费者崩溃或连接断开，未 ack 的消息自动从 unacknowledged 退回 ready，等待再次投递。unacknowledged 持续增长而 ready 不涨，通常说明消费者收到消息却不 ack——这是排查消费异常时最先看的一个信号。

%%{init: {'theme':'neutral'}}%%
stateDiagram-v2
 [*] --> ready: 消息入队
 ready --> unacknowledged: 投递给消费者
 unacknowledged --> [*]: 消费者 ack，消息移除
 unacknowledged --> ready: 消费者崩溃或断连，退回重投

消费确认在两类队列里，走的是两套不同的底层机制。 classic queue 的持久化层由「队列索引 + 消息存储」两个组件构成：队列索引记录每条消息的位置、是否已投递、是否已确认，消费者 ack 一条消息，broker 就在队列索引里把它标记为已确认，随后由消息存储的 GC 压缩把这条消息的数据真正回收。quorum queue 则不同——它把消息发布和消费确认都记录为 Raft 日志条目：消费者 ack 一条消息，Leader 就把这条 ack 追加进日志、复制给副本，与消息发布走同一条复制路径。所以「消息被消费」在 quorum queue 磁盘上的表现不是「那条消息被删掉」，而是「多了一条 ack 记录」，已 ack 消息的数据仍留在 segment 文件里，靠日志压缩逐步回收。这个回收机制在 4.3 前有一个缺陷：一条乱序的未确认消息就能挡住整段日志的截断，导致磁盘无界增长；4.3 引入的 Ra v3 压缩允许乱序 ack 与不同速率的确认共存，仍能正常回收空间。两类队列的差别正好落在第七节的磁盘结构上：classic 在 msg_stores/ 里按消息存储的 GC 回收，quorum 在 quorum/ 的 Raft 日志里按日志压缩回收。

确认模式决定交付语义。 交付语义回答的问题是：一条消息保证被投递几次。订阅时选择自动确认还是手动确认，直接给出两种不同的保证：

模式	保证	消息何时从队列移除
自动确认（auto-ack）	至多一次	broker 把消息写入 TCP 后立即移除，不等待消费者反馈
手动确认（manual-ack）	至少一次	消费者显式 `basic.ack` 后移除；未 ack 的消息在连接或信道关闭时自动重新入队

两种保证各有代价。自动确认下，消费者还没处理完就崩溃，消息已经没了，这是丢失；手动确认下，消费者处理完了、但 ack 还没发出去就断连，消息会重新投递，这是重复。官方文档对自动确认的定性是「应视为不安全」，它只适用于消息丢失可容忍的场景（指标、遥测）。可靠消费必须采用手动确认。

prefetch 限制在途消息数。 手动确认下，未确认的消息会一直留在消费者一侧。若不加限制，broker 会把积压消息全部推给消费者，既可能耗尽消费者内存，也让其他消费者无消息可处理。basic.qos 的 prefetch 值规定一个信道上最多同时未确认多少条：达到上限后 broker 停止投递，直到消费者 ack 一条、腾出一个位置。quorum queue 会把 prefetch 上限强制限制为 2000。取值依任务而定：计算密集型取小值（如 1，让多个消费者均匀分摊），IO 密集型取较大值（抵消网络往返延迟）。

可靠消费在应用里就是「设 prefetch + 手动确认」两件事，消费逻辑写在投递回调里：

// 手动确认 + prefetch=10：同一时刻最多 10 条消息未确认
channel.basicQos(10);

DeliverCallback handler = (consumerTag, delivery) -> {
 long tag = delivery.getEnvelope().getDeliveryTag();
 boolean redelivered = delivery.getEnvelope().isRedeliver();
 try {
 process(new String(delivery.getBody()));
 channel.basicAck(tag, false); // 处理成功，确认删除
 } catch (Exception e) {
 channel.basicNack(tag, false, true); // 处理失败，重新入队
 }
};
// 第二个参数 autoAck=false：由上面的回调显式确认，而不是 broker 自动删
channel.basicConsume("orders.quorum", false, handler, consumerTag -> {});

两处要盯住：basicConsume 的第二个参数必须是 false（否则变成自动确认，ack 逻辑形同虚设）；basicAck 的第二个参数 multiple 设为 false，只确认当前这一条，避免误把还没处理完的批量消息一起确认掉。delivery.getEnvelope().isRedeliver() 返回 true 时，说明这是一条之前投递过、但没来得及 ack 就被重投的消息——下面要讲的「重复」正是从这里来的。

重复是可靠消费需要应用侧自行消解的代价。 至少一次的代价是重复：处理成功、basic.ack 尚未发出时连接断开，该消息会被重新投递，并携带 redelivered=true 标记。RabbitMQ 不提供 exactly-once，只保证「至少一次」并标记重投，把「消除重复」交给应用侧：用消息中的业务唯一 ID 去重、用数据库唯一约束兜底、或用版本号与状态机做前置校验。

重复在本实验里有直接记录：失去多数派恢复后，3000 条预置消息共投递 3001 次，多出的一次是消费者被强杀时未及 ack 的那条被重新投递，队列剩余为 0、无丢失——即至少一次交付的粒度（读数出自 raw-quorum-consumption.log，机制细节见下一节）。

至此，消费可靠性的边界明确：手动确认与 prefetch 保证消息不丢、消费者不被压垮；余下的重复由应用以幂等消解。下一节将发布与消费置于同一批故障中，看这两套机制在故障时的表现。

十、故障分轻重：程度不同，RabbitMQ 的应对也不同

故障不只有「有」和「没有」两档，严重程度是逐级上升的。这一节按严重程度从轻到重走一遍：每一级故障下，发布和消费分别会发生什么，RabbitMQ 的架构又是靠哪一层把它扛住或放弃的。三级的差异本身就是信息——同样是节点停掉，停的节点角色不同，架构给出来的结局就完全不同。

最轻的一级：接入节点故障（该节点不承载目标队列成员）。 客户端连的那台节点停了，而且这台节点不承载目标队列的任何成员，既不是属主，也不是 quorum 副本。发布端的表现：broker 强制关闭连接，客户端收到 CONNECTION_FORCED (320)；实测 76 次尝试里 75 次异常，只有 1 次落在线路断开前的窗口里。把客户端改连到存活节点之后，178 次发布连续全部成功（raw-failover-timeline.log）。

消费端的表现：连在这台节点上的消费者会断链一次，异常原文是 StreamLostError: Transport indicated EOF，改连存活节点后 0.5 秒内恢复投递。队列侧什么都没发生：定义、副本、Leader 都不受影响，需要做恢复动作的只有客户端自己。

「只断连接」有一个必须交代的前提：普通集群节点往往同时是接入节点和多个队列的副本节点。一旦停掉的节点恰好还是某个队列的属主或 quorum 成员，它就升级成更严重的中间一级，不再是单纯的最轻一级。

对维护者来说，这一级几乎不需要动手：客户端换节点重连就能继续，队列侧没有状态要修。真正要做的只有一件事——先判断这次停掉的节点到底是不是某个队列的属主或 quorum 成员。判断方法就是看这个队列的成员列表（rabbitmqctl list_queues 的 members 字段）里有没有这台节点；没有，就按最轻一级处理，等客户端自愈；有，就得按下面的中间一级或最重一级处置，而不是停在「反正能重连」的错觉里。

中间的一级：Leader 故障，多数派仍在。 Leader 被 SIGKILL，剩下两个副本还在，多数派成立，组内重新选举。发布端的表现分两层：机制层，官方口径是选举窗口内写操作会被推迟、多数已发布的消息会保留并转交给新 Leader，但部分场景会以 basic.nack 拒绝；观察层，这一轮 3206 次发布全部拿到确认、0 异常，单条最长阻塞 348 毫秒，没有出现 basic.nack。两层不矛盾——前者说的是「可能」的范围，后者只是其中一次观察落在「全保留」这一端，所以这一条不能写成「只停顿、永不失败」的固定保证。

消费端的表现：重新选举期间投递暂停，选出新 Leader 后自动恢复；连在故障节点上的那个消费者断链一次后改连存活节点，前后投递 346 条，连在存活节点的对照消费者投递 348 条，最长无投递窗口 A 0.55 秒、B 0.24 秒。客户端在整个过程中不需要知道 Leader 换了人，它只感觉到一次停顿。

停顿的长短与「怎么停」有关。换成 SIGTERM（正常终止）再测一遍，4507 次发布同样全部成功，单条最长阻塞只有 41 毫秒，比硬杀小一个量级：正常终止的节点有机会先把状态交代清楚，硬杀让组内直接从「失联」开始判定。两种停法各只跑了一轮，这两个数字按单样本口径看。

对维护者来说，这一级是最该忍住别动手的一级。多数派还在，架构会自己重新选举、自己恢复，此刻最不该做的就是急着往组里加成员、删成员或强制改 Leader——成员变更是要等应用落地、且超时会回滚的操作，故障当口去动它，反而可能把本来还能自愈的局面搅乱。维护者该做的是两件事：盯住选举窗口里的写停顿（发布端最长阻塞、消费端最长无投递这两条时长指标），确认新 Leader 真的选出来了（rabbitmqctl list_queues 看 leader 字段是否指向存活节点）。停顿是预期内的、短暂的，只要多数派还在，不需要人工接替。

最重的一级：失去多数派。 三副本里再停一个，只剩一个。需要共识的操作无法继续推进——请求可能被保留、等多数派恢复，也可能在超时后失败。发布端的两种表现必须分开写，否则会得出「失去多数派也不报错」这种错结论：

已登记的信道会被挂住。 故障前就用过这个队列的信道，它的发布不会立刻失败，而是被保留着等多数派回来。实测里这条发布挂了 37.7 秒仍未返回，直到观察窗结束。
新连接会明确失败。 一个新连接的首条发布在 15.01 秒后以 basic.nack 结束，拿到的是明确的否定结局。

差别来自超时预算：信道持有的队列状态里有一个命令超时，值等于 net_ticktime 加 5 秒。本机 net_ticktime 是 10 秒，所以超时是 15 秒，15.01 秒正好对上。已登记那条挂得更久，是因为它在等待期间被反复重试，不是一次判定。

失去多数派之下消费端的表现最反直觉：静默停止。两个消费者做对照，A 连故障节点、B 连存活节点，预置 3000 条积压并限速消费（否则基线就会把积压吃光，分不清「停了」还是「没东西可投」）。失去多数派期间两者都是 0 条投递，连接未断、无异常、不重连，最长无投递 50.59 秒，等于整个观察窗。与发布侧「挂住 / 明确失败」不同，消费侧连「失败」这个信号都没有。应用侧只能靠投递停滞时长监控发现它，靠「连接是否存活」什么也看不出来。

多数派恢复之后，两侧都继续工作：恢复后 A、B 各投递 245 条，最长无投递窗口缩到 2.85 秒。3000 条预置消息最后投递了 3001 次，多出的那一条是消费者 A 被强杀时手里没来得及 ack 的那条被重新投递，队列剩余为 0、没有丢失。这是 at-least-once 的粒度实测，数字如实留档、不做归一化（消费侧读数出自 raw-quorum-consumption.log）。

对维护者来说，这一级没有任何「在线操作」能补救：队列的数据已经不足多数派，加成员、删成员、切 Leader 都救不回一个没有多数派的组。唯一有效的动作是尽快让离队的副本重新上线，多数派一旦回来，两侧就会按上面说的那样自动恢复。所以这一级的运维重心不在「怎么修」，而在「怎么早点发现」——因为消费侧是静默停止、连接还活着，靠连接存活探测什么也看不出来，只能靠投递停滞时长这条监控在 50 秒级别内报警，而不是等应用侧先崩了才后知后觉。

边注：失去多数派时，连「查一下队列现在什么样」的结果也不稳定。Khepri 默认的本地缓存读是最终一致的，失去 Leader 时在可达节点上仍能继续；只有走 Raft Leader 的线性一致读才会在选举期间暂停。本机有两轮实测：一轮在只剩一个副本时 list_queues 失败或超时（元数据 Raft 停在 pre_vote），另一轮同一时刻 list_queues 仍然可用（读到 1911 条）。两轮只在「哪个节点存活」与故障顺序上不同，单样本、结果不一致；两轮差异可能与实际采用的读取路径有关，但现有实验没有定位到，不下确定归因。真遇到时别把一次查询结果当成队列状态判据。

三级故障的全部读数出自 raw-failover-timeline.log 与 raw-quorum-consumption.log，完整输出在模块 README 里逐条可查。

十一、同一个故障，quorum 如何实现高可用

第十节按严重程度讲了「故障下会发生什么」，但没正面回答「quorum 为什么能在 Leader 挂了之后继续服务」。这一节就回答这个：quorum 的高可用，靠的是多副本、多数派、自动选举三样机制叠在一起，而不是某一个节点特别可靠。用 classic 队列作反衬——它只有一份数据，同样的故障下就不可用，正好把 quorum 靠「副本数」这一件事说清楚。

第一样：多副本，数据不在一台节点上。 一个 quorum 队列的每一条消息，不是只落在 Leader 一台节点，而是被复制到组内所有成员。Leader 挂了，消息还在其它副本手里，没有跟着那台节点一起消失。这是高可用的地基——没有多副本，后面两样机制无从谈起。classic 队列就是反面：它只有一个副本，数据只在属主那一台，属主一停，数据也跟着「离线」，谁也读不到。

第二样：多数派，少一个副本不致命。 quorum 的成员数是奇数（典型是三副本），一致性只要求「多数」在线，不要求全部。三个副本坏一个，还剩两个，仍是多数，队列照常可用；坏两个，只剩一个，不再是多数，队列就停摆。所以 quorum 的「高可用」不是「永不坏」，而是「容忍少数副本故障」——这个容忍度直接由副本数决定：三副本容忍一个，五副本容忍两个。classic 没有这个余地：一个副本就是唯一一份，坏一个就是全部，容忍度是零。

第三样：自动选举，Leader 换了人而客户端无感。 Leader 挂掉后，剩下的 follower 自己发起一轮选举，选出一个新 Leader 接替。选举的窗口很短，期间写操作会短暂停顿（第十节实测的单条最长阻塞是 348 毫秒），选出之后发布和消费照常继续；客户端全程不需要知道 Leader 换了人，它只感觉到一次停顿。没有这第三样，多副本和多数派只是「数据还在」，却没有人能继续处理写入。

三样机制叠起来，才是这一节标题那句话的完整答案：quorum 靠「数据复制到多台 + 只需多数在线 + 自动换 Leader」实现高可用，缺一不可。

反过来看 classic，就能把这件事看得更清楚。做一次对照：把 quorum 的 Leader 和 classic 的属主摆到同一台节点 1，再 SIGKILL 节点 1——对 classic 来说它失去了唯一副本，对 quorum 来说它只失去了三份里的 Leader。

	classic（唯一副本离线）	quorum（Leader 离线，2/3 在线）
故障中发布	旧信道与新信道各 10 条，全部被立即拒绝	10 条全部成功确认
故障中消费	挂 67.4 / 68.2 / 68.3 秒后才以 404 失败	正常取到，没有阻塞
属主恢复后	51 条一条不少，逐条消费验证通过	55 条，`online` 回到 3/3

同一个 SIGKILL 落在两类队列上，结局分岔在副本数这一个变量：classic 一份数据离线就是不可用，quorum 少一个副本仍有多数派。这个对照不是要讲 classic 有多差，而是用「没有多副本会怎样」反证 quorum 高可用到底靠的是什么。

对照里还有一个不对称值得一提，但只是支线，不展开：classic 那条路径上发布 0.01 秒就被拒，消费却挂到约 68 秒才有结果，方向性的原因是发布与消费走了两套不同的队列访问封装。完整归因和故障期间管理 API 的观测陷阱，见文末排错索引。

（对照读数出自 raw-classic-owner-failure.log 与耗时归因探针 raw-phase2-timing.log。）

十二、故障之后：RabbitMQ 怎样一步步恢复

第十一节讲的是故障当口 quorum 靠什么不倒下；这一节讲故障之后——离队的节点回来，RabbitMQ 从「少一个副本」走回「全量副本」的完整过程。这个过程不是节点一起来就瞬间完成，而是分几步，每一步都有它自己的判断点。

%%{init: {'theme':'neutral'}}%%
stateDiagram-v2
 [*] --> 离队: 节点故障
 离队 --> 进程重启: 节点回来
 进程重启 --> 续传追平: Leader 补日志
 续传追平 --> 追平验收: Last Log Index 一致
 追平验收 --> 重新参与多数派: 副本回到全量
 重新参与多数派 --> [*]: 队列恢复全量可用
 续传追平 --> 永久不可用: 多数节点永久丢失
 永久不可用 --> [*]: 只能删重建

图里有两条岔路：上面那条是「少数副本暂时离队」的正常恢复，一步一步走到重新参与多数派；下面那条是「多数节点永久丢失」，续传没有对象，直接跌入永久不可用、只能删重建。这一节按上面这条主路走，最后再回到那条岔路。

第一步：节点重启，进程先回来，数据还没追平。 容器重新起来，只说明这个 RabbitMQ 进程活了，不代表它的日志已经和组里其它成员对齐。一个离队很久的副本，落下的是它离开期间产生的所有新条目，重启那一刻它还停在旧的日志位置。所以「进程起来」和「副本追平」是两件事，不能划等号。

第二步：follower 从它离开的地方续传。 这是恢复路径上自动发生、不需要人工干预的一侧。重新上线的副本向 Leader 报告自己的日志位置，Leader 把落下的条目一批批补给它，直到它追到最新。这段时间里集群看起来是健康的，但这个副本还没有真的跟上——如果它还没追平就又发生故障，它的「多数派」贡献仍是空的。

第三步：追平验收，用官方指标，不用容器状态。 追平没有完成，得有一条可复核的判据。最直接的两个是三份 Last Log Index 是否一致、online 副本数是否回到全量；实测里追平后的三份 Last Log Index 是一致的（一轮是 10516、另一轮是 72）。check_if_node_is_quorum_critical 的退出码则是节点级关停检查，它回答的是「再把目标节点关掉，会不会让某个组件或队列失去多数派」，不是「某个队列是否已经追平」，所以它适合在关停前做风险评估，不适合当追平验收。容器报 healthy 只说明进程活着，不说明日志追上了——这一步的判据必须落在日志与副本数上，而不是容器状态。

第四步：追平后重新参与多数派。 副本一旦追到最新，就重新成为多数派里的有效一员。第十一节讲过多数派才是可用性的关键——一个离线副本在追平之前不贡献多数派，追平之后才真正「回来」了。这一步完成，队列才回到故障前的可用状态。

追不平的另一侧：永久不可用。 如果多数节点是永久丢失，而不是暂时离队，那么数据已经不足多数派，续传没有对象、追平无从谈起。这个队列就永久不可用，任何自动化都救不回来，只能强制删除重建。所以恢复过程有一个前提：丢失的只是少数副本。多数一旦没了，走的就是「删重建」而不是「恢复」。

十三、如何选择队列类型和副本位置

前面把机制讲完了，这里落到两个实际决定：选哪种队列类型，副本放在哪。

队列类型，按「要多少可靠性」选。 三种类型本质上是三档不同的可靠性：

classic：数据只在属主节点一份。属主离线队列就不可用，但写入最快、最简单。适合能接受「节点故障时短暂不可用」的场景。
quorum：数据复制到多数节点（典型三副本）。容忍少数节点故障，写入要多一轮复制确认。适合要求「挂掉一个节点还能继续收发」的场景。
stream：按追加日志存、可反复重放，面向大吞吐流。副本也是多数派复制，但不显式 fsync，不受控关机可能丢数据，所以比 quorum 的保证弱一档——RabbitMQ 自己在文档里都说「要更安全就用 quorum queue」。

一句话记住这个选择：classic 是单点、quorum 是多数派、stream 是带重放的多数派（但可靠性略降）。要「不丢且高可用」就 quorum，要「极致简单或能容忍单点」就 classic，要「日志型重放」才考虑 stream。三档的关键不是「谁最好」，而是「代价和可靠性一起涨」：classic 写入最快，代价是属主一挂就不可用；quorum 靠多数派把可靠性顶上去，代价是每次写入多一轮复制确认；stream 在多数派之外加了日志重放，但「不显式 fsync」让它的可靠性比 quorum 弱一档。选型时先定「能接受多大的不可用窗口、能承受多大的写入代价」，再对着这三档取。

副本位置，靠 queue-leader-locator 控制，但只能「建议」不能「指定」。 这个配置决定声明队列时副本落在哪些节点：

两个有效取值：client-local（默认）与 balanced。另外三个已弃用的取值（random、least-leaders、min-masters）在内部都映射到 balanced。
成员怎么挑：声明队列时，声明它的客户端所连的那台节点一定被放上一个副本；其余成员在队列总数少于 1000 时按「哪个节点同类队列成员最少」来挑，达到 1000 后改随机。
关键限制：client-local 对 quorum、stream 只是建议——它保证副本落在声明节点，但不保证这个节点一直是 Leader，因为 Leader 由之后的 Raft 选举决定。balanced 则去均衡 Leader 分布。

由此，那句「Leader 位置影响跨节点流量与热点」要这样理解：热点确实存在，但配置只能把副本放过去、不能把 Leader 钉死。要治理热点，靠的是选节点，不是指望一条配置锁住 Leader。

副本位置之外，还有成员变更的边界。 副本数不是定死就不能动的，声明之后运维还能手动加删成员，但有两条要记住：

加成员默认是 promotable（非投票成员），声明时创建的才是 voter；只加不提升，就不参与多数派计算。
删不掉最后一个成员（返回 last_node）；成员变更 20 秒超时会回滚。

（成员变更更细的底层行为——比如 ra:add_member 要等 applied 才真正落地——见排错索引与源码，这里不展开，不影响选型这个主线。）

十四、收口：整条链的分工与保证边界

把整条链各方的分工摆在一起看：Publisher Confirm 负责把「消息已被接受」这件事如实告诉你，它不负责不重复；客户端重连负责把「接入节点没了」变成一次可恢复的断线，它不负责不中断；消费端幂等负责兜住 at-least-once 语义下的重复投递；而队列类型与副本放置，决定上面每件事发生在哪种故障模型里。

几个「安全」类说法，都成立于一个具体的故障模型，脱离那个模型就不成立：

「quorum queue 能容忍一个节点故障」成立于三副本、且任一时刻仍有多数派在线。关键不是故障是否「同时」发生，而是第一个副本尚未恢复之前，第二个故障到来同样会失去多数派。
「已确认的消息不会丢」成立于「托管该队列的多数节点不是永久不可用」。一旦多数节点永久丢失，这个保证就不复存在，队列只能强制删除重建。
「客户端不需要知道 Leader 在哪」成立于客户端能连上任意一台存活节点。接入节点故障时，需要换节点的是客户端自己。
「消费不会丢」——本文实验只验证到 at-least-once：3000 条投递了 3001 次，没有丢失，但有重复。

所以 quorum queue 并不保证「不丢消息」，也不保证有多数派就等于 exactly-once。basic.ack 保证的是「这条可路由消息已被所有命中队列接受」；消费侧的补偿与幂等是另一件事。

最后跨产品对照一句：RabbitMQ 与 RocketMQ 在这类系统上的差别是副本粒度——RocketMQ 复制的是整份日志，RabbitMQ 在 quorum queue 上的复制单位是队列。这一句的依据是本系列第四话的副本粒度结论，加上本文实测到的 RabbitMQ 侧副本范围。

排错索引

遇到下面这些现象，按「判据 → 处置」对一遍。最后一列指向原始日志或证据条目，每一条都能回溯。

现象	判据 / 原因	处置	证据
读到的队列条数比 `basic.ack` 成功的条数少	条数指标按周期上报（quorum queue 上是 Ra 的 tick 回调，默认 5 秒），读到的是上一份快照	等两次读数一致再取值；不要据此判定丢消息	`raw-failover-timeline.log` 末尾
管理 API 查不到刚建立的连接	连接表是周期性采集的	轮询到出现为止，别把「查不到」当成「落在别的节点」	`raw-classic-owner-failure.log`
故障期间管理 API 仍报 `state = 'running'`，`node` 指向已离线节点	`state` 反映的是元数据里的记录，不是可用性	用 `quorum_status` 与 `list_queues` 判断；但这两个查询本身也可能读不到（见下一条）	`raw-classic-owner-failure.log`
`transfer_leadership` 返回非零	目标已是 Leader 时退出码为 69，且结果头在 stdout、错误在 stderr	接受 `already the leader` 为成功；判定文本要两路都读	`raw-classic-owner-failure.log` 首行
`list_queues` 在失去多数派时可能失败或超时	Khepri 的缓存读与线性一致读行为不同，两轮实测结果不一致，归因未定（见第十节边注）	别把一次查询结果当成确定的队列状态判据；先看元数据存储状态再下结论	`raw-failover-timeline.log`、`raw-quorum-consumption.log`
消费挂住很久才报 404	classic 的读取路径有 2000 × 30 毫秒的重试预算	这是 broker 侧的耗时尺度（约 1 分钟量级）；应用侧的超时按自己的 SLA、幂等与重试策略设，不必照抄这个预算	`raw-phase2-timing.log`
节点重启后立刻读写	容器起来 ≠ 副本追平	用 `quorum_status` 的 `Last Log Index` 与 `online` 验收	`raw-failover-timeline.log`、`raw-classic-owner-failure.log`
发布拿到 `basic.nack`，以为这条消息哪儿都没进去	`basic.ack` 是所有命中队列的 AND；被拒绝的那一个决定了结局，别的队列可能已经收下了	重投前先按消息 id 去重，或把多队列命中改成显式检查；不要假设「`basic.nack` = 没写入」	`raw-fanout-per-queue.log` 阶段 3 / 3b
消费者「连着但收不到消息」，日志里什么都没有	失去多数派时消费是静默停止：连接不断、不报错、不重连，只是不再投递	用「投递停滞时长」而不是「连接是否存活」做告警	`raw-quorum-consumption.log` 阶段 3
重启节点后出现少量重复消费	消费者所在节点被强杀时，手里未 ack 的消息会被重投；这是 at-least-once 的粒度	消费侧做幂等；不要期望重连后不重复	`raw-quorum-consumption.log` 阶段 5（3001 / 3000）

参考资料

RabbitMQ, Clustering Guide. https://www.rabbitmq.com/docs/clustering —— 集群复制什么与不复制什么、客户端操作的路由、奇数节点与 Leader 放置
RabbitMQ, Metadata Store. https://www.rabbitmq.com/docs/metadata-store —— Khepri 保存的范围，及其与 Mnesia 的关系（与 partitions 页口径冲突，见正文第五节）
RabbitMQ, Quorum Queues. https://www.rabbitmq.com/docs/quorum-queues —— Leader 与 Follower 的角色、「操作」的定义、Publisher Confirm 的确认边界、组大小与容错、成员与放置
RabbitMQ, Reliability Guide. https://www.rabbitmq.com/docs/reliability —— 选举期间投递暂停、消费者是否要自己恢复
RabbitMQ, Publisher Confirms. https://www.rabbitmq.com/docs/confirms —— 三种路径分别何时发 confirm、没有 confirm 就没有保证
RabbitMQ, Network Partitions. https://www.rabbitmq.com/docs/partitions —— 4.3.0 移除了什么、失去多数派时哪些操作停摆
RabbitMQ, Streams. https://www.rabbitmq.com/docs/streams —— stream 的副本管理、确认边界与恢复动作（本文选型表的官方依据）
RabbitMQ Server v4.3.5 源码（rabbit_quorum_queue.erl、rabbit_queue_location.erl、rabbit_fifo_client.erl、rabbit_amqqueue.erl 等）—— 成员变更的三条边界、Leader 放置的实现、classic 读取路径的重试预算
本系列：第一话《RabbitMQ 的架构与特性》、第四话《RocketMQ 4.x 的架构与机制》—— 前者是本文的队列类型基础，后者的副本粒度结论是本文末节跨产品对照的依据

演示代码：三节点集群的编排与全部实测脚本在 GYD 仓库 infra/rabbitmq-cluster/。集群的起停、运行顺序、完整命令、原始输出与每一步的预期观察点，都在该模块的 README 里；正文里每个读数的出处也在那里。这篇文章不复现命令与输出——它负责机制，复现交给仓库。

第四话｜RocketMQ 4.x 的架构与机制：一条消息从发送到消费的全程

Wed, 18 Feb 2026 00:00:00 +0000

一条消息从生产到消费，中间经历了哪些环节？网络是怎么连接的，磁盘又是怎么存储的？

先把 RocketMQ 4.x 的全貌铺开：有哪些角色、各自负责什么、谁跟谁通信（一）。然后跟着一条消息走完主链路——客户端启动后怎么找到 broker（二），生产者怎么把消息发出去（三），broker 收到之后怎么落盘（四、五），主从之间怎么保证不丢（六），消费者又是怎么把它取走（七）。剩下的几节停在这条链路上挂着的功能上（八～十一），逐个说明它的取舍与代价，最后一节把这些代价来源并排放在一起（十二）。

全文以 apache/rocketmq 4.9.7 为准，覆盖的是传统 Remoting 客户端与静态主从部署。5.x 引入的 Proxy、gRPC 客户端、Controller 自动切换、TimerWheel 毫秒延迟与 Topic 类型约束，都不在本文范围内。正文引用的官方文档（Design_Store.md、Design_Filter.md、Design_Trancation.md、Feature.md、Example_Delay.md 等）均指 apache/rocketmq 仓库 rocketmq-all-4.9.7 tag 下的 docs/cn/ 原文，不是随时变动的 develop 分支。凡本机没跑过的机制，正文会写明是「结构推导」，不当成已证实的结论。

边注：文中标为「边注」的段落是限定与例外，不影响主线，第一遍可以跳过；其中几条会改变边界，真用到那一节时值得回头看。

一、全貌：四个角色，五条通信线

图上这五个方框就是 RocketMQ 4.x 的全部角色，彼此独立、没有包含关系：浅蓝的两个是客户端（Producer 和 Consumer），浅绿的三个是服务端（NameServer，以及 Broker 的主与从）。箭头方向就是连接（TCP）的发起方向，线上的编号与后文逐条对应；注意它不等于数据流向——⑤ 里连接由从节点发起，数据却是主节点往从节点写。

角色	负责什么	不管什么
NameServer	broker 的注册与存活、每个 topic 在哪台 broker 上有几个读写队列	不存消息、不记位点；节点之间互不通信
Broker	接收并存储消息、投递给消费者、存集群模式的消费位点；主从一组时，从节点做副本	不管寻址：客户端连它之前，先向 NameServer 拿到它的地址
Producer	拉路由、选队列、把消息发出去，按返回码决定要不要换队列重试	不参与存储与投递
Consumer	拉路由、做 rebalance、长轮询拉消息、上报位点	不负责「不重复」，那是消费端幂等的事

四个角色之间，普通消息主链路上的通信数得出来五条，发起方都在客户端或从节点一侧（图上的编号边就是它们；① 和 ② 的发起方各有两个，所以各画了两条）：

① Producer / Consumer → NameServer：每 30 秒拉一次路由，换回一张「哪个 topic 在哪台 broker 的第几个队列」的地址表；
② Broker → NameServer：主和从各自每 30 秒上报一次，整张 topic 配置一并带上；但只有主的那份进路由表（队列数与读写权限），从的那份只用来证明它自己活着；
③ Producer → Broker：发送请求，走一条常驻连接；
④ Consumer → Broker：投递走长轮询；位点随拉取请求捎带、另按固定间隔批量写回；
⑤ Slave → Master：主从复制，从节点主动连上主节点的 HA 端口去拉，不是主推过去。它连哪个地址，是向 NameServer 注册时从响应里问回来的（见第六节）；

五条线里没有一条是服务端回连客户端：每次通信都由发起方主动去连，服务端之间的 ② 与 ⑤ 也一样。在这条普通消息主链路上，消息一律由客户端主动发起，服务端只应答。 唯一的例外是事务消息回查（第十一节）：那时 Broker 会主动向 Producer 发起回查请求，是后文才加入的一条反向 RPC，不在主链路这五条里。

角色和通信线之外，还有一个概念要在全貌里定下来：组（group）。RocketMQ 的客户端不是孤零零一个实例，而是挂在一个组名之下，组是它后面几乎所有机制的作用域。

消费组（Consumer Group）：rebalance、消费位点、重试与死信，都按「主题 + 消费组」记。同一个消费组内的实例，共享一份位点、分摊队列；不同消费组各自独立消费同一主题，互不影响。同组的实例订阅关系必须一致，否则 rebalance 结果不可预测。
生产者组（Producer Group）：普通发送里它几乎不做事——不参与选队列、不分配队列，名字更多是业务上的归类。它真正起作用的地方是事务消息回查（第十一节）：broker 回查本地事务结果时，要到一个生产者组里去找还活着的实例来回答。

把组立住之后，后面几节的「位点按组记」「rebalance 在组内做」「回查找同组实例」才有着落。与组并列的另一个基础概念是 topic 与队列的关系：

topic 是客户端手里的逻辑名字，到了 broker 就成了一份配置，队列数记在这份配置里（读、写各一个数字，本文都填 4），每条队列都落在某台 broker 上——本文只有一个 brokerName，所以这 4 条都在 broker-a 上。

读与写是两个独立数字，因为它们在客户端各管一段：拉回路由时，发送那侧只取写队列摊成发送列表，消费那侧只取读队列摊成订阅列表，两个列表可以不一样（本文都填 4，看不出差别）。

队列不是消息的容器，是消息的归属：开 4 条队列，等于把「谁来写、谁来读、按什么顺序读」切成 4 份。发送时挑一份写进去；消费时每个实例领一份，同一个消费组内，一条队列同一时刻只归一个消费实例。这里说的是集群消费模式；广播模式不同，每个实例都消费全部队列，位点也保存在本地（第七节）。

它管归属，不管消息存在哪：磁盘上它只留下一个索引目录 consumequeue/<topic>/<queueId>/，那个目录就是队列唯一的物理残留，消息本体落在哪一层是第四节的事。

图上把同一个主题的 4 条队列画成了三副样子：发送侧写、消费侧读、存储侧只剩目录。这个数还能拿来自查：主题建 4 条队列，发送侧就摊出 4 条并行车道；消费侧（同一消费组内）最多 4 个实例真正并行，第 5 个分不到队列、只能空转（第七节）；顺序消息的并发上限同样是 4。三个 4 是同一个 4——队列数在消费侧就是并行度上限，它在第三节被定死，第八节收账。

边注：队列在客户端不是一个裸编号，而是「topic + brokerName + queueId」三件套：同一个主题在两个 brokerName 上各有一条 0 号队列，它们不是同一条；主从共享同一份队列定义，从节点也不会另外多出一份。

下面各节对照的集群就是三个容器：一个 NameServer，加 broker-a 的一组主从，主题显式建成上面说的那 4 条读写队列。客户端到 broker 那条连接在第三节展开，broker 内部怎么存消息在第四节。

二、客户端启动之后：从 namesrvAddr 到一条真的建起来的连接

RocketMQ 的客户端不直连 broker。它拿到 namesrvAddr 之后做的第一件事，是去 NameServer 换一份路由——和 Kafka 客户端先连一个 bootstrap 节点换元数据是同一个路子，区别在于 NameServer 把自己压到了最小。

NameServer 是一张节点之间互不通信的路由表。 它存三类东西：

broker 注册表：有哪些 brokerName、每个下面有哪些 brokerId、各自地址；
每台 broker 的存活状态；
每个 topic 的路由：只到「哪台 broker 上有几个读队列、几个写队列、可读可写否」为止。

哪条消息落在哪个队列、消费位点走到哪，它一概不记。

这三样都不是它自己维护出来的，是靠两个每 30 秒一次的动作拼出来的：broker 上报心跳（顺带把整张 topic 配置报上来，只有主节点那份进路由表，所以队列数是 broker 报的，不是它定的），客户端来拉路由。既然节点之间不通信，它也就没有选主、没有一致性协议——每台各存一份上报结果，容错靠客户端在 namesrvAddr 里多写几个地址。

客户端拉回来的这份路由不是权威真相，而是一张最终一致的可用地址表：broker 刚下线、客户端手里的路由可能还指着它，这个窗口最长就是一个刷新间隔（默认 30 秒）。

路由拿到了，接下来是连。这一步的变数全在地址上：客户端要连的那个地址由 broker 报给它，它自己决定不了。

而这个地址由 brokerIP1 决定。它是 broker 对外通告的地址，写进 broker.conf：

# broker.conf
brokerIP1 = 192.168.31.132 # 宿主机可达的局域网 IP

这个值必须是客户端所在的那台机器也能到达的地址。在 Docker 里把它填成容器名（brokerIP1 = broker-a-master），只有容器网络内解析得了这个名字，宿主机上的客户端解析不了，后果直接就是连不上。

两步合起来，一次启动的时序是这样的：

%%{init: {'theme':'neutral'}}%%
sequenceDiagram
 autonumber
 participant C as 客户端
 participant NS as NameServer
 participant B as Broker（主）

 B->>NS: 注册 + 心跳上报（每 30s）
 C->>NS: 拉路由（启动时 + 每 30s）
 NS-->>C: brokerIP1 通告的地址 + 存活状态 + 队列数
 C->>B: 用这个地址建常驻连接

三、发送一条消息：一次 TCP 往返，和三道可以单独拨动的开关

生产者把消息送到 broker，在网络上就是一次请求—响应往返：一条 TCP 长连接上发出一个带序号的请求帧，broker 把消息追加进 CommitLog，再回一个返回码。这条路上有三道开关——客户端换队列重试、刷盘策略、主从复制——每一道都能单独拨动：关掉换响应时间，打开换「不丢」。

%%{init: {'theme':'neutral'}}%%
flowchart LR
 A[应用调用 send] --> B[选队列 · 组装请求]
 B --> C[TCP 长连接 10911]
 C --> D[broker 校验 · 追加 CommitLog]
 D -->|追加成功| E{等刷盘 · 等从节点}
 E -->|默认都不等| F[返回码 0/10/11/12]
 F -. 重试：换队列，上限 2 次 .-> B

图上是同步发送的六个环节：选队列在客户端，中间一节是那条 TCP 长连接，broker 侧只有「校验 + 追加」是必做的，后面两步等不等由配置决定；虚线那条是重试，只在抛异常或返回码命中白名单时才走。

连接与协议

连接是 TCP 长连接，上面跑的是自定义二进制协议：4.9.7 的客户端与 broker 之间既不是 HTTP 也不是 gRPC——4.9.7 的代码库里没有 proxy 模块，两端只说这一套 Remoting 协议（5.x 才把 gRPC 客户端与 Proxy 作为另一条路线加入，见引言的范围说明）。发送、拉消息、查位点共用同一种帧：4 字节长度前缀切边界，头在默认配置下通常是 JSON（请求码、序号与各请求自带的字段；序列化格式由帧内的序列化类型标记决定，可切换），体就是消息体。

连接按 broker 地址存在客户端实例里：同一个进程的多个 producer 共用一条，一条连接上并发跑多个请求。空闲 120 秒（clientChannelMaxIdleTimeSeconds）会被断开，下次要发时重建，建连超时 3 秒。所谓「常驻连接」，省掉的是重复握手，不是永不重建。

客户端六件事与三种发送模式

这一步是六件事：

校验消息：体非空、不超 4 MiB、topic 合法；
取路由：手里没有就回头向 NameServer 拉；
选队列：sendWhichQueue 计数器对着队列列表轮询，自定义选择器可覆盖；
查出 broker 地址；
生成全局唯一 ID（UNIQ_KEY）并按需压缩：体超过 4 KiB 时自动压缩，阈值 compressMsgBodyOverHowmuch 默认 4096，压缩标记写进消息标志位 sysFlag；
写进连接。

之后怎么等，有三种模式：

模式	`send` 的返回	失败怎么知道	重试
同步	阻塞到响应或超时（默认 3000ms）	抛异常，或返回非 `SEND_OK`	换队列，最多 2 次
异步	立即返回 `null`	回调里拿到异常	换队列，最多 2 次
单向	立即返回 `null`	无从知道	无

三种模式在代码里就是三个不同的调用：

// 同步：阻塞到拿到 SendResult 或超时
SendResult r = producer.send(msg);
if (r.getSendStatus() != SendStatus.SEND_OK) {
 // 返回码是 10/11/12 那一类：消息已写，但保证没兑现
}

// 异步：立即返回，结果走回调
producer.send(msg, new SendCallback() {
 @Override public void onSuccess(SendResult r) { /* queueId、SendStatus */ }
 @Override public void onException(Throwable e) { /* 超时或抛异常 */ }
});

// 单向：写完就返回，没有结果也没有回调
producer.sendOneway(msg);

单向是协议层的事：帧头置了单向标记，broker 处理完不写任何响应，调用方既拿不到成功也拿不到失败。超时也不等于没写进去：3000ms 只是客户端愿意等的窗口，超时那一刻 broker 可能已经把消息追加进 CommitLog 了。

边注：两处数值官方文档与代码不一致，正文按代码写。sendMsgTimeout 官方说 10 秒，代码默认 3000ms；异步重试官方说「0 次」，代码是 retryTimesWhenSendAsyncFailed = 2，而且重试时会像同步一样优先换一个 broker（挑不出别的才回到原队列）——那句「0 次」很容易被读成「异步不重试」。

broker 侧两道开关

能不能回 SEND_OK，由 broker 侧两道开关决定。帧到达后先校验（topic 在不在路由里、有没有写权限、队列号是否越界），通过就追加进 CommitLog（追加的细节在第四节展开）。追加成功不等于能回 SEND_OK：默认配置下它立刻回，两道开关各自能让它多等一段。这两道都在 broker 端，客户端改不了。

第一道是刷盘策略 flushDiskType。 ASYNC_FLUSH（默认）下，消息追加进 PageCache 就算写成功，刷盘交给后台线程：按 flushIntervalCommitLog（默认 500 毫秒）醒一次，攒够 flushCommitLogLeastPages（默认 4 页，16 KiB）才真刷，攒不够也会在 flushCommitLogThoroughInterval（默认 10 秒）后全量刷一次。成功与否只看「追加」这一步，掉电丢的就是这一瞬还没落盘的那段。

SYNC_FLUSH 则要求 fsync 完成才回：写线程把「请刷到这个偏移」挂进刷盘线程的请求队列，等它落盘。它不是一个请求一次 fsync：队列里的请求会被攒成一批，刷盘线程挨个检查各自的目标偏移，已刷位置还没盖过谁就刷一次、盖过了的直接放行——批里的第一个几乎总在触发刷盘，后面那些「已经被刷过头了」就不必再刷。一次 fsync 摊到整批上，这才是同步刷盘还能留住吞吐的原因。

等不到就由 syncFlushTimeout（默认 5 秒）截断：这条计时不由发送方自己守着，而是一条独立的看门狗线程（FlushDiskWatcher）盯着，到点直接把请求标记成超时。刷盘线程再忙，发送方也不会无限期挂着。

第二道是复制角色 brokerRole。 取 ASYNC_MASTER（默认）、SYNC_MASTER 或 SLAVE，主从成对配：主节点配前两者之一，从节点配 SLAVE。ASYNC_MASTER 下主节点的确认不等待从节点，主宕机时丢的是「主已写、还没推给从」的那段偏移差。

SYNC_MASTER 下，写线程挂一个请求进同步等待队列，等从节点复制到的最大偏移追平这条消息的结束偏移：追平回 PUT_OK，超过 slaveTimeout（默认 3 秒）回 FLUSH_SLAVE_TIMEOUT。有一种情况连等都不等：判定要求「有从节点连着」和「主已写但还没推给从的偏移差小于 haSlaveFallbehindMax（默认 256 MiB）」两条同时成立，任一不满足就直接回 SLAVE_NOT_AVAILABLE，不进入等待——所以从节点掉线时，发送耗时反而比它在线时更短。

还有一层要分清：主节点等的是「从节点的复制偏移追上了」，不是「从节点已经落盘」。从节点收到数据同样是先追加进自己的 CommitLog，fsync 与否由从节点自己的 flushDiskType 决定——同步复制和同步刷盘是两台机器上各自独立的开关，想让副本也严格落盘，两台的刷盘策略都得打开。

返回码与「不丢」组合

返回码	含义	消息还在不在
`0` `SEND_OK`	该等的都等到了	在
`10` `FLUSH_DISK_TIMEOUT`	等刷盘超时	在，只是还没落盘
`12` `FLUSH_SLAVE_TIMEOUT`	等从节点超时	在
`11` `SLAVE_NOT_AVAILABLE`	从节点不可用，没等	在

四个码里只有第一个表示「你要的保证已经兑现」，后三个都是「消息已经在这里了，但保证没兑现」。它们不算异常：客户端拿到后不抛 MQBrokerException，默认也不会换 broker 重发（retryAnotherBrokerWhenNotStoreOK 默认关闭）。

边注：SLAVE_NOT_AVAILABLE 的码值是 11、FLUSH_SLAVE_TIMEOUT 是 12，与名字顺序相反，翻日志时别按顺序猜。

三道开关合起来定义的是「不丢」。 两道在 broker 端（刷盘、复制），第三道在客户端（换队列重试），三道各自独立、可以只开其中一道：

环节	开关	默认	打开后多等什么	上限	超时码
客户端	`retryTimesWhenSendFailed` / `retryTimesWhenSendAsyncFailed`	2（同步共发 3 次）	换队列、尽量换 broker 重发	—	—
单机	`flushDiskType`	`ASYNC_FLUSH`	一批请求一次落盘确认	5 秒（`syncFlushTimeout`）	`10`
主从	`brokerRole`	`ASYNC_MASTER`	一次从节点追平确认	3 秒（`slaveTimeout`）	`12` / `11`

三道全开是最严的组合，代价是每条消息的响应时间被最慢的那一环拖住；三道全关就是默认那副样子：消息还没落盘，SEND_OK 就回去了。

配置改不了，但单条消息能让它们不等：属性 WAIT 为 false 时（msg.setWaitStoreMsgOK(false)，缺省是 true），broker 拿到它就不把请求挂进等待队列，直接回 SEND_OK——落盘和复制照旧在后台做，只是这条消息不等它们。

「不丢」保住了，「不重」不在这里。 一次超时或一次重试，都会让同一条消息在 CommitLog 里出现两次，UNIQ_KEY 与消息体都一样——发送侧不去重，它给的是 at-least-once。要消掉重复投递，只能靠消费端幂等；事务消息补的是「本地事务与消息发送之间的一致性」（第十一节），它不保证消费结果不重复，也替代不了消费端幂等。

发送失败三类走向

判据是返回码白名单：

第①类：返回码命中白名单（1 / 14 / 16 / 17 / 204 / 205，即系统错误、服务不可用、无权限、主题不存在、无买家 ID、不在当前单元）→ 静默换队列重试，调用方看不见；
第②类：不在白名单 → 有部分结果就先返回，否则抛 MQBrokerException；
第③类：不抛异常，但状态不是 SEND_OK（就是上面那张返回码表的后三行）→ 原样交给调用方。

第③类最容易踩：主从同步复制下停掉从节点，发送返回 SLAVE_NOT_AVAILABLE，既不抛异常也不重试，耗时反而比从节点在线时更短——它并没有等（failmode）。消息确实写进了主节点的 CommitLog，返回码只是如实说明那份保证没兑现。

自动建主题定死队列数

发到一个不存在的主题，先暴露出来的信号是查不到路由：客户端手里没有这个 topic 的路由，显式调 getTopicRouteInfoFromNameServer(topic, 3000L) 查一次会直接抛 MQClientException CODE=17（TOPIC_NOT_EXIST）。随后的真正 send(...) 并不报这个错——发送请求会带上自动建主题专用的键 TBW102，broker 收到才建主题，队列数取 min(客户端 4, broker 8) = 4。也就是说：「主题不存在」报错发生在显式查路由这一步，发送路径本身走的是自动建主题。这个数一旦落下来就是所有人共用的：第一个发消息的客户端，替后面所有人定死了队列数，而顺序消息的并发度上限正好等于它（第八节）。自动建主题是练习环境的能力，生产里主题应当预先建好、定好队列数与消息类型。

四、Broker 收到之后：一份只追加的日志

只追加的日志

消息到了 broker，先落成一份只追加的文件。它不做队列级分文件：什么主题、哪条队列来的都一样，按到达顺序接在文件末尾。这份文件叫 CommitLog，官方文档里那个「混合存储」说的就是它，一个 broker 实例上的队列共用这一份日志。

「只追加」是它快的原因，也是它全部的限制。 文件通过内存映射摊进进程地址空间，写消息就是往映射区末尾顺序搬字节：不用在文件里找位置，也不用为每条队列各维护一份写指针，写入位置只有一处。

写满 1 GiB 切下一个文件，文件名就是它承接的起始偏移。磁盘上第一个文件叫 store/commitlog/00000000000000000000，往后每切一个，名字就加 1 GiB（inspect-storage）。文件名自带顺序，重启时按名字排一下就得到这份日志的范围。

消息长什么样

它不做对齐，长度写在记录自己头上：开头的 4 个字节是这条消息的总长度，紧接着一个标记值，用来确认「这里确实是一条消息的开头」。往后依次是队列号、它在队列里排第几、它在日志里的物理偏移、产生与落盘的时刻，末尾是消息体、主题和属性串。消息体长短不一，每条记录的长度也就不一样。

长度写在数据自己头上，换来两件事：从头往下走时，读 4 个字节就知道这条到哪结束，跳到下一条接着读；手上已经有一个物理偏移时，读那 4 个字节就能把整条取出来。前者是顺序重放（重启恢复、后台线程补索引）用的，后者是定点取消息用的，同一套字段支撑两种读法。

属性也在这条记录里，和消息体、主题放在一起。 tag 与 key 是拼成一串的键值对，tag 的原文只有读这条记录才拿得到；落到索引时，broker 对 tag 字符串算一次 hashCode，把这个数字另外抄一份进索引条目。于是同一个信息有了两个位置：tag 的原文只在日志正文里，它的 hashCode 只在索引条目里——要拿原文必须读正文，拿 hashCode 只看索引就够。这个位置之分，是后面消费过滤与定时投递能「只靠索引、不读正文」的地基。

代价是它只有一个顺序，而落下来的内容混在一起：前 110 条消息里出现了 12 个不同主题，相邻两条主题不同的有 22 次，业务主题的消息之间夹着延迟消息、半消息、位点变更事件。混写把队列顺序抹掉了：这份文件只提供一条落盘顺序。

五、索引：消费索引与查询索引，日志的两个派生物

日志本身只有一条落盘顺序，回答不了「某条队列的下一条在哪」「某个 key 的那条在哪」。索引就是为这两个问法各建的一份派生物。

两份索引

「某条队列的下一条消息在哪」，这份日志回答不了。按顺序读出 gyd-c03-send 0 号队列那 6 条消息，得在 1 GiB 里从头往下翻、边翻边筛；而它们物理上分散在偏移 1346 到 17857 之间，中间隔的全是别人的消息。索引存在的理由就是这个，并且按两种问法各建一份：

索引	回答什么问题	怎么组织	谁在用
消费索引	某条队列的下一条消息在哪	一条队列一个目录 `consumequeue/<topic>/<queueId>/`	消费
查询索引	某个 key 的那条消息在哪	按时间切文件，文件名是创建时刻	排查

两行只在问法上不同，组织方式就跟着不同：消费的问题天然按队列切，查询的问题天然按时间翻。查询索引不需要额外打开，messageIndexEnable 默认是开的。

定长条目与寻址

反过来：消费索引的条目是定长的，每条只装三件事——消息在日志里的物理偏移、这条消息有多大、一个 8 字节的比较值。这个比较值装什么，随主题变：普通业务主题装的就是 tag 字符串的 hashCode，发送时对 tag 原文算一次 hash、把结果抄进来，原文仍留在日志正文里；定时消息的内部主题装的是到期投递时刻（第十节）。长度固定，位置就能算：第 N 条落在「N × 每条长度」这个字节位置上。

两份索引的读法，和日志那套「读长度跳下一条」正好是两套寻址：日志是顺序读，读开头的总长度、跳过它、接着读下一条；消费索引是定点读，第 N 条的位置由 N × 20 一次乘法算出来。broker 处理一次读请求，就是先乘出字节位置，再按索引文件大小取余，得到「哪个文件、文件内哪个位置」。这份索引文件同样按固定字节数切开，文件名就是它承接的那段起点，和日志文件一个命名规则。

	日志（CommitLog）	消费索引（ConsumeQueue）
每条长度	不固定，随消息体变	固定
怎么到下一条	读开头的总长度，跳过去	序号 × 每条长度，一次乘法
顺序有几条	全 broker 一条	每个队列一条

定长还多给了一件事：折半比较。 要找「某个时刻之后的第一条」，中间那条的位置同样是一次乘法算出来的，所以能在这串条目上做二分；把消费进度挪到「某个时刻之后」这个操作，靠的就是它。

两份索引都只回答「去哪找」，不回答「是什么」。 条目把人领到日志的某个位置就结束了；消息本体始终只在日志里存一份。

边注：定长条目的 20 字节按 8 + 4 + 8 切开，依次是物理偏移、消息长度、那个比较值；消费索引一个文件装 30 万条（6,000,000 字节）换下一个。比较值装的什么随主题变化：普通业务主题装 tag 的 hashCode，SCHEDULE_TOPIC_XXXX（定时消息的内部主题）装的是到期投递时刻。同一个位置按主题换语义，就是这一份定长布局能被 tag 过滤与定时投递共用的原因。

查询索引：key 怎么哈希，怎么避冲突

查询索引按 key 找人，key 是一条消息可选的业务主键（比如订单号）。它的文件结构分成三段：一个 40 字节的文件头，接着一串哈希槽，最后是定长的索引条目。写一条 key 时，先对这个 key 字符串算一个 keyHash（就是 Java 的 Math.abs(key.hashCode())），再用它对槽数取余，落到某个槽上。

这个槽里存的不是 key 本身，而是一个指向索引条目的位置。每个索引条目 20 字节，装着 keyHash、消息的物理偏移、一个相对文件起始时刻的秒数、以及上一条冲突条目的位置。两个不同的 key 算出同一个槽时，新条目就用这第四个字段回链到旧条目，在槽后面串成一条链表；找 key 时沿这条链比对 keyHash，命中才返回物理偏移。

所以查询索引也是「先哈希定位、再沿链确认」，和第九节 tag 的 hashCode 一样，keyHash 相同并不等于 key 相同，最终要靠读回日志里的 key 原文再核一次。它按时间切文件，是因为排查时「按时间段翻」比「按队列翻」更自然，文件名就是创建时刻。

写路径不碰索引，后台异步补

追加进日志，写路径就返回了（要不要等它落盘，由刷盘与复制那两个开关决定）；索引由一条后台线程追着补。这条线程叫 ReputMessageService：它反复把日志里的消息读回来，分派给「建消费索引」与「建查询索引」两个动作，一轮做完只睡 1 毫秒又去看有没有新数据。官方 Design_Store.md 讲这段路径用的词是「不停地分发请求并异步构建 ConsumeQueue 和 IndexFile 数据」。

它怎么知道「补到哪了」？靠一个叫 reputFromOffset 的游标：每轮从游标位置顺序往后读日志，解析出一条就分派一条，游标同步往前推。日志末尾有写入就唤醒它，游标追平末尾就睡 1 毫秒再探一次。所以消费索引条目是日志落盘后异步补出来的，不是写日志时同步写——追加返回的那一刻，消费索引里可能还没有这条消息的条目。这个窗口的具体时长没有保证，受消息量、分派工作量、磁盘与线程调度影响；能确认的只是在在线空载实验里它很快收敛到 dispatchBehindBytes=0。

分派时还有一个关键开关：它按消息的事务标记决定写不写消费索引。普通消息、以及事务消息 commit 后重投的那条，标记是「普通 / 已提交」，会写进消费索引；事务的 prepare 与 rollback 两种标记，分派时直接跳过、不写索引——这正是第十一节「半消息不在原主题索引里」的源码依据。

追到哪了是可观测的：日志最大偏移减去索引已补到的位置，就是 dispatchBehindBytes，在线情形下它收敛到 0。日志本身也不会无限长：默认保留 72 小时，过期的文件由清理任务删除。

重启以日志为准

启动时从最后几个文件开始往下扫，能一条条解析出消息就继续；碰到长度或标记对不上、读不成形的数据（上一次进程被杀在写一半的位置）就停在那里，把文件截回读得通的地方。索引这边相反：多出来的、比日志还远的条目会被删掉。日志是那份真相，索引是它的派生物，对不上时按日志修。

写是同步的，索引是异步的。 追加返回时，消费索引里可能还没有这条消息的条目。这个窗口在线很快收回；容易复现的那种「一条都收不到」成因是位点残留，与这里不是一回事。

边注：日志文件内部有三个独立游标（写入位置、已提交位置、已刷盘位置）。它们的差值决定掉电会丢哪一段，也正好是刷盘与复制那两个开关在等的东西，属于结构推导。

六、高可用：刷盘与复制两道开关，和一份整机级的只读副本

消息什么时候算「安全」？主节点挂了会怎样？这两个问题的答案，藏在两个互相独立的开关里。

刷盘（flushDiskType）和复制（brokerRole）是两个开关，各取一档，拼出四种搭配。这两个开关在发送路径上各自要多等什么已经交代过；这里只看它们组合起来，消息在什么情况下会丢。

flushDiskType 管「还没写进磁盘的那一段」：ASYNC_FLUSH（异步刷盘）返回 SEND_OK 时数据可能还在内存里（PageCache），机器一断电就没了；SYNC_FLUSH（同步刷盘）返回前先写进磁盘文件，单机断电不丢已确认消息。
brokerRole 管「从节点还没拿到的那一段」：ASYNC_MASTER（异步复制）不等从节点就返回，主节点整机坏掉时这一段真没了；SYNC_MASTER（同步复制）等从节点收下才返回，主节点这时候坏掉，从节点手里是齐的——代价是从节点不在场时拿不到 SEND_OK（返回 SLAVE_NOT_AVAILABLE，消息仍在主节点上），这正是发送失败第三类里的那个坑。

四种搭配

两个开关各取一档，各自怕什么、丢什么，并列着看最清楚：

刷盘 × 复制	什么情况下会丢	实际后果
异步刷盘 × 异步复制（默认值）	主节点断电，或整机坏掉	「没落盘」和「从节点没拿到」两段，摊上哪段丢哪段
异步刷盘 × 同步复制（本机实测这一档）	两台机器同时断电	只丢「没落盘」那段；数据在从节点上已有一份
同步刷盘 × 同步复制	两台机器连磁盘一起毁掉	可容忍任一单节点故障；同时失去两个副本仍会丢。真正的麻烦是从节点不在场时发送拿不到成功返回
同步刷盘 × 异步复制	主节点整机坏掉	只丢「从节点还没拿到」那段

怎么选，看你能接受哪种坏法。 只担心主节点整机坏掉，打开同步复制就够（本机实测里它的延迟代价比同步刷盘小，这是实验读数，不是一般结论）；连主节点断电都不想丢，再把同步刷盘打开，代价是每条消息多发一次落盘等待；两种都能接受、只要吞吐，就保持默认的两异步。第四格（同步刷盘 × 异步复制）少见：刷盘的代价付了，主节点整机坏掉时照样丢从节点没拿到的那段。

一个结论可以直接下：四种搭配选的是「丢多少」，不是「丢不丢」——每一格丢的都是「没落盘」与「从节点没拿到」这两段的组合。除实测的那一格外，其余三格按开关语义推出，没有逐一验证过。

复制通道

复制机制的关键在方向：是从节点主动连上来拉，不是主推过去。它去连的那个地址也不是自己配的——从节点向 NameServer 注册时，响应里就把主节点的地址与 HA 地址一并回了过来。

复制只有一条通道。 主节点在 haListenPort（默认 10912）上监听，一个从节点一条 TCP 长连接；连接建起来的第一件事，是从节点把自己的最大物理偏移报上去，主节点从那个位置开始顺序读 CommitLog 推给它——复制因此天生是断点续传，重连之后不用从头再来。

这条通道上跑两个方向。 主节点往从节点推数据，每批不超过 haTransferBatchSize（默认 32 KiB），批头带着这批数据的起始偏移；从节点每处理完一批，把「我已经写到哪儿」回报给主节点。

主节点手里的偏移差就是两个数相减：它已经写到的偏移，减去从节点回报的已写入偏移。这个数有两个用途——同步复制的写请求等的正是它追平，以及判断从节点还跟不跟得上：偏移差超过 haSlaveFallbehindMax（默认 256 MiB），主节点就认定这个从节点落后太多。

所以「有从节点在场」是两件事同时成立：连接还在（haSendHeartbeatInterval 5 秒心跳、haHousekeepingInterval 20 秒做保活与清理），并且偏移差没有超过那个上限。

复制的单位也是整机：主从之间追平的是同一份 CommitLog 的偏移差，同一个 brokerName 下的主与从各持一份完整的 store/。从节点把复制来的 CommitLog 自己再分派一遍，生成自己的 ConsumeQueue——索引不在复制的内容里，是本地按同样的规则重建出来的。

从节点能做什么

从节点只能读：写请求在从节点上直接被拒（SERVICE_NOT_AVAILABLE），延迟消息的投递任务在从节点上也不启动。消费默认也不会落到它身上——slaveReadEnable 默认关闭；打开之后，也只在「消费跟不上」时把拉取建议转给从节点，而从节点默认不做位点校正（offsetCheckInSlave 为 false）。所以 4.x 的副本是整机级的只读副本：一个 topic 的队列不会在别的 broker 上再存一份，跨 brokerName 的队列之间也没有复制关系。

副本的粒度是整台 broker 的整份 store/：偏移差是整台机器的属性，不存在「某个队列的副本落后了」这种状态。队列这一层的切分只是逻辑上的，它不构成一个能独立复制、独立迁移的单元。

把队列这一层与副本这一层叠起来看，粒度关系是这样的：

主节点挂了

主从的角色是静态的：从节点只做复制，不参与选举。写入只发生在主节点上，从节点的 brokerId 恒为 1、角色恒为 SLAVE——硬杀主节点（模拟宕机，不是优雅退出）之后，从节点全程没有任何升主记录。

客户端的反应因此是「没有可写的主」：主节点一连断线，NameServer 就立即把它注销（断开连接即注销，不等心跳超时那 2 分钟兜底）。

40 秒后发送拿到的是 MQClientException: No route info of this topic——不是「连不上 10911」，而是本地已经没有可写的路由；同一类现象在发送侧还有一个 CODE=17（ha-failover）。

所以主节点宕机后写入要等人介入，这是静态角色这个设定的直接后果，不是配置没调对。范围限 4.9.7、单组主从，观察窗口 40 秒内如此。

这里也要划清一条边界：这一主一从是同机房的副本，不是灾备。它挡的是单节点故障（主宕、主盘坏），不挡机房级故障——两台机器连机架一起没了，副本也跟着没；同步复制确认的只是「从节点追平了」，不等于数据被复制到了另一个地域。保留时间、误删除、两副本同时损坏，仍可能让数据无法恢复。要跨地域容灾，得靠别的机制（异地双活、备份导出），不在本节范围内。

元数据另一条通道

从节点启动 3 秒后开始，之后每 10 秒向主节点拉一次，拉四样：

主题配置；
消费位点；
延迟位点；
订阅组配置。

四样都走 broker 之间的请求响应，不经过 HA 那条连接；拉不到就保持上一次同步到的值。消息体那边是「推数据 + 报偏移」的闭环，元数据这边是定时拉取，两条线各自独立——「副本落后了多少」这个说法只对前一条成立。

另外，「索引落后日志多少」这个指标主从两侧都会打，不能拿它当复制是否正常的证据。

七、消费一条消息：rebalance、长轮询与位点

Push 消费端底下走的是拉：客户端主动去要，broker 在没有消息时把这次请求挂住不回，这个形态叫长轮询（long polling）。一条消息到消费者手上要过三件事：队列先分给实例，实例把队列里的消息拉回来，拉到哪儿记在位点上。

队列归谁

这一步由客户端自己算：分配不经过 broker，broker 只提供名单。每个消费实例每 30 秒向 broker 发一次心跳，心跳里带着消费组名和自己的客户端 id，broker 把这些攒在一张表里。轮到分配时，客户端先向 broker 问一句「这个组现在有哪些实例」，再把本地路由表里这个主题的队列集合拿出来；两边各自排好序，然后按实例序号切段。

默认的切法是平均分：队列集合切成与实例数相同的段，不能整除时靠前的段各多一条。4 条队列 2 个实例，就是实例 A 拿 0、1 号，实例 B 拿 2、3 号；3 个实例则是 2、1、1。这套在实例之间重新分队列的动作就是 rebalance。

分配的单位是队列，一条队列同一时刻只归一个实例。 这句话有两个直接后果：4 条队列的组里放进第 5 个实例，它一条队列都领不到，只能空转——加实例不等于加并行度，队列数才是并行度上限；同一条队列的消息也因此总在同一个实例上被处理。

rebalance 每 20 秒跑一次，收到「组内实例变了」的通知时立刻再跑，不必等下一轮。结果变化就意味着队列易主：一条队列从实例 A 换到实例 B，B 接着往下消费；而位点在 broker 上按主题、消费组、队列号三者记，不跟着实例搬家，B 从 broker 上那份位点继续读。扩容、缩容、实例重启之后，队列归属变了、位点归属没变，这是「重复消费」在位点上报之外的另一个来路。

把消息拉回来

长轮询在客户端这一侧是一个拉取线程管所有队列：它从待办里逐个取出拉取请求发出去，发完不等响应就取下一个。请求带四样：主题、队列号、队列内序号、最多要几条。每条队列同时只有一份请求在飞，请求没回来之前客户端不会再发第二份。

队列里没有新消息时，broker 不回这个请求，把它挂在内存里；等这条队列有新消息落盘、索引分派完，再把它取出来回掉。「推送」的实时性就是这个观感：一次拉取请求被长时间挂着，而不是服务端主动推。 没有消息时靠每 5 秒一轮的巡检兜底，那时顺带检查挂起有没有到期，到期就回一个空响应。

挂多久由客户端在请求头里指定，broker 照它执行，4.9.7 客户端给的上限是 15 秒；官方文档里那个 30 秒是另一次 RPC 的超时，不是挂起时长。

%%{init: {theme: neutral}}%%
sequenceDiagram
 participant P as 拉取线程
 participant B as Broker
 participant S as 存储与分派
 participant Q as 消费线程池
 P->>B: 拉取请求（主题、队列号、序号、条数）
 alt 队列里有消息
 B-->>P: 立即返回
 else 没有新消息
 B->>B: 挂起请求，不回
 S-->>B: 新消息落盘、索引分派完成
 B-->>P: 唤醒并返回
 end
 P->>Q: 消息进缓存队列，交给消费线程池

消费侧的入口是 DefaultMQPushConsumer——名字里带 Push，底下走的仍是上一段说的拉取。业务逻辑注册在监听器里：

DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("gyd-c03-consumer");
consumer.setNamesrvAddr("localhost:9876");
consumer.subscribe("gyd-c03-send", "*"); // 主题 + tag 表达式
consumer.registerMessageListener((MessageListenerConcurrently) (msgs, ctx) -> {
 for (MessageExt m : msgs) {
 handle(m); // 业务处理
 }
 return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
});
consumer.start();

消息拉回来也不直接进业务代码。拉取和消费是两拨线程：拉取线程把消息放进这条队列的缓存队列，消费线程池（默认 20 个线程）再从缓存里取走、执行监听器。缓存有两道闸，条数超过 1000 或者体积超过 100 MiB，下一次拉取就推迟 50ms；并发消费时还多一道，缓存里最早与最新的序号相差超过 2000 也推迟。这三道闸是按消费能力给的流控，挡不住会积压，挡太紧会空转。

位点

位点（offset）是队列内的序号，不是消息的全局编号。它和「一条队列只归一个实例」合起来，才是「每条队列各推各的进度」这件事。

位点存哪取决于消费模式：集群模式存在 broker 上，广播模式存在本地。集群模式下，位点从客户端内存抵达 broker 有三条路：

随下一次拉取请求捎带：只有内存里的位点大于 0 才带；
定时批量刷：启动 10 秒后首刷，之后每 5 秒一次；
正常关闭时同步刷一次。

broker 收到先写内存，再定时落到 config/consumerOffset.json。

第一条路和长轮询是同一个节奏：没有消息时那份请求正被挂着，要等它被回掉才有下一次捎带的机会。位点上报的节奏被拉取的节奏拖着，定时刷就是给这个节奏兜底的那条路。

顺带一个默认值：组在 broker 上还没有位点时，起点取队列当前的最大序号，新组默认只消费启动之后进来的消息，不补历史。

两条边界

位点不随主题删除而清空：它在 broker 上按主题和消费组记，删主题不清位点。删掉 gyd-c03-order 再重建、重新灌 6 条（队列内序号 0–5）之后，这个组手上的位点还是上一轮留下的 6，正好顶在队尾：broker 回「没拉到」，一条都不给，也不报错。恢复动作是把消费进度重置到某个时刻，重置后这 6 条全部收到。

重放边界。 位点不是消费一条写回一条，而是批量走。同一主题、同一消费组，消费到第 4 条时进程被强杀，broker 上的位点还停在 0，重启后这 20 条从头再来一遍；消费完 20 条正常退出之后位点已经落到 20，重启后一条都不会重来。「重复消费」的成因很具体：位点还没走完那段路，进程先没了。

边注：broker 回「没拉到」的背后有四种情形——队列为空、位点比队列最小值还小、位点正好顶在队尾、位点越过队尾太多。它们对客户端的含义分两类：顶在队尾时客户端会立刻再问一次，观感是原地等；越过或低于最小值时 broker 会给一个纠正后的位点，客户端把手上这条队列丢掉，按新位点重来。上面那个强杀样本落在「顶在队尾」这一格。

消费失败之后

前面只讲了「监听器成功、位点提交」这条成功路径。监听器返回失败（RECONSUME_LATER，或抛异常）时，消息不是被丢掉，而是进一条重试链路：

第一次失败，消息被改投到该消费组的重试主题 %RETRY%<消费组名>，投递次数写进消息属性，等一个退避间隔后再次投回原主题；
重试主题也有自己的消费队列，这条链路继续由原消费者消费，位点在重试主题上按组记录；
投递次数累计到一个上限（默认 16 次）后，消息被改投到死信主题 %DLQ%<消费组名>，不再自动重试，等人手工介入。

这一小段为什么关键，因为它把「至少一次」和「消费端幂等」钉在了一起：重试会带来同一消息被多次投递，业务处理必须幂等；第三节说「发送侧只给 at-least-once」，这里就是重复在消费侧的具体落点——不是发送重试造成的，是消费失败重投造成的。它也和第三节的问题 1 首尾相接：事务消息不解决重复，解决重复的是幂等，而幂等正是被这条重试链路逼出来的。

顺序消费里，失败还有一层额外后果：顺序消费的队列被锁住、逐批串行，一批里的某条失败会让整条队列停在这个位置，后续消息被挡住，直到这一条被处理成功或达到死信上限。所以顺序消费对「某一条能不能被可靠处理」的敏感度，比并发消费高得多。

边注：重试的退避间隔和次数上限（RETRY 主题的队列数、delayLevelWhenNextConsume 等）都是消费组级的配置，默认行为是「逐次退避、16 次进死信」，具体档位可调。死信主题不会被普通消费者订阅，需要单独拉取或走运维通道。

八、顺序消息：先保住两条前提，再用锁立住它

顺序消息解决什么

有些消息之间是有先后的：同一个订单的「下单、支付、发货」必须按这个顺序被处理，先处理「发货」再处理「下单」就是错账。顺序消息要保证的就是这件事——一批相关的消息，被消费的顺序和它们发出来的顺序一致。

但默认的并发消费做不到。上一节说过，消费线程池有 20 个线程，同一条队列的几批消息会被同时取走、各自处理：先提交的那批还没处理完，后提交的那批可能已经跑完了。顺序正是在这「同时处理」里丢掉的——不是消息落盘时乱，是消费时几批并行，先后没有保证。

难点在哪

顺序消息的讨论放在前面已经固定的集群设定上：主题 4 条读写队列（第一节）、消费线程池 20 个线程（第七节）。

要让顺序成立，得同时按住两件事，缺一个都不行：

发送侧：相关的消息必须进同一条队列，而不是被轮询摊到 4 条队列上——摊开了，连「它们本来是一组的」这个信息都没了；
消费侧：同一条队列，同一时刻只能有一个消费者在处理——否则又是几批并行，顺序照散。

队列本身是有序的（第七节），这两件事同时成立，顺序就自然成立。难点不在「想到这两件事」，而在「在分布式、多实例、可能宕机的环境里，把它们固定成不可被绕过的约束」。

第一件事：发送侧按业务键选定队列

默认的选队列动作是轮询，sendWhichQueue 那个计数器对着队列列表转，同一个业务键的消息会被摊到 4 条队列上，顺序在源头就被打散。要保序，得给发送端挂一个选择器，按业务键决定落点，最常见的写法是业务键对队列数取模：同一个订单号的「下单、支付、发货」三条消息，业务键相同，取模落到同一条队列。对应到 API，就是实现 MessageQueueSelector：

// 按业务键（订单号）选队列：同一订单的消息进同一条队列
SendResult r = producer.send(msg, new MessageQueueSelector() {
 @Override
 public MessageQueue select(List<MessageQueue> mqs, Message msg, Object arg) {
 long orderId = (Long) arg; // 业务键
 int idx = (int) (orderId % mqs.size()); // 对队列数取模
 return mqs.get(idx);
 }
}, orderId);

这一层只解决落点：发送端保证的是「相关的消息进同一条队列」，不保证它们落盘的先后——同一个业务键的消息由多个发送线程并发发出时，谁先落到 broker 上就不一定了。要连落盘顺序也保证，得发送端自己串行发。

第二件事：消费侧认领队列

消费侧分两层。第一层是「这条队列现在归不归我」：队列归谁由客户端自己算、broker 只给名单（第七节）。顺序模式不采用这个结论——「算给我了」还不够，因为另一个实例也可能算出同样的结果。它还必须在 broker 那儿留一份登记，证明「这条队列此刻只归我」：客户端把分配到的每条队列都走一遍 lock，拿不到就把这条队列整个摘掉、一条都不拉（if (isOrder && !this.lock(mq)) continue;）。在顺序模式里，「算给我了」和「现在归我」是两件事。

这次确认不是阻塞锁，是一次登记。客户端把要用的队列打包进一个 LockBatchMQ 请求（超时 1000 ms）发给 broker，broker 侧按消费组维护一张表（RebalanceLockManager），每行记「这条队列现在归哪个 clientId、最后一次续租在什么时候」。归属靠续租维持，不是一次授权就长期有效。 客户端每 20 秒续一次（REBALANCE_LOCK_INTERVAL），续上就刷新时间戳；本地 30 秒没续上就把这条队列的锁标记成过期（REBALANCE_LOCK_MAX_LIVE_TIME），消费随即停下；broker 侧要 60 秒没等到续租才判失效、放给别的实例（rocketmq.broker.rebalance.lockMaxLiveTime）。

消费请求本身也认这两个条件：进来先查「锁在手上、且没过期」，任一不满足就把这条队列推到 10 ms 后重试，重试仍拿不到锁就改 3 秒后再来。

推到极端就是顺序模式比并发模式贵的地方：一个实例整机挂掉，它在 broker 上登记的那几条队列要等 60 秒没人续租才放出来，别的实例才接得走。这个 60 秒是从两侧的常量推出来的，本机没有实测过。

第三件事：实例内部逐批串行

第二层在实例内部，这一层才是真正的锁：客户端给每条队列准备一个锁对象（MessageQueueLock），消费请求进来先 synchronized 住它，这一批处理完下一批才进得来；不同队列各锁各的，仍然并行。对照并发消费：它没有这一层，同一个队列的几批消息按 consumeMessageBatchMaxSize 切完就直接提交进 20 个线程的池子，同队列并行——顺序正是在这一步丢失的。

消费侧要拿到这套串行语义，注册的是 MessageListenerOrderly 而非普通的 MessageListenerConcurrently：

consumer.registerMessageListener(new MessageListenerOrderly() {
 @Override
 public ConsumeOrderlyStatus consumeMessage(List<MessageExt> msgs,
 ConsumeOrderlyContext ctx) {
 // 同一队列的这批消息，上一批处理完才会进来下一批
 for (MessageExt m : msgs) {
 processOrder(m); // 按队列内顺序处理
 }
 return ConsumeOrderlyStatus.SUCCESS;
 }
});

一个 MessageListenerOrderly 内部，consumeMessage 对同一条队列是串行进入的；锁住的是「这一批与下一批不并发」。

代价：并发度上限就是队列数

三件事都成立之后，代价就具体了：20 个消费线程都还在，但同一条队列同一时刻只有一批在处理，线程数不等于并发度——4 条队列最多也就是 4 路并行。而这个 4 在主题建出来的时候就定死了：要么显式 -w 4 建，要么第一个发消息的客户端自动建 min(4,8)=4。队列既是存储的容量单位，也是顺序的最小单位，顺序消息的代价和存储骨架是同一个问题。

官方 Operations_Consumer.md 对这一步的措辞很直接：顺序消费会 lock 每个队列，「This will cause a performance loss」，「性能损失」四个字就是本节说的代价；同一份文档也写明，需要保序的消息必须有序地发进同一个队列。

还有一条边界。顺序消息保证的是顺序，不保证不重复。 进程被强杀之后，落回队列的那批消息会再来一遍，顺序照样成立，重复也照样发生——顺序管的是先后，重不重复由位点决定，两件事互不替代。

九、消息过滤：先弄清过滤什么，再看它落在哪一层

过滤要解决什么

一个主题里的消息并不全是同一个消费者要的。比如订单主题里混着「下单、支付、发货、退款」四类事件，做对账的那个消费者只关心「支付成功」，其余三类它一条都不想收。订阅本身就是一个过滤动作：消费者在订阅时声明「我只要哪种消息」，broker 据此决定哪些投递、哪些不下发。

这个过滤放在 broker 侧做，而不是让消费者把消息全拉回来自己筛，省的是传输和处理的浪费：不符合条件的消息根本不下发，也就不占网络、不占消费端的 CPU。RocketMQ 给这个声明提供了两种写法：tag 和 SQL92。

两种写法长什么样

tag 是消息身上的一个标签字段。 发送时给消息打一个 tag，订阅时用 tagA || tagB 这样的表达式声明要收哪些。它匹配的是整个字符串，只能表达「等于」或「等于其中几个」：

// 发送侧：这条消息打上「支付成功」的 tag
Message msg = new Message("OrderTopic", "PaySuccess", "订单 1001 已支付".getBytes());

// 订阅侧：只收 tag 为 PaySuccess 或 Refund 的消息
consumer.subscribe("OrderTopic", "PaySuccess || Refund");

SQL92 是借用 SQL-92 标准的表达式，按消息属性筛选。 消息除了 tag，还能带一组键值属性（比如金额、地区）；SQL92 订阅就是写一条 WHERE，对这些属性做比较、范围、集合判断。能力比 tag 强得多：

// 发送侧：带上属性
msg.putUserProperty("amount", "150");
msg.putUserProperty("region", "hz");

// 订阅侧：只收金额大于 100 且地区在指定集合里的消息
consumer.subscribe("OrderTopic", MessageSelector.bySql("amount > 100 AND region IN ('hz', 'sh')"));

tag 是贴在消息上的一个短标签，SQL92 是对消息属性的一组判断：前者简单、只按字符串匹配，后者能表达任意属性组合。写法就这两种；但 SQL92 还有一个可选优化，叫 bitmap，下面要一起讲——所以后文说的是「三种形态」，而不是三种写法。

bitmap 是什么，先说清楚。 SQL92 的代价是每条候选都要读正文、求值表达式，读得越多越慢。bitmap 就是把这个求值提前：broker 在构建消费队列时，就拿到「这个主题下所有带 SQL92 条件的消费组」，对这条消息挨个用编译好的表达式先算一遍，把「哪些消费组匹配」的结果，用布隆过滤器（bloom）算成一个二进制位图，存进消费队列的扩展存储。

消费时第一层先查这个位图：位图说「不匹配」就直接跳过、不读正文；说「可能匹配」才落第二层确认。它们真正的差别在「这个判断在 broker 的哪一层做」，也就是下面这套两层判定。

两层判定

broker 侧的过滤是一个两层判定：tag 和 SQL92 的区别，就落在「被判掉在哪一层」。为什么会有这两层，答案在第四节那个位置之分——索引条目里只有 tag 的哈希、属性原文只在日志正文里，于是手上只有索引时，够判 tag、不够判 SQL92。这两层是这样的：

第一层：手上只有索引条目里那个 tag 的 hashCode，够判断 tag，不够判断 SQL92；
第二层：手上才有消息正文和属性，才能求值 SQL92 表达式。

逐条循环把这两层串成一个短路：先走第一层，判掉就不读正文，判不了才落第二层。三种形态（tag、SQL92、SQL92 + bitmap）的区别，全在这条短路上：

维度	tag	SQL92	SQL92 + bitmap
表达式在哪声明	客户端	客户端	同左
判定落在哪一层	第一层	第二层	第一层 bloom 预筛 + 第二层确认
判断需要的数据	索引条目里的 tag hashCode	消息属性（在正文里）	建索引时算好的 bitmap
是否要读消息正文	不读（第二层对 tag 直接放行）	每条候选都要读	预筛不命中就不读；命中仍要读
需要的服务端开关	无	`enablePropertyFilter`（默认关闭）	`enableCalcFilterBitMap` + `enableConsumeQueueExt`（位图要存进扩展存储，两个都得开，默认都关）
主要代价	一次 hash 查表	读正文 + 属性求值	建索引时预计算；bloom 假阳性会白读一次

「tag 过滤为什么不必读消息体」这一行，答案也在这里：tag 的判定落在第一层，用索引条目里那个 hashCode 就能在读正文之前把不匹配的消息淘汰掉，只有候选消息才读正文、传给客户端。这也是第四节那个比较值的用途：它让 tag 过滤在 broker 这边先靠索引筛一道。

但 hashCode 会碰撞，broker 手上又没有 tag 原文——它比的是 codeSet.contains(tagsCode)，只是两个整数是否相等；两个不同的 tag 撞出同一个 hashCode，第一层就会把「本不该匹配」的消息误放行。这个口子 broker 补不了，得靠客户端：消息拉到本地后，PullAPIWrapper 里再跑一遍 tagsSet.contains(msg.getTags())，这次比的是 tag 原文，把碰撞造成的假阳性丢掉。所谓「不读正文」，省的是 broker 读盘与传输，不是省掉最终那道精确比对——精确过滤始终在，只是从 broker 挪到了客户端。

SQL92 则相反：第一层没有任何信息，每条候选都要读正文、解析属性、求值表达式。所以 SQL92 需要 broker 侧打开 enablePropertyFilter（默认关闭）；开关没打开时，用 SQL92 订阅会被 broker 直接拒绝：The broker does not support consumer to filter message by SQL92。

bitmap 是给 SQL92 的优化：建队列时用 bloom 把「哪些消费组可能匹配」算成位图，第一层按这个位图预筛，判不中就不读正文。但 bloom 是概率结构，命中不等于真匹配，仍需第二层确认；假阳性会白读一次。

启用 bitmap 的这两个开关不在同一个配置项里：enableCalcFilterBitMap 在 broker 配置，enableConsumeQueueExt 在消息存储配置，别找错地方。

官方 Design_Filter.md 也把这道两层判定说穿了：服务端「只用 hashcode，因此无法精确，所以 Consumer 拉取后还要比对原始 tag 字符串」。服务端 isMatchedByConsumeQueue 里比的是 codeSet.contains(tagsCode)（整数），客户端 PullAPIWrapper.processPullResult 里比的是 tagsSet.contains(msg.getTags())（原文）——一道比 hashCode、一道比原文，碰撞的口子由后者补上。

十、定时消息：18 级级表与 SCHEDULE_TOPIC_XXXX

定时消息为什么要绕一个内部主题？因为原主题的队列是顺序消费的（第六、七节）：一条 10 秒后才该投递的消息如果现在就进原队列，会挡住排在它后面、本应立即可见的消息。所以定时消息必须先隔离到一个内部主题、到期再投回来，不能占着原队列的位置。

它和第四节「只追加日志」并不冲突，但「隔离」「投回」两个动作，各有各的写。隔离：这条消息落盘时，topic 被改成 SCHEDULE_TOPIC_XXXX，正文照常追加进 CommitLog，但消费索引建在内部主题下，原主题的消费者看不到它。

投回：到期后后台任务从这条消息的属性里还原出真实主题与队列，重新写一条 CommitLog（一条全新的消息），新消息在原主题下建消费索引，消费者这时才在原队列里看到它。旧的内部主题索引不删，靠扫描任务自己的进度表记录「这条队列扫到哪了」，随日志过期一起回收。

这个内部主题配合的是一张离散延迟级别表（默认 18 级，从 1 秒到 2 小时，完整级表见下），而不是「每条消息一个定时器」。发送时给消息设一个延迟级别，broker 把它改投到内部主题 SCHEDULE_TOPIC_XXXX 的第 delayLevel - 1 个队列，由一个后台定时任务扫描到期后重新投回原 Topic：

Message msg = new Message("OrderTopic", "订单超时关闭".getBytes());
msg.setDelayTimeLevel(3); // 第 3 级 = 10 秒后投递
producer.send(msg);

延迟级别是唯一入口，落盘时级别决定投到内部主题的哪个队列。

所以第一个结论是：4.9.7 不支持每条消息直接指定任意投递时间，只能从 broker 配置好的离散延迟级别里选。这套级别来自 broker 的 messageDelayLevel 配置项，可以改，但改的是「可选哪几档」，改不出「任意时刻」这一档。官方 Example_Delay.md 说得更直白：「does not support any time delay. It needs to set several fixed delay levels, which correspond to level 1 to 18 from 1s to 2h」。默认配置就是这 18 级，级表分布本身就是证据：1 分钟到 10 分钟这段每分钟一档，之后直接跳到 20 分钟、30 分钟、1 小时、2 小时，越长的延迟越粗糙。

但「精度」还有另一半，级表管不到：定时消息保证的是不早于该时刻投回原队列，不保证「一到点就被消费」。投回之后它就和普通消息一样排进原队列，原队列消费阻塞或积压时，实际被处理的时间照样往后漂。级表锁的是「能选哪些延迟」，消费侧排队锁的是「选中的延迟能不能准点兑现」，前者由 broker 定、后者由消费速度定。

边注：默认 18 级级表按序是 1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h。这套「离散档位」就是定时消息默认的全部可选精度，不存在「任意秒」这一档。

第二个结论：超出 18 级的 delayLevel 不被拒绝，而是被静默夹到第 18 级。落盘时若级别超出最大级，就把它压到最大级；而「级别」到「队列号」的映射就是「级别减一」。官方 Feature.md §8 也明写了这条规则（「level > maxLevel 则 level == maxLevel，例如 level==20，延迟 2h」）。

这条在磁盘上可以直接看到：DELAY=19 与 DELAY=99 两条的落点都是 queueId=17（第 18 级），索引条目里那个投递时刻减去落盘时刻，差值恒等于 2 小时（7200000 毫秒），请求里写多少都不算数。

%%{init: {theme: neutral}}%%
flowchart LR
 A[发送 delayLevel] --> B[改投 SCHEDULE_TOPIC_XXXX]
 B --> C[第 delayLevel-1 个队列]
 C --> D[后台定时任务扫描]
 D -->|到期| E[投回原 Topic]

客户端拿到 SEND_OK、消息进了 SCHEDULE_TOPIC_XXXX 的 Q17，在观察窗口内没有投递。「2 小时后投递」是结构推导：没有等满 2 小时做直接观测，这里标为未观测。

十一、事务消息：半消息、回查，与一次主题替换造成的索引迁移

「改库 + 发消息」的原子性怎么被兜住？答案分两半：客户端一个监听器，broker 一套半消息机制。

客户端是一个事务生产者 + 一个监听器，两个回调：

executeLocalTransaction：执行本地事务、返回状态（commit / rollback / unknown）；
checkLocalTransaction：broker 回查时，回答本地事务成没成。

TransactionMQProducer producer = new TransactionMQProducer("gyd-c03-tx-producer");
producer.setTransactionListener(new TransactionListener() {
 @Override
 public LocalTransactionState executeLocalTransaction(Message msg, Object arg) {
 // 执行本地事务（改库），按结果返回状态
 return doLocalTx(msg) ? LocalTransactionState.COMMIT_MESSAGE
 : LocalTransactionState.ROLLBACK_MESSAGE;
 }

 @Override
 public LocalTransactionState checkLocalTransaction(MessageExt msg) {
 // broker 回查时，再查一次本地事务到底成没成
 return queryLocalTx(msg) ? LocalTransactionState.COMMIT_MESSAGE
 : LocalTransactionState.ROLLBACK_MESSAGE;
 }
});
producer.start();
producer.sendMessageInTransaction(new Message("OrderTopic", "下单".getBytes()), null);

回查接口必须由业务方实现，这是事务消息的代价之一（第十二节）。

broker 侧，把半消息写进内部主题 RMQ_SYS_TRANS_HALF_TOPIC，处理 commit/rollback，并定期驱动回查。

这里有一个容易记混的地方：半消息的「不可见」不是「不建索引」，而是「不建到原主题的索引下」。落盘时做三件事：备份原 topic/queueId 进属性、把事务位重置为 0、换 topic 为 RMQ_SYS_TRANS_HALF_TOPIC。结果是两个索引状态：原主题的 ConsumeQueue 里没有它，内部主题的 ConsumeQueue 里有它；而且回查正是靠内部主题里的这条索引把半消息拉起来的。

官方 Design_Trancation.md 的原文是「消息并不会转发到该原主题的消息消费队列」，而不是「不建索引条目」：半消息确实建了条目，只是建在内部主题下：磁盘上 RMQ_SYS_TRANS_HALF_TOPIC 的 queueId=0 下有 4 条，与 4 条半消息一一对应。

半消息一旦被 commit 或 rollback，还多一步：broker 向另一个内部主题 RMQ_SYS_TRANS_OP_HALF_TOPIC 写一条 Op 消息，正文是那条半消息在 half 主题里的队列偏移。回查扫描时先看 Op 主题，已经出现在 Op 里的半消息直接跳过、不再回查。半消息自己的索引条目不物理删除，靠 Op 标记 + 日志过期一起清。

commit 的语义也要说准：commit 是「重新落一条」，不是「解锁旧消息」。还原真实主题后重新写一次，可见的是新写的那条。所以原主题的索引条目，只在 commit 之后才第一次出现（rollback 则永不出现）。这和第十节定时消息的「投回」是同一套写法：定时到期重写一条、事务 commit 也重写一条，都是「新落一条、在原主题下建索引」。

回查是周期扫描任务，不是「每条一个定时器」。它的循环就是「睡一个检查间隔 → 醒来扫一遍」，扫的是「落盘超时仍未定论」的半消息。所以一条半消息从落盘到被回查的等待 = 超时阈值 + 扫描周期相位：落盘 6 秒内没定论（transactionTimeOut）才进入可回查范围，再等扫描轮询到它；所以不是固定 60 秒（观察到的这一次是在落盘后约 19 秒）。而且回查依赖生产者进程仍存活——生产者挂了，没人回答回查。

%%{init: {theme: neutral}}%%
sequenceDiagram
 participant P as Producer
 participant B as Broker
 participant C as Consumer
 P->>B: 第一次写（半消息）
 B->>B: 写入 RMQ_SYS_TRANS_HALF_TOPIC / Q0
 Note over B: 内部主题索引已有条目
 P->>P: 执行本地事务
 alt commit
 P->>B: 第二次写（还原真实主题）
 Note over B: 原主题索引首次出现条目
 B-->>C: 可见
 else rollback
 P->>B: rollback
 Note over B: 原主题永不出现条目
 else unknown
 B->>B: 周期扫描回查
 B->>P: 回查本地事务结果
 end

事务消息解决的是一种原子性：本地库改了、消息没发出去（或反过来）。它替代不了消费端幂等，也不解决跨库一致性。不宣称端到端 exactly-once。

十二、收口：四个功能的取舍边界

主链路走完了。顺序、定时、事务、过滤这四个功能，都长在同一份 CommitLog 上，但它们各自付出了什么代价、代价的边界在哪，并不相同。逐个收口：

顺序消息：代价是并发度，边界是队列数。一个队列同一时刻只归一个消费线程，串行是锁出来的，并发上限就是队列数——队列数可以调，但调了会动路由、顺序粒度与并行度，不是无代价的旋钮（第八节）。
定时消息：代价是精度，边界是离散延迟级别（默认 18 级）。改投的队列号就是「级别减一」，级表可配置，但选的是「哪几档」，选不出「任意时刻」，越长的延迟越粗糙（第十节）。
事务消息：代价是「业务方实现回查接口」加「消息要重写一次」，边界来自框架设计。半消息先落到内部主题，commit 时重新写一条才在原主题可见；本地事务成没成，最终要业务方自己回答（第十一节）。
过滤：代价是索引条目里的 tag hashCode，边界来自索引布局。tag 订阅靠条目里的 code 在读正文前预筛；SQL92 订阅默认读候选消息的属性求值，开启 bitmap 后才多一层 bloom 预筛（第九节）。

这四个功能各有一处「要能力就要付代价」的取舍，代价来源不同。高可用（第六节）不在这一类里——它没有拿能力做交易，代价是另一回事：主从角色静态，主节点宕机后写入要等人介入，这是主路径上的安全边界，跟上面四个功能的设计取舍性质不同。

所以总边界可以概括成一句：这四个功能的能力上限，有的由存储骨架决定（队列数、级表、索引字段），有的由框架设计决定（回查接口、重写一次）；其中队列数、级表这类参数可以改，但每改一次都要重新掂量它牵连的并行度、路由与顺序粒度。

排错索引

遇到下面这些现象，翻到对应章节看原因：

现象	去哪一节看
宿主机客户端连不上 / 容器名解析失败	二（`brokerIP1` 是通告地址）
显式查询不存在主题的路由，抛出 `CODE=17`	三（`getTopicRouteInfoFromNameServer` 探测）
发送报超时，消息却已经写在 broker 上	三（超时只是客户端愿意等的窗口）
返回了非 `SEND_OK`，却既不抛异常也不重试	三（「发送失败」三类 + `retryAnotherBrokerWhenNotStoreOK` 默认关闭）
重建主题后消费者一条都收不到	七（位点不随主题删除而清空）
进程被 kill 后同一批消息又消费了一遍	七（位点上报的三条路都还没走完）
SQL92 订阅直接报错	九（`enablePropertyFilter` 默认关闭）
设了很大的 delayLevel 却一直不投递	十（超范围级别被静默夹到第 18 级）

顺序消息和「加了消费实例、吞吐却不涨」都没有独立的排错条目：它们的问题不是「报错」，而是「并行度上不去」，属于能力边界而不是故障：前者的上限就是队列数，后者是实例数超过了队列数。

演示代码：完整实现在 GYD 仓库 c04-rocketmq-architecture，RocketMQ 集群的编排在仓库级 infra/rocketmq/。正文里括注的名字分两类：failmode / orderly / offsetprobe 是模块里的示例名，在 GYD 仓根用 ./gradlew :c04-rocketmq-architecture:run --args="<示例名>" 跑（JDK 21 需显式指定 JAVA_HOME）；inspect-storage / ha-failover 是三个 docker 层对照实验（端口映射、硬杀主节点、磁盘逐字节巡检）的巡检名。每个示例做了什么、各结论对应的完整输出记录、以及对照实验的做法与读数，都在该模块的 README 里。

第三话｜跨行清算对账：跟你跑通一个对账流水线，亲手拆解分布式一致性的工程骨架

Sun, 15 Feb 2026 00:00:00 +0000

A 从工行转 10,000 元给 B 的建行账户。工行 App 显示扣款成功，建行的到账短信也到了，两边客户看到的都是「成功」。

第二天日终对账跑完，报表上多出一行差异：建行侧这笔交易有两条分录（账本上的记账记录），B 的账户多出一万块。钱只转了一次。那条多出来的分录是哪来的？谁负责把它消掉？能自动消掉吗？

这三个问题，对账系统都得回答。而回答之前，得先知道这笔转账在哪几个地方各记了什么——它不是一个系统写一行数据，是三个互不信任的系统各写各的账。

GYD 这个系列讲分布式系统里各种解决方案的实现方式。上一篇讲了消息队列的可靠投递——一条消息从发出到被处理，中间可能死在三段里。当消息可靠地到达了，新的问题浮现：两边的账还是可能对不上，你怎么发现、怎么分级处理、怎么修正？

对账这件事，本质上不是在检查「账有没有记错」——它是在问一个更根本的问题：在没有全局一致性的分布式环境里，你用什么手段去证明系统的状态是对的？

建一个最小可行的对账流水线：两个银行服务、各自的借贷账本、一个模拟结算服务、一个日终对账 Job。跑起来，亲手看到对账怎么发现差异、怎么分级决策、怎么追加式更正。不追求完整银行核心系统——那太大了——而是聚焦对账最核心的口径、匹配和分级处理。

一、一笔跨行转账，动了三个账本

回到那笔 10,000 元。表面上看，就是工行的一个账户余额减了，建行的一个账户余额加了。但这个简化版本漏掉了最关键的一环：银行间的结算。

先说清一件容易被跳过的事：工行不会用运钞车把一万块现金送到建行。银行之间的「钱」，是它们在央行开的账户里的数字。每家商业银行都在央行有一个结算账户——好比公司里每个部门都在财务总部存了一笔备用金，跨部门的结算由总部在这个池子里挪数字。

所以一笔跨行转账，实际有三个记账主体，各自维护一个独立数据库，互相看不到对方的账：

记账主体	账本上记的是什么	谁维护
工行核心系统	A 的客户存款 + 工行存放央行的钱	工行
央行支付系统	工行结算账户 + 建行结算账户	央行
建行核心系统	建行存放央行的钱 + B 的客户存款	建行

三幕记账

时间线上分三幕，每一幕各写一组分录。分录（journal entry）就是账本上的一行记账记录，它的约束第二节细讲。

第一幕：A 点转账，工行记账。 工行校验 A 余额充足，在自己的账本上写入两条：A 的客户存款减少一万，工行存放央行的钱减少一万。此时钱还没易手，只是工行单方面记下了「我要付一万出去」。

第二幕：工行把支付指令发给央行，央行记账。 央行检查工行结算账户余额够不够，够则同时改两户：工行的结算账户减一万，建行的结算账户加一万。这一步完成，银行间资金交割就「最终」了——在央行的制度里这叫结算最终性，记入央行账户后不可撤销。

第三幕：央行通知建行，建行记账。 建行收到入账通知，确认 B 账户状态正常，在自己的账本上写入两条：建行存放央行的钱增加一万，B 的客户存款增加一万。之后建行回执、工行给 A 弹「转账成功」——那是通知，不是记账。

%%{init: {'theme':'neutral'}}%%
sequenceDiagram
 autonumber
 participant A as A（工行客户）
 participant ICBC as 工行核心系统
 participant PBC as 央行支付系统
 participant CCB as 建行核心系统
 participant B as B（建行客户）

 A->>ICBC: 发起转账 10,000 元
 ICBC->>ICBC: 记账：客户存款-A 减 / 存放央行 减
 ICBC->>PBC: 支付指令
 PBC->>PBC: 记账：结算存款-工行 减 / 结算存款-建行 加
 Note over PBC: 资金真正易手，结算最终性成立
 PBC->>CCB: 入账通知
 CCB->>CCB: 记账：存放央行 加 / 客户存款-B 加
 CCB-->>B: 到账短信
 ICBC-->>A: 转账成功

三幕走完，四个账户余额发生了变化：A 的存款 −1 万、工行在央行的结算户 −1 万、建行在央行的结算户 +1 万、B 的存款 +1 万。钱没有消失也没有多出，只是欠条链条换了人。

同一个结算账户，在两个账本里性质相反

这里有一处最容易绕晕，说透了后面全通：工行在央行的那个结算账户，在工行账本上是资产，在央行账本上是负债。

就像你的工资卡余额——对你自己记「别人欠我一万」，对银行记「我欠客户一万」。同一笔债，两边各记各的，谁也没错。所以第二幕里，央行记的是「结算存款—工行」减少，因为那是央行欠工行的钱变少了；而第一幕里，工行记的是「存放央行款项」减少，因为那是工行存在别人那里的钱变少了。两笔指的是同一件事，但记在两个不同的数据库里，用两个方向相反的科目名。

对账要跨的就是这种缝：三本账各记各的，同一个事实在不同账本里长得完全不一样。

为什么裁判只能是央行

既然工行和建行各记各的账，为什么不能两边互相对一下就完事？

假设只让两家互对：工行说「我转了」，建行说「我没收到」，信谁？两家都是这笔交易的利益相关方，漏记、错记的一方有动机把责任推给对方。更糟的情况是两边都记错了——比如入账通知丢失导致两边都没入账，互对反而「对平了」，两家错得整整齐齐，谁也不知道出了问题。

央行不一样：它在这笔交易里没有利益瓜葛，而且是资金真正动过的那个地方。第一幕和第三幕都只是各家自己账本上的数字变化，第二幕才是钱真的易手。既然「钱到底转没转成」这个动作只发生在央行账上，这个问题的裁判也只能是央行账。

这就是「两方互对只能发现不一致，三方核对才能判定哪边不一致」的由来：工行建行互对，发现差一万，吵不清谁错；拿出央行记录一看「总部说转了一万」，立刻知道是哪家的小账本没记上。

这条判断抽掉金融外壳也成立——谁是那个动作真正发生的地方，谁的数据就是事实；两边平票时，找一个改它记录对自己没好处的第三方。 支付公司和微信对账以商户平台账单为准，电商和物流对账以仓储出库记录为准，都是同一个道理。

三幕链条会断在哪里

三幕跨越三个数据库、靠异步消息传递，没有任何全局事务能保证三步原子完成。断点至少有三个：

断在哪	后果	对账看到的现象
第一幕成功、指令没发出去	工行扣了 A 的钱，央行和建行都没动静	付款行有分录、结算侧无记录
第二幕成功、入账通知丢了	钱已到建行在央行的户头，但 B 没到账	结算已确认、收款行漏记
通知重复投递、消费端没做好幂等	B 到账两万	同一笔交易在收款行有重复分录

开篇那个场景就是第三种。记住这三种断裂方式，第四节的差异分类表就不是凭空冒出来的分类，而是这三个断点的直接映射。

demo 的架构

三幕在 demo 里的落点：

%%{init: {'theme':'neutral'}}%%
flowchart LR
 ICBC["工行服务
客户存款账本"]
 CCB["建行服务
客户存款账本"]
 SETTLE["模拟结算服务
清算结果记录"]
 MQ["RabbitMQ
清算通道"]
 RECON["对账 Job
日终逐笔匹配"]
 
 SETTLE -->|"分别投递"| MQ
 MQ -->|"消费记账"| ICBC
 MQ -->|"消费记账"| CCB
 RECON -->|"REST 拉取当日数据"| ICBC
 RECON -->|"REST 拉取当日数据"| CCB
 SETTLE -.->|"对账 Job 同进程
直接读本地库"| RECON

模拟结算服务充当那个「央行的角色」，产生每笔转账的清算结果。RabbitMQ 只是传递这些指令的通道——它不代替结算服务的权威性。对账 Job 从两家银行各拉一份数据，再加上自己进程内的结算记录，凑齐三方才能进入真正的匹配逻辑。

有一处和真实世界的差异要说清楚：现实中是「工行主动向央行发指令，央行结算后通知建行」，方向和顺序都固定；demo 里是结算服务生成结果后通过 RabbitMQ 分别投递给两家银行记账，两家都是被动消费。方向不同，但「三方各记各账、靠同一个交易流水号关联」的骨架一致。

二、单方账本的约束：借贷记账法的边界

在讲跨行对账之前，先要弄清楚一件事：一家银行自己的账本，凭什么说自己是「自洽」的？

答案是一套五百多年前发明的记账规则：借贷记账法（Double-Entry Bookkeeping）。

先把三个词落地

上一节说「工行写入两条」，那两条长什么样？要看懂它，得先落地三个词。

科目：账本上的分类抽屉。银行账本上不写「张三」「李四」，而写「客户存款」「存放央行款项」这样的类别，每一类是一个科目，下面再挂具体账户。第一节里工行记的那两条，科目分别是「客户存款」和「存放央行款项」。

资产和负债：「存放央行款项」是资产——钱存在别人那里，是别人欠银行的。「客户存款」是负债——客户存进来的钱是银行欠客户的，客户随时可以取走。你存 1 万，是银行欠你 1 万，这笔钱在银行账上从来不是「银行的钱」。

借和贷：跟借钱、贷款没有任何关系。它们是会计里的两个方向符号，相当于左和右，五百年前意大利商人记账时定下的习惯，沿用至今。方向怎么定，规则只有两条：

	增加记	减少记
资产	借	贷
负债	贷	借

有了这两条，第一幕那两条分录就能自己读通了：客户存款是负债，减少记借；存放央行是资产，减少记贷。第三幕反过来：存放央行是资产，增加记借；客户存款是负债，增加记贷。

借贷记账法做了什么

每笔账务交易，必须至少产生两条分录——一条记借方（Debit），一条记贷方（Credit），这两条的总金额相等、方向相反。

转账那笔 10,000 元，在工行侧产生的分录是：

方向	科目	金额
借	客户存款（负债减少）	¥10,000
贷	存放央行款项（资产减少）	¥10,000

两条分录的金额相等，借贷平衡。把工行所有账务分录的借方加总、贷方加总，两者必须相等——这就是「试算平衡」。

为什么钱必须记成对？因为钱不会凭空出现——它一定是「从某处来、到某处去」。只记「A 少了一万」而不记「这一万去了哪」，账本就没交代这笔钱的去向。借贷成对，等于强制每一笔都写清来源和去向。

这个约束的价值在于：任何一笔账务操作，要么借方和贷方一起写入（交易提交），要么一起不写（交易回滚）。 数据库的原子提交保证了这一点。所以「借记了一笔但忘了记对应的贷方」在正常运行的系统中不会发生——要么都记，要么都不记。

在 demo 里，这个约束落在 LedgerService.postEntries 上——它接收一组分录，校验借贷平衡后在同一事务写入：

// bank/LedgerService.java（节选）
@Transactional
public void postEntries(List<JournalEntry> entries) {
 // 校验借贷平衡：借方合计必须等于贷方合计
 long debitSum = entries.stream()
 .filter(e -> e.getDirection() == Direction.DEBIT)
 .mapToLong(JournalEntry::getAmountCents)
 .sum();
 long creditSum = entries.stream()
 .filter(e -> e.getDirection() == Direction.CREDIT)
 .mapToLong(JournalEntry::getAmountCents)
 .sum();

 if (debitSum != creditSum) {
 throw new UnbalancedException(debitSum, creditSum);
 }

 // 借贷平衡 + 原子提交：所有分录在同一事务中写入
 repo.saveAll(entries);
}

注意两处和直觉不同的地方：

金额用的是 long（最小货币单位「分」），不是 BigDecimal 也不是浮点。这不是「贬低 DECIMAL」——DECIMAL 本身是精确的定点数，银行系统里也广泛使用。demo 选 long 分是因为它足够表达整数金额、且避免了跨语言序列化时定点数精度不一致的坑。这是工程取舍，不是「浮点不安全所以只能选 long」。
借贷平衡的校验在应用层完成，PostgreSQL 的普通 CHECK 约束无法跨行校验「借方合计 == 贷方合计」——CHECK 只能约束单行的取值范围。这是数据库约束的边界，需要应用层补上。

借贷平衡 + 原子提交，保证了单方账本不会出现「凭空多了一笔钱或凭空少了一笔钱」。但它的保护范围到此为止。

借贷平衡不能发现的问题

试算平衡验证的是账务的内部自洽性，不是业务正确性。以下四类错误，账都是平的——借贷合计仍然相等：

整笔漏记：转账根本没入账。借方和贷方都没有，当然平衡。
整笔重复入账：同一笔转账被记了两次。第一次的借贷平衡，第二次的借贷也平衡，两次合起来仍然平衡。
记错科目：本该借记客户存款，却借记了另一个负债科目。借贷合计对得上，但客户的实际余额不对。
两侧金额同时记错：本来该记 10,000 元，两侧都记成了 1,000 元。借贷平衡，金额错误。

这四类正好覆盖第一节那三个断点：指令没发出去是整笔漏记，通知重复投递是整笔重复入账。它们全是异步链条的正常故障模式，而在单方账本上全都是「平的」——这就是为什么必须有跨方核对。

试算平衡就像一道数学题的自检验算——能证明「我的计算过程没有低级算术错误」，但不能证明「我的算式列对了」。要证明「列对了」，需要和外部数据进行比对。这就是对账要解决的。

%%{init: {'theme':'neutral'}}%%
flowchart TB
 subgraph PASS["「平了」但有问题"]
 direction LR
 P1["整笔漏记"]
 P2["整笔重复"]
 P3["记错科目"]
 P4["金额同时记错"]
 end
 subgraph FAIL["「不平」才是报警"]
 direction LR
 F1["单侧多记"]
 F2["金额单侧偏差"]
 end
 CHECK["借贷平衡校验"] --> PASS
 CHECK --> FAIL

这张图的核心信息是：不要以为账平了就万事大吉。平了只说明单方账簿没有算术错误。对账就是去验证「平了的那几行，是不是真的对应了一笔正确的交易」。

三、实时处理与周期核对可以并存

在讲对账逻辑之前，需要先澄清一个容易混淆的话题：什么时候对账？ 很多人把「清算的实时性」和「对账的时效」混为一谈。

先用一个生活类比把三个词分开。你和同事这个月互相请客：算清楚「他欠我 80 块」是清算，他真的微信转你 80 是结算，月底翻聊天记录和账单确认「确实是 80，不是 180，也没重复算」是对账。

维度	在做什么	时效
清算（Clearing）	计算各方的应收应付义务	HVPS（大额支付系统）逐笔实时，BEPS（小额支付系统）批量轧差
结算（Settlement）	通过资金账户完成义务清偿	大额实时，小额定时净额
对账（Reconciliation）	核对各方记录是否一致	可以是日终批次、小时批次或准实时

清算和结算发生在交易当时（第一节的第二幕），对账发生在事后。这个时间差就是对账存在的全部理由——当时没人能保证三本账都写对了，只能事后摊开来核。

大额支付系统（HVPS）逐笔实时全额清算，每笔大额转账完成时就已经决定了各家银行的应收应付义务，银行间的结算也是实时的。小额支付系统（BEPS）用批量轧差——工行今天欠建行 80、建行欠工行 50，不必转两次，轧一下只转净差额 30；把一段时间里所有小额交易的借方和贷方分别汇总，只结算这个净额。

但不管清算和结算是实时的还是批量的，对账这件事都不一定跟它们同步。对账的时效是一个独立的工程选择，取决于你愿意在多大延迟内发现差异、差异出现时系统里堆积了多少未核对数据。

网联清算平台的做法很有代表性：它的交易是实时转接的，但对账按小时切分成多个批次，每个批次独立处理。好处是把一天的量打散到 24 小时里分别核对，避免了日终集中处理的性能洪峰，也让差异能在小时内被发现、而不是等到第二天。

我们这个 demo 选择日终批次。 不是因为「银行都是这样做的」，而是因为日终批次是理解对账口径最清晰的模型：定义一个业务日的截止点，拉取那一天的完整数据，逐笔匹配，对所有差异做出分类和处理。至于这个「日」是 24 小时、1 小时还是一刻钟，口径不变，只改调度频率。

四、简化对账流水线的实现

好了，原理讲完，开始跑代码。整个 demo 的结构如下：

服务清单

服务	职责	对应第一节哪个角色	端口
`gyd-c03-settlement`	模拟结算服务：生成每笔转账的清算结果记录	央行（第二幕的记账者 + 权威记录源）	18080
`gyd-c03-bank`（bank-a profile）	付款行（工行）：维护客户存款账本，消费清算指令记账	工行（第一幕）	18081
`gyd-c03-bank`（bank-b profile）	收款行（建行）：维护客户存款账本，消费清算指令记账	建行（第三幕）	18082
`ReconJob`（结算服务内的组件）	对账任务：定时拉取三方数据，逐笔匹配，分级处理差异	事后核对，不属于三幕	随结算服务同进程（Spring Scheduler）

三个业务服务各自有独立的 PostgreSQL 数据库，中间通过 RabbitMQ 传递清算指令。对账 Job 随结算服务一起运行——它直接读本进程内的结算记录表（权威数据源），银行侧的分录则通过 REST API 拉取。

数据库表设计

每家银行的账本结构相同：

-- 账务分录表（append-only，已入账的行永不修改）
CREATE TABLE journal_entry (
 id BIGSERIAL PRIMARY KEY,
 entry_id VARCHAR(64) NOT NULL UNIQUE, -- 业务流水号
 trade_id VARCHAR(64) NOT NULL, -- 清算指令 ID（关联结算记录）
 account_id VARCHAR(32) NOT NULL,
 direction VARCHAR(6) NOT NULL CHECK (direction IN ('DEBIT', 'CREDIT')),
 amount_cents BIGINT NOT NULL, -- 金额，最小货币单位（分）
 trade_time TIMESTAMPTZ NOT NULL, -- 业务发生时间
 booked_at TIMESTAMPTZ NOT NULL, -- 记账时间（应用层 Instant.now() 写入）
 reversal_of VARCHAR(64) -- 若为冲正分录，指向被它抵销的那条原始分录（第六节细讲）
);

CREATE INDEX idx_entry_trade ON journal_entry(trade_id);
CREATE INDEX idx_entry_booked ON journal_entry(booked_at);

模拟结算服务的数据库：

-- 清算结果表
CREATE TABLE settlement_record (
 id BIGSERIAL PRIMARY KEY,
 trade_id VARCHAR(64) NOT NULL UNIQUE, -- 清算指令 ID
 from_bank VARCHAR(16) NOT NULL,
 to_bank VARCHAR(16) NOT NULL,
 amount_cents BIGINT NOT NULL,
 settled_at TIMESTAMPTZ NOT NULL, -- 结算完成时间
 status VARCHAR(16) NOT NULL -- 结算状态，SETTLED = 已结算（应用层默认）
);

几个关键设计决策：

金额用 BIGINT 存分（最小货币单位），不是浮点。浮点确实不能用于金额——多笔累加后的舍入误差会制造假差异。但 DECIMAL 本身是精确的定点数，银行系统里也广泛使用，这里选 BIGINT 分而不是 DECIMAL，是为了让跨语言（Java ↔ SQL ↔ JSON）序列化时金额精度完全一致，减少一个出错面。这是取舍，不是说 DECIMAL 不能用。
entry_id 是业务身份。这是对账匹配的核心——同一个 trade_id 在付款行和收款行各自产生分录，各自的 entry_id 不同，但都关联到同一个 trade_id。对账靠 trade_id 匹配。
reversal_of 链。冲正分录指向被冲正的原始 entry_id，形成完整的更正链路。对账的闭环验收靠这个字段追溯。

对账 Job 的核心逻辑

对账 Job 定时执行（demo 里用 fixedDelay，方便跑起来立刻看到结果），拉取当日的完整数据：

// settlement/recon/ReconJob.java（节选，完整代码见仓库）
@Scheduled(fixedDelayString = "${gyd.c03.recon.schedule-ms:60000}",
 initialDelayString = "${gyd.c03.recon.initial-delay-ms:30000}")
public void run() {
 LocalDate today = LocalDate.now();
 Instant start = today.atStartOfDay(ZoneOffset.UTC).toInstant();
 Instant end = today.plusDays(1).atStartOfDay(ZoneOffset.UTC).toInstant();

 // 1. 拉取三方数据（银行通过 REST，结算记录直接查本地库）
 List<SettlementRecord> settlements = settlementRepo.findSettledBetween(start, end);
 List<JournalEntry> bankAEntries = fetchBankEntries(bankAUrl, start, end);
 List<JournalEntry> bankBEntries = fetchBankEntries(bankBUrl, start, end);

 // 2. 以 trade_id 为键建立三方索引
 Map<String, List<JournalEntry>> aByTrade = groupByTrade(bankAEntries);
 Map<String, List<JournalEntry>> bByTrade = groupByTrade(bankBEntries);
 Map<String, SettlementRecord> settlementMap = settlements.stream()
 .collect(Collectors.toMap(SettlementRecord::getTradeId, s -> s));

 Set<String> allTradeIds = new HashSet<>(settlementMap.keySet());
 allTradeIds.addAll(aByTrade.keySet());
 allTradeIds.addAll(bByTrade.keySet());

 // 3. 逐笔匹配：结算侧无记录单独判，其余交给 checkBank 按科目核对
 List<ReconDiff> diffs = new ArrayList<>();
 for (String tradeId : allTradeIds) {
 SettlementRecord settlement = settlementMap.get(tradeId);
 List<JournalEntry> aEntries = aByTrade.getOrDefault(tradeId, List.of());
 List<JournalEntry> bEntries = bByTrade.getOrDefault(tradeId, List.of());

 if (settlement == null) {
 // 银行有分录、结算侧查不到已结算记录 → 待查，不自动修正
 if (!aEntries.isEmpty()) {
 diffs.add(new ReconDiff(tradeId, ReconDiffType.NO_SETTLEMENT,
 Bank.ICBC.code(), entryIds(aEntries), -1, 0));
 }
 if (!bEntries.isEmpty()) {
 diffs.add(new ReconDiff(tradeId, ReconDiffType.NO_SETTLEMENT,
 Bank.CCB.code(), entryIds(bEntries), -1, 0));
 }
 continue;
 }

 checkBank(aEntries, settlement, Bank.ICBC, tradeId, diffs);
 checkBank(bEntries, settlement, Bank.CCB, tradeId, diffs);
 }

 // 4. 分级处理差异（processDiff 按类型决策）
 for (ReconDiff diff : diffs) {
 processDiff(diff, settlementMap);
 }

 // 5. 闭环验收
 verifyClosedLoop(diffs, settlementMap, start, end);
}

checkBank 里的匹配规则：

结算侧有没有记录，在主循环里单独判，不在 checkBank 里：findSettledBetween 已经过滤掉非 SETTLED 的记录，所以「银行有分录、结算侧查不到」直接标 NO_SETTLEMENT（待查）。checkBank 只负责单侧的逐科目核对。
本行的角色从结算记录的 fromBank / toBank 推导，不写死「工行一定是借方」——反向交易（建行付给工行）时，两个科目的方向会整体反过来。
按科目逐个核对，不是只看一个方向：本行这笔交易应该在「客户存款」和「存放央行款项」上各有一条净分录，预期方向由 account.directionFor(movement) 推导。
金额以结算记录为准（权威数据源）。某科目上没有分录 → MISSING；多于一条净分录 → DUPLICATE；方向与预期不符 → DIRECTION_MISMATCH；金额不符 → AMOUNT_MISMATCH。
只比「净分录」——已被冲正的原始分录不参与匹配，这一步在银行侧的查询里就完成了（findNetByBookedAtBetween）。
金额不作为唯一匹配依据——如果金额匹配但 trade_id 不匹配，这不是同一笔交易。

匹配结果的分类：

结算记录	付款行分录	收款行分录	分类
有、状态=SETTLED	有、金额匹配	有、金额匹配	✅ 平
有、状态=SETTLED	无或金额不匹配	有	付款行漏记/金额偏差
有、状态=SETTLED	有	无或金额不匹配	收款行漏记/金额偏差
有、状态=SETTLED	方向与角色不符（金额对得上）	同左	方向记反（`DIRECTION_MISMATCH`）
有、状态=SETTLED	重复（同一 trade_id 多笔）	—	付款行重复入账
有、状态=SETTLED	—	重复（同一 trade_id 多笔）	收款行重复入账
无或状态≠SETTLED	—	—	待查：结算结果未知
有、状态=SETTLED	在途（trade_time 在截止点附近）	—	等待：数据可能尚未齐备

最后一行的「在途」指交易已经发起、但三幕还没走完的状态——比如第一幕工行记了账，第三幕的入账通知还在路上。这类记录不是错误，只是数据还没齐，下一批次再核。

这里有一处代码与表格的落差，直说：IN_FLIGHT（在途）作为差异类型和处理分支是存在的——processDiff 对它只发 [P2][在途] 告警、不动账，闭环验收也不把它算进失败——但 checkBank 当前并不会主动产出这一类差异。它实际判定的是 MISSING（漏记）、DUPLICATE（重复入账）、DIRECTION_MISMATCH（方向记反）、AMOUNT_MISMATCH（金额不符）四类，主循环另判 NO_SETTLEMENT（结算侧无记录）。主动判定在途需要一套「交易发起时间 vs 对账截止点」的口径规则，属于对账口径设计，留到讲口径的那一篇。

五、差异不是错误：分级处理，不是统一冲正

对账最容易被误解的地方是：发现了差异，不代表知道了问题。 差异只是一个信号——两侧记录不一致。至于不一致的原因，是漏记、多记、记错、还是数据还没到，对账本身无法区分。

回到开篇那个场景：报表上说建行侧多了一条分录。这条信息只告诉你「两边对不上」，它没告诉你该不该动、动哪一条、动了之后钱会不会退回去。

分级决策模型

对账 Job 对差异的处理不是「有一个差异就冲一笔」。它先判断这个差异的类型，再做对应动作：

%%{init: {'theme':'neutral'}}%%
flowchart TB
 DIFF["对账发现差异"]
 
 DIFF --> Q1{"结算侧
有对应记录？"}
 Q1 -->|"无"| WAIT1["待查：标记为 pending
下一批次重新核对"]
 Q1 -->|"有"| Q2{"结算状态
是 SETTLED？"}
 
 Q2 -->|"否"| WAIT2["等待：交易仍在途
下一批次重新核对"]
 Q2 -->|"是"| Q3{"哪一侧
不一致？"}
 
 Q3 -->|"付款行缺分录"| ACT1["补记：根据结算记录
补入借记分录"]
 Q3 -->|"收款行缺分录"| ACT2["补记：根据结算记录
补入贷记分录"]
 Q3 -->|"金额不符"| ACT3["挂起：查证原指令
人工裁决后修正"]
 Q3 -->|"重复入账"| ACT4["挂起：无法判断哪组多余
人工裁决后冲正"]

这个决策树的每一层都依赖一个前提：结算记录是权威数据源。 结算侧说这笔钱该付、该转，那它就是事实。银行分录如果缺了、多了、金额错了，以此为基准修正。

但反过来，如果结算侧没有记录、或状态不是 SETTLED，对账 Job 不做任何自动修正——它记一条 NO_SETTLEMENT 差异，走 [P1][待查] 告警，等下一个批次重新核对。权威源缺位时，宁可什么都不做也不猜。

自动处理 vs 人工裁决

哪一类差异能自动处理？

漏记 + 结算已确认：结算侧明确有一笔成功的清算结果，但某家银行没有对应的分录。这是最干净的情况——补记即可。补记的「正确动作」完全由结算记录决定（补哪一侧、补多少金额），没有歧义。

哪些只能人工裁决？

重复入账：同一 trade_id 在同一侧出现了多条分录。trade_id 相同说明这是重复，但无法判断「哪一组是正确的那组、哪一组该冲正」——自动冲正必须回答「冲哪一组」，而这个答案对账本身给不出来。开篇那个场景就落在这里：程序知道建行侧多了一条，但不知道该消哪条。
金额不符：两边金额对不上，而且结算结果看不出金额是对是错（结算结果本身的金额也是参与方上报的）。需要回溯原始支付指令确认。
结算侧无记录：可能是延迟、系统故障，也可能是欺诈交易。不自动处理。

区分「能自动处理」和「只能人工裁决」的边界很清晰：当正确的修正动作能由权威数据源唯一确定时，可以自动处理；当存在多个可能的动作、或正确动作无法从数据里推断时，只能挂起等人裁决。 漏记的补记动作由结算记录唯一确定（补、补多少都明确），所以能自动做；重复入账要冲正哪一组、金额不符到底哪边错，都存在歧义，所以只能人工。

一个易混淆的点：本地账务的冲正和外部资金的退回是两件事。 银行发现一笔跨行转账记重了，冲正的是本地账本里的多余分录——这不会自动把钱从对方银行退回来。那笔钱已经通过央行结算，结算最终性成立后不可撤销；要追回得走独立的退款流程，需要对方银行配合。如果资金还没完成结算，另一条路是止付——让央行拦下这笔尚未落地的资金，不再继续结算。对账 Job 只处理本地账务的一致性，不管外部资金的流向。

// settlement/recon/ReconJob.java（节选）：补记漏记分录
private void compensateMissing(String bankUrl, ReconDiff diff, SettlementRecord s) {
 try {
 restTemplate.postForEntity(bankUrl + "/api/bank/compensate",
 Map.of("tradeId", diff.tradeId(),
 "fromBank", s.getFromBank(),
 "toBank", s.getToBank(),
 "amountCents", s.getAmountCents(),
 "settledAt", s.getSettledAt().toString()),
 String.class);
 log.info("[recon] 补记完成: tradeId={}, 银行={}, 科目={}, 金额=¥{}.{}",
 diff.tradeId(), bankLabel(diff.bankCode()), diff.account().label(),
 s.getAmountCents() / 100, s.getAmountCents() % 100);
 } catch (Exception e) {
 // 补记失败不能中断整轮对账：记下来，下一批次重新核出同一条差异再补
 log.error("[recon] 补记失败: tradeId={}, 银行={}", diff.tradeId(), diff.bankCode(), e);
 }
}

补记动作本身在银行侧执行（BankController.compensate），它复用和消费记账相同的 LedgerService，所以补记的分录同样受借贷平衡和幂等约束——补一笔漏记，也是补「一组」分录（客户存款 + 存放央行款项），而不是孤零零补一条。

六、冲正不是删除，是追加式更正

「发现错了，能不能把那条错的分录删掉？」这是很多工程师的第一反应。答案是：不能。 已入账的分录一旦写入，本 demo 的设计是禁止后续修改或删除的。

这不是保守，而是两道硬约束决定的：

审计追溯：外部审计师需要看到完整的账务变迁历史。原始记录消失，审计就失去了锚点。
修复幂等：如果允许删除原始记录然后重新写入，对账 Job 重复执行时就会把已修复的数据再次标记为差异，进入死循环。

纸质账本上也是同一个道理：用圆珠笔记的账，写死的字划不掉，记错了只能在下面补记一笔反向的，两笔抵消，但两条笔迹都留在本子上。冲正的做法就是这一条：写一组金额相等、方向相反的新分录，来抵销原分录的影响。 而且关键的是——冲正不是「逐条反」某一条 posting，而是按 trade_id 找到这笔交易的整组分录（客户存款 + 存放央行款项两条），一起反向。

为什么必须整组反向？因为借贷平衡是对「一组分录」的约束。只反其中一条，这一组就不平了，postEntries 的校验会直接把它拒掉。

// bank/LedgerService.java（节选）
@Transactional
public int reverseByTradeId(String tradeId) {
 return reverseEntries(repo.findOriginalByTradeId(tradeId));
}

/** 冲正的实际动作：为一组原始分录生成等额反向分录并写入 */
private int reverseEntries(List<JournalEntry> originals) {
 if (originals.isEmpty()) {
 return 0;
 }

 List<JournalEntry> reversals = new ArrayList<>();
 for (JournalEntry original : originals) {
 String reversalEntryId = "REV-" + original.getEntryId();
 // 已有冲正记录则幂等跳过：重复执行冲正不会写出第二组反向分录
 if (repo.findByEntryId(reversalEntryId) != null) {
 continue;
 }
 Direction revDir = original.getDirection().opposite();
 reversals.add(new JournalEntry(reversalEntryId, original.getTradeId(),
 original.getAccountId(), revDir, original.getAmountCents(),
 original.getTradeTime(), original.getEntryId()));
 }

 // 整组反向分录同样走 postEntries，受借贷平衡校验
 if (!reversals.isEmpty()) postEntries(reversals);
 return reversals.size();
}

冲正的入口有两个：整笔撤销走 reverseByTradeId，人工裁决「只冲多余那组」走 reverseByEntryIds——后者必须由人指定冲哪几条，因为重复入账时一个 trade_id 下有两组分录，整组冲正会把合法的那组也冲掉。两个入口共用 reverseEntries，所以幂等和借贷平衡的行为完全一致。

注意三个要点：

冲正必须保持借贷平衡。 原分录是借记客户存款 ¥10,000、贷记存放央行款项 ¥10,000，冲正分录是贷记客户存款 ¥10,000（反向）、借记存放央行款项 ¥10,000（反向）。不是孤零零写一条 posting。
reversal_of 指向原始分录。 对账闭环验收时，通过这个链条确认「差异 → 原始分录 → 冲正分录 → 重新核对平了」。
冲正只更正本地账务。 前面说了，外部支付已经发生了，冲正不改外部事实。

原始分录和冲正分录并排看（以工行付款侧为例，两条原始分录共享同一个 trade_id，但各有独立的 entry_id；trade_id 是 TRD- 加 8 位随机大写十六进制，entry_id 的末尾 CUST / PBOC 是科目标记）：

分录类型	分录 ID	方向	科目	金额	备注
原始	`E-TRD-2B14449D-ICBC-CUST`	借	客户存款	¥10,000	正常记账
原始	`E-TRD-2B14449D-ICBC-PBOC`	贷	存放央行款项	¥10,000	正常记账
冲正	`REV-E-TRD-2B14449D-ICBC-CUST`	贷	客户存款	¥10,000	抵销上面那笔借方
冲正	`REV-E-TRD-2B14449D-ICBC-PBOC`	借	存放央行款项	¥10,000	抵销上面那笔贷方

四条分录合在一起，净借贷合计仍然是 0。账平了，原始记录还在，审计师可以看到「发生过什么、怎么修正的」。

七、为什么对账不能替代幂等

对账是事后发现，幂等是事前防护。很多人觉得「有了对账就不需要幂等」，这个想法有一个根本性的问题：对账只能发现「结果不一致」，它不知道「不一致的原因」。

上一篇讲的消费端幂等，防的是「同一条消息被处理两次」；这里的对账，查的是「处理完之后三本账对不对得上」。两者在链路上前后相接：幂等让第一节的第三个断点（重复投递）尽量不发生，对账在它还是发生了之后把差异捞出来。

有业务身份，对账能做的远比「人工裁决」多

这个问题的关键不在于幂等键本身，而在于业务身份是否可追溯。 如果每一笔交易都有一个唯一的 trade_id，并且这个 ID 贯穿了从结算指令、银行分录、到对账匹配的整条链路，那么：

对账可以准确判断两笔相同金额的记录是不是同一笔交易的重复执行（因为 trade_id 相同）。
对账可以区分「两笔金额一样的合法交易」和「同一笔交易记了两次」。

反过来，如果系统里根本没有 trade_id 这样的业务身份，记账时只写了金额、方向和时间戳，那对账面对两条 ¥10,000 的借记分录时，完全无法判断这是一笔重复记账还是两笔独立的合法转账。

但即便有了 trade_id，重复入账的自动修复也不是理所当然的。trade_id 相同只能说明「这是同一笔交易产生了多余的分录」，却不能告诉你「哪一组是正确的那组、哪一组该冲正」。这也是为什么 demo 里对重复入账（DUPLICATE）的处理是标记人工裁决，而不是自动冲正——自动冲正必须回答「冲哪一组」，而这个答案对账本身给不出来。

幂等键的三个必要条件

幂等键（Idempotency Key）只是第一步。要让对账能做到自动修复，还需要三个条件同时满足：

消费端实际执行唯一性控制。 不是生产端带了一个键就叫幂等——消费端必须在写入前检查这个键是否已经处理过。如果消费端收到带相同键的消息直接再次写入，键就是摆设。
去重记录与账务写入在同一个事务中。 先检查去重再记账，中间断开事务，竞态条件下仍然可能重复写入。
同一键携带不同金额时能拒绝冲突。 如果一个键第二次出现时带的金额和第一次不同，系统应该拒绝而不是覆盖。

// bank/LedgerService.java（节选）：消费端的幂等写入
@Transactional
public boolean postIfNew(List<JournalEntry> entries) {
 String tradeId = entries.getFirst().getTradeId();
 // 幂等检查：这个 trade_id 已经记过账了？
 if (repo.existsByTradeId(tradeId)) {
 return false; // 幂等跳过，不重复写入
 }
 // 记账：去重检查 + 分录写入在同一事务中完成
 postEntries(entries);
 return true;
}

消费端 BankSettlementConsumer.onSettlement 调用它，收到重复消息时返回 false 直接跳过——这是正常的幂等跳过，不是错误，所以不抛异常、照常 ack。

核心结论：决定对账自动修复能力的，不是有没有幂等键，而是业务身份是否可追溯、以及能否据此确定「正确的动作」。 有可追溯的业务身份，对账可以精准定位差异、判断漏记并补记；但没有业务身份、或虽有身份却无法判断哪边该修正（比如重复入账该冲哪一组），对账就只能标记差异，等着人来看。幂等键是让「不产生重复」成为可能，而对账负责在「已经产生差异」时给出能追溯的处理。

八、从银行对账到分布式系统设计

对账这件事，拆开来看，其实是一个通用分布式系统的设计骨架。把前面几节里出现的核心设计模式抽象出来，它们都对应着分布式系统中反复出现的工程手段。

对账系统中的设计	解决的问题	分布式系统通用表达
借贷平衡约束	保证单方账本不自相矛盾	可校验的内部一致性：任何系统都应该有办法自证「状态没乱」，但不等于状态正确
业务身份（`trade_id`）	让对账能准确匹配同一笔交易	全局唯一请求标识：跨服务追踪、去重、匹配的基础
追加式更正（冲正）	修正错误而不破坏审计链	不可变日志 + 补偿操作：Saga 的补偿动作、Event Sourcing 的逆事件
第三方结算数据	提供独立的事实来源	外部权威数据源：跨系统对账不能只靠两方互对
分级处理决策树	不同差异不同动作	错误分类 + 分级恢复策略：在途、补记、冲正、待查各有对应的处理方式
对账 Job 的幂等设计	重复执行不对数据造成二次伤害	可重入任务：修复操作的结果是幂等的

这张表里的每一行，回到第一节的三幕链条上都有具体落点：借贷平衡管住一幕之内的自洽，trade_id 把三幕串成同一笔交易，冲正让改错不毁历史，结算记录提供跨幕的裁判，分级决策决定每种断裂怎么收场。

对账最大的工程价值：分离「发现」和「修复」

很多人把对账理解成「一个定时任务，跑完报一堆差异」。但它的工程价值不在「发现差异」——任何简单的比对脚本都能做到。对账的真正价值在于：

对账确定了「差多少」，分级处理确定了「怎么补回去」。 这两个问题被拆成两个独立的步骤，各自有独立的执行逻辑、独立的幂等保证。

这个分离是金融系统能在出错后继续运行的基石。如果发现差异的同时就「自动修正」，那修正错了怎么办？修正再修正？系统会陷入不可追溯的循环。但把它们分开——对账先给出一个不可变的事实陈述（「2026 年 9 月 14 日的日终核对显示，trade_id=TRD-2B14449D 在工行的客户存款科目上缺失分录」），然后分级处理再给出可追溯的修正动作（「根据结算记录补记分录 entry_id=COMP-TRD-2B14449D-ICBC-CUST」）——每一步的结果都可以被验证、被追溯、被重新评估。

闭环验收：没有重新核对就不算修好

修复动作完成后，不能以「生成了补记分录」或「写入了冲正记录」作为成功标准。真正的成功标准是：对当前这批数据重新跑一遍对账逻辑，差异消失了。

// settlement/recon/ReconJob.java（节选）：闭环验收
private void verifyClosedLoop(List<ReconDiff> diffs, Map<String, SettlementRecord> settlementMap,
 Instant start, Instant end) {
 // 只有「本轮自动处理过」的差异参与闭环。挂起等人工的、等下一批次的不算失败——
 // 它们本来就不该在这一轮被修好，算进失败会让「闭环失败」失去信号意义。
 List<ReconDiff> autoFixed = diffs.stream()
 .filter(d -> d.type() == ReconDiffType.MISSING
 && settlementMap.containsKey(d.tradeId()))
 .toList();
 if (autoFixed.isEmpty()) {
 log.info("[recon] 本轮无自动处理的差异，跳过闭环验收");
 return;
 }

 // 重新拉取净分录（已被冲正的 journal 不再参与），复用 checkBank 重新核对
 Map<String, List<JournalEntry>> aRecheck = groupByTrade(fetchBankEntries(bankAUrl, start, end));
 Map<String, List<JournalEntry>> bRecheck = groupByTrade(fetchBankEntries(bankBUrl, start, end));

 List<String> remaining = new ArrayList<>();
 for (ReconDiff diff : autoFixed) {
 SettlementRecord s = settlementMap.get(diff.tradeId());
 Bank bank = Bank.fromCode(diff.bankCode());
 List<JournalEntry> now = (bank == Bank.ICBC ? aRecheck : bRecheck)
 .getOrDefault(diff.tradeId(), List.of());

 List<ReconDiff> recheckDiffs = new ArrayList<>();
 boolean ok = checkBank(now, s, bank, diff.tradeId(), recheckDiffs);
 if (!ok) {
 remaining.add(diff.tradeId() + "/" + diff.account().label());
 }
 }

 if (remaining.isEmpty()) {
 log.info("[recon] 闭环通过: {} 条自动处理的差异已重新核对为平", autoFixed.size());
 } else {
 log.error("[recon] 闭环失败: {} 条差异补记后仍不平: {}", remaining.size(), remaining);
 }
}

这里有一个容易被忽略的细节：闭环验收不能用「数一下分录条数对不对」这种简化判断。因为冲正是追加式的，原始分录不会删除，冲正后「原始分录条数」不会变——只有按「净分录」（原始分录中尚未被冲正的部分）重新跑一遍完整的匹配逻辑，才能确认差异真正消失。

闭环验收 + 不可变差异记录，构成了对账系统最底层的安全网：对账能证明自己修好了，而不是「相信」自己修好了。

参考资料

中国人民银行, 小额支付系统业务处理手续（试行）, 央行官网公开文档. https://www.pbc.gov.cn/eportal/fileDir/history_file/files/att_19041_2.pdf —— 冲正、止付与退回流程的官方定义
金融时报, 网联平台荣获 2019 年度银行科技发展奖特等奖, 2020-09-25. https://www.financialnews.com.cn/if/hydt/202009/t20200925_201999.html —— 网联「三地六中心」架构与小时级多批次对账设计
ACCA, Suspense accounts and error correction, Foundation Level Study Resources. https://www.accaglobal.com/gb/en/student/exam-support-resources/foundation-level-study-resources/ffa/ffa-technical-articles/suspense-accounts-error-correction.html —— 试算平衡无法发现的六类错账
Formance, Transaction Reconciliation at Scale: An Engineering Guide. https://www.formance.com/blog/engineering/transaction-reconciliation-at-scale-for-eng —— 对账前的四项账本不变约束：复式记账、幂等、不可变性、双时态

演示代码：完整实现在 GYD 仓库 c03-reconciliation，PostgreSQL 编排在仓库级 infra/。按各目录 README 的命令跑，不要复制这篇文章里零散的代码块。

第二话｜消息队列的可靠投递与可靠消费：不丢靠三段兜底，不重只能靠幂等

Wed, 11 Feb 2026 00:00:00 +0000

一张订单表里多了一行，下游的发货系统没有收到这条消息。

订单服务在创建订单成功后投递 order.created，发货、积分、通知三个下游各自消费它。这一笔的发送日志打着成功，订单表里有数据，下游的队列里没有消息。这条消息死在了哪一段？

消息队列从进入架构的第一天就带着「可靠」的承诺，但这句承诺不是某一个组件给的，而是生产者、Broker、消费者各兜一段才拼出来的。任何一段缺了兜底，都会出现「发送成功、下游没收到」。

这条链路的骨架：消息穿过生产者、Broker、消费者三个边界，Broker 里是交换机到队列的一段路由；路径上还有两个反向回执——Broker 回给生产者的 confirm、消费者回给 Broker 的 ack。

顺着这条消息的生命周期走一遍，它有三个可能消失的位置：

发送时：生产者以为发出去了，消息却没进 Broker，或者进了 Broker 却没进任何队列。那笔订单的发送日志打的就是「成功」。
存储时：Broker 收下了，回执也回了，消息还没挺过一次重启就从磁盘上消失。
消费时：消费者读到了，处理到一半进程挂掉，重启后不知道这一笔该不该再处理。

这三个位置分别由生产者、Broker、消费者兜住，彼此没有替代关系：生产端再严谨也管不到消费者崩溃，Broker 副本再多也管不到生产者发错了路由键。

这条链路上有两类问题，经常被混在一起谈：

不丢：一条消息从产生到被处理完，中途不能消失。
不重：同一笔业务不能被处理两次。

在 Broker 这一层，这两类目标是冲突的：要保证不丢，就得允许重复投递。真正的「既不丢也不重」要到消费端用幂等去拼，Broker 给不了。

GYD 这个系列讲分布式系统里各种解决方案的实现方式。消息队列出现得早，也最容易被当成「基础设施，接上就行」的一环，而可靠性缺口通常就藏在这个默认判断里。

这三段在 RabbitMQ 4.3.5 上分别跑一遍。结论对应的是 RabbitMQ 4.3.5 + Spring Boot 4.1.1 + Spring AMQP 4.1.1 + amqp-client 5.30.0 + JDK 21；完整实现、端点对照与复现方式在仓库 c02-mq-reliable-delivery，下面每处结论后面也各自带了落点。

一、生产端：confirm 和 return 是两件事

RabbitMQ 的投递路径是 生产者 → 交换机 → 绑定 → 队列。生产者把消息发给交换机，交换机再根据绑定关系决定它进哪些队列。

消息先到交换机这一层，意味着「到了 Broker」和「进了队列」是两个可以分开发生的事件。RabbitMQ 给了两个独立机制来报告它们：

机制	报告的是什么	触发条件
publisher confirm	视路由结果分情况：可路由＝路由到的队列已接收；不可路由＝确认没有目标队列	消息被交换机处理之后
publisher return	消息没能路由到任何队列	交换机找不到匹配的绑定，且投递时设置了 `mandatory`

这两道回执在配置里是两个分开的开关（publisher-confirm-type 收 confirm、publisher-returns 收退回），默认都不开；客户端代码侧还要给发送模板打上 mandatory 标记、并分别注册两个回调。缺了任何一处，等于少了一道回执。

把一条消息投到没有任何队列绑定的路由键上，日志会连出三件事：生产端记下自己把消息投了出去；Broker 退回一条 NO_ROUTE，说明没有任何队列接收它；紧接着是一条 confirm 的 ack，说 Broker 已确认。再去查队列深度，两个业务队列都是 0 条（端点 unroutable）。

confirm 返回了 ack，消息已经被丢掉了。

官方文档在描述这件事时语气很平淡：「对不可路由的消息，Broker 会在交换机确认没有队列可路由之后发出 confirm；如果消息同时以 mandatory 方式发布，basic.return 会在 basic.ack 之前发给客户端。」文档没有单独警告不处理 return 会怎样，但把两者的定义摆在一起，结论是清楚的：confirm 的 ack 不是一律「成功」，它跟着路由结果走。路由到了队列，ack 表示队列已接收；路由不到，ack 只表示「确认了没有队列」，这条消息已经丢了。

只监听 confirm 而不管 return 的服务，等于在发送环节装了一个常亮的绿灯。

这里还有个更隐蔽的边界：return 的语义是「一个队列都没路由到」，所以「没有 return」只说明至少有一个队列接收了，不能证明发货、积分、通知三个预期订阅都配置正确。漏配了一个订阅，消息照样 confirm ack、照样不 return，只是那个下游安静地没收到。这个边界单靠发送端的回执是看不见的。

flowchart LR
 A["投递一条消息"] --> B{"有队列绑定这个路由键吗"}
 B -- 有 --> C["消息进入队列
confirm: ack"]
 B -- 没有 --> D["没有队列接收
confirm: ack
return: NO_ROUTE"]

需要等回执再继续的场景，可以同步等确认结果（示例里给了 3 秒超时）。这里有一处容易写漏：不可路由时 confirm 依然返回 ack，此时消息已被退回、并未进队列，所以只查 ack 会把「路由不到队列」当成「发送成功」，必须再查一次退回结果。同步等回执会拖住发送方。文档里给了个量级：在持续负载下，ack 的延迟可以达到数百毫秒，因此它建议把 confirm 当作异步事件流处理，或者批量投递、统一等待整批回执。同步等待更适合这里这种单条验证，一眼就能看出这一条到底有没有被 Broker 收下。

生产端的可靠性到这里只解决了一半。ack 在「路由不到队列」时并不代表成功，不是回执说了假话，是应用把成功条件理解少了：只盯 confirm 不看 return，就把「没有队列」当成了「发送成功」。而一旦把发送失败当成功、靠重试兜底，「同一笔订单发了两遍」的概率就不再为零。可靠性问题的另一半，是从生产端的重试里长出来的。

二、Broker 端：持久化要分清「消息恢复」和「拓扑恢复」

消息进了队列，下一个问题是它会不会在 Broker 这一侧消失。这里要先把两件事分开：已经入队的消息能不能挺过重启，和重启后拓扑（交换机、绑定）还在不在。它们由不同的属性决定，不能混成一句话。

对一条 classic queue 里的消息，「能不能挺过重启」只看两个属性：

属性	落点	缺了会怎样
队列持久化	声明队列时标 `durable`	重启后队列连同消息一起消失
消息持久化	投递时标 `deliveryMode=2`	队列还在，队列里的这条消息不在

交换机的 durable(true) 是另一件事，管的是拓扑恢复：它决定重启后这个交换机还在不在、还能不能继续往它投，但不决定已经入队的消息能否恢复。所以别把交换机、队列、消息并列成「三个都要持久化」——交换机那条管的是「以后还能不能投」，跟「已经投进去的还在不在」是两码事。

官方文档对「能不能挺过重启」的说法是：durable queue 的元数据写磁盘，重启时会被恢复，「包括其中以 persistent 方式发布的消息。以 transient 方式发布的消息会在恢复过程中被丢弃，即使它们的队列是 durable 的。」

这两个属性里，消息持久化这条更容易被漏：队列的 durable 在声明时顺手就写了，消息的 deliveryMode 却要每次投递单独指定。

用一条不挂消费者的持久化探针队列做对照（这个实验只在 classic queue 上成立，quorum queue 的持久化不依赖 deliveryMode）：投一条持久化、一条非持久化，两条都会收到 confirm 的 ack；重启 Broker 之后队列深度从 2 掉到 1，messages_persistent 一直是 1。再单独投一条非持久化消息复验：重启前深度 1，重启后归 0（端点 probe）。

ack 是否意味着落盘，取决于消息和队列的持久化属性。 文档给「持久化消息投到持久化队列」这种组合打了包票，那时 ack 意味着已经写盘。但只要消息属性没标持久化，ack 照样返回，重启后它无声消失。

单机持久化挡得住进程重启，挡不住磁盘损坏和机器故障。要扛机器级故障，只能用副本，在 RabbitMQ 4.x 上意味着 quorum queue——文档里那句「Classic queue mirroring was removed starting with RabbitMQ 4.0」，把过去的退路一并关掉了。

quorum queue 基于 Raft，副本关系里有一个 leader 和若干 follower，可用性由「多数派是否在线」决定。单节点验证不了这件事，所以另起了一套 3 节点集群（infra/rabbitmq-cluster/，端口与单节点错开，可以同时运行）。观察到的是这样一串：声明出来的 quorum queue 副本组实为 3 个成员、leader 落在 rmq1；投 3 条持久化消息全部收到 confirm；停掉 leader 所在节点后重新选主（两次运行分别落在 rmq2 与 rmq3），2/3 在线时继续投 2 条都成功，而且能取回全部 5 条，原 3 条一条不少；再停一个、只剩 1/3 时投递被拒，15.0s 后返回 NackError: 0 message(s) NACKed；把停掉的节点恢复回来，队列自愈到 3/3、投递恢复，而被 NACK 的那条并没有留在队列里（脚本 quorum-majority.py）。

quorum queue 的可用性由多数派决定：2/3 在线可以读写，掉到 1/3 就无法提交写入。 这不是丢消息，是 Raft 为避免脑裂做的取舍：宁可拒绝写入，也不让两个分区各自接受写入。客户端看到的表现不一定是即时报错，可能是等待、超时，也可能是明确的 NACK（本次实测是 15s 后返回 NackError）。

顺带一个观测上的坑：失去多数派时，连读队列视图本身都会超时，list_queues 时好时坏。故障期间的监控图表断点，有一部分来自这里。

维度	单机 durable queue	quorum queue
数据存活范围	单节点磁盘	多数派副本
扛得住什么	进程重启、节点重启	节点重启、单机磁盘损坏、少数派节点丢失
可用性前提	节点在线	多数派在线（3 节点可容忍 1 个）
代价	—	每次投递要复制到多数派，写入路径更长

quorum queue 的 confirm 语义也跟着变严：只有在消息被复制到多数派成员之后，Broker 才会发出 publisher confirm。 这一点和单机队列不同，单机队列上「收到 ack」离「数据安全」还有距离，quorum queue 上这句话的分量更重。

副本组本身也有几条固定约束：quorum queue 必须是持久化队列（Raft 的副本机制不建立在内存队列上）；官方建议副本数为奇数，默认 group size 是 3；文档明确写了「不要在多过 7 个 RabbitMQ 节点上运行 quorum queue」，也提醒少于 3 个节点的集群拿不到 quorum queue 的完整保证。本次实测的 3 节点加 group size 3，正好是能观察到选主、多数派可用性和少数派拒写的最小配置。

三、消费端：ack 时机与 prefetch 决定崩溃后重投多少条

消息安全躺在队列里，最后一个缺口在消费者手里。ack 的时机就是一次投票：投给「不丢」，还是投给「不重」。

处理成功后再确认、还是先确认再处理，是两个方向相反的取舍：先处理成功后 ack，中途崩溃消息会重投，于是可能重复处理；先 ack 再处理，中途崩溃时消息已删除，于是可能丢失。autoAck 是后者的极端形式，消息一交给消费者就当作已确认，跑得最快，也最不设防。

这里要插一句和 Spring 的边界：上面两种只是 AMQP 层的 manual / autoAck；Spring 还有一个默认的 AUTO 模式，它是容器在监听方法成功返回后替你 ack，比 autoAck 保守，比 manual 省事。这套 demo 用的是 manual，配置里关掉框架自动确认，把 ack 时机完全交给业务代码：业务成功才 ack，失败则带 requeue=false 拒绝，交给重试链路（不重回原队列，否则会原地死循环）。

flowchart LR
 A["收到一条消息"] --> B{"先做哪一步"}
 B -- "先处理，成功后 ack" --> C["中途崩溃
消息重投，可能重复处理"]
 B -- "先 ack，再处理" --> D["中途崩溃
消息已删，可能丢失"]

选完 ack 时机，还有一个必须显式决定的参数：prefetch。

RabbitMQ 的消费模型是「未确认消息的集合」，不是 Kafka 那种记「读到哪了」的位点。Broker 把消息推给消费者，在收到 ack 之前一直记着这些消息属于这个消费者，没有 ack 就没有「位点前进」，只有「这条还没结清」。于是 prefetch（协议里的 basic.qos）决定了一个消费者最多同时持有多少条未确认消息。

这个参数不影响单条消息的处理速度，它影响的是消费者崩溃时有多少条要重投。用 50 条慢消息（每条处理 200ms）只改 prefetch 来对照：设成 1 时未确认条数恒为 1，设成 20 时恒为 20，而 50 条排空都花约 10s（端点 burst）。两者的吞吐相同，差别在同时在途的未确认条数。 如果消费者在任一时刻崩溃，prefetch=1 最多重投 1 条，prefetch=20 最多重投 20 条。

这里有个边界要说清楚：本实验的瓶颈在消费处理本身（每条固定 200ms），所以两者耗时相同。如果消费逻辑很快、网络往返占比高，prefetch 取值会明显影响吞吐，那是另一个结论，不能从这组数据外推。表里的「恒为」也只成立在积压充足阶段，消息源源不断时未确认条数稳定在 prefetch 上限；排空的最后一段，队列里剩不足 prefetch 条，未确认条数会掉下来。另外，实验只测了单消费者，多消费者共用一个队列时的负载分摊没有测。

还有一件事值得和 prefetch 分开看：消费者崩溃后，那些未确认的消息会被重新投递，但不一定回到同一个消费者。Broker 把它们放回队列等重新分配，多个消费者在场时通常落到别人手里。这就是为什么扩容之后「同一笔业务被两个消费者各处理一次」会更常见，幂等在那里不再是理论问题。

至于 prefetch 该定多少，没有一个可以照抄的数。它取决于单条消息的处理耗时、下游能承受的并发、以及你愿意接受崩溃时重投多少条。文档里 0 表示不设上限，等于把未确认集合交给内存和连接去决定，生产环境一般不会这么配。Broker 侧另有一个「消费者没指定时生效」的默认 prefetch，可在高级配置里调整（文档示例给的值是 250），所以不显式设置并不等于没有限制，只等于这个数由别人替你定了。

四、不丢和不重分别落在两层：Broker 管投递，幂等管效果

前三段各自解决了一类丢失，代价是把重复引了进来：生产端的重试会重发，消费端的 ack 时机（先处理再确认）会重投。要理解这件事的边界，得先看清 Broker 能承诺什么。

官方可靠性文档把话说得很直白：「使用 acknowledgements 保证 at least once 投递。不使用 acknowledgements 时，发布和消费过程中都可能丢消息，只能保证 at most once。」至于 exactly-once，文档在同一页给出了它的现实形态：生产者重传、确认丢失时消息可能重复，「因此消费端应用需要做去重，或者以幂等的方式处理收到的消息。」

Broker 能给的只有 at-least-once 和 at-most-once。exactly-once 不是队列的承诺，而是「at-least-once 投递 + 消费端幂等」拼出来的效果，而且这个 exactly-once 只覆盖被幂等机制管住的那些业务效果。

投递语义	谁提供	结果
at-most-once	关掉 ack / autoAck	不重，可能丢
at-least-once	手动 ack + 失败重投	不丢，可能重
exactly-once	队列不提供	由 at-least-once + 消费端幂等拼出

这里要分清三个层次，它们经常被混成一句话。投递可以重复：Broker 重投、生产者重发都会让同一条消息到两次。执行可以重复：处理函数被调用两次。业务副作用能不能只生效一次，取决于消费端有没有幂等，而且幂等只覆盖它自己管得住的那些副作用。数据库去重表能让「改库」只发生一次，但它不会自动让发货、短信、外部扣款也只发生一次；那些副作用要各自有幂等键（发货单号、短信去重、扣款流水号），或者接受「至少一次 + 人工对账」。

注意幂等这一层必须落在业务侧。Broker 手里也有一些计数，比如 quorum queue 会把一条消息失败的投递次数记在 x-delivery-count 头里，配合 delivery-limit 策略，投递超过上限的消息会被死信掉，而它解决的是「一条毒消息别在队列里无限打转」，不是「你的业务代码只跑一次」。这两个问题在不同的层，别指望前一层替后一层兜住。（delivery-limit 的计数规则在 4.3 有调整，不是所有显式 nack 都计入失败次数，与第六节讲的 delayed retry 相关。）

落回订单场景：这一笔订单可能被处理两次。幂等的最小形态是让消息带上业务唯一键，消费端用它去重，这套 demo 里就是消息体上的 orderId。它由订单服务生成，重发时不变；消费端拿到它，先查这一步业务是否已经做过，再决定要不要执行。但要小心并发：去重记录和业务写入必须原子提交（比如唯一索引 + 同库事务），否则两个消费者同时「查无记录」、都往下执行，幂等就失效了。去重表、唯一索引、状态机校验各有各的适用场景，本 demo 没有落到那一层，orderId 只负责把「同一笔业务」这个身份带过去。

五、兜底：死信与延迟重试链路

三段兜底之外，还有一类问题没有解决：消费一直失败怎么办。失败一次就重投，会得到一个高速空转的循环；失败三次就扔掉，会丢掉一条本该被处理的消息。

RabbitMQ 在这一层的原语是死信。消息在四种情况下会被重新投递到死信交换机：消费者以 requeue=false 拒绝（basic.nack / basic.reject）、消息因 TTL 到期（per-message TTL，或队列级 message-ttl）、队列超过长度上限、以及 quorum queue 上超过 delivery-limit 的投递次数。

这里有两个容易踩到的地方。如果队列上配了死信交换机，但消息需要死信时那个交换机并不存在，消息会被静默丢弃，没有回执，没有异常。拓扑声明因此不能只声明队列，交换机、绑定、队列的生命周期要一起管。

另一个和队列类型有关：classic queue 的死信过程默认不带 publisher confirm，消息从原队列删除后直接投给死信目标，目标不可用时它就丢了。quorum queue 可以做得更强，但默认仍是 at-most-once，要显式配置 dead-letter-strategy=at-least-once、overflow=reject-publish 并配好死信交换机，才切到带 confirm 的 at-least-once 死信。同一套死信拓扑，队列类型和策略配置不同，兜底强度并不一样。本 demo 没有显式配置这套策略，死信转移仍是 at-most-once 语义。

要做「重试 N 次再进死信」，标准做法是让业务队列的死信出口指向一条重试链路：业务队列 → nack → 重试交换机 → TTL 重试队列 → 到期回业务交换机 → 业务队列。这套 demo 的拓扑里，业务队列的死信出口不是最终死信队列，而是重试交换机；重试队列上配了 2000ms 的队列级 TTL，到期后经自身的死信出口回到业务交换机；最终死信交换机只接重试用尽以后由应用显式投递的消息。

flowchart LR
 Q["业务队列
收到消息"] --> C["处理失败
nack(requeue=false)"]
 C -- "还没用尽重试" --> R["重试队列
TTL 2000ms"]
 R -- "到期回投，x-death 计数 +1" --> Q
 C -- "重试用尽" --> D["最终死信队列
等待人工或定时任务"]

重试计数不一定非要应用自己维护，本 demo 读 Broker 写在 x-death 头里的死信记录。 应用自己维护一个进程内计数器，进程重启后就归零；要可靠就得把次数持久化到数据库、任务记录或消息头里，那是另一套存储。本 demo 选择读 x-death，它跟着消息走，避免了另建一套重试计数存储。官方文档对它的定义是：每条记录里 count 表示「这条消息因为这个原因从这个队列被死信了多少次」，并且记录会按 {队列, 原因} 压缩，同一个 (队列, 原因) 组合只保留一条，count 累加。

还要说清一个边界：x-death 记的是「死信」次数，不是「投递」次数。消费者崩溃后消息被直接重投、没走死信的那一次，不会在 x-death 里留记录。所以「rejected 次数 + 1 = 累计投递次数」这个等式，只在「每次失败都走 nack 死信」的本实验路径下成立。

实测一条一直失败的消息（orderId 里带 fail），队列级 TTL 2000ms、最多重试 3 次。第一次失败时 x-death 还是空的；第二次时里面已经有两条记录，业务队列上一条 rejected 计数 1、重试队列上一条 expired 计数 1；第三次两边各加 1；到第 4 次投递仍失败，消息转入最终死信队列，此时累计投递 4 次，也就是首次加上 3 次重试。相邻两次处理的间隔实测 2004 / 2003 / 2003ms，与配置的 2000ms 对得上（重跑会有几毫秒浮动）。

计数时要挑对条目：同一次失败会留下两条记录，业务队列上一条 reason=rejected，重试队列上一条 reason=expired，两个都算就重复计数了。示例里的计数只挑与业务队列同名的 rejected 记录求和。

重试用尽之后怎么收尾，有一个容易写错的地方。这里的业务队列死信出口是重试交换机，所以不能再用 nack 结束，它会再一次进入重试循环。正确做法是显式投到最终死信交换机，再 ack 掉原消息，同时把尝试次数写进消息头备查。

六、单个 TTL 重试队列的限制：混合延迟会出现队头阻塞

重试链路跑通之后，一个自然的想法是让间隔递增：1 秒、10 秒、60 秒，给下游留出恢复时间。这个想法在 RabbitMQ 的 TTL 上会撞到一件不那么直观的事。

队列级的 x-message-ttl 是队列的属性，同一条队列里的消息共用一个延迟，所以它天然只能做固定间隔，要递增就得给每一级配一条队列。另一条路是 per-message TTL：投递时给每条消息带上自己的 expiration。直觉上「谁先到期谁先走」，实测是「队头说了算」。

同一条队列投 3 条消息、各带不同的 expiration，只换入队顺序（脚本 ttl-head-of-line-blocking.py）：先投 6000ms 再投两条 1000ms，三条全部在 +6.0s 才死信；把顺序换成两条 1000ms 在前、6000ms 在后，前两条 +1.0s 就走，第三条 +6.0s。后两条的 expiration 明明只有 1000ms，却等到 +6.0s 才死信，被队头那条 6000ms 的消息卡了约 5 秒。

在本实验这种「同一条 classic 队列、只靠 per-message TTL 触发死信」的场景下，过期检查只在队头进行。 队头那条没到期，排在它后面、已经过期的消息也不会被处理。

官方文档写得很清楚：classic queue 与 quorum queue 都是「过期消息到达队头时才被死信掉」，并且「设置 per-message TTL 后，已过期的消息可能排在未过期消息后面，直到后者被消费或过期；这些过期消息占用的资源不会被释放，也会被计入队列的消息数」。

所以递增退避的「手搓」做法有两条：每一级一条队列（1s 队列、10s 队列、60s 队列各配一条，用路由键区分级别），或者装延迟消息插件。本 demo 用固定 2000ms 间隔，正是因为它只需要一条重试队列。

不过这两条都不是唯一的答案了。RabbitMQ 4.3 起给 quorum queue 提供了原生 delayed retry：通过 x-delayed-retry-type / x-delayed-retry-min / x-delayed-retry-max 三个参数，消息被拒绝（reject/nack）后按投递次数自动线性退避，延迟 = min(min_delay × delivery_count, max_delay)。它把「递增退避」做成了队列的内建能力，不用再叠一堆 TTL 队列或插件。注意三点：它只对 quorum queue 生效；默认 x-delayed-retry-type=disabled，要显式开启；本 demo 用的是 classic queue + 单条 TTL 重试队列，走的是上面那条「手搓」路径，正好能看清队头阻塞这个底层限制。

七、一致性补偿：Broker 之外的那一段

上面讲的都是「消息发出去之后」的可靠性。还有一类问题在更早的地方：订单写进了数据库，消息没发出去，或者反过来。

在 RabbitMQ 上这件事要靠应用层补偿。AMQP 的 channel 事务在这里帮不上忙，它的硬伤首先是事务边界：channel 事务只能包住「发消息」这一个动作，包不住「数据库写 + 发消息」这对跨系统的操作，所以它根本解决不了原子提交；顺带它还有吞吐代价（文档给的是降到约 1/250）且和 confirm 模式互斥。RabbitMQ 也没有 RocketMQ 那种 broker 级的事务消息（半消息 + 回查）。可行的模式是本地消息表（也叫 outbox）：在写订单的同一个本地事务里，往一张 outbox 表插一条待投递记录；事务提交后由后台任务把 outbox 里的记录投递出去，投递成功再标记完成；消费端仍然靠幂等兜底。

这个模式的关键在「同一个本地事务」，数据库事务保证订单和待发消息一起落库，消息投递则从「必须成功」降级成了「迟早成功」。本 demo 没有实现本地消息表，这里只说明它在链路里的位置：它是把「改库 + 发消息」这对跨系统操作，压回一个本地事务里的做法。

三个角色可以分开看：订单表和 outbox 表写在同一个事务里，解决「改库成功但消息没发出去」；后台投递任务负责重试，解决「投递时下游不可用」；消费端幂等兜最后一道，解决「投递重试带来的重复」。三处缺一处，一致性就漏一处。

这个模式也有自己的代价：outbox 表需要清理策略，否则它会跟着业务表一起无限增长；投递任务要独立控制并发和失败告警，它本身变成一条需要被监控的链路；投递逻辑和业务表放在同一个库时，事务的粒度会变大。它适合「本地写库、且要求通知最终一定送到」的场景，不适合拿来兜一个本来就不要求一致的通知。

八、Boot 4 与 RabbitMQ 4.3 上的几处版本差异

这套代码跑在 Spring Boot 4.1.1 + Spring AMQP 4.1.1 + amqp-client 5.30.0 + JDK 21 上，和大多数 Boot 3 时代的 RabbitMQ 教程有几处对不上的地方：

现象	原因	处理
`Jackson2JsonMessageConverter` 找不到依赖	Boot 4 用 Jackson 3（`tools.jackson`），类路径上只有 `com.fasterxml.jackson` 的注解包，没有 databind	改用 `JacksonJsonMessageConverter`
消费侧抛 `The class ... is not in the trusted packages`	转换器默认只信任 `java.util` / `java.lang`	按消息类的包名授权，不要写成 `"*"`
`Confirm.isAck()` 报弃用	Spring AMQP 4 起确认结果改成了 record	用 `ack()` / `reason()`
死信监听器反序列化失败	参数写成 `org.springframework.amqp.core.Message` 会走 typeId 反推，撞上信任包检查	参数直接用具体的消息类型
改完队列参数后应用启动失败，报 `inequivalent arg`	队列的 `x-dead-letter-exchange` 等参数不允许原地修改	先 `rabbitmqctl delete_queue` 再重启，让应用重新声明（只适用于可清空的实验环境，删除队列会连消息一起删；生产环境应改用 policy 动态配置）
脚本里声明非持久化的非排他队列报 `transient_nonexcl_queues is deprecated`	RabbitMQ 4.3 起默认不再允许这类队列	一律声明为持久化队列

最后一条是 4.3 引入的：官方文档把「transient（非持久化）且非排他的 classic queue」标为弃用，4.3.0 起默认不允许声明。写实验脚本时如果沿用了老教程里的 durable=False，会直接撞上这个报错。

九、收口：三段各兜住什么，以及它划出的边界

回到开篇那三个可能消失的位置，每一处现在都能对上兜底的一方，也能看清它兜到哪为止：

发送时：生产端的 confirm 加 return。两道回执都要看——confirm 跟着路由结果走，不可路由时它照样返回 ack，只监听 confirm 等于在发送环节装一盏常亮的绿灯；回执也覆盖不到订阅配置，没有 return 只说明至少有一个队列接收了。
存储时：Broker 端的持久化与副本。两个持久化属性回答「重启后还在不在」，副本回答「机器坏了还在不在」，后者把可用性前提从「节点在线」换成「多数派在线」，故障期间连读队列视图都会超时。
消费时：消费端的 ack 时机与 prefetch。前者决定崩溃时消息是重投还是丢失，后者决定重投的规模，但都没有改变「可能重复」这个结果。

重复这件事在三段里没有归宿：Broker 侧的 x-delivery-count 与 delivery-limit 管的是毒消息别在队列里无限打转，不是业务代码只跑一次；消掉重复的位置在消费端的业务幂等里，而幂等只覆盖它自己管得住的那几个副作用。三段拼出来的承诺是「不丢」加 at-least-once，不是「既不丢也不重」。

代价和上面三处一一对应：生产端要处理两道回执，并决定同步等还是异步收，同步等会把发送方拖进回执时延里（文档给的量级是持续负载下数百毫秒）；Broker 端要接受「多数派不在就拒绝写入」这个前提；消费端先处理再 ack 把重复引了进来，扩容之后同一笔业务落到两个消费者手里会更常见；重试链路上固定间隔只占一条 TTL 队列，改成递增退避，要么每级一条队列，要么接受过期检查只在队头这一条限制。

还有一段不在这三段的视野里：订单写进数据库、消息没发出去（或者反过来）发生在第七节的位置。三段兜底保证消息不消失，保证不了业务状态和消息一起生效；把这件事压回一个本地事务里的做法是本地消息表，它的代价是 outbox 的清理策略、投递链路自己的监控，以及变大的事务粒度。

参考资料

Consumer Acknowledgements and Publisher Confirms：publisher confirm 与 consumer ack 的定义与触发时机，mandatory 与 basic.return 的先后顺序。
Reliability Guide：at-least-once / at-most-once 的边界，以及消费端去重与幂等的必要性。
Queues：队列持久性与消息持久化的关系，transient 非排他 classic queue 的弃用说明。
Quorum Queues：Raft 副本、多数派可用性、publisher confirm 的发出时机、x-delivery-count 与 delivery-limit、at-least-once 死信（dead-letter-strategy/overflow）、4.3 原生 delayed retry。
Dead Letter Exchanges：死信的四种触发条件，x-death 头部结构与按 {队列, 原因} 压缩的规则。
Time-To-Live and Expiration：per-queue 与 per-message TTL 的区别，过期检查发生在队头的行为。
Consumer Prefetch：basic.qos 与未确认消息上限。
Metadata store：Khepri 自 4.2.0 起成为默认元数据存储，与 Mnesia 的关系。

演示代码：完整实现在 GYD 仓库 c02-mq-reliable-delivery，该目录的 README 列了环境、运行方式、端点与本文各节的对照，以及本文引用的完整输出记录；RabbitMQ 与 3 节点集群的编排在仓库级 infra/，两个实测脚本在 infra/rabbitmq/scripts/ 与 infra/rabbitmq-cluster/scripts/。

第一话｜RabbitMQ 的架构与特性：一条消息的一生

Sun, 08 Feb 2026 00:00:00 +0000

一笔订单的消息发了出去，下游没有收到，发送端也没有报错。

这不是配置写错了，而是 RabbitMQ 的默认路径本来就不保证「发出去了」等于「进了队列」。同一类落差还有另外两种常见的落法，三种都不用改业务代码，改一个声明参数或者换一个路由键就能撞上：

把消息发到一个没有任何绑定关系的路由键上，发送端拿到的是成功，消息也没有进任何队列；
给一个已经存在的队列的声明补上一个 TTL 参数，应用下次启动报 406；
想把一个已经存在的 classic 队列改成 quorum，重新声明一次就直接失败。

三条都不是 bug。它们各自对应一条结构性的机制，而这三条机制是同一套骨架的不同侧面：

现象	真实机制	对应章节
无绑定的路由键：不报错，也不投递	落点由交换机类型与绑定共同决定，落点数可以是 0；默认路径下发送端拿不到异常	二
改声明参数 → `406`	声明是幂等比对而不是覆盖，任何参数不一致都被拒	七
换队列类型 → 失败	与上一条是同一个机制：`x-queue-type` 本身就是被比对的参数之一	三（陈述事实）、七（机制）

全文按一条消息走过的顺序展开：它先在多大的范围里活动（一），然后被投到哪个落点（二），落在哪种队列上（三），接着谈它什么时候算安全（四）、怎么被消费掉（五），再看挂在队列上的三个常用特性（六），最后回到「声明」这一步（七）。第八节把这七节收成两条主轴。

读完之后应当能做到两件事：解释上面这三个现象为什么发生；以及在动手之前判断出「我选的这个队列类型，支不支持我要用的那个队列级特性」。

边注：文中标为「边注」的段落是限定与例外。它们不影响主线，第一遍可以跳过；但其中几条会改变边界，真用到那一节时值得回头看。

环境与运行方式

本文全部结论对应 RabbitMQ 4.3.5 与客户端 amqp-client 5.30.0，JDK 21。客户端刻意用裸 AMQP 库而不是 Spring AMQP：RabbitTemplate 和 MessageListenerContainer 恰好把 connection 与 channel 这两层封装掉了，而这两层正是下面要看的对象。完整实现与复现命令在仓库 c01-rabbitmq-architecture，文中每个结论后面括注的示例名就是复现入口。

一、连上 Broker：vhost、connection、channel 是三个不同粒度的作用域

一条连接建立起来，再在它上面开出若干条逻辑信道。vhost、connection、channel 这三层东西名字都很熟，但它们的用途经常被混着说。

连接阶段一次性谈定了一批东西，粒度层层收窄：最外层是这次进哪个 vhost、用哪个身份；中间是这条 TCP 连接的参数：服务端自报的版本、单条连接允许的最大信道数（2047）、单个帧的最大字节数（131072）、心跳间隔（60 秒）；最里面才是若干条逻辑信道（topology）。

flowchart TB
 B["Broker：vhost=/ 这个环境"]
 C["connection：一条 TCP，协商与认证在这一层完成"]
 CH1["channel #1"]
 CH2["channel #2"]
 CH3["channel #3"]
 B --- C
 C --- CH1
 C --- CH2
 C --- CH3

vhost 是资源命名空间。同名交换机与同名队列在不同 vhost 里是两个互不相干的实体，客户端在连接协商时指定自己进哪个 vhost。同一条 connection 上开了三条信道时也一样：队列在 #1 上声明、在 #2 上被动声明、在 #3 上删除，三个动作都成立。队列挂在 vhost 上，跟哪条信道碰它没有关系。

connection 是协商与身份的单位。官方文档讲连接生命周期时的顺序是：先协商协议版本与参数，再做认证，认证通过之后每一个操作还要各自过一次授权检查。这句话的工程含义是：连接建立成功只代表身份被接受了，不代表后面每一个动作都被许可，授权是逐操作判定的，所以一个能建连的账号仍可能在某个队列上被拒。

边注：不要把 connection 理解成「一个进程对应一条连接」，官方没有这层意思。它是一条 TCP 长连接加上一套会话状态，不绑定进程模型。

channel 是一条 TCP 上的逻辑连接。官方对它的定义是「共享一条 TCP 连接的轻量连接」。每个协议操作都必须落在某条 channel 上，协议方法按 channel ID 分流，所以同一个 connection 上的多条 channel 互不阻塞对方。更要紧的是错误的边界停在 channel 上：在一条信道上被动声明一个不存在的队列，broker 返回 404，被关掉的只有这条信道，connection 还活着，同一条连接上新开一条即可继续（topology）。

那为什么要有 channel 这一层？因为握手与认证的成本落在 connection 上，而复用同一条 TCP 承载多个逻辑会话的成本低得多。「一个进程开多个 connection」和「一个 connection 开多条 channel」不是等价的两种写法，后者省掉的正是重复的协商与认证。

二、发布一条消息：落点由交换机类型与绑定共同决定，落点可以是 0

发布这一步的第一站不是队列，是交换机——消息交给交换机，由它按绑定决定落到哪些队列，不存在「直接发进队列」这回事。客户端库里那个发布方法，第一个参数就是交换机名；平时习惯写的「只填队列名」的写法，是把它省略成了空串，而空串是一个内建交换机的名字。

先看正常的路径。交换机拿到消息后，按自己上面挂的绑定（binding）分发；一条绑定由「匹配规则 + 目标队列」两部分组成。同一句发布、同一个路由键，换个交换机类型，落点数量就完全不同：

交换机类型	匹配规则	`order.created` 的落点	`no.match.at.all` 的落点
`direct`	路由键全等	1 个队列	0
`fanout`	忽略路由键	2 个队列（全部绑定）	2 个队列
`topic`	按 `.` 分段，`*` 匹配恰好一段、`#` 匹配零或多段	2 个队列	0
`headers`	按消息头匹配（匹配语义未经验证）	未验证	未验证

这张表逐行核对过（route）。

而发送端在这一路上始终没有抛异常。no.match.at.all 这个路由键在 direct 和 topic 上都落 0 个队列，消息直接被丢弃，发送端拿到的却是成功，这就是开篇第一个现象。默认路径下「发出去了」与「进了队列」是两件事，中间隔着一次可能为空的匹配：

flowchart LR
 P["发布一条消息"] --> X["交换机"]
 X --> B{"有匹配的绑定吗"}
 B -- "有" --> Q["投到绑定的队列（0 个到多个）"]
 B -- "没有" --> N["0 个队列：默认路径下发送端不报错"]

要让发送端知道自己没投出去，得用 publisher confirm 加 mandatory 那一套参数。这里只需要记住落点可以是 0，而默认路径不会告诉你。

四个内建交换机有预声明的名字：amq.direct、amq.fanout、amq.topic、amq.match。除此之外还有一个名字是空串的 default exchange，它有两条特殊性质：每个队列在声明时会自动以自己的队列名为路由键与它绑好；它本身不能被操作。

第二条比预期严格。官方只说不要拿它做显式绑定，实际是两种手势都被拒：被动声明它与往它上面加绑定都返回 403。管理 API 里读到的绑定记录还证实了那条特殊绑定确实存在，source="" 而路由键就是队列名（default-exchange）。所以「直接发到队列名」这种写法一直在走交换机，只是交换机名和路由键都被省略成了默认值。

三、消息停在哪：三种队列类型的差别是消费语义，不是性能档位

消息落到队列之后，队列本身还有一个属性要选：类型。类型由声明参数 x-queue-type 指定，取值 classic（不写就是这个）、quorum、stream。

要和队列的另外三个属性区分开：durable（是否持久化）、exclusive（是否独占）、auto-delete（无人使用后是否自动删除）。这三个改的是同一套语义下的行为，而类型换的是消费语义本身。类型在声明期就锁定，改它会失败（机制见第七节）。

类型	存储与复制	消费语义	关键约束
`classic`	单节点，4.x 已无复制	消费即删除	默认类型；支持独占、支持全局 QoS
`quorum`	Raft 多数派复制	消费即删除	恒为 durable、不支持独占（改用单活跃消费者）、不支持全局 QoS
`stream`	复制 + append-only	非破坏性读（按 offset 读，读不走消息）	不支持死信与优先级；TTL 与队列长度限制改为 retention（官方矩阵写作 `no (but see Retention)`，用 `x-max-age` / `x-max-length-bytes` 表达）；成员变更手动

分界线在最后一列之外，也就是「消费会不会破坏数据」：

flowchart TB
 Q["x-queue-type"]
 CL["classic：单节点，消费即删除"]
 QU["quorum：Raft 多数派复制，消费即删除"]
 ST["stream：复制 + append-only，非破坏性读"]
 Q --> CL
 Q --> QU
 Q --> ST

classic 与 quorum 的差别在复制：一个单节点、一个多数派，但在消费语义上两者一致，都是读完就删。声明 quorum 时不要沿用 classic 里 durable=false 的写法，它恒为 durable，durable=false 直接不合法。stream 换掉的是这一层语义：它是一份 append-only 的日志，消费者按 offset 读，读这个动作不删数据。官方列出的许多特性支持与否，都从这一点推出来。

这个差别在读数上很直接：同一条 stream 上让两个消费者各自从头读，两边都拿到完整的 5 条；同样的动作在 classic 上，第二个消费者拿到 0 条（queue-types）。这也说明了为什么 stream 在第六节那三个特性上没有位置：TTL、长度限制、死信都以「消息会被删掉」为前提，而 stream 的读不删数据，前提本身不成立。它用按时间或字节保留的 retention 替代前两个。

边注：官方把 stream 称作「not really queues in the traditional sense」，并把原因说得很直接：「Many features will never be supported by streams due to their non-destructive read semantics.」

四、消息什么时候算安全：持久化与复制是两个独立维度

队列选定之后，接下来是「消息写到什么程度算安全」。这里有两个经常被合并成一个的维度。

维度一是持久化，它由两个开关共同决定：队列的 durable 管队列本身的元数据，消息自己的发布属性 deliveryMode 管消息内容，deliveryMode=2 即通常说的持久化消息。两个开关各管一半。

维度二是复制，它决定「一台机器挂了，另一个节点上有没有这份数据」。这个维度只跟队列类型有关：quorum 与 stream 有副本，classic 在 4.x 没有：官方原话是 classic 历史上支持复制，但这个特性「was removed for RabbitMQ 4.x」。

两个维度不能互相替代，最容易搞混的是持久化这一侧。官方在这一句上写得很直白：durable 队列会在节点启动时恢复，包括以 persistent 发布的消息；而以 transient 发布的消息在恢复时会被丢弃，即使它们存在 durable 队列里。后半句是这一段的关键：队列的 durable 不会替消息做决定。

要验证这一点，得让 broker 真的重启一次：往同一个 durable 队列里放 2 条 deliveryMode=2 与 1 条 deliveryMode=1，重启，再重声明队列并抽干。重启前队列里是 3 条，重启后剩下 2 条，队列本身仍在，而少的那条正是以 transient 发布的那条。发布时三条都在同一个队列里、同一次连接、同一批调用，唯一的差别就是发布属性（persistence-write → persistence-read，中间重启一次 broker）。

复制这个维度在正文里只到这一步。这里要拿到的是两个维度正交这个结论。

五、消费一条消息：ack 才是「可删除」的条件，prefetch 决定未确认消息的上限

默认的消费方式是推送：客户端订阅之后，服务端用 basic.deliver 把消息推过来，一个订阅由它自己的标签（consumer tag）标识。收到之后怎么算「处理完了」，取决于 ack 模式。

手动确认有三种应答：成功；失败并要求重新排队；失败且拒绝重排（这一种不能批量）。协议里它们分别叫 basic.ack / basic.nack（多带一个是否重排的标志）/ basic.reject。其中「成功」那一档的语义值得单独说清楚：它是「这条消息可以被删掉了」，不是「我读到了」。在这句话兑现之前，消息同时存在于两个地方：

sequenceDiagram
 participant C as 消费者
 participant S as Broker
 participant U as 未确认集合
 S->>C: basic.deliver 投递一条消息
 S->>U: 同时记入未确认集合
 C->>S: basic.ack：这条可以删了
 S->>U: 从集合里移出
 C--xS: 信道或连接断开
 U->>S: 未确认的那几条退回 ready，可被重新投递

这张图给出了「消费」的准确边界：它不是一次瞬时动作，而是一段有起止的状态。从交付到 ack 之间，消息既在服务端的未确认集合里，也在客户端手里。所以「队列空了」不等于「处理完了」，而「客户端收到了」也不等于「不会被重投」。

这段状态在队列深度上读得出来。5 条消息、prefetch 设成 2：刚发布完 ready 是 5；2 条被投递到客户端手里之后降到 3，此时再等也不会有第 3 条过来；直到其中 1 条被 ack、名额腾出来，第 3 条这才被推进来，深度走到 2；最后把信道关掉，尚未确认的那 2 条退回 ready，深度回到 4（consume-ack）。

从 5 到 3 减掉的 2 条，就是被投递但还没 ack 的那两条。它们没有消失，只是从 ready 挪到了未确认集合。这也说明了 prefetch 管的是什么：它是同一条信道上未确认消息的条数上限，不是投递速率，它限制并发在途的量，而不管每秒能发多少条。最后那一步回到 4，是因为此刻已投递 3 条、已 ack 1 条，剩下 2 条未确认，把信道关掉，这 2 条退回 ready。5 条里 1 条被 ack 后永久删除，剩下 4 条一条没丢。

另一种收手势的结果和直觉不同。把消费者取消掉，但连接与信道都留着，ready 仍是 2；只有把信道也关掉，它们才退回 4。所以未确认消息退回的触发点是信道或连接关闭，取消消费者本身不构成退回（consume-ack）。排查「消费者停了但消息没回来」这类现象时，这一条能省下不少时间。

另一种取法是主动拉取（pull 模型，协议里的 basicGet），官方口径是低效、应当避免，这里只用它做一个对照：连续三次 basicGet，第三次返回 null，因为队列已经空了。

channel 与线程

最后回到信道本身。交付和 ack 都发生在某条 channel 上，而 channel 不是给多线程共享用的。这件事在客户端库那里的措辞是禁止级的：官方客户端 5.30.0 的 Channel 类说明用的词是 must not：「Channel 实例不得在线程之间共享」，并且点名了后果：其中一部分操作会导致帧在同一连接上交错（incorrect frame interleaving on the wire），而且在多线程之间共享信道还会干扰 publisher confirms。

后半句有一个很直观的读数：让 8 个线程共享同一条信道，每个线程各取一次发布序号、再发布，一共 1600 条，读到的 1600 个序号里互不相同的只有 1572 个（重复 28 个），确认回调也只到了 193 次。这两个数字就是「干扰 publisher confirms」的具体形状：序号账本是 publisher confirm 用来对账的凭据，本该一次发布对应一个唯一序号（topology）。

正确的姿势是每个线程（或每个进程）持有自己的 channel，共享的是 connection，它本身是设计给多线程共用的。Spring AMQP 的并发消费者配置正是按这个模型，把 channel 分摊到各个消费线程上：

flowchart TB
 CO["connection（多线程可共用）"]
 CH1["channel #1"] --> T1["消费线程 1"]
 CH2["channel #2"] --> T2["消费线程 2"]
 CO --> CH1
 CO --> CH2

六、挂在队列上的三个常用特性：TTL、死信、长度限制，可用性由队列类型决定

TTL、死信、长度限制是队列上最常用的三个配置。它们放在同一节，是因为它们有同一个挂载点：三者都是队列级特性，都配置在队列上（声明参数或 policy），而不是配置在客户端代码里。这个共同点直接决定了一件事：它们能不能用，由队列类型决定。

TTL

项	结论
队列级 `x-message-ttl`	毫秒单位的非负整数，可写在声明参数或 policy 里
单条消息 `expiration`	发布时设置，必须是数字的字符串形式
两者并存	取较小的那个
到期语义	官方用词是 guarantees：到期的消息不会通过 `basic.deliver` 投给消费者，`basic.get` 也取不到
队头规则	只有排到队头时才会真正被丢弃；单条消息 TTL 下，先过期的消息会堵在未过期消息后面，资源不释放、仍计入队列统计
requeue 之后	保留原来的到期时间
`TTL = 0`	到达即过期，除非当时正好能投给消费者；它是 `immediate` 参数的替代品，且不产生 `basic.return`
队列过期 `x-expires`	必须是正整数，只在队列未被使用时计时

队头规则是这里最容易误判的一条：只有排到队头时才会真正被丢弃。

flowchart TB
 A["队头消息"] --> C{"超过 TTL 了吗"}
 C -- "是" --> D["丢弃：basic.deliver 不会投，basic.get 也取不到"]
 C -- "否" --> E["投递给消费者"]
 F["排在后面的消息：还没成为队头之前不会被检查"] --> A

这一条在读数上很好分辨。先发一条 60 秒的 A、再发一条 2 秒的 B，3 秒后 B 早该过期，但此时队列深度仍是 2；直到消费时消费者只拿到 A 一条，深度才直接归零：A 被消费掉，B 在排到队头的那一刻被丢弃（ttl）。所以设了 TTL 之后队列长度不会立刻下降，要等消息挪到队头才会掉。

另外两条规则也在同一组读数里：队列级 8 秒与单条 1.5 秒并存时，3 秒时深度为 1、9 秒时归零，生效的是较小的那个；一条 12 秒的消息被另一条连接取走后按住 6 秒再退回，仍在 t=13.8s 到期消失，说明 requeue 不会重新计时，它按首次发布的时刻算。最后这条是专门为了分开两种假设设计的：如果 requeue 会重新计时，消息应该活到 t≈18s（ttl）。

死信

满足下面四个条件之一时，消息会被投到 x-dead-letter-exchange 指定的交换机上：

触发点	说明
`basic.reject` 或 `basic.nack` 且 `requeue=false`	消费者主动拒绝并声明不再投回
消息 TTL 到期	队列级与单条两种配置都算
超过长度限制被丢弃	见下一小节
`quorum` 上返回次数超过 `delivery-limit`	4.0 起默认 20

flowchart LR
 A["四种触发：reject/nack 且 requeue=false · TTL 到期 · 超长度被丢弃 · quorum 超过 delivery-limit"]
 B["x-dead-letter-exchange 指定的交换机"]
 C["死信队列"]
 D["例外：整个队列被 x-expires 删掉时，消息不进死信"]
 A --> B --> C
 C -.-> D

几个配套细节：路由键没设时用消息的原路由键（含 CC 头，不含 BCC）；被死信的消息会带上 x-death 数组，记录 queue / reason / count / 时间戳，reason 取值是 rejected、expired、maxlen、delivery_limit；消息被死信时原本的 expiration 会被移除，防止它在新队列里再次到期。

边注：死信转发默认不开内部 publisher confirm，也就是 at-most-once：目标队列不可用时消息会丢。要用它的场景需要自己把这一环补上。

四个触发点各自的表现（dlx）：主动拒绝（nack 且 requeue=false）、单条 TTL 到期、队列级 x-message-ttl 到期各进死信 1 条，而整队被 x-expires 删掉时进死信 0 条，符合文档的例外说明。

其中队列级 TTL 到期这一条值得留意，因为官方两个页面的措辞不一致：dlx 那一页只写了「因单条消息 TTL 到期」，而 ttl 那一页同时覆盖队列级配置，这里的结论是两者都进死信。两条路径在数据上可以区分：队列级这条的 x-death 里没有 original-expiration，单条 TTL 那条有。如果代码要靠 x-death 判断死因，这个差别会用到。

长度限制

项	结论
参数	`x-max-length`（条数）或 `x-max-length-bytes`（字节）
`x-overflow` 三档	`drop-head`（默认）、`reject-publish`、`reject-publish-dlx`
`drop-head`	从队头（最早的）开始丢，发送端感知不到
`reject-publish`	丢最新的，发送端通过 `basic.nack` 感知
`reject-publish-dlx`	被拒的那几条改道进死信队列
`quorum` 上的 `reject-publish-dlx`	官方说 quorum「do not support」这一档；实际行为：声明不会报错，但会静默退回 `drop-head`

四段对照里有两处值得留意（max-length）。一是 reject-publish 这一档发送端确实能感知到：上限 3 条时依次发 5 条，确认回调里 ack 3 次、nack 2 次；而默认的 drop-head 从队头丢，留下的是最后 3 条，发送端拿到的全是成功。

二是 quorum 队列上那次 reject-publish-dlx：声明被接受、没有报错，主队列 3 条、死信 2 条。只看深度，这和真正生效那一档的形状完全一致。要分开这两个假设只能看死信里是哪两条：真正生效那次死信里是最新的两条，这一次是最早的两条，说明它在 quorum 上并没有按 reject-publish-dlx 走，而是静默退回成了队头丢弃。声明成功不等于行为生效。

边注：reject-publish 这一档在 quorum 上不严格强制上限，会超出上限至少一条消息：它的机制是达到上限之后逐个通知发布方信道，此期间还在途的消息仍会被接受。要用精确上限的场景要注意这一点。

三个特性齐了，回到它们共同的那条边界：这三项在 classic 与 quorum 上都能用（quorum 上只有溢出那一档有差别），在 stream 上则被 retention 取代。所以它们可用与否，取决于消费会不会删数据；客户端代码怎么写、队列是 classic 还是 quorum，都不构成决定因素。

七、声明为什么会被拒绝：幂等比对，与 4.3.0 的 transient 队列

回到开篇的另外两个现象：改声明参数报 406，换队列类型直接失败。两条都不在发布、消费路径上，而在声明这一步。

先立错误分级

AMQP 的协议异常分两级，判据不是错误文本，而是 broker 关掉了哪一个实体：

级别	错误码	broker 关掉的是谁	之后还能不能继续用这条 connection
soft（信道级）	`404` / `406` / `403` / `405`	这条 channel	能，新开一条继续
hard（连接级）	`501` / `540` / `541`	整条 connection	不能，得重建连接

406 属于前者，也就是关一条信道、连接还活着。这与第一节那次「被动声明一个不存在的队列」拿到的 404 是同一类表现。

hard 这一类有一条反直觉的性质：它们是异步上报的。调用点不会抛同步异常，要注册 addShutdownListener 才拿得到。给发布方法带上 immediate=true（这个参数在 4.x 上已被移除）返回 540，手工塞一个非法帧类型的帧返回 501，两次调用点都是「正常返回」，连接却已经不在了（topology）。所以排查「整条连接突然断掉、日志里只有 5xx 错误码」这类故障时，不能用「有没有抛异常」作为判据，得看 shutdown listener 或连接状态。

声明是幂等比对，不是覆盖

声明一个已经存在的队列或交换机时，服务端做的是把这次声明的参数和已存在的实体逐项比对，而不是用新的覆盖旧的。任何一项对不上就报 406，报错文本落在 inequivalent arg 这个词上，并且关掉这条 channel。两个用例的表现（precondition）：给一个已存在的队列补上 x-message-ttl=1000 再声明一次，报 406 并指出收到的值与当前值不一致；把已存在的 classic 队列重新声明成 quorum，同样报 406，指出 received 'quorum' but current is 'classic'。两次都是 connection.isOpen=true 而 channel.isOpen=false。

开篇现象 2 和现象 3 在这里合流：它们不是两件事。换队列类型失败，只是因为 x-queue-type 恰好也是被比对的一项。保留的语义是「这次声明不生效」，而不是「把旧的改成新的再失败」：被拒之后，原队列的类型没有变。

flowchart TB
 A["声明一个已存在的队列"] --> B{"参数与现有声明一致吗"}
 B -- "一致" --> C["放行（声明是幂等的）"]
 B -- "不一致" --> D["406 PRECONDITION_FAILED"]
 D --> E["关掉这条 channel；connection 仍然可用"]

这条机制解释了一个很常见的现象：本地把队列参数改了一行，重启应用就报 406，而在一个新环境上跑得好好的，因为新环境里队列还不存在，第一次声明总能成功。所以声明参数应当当成接口契约来管：线上已经声明过的队列，参数就不能随手改。要改就得先删队列（会连消息一起删），或者改用 policy：它是动态下发、不参与这次比对的。

4.3.0 起，transient 非排他队列默认不可声明

剩下两个用例是版本边界和一个未预期的结果：

用例	结果	级别
队列名用保留前缀 `amq.`	`403 ACCESS_REFUSED`（contains reserved prefix）	信道级
`durable=false` + `exclusive=false`	`541 INTERNAL_ERROR`（Feature `transient_nonexcl_queues` is deprecated）	连接级
用另一条 connection 访问独占队列	`405 RESOURCE_LOCKED`	信道级

第二行是最值得记的一条。官方从 4.3.0 起把「非持久化且非排他的 classic 队列」列为弃用并默认拒绝（配置项 deprecated_features.permit.transient_nonexcl_queues），老教程里顺手写的 durable=False 在这个版本上直接撞上它。而它返回的是 541，属于连接级，不是 406。所以一条队列声明失败，代价是整条连接被带走，同一次运行里后面几步必须重建连接才能继续。把它和上面那张分级表对照着看：同样是「声明被拒」，406 只关信道，541 关整条连接，错误码决定了故障半径。

第三行补的是另一个方向：在连接 A 上声明的独占队列，用连接 B 去被动声明会得到 405 RESOURCE_LOCKED（信道级）。独占的语义是按连接判定的。

八、收口：两层骨架与它划出的边界

把前面七节的对象串起来，一条消息走过的是一条单一方向的链：

flowchart TB
 subgraph R["路由层：决定去哪"]
 X["交换机类型 + 绑定"]
 end
 subgraph C["承载层：决定以什么语义保存与消费"]
 Q["队列类型：classic / quorum / stream"]
 F["队列级特性：TTL / 死信 / 长度限制"]
 end
 R --> C

路由层是交换机类型加绑定，它回答「去哪」，并且与队列类型无关：同一个路由键在 direct 下落 1 个、在 fanout 下落全部、在 topic 下按通配落若干，把队列从 classic 换成 quorum 不会改变这个结果。承载层是队列，它回答「以什么语义被保存与消费」，队列类型决定消费语义（消费即删除还是非破坏性读），而挂在队列上的那些特性也跟着这个语义走。

回到开篇那三个现象，它们都能从上面两条机制推出来：

无绑定的路由键不报错，是路由层的直接结果：落点由绑定决定，而落点可以是 0；默认路径下发送端拿不到异常。
改声明参数报 406，是承载层的直接结果：队列的参数是它自己的身份，声明只做比对不做覆盖。
换队列类型失败，与上一条是同一件事，x-queue-type 也是被比对的一项。它看起来像第三个坑，其实是第二个坑的一个实例。

这套骨架有两处代价。三层作用域（vhost / connection / channel）换来了复用一条 TCP 的能力，代价是错误域分了级：同一个失败在不同错误码下可能只废掉一条信道，也可能废掉整条连接，所以错误码在 RabbitMQ 里不是一个诊断细节，而是故障半径本身。两层结构（路由 + 承载）让「去哪」和「怎么存」解耦，代价是队列类型一旦选定就锁住了它能用哪些特性，而且改不了：选 stream 那一刻，TTL 与长度限制就换成了 retention，死信则没有位置。

参考资料

AMQP 0-9-1 Model Explained：vhost / connection / channel 三层定义，交换机与绑定的关系，ack 语义。
Connections：连接生命周期、协商参数、认证与逐操作授权、连接是长生命周期对象这一前提。
Channels：信道的定义（一条 TCP 上的轻量连接）、协议异常分级（soft 关信道 / hard 关连接）、未确认消息随信道关闭退回。
Exchanges：四种内建交换机与预声明名，default exchange 的三条特殊性质。
Queues：队列属性、durable 队列恢复时包含 persistent 消息而 transient 消息被丢弃、classic 复制在 4.x 移除、x-queue-type 声明期不可变。
Quorum Queues：Raft 复制、恒 durable、不支持全局 QoS、长度限制不含 reject-publish-dlx、reject-publish 会超出上限至少一条。
Streams：非破坏性读语义、与 classic 的完整特性矩阵（含 TTL 与长度限制的 no (but see Retention)）。
Time-To-Live and Expiration：队列级与单条 TTL、取较小值、队头规则、x-expires 的取值要求。
Dead Letter Exchanges：四个触发点、x-death 结构与 reason 取值、整队过期不进死信的例外、默认 at-most-once。
Queue Length Limits：x-overflow 三档行为与发送端的可感知差异。
Consumer Acknowledgements and Publisher Confirms：ack / nack / reject 的语义与批量限制、confirm 的序号账本。
Consumer Prefetch：basic.qos 与未确认消息上限。
Deprecated Features：transient_nonexcl_queues 自 4.3.0 起默认拒绝及其配置项。

演示代码：完整实现在 GYD 仓库 c01-rabbitmq-architecture，RabbitMQ 的编排在仓库级 infra/rabbitmq/。正文每个结论后面括注的名字就是复现入口，在仓库根用 ./gradlew :c01-rabbitmq-architecture:run --args="<名字>" 跑（JDK 21 需显式指定 JAVA_HOME）；运行方式、每个示例做了什么、以及各结论对应的完整输出记录，都在该模块的 README 里。第四节的持久化那一段要按顺序跑两条命令、中间重启一次 broker。