Pulsar Ledger Offload（冷数据归档）配置指南 详解

在 Apache Pulsar 中，Ledger Offload（账本卸载） 是一项关键的 冷数据归档机制，用于将不再频繁访问的“冷”消息从本地 BookKeeper 存储迁移到低成本、高容量的云存储系统（如 AWS S3、Google Cloud Storage、Azure Blob Storage 等），从而释放本地磁盘空间、降低存储成本，并支持长期数据保留与合规性要求。

---

📘 Pulsar Ledger Offload（冷数据归档）配置指南 详解

---

一、什么是 Ledger Offload？

• Ledger Offload 是将 Pulsar Topic 中的旧 Ledger（已关闭且不再写入）从 Bookie 节点 异步迁移到外部对象存储 的过程。
• 迁移后，原始 Ledger 在 Bookie 上的文件可被 GC 回收，释放本地磁盘。
• 消费者仍可通过 Pulsar 接口读取归档数据（自动从云存储拉回）。

✅ 类比：数据库的“冷热分离”或 Kafka 的 Tiered Storage。

---

二、为什么需要 Ledger Offload？

需求	说明
💰 降低存储成本	本地 SSD 昂贵，云存储（如 S3）便宜 10 倍以上
📈 支持长期数据保留	满足合规要求（如 7 年日志保留）
🔋 释放 Bookie 磁盘压力	防止磁盘打满导致服务中断
🧩 解决 GC 碎片问题	归档后，Entry Log 可被彻底回收
🔄 支持数据重放与审计	历史消息可随时读取

---

三、支持的 Offload 介质（Tiered Storage）

Pulsar 支持多种云存储作为归档目标：

存储类型	插件名称	说明
AWS S3	S3ManagedLedgerOffloader	最常用，支持 IAM、KMS 加密
Google Cloud Storage (GCS)	GCSOffloader	GCP 用户首选
Azure Blob Storage	AzureBlobStorageOffloader	Azure 用户
Aliyun OSS	OSSManagedLedgerOffloader	阿里云用户
FileSystem	FileManagedLedgerOffloader	本地或 NAS（测试用）

✅ 插件位于 offloaders/ 目录下，需单独下载或打包。

---

四、Offload 工作流程

1. Broker 检测到 Ledger 可归档（已关闭 + 达到策略）
   ↓
2. 调用 Offloader 插件将 Ledger 打包上传至云存储
   ↓
3. 上传成功后，更新 Ledger 元数据（ZooKeeper）
   ↓
4. Bookie 的 GC 可安全删除本地文件
   ↓
5. 消费者读取时：
   ├─ 若在本地 → 正常读取
   └─ 若已归档 → Broker 从云存储拉回并缓存

✅ 对消费者透明，无需修改代码。

---

五、配置步骤详解

第 1 步：准备 Offloader 插件

# 下载或构建 offloader 插件（以 S3 为例）
# 插件包通常为：tiered-storage-jcloud-*.nar

# 放置到 Pulsar 目录
cp tiered-storage-jcloud-*.nar $PULSAR_HOME/offloaders/

🔗 下载地址：Pulsar Offloaders

---

第 2 步：配置 broker.conf

# 启用 Offload 服务
managedLedgerOffloadEnabled=true

# 设置默认 Offloader 类型
managedLedgerOffloadDriver=s3

# Offloader 插件目录
offloadersDirectory=./offloaders

# 临时目录（用于打包）
managedLedgerOffloadThreshold=1073741824  # 1GB（达到此大小触发 offload）
managedLedgerOffloadDeletionLagMs=86400000  # 24小时（延迟删除本地数据）

# S3 配置示例
s3ManagedLedgerOffloadBucket=my-pulsar-archive
s3ManagedLedgerOffloadRegion=us-west-2
s3ManagedLedgerOffloadMaxBlockSizeInBytes=67108864  # 64MB
s3ManagedLedgerOffloadReadBufferSizeInBytes=1048576  # 1MB

# 认证方式（推荐使用 IAM Role 或 Secret）
s3ManagedLedgerOffloadAccessKey=your-access-key
s3ManagedLedgerOffloadSecretKey=your-secret-key
# 或使用 IAM Role（K8s 推荐）
# s3ManagedLedgerOffloadUseIAMRole=true

✅ 其他云存储配置类似，替换 driver 和 bucket 参数。

---

第 3 步：配置命名空间策略（可选）

可通过 pulsar-admin 为特定命名空间设置 offload 策略：

# 启用 offload
pulsar-admin namespaces set-offload-threshold my-tenant/my-namespace --size-threshold 1G

# 设置 offload 策略（S3）
pulsar-admin namespaces set-offload-policies my-tenant/my-namespace \
  --driver s3 \
  --region us-west-2 \
  --bucket my-pulsar-archive \
  --maxBlockSizeInBytes 67108864 \
  --readBufferSizeInBytes 1048576

✅ 可为不同命名空间设置不同归档策略。

---

六、触发 Offload 的方式

1. 自动触发（推荐）

• 当 Ledger 大小 ≥ managedLedgerOffloadThreshold 时自动触发。
• 通常在 Ledger 关闭后异步执行。

2. 手动触发

# 对某个 Topic 触发 offload
pulsar-admin topics offload persistent://my-tenant/my-namespace/my-topic

# 检查 offload 状态
pulsar-admin topics offload-status persistent://my-tenant/my-namespace/my-topic

输出示例：

{
  "status": "Success",
  "msg": "Offload successfully completed"
}

---

七、消费者读取归档数据

• 完全透明：消费者无需任何修改。
• 当读取已归档的 Ledger 时：
  1. Broker 检测到 Ledger 在云存储中。
  2. 从 S3/GCS 下载数据（可缓存）。
  3. 返回给消费者。

⚠️ 首次读取归档数据会有延迟（取决于网络和文件大小）。

---

八、监控与运维

1. 关键监控指标（Prometheus）

指标	说明
pulsar_broker_leger_offloader_success_count	成功 offload 次数
pulsar_broker_leger_offloader_failure_count	失败次数
pulsar_broker_leger_offloader_duration_ms	offload 耗时
bookie_disk_usage	本地磁盘使用率（应下降）

2. 常用命令

# 查看 offload 状态
pulsar-admin topics offload-status my-topic

# 列出所有 offloaded ledgers（需自定义脚本）
# 通过 ZooKeeper 查看 /ledgers/L/.../offloaded 节点

---

九、最佳实践建议

实践	建议
✅ 生产环境使用 S3/GCS/Azure	不推荐本地 FileSystem
✅ 启用 KMS 或 SSE 加密	保证归档数据安全
✅ 设置合理的 offload 阈值	如 1GB，避免频繁小文件上传
✅ 监控 offload 失败率	网络、权限问题可能导致失败
✅ 结合 TTL 策略	归档后仍可设置自动删除（如 7 年后）
✅ 为归档数据打标签	便于成本分摊和管理
✅ 测试读取性能	确保业务可接受延迟

---

十、常见问题与解决方案

问题	原因	解决方案
Offload failed: Access Denied	权限不足	检查 IAM/S3 Policy
Offload stuck	网络慢或磁盘满	检查 Bookie 磁盘、网络带宽
消费者读取慢	首次拉取归档数据	启用缓存或预加载
Offload 不触发	未达到阈值	检查 managedLedgerOffloadThreshold
本地磁盘未释放	GC 未运行	检查 managedLedgerOffloadDeletionLagMs

---

✅ 总结

特性	说明
✅ 透明归档	对生产者/消费者无感知
✅ 降低成本	本地 SSD → 云存储，成本降低 5~10 倍
✅ 支持长期保留	满足合规与审计需求
✅ 解决碎片问题	归档后 Entry Log 可被 GC 回收
✅ 多云支持	S3、GCS、Azure、OSS 等
⚠️ 首次读取延迟	需从云存储拉回数据

📌 一句话总结：

Ledger Offload 是 Pulsar 的“冷热分层存储”引擎 —— 通过将冷数据自动归档到云存储，你可以在不牺牲数据可访问性的前提下，大幅降低存储成本，实现无限数据保留。