Apache Pulsar 消息队列的多租户架构

FreeGuideOnline 最新 2026-07-10

Apache Pulsar 多租户架构：从概念到实践

Apache Pulsar 从设计之初就原生支持多租户，这使得单个 Pulsar 集群可以安全、高效地被多个团队、应用或业务线共享。本教程将带你系统性地理解 Pulsar 的多租户模型，并上手进行配置与管理。

为什么需要多租户

在消息系统中，多租户指同一套基础设施服务多个独立“租户”的能力。对开发者而言，它带来的直接好处包括：

强隔离性：租户之间的数据、元数据与认证完全隔离，一个租户的故障不会波及他人。
精细化管理：可以按租户施加存储配额、消息 TTL、限流等策略，实现资源管控。
简化运维：只需维护一个集群即可满足不同部门或项目需求，降低硬件与管理成本。
安全保障：基于租户分配权限，确保只有授权主体才能生产或消费指定消息。

Pulsar 通过层次化的逻辑组织模型来落地多租户，接下来我们逐层解析。

多租户模型的三层结构

Pulsar 的逻辑隔离结构自顶向下分为 租户（Tenant） 、命名空间（Namespace） 和 主题（Topic）。

租户 —— 顶级隔离单元

租户是多租户架构的最顶层容器，代表一个组织、团队或大型应用。它的核心职责是：

承载一组命名空间，并通过集群划定数据存储的物理范围。
配置权限，决定哪些角色可以进行创建命名空间、查看统计等管理操作。
可以跨多个数据中心（Pulsar 实例）存在，但实际隔离仍以允许的集群为单位。

一个租户只能操作其内部资源，不同租户的主题完全不可见，即使主题名相同也不会冲突。

命名空间 —— 策略与管理单元

命名空间位于租户之下，是对一组主题进行统一管理的逻辑组。你可以将它看作一个“文件夹”，里面存放着功能或领域相近的主题。命名空间的核心能力包括：

策略配置：设置消息保留策略（如存储大小、时间）、数据持久化副本数、消息去重、限流等。这些策略会应用于命名空间内的所有主题。
跨集群复制：可以在创建命名空间时指定需复制的目标集群列表，实现数据在多个数据中心同步。
隔离与资源共享：同一命名空间的 Topic 默认共享底层存储段（Ledger），但可以通过策略隔离。
清理与生命周期管理：支持一次性截断或删除整个命名空间下的所有主题。

所有主题都必须归属于某个命名空间，因此你无法在租户下直接创建“游离”的主题。

主题 —— 消息的实际载体

主题是消息存储与消费的最小单元，遵循 {persistent|non-persistent}://tenant/namespace/topic-name 的完整路径格式。在生成者或消费者眼里，只需指定这个完整路径就能唯一定位到消息管道，多租户的权限校验和路由也会基于该路径自动完成。

三层结构的完整路径示例：

persistent://my-company/inventory-service/stock-updates

其中 my-company 是租户，inventory-service 是命名空间，stock-updates 是主题名。前缀 persistent 表示消息持久化到磁盘，non-persistent 则为非持久化模式。

多租户下的资源隔离与存储

理解逻辑隔离后，还需要了解实际存储是如何支持多租户的，这关系到性能与稳定性。

BookKeeper 分层：Pulsar 使用 Apache BookKeeper 存储消息数据。BookKeeper 不会为每个租户单独创建物理存储卷，而是在 Ledger 级别进行逻辑隔离。各个租户的 Ledger 混合存储在同一套 BookKeeper 集群中，但元数据和路径上完全隔离，确保了性能的弹性。
Broker 无状态服务：Pulsar Broker 不保存持久化数据，只是基于租户/命名空间的路径将请求路由到 BookKeeper。因此，单个 Broker 可以同时处理来自多个租户的连接，计算资源天然共享但通过所有权映射防止混乱。
存储配额与流控：你可以在命名空间级别设置 backlog-quota 来限制租户可使用的缓存及存储上限，防止某个租户过度消费系统资源。同时，也可配置 publish-rate 和 dispatch-rate 实现生产者/消费者端的速率控制。

动手实践：创建与管理租户和命名空间

假设你已有一个可运行的 Pulsar 集群，我们将通过 pulsar-admin 命令行工具来完成多租户搭建。以下示例中的 pulsar-admin 需连接至目标集群，通常默认连接 localhost:6650，请根据实际地址调整。

1. 创建租户

创建一个名为 ecommerce 的租户，并允许其使用 standalone 集群（单机开发环境常用）以及赋予管理员角色。

pulsar-admin tenants create ecommerce \
  --allowed-clusters standalone \
  --admin-roles admin

参数说明：

--allowed-clusters：指定此租户可使用的集群列表，以逗号分隔。
--admin-roles：授予管理该租户资源的角色（多个角色用逗号分隔）。

2. 查看租户信息

pulsar-admin tenants get ecommerce

输出示例：

{
  "allowedClusters" : [ "standalone" ],
  "adminRoles" : [ "admin" ]
}

3. 在租户下创建命名空间

为 ecommerce 租户创建名为 orders 的命名空间，并设置消息保留策略（保留 100GB 或 2 天，以先达到者为准）。

pulsar-admin namespaces create ecommerce/orders \
  --clusters standalone

设置保留策略：

pulsar-admin namespaces set-retention ecommerce/orders \
  --size 100G \
  --time 2d

如需配置消息 TTL（未被确认的消息将在 1 小时后自动丢弃）：

pulsar-admin namespaces set-message-ttl ecommerce/orders \
  --messageTTL 3600

4. 验证命名空间策略

pulsar-admin namespaces policies ecommerce/orders

你将看到刚才设置的保留、TTL 等策略已生效。

5. 创建主题并发送消息

现在可以在完整路径下创建主题并进行测试。使用 Pulsar 客户端 pulsar-client 进行消费和生产：

# 在终端1启动消费者（订阅名 test-sub）
pulsar-client consume persistent://ecommerce/orders/test-topic -s "test-sub" -n 0

# 在终端2发送消息
pulsar-client produce persistent://ecommerce/orders/test-topic -m "Hello Multi-tenant"

消费者会立即收到消息，证明主题正常工作。

6. 多租户管理扩展

删除命名空间：pulsar-admin namespaces delete ecommerce/orders，会删除该命名空间下的所有主题。
删除租户：租户内必须无任何命名空间，否则会失败。需要先删除全部命名空间再执行 pulsar-admin tenants delete ecommerce。

权限授予：可为特定命名空间或主题添加生产和消费权限，例如：

pulsar-admin namespaces grant-permission ecommerce/orders \
  --role order-service \
  --actions produce,consume

提示：生产环境中你应该通过 Pulsar 的 JWT 或 OAuth2 认证后使用上述命令，并严格划分管理角色。

生产环境最佳实践

租户粒度：建议按业务部门或独立产品线划分租户，避免租户数量爆炸。一个租户内可用命名空间做进一步的环境划分（如 staging, prod）。
命名空间策略模板：为常见的消息模式创建标准策略，例如：日志类命名空间设置较低的保留时间和 TTL；核心交易类命名空间设置高副本数和强制持久化。
启用认证与授权：多租户环境中必须开启认证，并使用 adminRoles 和细粒度权限，防止越权。Pulsar 支持 TLS、JWT、OAuth2 等多种方式。
监控与计量：利用 Pulsar 的统计工具或 Prometheus 导出器监控每个租户的吞吐量、积压量和存储用量，提前发现集群热点。
跨集群复制：对于高可用需求，利用租户允许的多个集群，在命名空间级别配置异地复制，实现容灾。

总结

Apache Pulsar 通过 租户 > 命名空间 > 主题 的三层逻辑模型落地了企业级多租户架构。这种设计将隔离粒度与策略控制点完美结合：

租户是计费与权限的边界；
命名空间是策略和复制的管理单元；
主题是业务消息的最终载体。

初学者只要掌握 pulsar-admin 工具的租户与命名空间创建命令，就能快速为团队或项目开辟独立的、受控的消息环境。随着你对策略配置和认证的深入，这套多租户体系将展现出强大的灵活性和安全性，支撑起复杂的消息基础设施。