Apache Pulsar 消息体系核心概念全解析:消息、主题、订阅类型与消息去重

原创2026-09-24 15:06:281,758 阅读
文章标签:消息队列后端流处理

Apache Pulsar 消息体系核心概念全解析:消息、主题、订阅类型与消息去重

本文以 Apache Pulsar 2.3.0 版本官方 Messaging Concepts 文档为核心骨架,结合当前仓库中的客户端 API 源码(pulsar-client-api)、broker 配置(conf/broker.conf)与配套 cookbook,系统梳理 Pulsar 消息模型中最核心的概念:消息结构、生产者/消费者行为、主题与命名空间、四种订阅类型、分区主题、非持久化主题、消息保留/过期与消息去重。读完本文,你将能够准确理解 Pulsar 的发布-订阅模型,掌握主题命名、订阅选择、分区路由与去重配置等实战要点,并能在真实部署中据此做出正确的架构决策。

Pulsar 的发布-订阅模型:一切消息行为的基础

Pulsar 构建在经典的 发布-订阅模式(publish-subscribe pattern,简称 pub-sub) 之上。在这个模式中:

  1. 生产者(Producer) 将消息发布到主题(Topic);
  2. 消费者(Consumer) 通过订阅(Subscription) 连接到主题,处理到达的消息;
  3. 消费者处理完成后,需要向 broker 发送确认(Acknowledgement)。

值得特别强调的是 Pulsar 与许多消息队列(如传统 JMS 队列)的关键差异:一旦某个订阅被创建,即使消费者断开连接,Pulsar 也会保留该订阅下的所有消息(持久化存储),只有消费者确认某条消息已经成功处理后,这条消息才会被丢弃。这正是 Pulsar 可以同时充当队列(Queue)与流(Stream)两种语义的基础——详细架构可参见 Concepts 之架构总览。

消息(Messages):Pulsar 数据的最小单元

消息是 Pulsar 中最基本的"单元":生产者把消息发布到主题,消费者从主题消费消息,并在处理完成后对消息进行确认。如果把整个 Pulsar 系统比作邮政系统,消息就是信件本身。

一条 Pulsar 消息由以下组件构成:

组件 用途
Value / 数据负载(data payload) 消息携带的数据。所有 Pulsar 消息都承载原始字节(raw bytes),但消息数据也可以遵循数据 Schema(模式) 的约束
Key(键) 消息可以可选地携带键,键在 主题压缩(topic compaction) 等场景中非常有用
Properties(属性) 用户自定义属性的可选键值映射(key/value map)
Producer name(生产者名称) 产生该消息的生产者名称。生产者会自动获得默认名称,但也可以显式指定
Sequence ID(序列 ID) 每条 Pulsar 消息都属于其所在主题上的一个有序序列,消息的序列 ID 表示它在该序列中的位置
Publish time(发布时间) 消息发布时的时间戳(由生产者自动附加)
Event time(事件时间) 应用可选附加的时间戳,表示"某事发生"的时间,例如消息被处理的时间。若未显式设置,消息的事件时间为 0

关于 Pulsar 消息内容的更深入拆解(消息如何在线上逐字节编码、单条消息与批处理消息的协议差异等),可参阅 Pulsar 二进制协议(binary protocol) 文档。

生产者(Producers)

生产者(Producer)是附着到某个主题、并向 Pulsar broker 发布消息以供处理的过程。

发送模式:同步与异步

生产者可以以**同步(sync)或异步(async)**两种模式向 broker 发送消息:

模式 描述
同步发送(Sync send) 生产者每发送一条消息后都会等待 broker 的确认。如果没有收到确认,生产者将认为该次发送操作失败
异步发送(Async send) 生产者将消息放入阻塞队列(blocking queue)后立即返回。客户端库会在后台把消息发送给 broker。如果队列已满(最大大小可通过 broker 配置 调整),调用 API 时生产者可能被阻塞,也可能立即失败,具体取决于传递给生产者的参数

从客户端 API 的角度看,同步/异步发送分别对应 send() 与 sendAsync() 两类方法(CompletableFuture 风格),异步模式下调用方可以在未来某个时刻等待结果,而无需阻塞当前线程。

压缩

为了节省带宽,生产者发布的消息可以在传输过程中进行压缩。Pulsar 支持以下几种压缩类型:

在客户端库的源码中可以看到对应的编解码器实现,例如 C++ 客户端在 pulsar-client-cpp/lib/ 下分别提供了 CompressionCodecLZ4、CompressionCodecZLib 与 CompressionCodecZstd;此外当前仓库中还实现了 Snappy(CompressionCodecSnappy)编解码器。压缩类型通过生产者配置项的 CompressionType 指定,压缩与解压由客户端库透明完成,broker 与消费者无需关心。

批量发送(Batching)

如果启用了批量发送,生产者会把多条消息累积起来,在单次请求中一并发送。批量的大小由两个维度共同决定:

  • 最大消息数量(batching max messages);
  • 最大发布延迟(batching max publish delay)。

也就是说,只要累积的消息数达到上限,或距离第一批消息到达的等待时间达到上限,生产者就会把当前批次发送出去。批量的目的在于减少网络往返次数,从而在吞吐与延迟之间取得平衡。

消费者(Consumers)

消费者(Consumer)是经由订阅(subscription)附着到某个主题、并接收消息的过程。

接收模式:同步与异步

消息可以从 broker 以**同步(sync)或异步(async)**方式接收:

模式 描述
同步接收(Sync receive) 同步接收会一直阻塞,直到有消息可用
异步接收(Async receive) 异步接收会立即返回一个 future 值——例如 Java 中的 CompletableFuture——该 future 在新的消息可用时完成

异步接收非常适合高并发场景:应用可以同时发起多个"等待中的接收",让客户端库在消息到达时以回调方式完成 future,从而最大化单连接的消费吞吐。

消息确认(Acknowledgement)

当消费者成功处理完一条消息后,它需要向 broker 发送确认,broker 才能丢弃这条消息(否则 broker 会一直 存储 该消息)。

消息确认有两种方式:

  • 单条确认(individual acknowledgement):逐条确认每条消息;
  • 累计确认(cumulative acknowledgement):消费者只需确认它收到的最后一条消息。流中截至(并包含)该条消息的所有消息,都不会再重新投递给该消费者。

⚠️ 累计确认不能用于共享(shared)订阅类型,因为共享模式下同一个订阅会有多个消费者同时访问,累计确认无法正确表达"某条消息已被某个消费者处理完毕"这一语义。

监听器(Listeners)

客户端库可以为消费者提供自己的监听器实现。以 Java 客户端 为例,它提供了 org.apache.pulsar.client.api.MessageListener 接口:每当收到一条新消息时,该接口的 received 方法就会被调用。基于监听器,应用可以编写事件驱动的消费逻辑,而无需自己轮询调用 receive。

主题(Topics)

与其它 pub-sub 系统类似,Pulsar 中的主题是用于在 生产者 与 消费者 之间传输消息的命名通道。主题名称是结构定义良好的 URL:

{persistent|non-persistent}://tenant/namespace/topic

主题名称各组成部分的含义如下:

组成部分 描述
persistent / non-persistent 标识主题的类型。Pulsar 支持两类主题:持久化主题 与 非持久化主题。持久化是默认类型——如果不指定类型,主题就是持久化的。持久化主题的所有消息都会被持久化到磁盘(除非 broker 以 standalone 模式运行,此时意味着多磁盘上的持久化),而非持久化主题的数据不会被持久化到存储磁盘
tenant 主题在实例中所属的租户。租户(tenant)是 Pulsar 多租户能力的基础,并且可以跨集群分布
namespace 主题的管理单元,作为相关主题的分组机制。绝大多数主题配置都是在 命名空间 级别完成的。每个租户可以拥有多个命名空间
topic 名称的最后一部分。主题名称是自由格式的,在 Pulsar 实例中没有特殊含义

无需显式创建主题

在 Pulsar 中你不需要显式创建主题:如果某个客户端尝试向尚不存在的主题写入或接收消息,Pulsar 会自动在主题名称所提供的命名空间下创建该主题。

  • 如果客户端创建主题时未指定租户和命名空间,主题会创建在默认租户与默认命名空间中;
  • 你也可以在指定的租户和命名空间下创建主题,例如 persistent://my-tenant/my-namespace/my-topic,该名称表示 my-topic 这个主题创建于 my-tenant 租户的 my-namespace 命名空间下。

在 conf/broker.conf 中可以找到 allowAutoTopicCreation 相关的行为开关,broker 会依据命名空间策略决定是否允许自动创建(持久化与非持久化主题均有对应的开关,见下文非持久化主题一节)。

命名空间(Namespaces)

命名空间(namespace)是租户内部的一个逻辑命名空间(logical nomenclature)。租户可以通过 Admin API 创建多个命名空间。例如,一个拥有多个应用的租户可以为每个应用创建独立的命名空间。

命名空间允许应用创建并管理一个主题层级(hierarchy of topics)。例如主题 my-tenant/app1 就是 my-tenant 租户下应用 app1 的命名空间。你可以在该命名空间下创建任意数量的主题。

在 Pulsar 中,命名空间是绝大多数管理策略的作用边界:消息保留(retention)、消息过期(TTL)、消息去重(deduplication)、限流(throttling)、备份配额(backlog quota)等都是以命名空间为单位进行配置的(详见下文相应章节)。

订阅类型(Subscription types)

订阅(subscription)是一条命名的配置规则,它决定消息如何被投递给消费者。 Pulsar 提供了多种订阅类型:独占(exclusive)、共享(shared)、故障转移(failover),以及(在当前仓库源码中出现的)键共享(Key_Shared)。下图展示了这些类型的整体示意图:

Pulsar 订阅类型总览图:exclusive、shared 与 failover 三种订阅的投递模型

独占(Exclusive)

在 exclusive 类型下,只允许一个消费者附着到该订阅。如果有多个消费者尝试使用同一个订阅名订阅同一个主题,消费者会收到错误。

在上述示意图中,只有 Consumer A-0 被允许消费消息。

Exclusive 是默认的订阅类型。

Exclusive 订阅示意:同一订阅仅允许一个消费者

共享(Shared)

在 shared(或称 round-robin)模式下,多个消费者可以附着到同一个订阅。消息以轮询(round robin)的方式在消费者之间分发,并且任何一条消息只会投递给一个消费者。当某个消费者断开连接时,所有已发送给它但尚未确认的消息会被重新调度,投递给剩余的消费者。

在上述示意图中,Consumer-B-1 和 Consumer-B-2 都可以订阅该主题,而 Consumer-C-1 等其它消费者同样可以加入。

共享模式的两个重要限制

使用 shared 模式时需要注意两点:

  • 消息顺序无法保证(message ordering is not guaranteed);
  • 不能使用累计确认(cumulative acknowledgement)。

Shared 订阅示意:消息按轮询方式分发给多个消费者

故障转移(Failover)

在 failover 类型下,多个消费者可以附着到同一个订阅。消费者会按照消费者名称的字典序(lexically)排序,排在第一位的消费者最初是唯一接收消息的消费者,称为主消费者(master consumer)。

当主消费者断开连接时,所有(未确认的以及后续的)消息都会投递给队列中的下一个消费者。

在上述示意图中,Consumer-C-1 是主消费者;如果 Consumer-C-1 断开,Consumer-C-2 将成为下一个接收消息的消费者。

Failover 订阅示意:主消费者与备选消费者的切换机制

补充:键共享(Key_Shared)——当前仓库源码中的第四种订阅类型

2.3.0 版本文档当时仅收录了上述三种订阅类型,但当前仓库的客户端 API 源码 SubscriptionType.java 中已包含第四种枚举值 Key_Shared:多个消费者可以使用同一个订阅名,所有携带相同 key 的消息都会被投递给同一个消费者,并且可以通过 ordering_key 覆盖消息的 key 来参与消息排序。它结合了 shared 的扩展性与 failover 的按 key 顺序保证,适用于需要"同 key 有序"又需要水平扩展的场景。

三种(按 2.3.0 文档)订阅类型可对比如下:

订阅类型 消费者数量 消息投递 顺序保证 累计确认
Exclusive 仅 1 个 全部消息投给唯一消费者 有 可用
Shared 多个 轮询分发,一条消息仅投一个消费者 无 不可用
Failover 多个 仅主消费者接收,断开后切换 有(分区主题上按分区保证) 可用

多主题订阅(Multi-topic subscriptions)

消费者订阅 Pulsar 主题时,默认订阅的是一个具体主题,例如 persistent://public/default/my-topic。但从 Pulsar 1.23.0-incubating 版本开始,Pulsar 消费者可以同时订阅多个主题。你可以用两种方式定义主题列表:

  • 基于正则表达式(regular expression),例如 persistent://public/default/finance-.*;
  • 通过显式定义主题列表。

通过正则表达式订阅多个主题时,所有主题必须位于同一个命名空间中。

当订阅多个主题时,Pulsar 客户端会自动调用 Pulsar API 发现匹配正则/列表的主题,然后订阅它们全部。如果其中某些主题当前尚不存在,消费者也会在这些主题创建后自动订阅它们。

跨主题不存在顺序保证

生产者向单个主题发送消息时,所有消息都保证按发送顺序被读取。但这一保证在多个主题之间并不成立。因此当生产者向多个主题发送消息时,从这些主题读取消息的顺序无法保证与发送顺序一致。

下面是 Java 的多主题订阅示例:

import java.util.regex.Pattern;

import org.apache.pulsar.client.api.Consumer;
import org.apache.pulsar.client.api.PulsarClient;

PulsarClient pulsarClient = // 实例化 Pulsar 客户端对象

// 订阅命名空间内的所有主题
Pattern allTopicsInNamespace = Pattern.compile("persistent://public/default/.*");
Consumer allTopicsConsumer = pulsarClient.subscribe(allTopicsInNamespace, "subscription-1");

// 基于正则表达式订阅命名空间内的部分主题
Pattern someTopicsInNamespace = Pattern.compile("persistent://public/default/foo.*");
Consumer someTopicsConsumer = pulsarClient.subscribe(someTopicsInNamespace, "subscription-1");

更多代码示例可参阅 Java 客户端文档中的多主题订阅章节。

分区主题(Partitioned topics)

普通主题只能由一个 broker 提供服务,这限制了主题的最大吞吐量。分区主题(partitioned topic)是一种特殊类型的主题,可以由多个 broker 共同处理,从而支持高得多的吞吐。

在幕后,一个分区主题实际上被实现为 N 个内部主题,其中 N 是分区数。向分区主题发布消息时,每条消息会被路由到多个 broker 之一。分区在 broker 之间的分布由 Pulsar 自动处理。

下图说明了这一点:

分区主题示意:Topic1 的 5 个分区(P0-P4)分布在 3 个 broker 上

在上图中,主题 Topic1 拥有 5 个分区(P0 至 P4),分布在 3 个 broker 上。由于分区数多于 broker 数,两个 broker 各处理 2 个分区,第三个 broker 只处理 1 个(同样,分区分布由 Pulsar 自动完成)。

该主题的消息被广播给两个消费者。**路由模式(routing mode)决定每条消息由哪个分区(进而哪个 broker)处理,而订阅类型(subscription type)**决定哪些消息投递给哪些消费者。

大多数情况下,路由与订阅类型的选择可以分开考虑:一般而言,吞吐需求应指导分区/路由决策,而应用语义应指导订阅决策。

在订阅类型的工作方式上,分区主题与普通主题没有区别——分区只决定"消息从生产者发布后,到消费者处理并确认前"这一段路径上的行为。

分区主题需要通过 Admin API 显式创建,创建时即可指定分区数量。

路由模式(Routing modes)

向分区主题发布消息时,必须指定路由模式。路由模式决定每条消息应发布到哪个分区——也就是哪个内部主题。

Pulsar 提供了三种路由模式(对应客户端 API 中的枚举 MessageRoutingMode):

模式 描述
RoundRobinPartition 如果未提供 key,生产者将按轮询(round-robin)方式把消息发布到全部分区,以获得最大吞吐。请注意,轮询并不是逐条消息进行的,而是以批量的延迟边界为粒度进行,以确保批量发送依然有效。而如果消息上指定了 key,分区生产者会对 key 做哈希,把消息分配到特定分区。这是默认模式
SinglePartition 如果未提供 key,生产者将随机挑选一个分区,并把所有消息都发布到该分区。而如果消息上指定了 key,分区生产者会对 key 做哈希,把消息分配到特定分区
CustomPartition 使用自定义的消息路由器实现来决定特定消息的分区。用户可以使用 Java 客户端 实现 MessageRouter 接口来创建自定义路由模式

从源码看,MessageRoutingMode.java 的 javadoc 明确指出:上述路由逻辑是在应用没有通过 TypedMessageBuilder#key(String) 为特定消息设置 key 时才生效;一旦设置了 key,SinglePartition 与 RoundRobinPartition 都会退化为"按 key 哈希到固定分区"。

顺序保证(Ordering guarantee)

消息的顺序与 MessageRoutingMode 及消息的 Key 相关。通常,用户期望的是 Per-key-partition(每键每分区) 级别的顺序保证。

如果消息带有 key,无论使用 SinglePartition 还是 RoundRobinPartition 模式,消息都会根据 ProducerBuilder 中指定的 HashingScheme 哈希方案被路由到对应分区。

顺序保证 描述 路由模式与 Key
Per-key-partition(按 key 保证) 所有携带相同 key 的消息保持有序,并落在同一个分区中 使用 SinglePartition 或 RoundRobinPartition 模式,且每条消息都提供 Key
Per-producer(按生产者保证) 来自同一生产者的所有消息保持有序 使用 SinglePartition 模式,且每条消息不提供 Key

哈希方案(Hashing scheme)

HashingScheme 是一个枚举,表示在为特定消息选择分区时可用的标准哈希函数集合(见 HashingScheme.java)。

Pulsar 提供两种标准哈希函数:

  • JavaStringHash——使用常规的 String.hashCode();
  • Murmur3_32Hash——使用 Murmur3 哈希函数。

生产者的默认哈希函数是 JavaStringHash。 需要特别注意:当生产者来自多种不同语言的客户端时,JavaStringHash 并不适用——因为不同语言对 Java String.hashCode() 的实现可能存在差异,会导致同一 key 在不同语言客户端中被哈希到不同分区。在这种跨语言场景下,推荐使用 Murmur3_32Hash,以保证多语言客户端对同一 key 的哈希结果一致。

非持久化主题(Non-persistent topics)

默认情况下,Pulsar 会把所有未确认的消息持久化存储在多个 BookKeeper bookie(存储节点)上。因此持久化主题上的消息数据可以经受住 broker 重启与订阅方故障转移(subscriber failover)。

然而,Pulsar 也支持非持久化主题:这类主题上的消息永远不会被持久化到磁盘,只存在于内存中。使用非持久化投递时,如果 Pulsar broker 被杀掉或某个订阅者断开连接,该(非持久化)主题上所有在途(in-transit)消息都会丢失,客户端可能会观察到消息丢失。

非持久化主题的名称形如下面这样(注意名称中的 non-persistent):

non-persistent://tenant/namespace/topic

关于非持久化主题的更多使用说明,可参阅 Non-persistent messaging cookbook。

在非持久化主题上,broker 会不经过 BookKeeper 持久化,直接把消息投递给所有已连接的订阅者。如果某个订阅者断开,broker 将无法把那些在途消息投递给它,订阅者也永远无法再次收到这些消息。省去持久化存储这一步,使得非持久化主题上的消息传递在某些场景下比持久化主题稍快,但代价是失去了 Pulsar 的部分核心优势。

⚠️ 非持久化主题的消息数据只存在于内存中。 如果 broker 故障或消息数据无法从内存中取回,你的消息数据可能会丢失。请仅在确定你的用例需要并且能够承受这种风险时,才使用非持久化主题。

默认情况下,非持久化主题在 Pulsar broker 上是启用的。你可以在 broker 的 配置 中将其禁用。当前仓库的 conf/broker.conf 中对应配置为:

enablePersistentTopics=true
enableNonPersistentTopics=true

将 enableNonPersistentTopics 改为 false 即可在 broker 上彻底关闭非持久化主题。此外,你可以使用 pulsar-admin topics 接口管理非持久化主题。

性能

非持久化消息通常比持久化消息更快,因为 broker 不持久化消息,并且在消息投递给所有已连接订阅者的同时立即向生产者发回确认。因此,在使用非持久化主题时,生产者会观察到相对较低的发布延迟。

客户端 API

生产者和消费者可以像连接持久化主题一样连接非持久化主题,唯一的关键区别是主题名称必须以 non-persistent 开头。三种订阅类型——exclusive、shared 和 failover——都支持非持久化主题。

下面是一个非持久化主题的 Java 消费者 示例:

PulsarClient client = PulsarClient.create("pulsar://localhost:6650");
String npTopic = "non-persistent://public/default/my-topic";
String subscriptionName = "my-subscription-name";

Consumer consumer = client.subscribe(npTopic, subscriptionName);

同一个非持久化主题的 Java 生产者 示例:

Producer producer = client.createProducer(npTopic);

消息保留与过期(Message retention and expiry)

默认情况下,Pulsar 消息 broker 的行为是:

  • 立即删除所有已被消费者确认的消息;
  • 将所有未确认的消息持久化存储在消息积压(message backlog)中。

Pulsar 提供了两个特性来覆盖这种默认行为:

  • 消息保留(retention):让你能够存储已经被消费者确认的消息;
  • 消息过期(expiry):让你能够为尚未被确认的消息设置存活时间(time to live,TTL)。

所有消息保留与过期都在命名空间](#命名空间-namespaces)级别管理。操作指南可参阅 [Message retention and expiry cookbook。

下图同时说明了这两个概念:

消息保留与过期示意:保留策略决定已确认消息是否继续存储,TTL 决定未确认消息何时被删除

  • 上图上半部分展示的是消息保留:作用于命名空间内所有主题的保留策略(retention policy)决定了部分消息即使已被确认,也会被持久化保存在 Pulsar 中。未被保留策略覆盖的已确认消息会被删除。如果没有保留策略,那么所有已确认消息都会被删除。
  • 上图下半部分展示的是消息过期:某些消息即使尚未被确认,也会因为过期而被删除——因为它们已经超过了应用于该命名空间的 TTL(例如命名空间配置了 5 分钟 TTL,而某条未确认消息已经存在了 10 分钟)。

在 broker 层面,conf/broker.conf 提供了一组默认值(命名空间未单独配置时生效):

# 默认消息保留时间(分钟),0 表示不保留
defaultRetentionTimeInMinutes=0
# 默认保留大小(MB)
defaultRetentionSizeInMB=0
# 命名空间默认 TTL(秒),0 表示禁用默认 TTL
ttlDurationDefaultInSeconds=0

实际生产环境通常通过 Admin API 在命名空间级别显式配置 retention(保留时长/保留大小)与 messageTTL,以便为不同业务主题定制差异化的存储策略。

消息去重(Message deduplication)

**消息重复(duplication)**指一条消息被 Pulsar 持久化了不止一次。消息去重(deduplication)是 Pulsar 的一个可选特性,它通过每条消息只处理一次来防止不必要的重复,即使该消息被收到多次也是如此。

下图展示了关闭与开启消息去重时分别发生什么:

Pulsar 消息去重示意:开启后,broker 对已见过的消息不再重复持久化

  • 上图上半部分是关闭去重的场景:生产者把消息 1 发布到主题,消息到达 Pulsar broker 并被持久化到 BookKeeper。随后生产者(例如由于某些重试逻辑)再次发送消息 1,broker 再次接收并再次存储到 BookKeeper——于是重复发生了。
  • 上图下半部分是开启去重的场景:生产者发布消息 1,broker 接收并持久化,与第一个场景相同。但当生产者再次尝试发布该消息时,broker 知道自己已经见过消息 1,因此不再持久化它。

消息去重在命名空间级别处理。详细操作指南可参阅 message deduplication cookbook。

生产者幂等(Producer idempotency)

另一种可行的去重思路是确保每条消息只被生产一次,这种方法通常称为生产者幂等(producer idempotency)。这种方法的缺点是把去重工作推迟给了应用本身。而在 Pulsar 中,去重是在 broker 层面处理的——这意味着你无需修改 Pulsar 客户端代码,只需做管理层面的变更即可(指南见 Managing message deduplication cookbook)。

去重与有效一次(effectively-once)语义

消息去重使 Pulsar 成为与流处理引擎(SPE,stream processing engines)及其它寻求 effectively-once(有效一次) 处理语义的系统搭配使用的理想消息系统。不提供自动去重的消息系统需要 SPE 或其它系统自行保证去重,这意味着严格的消息顺序是以把去重责任转嫁给应用为代价的。而在 Pulsar 中,严格顺序保证无需付出任何应用层代价。

在 Pulsar 中配置消息去重

从 conf/broker.conf 与 cookbook 文档可以看出,消息去重默认是关闭的,可以通过 broker 级、命名空间级、主题级三级进行控制:

  • broker 级(全局默认):conf/broker.conf 中 brokerDeduplicationEnabled=false(默认关闭),将其改为 true 并重启 broker,即可对所有命名空间/主题启用。同文件还提供一组去重相关参数:
    • brokerDeduplicationMaxNumberOfProducers=10000——为去重目的而保存的最大生产者信息数量;
    • brokerDeduplicationEntriesInterval=1000——每积累多少条 entry 后对去重信息做一次快照,间隔越大快照越少,但会延长主题恢复时间(快照之后发布的 entry 需要重放);
    • brokerDeduplicationProducerInactivityTimeoutMinutes=360——broker 丢弃与已断开生产者相关的去重信息之前的不活动时间(默认 6 小时)。
  • 命名空间/主题级(按需覆盖):使用 pulsar-admin namespaces set-deduplication 或 pulsar-admin topics set-deduplication 命令,配合 --enable/-e 或 --disable/-d 标志指定目标命名空间或主题。例如:
$ bin/pulsar-admin namespaces set-deduplication \
  --enable public/default
  • 生产者端配合:启用 broker 去重后,客户端生产者还需要满足两个条件才能真正生效——显式设置生产者名称(producer name),并将发送超时设为 0(sendTimeout/send_timeout_millis),以保证重试时 broker 能识别出同一生产者与同一条消息(具体示例见 cookbooks-deduplication 中 Java、Python、C++ 客户端的配置说明)。

总结

本文围绕 Apache Pulsar 的 Messaging Concepts 文档,完整梳理了其消息体系的八个核心维度:

  1. 消息是数据的最小单元,由数据负载、Key、属性、生产者名、序列 ID、发布时间与事件时间组成;
  2. 生产者支持同步/异步发送、多种压缩算法与批量发送;
  3. 消费者支持同步/异步接收、单条/累计确认与监听器回调;
  4. 主题采用 {persistent|non-persistent}://tenant/namespace/topic 的结构化命名,并支持自动创建;
  5. 命名空间是配置与多租户管理的作用边界;
  6. 订阅类型包括默认的 exclusive、高扩展的 shared 与故障转移的 failover(当前源码中还包含 Key_Shared);
  7. 分区主题通过 N 个内部主题突破单 broker 吞吐瓶颈,并由路由模式、顺序保证与哈希方案共同决定消息去向;
  8. 非持久化主题、消息保留/过期与消息去重则分别解决低延迟、存储策略与重复消息三个实际问题。

无论是搭建生产级消息管道、设计基于分区的流处理拓扑,还是规划多语言客户端的跨语言一致性,理解并正确运用这些概念都是 Pulsar 使用者的基本功。文中涉及的客户端 API 枚举(MessageRoutingMode、HashingScheme、SubscriptionType)与 broker.conf 配置项,均可直接在仓库中查阅,以便在实际环境中做进一步的验证与调优。

登录后查看全文
pulsar