简介Apache Pulsar 2.9.1 官方二进制发行包面向需要构建可靠消息中间件的后端工程师与运维人员解决分布式场景下高性能投递、持久化与多租户隔离问题。压缩包约三百二十一点五兆字节包含启动服务器、客户端库、脚本及其他辅助工具解压后即可按官方文档开展单机或集群部署。Pulsar 利用 ZooKeeper 协调元数据支持多节点水平扩展和故障转移存储层采用 BookKeeper 确保消息不丢失并提供共享、独占、故障转移等多种订阅模式以适配不同业务需求。包内还附带 Functions 轻量流处理能力可在消息流转过程中直接进行过滤与转换其云原生特性亦可无缝集成 Kubernetes便于自动化部署与弹性伸缩。已有约一百五十一人学习该资源适合作为生产环境部署参考也可用于深入理解 Pulsar 内核机制。1. apache pulsar 2.9.1 bin.tar.gz 是什么先跑通单机再谈集群架构一条命令启动一个同时包含 ZooKeeper、BookKeeper、Broker 的分布式消息系统这在同类中间件里不多见但 Apache Pulsar 2.9.1 的 bin.tar.gz 就能做到。这个二进制发行包官方预编译了全部组件和客户端工具解压后即可运行是社区最常见的 Pulsar 入门与验证方式。它解决的核心问题很直接不用先搭三套集群就能在开发机上复现生产环境的行为跑通发布订阅、验证 API、做小规模内部服务对后端开发者、做选型对比的架构师、需要离线部署的实施人员都适用。后面的章节按“下载校验 → 配置启动 → 收发验证 → 踩坑排查 → 生产化改造”的顺序展开。2. 下载与校验把 apache-pulsar-2.9.1-bin.tar.gz 安全装进你的机器先说选择 2.9.1 的理由。Pulsar 的版本节奏比较快2.9.1 是 2.9 系列的首个补丁版本常用于验证环境或对版本敏感的内部系统。选 bin.tar.gz 而非源码包是因为 bin 包已经预编译好全部依赖 jar解压就能起服务源码包要自己用 Maven 编译还得处理依赖下载和 Java 版本兼容时间成本高出几个量级。如果只是为了评估功能、做集成测试或部署离线环境bin 包是唯一推荐选择。2.1 用 sha512 和 GPG 校验 bin.tar.gz避免拿到损坏的发行包先讲为什么校验是第一步Apache 的发行包虽然提供哈希文件但实际下载走 CDN 镜像镜像同步偶尔产生文件不一致更常见的是公司内网中转、下载器断点续传导致文件截断。你tar zxvf到一半报gzip: stdin: unexpected end of file或者解压后 bin/pulsar 脚本少了几行都是没做校验的代价。2.9.1 的发行包同时提供 .sha512 和 .asc 签名文件常见做法是两个都验wget https://archive.apache.org/dist/pulsar/pulsar-2.9.1/apache-pulsar-2.9.1-bin.tar.gz wget https://archive.apache.org/dist/pulsar/pulsar-2.9.1/apache-pulsar-2.9.1-bin.tar.gz.sha512 wget https://archive.apache.org/dist/pulsar/pulsar-2.9.1/apache-pulsar-2.9.1-bin.tar.gz.asc # 校验 sha512输出 OK 才是完整文件 sha512sum -c apache-pulsar-2.9.1-bin.tar.gz.sha512 # 导入 Apache 官方 KEYS 并验签 wget https://archive.apache.org/dist/pulsar/pulsar-2.9.1/KEYS gpg --import KEYS gpg --verify apache-pulsar-2.9.1-bin.tar.gz.asc apache-pulsar-2.9.1-bin.tar.gzsha512sum -c 会读取 .sha512 里的期望值本地重新计算后比对显示apache-pulsar-2.9.1-bin.tar.gz: OK才算完整如果输出 FAILED直接重新下载别想着解压碰运气。gpg --verify 用 KEYS 里的公钥验证 .asc 签名确认这个包确实是 Pulsar 项目签署的防止下载过程中被替换。第一次验签会看到gpg: Good signature同时带一句 WARNING 说公钥没有信任等级这是正常现象因为 KEYS 只提供了公钥本身没建立信任链只要看到 Good signature 就说明文件没被篡改。内网离线环境访问不了外网时可以在构建机上验一次签内网分发时复用同一份 tar 包但哈希校验在每台目标机上都要重做。2.2 JDK 8/11 与目录结构解压后先认清 bin、conf、lib2.9.1 要求 JDK 8 或 11实际部署我用 OpenJDK 11老项目依赖 JDK 8 也完全兼容。有一个前置问题很常见机器上装了多个 JDK 时java命令指向的版本和JAVA_HOME不一致。Pulsar 的启动脚本优先用 JAVA_HOME 定位 java所以java -version显示 8、JAVA_HOME 却是 11 时实际运行的是 11。统一做法是把 JAVA_HOME 写进 /etc/profile.d/ 下的环境脚本里启动前先 echo 确认。java -version echo $JAVA_HOME tar zxf apache-pulsar-2.9.1-bin.tar.gz cd apache-pulsar-2.9.1 ls -la目录/文件作用使用时注意bin/所有命令行入口pulsar、pulsar-daemon、pulsar-admin、pulsar-client、pulsar-perf统一走 bin/pulsar 解析 JAVA_HOMEconf/各组件配置standalone.conf、broker.conf、bookkeeper.conf、zookeeper.conf、pulsar_env.sh端口、内存、存储路径都在这改lib/服务端与工具的全部 jar 依赖不要手动删改避免类加载冲突examples/官方示例代码新手看 API 用法很方便licenses/第三方依赖许可证合规审计时用data/ZooKeeper、BookKeeper 运行时数据首次启动后生成备份必须包含它logs/运行时日志排查问题的第一现场这里要特别强调一个容易踩的坑standalone 模式真正读的是 conf/standalone.conf不是 broker.conf。很多同学把 broker.conf 改了一通bin/pulsar standalone启动后完全不生效因为 standalone 启动流程会用 standalone.conf 覆盖 Broker 默认配置broker.conf 是后续做分布式集群时每台 Broker 的配置文件。这个区分越早认清后面排错越省时间。2.3 运行前的磁盘、权限与文件描述符给 Pulsar 留出 20GB 和独立用户standalone 默认把 ZooKeeper 快照、BookKeeper journal 和 ledger 全写到安装目录下的 data/ 里。一次简单的收发测试占用不大但用 pulsar-perf 压测或 retention 策略没收敛时几个 GB 很快会没。我一般先做三件事确认目标分区剩余空间、用非 root 用户运行、调大文件描述符上限。df -h /data useradd -r -s /bin/bash pulsar mkdir -p /data/pulsar chown -R pulsar:pulsar /data/pulsar ulimit -n 65536用独立用户运行是为了避免以 root 启动后在数据目录里留下 root 属主的文件将来切到普通用户做备份、清理、迁移时权限处处碰壁。解压后我会把安装目录和数据目录分离安装目录放 /opt/pulsardata/ 用软链指到 /data/pulsar/data这样后面升级补丁版本时直接替换安装目录数据不动。ulimit -n 是文件描述符上限默认 1024 在高并发连接下很快打满表现为连接被拒或线程卡住临时设置只对当前会话有效要写进 systemd unit 或 /etc/security/limits.conf 持久化。更规范的做法是写一个 systemd unit 文件管理进程生命周期把 User、LimitNOFILE、ExecStart 都固化下来比裸用 pulsar-daemon 更适合长期跑的 standalone 测试机。磁盘 20GB 是起点参考值取决于你要保留多少消息按 1GB 堆内存配 4GB 数据空间的比倒推算测试环境 20GB 很宽松。3. 启动 standalone 与核心参数一条命令背后的三个配置来源默认配置能跑但一定不适合你的实际机器。在 2GB 内存的云主机上直接用默认配置启动Broker 和 BookKeeper 的内存预算加起来可能超过物理内存必炸。落地时我按三个文件来改conf/pulsar_env.sh 管 JVM 内存conf/standalone.conf 管 Broker 行为conf/bookkeeper.conf 管存储路径。下面的内容围绕这三个配置来源展开。3.1 bin/pulsar standalone 与后台守护端口、日志和进程关系执行bin/pulsar standalone会以前台方式启动进程里同时包含内嵌的 ZooKeeper、BookKeeper、Broker 和 Function Worker。第一次启动会看到大量 INFO 日志最后出现Standalone service started at http://0.0.0.0:8080这行输出说明服务就绪。默认端口如下端口服务说明2181ZooKeeper元数据存储standalone 内嵌3181BookKeeperbookie 服务端口6650Broker客户端生产/消费的二进制协议端口8080Broker管理端口pulsar-admin 走这里8000Function Workerstandalone 默认启用 Functions Worker前台启动适合第一次跑通日志直接打在终端上CtrlC 一次全停。但终端一关进程就没了日常起测试环境我建议用守护进程方式bin/pulsar-daemon start standalone bin/pulsar-daemon stop standalone tail -f logs/pulsar-standalone-*.logpulsar-daemon 会把进程放到后台日志写到安装目录的 logs/ 下文件名以 pulsar-standalone 开头。stop 是标准优雅停机会依次让 Broker 停止接收新请求、bookie 刷盘、ZooKeeper 关闭。2.9.1 的 standalone 在 stop 后有时要等十几秒才完全退出这时候别急着再次 start否则端口还没释放新进程会直接失败。想确认进程真的退了用ps -ef | grep PulsarStandaloneLauncher。启动失败时别只看最后几行用 grep 找到第一个 ERROR 或Caused by之前的上下文大多数根因在异常栈的Caused by那一行而不是最后一行。3.2 standalone.conf、broker.conf、pulsar_env.sh哪些参数必须改先泼冷水默认配置能跑通但不代表适合你的机器。我按三个文件来改第一处是内存配置在 conf/pulsar_env.sh 里# conf/pulsar_env.sh PULSAR_MEM-Xms1g -Xmx1g -XX:MaxDirectMemorySize2g BOOKIE_MEM-Xms512m -Xmx512m -XX:MaxDirectMemorySize1g ZK_MEM-Xms512m -Xmx512mPULSAR_MEM 对应 Broker 进程BOOKIE_MEM 对应 bookieZK_MEM 对应 ZooKeeper。堆内存给多少取决于消息体大小和并发数Netty 网络传输走的是堆外 direct memory所以 MaxDirectMemorySize 必须显式给否则高吞吐压测时会报OutOfMemoryError: Direct buffer memory这个错光加大 -Xmx 是不管用的。如果你的场景是大量小消息小于 1KB堆内存可以压得更低重点是 direct memory如果是 10KB 以上的大消息堆内存反而要给足因为消息对象在消费端会进入堆内。没有固定标准答案压测后看 GC 日志调整才是正路。第二处是 conf/standalone.conf重点参数如下参数默认值说明webServicePort8080管理端口pulsar-admin 和 HTTP 请求入口brokerServicePort6650二进制协议端口改它要同步改客户端连接串advertisedAddress空空时取 hostname客户端连不上时显式设为内网 IPmanagedLedgerDefaultEnsembleSize1分片写入的 bookie 数standalone 只能 1集群要调 3managedLedgerDefaultWriteQuorum1写入副本数managedLedgerDefaultAckQuorum1确认副本数brokerDeleteInactiveTopicsEnabledtrue空 topic 自动删除测试数据容易被静默清理retentionSizeInMB-1按大小保留消息-1 表示不限制这些参数在 standalone.conf 和 broker.conf 里都存在standalone 模式以 standalone.conf 为准集群模式以 broker.conf 为准。第三处是 conf/bookkeeper.conf。standalone 会读这个文件来启动内嵌 bookie最实用的参数是journalDirectory和ledgerDirectories默认指向安装目录 data/ 下的子目录。想把数据放到独立磁盘改的是这里而不是 standalone.conf。注意 2.9.x 的 ledger 目录参数是复数形式ledgerDirectories可以配多个路径做负载分摊逗号分隔。3.3 用 pulsar-admin 和 pulsar-client 验证消息收发启动完成后先做管理面验证再做数据面验证。管理面用 pulsar-admin 查集群和 topic数据面用 pulsar-client 生产和消费一条消息bin/pulsar-admin clusters list bin/pulsar-admin topics list persistent://public/default bin/pulsar-client produce -m hello-pulsar-2.9.1 -n 1 persistent://public/default/order-events bin/pulsar-client consume -s order-sub -n 1 persistent://public/default/order-eventsclusters list 输出 standalonetopics list 一开始是空列表produce 向 persistent://public/default/order-events 写入一条消息Broker 第一次见到这个 topic 会自动创建。consume 指定订阅名 order-sub消费一条后退出。注意持久化 topic 必须以 persistent:// 开头不带 scheme 时 pulsar-client 默认走 persistent。想看消息有没有真正落盘再执行bin/pulsar-admin topics stats persistent://public/default/order-events重点看 StorageSize 和 msgBacklog 字段StorageSize 大于 0 说明写入 BookKeeper ledger 成功msgBacklog 在 consume 后归零说明消费位点推进正常。这套验证覆盖了生产上最关注的两条链路管理链路HTTP 8080和数据链路6650。这里有个细节2.9.1 默认的订阅类型是 Exclusive独占同一个订阅名下只能有一个消费者在消费想开多个消费者分摊要给 consume 加-t shared。学习阶段无所谓但用共享订阅测试时很容易踩“第二个消费者连不上”的坑。4. Pulsar 2.9.1 避坑指南五个高频翻车现场与排查方法以下五类问题是我在实际使用 2.9.1 时见过的大部分和版本无关换 2.10、2.11 同样适用。每条按现象、原因、解决的顺序写方便你照着排查。4.1 端口冲突8080/6650 被占导致 Broker 启动失败现象bin/pulsar standalone启动后日志里出现Failed to bind to [0.0.0.0:8080]或Address already in use进程随即退出终端上只能看到一段 bind 异常堆栈。原因机器上已有服务占用了 webServicePort 或 brokerServicePort常见的是其他 Java 应用占 8080自研 RPC 或老消息中间件占 6650。解决ss -lntp | grep -E 8080|6650|2181|8000 # 确认被占用后改 conf/standalone.conf 里的端口再重启优先改 Pulsar 的端口而不是杀业务进程因为一旦改动 6650所有客户端连接串都要同步更新。改完用 ss -lntp 确认四个端口都 LISTEN。如果 8080 和 6650 没被占但启动还是失败把日志里第一个 bind 异常的完整堆栈拿来找上下文大多是 advertisedAddress 配置导致的绑定问题。4.2 JVM 内存翻车默认堆内存不适合小机器现象在 2GB 内存的虚拟机或容器里启动 standalone运行一阵出现OutOfMemoryError: Java heap space或整机卡进 swap压测数据完全不可信。原因默认 PULSAR_MEM、BOOKIE_MEM 加在一起把物理内存吃满容器场景下 JVM 还未必识别 cgroup 限制。解决启动前改 pulsar_env.sh启动后确认实际生效参数ps -ef | grep PulsarStandaloneLauncher | grep -v grep jcmd PID VM.flags | grep -E Xmx|MaxDirectMemorySize如果 jcmd 输出和你改的不一致检查是不是通过 bin/pulsar 启动时环境变量被其他脚本覆盖。按我的经验1GB 堆给 Broker、512MB 堆给 bookie就能在 2GB 容器里跑完 10 万条消息的测试还不行就用 docker stats 确认容器内存上限。另一个隐蔽点是 swap内存不够时系统换页Pulsar 的延迟会瞬间飙高压测数据完全不可信所以压测前先把 swap 关掉或预留充足内存。4.3 BookKeeper journal 损坏非正常关闭后的启动失败现象kill -9杀掉 standalone 进程后再次启动报Failed to read the journal或Bookie journal consistency check failedbookie 起不来。原因BookKeeper 的 journal 是顺序写盘进程被杀时最后一个写事务可能未完成恢复ZooKeeper 侧的元数据还在但 bookie 数据侧的目录已经不一致。解决优先用bin/pulsar-daemon stop standalone优雅停机已经损坏的把损坏目录备份后移走再恢复启动cp -a data data.bak.$(date %s) mv data/bookkeeper-journal data/bookkeeper-journal.bad mv data/bookkeeper-ledgers data/bookkeeper-ledgers.bad bin/pulsar-daemon start standalone移走损坏目录会让这个 standalone 实例上已保存的所有消息丢失所以这条命令只适用于测试环境、数据可重建的场景。如果里面有不能丢的数据正确做法是保留原数据目录找有 BookKeeper 恢复经验的人手工回放 journal代价远大于重建。这算 2.9.1 的一条血泪经验任何对 data/ 目录的拷贝都要先停服务热拷贝的一致性没人能保证。4.4 客户端连接超时hostname 与防火墙才是真凶现象服务端日志一切正常但本机或局域网另一台机器用 pulsar-client 时报Connection refused或长时间waiting for connection。原因standalone 默认用本机 hostname 作为 advertisedAddresshostname 可能解析到 127.0.0.1客户端拿到错误地址另一种可能是防火墙或云安全组没放行 6650/8080。解决显式设置 advertisedAddress 为本机内网 IP# conf/standalone.conf advertisedAddress192.168.1.20 bin/pulsar-daemon stop standalone bin/pulsar-daemon start standalone nc -vz 192.168.1.20 6650改完后用bin/pulsar-admin brokers list standalone看 broker 上报地址是否已是内网 IP。advertisedAddress 只影响广播给客户端的地址不影响监听监听由 brokerServicePort 决定。排查网络层用 nc 或 telnet两步就能分清是地址问题还是防火墙问题本机连不通是地址问题局域网其他机器连不通则先查防火墙。4.5 磁盘写满Broker 拒绝写入与 topic 自动卸载现象分区使用率到 100% 后produce 报错日志出现No space left on device或 bookie 状态变为不可写部分空 topic 还消失了。原因BookKeeper ledger 写入需要连续磁盘空间分区满后 broker 判定 bookie 不可写brokerDeleteInactiveTopicsEnabledtrue又会让超过保留时间的空 topic 被自动清理。解决先扩容或收敛 retention再决定是否关闭自动删除df -h /data bin/pulsar-admin namespaces set-retention public/default --size 10G --time 3dretention 的 size 和 time 同时设表示保留最多 10GB 或最多 3 天先到先删。这里有个常见误解消息被消费确认后并不会自动删除Pulsar 的存储模型是“消息保留直到 retention 策略淘汰”消费位点只影响 backlog 计数不影响磁盘占用。所以压测完不清理磁盘迟早写满。生产环境记得给 ledger 目录单独挂盘别和系统盘共用。5. 进阶验证用 pulsar-perf 压测 2.9.1 并准备生产化改造验证一个消息中间件能不能用不能只看一条消息收发。我在跑通 standalone 后会在同一台机器上用 pulsar-perf 做一轮压测顺带确认第 3 章改的内存参数是否合理# 4 个 producer 线程每个线程每秒 1 万条共 60 万条 bin/pulsar-perf produce persistent://public/default/perf-test -t 4 -r 10000 --num-messages 600000 # 另一个终端消费看吞吐和延迟分位数 bin/pulsar-perf consume persistent://public/default/perf-test -t 4 --num-messages 600000压测结束后看两个数字producer 侧 “Throughput produced” 和 consumer 侧 “Publish latency” 的分位数。单机 standalone 跑到几万 msg/s 是正常的如果只有几百条回查 4.2 节的 direct memory 配置和磁盘类型。压测会留下大量 backlog收尾时用bin/pulsar-admin namespaces set-retention public/default --size 5G --time 1d收敛别让测试数据把磁盘堆满。验证完单机能力就该把 standalone 的配置思维迁移到生产架构。常见做法是拆成三套角色ZooKeeper 集群做元数据协调至少 3 节点、BookKeeper 集群存 ledger副本数建议 3、Broker 集群对外服务。先初始化集群元数据再逐台启动 Brokerbin/pulsar initialize-cluster-metadata --cluster pulsar-prod \ --zookeeper zk1:2181,zk2:2181,zk3:2181 \ --configuration-store zk1:2181,zk2:2181,zk3:2181 \ --web-service-url http://broker1:8080,broker2:8080 \ --broker-service-url pulsar://broker1:6650,broker2:6650初始化元数据后每台 Broker 的 conf/broker.conf 里设置相同的 zookeeperServers、clusterName并把第 3 章里那几个 managedLedger 副本参数从 1 调到 3启动方式从bin/pulsar standalone换成bin/pulsar-daemon start broker否则生产集群里数据只有一份bookie 宕机就是真丢数据。最后提醒一个习惯不管单机还是集群每次改完配置都用bin/pulsar-admin brokers get-internal-config standalone校验生效值不要只相信“我改了文件”。在 2.9.1 上我养成的经验是版本越老配置文件里废弃参数越多日志第一行的配置说明往往比文档更可信。希望帮到你。本文还有配套的精品资源点击获取