Apache Pulsar 消息与流平台生产运维实战
Apache Pulsar 以 Broker、BookKeeper 和元数据服务分离计算与存储，支持多租户、持久 Topic、订阅、分层存储和跨地域复制。它适合消息、事件流和大规模租户平台，但组件较多，故障定位必须区分 Broker、Bookie、Ledger、元数据、Namespace Bundle、客户端和对象存储。
一、核心架构
- Broker：接收生产与消费请求，不长期保存消息；
- BookKeeper/Bookie：把消息持久化为 Ledger；
- 元数据服务：保存集群、Topic、Ledger 和协调信息；
- Proxy：可作为统一入口；
- Functions/IO：流处理和连接器；
- Tiered Storage：把旧数据卸载到对象存储。
Producer / Consumer
│
Broker / Proxy
│
Managed Ledger
│
BookKeeper + Metadata Store
└─ Tiered Storage
Broker 无状态不代表集群简单。Bookie 磁盘、Journal、Ledger 副本和元数据是数据安全核心。
二、集群规划
生产至少跨多个故障域部署 Broker、Bookie 和元数据节点。Bookie 的 Journal 与 Ledger 目录按官方建议规划独立磁盘，避免写日志和数据读取相互争抢。
容量估算：
写入带宽 × 保留时间 × 副本数
+ Ledger/索引开销
+ Compaction 与临时空间
+ 故障恢复余量
+ 分层存储缓冲
同时估算 Topic 数、分区、订阅、积压、消息大小、峰值生产/消费、确认速率和跨地域复制。大量空闲 Topic 也会消耗元数据和 Broker 资源。
三、Tenant、Namespace 与 Topic 规范
Tenant 表示组织或平台租户，Namespace 是策略与权限边界，Topic 是消息流。生产命名建议包含业务域、事件语义和版本，但不要把环境信息重复堆叠。
为 Namespace 定义：
- 允许的集群；
- Retention 与 Backlog Quota；
- TTL；
- 副本与持久化策略；
- Schema；
- Compaction；
- Offload；
- 权限；
- 速率与容量限制。
禁止所有团队使用同一个 Tenant 和超级账号。
四、分区与 Bundle
分区 Topic 提供并行度，但分区过多会增加 Broker、元数据、客户端连接和运维成本。根据目标吞吐、消费者并发和 Key 顺序要求选择分区数，并预留增长。
Namespace Bundle 决定 Topic 在 Broker 间的归属与迁移。热点 Bundle 可拆分，但频繁自动拆分和卸载会造成连接抖动。监控 Bundle 流量、Topic 数和 Broker 负载，设置合理负载均衡策略。
五、订阅类型与顺序
- Exclusive：单消费者；
- Failover：主备消费者；
- Shared：多消费者并行，不保证全局顺序；
- Key_Shared：相同 Key 路由到同一消费者，保持 Key 级顺序。
业务必须明确顺序范围、重复容忍和并发。不能既要求全局严格顺序，又要求无限横向扩展。
消费者处理成功后再 Ack。批量 Ack、Negative Ack、Ack Timeout、重试 Topic 和 Dead Letter Topic 要结合幂等设计。
六、数据持久性与 BookKeeper
Ensemble、Write Quorum 和 Ack Quorum 决定 Ledger 数据分布和确认条件。参数必须满足故障容忍并与 Bookie 数量匹配。
Bookie 监控：
- Journal 写延迟和 fsync；
- Ledger 磁盘容量、IOPS、延迟；
- Entry Log 与 GC；
- Ledger 副本不足；
- Bookie 注册与只读状态；
- 网络与请求队列；
- 磁盘坏块和文件句柄。
Bookie 故障后通过 AutoRecovery/Replication 恢复 Ledger。恢复会产生大量磁盘与网络流量，应保留余量并控制并发。
七、保留、积压与配额
Retention 保存已确认消息，Backlog 保存尚未被订阅确认的消息，两者语义不同。未消费订阅可能让积压无限增长。
每个 Namespace 应设置：
- Backlog Quota；
- Retention Size/Time；
- Message TTL；
- 未活跃订阅清理策略；
- 生产阻断或丢弃策略；
- 告警阈值。
删除订阅前确认业务不再需要消费。强行 Skip Backlog 是数据处置操作，需要审批和审计。
八、Schema 与兼容
使用 Schema Registry 管理 Avro、JSON、Protobuf 等 Schema，并设置兼容策略。生产者发布前在 CI 校验兼容，消费者要能够处理未知字段和新旧版本。
Schema 兼容不等于业务含义兼容。枚举含义、单位、时间格式和必填逻辑变化仍需契约评审。
九、分层存储
Tiered Storage 把冷 Ledger 卸载到对象存储，降低本地盘压力。设计时考虑对象存储带宽、请求费用、加密、生命周期、恢复速度和跨区域流量。
Offload 后本地数据清理前要确认对象可读。对象存储生命周期不得早于 Pulsar 保留策略。定期执行冷数据读取演练，避免只验证写入成功。
十、跨地域复制
Geo-Replication 可把 Namespace 数据复制到多个集群，用于跨地域消费或灾备。需要防止循环、带宽不足和复制积压。
规划：
- Active-Active 还是主备；
- Producer 写入入口；
- Topic 与 Namespace 创建方式；
- Schema 复制；
- 复制延迟目标；
- 故障切换后的重复消息；
- 回切与数据对账；
- 跨区域成本。
跨地域复制不是数据库级强一致，业务仍要处理重复、乱序和短时差异。
十一、客户端可靠性
生产者设置 Send Timeout、批处理、压缩、Pending Queue、路由和幂等/去重策略。消费者设置 Receiver Queue、Ack、Negative Ack、死信、重试和并发。
客户端版本与 Broker 兼容，服务发现和 TLS 地址稳定。大量客户端同时重连可能形成风暴，滚动升级和故障恢复需限速与随机退避。
十二、安全
- Broker/Proxy/Bookie 间启用 TLS；
- 使用 Token、OAuth2 或官方支持认证；
- Tenant/Namespace 最小权限；
- 管理 API 与数据面分离；
- Secret 定期轮换；
- 禁止匿名公网访问；
- 审计权限、Topic 删除、订阅跳过和策略变更；
- 对象存储和元数据服务独立保护。
十三、监控与告警
Broker：吞吐、消息率、延迟、连接、Topic、Bundle、卸载、内存和 JVM。
Bookie：Journal/Entry 延迟、磁盘、Ledger、只读、GC、复制与网络。
业务：生产失败、消费延迟、积压、未确认消息、死信、Schema 错误、复制延迟。
按 Tenant/Namespace/Topic/Subscription 聚合，避免高基数指标压垮监控系统。
十四、备份与灾难恢复
Pulsar 高副本不是备份。保护元数据、BookKeeper 数据、分层存储、Schema、Tenant/Namespace 策略、权限、配置和部署制品。
对于关键消息，结合 Geo-Replication、对象存储和业务源数据重放设计恢复。演练单 Broker、单 Bookie、多个 Bookie、元数据故障、对象存储不可用和区域切换。
恢复后验证 Topic、订阅位置、Schema、积压、重复和业务对账。
十五、升级
升级前核对 Broker、BookKeeper、元数据、Proxy、Function、Connector 和客户端兼容。先备份配置与元数据，在预生产回放真实流量。
逐组件滚动升级，保持 Quorum 与 Broker 容量，监控连接重建、Ledger、复制、积压和 Schema。跨大版本按照官方支持路径，不同时变更存储和认证架构。
十六、常见故障
Topic 积压快速增长
检查消费者存活、处理延迟、下游、订阅类型、分区和 Ack。扩容前确认不是单 Key 顺序限制。
Bookie 进入只读
检查磁盘容量、IO、Journal/Ledger 目录和阈值。保护副本后再扩容或迁移，禁止手工删除 Ledger 文件。
Broker 负载不均
检查 Bundle、热点 Topic、连接、负载均衡和卸载频率，必要时拆分 Bundle。
复制延迟
检查跨地域网络、远端 Broker、复制客户端、对象大小和积压，评估是否需要限流生产。
消息重复
确认重试、Ack 超时、Producer 重发和故障切换。消费者必须以业务键幂等。
十七、生产检查清单
- [ ] Broker、Bookie、元数据跨故障域；
- [ ] Journal 与 Ledger 磁盘规划合理；
- [ ] Tenant/Namespace 权限与配额明确；
- [ ] 分区数依据吞吐和顺序设计；
- [ ] Subscription 类型符合业务语义；
- [ ] Retention、Backlog、TTL 不会无限增长；
- [ ] Schema 兼容在 CI 校验；
- [ ] 分层存储完成冷读取演练；
- [ ] 跨地域切换与回切经过对账；
- [ ] 客户端重连具备退避；
- [ ] BookKeeper 恢复有容量余量；
- [ ] 已演练多类故障与数据恢复。
参考资料
- Apache Pulsar 官方文档：https://pulsar.apache.org/docs/
- Pulsar 架构：https://pulsar.apache.org/docs/next/concepts-architecture-overview/
- BookKeeper 管理：https://pulsar.apache.org/docs/next/administration-bk/
- Pulsar 版本：https://pulsar.apache.org/versions/