Pulsar `pulsar-admin` 详解：熟练管理集群、Broker、租户、命名空间、Topic、订阅、Schema、函数等

pulsar-admin 是 Apache Pulsar 最核心的命令行管理工具，它提供了对 Pulsar 集群几乎所有资源的管理能力，是运维、开发、调试 Pulsar 集群的“瑞士军刀”。

掌握 pulsar-admin 的使用，意味着你可以在不依赖 Web UI 的情况下，自动化、脚本化、批量管理整个 Pulsar 平台。

---

📘 Pulsar pulsar-admin 详解：熟练管理集群、Broker、租户、命名空间、Topic、订阅、Schema、函数等

---

一、pulsar-admin 概述

项目	说明
本质	Pulsar Admin REST API 的 CLI 封装
协议	HTTP/HTTPS（连接 Broker 的 8080 端口）
功能	全面管理 Pulsar 元数据与运行时状态
部署位置	通常在任意可访问 Pulsar 集群的机器上运行
权限	支持 JWT、TLS 认证，基于 RBAC 控制权限

✅ 命令格式：

pulsar-admin [options] <command> <subcommand> [args]

✅ 示例：

pulsar-admin --admin-url http://localhost:8080 tenants list

---

二、全局选项（常用）

选项	说明
--admin-url <url>	指定 Broker 的 REST 服务地址（默认 http://localhost:8080）
--auth-plugin <plugin>	认证插件（如 jwt）
--auth-params <params>	认证参数（如 token:xxx）
--verbose	输出详细信息

---

三、核心资源管理命令详解

---

1. 🌐 集群管理（Clusters）

管理 Pulsar 集群元数据，支持多集群部署。

# 列出所有集群
pulsar-admin clusters list

# 查看集群详情
pulsar-admin clusters get standalone

# 创建集群（用于多集群复制）
pulsar-admin clusters create my-cluster \
  --broker-url pulsar://broker:6650 \
  --service-url http://broker:8080

# 更新集群配置
pulsar-admin clusters update my-cluster --broker-url pulsar://new-broker:6650

🔧 用途：跨地域复制（Geo-Replication）的基础。

---

2. 🖥️ Broker 管理（Brokers）

管理 Broker 实例状态与配置。

# 列出集群中所有 Broker
pulsar-admin brokers list standalone

# 查看 Broker 元数据（包含运行时信息）
pulsar-admin brokers broker-stats

# 查看某个 Broker 上加载的 Topic
pulsar-admin brokers list-topics standalone pulsar://broker:6650

⚠️ 注意：broker-stats 需要 Prometheus 集成才能获取详细指标。

---

3. 🏢 租户管理（Tenants）

租户是最高级别的隔离单元。

# 列出所有租户
pulsar-admin tenants list

# 创建租户
pulsar-admin tenants create mycompany \
  --admin-roles admin-user,dev-team \
  --allowed-clusters cluster-a,cluster-b

# 查看租户详情
pulsar-admin tenants get mycompany

# 删除租户
pulsar-admin tenants delete mycompany

✅ --admin-roles：指定对该租户有管理权限的角色（用于 JWT 认证）。

---

4. 📁 命名空间管理（Namespaces）

命名空间是租户下的逻辑分组，是资源配置的基本单位。

# 创建命名空间
pulsar-admin namespaces create mycompany/finance

# 列出租户下所有命名空间
pulsar-admin namespaces list mycompany

# 设置存储配额（10GB）
pulsar-admin namespaces set-storage-quota mycompany/finance \
  --storage-quota-limit 10G

# 设置消息保留策略（72小时）
pulsar-admin namespaces set-retention mycompany/finance \
  --time 72h --size 10G

# 设置生产/消费速率限制
pulsar-admin namespaces set-publish-rate mycompany/finance \
  --msg-publish-rate 1000 --byte-publish-rate 10485760

# 授予角色权限
pulsar-admin namespaces grant-permission mycompany/finance \
  --role finance-team --actions produce,consume

# 查看命名空间所有策略
pulsar-admin namespaces policies mycompany/finance

---

5. 📦 Topic 管理（Topics）

Topic 是消息的逻辑通道。

# 创建非分区 Topic（通常自动创建）
pulsar-admin topics create persistent://mycompany/finance/orders

# 创建分区 Topic（4 个分区）
pulsar-admin topics create-partitioned-topic persistent://mycompany/finance/events --partitions 4

# 列出命名空间下所有 Topic
pulsar-admin topics list mycompany/finance

# 查看 Topic 统计信息（吞吐、backlog、连接数）
pulsar-admin topics stats persistent://mycompany/finance/orders

# 查看分区 Topic 的统计
pulsar-admin topics partitioned-stats persistent://mycompany/finance/events

# 删除 Topic
pulsar-admin topics delete persistent://mycompany/finance/orders

# 删除分区 Topic
pulsar-admin topics delete-partitioned-topic persistent://mycompany/finance/events

---

6. 🔄 订阅管理（Subscriptions）

管理消费者订阅状态。

# 查看 Topic 的所有订阅
pulsar-admin topics subscriptions persistent://mycompany/finance/orders

# 查看订阅的消费进度（游标位置）
pulsar-admin topics peek-messages \
  --subscription sub1 \
  --number 5 \
  persistent://mycompany/finance/orders

# 跳过消息（跳过前 100 条未确认消息）
pulsar-admin topics skip \
  --subscription sub1 \
  --count 100 \
  persistent://mycompany/finance/orders

# 清除订阅（跳过所有消息）
pulsar-admin topics clear-backlog \
  --subscription sub1 \
  persistent://mycompany/finance/orders

# 重置消费游标（回溯到指定时间）
pulsar-admin topics reset-cursor \
  --subscription sub1 \
  --time "2024-01-01T00:00:00Z" \
  persistent://mycompany/finance/orders

✅ reset-cursor 是调试、数据修复的利器。

---

7. 🧱 Schema 管理（Schemas）

管理 Topic 的数据结构契约。

# 查看 Topic 的 Schema
pulsar-admin schemas get my-topic

# 上传 Schema（JSON/Avro）
pulsar-admin schemas upload my-topic --filename user-schema.json

# 删除 Schema（恢复为 bytes）
pulsar-admin schemas delete my-topic

# 强制覆盖 Schema（危险）
pulsar-admin schemas upload my-topic --force --filename new-schema.json

✅ 建议：生产环境预注册 Schema，禁用自动上传。

---

8. 📦 函数管理（Functions）（Pulsar Functions）

管理轻量级流处理函数（类似 Serverless）。

# 列出所有函数
pulsar-admin functions list

# 获取函数详情
pulsar-admin functions get --tenant public --namespace default --name my-function

# 创建函数（Java 示例）
pulsar-admin functions create \
  --jar target/my-function.jar \
  --classname com.example.MyFunction \
  --inputs persistent://public/default/in-topic \
  --output persistent://public/default/out-topic \
  --name my-function

# 更新函数
pulsar-admin functions update --name my-function --parallelism 2

# 删除函数
pulsar-admin functions delete --name my-function

# 触发函数（测试用）
pulsar-admin functions trigger --name my-function --data "hello"

# 查看函数日志
pulsar-admin functions get-status --name my-function

✅ Pulsar Functions 支持 Java、Python、Go。

---

四、高级管理命令

1. 🔁 Ledger 滚动（强制）

# 触发 ManagedLedger 滚动（创建新 Ledger）
pulsar-admin topics trigger-managed-ledger-rollover my-topic

用于测试 Ledger 切换或释放旧日志文件。

---

2. 🧹 资源清理

# 清理未使用的命名空间策略
pulsar-admin namespaces clear-backlog --subscription sub1 my-topic

# 删除死信队列（需先清除 backlog）
pulsar-admin topics delete persistent://mycompany/dlq/order-failed

---

3. 📊 监控与诊断

# 查看 Broker 运行时指标（需 Prometheus）
pulsar-admin brokers broker-stats

# 查看 Topic 的精确 backlog
pulsar-admin topics stats --subscription sub1 my-topic

---

五、最佳实践建议

实践	建议
✅ 脚本化常用操作	如创建租户/命名空间的 shell 脚本
✅ 权限最小化	非管理员禁用 delete、reset-cursor 等危险操作
✅ 结合 jq 解析 JSON 输出	pulsar-admin topics stats topic -w | jq .
✅ 记录操作日志	所有 pulsar-admin 操作建议记录审计日志
✅ 生产环境使用 JWT 认证	避免明文密码
✅ 避免频繁创建/删除 Topic	影响 ZooKeeper 性能
✅ 定期查看 backlog	防止消息堆积

---

六、常用命令速查表

资源	常用命令
集群	clusters list, clusters create
Broker	brokers list, brokers broker-stats
租户	tenants list, tenants create
命名空间	namespaces create, set-storage-quota, grant-permission
Topic	topics list, create-partitioned-topic, stats
订阅	topics subscriptions, reset-cursor, clear-backlog
Schema	schemas get, upload, delete
函数	functions list, create, update, trigger

---

✅ 总结

工具	作用	类比
pulsar-admin	全量管理工具：集群、租户、Topic、订阅、Schema、函数等	≈ Kubernetes 的 kubectl

📌 一句话总结：

pulsar-admin 是 Pulsar 的“控制台” —— 熟练掌握它，你就能像“数据库管理员”一样，对 Pulsar 集群进行精细化、自动化、可审计的管理。