做消息中间件这块时间长了，你会发现大部分线上问题最后都指向同一个地方——消息到底被送到哪儿去了，又是从哪儿被取走的。Pulsar消息路由这个话题，表面上看就是"生产者发到哪个分区、消费者从哪个分区读"，但真正扒开来看，它横跨了元数据寻址、Broker归属、分区选择、订阅分发、跨集群复制五六个环节，任意一环的理解偏差都会在实际运维中变成难查的故障。我第一次接触Pulsar的时候，习惯性地拿它和分区式的消息队列做类比，结果在一次分区热点排查里彻底翻了车：明明生产端配了轮询，流量还是死死压在一个Broker上。后来才搞明白，Pulsar的路由是"两级"的——Topic先哈希到Bundle，Bundle再归属到Broker，分区轮询只发生在第二级，第一级根本不受生产者控制。这篇内容我打算把这条链路从头到尾走一遍，讲清楚哈希怎么算、Owner怎么抢、分区怎么选、订阅怎么分发，也把踩过的坑和验证用的命令一并放出来。适合已经在用Pulsar、但对其内部寻址和分发机制只有模糊印象的后端开发和运维同学，也适合正在做选型评估、想搞清楚它和传统分区模型差异的技术负责人。
1. 先把消息路由这件事拆开看
1.1 一条消息从产生到落盘要经过几次"找路"
我习惯用快递来类比。你寄一个包裹，第一步要确定收件的城市网点（Topic归属哪个Broker），第二步要确定这个网点里具体哪个货架（分区），第三步是收件人来了之后，网点按什么规则把包裹递给他（订阅分发）。这三步在Pulsar里分别对应寻址路由、分区路由、投递路由，它们由完全不同的组件负责，配置项也分散在三个地方，这是很多人搞混的根源。
生产端创建一个Producer时，客户端拿到的只是一个Topic全名，比如persistent://tenant/ns/order-events。这个名字本身不包含任何Broker信息，客户端必须先做一次Lookup，问元数据中心"这个Topic归谁管"。拿到Broker地址后建立TCP连接，之后的发送请求才真正落到某个Broker上。而具体写到哪个分区，是客户端侧的MessageRouter在发消息的那一刻决定的，Broker完全不参与。到了消费侧，情况反过来：消费者订阅的是一个逻辑Topic，Broker端的Dispatcher负责把消息推给订阅下的哪个消费者实例。
这三步的耦合度很低，低到你可以只改生产端路由模式而不影响消费端，也可以只调整Bundle划分而不动任何业务代码。但低耦合也意味着排障时要一层一层剥，不能指望一个指标看穿全部。我的经验是先定位问题发生在哪一级：是所有分区都慢，还是只有某几个分区慢；是所有消费者都收不到，还是只有某个实例收不到。这两个问题的答案基本能锁定层级。
1.2 三级路由模型：寻址路由、分区路由、投递路由
把三级模型摊开成表格，后面所有细节都可以往里填：
| 层级 | 决策方 | 决策依据 | 客户端可配置 | 典型故障表现 |
|---|---|---|---|---|
| 寻址路由 | Broker端OwnershipCache+ 元数据中心 | Topic名哈希 → Bundle → Owner Broker | 否（仅能通过Bundle切分间接影响） | Lookup超时、ServiceUnitNotReady、连接被重定向 |
| 分区路由 | 生产端MessageRouter | 路由模式 + Key哈希 + 分区数 | 是（routing mode、自定义Router） | 分区流量倾斜、同Key乱序 |
| 投递路由 | Broker端Dispatcher | 订阅类型 + 消费者数量 + permits | 部分（订阅类型、receiverQueueSize） | 消费堆积在单实例、Key乱序、重复消费 |
这张表我自己贴在工位上贴了很久。它的价值在于：当你看到"某个分区消费堆积"的时候，能立刻排除寻址层——因为寻址层出问题表现为整个Topic不可用，而不是单个分区慢。反过来，如果现象是"生产者报Topic not found但Topic明明存在"，那几乎可以确定是寻址层，跟分区和订阅一点关系都没有。
再补充一点容易被忽略的：这三级的"所有权"边界很清晰。寻址路由的所有权在Broker集群，客户端只能被动接受重定向；分区路由的所有权完全在客户端，Broker甚至不知道你用的是哪种路由模式；投递路由的所有权在Broker，客户端只能通过订阅类型和队列大小施加影响。理解了所有权边界，就不会出现"我改了生产端配置为什么消费端还是不均匀"这种困惑。
1.3 为什么不是"客户端直连存储"
有人会问，既然底层是分布式日志存储，为什么不干脆让客户端直接连存储层读写，跳过Broker这一层路由？这个问题我在做架构评审时被问过不止一次。答案藏在三个地方。
第一是一致性。存储层只认Ledger，不认Topic和Subscription这些逻辑概念。消息的消费位点（Cursor）、订阅的Ack状态、消息的TTL和积压统计，这些全是Broker维护的语义，存储层提供不了。如果客户端直连，每个客户端都得自己维护一套位点，多消费者协同就变成了分布式共识问题，复杂度直接爆炸。
第二是隔离。Broker是逻辑上的租户隔离单元，Bundle的归属机制保证了同一个Namespace下的Topic能被打散到不同Broker，从而实现CPU和网络的水平扩展。存储层是物理的Bookie节点，一台Bookie上可能同时承载几十个租户的数据，没有逻辑层的路由就没法做租户级的限流和隔离。
第三是缓存与合批。Broker在投递路径上做了大量优化——把多个小消息合成一个Entry读出来、按订阅维度缓存、用receiverQueue做批量推送。这些优化都依赖"中间有一层"这个前提。客户端直连的话，每个消费者都要独立读一遍磁盘，读放大非常严重。
所以Broker这一层的路由不是多余的抽象，它是把"物理存储"翻译成"逻辑消息流"的必要成本。理解了这一点，也就理解了为什么Pulsar的路由设计会把复杂度放在Broker而不是客户端——它选择了中心化的元数据管理，换来客户端逻辑的极度简化。
2. Topic寻址：Hash到Bundle，Bundle找到Owner
2.1 Topic全名如何映射成32位哈希
这一层是很多人真正模糊的地方。Pulsar的Namespace并不是一个不可分割的整体，它在元数据层面被切成了若干个Bundle，每个Bundle是一段哈希区间，格式长这样：0x00000000_0x3fffffff。默认情况下一个Namespace会被切成4个Bundle，也就是把32位哈希空间四等分。
具体的计算链路是这样的：客户端或Broker拿到Topic全名后，先取它的分区基名——注意这一步很关键，如果你操作的是order-events-partition-3，实际参与哈希的是order-events，分区后缀会被剥掉。这样做的目的是让同一个分区Topic的所有分区落在同一个Bundle里，进而由同一个Broker管理。我第一次看到这个设计时觉得有点反直觉：为什么不把不同分区打散到不同Broker上做负载均衡？后来想明白了——分区Topic的元数据操作（比如扩分区、查分区数、删Topic）需要原子性，如果分区散落在多个Broker，这些操作就得跨Broker协调，复杂度陡增。用一个Bundle兜住整个分区Topic，元数据操作就退化成单机操作。
哈希算法用的是Murmur3的32位版本，对Topic基名的字节做哈希，得到一个无符号32位整数，然后在这个整数上找落在哪个Bundle区间。整个过程没有任何随机因子，是纯确定性的。这意味着只要Topic名不变、Bundle划分不变，这个Topic永远归属同一个Bundle。确定性带来的好处是缓存友好，客户端和Broker都能长期缓存映射关系；坏处是如果一批Topic的名字前缀高度相似，哈希分布可能不够均匀，这时候就需要靠Bundle切分来打散。
提示：Bundle的哈希是打在Topic基名上的，不是打在Namespace上。所以同一个Namespace下Topic数量越多，哈希分布越接近均匀；只有两三个Topic的Namespace，很可能所有Topic挤在一个Bundle里，这是正常的，不是配置错误。
2.2 Ownership竞争与缓存
确定Bundle之后，下一步是找出这个Bundle归哪个Broker。这一步的实现在Broker侧的OwnershipCache里。每个Broker启动后会监听元数据中心里Bundle归属节点的变化，当需要接管某个Bundle时，它会尝试在元数据中心创建一个临时节点，谁创建成功谁就是Owner。这是一个典型的抢占式选主，用的是临时节点的会话特性——Broker挂了，会话超时，节点自动消失，其他Broker就能接管。
这里有几个实操中很关键的细节。第一，接管不是瞬时的，会话超时时间决定了故障转移的窗口，配置得太短会导致网络抖动时频繁误切，配置得太长会导致故障后长时间不可用。我见过的生产集群大多把这块调到30秒上下，配合客户端的重试逻辑，体感上是可以接受的。第二，Broker在真正对外服务之前，需要先把Bundle下的所有Topic从存储层加载出来，重建Cursor状态，这个"预热"过程在Topic数量多的时候会明显拖慢接管速度，也是故障恢复期间客户端大量报错的直接原因。
第三，OwnershipCache在本地是有一份缓存的，Broker收到请求后先查本地缓存判断自己是不是Owner。如果缓存里显示不是，它会返回一个重定向响应，让客户端去问别的Broker或者重新Lookup。这个缓存失效的瞬间会产生一小段"谁都不认"的窗口，表现为客户端收到ServiceUnitNotReadyException。这个异常名字起得很准——服务单元（Bundle）还没准备好，不是Topic不存在，重试就能恢复。
2.3 Lookup链路与客户端重定向
客户端首次连接Topic时会发起Lookup请求，报文里带Topic全名和请求类型。Broker收到后走一遍刚才说的流程：算哈希、查Bundle、查Owner。如果自己就是Owner，直接返回自己的服务地址；如果不是，返回Owner的地址并标记authoritative=false或者干脆返回重定向。
客户端拿到地址后会缓存起来，后续发送直接连这个Broker，不再重复Lookup。缓存的失效条件有几个：连接断开、收到重定向响应、收到Topic不存在或归属变更的错误。这里有个容易被忽略的点——客户端的连接是按Broker复用的，不是按Topic。同一个Broker上的多个Topic共享一条TCP连接，这对减少连接数很有帮助，但也意味着某个Topic的高流量会影响同连接上的其他Topic，排查时如果看到"不相干的Topic延迟升高"，可以往这个方向想。
Proxy模式下链路会多一跳。客户端连Proxy，Proxy自己去跟Broker做Lookup，然后把请求转发过去。这种模式下客户端完全感知不到Broker拓扑，扩缩容对客户端透明，代价是多一次网络跳转和一层连接管理。我在多租户场景里更倾向用Proxy，因为租户隔离和访问控制集中在一层做，比在每个Broker上配要清爽得多。
2.4 Bundle切分粒度怎么定
Bundle数量是寻址层唯一可以人为干预的杠杆，也是容量规划里最容易被低估的一项。默认4个Bundle意味着一个Namespace最多只能被4个Broker分担，如果你有20台Broker而Namespace只有4个Bundle，那另外16台就是闲着的。这个道理很简单，但实际集群里我见过太多"Broker很多但负载集中在几台"的案例，根因就是Bundle太少。
反过来，Bundle也不是越多越好。每个Bundle在元数据中心都有一个归属节点，Bundle数量上去了，元数据写入和监听的压力同步上升；Broker接管时也要按Bundle粒度加载，切得太碎会让故障转移的元数据操作次数暴涨。我的经验是按Broker数量的2到4倍来规划初始Bundle数，比如12台Broker就先切24到48个Bundle，运行一段时间观察负载分布再决定要不要继续拆。
切分用的是split-bundle命令，可以指定切哪个Bundle、切成几份。这里有个坑：拆分只影响后续的归属分配，已经归属的Topic不会自动迁移，需要配合负载均衡器或者手动unload才会重新分布。所以拆分之后如果发现负载没变化，别急着怀疑命令没生效，先看看是不是少了这一步。另外拆分是不可逆的，Bundle只能越切越细，不能合并，规划的时候宁可保守一点。
3. 生产端路由：分区选择逻辑与Key的一致性
3.1 三种路由模式的真实行为
生产端的路由模式直接决定消息落到哪个分区，这里的行为差异比文档上写的要微妙。RoundRobinPartition是默认值，顾名思义是轮询，但它的轮询粒度是"批"而不是"条"。生产者开启批量发送后，每批消息会发给同一个分区，下一批才切到下一个分区。这个设计是为了提升顺序写的效率，但如果你对"轮询均匀"有很强的预期，会发现在低流量下分区分布可能很不均——因为批还没攒满就发出去了，轮询的切换频率取决于batchingMaxPublishDelay。
SinglePartition更简单：随机挑一个分区，然后所有消息都发这个分区，直到生产者重建。注意是随机不是固定第一个，这是为了防止多个生产者同时启动时全部打到同一个分区。如果你显式指定了Key，这个模式会退化成按Key哈希。
第三种是自定义，实现一个MessageRouter接口，返回分区索引。这个接口的能力很有限——只能看到消息和分区列表，做不了跨消息的复杂状态管理，也不能异步。我在一个需要"按业务线固定分区"的场景里用过，把业务线ID映射到固定的分区索引，实现上是几十行代码，但收益很明显：后续排查某个业务线的问题时，直接看一个分区就够了。
| 路由模式 | 无Key时的行为 | 有Key时的行为 | 适用场景 |
|---|---|---|---|
| RoundRobinPartition | 按批轮询切换分区 | 按Key哈希，忽略轮询 | 追求整体吞吐和均匀分布 |
| SinglePartition | 随机锁定一个分区 | 按Key哈希 | 单生产者、需要减少分区连接开销 |
| CustomPartition | 由自定义Router决定 | 由自定义Router决定 | 业务线隔离、特殊亲和性需求 |
3.2 Key哈希与批处理叠加的坑
Key的路由算法是Murmur3哈希后对一个有符号余数做安全取模，落到0到分区数-1的区间。这个算法本身没问题，问题出在它和批处理的组合上。
批量发送时，生产者会先把消息按Key做一次初步分组，同一批里Key相同的消息会放在一起，目的是让它们落到同一个分区。但如果一批里混了多个不同的Key，而且这批消息的分区计算结果不同，生产者就必须把批拆开——这叫"按Key拆批"。拆批本身是正确行为，代价是降低了压缩率和写效率。我在一个Key基数特别大的场景里观测到过这个现象：明明开了批量，实际写出去的Entry大小只有几十字节，压根本不生效，原因是每批里全是不同的Key，拆得干干净净。
注意：高Key基数 + 开启批量 + 强顺序需求，这三个条件同时成立时，批量几乎失效。要么接受吞吐损失，要么在业务侧把Key的基数降下来，要么改用不含顺序要求的场景。没有第四个选项。
另一个坑是Key的编码。Key可以是字符串也可以是字节数组，字符串会按UTF-8转字节再做哈希。如果你的Key是数字但存成了字符串，"10"和"010"会被哈希成不同的值，虽然业务语义上它们可能相同。这类问题在跨语言生产端混用的时候特别容易出，因为不同语言的序列化行为不一致。我的建议是Key统一用二进制或定长的字符串格式，别依赖语言默认的转换。
3.3 自定义MessageRouter的适用边界
自定义Router看起来是个万能入口，但它有明确的能力边界，踩过一次就知道疼。它的接口是同步的，每次发消息都调用一次，所以里面绝对不能做远程调用或者复杂计算，否则会成为生产端的性能瓶颈。它也拿不到Broker的状态信息，做不了"根据分区负载动态选择"这种智能路由——想要这种能力，只能在客户端自己维护统计，或者干脆换方案。
真正适合自定义Router的场景，我总结成两类。一类是业务亲和性，比如按租户ID把消息固定到某个分区，方便后续做租户级的隔离和排障。另一类是可控的散列，比如你不信任默认的哈希分布，想用自己的算法保证长尾Key也能均匀落点。这两类的共同点是：决策依据完全在客户端本地，不需要外部状态。
不适合的场景也很明确：任何需要感知运行时负载、需要跨生产者协调、需要动态调整的路由决策，都不该放在这里。这类需求要么交给Broker侧的负载均衡，要么在业务层做前置分流。我见过有人在Router里读一个本地缓存的路由表，然后定期从配置中心刷新——能跑，但引入了配置中心和生产者之间的一致性窗口，出问题时排查链路会变得很长。
3.4 分区数怎么算
分区数的计算是容量规划里的经典问题，Pulsar这边有几个额外约束需要注意。基础公式还是那个：目标吞吐除以单分区吞吐。单分区吞吐取决于消息大小、副本数、存储介质的随机写能力。经验值上，小消息（几百字节）单分区写到几MB/s是正常的，大消息（几十KB）会明显下降。
但Pulsar有个特殊性：分区数一旦设定，只能增不能减，而且增加分区会导致Key到分区的映射发生变化——原来hash % 4，现在变成hash % 8，同一个Key可能跑到新分区去。这直接影响顺序性。所以分区扩容是一个需要停写或者接受短暂乱序的操作，不能当成日常运维动作。
我的做法是初始分区数按预估峰值的1.5倍来给，宁可一开始多给一点，也不要频繁扩。多给分区的成本主要是元数据条目和连接数，相比扩容带来的顺序性问题，这个成本是值得的。另外要记住分区数要和Bundle数量配合——如果分区Topic被一个Bundle兜住，那么所有分区只能由同一台Broker服务，分区再多也突破不了单机的网络上限。这种情况下要做的不是加分区，而是先把Bundle切细，让不同分区能分布到不同Broker。
4. 消费端路由：订阅类型就是分发策略
4.1 四种订阅背后的Dispatcher
消费端的路由由订阅类型决定，四种类型分别对应Broker端不同的Dispatcher实现，这个对应关系理解了，很多"为什么消费不均匀"的问题就有了答案。
Exclusive是独占，一个订阅只能有一个消费者，Dispatcher是单路分发，没有任何选择逻辑。Failover是主备，同订阅下多个消费者，但只有一个活跃，其余待命。它的选主规则是按消费者名排序取第一个，所以你会发现活跃消费者经常是同一个——名字字典序靠前的那个。这个规则简单但不够灵活，如果你的消费者是动态创建的，名字带随机后缀，那活跃消费者可能会频繁换，反而不好。稳妥的做法是给消费者指定有意义的前缀，让排序结果稳定可预期。
Shared是共享，消息在多个消费者之间轮转分发，对应RoundRobinDispatcher。这里有个常见误解：很多人以为Shared是严格轮询，实际上它是"按可用permits轮询"。每个消费者有一个receiverQueueSize的缓冲槽位，Broker只在消费者还有空位时才往它那里分发，没空位的直接跳过。这就导致消费能力强的实例会拿到更多消息——这在自适应场景下是好事，但如果你的消费者是异构的（比如有些实例部署在性能差的机器上），就会出现严重的分配不均。
Key_Shared最特殊，它保证同一个Key的消息只投给同一个消费者，对应的是粘性Key分发器。这个类型的细节最多，单独展开说。
4.2 Key_Shared的哈希区间分配
Key_Shared的工作方式是：Broker把哈希空间切成若干段，每个消费者负责一段，消息按Key的哈希落到对应的段，就投给那个消费者。哈希空间是0到65535（16位），默认策略是自动切分，消费者加入或离开时重新划分区间。
重新划分这一步是理解Key_Shared所有问题的钥匙。假设原来两个消费者，各管一半区间；第三个消费者加入，区间要重新三等分，那么原来属于消费者A的一部分Key现在归了C。这部分Key的消息如果还有在途未Ack的，或者消费者本地还有缓冲的，就会出现短暂的乱序甚至重复。这跟消息队列本身的可靠性无关，是路由变更的必然结果。
提示：Key_Shared订阅扩缩容时存在顺序性窗口。如果你的业务对顺序极其敏感，扩容要选在流量低谷，或者干脆一次性扩到位，减少变更次数。
另一种策略是显式指定每个消费者负责的区间，不走自动切分。这种模式的适用场景是消费者数量固定、每个实例的处理能力已知的场景——你可以按能力分配区间，让强实例多拿一点。代价是消费者数量变更时要手工调整，运维成本高。我一般只在消费者数量长期不变（比如固定分片部署）的场景里用这个。
还有一个容易踩的坑：Key_Shared的分区间是基于Key的哈希，而不是基于分区。也就是说，如果你的Topic是多分区的，同一个Key在每个分区里的哈希是一样的，但消息本身是分散在不同分区的。Key_Shared只保证"同一个分区内，同一个Key投给同一个消费者"，跨分区的顺序它不负责。要保证全局有序，就回到第一节的问题——分区本身就是为了并行而存在的，全局有序和水平扩展天然矛盾。
4.3 receiverQueue与流控对分发的影响
receiverQueueSize是消费端路由里最容易被误解的参数，默认1000，很多人以为它只是个缓冲，实际上它直接参与了分发决策。前面提到Shared分发是"按可用permits轮询"，permits的来源就是这个队列的剩余空间。队列越小，消费者能同时持有的消息越少，分发切换就越频繁；队列越大，单个消费者能囤积的消息越多，分配就越不均衡。
这个参数在跨分区场景下还有个总量上限，默认是50000，分摊到所有分区的子消费者上。比如你订阅了一个8分区的Topic，每个子消费者默认1000，总量8000，没超上限，各自独立。但如果分区数到64，每个1000就是64000，超了上限，分摊下来每个子消费者实际能拿到的队列会缩水到780左右。这个分配是动态的，分区分裂或者消费者变化时会重算。
我在一个消费延迟要求很高的场景里把这个值调到过100，明显的效果是消费延迟降低、分配更均匀，代价是吞吐下降——因为小队列导致Broker频繁等permits。反过来，做离线批处理时把队列调到上万，吞吐上去了，但单个实例的GC压力也跟着上来，几次Full GC就会触发消费者被踢出，触发重分配，形成恶性循环。这个值没有通用的最优解，只能根据业务侧延迟要求和实例内存反复调。
4.4 Ack、重投与DLQ的路由链路
Ack本身也是一次路由：消费者把Ack发给Broker，Broker确认自己是Owner后更新Cursor。如果Ack发到了非Owner的Broker，会收到重定向，客户端重连再发。Ack失败不会立刻导致消息重投，因为Broker维护的是位点而非逐条确认，个别Ack丢失会在位点推进时被覆盖。
真正的重投来自两种情况：Ack超时和Negative Ack。Ack超时是消费者拿到消息后在指定时间内没确认，Broker主动重发；Negative Ack是消费端显式告诉Broker"这条我处理失败，请重发"。两者最终都会走到重投逻辑，把消息放回待投递队列。
死信队列的路由是在重试次数耗尽后触发的。消息被重投若干次仍然失败，Broker会把它投递到%DLQ.订阅名这个特殊的Topic里。这个Topic本质上是个普通的Topic，也有自己的分区和归属，所以死信消息实际上经历了一次完整的路由：从原Topic的某个分区，投递到DLQ Topic的某个分区。如果你的DLQ没有预先创建分区，它默认是非分区的，所有死信挤在一个分区里，量大的时候会积压。
重试队列%RETRY.订阅名也是一样的道理，它承载的是"延迟重投"的消息，通过定时器在延迟到期后重新投回原Topic。这套机制绕了一圈又回到了原Topic的分区路由，所以如果你在压测时看到原Topic的流量出现周期性反弹，多半是重试队列在放量，不是生产端在重发。
5. 动手验证：一次完整的路由观测过程
5.1 准备环境与观测清单
纸上谈兵没有意义，路由这套东西必须自己跑一遍才能建立直觉。我一般用单机三节点的最小集群来验证，配置里把Bundle数调小、负载均衡器打开，方便观察归属变化。观测清单我固定在四项：Bundle归属、Topic所属Owner、分区流量分布、消费者接收分布。前两项看寻址层，后两项看分区和投递层。
准备一个测试Namespace，显式创建多分区Topic，这样避免自动创建带来的不确定性。同时把负载均衡的自动拆分关掉，不然观察过程中Bundle自己会变，容易让结论失真。
# 创建测试命名空间并设置6个Bundle bin/pulsar-admin namespaces create my-tenant/my-ns bin/pulsar-admin namespaces create-bundle my-tenant/my-ns 6 # 创建一个8分区的测试Topic bin/pulsar-admin topics create-partitioned-topic \ persistent://my-tenant/my-ns/route-test --partitions 8 # 关掉自动拆分，保证观察期内Bundle划分不变 bin/pulsar-admin namespaces set-auto-bundle-split \ my-tenant/my-ns --boundaries 0x00000000_0xffffffff5.2 查Bundle、查Owner、查Lookup
第一条命令看Bundle归属，输出会列出每个Bundle区间和对应的Owner Broker。这一步的看点是分布是否均衡——6个Bundle落在3台Broker上，理想情况是每台2个。如果出现4比1比1，说明负载均衡器还没收敛或者配置有问题。
第二条命令看Topic最终落到哪个Broker。这里要注意输出的是分区Topic的Owner，通常是整个分区Topic所属的Bundle对应的那台Broker，8个分区全在同一台上。
# 查看Bundle归属 bin/pulsar-admin namespaces list-bundles my-tenant/my-ns # 查看Topic的归属Broker bin/pulsar-admin topics lookup persistent://my-tenant/my-ns/route-test # 查看某个具体分区的归属 bin/pulsar-admin topics lookup \ persistent://my-tenant/my-ns/route-test-partition-3 # 查看集群内所有Broker及其负载 bin/pulsar-admin brokers list my-cluster第三条命令的输出会印证前面说的设计——所有分区指向同一个Broker。如果你的分区Topic分散在不同Broker上，那说明Bundle划分出了问题，大概率是Topic名被改过或者Bundle区间存在重叠。这个现象我在一次集群迁移后遇到过，原因是旧集群的Bundle划分被直接拷了过来，区间和新的不一致，后果是部分分区的元数据读写出现间歇性失败。
5.3 验证生产端分区落点
验证分区路由最直接的办法是发一批带不同Key的消息，然后看每个分区的消息数。用命令行工具发消息可以指定Key和路由模式，配合分区级的统计命令就能看出分布。
# 发100条带递增Key的消息，使用默认轮询路由 for i in $(seq 1 100); do bin/pulsar-client produce persistent://my-tenant/my-ns/route-test \ --messages "payload-$i" \ --key "order-$i" \ --routing-mode RoundRobinPartition \ --num-produce 1 done # 查看各分区的消息量 bin/pulsar-admin topics stats \ persistent://my-tenant/my-ns/route-test | \ jq '.partitions | to_entries[] | "\(.key): \(.value.msgInCounter)"'结果会显示每个分区的消息数大致均匀。然后把Key换成固定的单一值重复一遍，会看到所有消息集中到一个分区——这就是Key哈希的效果。再试一次去掉Key、保持轮询，但把消息改成大批量一次性发送，观察分布是否还均匀，能直观看到批处理对轮询粒度的影响。
实测中我还做过一个对照：同样100条消息，一条一条发和一次发100条，前者分布明显更均匀。原因就是单条发送时每批只有一条，轮询每次都切换；批量发送时一批几百KB，轮询粒度变成了批。这个差异在压测报告里如果没说明清楚，很容易被误读成"轮询路由失效"。
5.4 验证消费端分发
消费端验证要起多个消费者实例，观察每个实例收到多少消息。用Shared订阅起两个消费者，查看统计里的msgRateOut或者消息计数，正常情况下两者接近。然后换Key_Shared订阅，用两组不同前缀的Key发消息，观察是不是固定分流到两个消费者。
这里有个实测细节值得记下来：Key_Shared下两个消费者的分配不一定是五五开，取决于你的Key分布。如果Key的哈希集中在一半空间，消费者拿到的量就会严重倾斜。所以验证Key_Shared不能只看"两个消费者都有消息"，要看"两个消费者拿到的Key集合是否稳定不交叉"——这才是这个订阅类型的核心保证。
# 消费者A，Key_Shared订阅 bin/pulsar-client consume persistent://my-tenant/my-ns/route-test \ -s key-shared-sub -t Key_Shared -n 0 --hex-file /tmp/consumer-a.log # 消费者B，同一订阅 bin/pulsar-client consume persistent://my-tenant/my-ns/route-test \ -s key-shared-sub -t Key_Shared -n 0 --hex-file /tmp/consumer-b.log # 分别统计每个消费者收到的Key前缀 grep -o 'key-[a-z]*' /tmp/consumer-a.log | sort | uniq -c grep -o 'key-[a-z]*' /tmp/consumer-b.log | sort | uniq -c对比两份输出，如果同一个Key同时出现在两个文件里，说明分区间发生了重新分配，这在消费者数量变化时是预期内的，数量不变的情况下出现就是异常。
5.5 主动触发一次Bundle迁移看客户端表现
这一步是压力测试，也是最能建立直觉的一步。用unload命令把某个Bundle从当前Broker卸下来，观察客户端行为。预期现象是：生产端短时间内出现发送失败或超时，日志里能看到ServiceUnitNotReadyException或连接重置；随后客户端重新Lookup，找到新的Owner，恢复发送。整个过程通常在秒级完成，前提是客户端配置了足够的重试次数。
# 卸载指定Bundle，触发归属变更 bin/pulsar-admin namespaces unload \ my-tenant/my-ns \ --bundle 0x00000000_0x2aaaaaaa # 立刻观察Topic归属是否变化 watch -n 1 "bin/pulsar-admin topics lookup \ persistent://my-tenant/my-ns/route-test"我在测试环境反复做过这个操作，几个观察值得分享。第一，如果客户端的重试退避配得太激进（比如固定100毫秒无限重试），迁移瞬间会在新Owner上形成连接风暴，反而拖慢恢复；指数退避加随机抖动明显更稳。第二，迁移期间未Ack的消息会重新投递，如果你的消费逻辑不是幂等的，这时候就会产生重复数据——这个问题在生产环境里一旦发生，排查起来非常痛苦，因为现象是"偶发重复"，抓不到现场。第三，迁移完成后旧Owner上的连接不会立刻消失，会有一段TIME_WAIT残留，看连接数指标时别误判为泄漏。
6. 路由类故障排查速查表
6.1 生产侧报错对照
生产端的路由故障表现相对集中，我把遇到过的整理成表，按报错关键词对照。需要注意的是，同一个报错可能由不同层级的原因此引起，所以表格里给了"下一步动作"这一列，按动作走基本能收敛。
| 报错/现象 | 最可能的层级 | 根因 | 下一步动作 |
|---|---|---|---|
TopicNotFound但Topic确实存在 | 寻址层 | Lookup缓存过期、Owner正在迁移 | 查list-bundles确认归属，看是否有Broker离线 |
ServiceUnitNotReadyException | 寻址层 | Bundle正在加载或正在被接管 | 观察是否自愈，持续超过1分钟查Broker日志的加载耗时 |
| 连接被反复重定向 | 寻址层 | 客户端缓存了错误的Owner地址 | 检查是否有Broker频繁上下线，排查网络分区 |
| 发送超时但Broker指标正常 | 连接层 | 单连接承载Topic过多，队头阻塞 | 拆分连接池，或把热点Topic拆到独立生产者 |
| 分区流量严重倾斜 | 分区路由 | Key分布不均或路由模式选错 | 统计Key基数，考虑加随机后缀或换路由模式 |
| 同Key消息乱序 | 分区路由 | 分区数变更导致哈希取模结果变化 | 确认近期是否扩过分区，必要时停写重建 |
| 批量发送吞吐远低于预期 | 分区路由 | 高Key基数导致按Key拆批 | 检查Entry大小，考虑降Key基数或关按Key拆分 |
表格里第一行那个"Topic不存在但实际存在"的情况，我遇到过两次，两次原因完全不同。第一次是客户端缓存的Owner地址对应的Broker已经下线，连接超时后被误报成Topic不存在；第二次是Bundle正在迁移，新旧Owner都没准备好。区分方法是看错误出现的持续时间——瞬时的、几秒内自愈的是迁移，持续性的、每次都失败的是缓存或拓扑问题。
6.2 消费侧现象对照
消费侧的路由问题更隐蔽，因为消息不会丢，只是"分配得不合预期"。这类问题往往要靠对比多个消费者的指标才能定位。
| 现象 | 可能的层级 | 根因 | 排查手段 |
|---|---|---|---|
| Shared订阅下单个消费者拿到绝大部分消息 | 投递路由 | 各实例消费能力差异大，permits分配倾斜 | 对比各实例的处理耗时和receiverQueue水位 |
| 消费者加入后其他实例停止收消息 | 投递路由 | 误用了Failover订阅，新实例抢占活跃位 | 确认订阅类型，检查消费者名排序 |
| Key_Shared扩缩容后部分Key短暂乱序 | 投递路由 | 哈希区间重新分配 | 确认变更时间点，评估是否可接受 |
| 所有消费者都收不到消息 | 寻址层或Cursor | Owner异常或Cursor卡住 | 查归属、查订阅积压、查Ack位点是否推进 |
| 消费延迟周期性尖刺 | 重试链路 | 重试队列批量回灌 | 看%RETRYTopic的流量曲线 |
| 死信Topic积压但没人消费 | DLQ路由 | DLQ未建分区或未配置消费者 | 查DLQ Topic是否存在、分区数、订阅状态 |
第三行值得单独说。我处理过一个线上反馈"Key_Shared扩容后出现重复消息"的工单，查下来确实有重复，但根因不是消息队列的可靠性问题，而是扩容导致区间重分配，一部分原本属于A消费者的Key转给了C，A手上还有未Ack的在途消息，超时后重投给C。这个场景下重复是设计上的必然，解决方向只有两个：消费端做幂等，或者避开高峰期扩容。前者是根本方案，后者是运维妥协。
6.3 几个反直觉的坑
先说一个最容易误判的：分区数增加后，老消息的消费位置不会自动对齐。分区扩容只是增加了新的分区，旧分区的Cursor保持不变，新分区从最新的位置开始（或者按配置从最早开始）。这意味着如果你的消费者依赖"所有分区的位点大致同步"来做业务判断，扩容后会看到新分区消费得"特别快"，实际上是它起点就靠后。做数据对账的时候这个差异会造成困惑。
第二个坑是Bundle数量和分区数量的乘积效应。前面说过一个分区Topic被一个Bundle兜住，所以8个分区只能由一台Broker服务。如果你为了提升并发把分区加到64，但Bundle还是4个，那并发上限根本没变，只是把一台Broker的负载压得更重了。正确的顺序是先切Bundle再扩分区，反过来做等于白扩。
第三个坑是Proxy模式下Lookup的缓存位置。开启Proxy后，客户端缓存的是Proxy地址，不是Broker地址；Broker的归属变化对客户端不可见，由Proxy自己重新Lookup。所以你在客户端日志里看不到重定向，但实际发生了一次后端切换。排查时如果只看客户端日志，会得出"没有发生迁移"的错误结论，必须去看Proxy的日志。
第四个坑是Ack超时和消费超时的混淆。Ack超时是Broker侧的计时器，到点重投；消费超时是客户端自己的处理超时。两者配得不匹配时会出现"消息还在处理中就被重投"的情况，表现为同一实例收到重复消息。合理的配置是Ack超时明显大于业务处理的P99耗时，留出足够的余量。
注意：以上四个坑有一个共同点——都不会报错，只会让指标看起来"有点怪"。路由层的问题大多如此，靠日志抓不到，只能靠对指标曲线的理解。所以把关键指标（分区级吞吐、消费者级接收速率、Ack位点推进速度）做成看板，比事后排查有效得多。
7. 收尾时想补充的几点实际体会
写到这里，我想起一次集群扩容的经历，可以作为整篇内容的一个注脚。当时集群从8台Broker扩到16台，硬件资源翻倍，但业务侧的吞吐只涨了不到三成。排查了很久，最后发现问题出在Bundle数量：Namespace只有12个Bundle，扩容后新加的8台Broker上只分到了3个Bundle，其余5台几乎空闲。把Bundle切到48个之后，流量很快就摊开了。整个过程没有任何报错，所有监控指标都在"正常"范围内，唯一的异常是"扩容没效果"——这类问题恰恰是路由层最典型的故障形态。
所以我对Pulsar路由的理解可以浓缩成一句话：它不是一个配置项，而是一条有明确所有权边界的链路。生产者管分区，Broker管归属，订阅管分发，三者的边界不要越界去改。想让流量更均匀，先看Bundle够不够；想让顺序更可靠，先看Key和分区的关系；想让消费更均衡，先看订阅类型选对没有。绝大多数路由问题，答案都在"我改的是不是这一层"这个自问里。
最后留一个我自己常用的观测习惯：任何一次扩容、迁移、参数调整之后，我会固定观察三个指标至少半小时——分区级的生产速率方差、消费者级的接收速率方差、Ack位点的推进连续性。前两个反映路由是否均衡，第三个反映路由是否稳定。这三个指标都平稳了，才认为操作完成。单看总吞吐是最容易骗人的，总量平稳的背后可能是一半分区在过年、另一半在挨饿。
