企业官网建设流程全解析

• 消息队列
• 后端
• 流处理

本文档基于 Apache Pulsar 官方文档中的裸机（Bare Metal）部署指南，系统讲解如何从零搭建一个生产级 Pulsar 集群：从环境规划、二进制包安装、ZooKeeper 与 BookKeeper 集群部署，到集群元数据初始化、Broker 启动与客户端连通性验证。读完本文，你将掌握完整的裸机部署流程、关键配置文件（conf/zookeeper.conf、conf/bookkeeper.conf、conf/broker.conf、conf/client.conf）的核心参数含义，以及如何验证集群各组件是否正常工作。

部署前须知

在动手部署之前，先了解 Pulsar 集群的整体拓扑与三个官方建议：

1. 单集群优先：单集群的 Pulsar 安装足以满足绝大多数使用场景。如果只是实验、在创业公司或单个团队中使用，官方建议直接采用单集群；只有当确实需要运行多集群 Pulsar 实例时，才参考多集群裸机部署指南。
2. 内置连接器（Pulsar IO）：如果希望在部署中使用全部内置 Pulsar IO 连接器，需要额外下载apache-pulsar-io-connectors包，并确保其安装在每个 broker 节点的 pulsar 目录下的connectors目录中（如果你为 Pulsar Functions 单独运行了 function worker 集群，则安装在每个 function-worker 节点上）。
3. 分层存储（Tiered Storage）：如果希望启用分层存储特性，需要下载apache-pulsar-offloaders包，并确保其安装在每个 broker 节点的 pulsar 目录下的offloaders目录中，具体配置可参考分层存储 cookbook。

部署一个 Pulsar 集群的整体步骤（按顺序执行）：

• 部署 ZooKeeper 集群（可选，已有集群可复用）
• 初始化集群元数据
• 部署 BookKeeper 集群
• 部署一个或多个 Pulsar Broker

部署准备

环境要求

目前 Pulsar 支持 64 位macOS、Linux和Windows。使用 Pulsar 需要安装 64 位 JRE/JDK 8 或更高版本。

如果你已经有现成的 ZooKeeper 集群并希望复用，则无需为运行 ZooKeeper 准备机器。

裸机部署 Pulsar 的推荐硬件规划：

• 至少6 台 Linux 机器或虚拟机（VM）：
  • 3 台运行 ZooKeeper
  • 3 台运行一个 Pulsar broker 以及一个 BookKeeper bookie
• 一个覆盖所有 Pulsar broker 主机的单一 DNS 名称

如果机器数量不足，或只是想以集群模式试用 Pulsar（后续再扩容），也可以把 Pulsar 部署在单台节点上——zookeeper、bookie 和 broker 运行在同一台机器中。

集群中的每台机器都需要安装Java 8 或更高版本。

下图展示了基本的部署拓扑：

图中，客户端通过一个单一 URL（示例中为pulsar-cluster.acme.com）与 Pulsar 集群通信，该 URL 抽象了所有处理消息的 broker。Pulsar broker 与 BookKeeper bookie 运行在同一批机器上；broker 和 bookie 又都依赖 ZooKeeper 完成协调与元数据管理。

硬件选型建议

做容量规划时，以下基本建议可供参考。

ZooKeeper

运行 ZooKeeper 的机器建议使用较轻量的机型或 VM。Pulsar 只在周期性协调与配置相关任务中使用 ZooKeeper，不用于基本的数据读写操作。例如在 Amazon Web Services（AWS）上，一个 t2.small 实例通常就足够了。

Bookie 与 Broker

运行 bookie 和 Pulsar broker 的机器建议使用性能更强的机型。例如在 AWS 上，i3.4xlarge 实例可能是合适的。这些机器上还建议：

• 快速的 CPU 和 10Gbps NIC（供 Pulsar broker 使用）
• 小而快的固态硬盘（SSD），或带 RAID 控制器和电池供电写缓存（battery-backed write cache）的机械硬盘（HDD）（供 BookKeeper bookie 使用）

安装 Pulsar 二进制包

你需要在集群中的每台机器上都安装 Pulsar 二进制包，包括运行 ZooKeeper 和 BookKeeper 的机器。

开始裸机部署前，需要通过以下方式之一下载二进制 tarball 发布包：

• 点击下面的链接直接触发下载（对应 Pulsar 发布版本）：
  • Pulsar 二进制发布包
• 从 Pulsar 官方下载页面下载
• 从 Pulsar 的 GitHub releases 页面下载最新版本
• 使用 wget 下载：

$ wget https://archive.apache.org/dist/pulsar/pulsar-2.3.0/apache-pulsar-2.3.0-bin.tar.gz

说明：当前仓库是 Apache Pulsar 2.3.0 版本的镜像，上例以 2.3.0 为例；实际操作时请以你选定的具体发布版本号为准，替换文件名中的版本号即可。

下载 tarball 后，解压并进入生成的目录：

$ tar xvzf apache-pulsar-2.3.0-bin.tar.gz $ cd apache-pulsar-2.3.0

解压后的目录包含以下子目录：

在当前仓库中，这些配置文件与目录结构可以一一对应：conf/zookeeper.conf、conf/bookkeeper.conf、conf/broker.conf、conf/client.conf都位于仓库根目录的 conf 目录下，bin目录下的 CLI 工具源码则分布在 pulsar-client-tools、pulsar-broker 等模块中。

安装内置连接器（可选）

自2.1.0-incubating版本起，Pulsar 单独发布一个包含全部builtin连接器的二进制发行版。如果需要启用这些builtin连接器，按下面的说明操作；否则可以跳过本节。

使用内置连接器前，需要在每个 broker 节点上以下列方式之一下载连接器 tarball：

• 点击链接从 Apache 镜像下载连接器发布包

• 从 Pulsar 官方下载页面下载

• 从 Pulsar 的 GitHub releases 页面下载

• 使用 wget：

  $ wget https://archive.apache.org/dist/pulsar/pulsar-2.3.0/connectors/{connector}-2.3.0.nar

nar 文件下载完成后，将其复制到 pulsar 目录下的connectors目录。例如下载了连接器文件pulsar-io-aerospike-2.3.0.nar：

$ mkdir connectors $ mv pulsar-io-aerospike-2.3.0.nar connectors $ ls connectors pulsar-io-aerospike-2.3.0.nar ...

仓库中对应的连接器实现源码可以在 pulsar-io 目录下找到，例如 pulsar-io/aerospike、pulsar-io/kafka、pulsar-io/rabbitmq 等，每个连接器最终被打包为一个独立的.nar文件。

安装分层存储 Offloaders（可选）

自2.2.0版本起，Pulsar 单独发布包含分层存储 offloaders 的二进制发行版。如果需要启用分层存储特性，按下面的说明操作；否则可以跳过本节。

使用分层存储 offloaders 前，需要在每个 broker 节点上以下列方式之一下载 offloaders tarball：

• 点击链接从 Apache 镜像下载 offloaders 发布包

• 从 Pulsar 官方下载页面下载

• 从 Pulsar 的 GitHub releases 页面下载

• 使用 wget：

  $ wget https://archive.apache.org/dist/pulsar/pulsar-2.3.0/apache-pulsar-offloaders-2.3.0-bin.tar.gz

tarball 下载完成后，在 pulsar 目录下解压 offloaders 包，并将 offloaders 复制为 pulsar 目录下的offloaders：

$ tar xvfz apache-pulsar-offloaders-2.3.0-bin.tar.gz // 在 pulsar 目录中会找到一个名为 `apache-pulsar-offloaders-2.3.0` 的目录 // 然后复制 offloaders $ mv apache-pulsar-offloaders-2.3.0/offloaders offloaders $ ls offloaders tiered-storage-jcloud-2.3.0.nar

分层存储特性的详细配置方式，可参考分层存储 cookbook。仓库中分层存储的实现位于 tiered-storage 目录（包括 tiered-storage/jcloud 和 tiered-storage/file-system），offloaders 的打包配置在 distribution/offloaders 模块中。

部署 ZooKeeper 集群

如果你已经有现成的 ZooKeeper 集群并希望复用，可以跳过本节。

ZooKeeper 为 Pulsar 管理一系列关键的协调与配置相关任务。部署 Pulsar 集群需要先于所有其他组件部署 ZooKeeper。官方推荐部署一个 3 节点的 ZooKeeper 集群。由于 Pulsar 对 ZooKeeper 的使用并不重，运行 ZooKeeper 使用较轻量的机器或 VM 即可。

首先，将所有 ZooKeeper 服务器添加到 Pulsar 目录下 conf/zookeeper.conf（对应官方配置参考中的 zookeeper 一节）指定的配置中。示例：

server.1=zk1.us-west.example.com:2888:3888 server.2=zk2.us-west.example.com:2888:3888 server.3=zk3.us-west.example.com:2888:3888

如果只有一台机器部署 Pulsar，只需在配置文件中添加一条 server 条目。

仓库中的 conf/zookeeper.conf 还给出了 ZooKeeper 的核心基础参数（部署时可结合调整）：

• tickTime=2000：每个 tick 的毫秒数，是 ZooKeeper 中最基本的时间单元；
• initLimit=10：初始同步阶段最多可经过的 tick 数；
• syncLimit=5：请求发送到得到确认之间最多可经过的 tick 数；
• dataDir=data/zookeeper：快照存储目录，即默认的myid文件所在位置；
• clientPort=2181：客户端连接端口；
• admin.serverPort=9990：ZooKeeper admin 服务器端口；
• autopurge.snapRetainCount=3与autopurge.purgeInterval=1：快照自动清理策略（保留数量与清理间隔小时数）；
• metricsProvider.httpPort=8000：Prometheus 指标导出端口。

在每个主机上，需要在各节点的myid文件中指定该节点的 ID，该文件默认位于每个服务器的data/zookeeper目录下（可通过dataDir参数修改）。

关于myid及更多细节，请参考 ZooKeeper 官方文档中的多服务器设置指南。

例如，在zk1.us-west.example.com这个 ZooKeeper 服务器上，可以这样设置myid：

$ mkdir -p data/zookeeper $ echo 1 > data/zookeeper/myid

在zk2.us-west.example.com上命令为echo 2 > data/zookeeper/myid，以此类推（注意server.N中的 N 与myid中的数字必须一一对应）。

当每台服务器都已写入zookeeper.conf配置并设置了相应的myid后，就可以在所有主机上使用pulsar-daemonCLI 工具（后台、nohup 方式）启动 ZooKeeper：

$ bin/pulsar-daemon start zookeeper

如果计划在同一节点上同时部署 ZooKeeper 与 bookie，需要用不同的 stats 端口启动 ZooKeeper。

使用pulsar-daemon时，可通过PULSAR_EXTRA_OPTS指定其他 stats 端口：

$ PULSAR_EXTRA_OPTS="-Dstats_server_port=8001" bin/pulsar-daemon start zookeeper

初始化集群元数据

部署完集群的 ZooKeeper 后，需要为实例中的每个集群向 ZooKeeper 写入一些元数据。该元数据只需写入一次。

可以使用pulsarCLI 工具的initialize-cluster-metadata命令初始化这些元数据。该命令可以在 ZooKeeper 集群中的任意一台机器上运行。示例：

$ bin/pulsar initialize-cluster-metadata \ --cluster pulsar-cluster-1 \ --zookeeper zk1.us-west.example.com:2181 \ --configuration-store zk1.us-west.example.com:2181 \ --web-service-url http://pulsar.us-west.example.com:8080 \ --web-service-url-tls https://pulsar.us-west.example.com:8443 \ --broker-service-url pulsar://pulsar.us-west.example.com:6650 \ --broker-service-url-tls pulsar+ssl://pulsar.us-west.example.com:6651

从上面的示例可以看出，需要指定以下参数：

从源码结构看，该命令的实现在仓库的 PulsarClusterMetadataSetup.java 中：它负责在元数据存储中写入集群级信息（如ClusterData、租户与命名空间策略、BookKeeper 流存储初始化等），是集群上电前的"一次性"引导步骤，后续所有 broker 启动时都会从元数据存储读取这些信息。

部署 BookKeeper 集群

BookKeeper 负责 Pulsar 中所有持久化数据的存储。要使用 Pulsar，需要部署一个 BookKeeper bookie 集群，官方推荐运行一个3-bookie 的 BookKeeper 集群。

BookKeeper bookie 可以使用 conf/bookkeeper.conf（对应官方配置参考中的 bookkeeper 一节）配置文件进行配置。这里最重要的步骤是确保zkServers设置为 ZooKeeper 集群的连接串。示例：

zkServers=zk1.us-west.example.com:2181,zk2.us-west.example.com:2181,zk3.us-west.example.com:2181

仓库中 conf/bookkeeper.conf 的默认值为zkServers=localhost:2181，zkTimeout=30000（ZooKeeper 客户端会话超时毫秒数），请务必按你的 ZooKeeper 集群地址修改zkServers。

修改好zkServers参数后，可以按需提供其他配置修改。可以在官方配置参考中找到完整的 BookKeeper 配置参数列表，更深入的指南建议参考 BookKeeper 官方文档。

仓库中 conf/bookkeeper.conf 里值得留意的几个默认项（部署时可结合实际调整）：

• bookiePort=3181：bookie 监听端口；
• journalDirectory=data/bookkeeper/journal：预写日志（write-ahead log）目录；
• ledgerDirectories=data/bookkeeper/ledgers：ledger 数据目录（可配置多个，用逗号分隔；理想情况下 journal 目录与 ledger 目录应分属不同磁盘设备）；
• allowLoopback=false：默认禁止使用回环接口作为主接口，VPS 环境下 hostname 解析到 127.0.0.1 时需要显式设置监听接口；
• journalSyncData=true/journalWriteData=true：默认启用 journal 数据同步与写入，以保证写入持久性；
• ledgerStorageClass=org.apache.bookkeeper.bookie.storage.ldb.DbLedgerStorage：基于 RocksDB 索引的默认 ledger 存储实现；
• statsProviderClass=org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider与prometheusStatsHttpPort=8000：Prometheus 指标导出。

在conf/bookkeeper.conf中应用好所需配置后，就可以在每台 BookKeeper 主机上启动一个 bookie。每个 bookie 既可以用 nohup 在后台启动，也可以在前台启动。

后台启动 bookie，使用pulsar-daemonCLI 工具：

$ bin/pulsar-daemon start bookie

前台启动 bookie：

$ bin/bookkeeper bookie

可以通过在 bookie 上运行 BookKeeper shell 的bookiesanity命令验证 bookie 是否正常工作：

$ bin/bookkeeper shell bookiesanity

该命令会在本地 bookie 上创建一个临时 BookKeeper ledger，写入少量条目，读回它们，最后删除该 ledger——用一次完整的写读删循环验证单台 bookie 的数据通路。

启动所有 bookie 后，可以在任意 bookie 节点上使用 BookKeeper shell 的simpletest命令验证集群中所有 bookie 都已正常运行：

$ bin/bookkeeper shell simpletest --ensemble <num-bookies> --writeQuorum <num-bookies> --ackQuorum <num-bookies> --numEntries <num-entries>

该命令会在集群上创建一个大小为num-bookies的 ledger，写入一些条目，最后删除该 ledger，从集群层面验证多 bookie 的读写与副本协调是否正常。

部署 Pulsar Broker

Pulsar broker 是 Pulsar 集群中最后需要部署的组件。broker 负责处理 Pulsar 消息并提供 Pulsar 的管理接口。官方推荐运行3 个 broker，分别部署在已经运行 BookKeeper bookie 的 3 台机器上。

配置 Broker

broker 配置中最重要的元素是确保每个 broker 都知道已部署的 ZooKeeper 集群。请确保正确设置zookeeperServers和configurationStoreServers参数。本例中只有一个集群、没有独立的 configuration store，因此configurationStoreServers指向与zookeeperServers相同的地址：

zookeeperServers=zk1.us-west.example.com:2181,zk2.us-west.example.com:2181,zk3.us-west.example.com:2181 configurationStoreServers=zk1.us-west.example.com:2181,zk2.us-west.example.com:2181,zk3.us-west.example.com:2181

还需要指定集群名称（与初始化集群元数据时提供的名称一致）：

clusterName=pulsar-cluster-1

仓库中 conf/broker.conf 里与本节相关的核心参数还包括：brokerServicePort=6650（broker 数据端口）、webServicePort=8080（HTTP 服务端口）、bindAddress=0.0.0.0与advertisedAddress（对外通告地址，默认取本机 hostname）。

单节点部署：如果在单节点集群中部署 Pulsar，需要将conf/broker.conf中的复制相关参数改为1：

# Number of bookies to use when creating a ledger managedLedgerDefaultEnsembleSize=1 # Number of copies to store for each message managedLedgerDefaultWriteQuorum=1 # Number of guaranteed copies (acks to wait before write is complete) managedLedgerDefaultAckQuorum=1

这三个参数分别控制：创建 ledger 时使用的 bookie 数量（ensemble）、每条消息存储的副本数（write quorum）、写操作完成前需要等待的确认副本数（ack quorum）。在 bookie 数量少于 3 的环境中（如单节点试运行），必须将它们都调整为1，否则 ledger 会因凑不齐写入与确认配额而无法正常创建。

启用 Pulsar Functions（可选）

如果希望启用 Pulsar Functions，可以按以下步骤操作：

1. 编辑conf/broker.conf，通过设置functionsWorkerEnabled为true来启用 function worker：

   functionsWorkerEnabled=true

2. 编辑conf/functions_worker.yml，将pulsarFunctionsCluster设置为初始化集群元数据时提供的集群名称：

   pulsarFunctionsCluster: pulsar-cluster-1

仓库中 conf/functions_worker.yml 还包含其他与 function worker 相关的关键配置，例如workerPort: 6750（function worker 服务端口）、pulsarServiceUrl: pulsar://localhost:6650与pulsarWebServiceUrl: http://localhost:8080（worker 连接 broker 的服务地址）、pulsarFunctionsNamespace: public/functions（函数元数据所在命名空间）。请根据实际环境同步修改这些地址。

启动 Broker

在 conf/broker.conf 文件中完成其他所需配置后，就可以启动 Pulsar 集群的 broker 了。与 ZooKeeper 和 BookKeeper 一样，broker 既可以在前台启动，也可以用 nohup 在后台启动。

前台启动 broker：

$ bin/pulsar broker

后台启动 broker，使用pulsar-daemonCLI 工具：

$ bin/pulsar-daemon start broker

成功启动所有计划中的 broker 后，Pulsar 集群就可以投入使用了。

连接运行中的集群

集群启动并运行后，应该能够使用 Pulsar 客户端连接它。其中一个客户端是随 Pulsar 二进制包提供的pulsar-client工具。pulsar-client可以向 Pulsar topic 发布消息和消费消息，因此提供了一种简单的方式来确认集群运行正常。

使用pulsar-client工具前，先修改二进制包中的客户端配置文件 conf/client.conf（对应官方配置参考中的 client 一节）。需要修改webServiceUrl和brokerServiceUrl的值，把默认的localhost替换为你分配给 broker/bookie 主机的 DNS 名称。示例：

webServiceUrl=http://us-west.example.com:8080/ brokerServiceurl=pulsar://us-west.example.com:6650/

注意：仓库中 conf/client.conf 的默认值分别为webServiceUrl=http://localhost:8080/和brokerServiceUrl=pulsar://localhost:6650/，并预留了 TLS 场景的写法注释（https://localhost:8443/与pulsar+ssl://localhost:6651/）。webServiceUrl用于 Pulsar REST API（管理操作），brokerServiceUrl用于 Pulsar 二进制协议（生产与消费）。

完成修改后，可以向 Pulsar topic 发布一条消息：

$ bin/pulsar-client produce \ persistent://public/default/test \ -n 1 \ -m "Hello Pulsar"

如果在初始化元数据时指定的集群名称不是pulsar-cluster-1，topic 中需要使用对应的集群名称。

这会将单条消息发布到 Pulsar topic。另外，也可以在发布消息之前，在另一个终端中按如下方式订阅该 topic：

$ bin/pulsar-client consume \ persistent://public/default/test \ -n 100 \ -s "consumer-test" \ -t "Exclusive"

消息成功发布到 topic 后，你会在标准输出中看到它：

----- got message ----- Hello Pulsar

运行 Functions 验证

如果已经启用了 Pulsar Functions，现在也可以尝试运行 Pulsar Functions。

创建一个exclamation（感叹号追加）函数exclamation：

bin/pulsar-admin functions create \ --jar examples/api-examples.jar \ --classname org.apache.pulsar.functions.api.examples.ExclamationFunction \ --inputs persistent://public/default/exclamation-input \ --output persistent://public/default/exclamation-output \ --tenant public \ --namespace default \ --name exclamation

通过触发函数来检查函数是否按预期运行：

bin/pulsar-admin functions trigger --name exclamation --trigger-value "hello world"

你会看到如下输出：

hello world!

说明：上述示例中的ExclamationFunction是一个在输入字符串末尾追加!的示例函数。仓库中的 Java 函数示例源码位于 pulsar-functions/java-examples，Python 函数示例位于 pulsar-functions/python-examples，pulsar-admin functions命令的实现位于 pulsar-client-tools 模块。触发成功意味着函数 worker、broker 与客户端链路全部打通。

小结

至此，你已经按顺序完成了 Pulsar 裸机集群部署的全部四步：部署 ZooKeeper、初始化集群元数据、部署 BookKeeper、部署 Pulsar broker，并通过pulsar-client完成了生产/消费验证，通过pulsar-admin functions trigger验证了 Pulsar Functions 链路。核心配置文件（conf/zookeeper.conf、conf/bookkeeper.conf、conf/broker.conf、conf/functions_worker.yml、conf/client.conf）与对应官方配置参考（reference-configuration、reference-cli-tools）均在仓库中可查，便于进一步深入调优。后续若要扩展，可参考多集群裸机部署指南或在生产环境接入 TLS 传输加密与分层存储能力。

• 消息队列
• 后端
• 流处理