pulsar-admin 与 pulsar-client 详解

在 Apache Pulsar 中，pulsar-admin 和 pulsar-client 是两个核心的命令行工具，分别用于 集群管理 和 消息收发测试，是运维、开发、调试 Pulsar 集群的必备工具。

📘 pulsar-admin 与 pulsar-client 详解

一、pulsar-admin：集群管理工具

用途：管理 Pulsar 集群的元数据、租户、命名空间、Topic、策略、Broker 状态等。
本质：Pulsar Admin REST API 的命令行封装。

1. 基本用法

# 基本语法
pulsar-admin [options] <command> <subcommand> [args]

# 示例：连接本地 standalone 集群
pulsar-admin --admin-url http://localhost:8080 tenants list

✅ --admin-url：指向 Broker 的 HTTP 服务地址（默认 http://localhost:8080）

2. 核心命令分类与常用操作

(1) 🔹 Tenant（租户）管理

# 列出所有租户
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

(2) 🔹 Namespace（命名空间）管理

# 创建命名空间
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

# 设置生产速率限制（每秒 1000 条）
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

(3) 🔹 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

(4) 🔹 Subscription（订阅）管理

# 查看 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

(5) 🔹 Broker 与集群管理

# 查看 Broker 列表
pulsar-admin brokers list standalone

# 查看 Broker 元数据
pulsar-admin brokers broker-stats

# 查看集群列表
pulsar-admin clusters list

# 查看集群状态
pulsar-admin clusters get cluster-a

(6) 🔹 Schema 管理

# 查看 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

(7) 🔹 资源配额与策略

# 设置命名空间的去重策略
pulsar-admin namespaces set-deduplication mycompany/finance --enable

# 设置死信队列策略
pulsar-admin namespaces set-dead-letter-policy mycompany/finance \
  --maxRedeliverCount 5 \
  --deadLetterTopic dlq/finance-failed \
  --retryLetterTopic retry/finance

# 设置复制集群
pulsar-admin namespaces set-clusters mycompany/finance --clusters us-west,eu-central

二、pulsar-client：消息收发测试工具

用途：快速测试 Topic 的消息发送与接收，适合调试、压测、验证连通性。
本质：轻量级 Producer/Consumer 命令行客户端。

1. 基本用法

# 基本语法
pulsar-client [options] <command>

# 示例：连接集群
pulsar-client --url pulsar://localhost:6650 produce my-topic --messages "Hello"

✅ --url：指向 Broker 的 Pulsar 协议地址（默认 pulsar://localhost:6650）

2. 核心命令

(1) 🔸 发送消息（produce）

# 发送单条消息
pulsar-client produce my-topic --messages "Hello Pulsar"

# 发送多条消息
pulsar-client produce my-topic --messages "msg1","msg2","msg3"

# 发送带 Key 的消息（用于 Key_Shared 订阅）
pulsar-client produce my-topic \
  --messages "value" \
  --keys "user-123"

# 发送带属性的消息
pulsar-client produce my-topic \
  --messages "event" \
  --properties "type=click,version=1.0"

# 指定分区 Topic 的路由模式
pulsar-client produce my-partitioned-topic \
  --messages "test" \
  --use-v6-partitioning \
  --round-robin-messages

(2) 🔸 接收消息（consume）

# 消费消息（阻塞，按 Enter 继续）
pulsar-client consume my-topic -s my-sub --num-messages 10

# 持续消费（不自动退出）
pulsar-client consume my-topic -s my-sub -n 0

# 消费带 Key 和属性的消息
pulsar-client consume my-topic -s my-sub -r 10 --show-properties

# 从最早开始消费
pulsar-client consume my-topic -s my-sub -s earliest

⚠️ -s 有两个含义：

• --subscription-name（消费时）
• --subscription-position（如 earliest, latest）

3. 高级选项

# 压测：每秒发送 1000 条 1KB 消息，ZSTD 压缩
pulsar-client produce my-topic \
  --messages "x" \
  --size 1024 \
  --rate 1000 \
  --compression ZSTD

三、常用组合场景示例

场景 1：快速验证 Topic 连通性

# 终端 1：启动消费者
pulsar-client consume my-test-topic -s test-sub -n 0

# 终端 2：发送消息
pulsar-client produce my-test-topic --messages "Test message"

场景 2：调试消息内容

# 查看 Topic 中的前 5 条消息
pulsar-admin topics peek-messages \
  --subscription debug-sub \
  --number 5 \
  persistent://public/default/my-topic

场景 3：重置消费进度（消息重放）

# 将订阅游标重置到 1 小时前
pulsar-admin topics reset-cursor \
  --subscription batch-job \
  --time $(date -d '1 hour ago' -Iseconds) \
  persistent://mycompany/etl/data-topic

四、最佳实践建议

五、与 REST API 的关系

所有 pulsar-admin 命令都对应一个 REST 端点，例如：

pulsar-admin topics list public/default
↓↓↓
GET http://broker:8080/admin/v2/persistent/public/default

✅ 总结

📌 一句话总结：

pulsar-admin 是“管理员工具”，pulsar-client 是“开发者工具” —— 两者结合，让你既能“管好”Pulsar，也能“用好”Pulsar。