Apache Pulsar 本地单机模式（Standalone）快速上手指南：安装、启动、收发消息与停止-平芜编程栈

消息队列
后端
流处理

【免费下载链接】pulsar

Apache Pulsar - distributed pub-sub messaging system

项目地址：https://gitcode.com/gh_mirrors/pulsar28/pulsar

本文以 Apache Pulsar 仓库中的 getting-started-standalone.md 为骨架，结合仓库内的源码（如 PulsarStandalone.java、PulsarStandaloneStarter.java）与真实配置文件（conf/standalone.conf、conf/pulsar_env.sh）展开，帮助你在本机用一条命令跑起完整的 Pulsar 单机实例，完成从下载、解压、启动、收发消息到优雅停止的全流程，并为生产集群部署打下基础。

一、Standalone 模式是什么

对于本地开发与测试，Pulsar 提供了standalone（单机）模式：你只需在一台机器上、一个终端里，就能运行起一个完整的 Pulsar 实例。

从 getting-started-standalone.md 的说明可以看到，standalone 模式把以下组件全部放进同一个 Java 虚拟机（JVM）进程中运行：

Pulsar broker：负责消息的接收、路由与投递；
BookKeeper 组件：负责消息数据的持久化存储；
RocksDB 组件：作为本地元数据存储（metadata store），替代生产环境中独立部署的 ZooKeeper。

从源码角度验证这一点：在 PulsarStandalone.java 中可以看到该进程持有PulsarService broker、PulsarAdmin admin、LocalBookkeeperEnsemble bkEnsemble、WorkerConfig workerConfig等核心对象，分别对应 broker、管理接口、本地 BookKeeper 集成与可选的 Function Worker。而 PulsarStandaloneStarter.java 会强制把元数据存储地址设置为本地zk:127.0.0.1:<port>形式，并通过config.setRunningStandalone(true)标记当前运行在 standalone 模式下。

如果目标是搭建生产环境，请阅读 Deploying a Pulsar instance（裸机部署）指南，不要在单机模式下承载生产流量。

二、系统要求

在开始安装前，请确认本机满足以下条件：

操作系统：Pulsar 支持 64 位macOS、Linux与Windows；
JDK/JRE：需要安装 64 位 JRE/JDK8 或更高版本；
JVM 位数：broker 仅支持运行在 64 位 JVM 上（32 位 JVM 无法启动 broker）；
默认内存：默认情况下，Pulsar 会为 JVM 分配2G 堆内存。

内存参数在哪里调整

默认的 2G 堆内存配置定义在 conf/pulsar_env.sh 中：

PULSAR_MEM=${PULSAR_MEM:-"-Xms2g -Xmx2g -XX:MaxDirectMemorySize=4g"}

-Xms2g -Xmx2g：JVM 堆的初始与最大大小为 2G；
-XX:MaxDirectMemorySize=4g：Netty 等使用的直接内存上限为 4G。

该变量支持被外部环境变量覆盖（脚本采用${PULSAR_MEM:-...}的默认值语法）。调整方式有两种：

直接修改conf/pulsar_env.sh中的PULSAR_MEM；

在启动前设置环境变量，例如：

$ export PULSAR_MEM="-Xms1g -Xmx1g -XX:MaxDirectMemorySize=2g"

除此之外，conf/pulsar_env.sh 还定义了 GC 参数（PULSAR_GC，默认使用 G1GC）与 GC 日志参数（PULSAR_GC_LOG，会根据 Java 8 / JDK 9+ 自动切换日志语法），这些都属于"额外传给 JVM 的选项"。

三、安装 Pulsar Standalone

3.1 下载二进制发行包

Pulsar 官方发布预编译的二进制 tarball，下载方式有以下几种：

从 Apache 镜像站下载apache-pulsar-<version>-bin.tar.gz二进制发行包（进入 Pulsar 官方 downloads 页面或 releases 页面选择对应版本）；
使用wget命令行下载（URL 以你选择的版本对应的官方下载地址为准）：
```
$ wget <pulsar-二进制发行包下载地址>
```

下载完成后，解压并进入目录：

$ tar xvfz apache-pulsar-<version>-bin.tar.gz $ cd apache-pulsar-<version>

3.2 二进制包包含哪些内容

解压后，发行包初始包含以下目录：

目录	内容
`bin`	Pulsar 的命令行工具，如`pulsar`与`pulsar-admin`
`conf`	Pulsar 的配置文件，包括 broker 配置等
`examples`	包含 Pulsar Functions 示例的 Java JAR 包
`instances`	为 Pulsar Functions 创建的运行构件（artifacts）
`lib`	Pulsar 运行所需的 JAR 文件
`licenses`	各类组件对应的`.txt`格式许可文件

另外还有两个目录是在开始运行 Pulsar 后才会创建的：

目录	内容
`data`	RocksDB 与 BookKeeper 使用的数据存储目录
`logs`	安装产生的日志目录

3.3 关于 conf 目录与 RocksDB 配置

值得特别说明的是 conf/standalone.conf —— 它是 standalone 模式的核心配置文件。standalone 使用RocksDB 作为本地元数据存储，相关配置包括：

# The metadata store URL metadataStoreUrl= # The metadata store URL for the configuration data. If empty, we fall back to use metadataStoreUrl configurationMetadataStoreUrl= brokerServicePort=6650 webServicePort=8080

metadataStoreUrl：元数据存储地址，standalone 启动器会自动将其强制覆盖为本地地址（见 PulsarStandaloneStarter.java），因此文件中保留空值即可；
brokerServicePort=6650：broker 的消息服务端口（Pulsar 协议）；
webServicePort=8080：HTTP 管理端口；
clusterName=standalone：当前集群名，standalone 模式下默认为standalone。

在 conf/standalone.conf 中还有一组 RocksDB 专属调优项：

## RocksDB specific configurations ## DbLedgerStorage uses RocksDB to store the indexes from ## (ledgerId, entryId) -> (entryLog, offset) # Size of RocksDB block-cache. For best performance, this cache # should be big enough to hold a significant portion of the index # database which can reach ~2GB in some cases # Default is to use 10% of the direct memory size dbStorage_rocksDB_blockCacheSize= # Other RocksDB specific tunables dbStorage_rocksDB_writeBufferSizeMB=4 dbStorage_rocksDB_sstSizeInMB=4 dbStorage_rocksDB_blockSize=4096

RocksDB 在 BookKeeper 的DbLedgerStorage中负责维护从(ledgerId, entryId)到(entryLog, offset)的索引映射。dbStorage_rocksDB_blockCacheSize默认取直接内存的 10%，当索引库较大（某些场景可达约 2GB）时建议调大以提升性能；RocksDB 更完整的调优参数可参考其官方选项文件示例与 tuning guide。

3.4 可选安装：内置连接器（builtin connectors）

从2.1.0-incubating版本开始，Pulsar 会单独发布一个包含全部builtin连接器的二进制发行包。如果你需要用到 Pulsar IO 连接器，按以下步骤安装：

下载pulsar-io-<connector>-<version>.nar格式的连接器文件（从 Apache 镜像、官方 downloads 页面或 releases 页面获取）；
在 pulsar 目录下创建connectors目录并把.nar文件放进去，例如 aerospike 连接器：

$ mkdir connectors $ mv pulsar-io-aerospike-<version>.nar connectors $ ls connectors pulsar-io-aerospike-<version>.nar ...

注意事项：

在裸机集群中，需要确保connectors包在每一个 broker 的 pulsar 目录下都解压一份（若 Pulsar Functions 使用独立 worker 集群，则要在每个 function-worker 的 pulsar 目录下都放一份）；
如果使用 Docker 运行 Pulsar 或以 Docker 镜像部署（如 K8S、DC/OS），可直接使用apachepulsar/pulsar-all镜像——该镜像已内置全部 builtin 连接器。

不安装连接器不影响 Pulsar 本身的运行，可跳过本步骤直接进入 3.5 或第四节启动流程。

3.5 可选安装：分层存储 offloaders（tiered storage offloaders）

从2.2.0版本开始，Pulsar 单独发布包含分层存储 offloaders的二进制发行包。如需启用分层存储能力，请在每个 broker 节点上执行：

下载并解压 offloaders tarball；
把解压出的offloaders目录复制到 pulsar 根目录：

$ tar xvfz apache-pulsar-offloaders-<version>-bin.tar.gz // 解压后在 pulsar 目录下会出现名为 apache-pulsar-offloaders-<version> 的目录 // 将其中的 offloaders 复制出来 $ mv apache-pulsar-offloaders-<version>/offloaders offloaders $ ls offloaders tiered-storage-jcloud-<version>.nar

分层存储的具体配置方法见 Tiered storage cookbook。同样的注意事项：

裸机集群中offloaders包需要解压到每个 broker 的 pulsar 目录；
Docker/K8S/DC/OS 场景可直接使用已内置 offloaders 的apachepulsar/pulsar-all镜像。

四、启动 Pulsar Standalone

4.1 前台启动

拿到最新的发行包后，使用bin目录下的pulsar命令，并指定 standalone 模式即可启动本地集群：

$ bin/pulsar standalone

启动成功后，终端会出现一系列INFO级别日志，例如：

21:59:29.327 [DLM-/stream/storage-OrderedScheduler-3-0] INFO org.apache.bookkeeper.stream.storage.impl.sc.StorageContainerImpl - Successfully started storage container (0). 21:59:34.576 [main] INFO org.apache.pulsar.broker.authentication.AuthenticationService - Authentication is disabled 21:59:34.576 [main] INFO org.apache.pulsar.websocket.WebSocketService - Pulsar WebSocket Service started

这几条日志分别表明：BookKeeper 存储容器启动成功、broker 认证服务已启动（默认关闭认证）、WebSocket 服务已就绪。至此，一个包含 broker + BookKeeper + RocksDB 的单机 Pulsar 实例已经对外服务。

从源码看，standalone 启动器还提供以下可选参数（见 PulsarStandaloneStarter.java 与 PulsarStandalone.java）：

--no-broker：只启动 BookKeeper，不启动 broker；
--only-broker：只启动 broker，不启动 BookKeeper；
二者互斥，不能同时使用。

4.2 使用要点与安全提醒

服务占用当前终端：standalone 服务运行在你的终端中并受其直接控制，需要执行其他命令时请另开一个终端窗口；
后台运行：也可以使用bin/pulsar-daemon start standalone将服务作为后台进程运行，相关命令见pulsar-daemon；
默认无安全认证：默认情况下，standalone 不配置加密、认证或授权，任何能访问该机器网络地址的远端主机都可以无授权访问。请务必阅读 Security Overview 了解如何加固你的部署；
自动创建 namespace：启动本地 standalone 集群时会自动创建一个public/defaultnamespace，该 namespace 专门用于开发测试。Pulsar 的所有 topic 都归属于某个 namespace 之下，关于 topic 的更多说明见 Topics。

五、使用 Pulsar Standalone 收发消息

Pulsar 提供名为pulsar-client的 CLI 工具，可以在运行中的集群里对 topic 执行消息的消费与生产。其底层实现位于 pulsar-client-tools，并通过--url参数指定要连接的 broker 地址（默认连接pulsar://localhost:6650）。

5.1 消费消息

使用订阅名first-subscription消费my-topic上的消息：

$ bin/pulsar-client consume my-topic -s "first-subscription"

消费成功后，pulsar-client日志中会出现如下确认信息：

22:17:16.781 [main] INFO org.apache.pulsar.client.cli.PulsarClientTool - 1 messages successfully consumed

这条日志来自 CmdConsume.java 中的LOG.info("{} messages successfully consumed", numMessagesConsumed)，其中numMessagesConsumed是本次实际消费的消息条数。

5.2 生产消息

向my-topic生产一条内容为hello-pulsar的消息：

$ bin/pulsar-client produce my-topic --messages "hello-pulsar"

发布成功后，日志中会出现：

22:21:08.693 [main] INFO org.apache.pulsar.client.cli.PulsarClientTool - 1 messages successfully produced

对应源码位于 CmdProduce.java 的LOG.info("{} messages successfully produced", numMessagesSent)。

produce子命令还支持更多参数（见 CmdProduce.java）：

-m, --messages：要发送的消息内容，与-f二选一，默认分隔符为逗号；
-f, --files：以逗号分隔的待发送文件路径列表，与-m二选一；
-n, --num-produce：消息（或文件）重复发送的次数；
-r, --rate：发送速率控制。

5.3 关于 topic 的自动创建

细心的读者会发现：在消费或生产之前，我们并没有显式创建my-topic。

这正是 Pulsar 的便捷特性之一：

对一个尚不存在的 topic 执行消费时，Pulsar 会自动创建该 topic；
对一个尚不存在的 topic 执行生产时，同样会自动创建该 topic。

因此在上面的示例中，my-topic是在第一条命令执行时被自动创建出来的。

六、停止 Pulsar Standalone

停止前台运行的 standalone 服务，直接在该终端按Ctrl+C即可。

如果服务是通过bin/pulsar-daemon start standalone在后台启动的，则使用对应命令停止：

$ bin/pulsar-daemon stop standalone

关于pulsar-daemon的更多参数说明，参见pulsar-daemon文档。从源码角度看，standalone 进程在 PulsarStandaloneStarter.java 注册了 JVM shutdown hook：进程退出时会依次停止 Function Worker（fnWorkerService.stop()）并关闭 broker（broker.close()），保证数据与元数据能够安全落盘。