Apache Pulsar 2.9.1 单机环境部署与消息收发验证指南

简介Apache Pulsar 2.9.1 二进制发行包面向需要构建高吞吐、可扩展消息中间件的后端开发与运维人员尤其适合正在评估或落地分布式发布/订阅架构、准备在云原生环境中部署消息队列的团队。压缩包约 321.53MB内含部署与运行 Pulsar 所需的二进制文件、启动脚本、客户端库及辅助工具解压后即可按官方文档配置服务。Pulsar 以 BookKeeper 提供低延迟持久化存储支持共享、独占与故障转移等多种订阅类型并借助 ZooKeeper 管理主题分区、集群配置与租约信息从而保障分布式环境下的一致性与高可用其分层存储与 Pulsar Functions 轻量流处理能力也便于控制成本并在消息链路中直接完成数据转换。资源已有 152 人学习适合希望快速搭建本地或集群实验环境、理解 Pulsar 与 ZooKeeper 协作机制的读者参考使用。1. 从一台内存不够的测试机说起apache pulsar 2.9.1 单机环境怎么落地上周帮同事在一台 8GB 内存的测试机上装 apache pulsar 2.9.1解压完直接bin/pulsar standalone三分钟不到进程就被系统 OOM 掉了日志里只剩一行含糊的Killed。这不是 Pulsar 本身有问题而是很多人把「单机跑通」和「生产部署」混为一谈默认参数直接怼上去BookKeeper 的写缓存和堆内存一起把机器吃干净。apache pulsar 2.9.1 这个版本在云原生场景里出镜率很高配合 apache zookeeper 做元数据协调是它的标准形态但分布式组件凑在一起版本、端口、内存、JDK 任何一项没对齐装完就是起不来或者起来就挂。这篇记录面向的是想在本机或测试环境把 2.9.1 跑通、并且能验证消息真的收发成功的开发者从版本选择、依赖准备、配置改动到排错按我实际装过一遍的顺序写下来。2. 装前把环境列清楚JDK、内存与端口三件事2.1 版本组合与 JDK 选择apache pulsar 2.9.1 对 JDK 的要求比较明确官方构建和运行基线是 JDK 8 和 JDK 11JDK 17 在这个版本上并没有被完整验证过尤其是 BookKeeper 和 Netty 的一些反射调用在 17 上会触发模块访问限制。我一般会选 JDK 11原因是 8 虽然稳但 2.9.x 的部分依赖已经按 11 编译用 11 能少踩一类UnsupportedClassVersionError。装之前先确认版本java -version # 期望输出类似 # openjdk version 11.0.20 2023-07-18 # OpenJDK Runtime Environment (build 11.0.208)如果机器上同时有多个 JDK用update-alternatives --config java切过去别指望JAVA_HOME设了就行——Pulsar 的启动脚本会优先读JAVA_HOME但某些发行版的pulsar脚本里还会回退到which java两者不一致时会出现「命令行 java 是 11Pulsar 却用 8 跑」的玄学问题。稳妥做法是JAVA_HOME和PATH里的 java 指向同一个目录启动前用echo $JAVA_HOME再核一遍。内存这块要给个明确数字单机 standalone 模式官方建议至少 4GB 空闲内存但实际跑起来 BookKeeper ZooKeeper Broker 三合一8GB 机器上如果不调堆参数很容易被 OOM Killer 盯上。我的经验是测试机给 Pulsar 进程留 4GB 堆、系统留 2GB 以上低于这个配置就别开 standalone改用容器分组件跑。2.2 端口占用与 ZooKeeper 的角色2.9.1 的 standalone 会内嵌一个 ZooKeeper 实例默认端口 2181同时 Broker 占 6650二进制协议和 8080HTTP 管理BookKeeper 占 3181。装之前先扫一遍端口ss -lntp | grep -E 2181|6650|8080|3181 # 有输出说明被占用需要先停掉对应进程或改配置这里要澄清一个常见误解standalone 模式内嵌的 ZooKeeper 只用于本地元数据和你单独部署的 apache zookeeper 集群不是一回事。如果你打算后续切到分布式模式元数据存储要指向外部 ZooKeeper那时候conf/standalone.conf里的zookeeperServers和configurationStoreServers就得改成外部地址。单机阶段先别动保持内嵌减少变量。2.3 目录规划与文件准备下载下来的apache-pulsar-2.9.1-bin.tar.gz解压后是一个完整目录我习惯放到/opt/pulsar下数据目录单独挂一块盘或者单独建目录避免日志和数据混在一起把根分区写满sudo mkdir -p /opt/pulsar /data/pulsar sudo tar -xzf apache-pulsar-2.9.1-bin.tar.gz -C /opt/pulsar --strip-components1 ls /opt/pulsar # 应看到 bin conf lib examples 等目录--strip-components1是为了去掉压缩包里的顶层目录名让文件直接落在/opt/pulsar下后面所有脚本路径都以这个为基准。数据目录/data/pulsar先建好配置阶段再指过去。这一步看着简单但解压到带空格或者中文的路径下启动脚本里的相对路径解析会出问题血泪经验是路径只用英文和短横线。3. 解压后的第一轮配置standalone.conf 里改哪几个值3.1 内存参数别让默认值把机器拖垮conf/standalone.conf是单机模式的入口配置2.9.1 里它同时管 Broker 和 BookKeeper 的堆设置。默认的PULSAR_MEM给得比较保守但在小内存机器上仍然偏大我一般显式改成固定值# 编辑 conf/standalone.conf找到或新增以下行 PULSAR_MEM-Xms2g -Xmx2g -XX:MaxDirectMemorySize2g-Xms和-Xmx设成一样是为了避免运行期堆伸缩带来的抖动MaxDirectMemorySize控制 Netty 的堆外内存BookKeeper 写条目走的是直接内存这个值给小了会报OutOfDirectMemoryError给大了又和堆抢物理内存。2GB 堆 2GB 直接内存是 8GB 测试机上比较稳的组合机器更小就等比往下压但堆别低于 1GB否则 Broker 启动时加载元数据就会卡。改完用grep PULSAR_MEM conf/standalone.conf确认没有重复定义——有些版本模板里这行是注释掉的你新增一行而旧行没删脚本取最后一个容易改了个寂寞。3.2 数据与日志路径把写入引到独立目录默认数据落在data/下日志落在logs/下都在安装目录里。生产习惯是把它们挪出去# conf/standalone.conf 中调整 dataDir/data/pulsar/data # 日志目录通过环境变量控制启动前 export export PULSAR_LOG_DIR/data/pulsar/logsdataDir管的是 BookKeeper 的 ledger 和 ZooKeeper 的快照写入量随消息量线性增长放根分区迟早写满。日志目录用环境变量是因为 2.9.1 的pulsar脚本读PULSAR_LOG_DIR写进配置文件反而不生效。这两个路径改完要确保运行用户有写权限chown -R一遍再启动权限不足时报错信息往往只提示「无法创建文件」不告诉你具体哪个目录。3.3 关闭不需要的组件与端口收敛单机测试环境不需要对外暴露管理端口时可以把webServicePort改成非默认值减少和本机其他服务的冲突# conf/standalone.conf webServicePort8088 brokerServicePort6658改端口后所有客户端连接串都要跟着变pulsar-client默认连 6650测试时记得显式指定--url pulsar://localhost:6658。这一步不是必须的但如果机器上已经跑了别的 Web 服务占着 8080不改就会启动失败报Address already in use排查时先看端口再看配置顺序别反。4. 启动与验证从进程起来到消息真的收发成功4.1 启动命令与日志观察配置改完用前台方式先起一次方便看日志cd /opt/pulsar bin/pulsar standalone # 前台运行CtrlC 退出确认无误后再改后台启动过程会依次拉起 ZooKeeper、BookKeeper、Broker日志里出现messaging service is ready才算真正就绪这中间大概 20 到 40 秒。如果卡在Starting bookkeeper超过一分钟多半是dataDir权限或者磁盘空间问题如果报ZooKeeper session timeout检查 2181 端口有没有被别的进程抢了。后台运行用bin/pulsar-daemon start standalone停止用bin/pulsar-daemon stop standalone别直接kill -9BookKeeper 的 ledger 没正常关闭下次启动要做恢复时间会明显变长。4.2 用内置客户端验证生产消费进程起来不等于能用必须走一遍真实收发。2.9.1 自带pulsar-client工具# 终端一消费先起消费者避免消息漏看 bin/pulsar-client consume my-topic -s sub1 -n 10 # 终端二生产 10 条消息 bin/pulsar-client produce my-topic -m hello-pulsar-1,hello-pulsar-2 -n 10consume的-s是订阅名-n是消费条数消费够数自动退出produce的-m是消息内容多条用逗号分隔-n是发送条数。两边都正常时消费者终端会打印出消息体和 message id。如果生产者报Failed to create producer先看 Broker 日志里有没有Topic not found之外的权限或命名空间错误如果消费者一直挂着没输出检查订阅名是否和生产者所在的命名空间匹配standalone 默认租户是public/defaulttopic 名不带前缀时会自动落到这个命名空间。4.3 管理接口自检除了客户端HTTP 管理接口也能快速判断 Broker 状态curl -s http://localhost:8088/admin/v2/clusters # 正常返回 [standalone] curl -s http://localhost:8088/admin/v2/tenants # 正常返回 [public]这两个接口能通说明 Broker 的 Web 服务和元数据存储都正常。如果第一个通第二个 404多半是初始化没完成等几秒重试如果都连不上回到进程和端口层面查别在配置里绕。5. 装坏了怎么救五条踩坑记录5.1 启动即被 Killed日志无异常现象执行bin/pulsar standalone后进程几秒内消失logs/下没有明显 ERRORdmesg里能看到Out of memory: Killed process。原因PULSAR_MEM和MaxDirectMemorySize之和超过物理内存或者机器上还有其他 Java 进程占着内存OOM Killer 直接动手。解决按 3.1 节把堆和直接内存压到物理内存的一半以内启动前free -h确认可用内存必要时先停掉其他 Java 服务。改完用前台方式起观察 RSS 增长是否平稳。5.2 端口冲突导致启动中断现象日志报BindException: Address already in use进程退出。原因2181、6650、8080、3181 中某个被占用常见是本机已有 ZooKeeper 或另一个 Pulsar 实例没停干净。解决ss -lntp | grep 端口找到占用进程能停就停不能停就按 3.3 节改webServicePort和brokerServicePortZooKeeper 端口在conf/standalone.conf的zookeeperPort里改。改完记得同步客户端连接串。5.3 JDK 版本不匹配的隐蔽报错现象启动时报UnsupportedClassVersionError或NoSuchMethodError指向 Netty 或 BookKeeper 的类。原因JAVA_HOME指向 JDK 8但PATH里的 java 是 17或者反过来脚本和手动命令用了不同 JDK。解决echo $JAVA_HOME和which java对齐到同一个 JDK 11 目录java -version再确认一次。多版本机器上用update-alternatives统一别只改环境变量。5.4 数据目录权限不足导致 BookKeeper 起不来现象日志停在Starting bookkeeper随后报Permission denied或Unable to create directory。原因dataDir指向的目录属主不是运行用户或者磁盘只读、空间不足。解决chown -R 运行用户 /data/pulsardf -h确认空间mount | grep 挂载点确认不是只读挂载。改完重启别在权限没修好时反复重启容易留下半初始化状态。5.5 消费端收不到消息的订阅名问题现象生产者发送成功消费者终端无输出也不报错。原因消费者用的订阅名和之前测试残留的订阅状态冲突或者 topic 名带了命名空间前缀而生产者没带两边实际不是同一个 topic。解决换一个全新的订阅名重试bin/pulsar-admin topics list public/default确认 topic 真实存在生产消费两端统一用完整 topic 名persistent://public/default/my-topic。standalone 模式下残留订阅不会自动清理测试时勤换订阅名能省不少排查时间。6. 装完怎么算跑通一套五分钟自检流程装完别急着交付我固定走一遍自检五分钟内能确认这套 2.9.1 是真能用还是假活。第一步看进程和端口ps -ef | grep pulsar确认只有一个 standalone 主进程ss -lntp确认 2181、6650、8088、3181 都在监听第二步打管理接口/admin/v2/clusters和/admin/v2/tenants都要返回预期 JSON第三步走一次完整收发生产 10 条、消费 10 条条数对得上才算数第四步看日志尾部tail -n 50 logs/pulsar-standalone.log里不应有 ERROR 级别的持续刷屏偶发 WARN 可以接受第五步重启一次bin/pulsar-daemon stop standalone再start确认数据目录里的 topic 还在消费能接着之前的位点走。检查项命令通过标准进程ps -ef | grep standalone仅一个主进程无残留子进程端口ss -lntp | grep -E 2181|6650|8088|3181四个端口均监听管理接口curl -s localhost:8088/admin/v2/clusters返回[standalone]收发pulsar-client produce/consume消费条数与生产一致重启保持pulsar-daemon stop/starttopic 与订阅状态保留这套流程里最容易糊弄过去的是第三步有人只看生产者返回成功就认为通了实际上消息可能落在 ledger 里但消费者因为订阅问题读不到。我吃过一次亏生产端一切正常消费端静默查了半天才发现是 topic 名少了persistent://前缀两端指向了不同实体。从那以后我每次装完 Pulsar都强制用完整 topic 名走一遍生产消费再重启验证一次状态保留两步都过才敢说这套环境跑通了。希望帮到你。本文还有配套的精品资源点击获取