简介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 片段单机模式 brokerServicePort6650 webServicePort8080 # 单机只有一个 bookie所以这三个值只能是 1 managedLedgerDefaultEnsembleSize1 managedLedgerDefaultWriteQuorum1 managedLedgerDefaultAckQuorum1# conf/broker.conf 片段集群模式 zookeeperServers configurationStoreServers advertisedAddress brokerServicePort6650 webServicePort8080 # 集群默认按 2/2/2 起因为官方假设你至少有 3 个 bookie managedLedgerDefaultEnsembleSize2 managedLedgerDefaultWriteQuorum2 managedLedgerDefaultAckQuorum2对比这两份配置就能读出 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:MaxDirectMemorySize1g 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 standalonepulsar-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 为什么还绑着 ZooKeeperPulsar 在这个版本里的元数据分两套存一套是“集群级配置”比如集群名、broker 注册、权限策略另一套是“BookKeeper 元数据”记录 ledger 分布。两者在 2.9.1 里都落在 ZooKeeper 上区别只是用不同的 znode 前缀区分。所以你会看到配置里有两个字段长得像兄弟zookeeperServers和configurationStoreServers。单机部署时两个都填同一个地址没问题多机部署时官方推荐拆开配置存储用一组 ZKBookKeeper 元数据用另一组。理由很实际——配置存储的写入频率极低但关键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 需要改的三处 zkServers127.0.0.1:2181 journalDirectory/data/pulsar/bk-journal ledgerDirectories/data/pulsar/bk-ledger# 第五步起 bookie bin/bookkeeper bookie # 第六步改 conf/broker.conf 后起 broker # zookeeperServers127.0.0.1:2181 # configurationStoreServers127.0.0.1:2181 # advertisedAddress其他机器能访问到的地址 bin/pulsar brokerjournalDirectory和ledgerDirectories必须分盘这是 BookKeeper 的硬性建议。journal 是顺序写的 WAL对延迟敏感ledger 是随机读写的数据文件对吞吐敏感。放同一块盘上写入高峰时两者互相抢 IO表现出来是写入延迟的 P99 突然抬升而 QPS 看起来还很平稳——这种问题在没有监控的情况下极难定位。4.3 quorum 参数与 advertisedAddress 的联动# conf/broker.conf3 个 bookie 的典型配置 managedLedgerDefaultEnsembleSize3 managedLedgerDefaultWriteQuorum3 managedLedgerDefaultAckQuorum2这三个数字的关系是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 的堆外 bufferMaxDirectMemorySize默认值和堆内存绑在一起算流量上来后堆外先耗尽。解决在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 standaloneps -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 -20pulsar_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压测期间重点看四个指标我一般按下面这张表对照指标名含义异常判断brk_pulsar_rate_out出口消息速率与压测设定速率偏差超过 20% 要查消费端反压brk_pulsar_storage_size存储占用稳态下应该平缓持续线性上涨说明保留策略没生效brk_pulsar_subscription_msg_backlog订阅积压压测中持续上涨说明消费能力不足不是 broker 问题bookie_ledgers_countledger 数量增长过快通常是 segment 太小与写入速率不匹配事务是 2.9.1 的一个需要单独提的点。这个版本支持事务但transactionCoordinatorEnabled默认是关闭的配置在broker.conf里。开启后 broker 会多起一个协调器组件客户端的newTransaction()才能用。不开的话客户端不会在连接时报错而是在第一次开启事务时抛异常——又是一个“配置不报错、用的时候才炸”的位置。再补一个我现在的固定习惯任何环境交付前都会走一遍“起服务 → 建租户 → 建分区主题 → 生产消费 → 查 stats → 抓一次 metrics → 跑 60 秒压测”这套动作七步全过才认为这套部署是可用的。中间任何一步失败宁可停下来查也不带着疑点往下走——因为 Pulsar 的组件耦合度高前面一个小配置错了后面会以完全不相干的形态报出来届时排查成本会翻好几倍。希望这套流程能帮你少绕几圈。本文还有配套的精品资源点击获取