Apache Iggy 常用 CLI 命令与工具详解

目标：系统讲解 Apache Iggy 0.9.0 的官方命令行工具 iggy-cli（0.14.0）的核心子命令、全局参数、登录/上下文管理与 REST API 速查，命令输入与回显均在 Ubuntu 22.04 连接 iggy-server 0.9.0 实测。文中示例账号 root/密码 q1w2e3r4。

一、环境信息

组件：Iggy CLI iggy（iggy-cli 0.14.0）连接 iggy-server 0.9.0
传输协议：TCP（默认）、QUIC、HTTP、WebSocket
默认连接：TCP 127.0.0.1:8090；HTTP http://localhost:3000
示例账号：root / q1w2e3r4（默认内置 iggy/iggy）

二、工具概览

Iggy 提供两把工具：

工具	用途	安装命令（见安装指南篇）
`iggy-server`	服务端（二进制名 `iggy-server`）	`cargo build --release -p server` 或 `cargo install iggy-server`
`iggy`	命令行客户端	`cargo install iggy-cli` 或 `cargo build --release -p iggy-cli`

CLI 顶层命令一览（iggy --help 实测）：

stream           stream operations [alias: s]
topic            topic operations [alias: t]
partition        partition operations [alias: p]
segment          segments operations [alias: seg]
ping             ping iggy server
me               get current client info
options          list the options a resource's create command accepts
stats            get iggy server statistics
snapshot         collect iggy server troubleshooting data
pat              personal access token operations
user             user operations [alias: u]
client           client operations [alias: c]
cluster          cluster operations [alias: cl]
consumer-group   consumer group operations [alias: g]
consumer-offset  consumer offset operations [alias: o]
message          message operations [alias: m]
context          context operations [alias: ctx]
login            login to Iggy server [alias: li]
logout           logout from Iggy server [alias: lo]
session          login session operations [alias: sess]

三、前置条件

iggy-server 已启动（见安装指南篇）。
iggy CLI 已安装并加入 PATH，用 --version 校验：

iggy --version

实际回显：

iggy-cli 0.14.0

首次使用需登录（见 4.3）。

四、工具详解

4.1 全局参数（连接与认证）

任一命令前可加全局参数覆盖连接与凭据（iggy --help 实测默认值）：

参数	默认值	说明
`--transport <tcp	http	quic
`--http-api-url <URL>`	`http://localhost:3000`	HTTP 传输地址
`--tcp-server-address <ADDR>`	`127.0.0.1:8090`	TCP 传输地址
`--quic-server-address <ADDR>`	`127.0.0.1:8080`	QUIC 传输地址
`--credentials-username <NAME>`	`default`	登录用户名
`--credentials-password <PASS>`	`default`	登录密码
`--tcp-reconnection-max-retries <N>`	`10`	TCP 最大重连次数
`--tcp-reconnection-interval <DUR>`	`1s`	TCP 重连间隔
`--quic-max-concurrent-bidi-streams <N>`	`10000`	QUIC 并发双工流上限
`--encryption-key <B64>`	无	消息载荷加密密钥
`--quiet`	关闭	精简输出
`--debug`	关闭	调试日志

使用方式（指定 root 账密连接 TCP）：

iggy --credentials-username root --credentials-password q1w2e3r4 ping

实际回显：

Executing ping command
Ping sequence id: 1 time: 1.05 ms

Ping statistics for 1 ping commands
min/avg/max/mdev = 1.046/1.046/1.046/0.000 ms

💡 说明：更推荐用 4.3 的 context 持久化凭据，避免每条命令带 --credentials-*。

4.2 `context`：连接上下文管理

context 把「传输方式 + 服务地址 + 凭据 + TLS」存成可命名上下文，切换后免带参数：

iggy context create root --transport tcp --tcp-server-address 127.0.0.1:8090 --username root --password q1w2e3r4

实际回显：

Executing create context root
context 'root' created successfully

iggy context list

实际回显：

Executing list contexts in table mode
+----------+
| Name     |
+==========+
| default* |
|----------|
| root     |
+----------+

切换并持久生效：

iggy context use root

实际回显：

Executing use context root
active context set to 'root'

其余：iggy context show <name>、iggy context delete <name>。

4.3 `login` / `logout` / `session`：登录会话

iggy login

默认校验当前 context 的凭据；logout 清除会话，session status 查看当前会话。

⚠️ 说明：login 不接受 --credentials-username 等参数（那里属 iggy <全局参数> login 也不支持），凭据来自已配置的 context 或默认账密。默认账密为 iggy/iggy（DEFAULT_ROOT_USERNAME/PASSWORD）。

4.4 `ping`：存活与延迟

iggy ping

实际回显：

Executing ping command
Ping sequence id: 1 time: 1.05 ms

Ping statistics for 1 ping commands
min/avg/max/mdev = 1.046/1.046/1.046/0.000 ms

可加 -c 指定次数：

iggy ping -c 3

4.5 `stream`：流管理

stream（消息分组的顶层对象，一个 stream 下含多个 topic）。ID 可用数字或名称。

创建：

iggy stream create cli-stream

实际回显：

Executing create stream with name: cli-stream and ID auto incremented
Stream with name: cli-stream and ID auto incremented created

列出：

iggy stream list

实际回显：

Executing list streams in table mode
+----+---------------------+-------------+----------+----------+--------+
| ID | Created             | Name        | Size (B) | Messages | Topics |
+=======================================================================+
| 1  | 2026-10-11 10:46:53 | cli-stream  | 0 B      | 0        | 0      |
+----+---------------------+-------------+----------+----------+--------+

查看单个：

iggy stream get cli-stream

实际回显：

Executing get stream with ID: cli-stream
+----------------------+---------------------+
| Property             | Value               |
+============================================+
| Stream ID            | 1                   |
|----------------------+---------------------|
| Created              | 2026-10-11 10:46:53 |
|----------------------+---------------------|
| Stream name          | cli-stream          |
|----------------------+---------------------|
| Stream size          | 707 B               |
|----------------------+---------------------|
| Stream message count | 3                   |
|----------------------+---------------------|
| Stream topics count  | 1                   |
+----------------------+---------------------+

更新 / 删除 / 清空：

iggy stream update cli-stream new-name
iggy stream delete 1
iggy stream purge cli-stream

4.6 `topic`：主题管理

一个 topic 属于某个 stream，含若干分区。

创建（必填顺序：stream_id、name、partitions_count、compression_algorithm；可选 message_expiry）：

iggy topic create cli-stream cli-topic 1 none

实际回显：

Executing create topic with name: cli-topic, message expiry: server_default, compression algorithm: none, max topic size: server_default in stream with ID: cli-stream
Topic with name: cli-topic, partitions count: 1, compression algorithm: none, message expiry: server_default, max topic size: server_default created in stream with ID: cli-stream

带消息过期（如 15 天）与压缩：

iggy topic create prod sensor1 2 gzip 15days

列出：

iggy topic list cli-stream

实际回显：

Executing list topics from stream with ID: cli-stream in table mode
+----+---------------------+-----------+----------+--------------------+-------------+--------------------+----------------+------------------+
| ID | Created             | Name      | Size (B) | Max Topic Size (B) | Compression | Message Expiry (s) | Messages Count | Partitions Count |
+=============================================================================================================================================+
| 0  | 2026-10-11 10:46:58 | cli-topic | 0 B      | unlimited          | none        | unlimited          | 0              | 1                |
+----+---------------------+-----------+----------+--------------------+-------------+--------------------+----------------+------------------+

其他：

iggy topic get cli-stream 0
iggy topic update cli-stream cli-topic none unlimited
iggy topic delete cli-stream 0
iggy topic purge cli-stream 0

4.7 `partition` / `segment`：分区与段

# 为 topic 增加分区（0.9.0 分区可动态 add）
iggy partition create <stream_id> <topic_id> <partitions_count>
iggy partition delete <stream_id> <topic_id> <partitions_count>
# 删除段
iggy segment delete <stream_id> <topic_id> <partition_id> <segments_count>

💡 说明：topic 的分区数在 0.9.0 支持创建后增删（partition create/delete）；segment 操作用于清理旧段。

4.8 `message`：消息读写（核心）

发送：从 stdin 逐行、或按参数多则传入。

echo "Hello, Iggy! Message one" | iggy message send cli-stream cli-topic

实际回显：

Executing send messages to topic with ID: cli-topic and stream with ID: cli-stream
Sent messages to topic with ID: cli-topic and stream with ID: cli-stream

多条并行传入：

iggy message send cli-stream cli-topic "second message" "third message"

拉取（poll / 消费）：--offset 0 从头、-m 指定条数。参数顺序为 stream topic partition：

iggy message poll --offset 0 -m 10 cli-stream cli-topic 0

实际回显：

Executing poll messages from topic ID: cli-topic and stream with ID: cli-stream
Polled messages from topic with ID: cli-topic and stream with ID: cli-stream (from partition with ID: 0)
Polled 3 messages of total size 243 B, it took 564us 503ns
+--------+----------------------------+-----------------------------------------+--------+--------------------------+
| Offset | Timestamp                  | ID                                      | Length | Payload                  |
+===================================================================================================================+
| 0      | 2026-10-11 10:47:02.187263 | 167603331125191349804615584095985243893 | 24     | Hello, Iggy! Message one |
|--------+----------------------------+-----------------------------------------+--------+--------------------------|
| 1      | 2026-10-11 10:47:02.231461 | 151198054987925377670379535202524066036 | 14     | second message           |
|--------+----------------------------+-----------------------------------------+--------+--------------------------|
| 2      | 2026-10-11 10:47:02.231461 | 230224416531780937776377550697674624071 | 13     | third message            |
+--------+----------------------------+-----------------------------------------+--------+--------------------------+

poll 其他策略：-f/--first、-l/--last、-n/--next（按消费 offset 继续）；-s/--show-headers 显示消息头；-a/--auto-commit 自动提交 offset；-o/--offset <n> 从指定 offset 开始。

⚠️ 说明：poll 不支持 --count；条数参数是 -m/--message-count，默认 1。

4.9 `consumer-group` / `consumer-offset`：消费组与消费位点

iggy consumer-group create <stream_id> <topic_id> <name>
iggy consumer-group list <stream_id> <topic_id>
iggy consumer-group get <stream_id> <topic_id> <group_id>
iggy consumer-group delete <stream_id> <topic_id> <group_id>

iggy consumer-offset get <consumer_id> <stream_id> <topic_id> <partition_id> <kind>
iggy consumer-offset set <consumer_id> <stream_id> <topic_id> <partition_id> <offset> <kind>

4.10 `user`：用户管理

iggy user create guest <password>
iggy user create guest pass --global-permissions p_msg,s_msg
iggy user list
iggy user get 0
iggy user delete <user_id>
iggy user password <user_id> <current_password> <new_password>

实际回显（user create guest pass，示意）：

Executing create user with username: guest and password: pass
User with username: guest and password: pass created

--global-permissions 取值（长短）：manage_servers/m_srv, read_servers/r_srv, manage_users/m_usr, read_users/r_usr, manage_streams/m_str, read_streams/r_str, manage_topics/m_top, read_topics/r_top, poll_messages/p_msg, send_messages/s_msg。流/TOPIC 级权限用 -s STREAM_ID:perm#TOPIC_ID:perm。

4.11 `pat`：个人访问令牌

iggy pat create my-token 30d
iggy pat list
iggy pat delete my-token

4.12 `client` / `cluster` / `stats` / `me` / `options`

iggy client list
iggy client get <client_id>
iggy cluster metadata
iggy stats
iggy me
iggy options topic

cluster metadata 实际回显（单机 leader）：

Executing get cluster metadata in table mode
Cluster name: single-node
+-----------+-----------+------+------+------+-----------+--------+---------+
| Name      | IP        | TCP  | QUIC | HTTP | WebSocket | Role   | Status  |
+===========================================================================+
| iggy-node | 127.0.0.1 | 8090 | 8080 | 3000 | 8092      | leader | healthy |
+-----------+-----------+------+------+------+-----------+--------+---------+

stats 实际回显（节选，含本机 CPU/内存/OS 实测值）：

+--------------------------+----------------------+
| Server property          | Value                |
+=================================================+
| Iggy Server PID          | 13528                |
| Iggy Server CPU Usage    | 0.0000 %             |
| Iggy Server Memory Usage | 184074240            |
| Streams Count            | 2                    |
| Topics Count             | 2                    |
| Partitions Count         | 2                    |
| Segments Count           | 2                    |
| Message Count            | 5                    |
| Clients Count            | 1                    |
| Threads Count            | 14                   |
| OS Name                  | Ubuntu               |
| OS Version               | Linux (Ubuntu 22.04) |
+--------------------------+----------------------+

me 实际回显：

Executing me command
+-----------+-----------------+
| Property  | Value           |
+=============================+
| Client ID | 18              |
|-----------+-----------------|
| User ID   | 0               |
|-----------+-----------------|
| Address   | 127.0.0.1:42144 |
|-----------+-----------------|
| Transport | TCP             |
+-----------+-----------------+

五、REST API 速查（等价 `curl` 工具）

除 CLI 外，内置 HTTP REST 同样常用（--transport http 或 curl）。注意 0.9.0 端点：

方法/路径	说明
`GET /ping`	存活，返回 `pong`
`POST /users/login`	登录（body: username/password），返回 JWT
`GET /streams`、`POST /streams`	列/建 stream
`GET /streams/{sid}`	取 stream
`POST /streams/{sid}/topics`	建 topic（body 见安装指南篇六-3）
`GET /streams/{sid}/topics`	列 topic
`POST /streams/{sid}/topics/{tid}/messages`	发消息（`?ack=replicated`）
`GET /streams/{sid}/topics/{tid}/messages`	读消息（`?partition_id&count&strategy&offset`）
`GET /stats`	服务器统计
`GET /metrics`	Prometheus 指标
`GET /ui`	Web 控制台（需 `web_ui=true`）

登录示例：

curl -s -X POST http://127.0.0.1:3000/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"root","password":"q1w2e3r4"}'

实际回显：

{"user_id":0,"access_token":{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwMWExMmE5OS1iNTBlLTcyYTYtYmU1ZS00ODM4NDcwMzEyODgiLCJpc3MiOiJpZ2d5LmFwYWNoZS5vcmciLCJhdWQiOiJpZ2d5LmFwYWNoZS5vcmciLCJzdWIiOiIwIiwiaWF0IjoxNzkxNzE2MDc4LCJleHAiOjE3OTE3MTk2NzgsIm5iZiI6MTc5MTcxNjA3OH0.X4WWu6u9AcU5sN1VeN27p_jt8xzBIWilAcF8t8PM5zk","expiry":1791719678}}

六、注意事项

大小写与别名：子命令大多有短别名（如 m=message、s=stream、p=partition）。用到 -m 时注意它是 message 的别名，但在 message poll 内 -m 是消息条数。
message poll 条数参数是 -m，不是 --count；无 --count。
ID 可用名称或数字：stream_id/topic_id 都支持按名称解析。
消息 payload 为 UTF-8 文本；二进制消息可用 --input-file/--output-file，或 CLI 从 stdin 逐行发送。
TLS/加密：需 --tcp-tls-enabled、--encryption-key 等全局参数，配合服务端 [tcp.tls]/[encryption]。
权限：非 root 用户按 global-permissions/stream-permissions 受限；root（user_id=0）全量权限。

七、常见问题

Q1：命令报「Missing iggy server credentials」？

未提供凭据。用 context（4.2）或默认 iggy/iggy；如服务端 root 已改为自定义，先 iggy context create 写入正确账密再 iggy context use。

Q2：login 报 unexpected argument ——credentials-username？

iggy login 不接收 --credentials-*。凭据来自 context；先创建/切换含正确账密的 context，再 iggy login（或不登录直接用支持凭据的命令）。

Q3：stream/topic 操作提示无权限？

确认以 root 或具备相应权限的用户连接（iggy context use root），或用 --credentials-username/-password 指定有权限账号。

Q4：poll 想读指定数量但 --count 报错？

用 -m/--message-count，如 iggy message poll --offset 0 -m 100 stream topic 0。

Q5：服务端是 iggy/iggy，我用 root/q1w2e3r4 登录失败？

初识 root 由 IGGY_ROOT_USERNAME/PASSWORD 决定；如服务器用默认启动则 root 是 iggy/iggy。登录前先确认服务器启动时设置的环境变量（见安装指南篇）。

八、参考链接

官方 CLI/协议文档：https://iggy.apache.org/docs
源码：https://github.com/apache/iggy
快速上手：https://iggy.apache.org/docs/introduction/getting-started/

Apache Iggy 常用 CLI 命令与工具详解

Apache Iggy 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、工具详解

4.1 全局参数（连接与认证）

4.2 context：连接上下文管理

4.3 login / logout / session：登录会话

4.4 ping：存活与延迟

4.5 stream：流管理

4.6 topic：主题管理

4.7 partition / segment：分区与段

4.8 message：消息读写（核心）

4.9 consumer-group / consumer-offset：消费组与消费位点

4.10 user：用户管理

4.11 pat：个人访问令牌

4.12 client / cluster / stats / me / options

五、REST API 速查（等价 curl 工具）

六、注意事项

七、常见问题

八、参考链接

4.2 `context`：连接上下文管理

4.3 `login` / `logout` / `session`：登录会话

4.4 `ping`：存活与延迟

4.5 `stream`：流管理

4.6 `topic`：主题管理

4.7 `partition` / `segment`：分区与段

4.8 `message`：消息读写（核心）

4.9 `consumer-group` / `consumer-offset`：消费组与消费位点

4.10 `user`：用户管理

4.11 `pat`：个人访问令牌

4.12 `client` / `cluster` / `stats` / `me` / `options`

五、REST API 速查（等价 `curl` 工具）