Apache Pulsar 2.9.1 部署实战：单机到伪集群避坑指南

简介：Apache Pulsar 2.9.1 二进制分发包面向后端开发、中间件运维及实时流处理学习者，提供部署与运行所需的基础二进制环境，可用于搭建发布/订阅消息系统、验证多订阅类型与消息持久化机制。压缩包约321.53MB，文件总数记录为0，文件类型明细暂未展开，实际以官方二进制发行包结构为准，通常便于按启动脚本、客户端库与辅助工具等模块定位使用。已有152人学习或浏览，适合作为Pulsar入门部署与集群实验的参考包。结合ZooKeeper协调元数据、BookKeeper持久化、分层存储与Pulsar Functions等特性，读者可围绕主题分区、集群配置、租约信息和高可用一致性展开练习；云原生场景下也可对接容器化环境，理解跨节点、跨数据中心部署的容错与水平扩展思路，为大规模实时数据流应用打底。

1. 一个两百多兆的压缩包，凭什么值得单独拆一次

Apache Pulsar 2.9.1 的 bin.tar.gz 是这套分布式消息系统最“裸”的一种交付形态：没有 Docker 镜像，没有 Helm chart，解压出来就是一排脚本、一堆 jar 和一份 conf 目录。它对应的场景非常明确——你手上有几台干净的 Linux 机器，希望在一两个小时内把消息队列跑成能观测、能压测、能交付的状态，而不是先和容器编排纠缠半天。适合做日志采集链路、做多租户消息中台，或者单纯想验证“存算分离”到底省在哪儿的后端同学。下面从解包开始，一路拆到上线前的验证动作。

2. 解包先看结构：bin.tar.gz 里哪几个目录决定成败

拿到压缩包的第一件事不是急着启动，而是把它摊开看清楚。Pulsar 的发行包结构非常稳定，从 2.x 一路到现在基本没变过，理解一次可以复用很久。真正需要看的只有四个位置：bin/决定你能敲什么命令，conf/决定默认行为，lib/决定运行时依赖，examples/决定你验证时有没有现成样例。

2.1 bin 与 lib：脚本做了什么，jar 又该由谁管

tar -xzf apache-pulsar-2.9.1-bin.tar.gz cd apache-pulsar-2.9.1 ls -F bin/ | head -20 # pulsar 统一入口，后面接子命令（standalone/broker/zookeeper/bookkeeper） # pulsar-admin 管理面客户端：租户、命名空间、主题、订阅 # pulsar-client 命令行生产/消费工具，验证连通性最快的手段 # pulsar-daemon 后台启动包装脚本，生产环境基本都用它 # bookkeeper BookKeeper 自己的入口，起 bookie 用 # pulsar-perf 内置压测工具，比外部压测框架省事 du -sh lib/ conf/ examples/

bin/pulsar是最核心的一个脚本，它本身不是 Java 程序，而是一层 shell 分发器：读环境变量拼 JVM 参数，再根据子命令决定加载哪个主类。这意味着所有和内存、GC、日志相关的调优，第一落点都在这个脚本读取的环境变量上，而不是配置文件里。我一般会先打开它确认两件事：PULSAR_MEM的默认值，以及PULSAR_EXTRA_OPTS是否被引用。默认内存给得相当保守，只有百来兆量级，这在单机试用时够用，但只要开始跑真实流量，第一步就得改它。

lib/目录里堆的是编译好的依赖，包含 broker、bookkeeper、zookeeper 三套运行时的 jar。注意 2.9.1 这个版本把 ZK 和 BookKeeper 的客户端都打进来了，所以单机模式下你能直接用包内自带的组件起服务，不需要额外装 ZooKeeper——这是 standalone 能“一条命令跑全栈”的根本原因，也是很多人误以为“Pulsar 不依赖外部组件”的误会来源。

examples/目录里放着若干示例 jar，主要是 Functions 的演示。新手容易在这里卡住：示例能跑不代表 Functions Worker 配置正确，standalone 默认是把 worker 一起拉起来的，端口 6750，如果你后面把它关了又去跑示例，会得到一个连接超时的错误，而不是配置报错。

2.2 conf 里的默认值，暴露了 2.9.1 的部署定位

# conf/standalone.conf 片段（单机模式） brokerServicePort=6650 webServicePort=8080 # 单机只有一个 bookie，所以这三个值只能是 1 managedLedgerDefaultEnsembleSize=1 managedLedgerDefaultWriteQuorum=1 managedLedgerDefaultAckQuorum=1

# conf/broker.conf 片段（集群模式） zookeeperServers= configurationStoreServers= advertisedAddress= brokerServicePort=6650 webServicePort=8080 # 集群默认按 2/2/2 起，因为官方假设你至少有 3 个 bookie managedLedgerDefaultEnsembleSize=2 managedLedgerDefaultWriteQuorum=2 managedLedgerDefaultAckQuorum=2

对比这两份配置就能读出 2.9.1 的设计取向：单机用于开发自测，集群用于真实部署。参数说明一下这三个 quorum 字段的含义——ensembleSize是一条 ledger 分配到的 bookie 数量，writeQuorum是每次写入要落到几个 bookie 上，ackQuorum是写端要收到几个确认才算成功。单机配 1/1/1 是因为只有一个 bookie，写了 2 份也没地方放；集群配 2/2/2 是官方给的最低能容忍单点故障的组合。

提示：advertisedAddress留空时，broker 会用本机主机名注册自己。这一条后面会反复出现，是新手最常见的连不上问题根源。

conf/下还有zookeeper.conf、bookkeeper.conf、proxy.conf、functions_worker.yml。其中bookkeeper.conf的journalDirectory和ledgerDirectories值得单独看一眼：默认指向/tmp下的路径，这在容器里或者机器重启后会直接丢数据。做任何非玩具性质的验证之前，先把这两个路径改成独立磁盘挂载点，属于基本素养。

3. 单机跑通：standalone 的三条命令和一个闭环验证

单机模式的价值不在生产，而在于它能让你在十分钟内把租户、命名空间、主题、订阅整条链路走一遍，形成一个“我知道它长什么样”的具象认知。后面搭集群时，所有命令都是一样的，只是目标地址变了。所以这一步别跳过，跳过后面的错误你会分不清是配置问题还是用法问题。

3.1 起服务：内存、端口与前台后台的选择

# 前台启动，日志直接打到终端，适合第一次跑、观察启动过程 export PULSAR_MEM="-Xms512m -Xmx512m -XX:MaxDirectMemorySize=1g" bin/pulsar standalone -nss

-nss是--no-stream-storage的缩写，作用是关闭流存储服务。单机测试用不到它，关掉能省一点启动时间和内存。PULSAR_MEM这个环境变量会被bin/pulsar脚本读取并拼进 JVM 启动参数，两个值要分开看：-Xmx管堆内存，MaxDirectMemorySize管堆外内存。Pulsar 的读写大量走 Netty 的堆外缓冲，堆外给小了会先出现OutOfDirectMemoryError而不是 OOM，这类报错在日志里长得不像内存问题，很容易误判。

前台跑起来后，正常会看到连续几段日志：ZooKeeper 起来、BookKeeper 起来、broker 起来，最后打印一行包含messaging service is ready的信息。此时另开一个终端：

ss -lntp | grep -E '2181|3181|6650|8080' # 2181 ZooKeeper # 3181 BookKeeper # 6650 broker 二进制协议端口（客户端连这个） # 8080 HTTP 管理端口（pulsar-admin 和 metrics 走这个）

要是准备长期挂着，换成后台方式：

bin/pulsar-daemon start standalone bin/pulsar-daemon stop standalone

pulsar-daemon本质是把标准输出重定向到logs/下再 nohup，出问题时去logs/pulsar-standalone-*.log里找，别在终端里干等。这里有个小细节：后台启动失败时脚本不一定返回非零退出码，所以启动完必须用ss或pulsar-admin brokers list再确认一次，别信脚本的返回值。

3.2 pulsar-admin 把租户/命名空间/主题这条链建起来

Pulsar 的资源模型是四层：租户 → 命名空间 → 主题 → 订阅。这个层级不是装饰，它直接决定了配额、权限、留存策略挂在哪一级。很多人第一次用会觉得绕，但只要按顺序建一遍就通了。

# 1) 建租户，租户是资源隔离的最上层，多租户场景下每个业务方一个 bin/pulsar-admin tenants create my-tenant # 2) 在租户下建命名空间，配额、消息保留、复制策略都挂在这一层 bin/pulsar-admin namespaces create my-tenant/my-ns # 3) 设置命名空间的保留策略：保留 1 小时或 1GB，先到先删 bin/pulsar-admin namespaces set-retention my-tenant/my-ns \ --time 1h --size 1G # 4) 建一个普通主题 bin/pulsar-admin topics create persistent://my-tenant/my-ns/demo # 5) 再建一个 3 分区的分区主题，用于对比 bin/pulsar-admin topics create-partitioned-topic \ persistent://my-tenant/my-ns/demo-partitioned --partitions 3 # 6) 查看主题列表，确认建成功 bin/pulsar-admin topics list my-tenant/my-ns

参数说明几处容易含糊的地方。set-retention的--time和--size是“或”关系，任一条件满足就触发删除，不是“且”；要永久保留就写--time -1 --size -1，但生产环境慎用，磁盘会替你记住这个决定。create-partitioned-topic创建出来的是一个逻辑主题加 N 个物理分区，topics list只会显示逻辑名，用topics stats才能看到分区明细。

主题名里的persistent://前缀不能省。2.9.1 里还有一种non-persistent://，走的是不落盘路径，吞吐更高但 broker 重启即丢，适合做实时信令这类允许丢的场景。写错前缀不会报语法错，只会创建出一个你以为存在、实际在另一个域里的主题，然后用stats查不到——这是我早期翻过的一次车。

3.3 pulsar-client 生产消费闭环验证

# 生产 5 条消息 bin/pulsar-client produce persistent://my-tenant/my-ns/demo \ --messages "hello-pulsar" --num-produce 5 # 起一个订阅消费 5 条，--subscription-name 必须指定 bin/pulsar-client consume persistent://my-tenant/my-ns/demo \ --subscription-name sub-demo --num-messages 5 # 看主题状态：消息数、订阅积压、存储大小都在这里 bin/pulsar-admin topics stats persistent://my-tenant/my-ns/demo

--num-produce的语义是“这一批一共发多少条”，而--messages后面的内容会被当作消息体重复发送。消费端的--num-messages是消费够多少条就退出，不加这个参数会一直阻塞挂着，第一次用很容易以为卡死了。

topics stats的输出字段里，msgRateIn、msgThroughputIn、storageSize、subscriptions是最值得盯的四个。storageSize反映的是 ledger 实际占用，不是消息体大小之和——因为 Pulsar 按 ledger 分段存储，每条消息还带索引和元数据开销，实测下来通常比原始数据大 20% 到 40%，做容量规划时要把这个系数算进去。

跑完这一圈，你已经验证了元数据存储（ZooKeeper）、实际存储（BookKeeper）、接入层（broker）三部分都是通的。这就是单机模式最大的价值：它用最小代价把整条链路点亮了，后面拆成多进程时，你至少知道“正常应该长什么样”。

4. 拆成伪集群：ZooKeeper + BookKeeper + Broker 的手工编排

把三个组件拆开跑，是单机到集群之间必须迈的一步。哪怕所有进程都还在一台机器上，只要它们是独立进程、走网络通信，你就能提前遇到地址注册、元数据初始化、quorum 配置这几类问题。这些问题在单机模式下被默认值掩盖着，一到多机环境就集中爆发。

4.1 2.9.1 为什么还绑着 ZooKeeper

Pulsar 在这个版本里的元数据分两套存：一套是“集群级配置”，比如集群名、broker 注册、权限策略；另一套是“BookKeeper 元数据”，记录 ledger 分布。两者在 2.9.1 里都落在 ZooKeeper 上，区别只是用不同的 znode 前缀区分。所以你会看到配置里有两个字段长得像兄弟：zookeeperServers和configurationStoreServers。

单机部署时两个都填同一个地址没问题，多机部署时官方推荐拆开：配置存储用一组 ZK，BookKeeper 元数据用另一组。理由很实际——配置存储的写入频率极低但关键，BookKeeper 元数据的读写频率随 ledger 数量增长，混在一起时后者的抖动会影响前者的会话保活，表现出来就是偶发的 broker 掉线重连。

注意：这个版本还处在“ZooKeeper 强依赖”阶段，没有可选的元数据后端。做云原生部署评估时，ZK 的运维成本必须算进去，不能只看 broker 是无状态的。

4.2 三进程启动顺序与最小配置改动

顺序不能乱：ZK 先起并可用 → 初始化集群元数据 → 起 BookKeeper → 起 broker。元数据初始化必须在 bookie 之前，因为 bookie 启动时要往 ZK 里注册自己。

# 第一步：准备目录，避免默认的 /tmp 路径 mkdir -p /data/pulsar/{zk-data,bk-journal,bk-ledger,broker-data} # 第二步：改 conf/zookeeper.conf 的 dataDir # dataDir=/data/pulsar/zk-data # 第三步：起 ZooKeeper bin/pulsar zookeeper # 第四步：初始化集群元数据（只需执行一次） bin/pulsar initialize-cluster-metadata \ --cluster pulsar-cluster \ --zookeeper 127.0.0.1:2181 \ --configuration-store 127.0.0.1:2181 \ --web-service-url http://127.0.0.1:8080 \ --broker-service-url pulsar://127.0.0.1:6650

--cluster这个名字要注意，它会被写进主题的完整路径里，后续pulsar-admin clusters list看到的就是它。改名等于重建集群，测试阶段随便叫，定型后别动。--web-service-url和--broker-service-url决定了客户端和服务端拿到的重定向地址，写127.0.0.1就只能本机用，写主机名要保证所有客户端都能解析。

# conf/bookkeeper.conf 需要改的三处 zkServers=127.0.0.1:2181 journalDirectory=/data/pulsar/bk-journal ledgerDirectories=/data/pulsar/bk-ledger

# 第五步：起 bookie bin/bookkeeper bookie # 第六步：改 conf/broker.conf 后起 broker # zookeeperServers=127.0.0.1:2181 # configurationStoreServers=127.0.0.1:2181 # advertisedAddress=<其他机器能访问到的地址> bin/pulsar broker

journalDirectory和ledgerDirectories必须分盘，这是 BookKeeper 的硬性建议。journal 是顺序写的 WAL，对延迟敏感；ledger 是随机读写的数据文件，对吞吐敏感。放同一块盘上，写入高峰时两者互相抢 IO，表现出来是写入延迟的 P99 突然抬升，而 QPS 看起来还很平稳——这种问题在没有监控的情况下极难定位。

4.3 quorum 参数与 advertisedAddress 的联动

# conf/broker.conf，3 个 bookie 的典型配置 managedLedgerDefaultEnsembleSize=3 managedLedgerDefaultWriteQuorum=3 managedLedgerDefaultAckQuorum=2

这三个数字的关系是ackQuorum <= writeQuorum <= ensembleSize。上表的读法是：一条 ledger 分配到 3 个 bookie，每次写入同时发 3 份，收到 2 个确认就返回成功。这意味着能容忍 1 个 bookie 慢或挂，可用性上去了，代价是写放大 3 倍。

如果改成 2/2/2，能容忍 0 个故障——任意一个 bookie 挂了，新的 ledger 就分不出来，broker 会开始报NotEnoughBookiesException。这个异常名字很直白，但日志里往往埋在一堆重试信息中间，第一次见容易去查网络问题。血泪经验是：bookie 数量一变，这三个参数必须同步改，否则新主题创建会间歇性失败，而老主题一切正常，很容易被误判为“偶发问题”。

advertisedAddress是另一个高频坑点。broker 向 ZK 注册的是这个地址，客户端首次连接后会被重定向到这里。留空则取主机名。如果主机名在客户端那台机器上解析不了，现象是：pulsar-admin在 broker 本机能用，从别的机器连就超时，日志里出现Failed to get connection to broker。排查时先hostname再getent hosts <主机名>，确认两边解析一致，比翻配置快得多。

5. 避坑与排查：五个我真实踩过的坑

这一节按“现象 → 原因 → 解决”组织，都是能复现的。Pulsar 2.9.1 这个版本的报错信息整体偏底层，很多异常不会直接指向配置项，所以记现象比记原因有用。

5.1 启动即退出：JDK 版本不匹配

现象：执行bin/pulsar standalone后几秒钟进程消失，日志里出现InaccessibleObjectException或java.lang.reflect.InaccessibleObjectException，堆栈指向 ZooKeeper 或 BookKeeper 的反序列化代码。

原因：2.9.1 运行时依赖的 ZK 和 BookKeeper 版本用到了反射访问 JDK 内部类，在高版本 JDK 上默认被模块系统拦截。这个版本没有做完整的模块化适配。

解决：改用 JDK 8 或 JDK 11，并在启动前用java -version确认不是环境里残留的其它版本。多 JDK 机器上建议在脚本里显式指定JAVA_HOME，而不是依赖 PATH——我见过 PATH 里是 11、JAVA_HOME 指向 8、实际生效的又是第三个版本的情况，排查了半小时。

5.2 跑一会儿就挂：堆外内存没跟着堆一起调

现象：压测跑几分钟后 broker 挂掉，日志末尾是java.lang.OutOfMemoryError: Direct buffer memory，但jstat看堆内存还有大量空闲。

原因：Pulsar 的网络读写、ledger 缓存大量使用 Netty 的堆外 buffer，MaxDirectMemorySize默认值和堆内存绑在一起算，流量上来后堆外先耗尽。

解决：在PULSAR_MEM里显式给堆外内存，量级按堆内存的 1 到 2 倍给，同时把-XX:MaxDirectMemorySize放在同一个变量里，别分散到PULSAR_EXTRA_OPTS。改完必须重启验证，jcmd <pid> VM.native_memory或者简单点看/proc/<pid>/status里的VmRSS，能确认堆外确实涨上去了。

5.3 本机正常、跨机超时：地址注册成了回环

现象：broker 所在机器上pulsar-admin topics list一切正常，从另一台机器用同样命令超时，客户端日志停在Connecting to broker。

原因：advertisedAddress未配置，broker 把主机名注册进了 ZK；或者填了127.0.0.1，客户端拿到这个地址后连的是自己。

解决：把advertisedAddress显式设成其它机器能访问的 IP 或可解析的主机名，重启 broker。改完用bin/pulsar-admin brokers list pulsar-cluster看注册结果，输出里的地址就是客户端会拿到的地址，一眼能验证。

5.4 改完配置重启，行为没变：data 目录残留

现象：改了standalone.conf的端口或 quorum 参数，重启后行为还是老的，甚至报端口被占用。

原因：standalone 模式把元数据和 ledger 都落在data/standalone下，重启时会读回旧的元数据；同时旧进程可能没退干净，端口还被占着。

解决：确认改配置后先bin/pulsar-daemon stop standalone，ps -ef | grep pulsar确认无残留，再决定是否清data/standalone。清目录等于重置集群，测试环境可以，任何有数据的环境都要先确认能不能丢。端口占用的排查用ss -lntp | grep 6650，直接看 PID 比猜快。

5.5 想开分层存储，发现 offloaders 目录是空的

现象：按文档配好managedLedgerOffloadDriver和对象存储参数，重启后topics offload报找不到 driver。

原因：2.9.1 的 bin 包里不包含分层存储的驱动实现，offloaders 是单独的发行包，需要额外放置到offloaders/目录下。

解决：确认offloaders/目录存在且内有对应驱动的 nar 包，没有就先补上再重启。这个坑的隐蔽点在于配置项本身不报错，broker 能正常起来，只有真正触发 offload 时才失败。做云原生环境下的冷热分离方案评估时，这一条要提前验证，别等到容量规划做完才发现驱动没装。

6. 从能跑到敢用：指标、事务开关和一次压测验证

跑通之后最该做的不是继续加功能，而是建立“它现在健康吗”的判断依据。Pulsar 的管理端口自带 Prometheus 格式指标，不需要额外组件：

# 抓关键指标，先确认端点通 curl -s http://127.0.0.1:8080/metrics | grep -E \ 'brk_pulsar_(rate|storage|subscription)' | head -20

pulsar_perf是包里自带的压测工具，比自己写客户端快得多：

# 10 个 topic、每个 1 分区、4 个生产者、每条 1KB、限速 10000 条/秒 bin/pulsar-perf produce \ --topics 10 --threads 4 --rate 10000 --size 1024 \ --duration 120 persistent://my-tenant/my-ns/bench

压测期间重点看四个指标，我一般按下面这张表对照：

事务是 2.9.1 的一个需要单独提的点。这个版本支持事务，但transactionCoordinatorEnabled默认是关闭的，配置在broker.conf里。开启后 broker 会多起一个协调器组件，客户端的newTransaction()才能用。不开的话客户端不会在连接时报错，而是在第一次开启事务时抛异常——又是一个“配置不报错、用的时候才炸”的位置。

再补一个我现在的固定习惯：任何环境交付前，都会走一遍“起服务 → 建租户 → 建分区主题 → 生产消费 → 查 stats → 抓一次 metrics → 跑 60 秒压测”这套动作，七步全过才认为这套部署是可用的。中间任何一步失败，宁可停下来查，也不带着疑点往下走——因为 Pulsar 的组件耦合度高，前面一个小配置错了，后面会以完全不相干的形态报出来，届时排查成本会翻好几倍。希望这套流程能帮你少绕几圈。

本文还有配套的精品资源，点击获取