Java 消息中间件 - 云原生多租户：Pulsar 保姆级全解2026

（概念 → 安装 → 配置 → 使用 → 进阶 → 黑科技 → 踩坑）一步一图一命令，全文基于 Pulsar 3.0 + JDK 17 + Spring Boot 3 实测可拷走。

阶段 0：一句话定位 Pulsar

云原生：K8s 原生设计，计算存储分离，自动扩缩容
多协议：Java(JMS)、C++、Python、Go、Kafka、AMQP、MQTT 一套 broker 搞定
多租户：namespace + role + quota，硬隔离资源 & 流量
万亿级：Segment 存储 + 分层存储，冷热分离成本低

"Kafka 的性能 + RabbitMQ 的协议 + 云原生的扩缩"

阶段 1：安装前准备------环境检查

项	要求	命令
OS	Linux kernel ≥ 4.14（CentOS 7/8、Ubuntu 18+）
JDK	≥ 11（推荐 17）	java -version
内存	开发 4 GB 即可

阶段 2：一键安装------3 命令完成

1.下载（国内镜像快）

bash 复制代码

wget https://mirrors.tuna.tsinghua.edu.cn/apache/pulsar/3.0.1/apache-pulsar-3.0.1-bin.tar.gz 
tar -xzf apache-pulsar-3.0.1-bin.tar.gz 
cd apache-pulsar-3.0.1

2.启单机（含控制台）

bash 复制代码

bin/pulsar standalone -nss

3.验证浏览器打开 http://localhost:8080 出现 Pulsar Manager 即成功。

阶段 3：目录速览------5 个文件夹看懂

目录	作用
bin	启停脚本
conf	broker、proxy、zk 配置
data	单机 zk 数据
lib	依赖 jar
instances	Functions 运行时

阶段 4：最小配置------生产必改 3 项

编辑 conf/standalone.conf（单机）或 broker.conf（集群）：

bash 复制代码

# 1. 外网 IP，Docker/NAT 必须 
advertisedAddress=192.168.1.101 
# 2. 多协议端口 
brokerServicePort=6650 webServicePort=8080 
# 3. 启用 Functions（可选） 
functionsWorkerEnabled=true

重启生效：

bash 复制代码

bin/pulsar restart

阶段 5：Spring Boot 3 最小可运行代码

依赖：

XML 复制代码

<dependency> 
  <groupId>org.apache.pulsar</groupId>
  <artifactId>pulsar-spring-boot-starter</artifactId>
  <version>3.0.1</version> 
</dependency>

yml：

XML 复制代码

spring: 
 pulsar: 
  service-url: pulsar://localhost:6650 
  consumer: 
   subscription-name: my-sub 
   subscription-type: Shared

生产者：

java 复制代码

@RestController 
class ProducerCtl { 
  @Autowired private PulsarTemplate<String> template; 

  @GetMapping("/send") 
  public String send(@RequestParam String msg) { 
    template.send("persistent://public/default/test-topic", msg); 
    return "ok"; 
  } 
}

消费者（异步，自动 ack）：

java 复制代码

@Component 
public class TestConsumer { 
  @PulsarListener(topic = "persistent://public/default/test-topic") 
  public void listen(String msg) { 
    System.out.println("收到 = " + msg); 
  } 
}

启动后访问 http://localhost:8080/send?msg=hello 控制台打印即成功。

阶段 6：多租户------硬隔离 3 层模型

XML 复制代码

租户(Tenant) → 命名空间(Namespace) → 主题(Topic)

CLI 一键创建：

bash 复制代码

# 创建租户 
bin/pulsar-admin tenants create mytenant --allowed-clusters standalone 
# 创建命名空间 
bin/pulsar-admin namespaces create mytenant/myns 
# 创建主题 
bin/pulsar-admin topics create persistent://mytenant/myns/test-topic

Spring 指定租户/空间：

java 复制代码

@PulsarListener(topic = "persistent://mytenant/myns/test-topic") 
public void listen(String msg) { ... }

配额控制（硬隔离）：

bash 复制代码

bin/pulsar-admin namespaces set-bundle-quota mytenant/myns --type throughput --quota 1024

阶段 7：高阶功能------一条命令开启

功能	开启方式	效果
分区主题	bin/pulsar-admin topics create-partitioned topic -p 12	12 分区，秒级扩容
延迟消息	message.newMessage().value(msg).deliverAfter(5, TimeUnit.SECONDS)	5 秒后投递
Functions	bin/pulsar-admin functions create --jar xxx.jar --classname com.xxx.Fun	流计算，Serverless
分层存储	bin/pulsar-admin namespaces set-offload-threshold --size 1G	冷数据自动上云，成本 ↓80%

阶段 8：集群 & 云原生------K8s 一键部署

Helm 安装（官方 chart）：

bash 复制代码

helm repo add apache https://pulsar.apache.org/charts 
helm install pulsar apache/pulsar --set components=["broker","proxy","bookkeeper","zookeeper"] --set monitoring.enabled=true

自动扩缩：

XML 复制代码

apiVersion: autoscaling/v2 
kind: HorizontalPodAutoscaler 
metadata: 
  name: pulsar-broker-hpa 
spec: 
  scaleTargetRef: 
    apiVersion: apps/v1 
    kind: Deployment 
    name: pulsar-broker 
  minReplicas: 2 
  maxReplicas: 10 
  metrics: 
  - type: Resource 
    resource: 
      name: cpu 
      target: 
        type: Utilization 
        averageUtilization: 70

阶段 9：黑科技玩法

Kafka 协议兼容客户端改 bootstrap.servers=pulsar://ip:6650 零代码迁移。
Functions Mesh YAML 声明流处理链，自动扩缩到 0，Serverless 计费。
分层存储 + Flink 冷数据在 S3，热数据在 BookKeeper，Flink 直接读 S3，成本降 80%。
多协议网关同一条 Topic 可同时被 Kafka、MQTT、AMQP 客户端消费，协议透明。
Geo-Replication 0 RPO 跨地域双活，同步复制，故障自动切换，RPO=0。

阶段 10：踩坑 & 急救

坑	现象	急救
端口被占	启动失败	改 brokerServicePort
Bookie 磁盘满	写入阻塞	设置 diskUsageThreshold=0.95 + 分层存储
Functions 内存溢出	OOM	限制 maxRamPerInstance=512M
消费者堆积	msgBacklog 暴涨	扩容分区 + 增加实例
Geo-Replication 断网	复制 lag 无穷大	自动重试 + 降级为异步

总结口诀

"Pulsar = 云原生 + 多协议 + 分层存，租户隔离硬，分区秒扩容， Kafka 零迁移，Functions Serverless， Geo-Replication 0 RPO，监控 Lag 别停盯！"