Kafka Topic 管理命令 kafka-topics.sh 详解

一、kafka-topics.sh 是什么？

kafka-topics.sh 是 Kafka 的 Topic 元数据管理工具，用于：

创建 Topic
查看 Topic
修改 Topic
删除 Topic
查看分区、副本、ISR 状态

本质：

👉 操作 Controller 中的 Topic Metadata

在 KRaft 模式 下：

复制代码

Client → Broker → Controller Quorum(KRaft)

不再依赖 ZooKeeper。

二、脚本位置

复制代码

$KAFKA_HOME/bin/kafka-topics.sh

例如：

复制代码

/opt/kafka/bin/kafka-topics.sh

三、连接方式（Kafka 4.x 必须理解）

✅ 新版连接参数

复制代码

--bootstrap-server

示例：

复制代码

--bootstrap-server 192.168.1.10:9092

含义：

连接任意 Broker
Broker 自动路由到 Controller

⚠️ 不再使用：

复制代码

--zookeeper   ❌ (已废弃)

四、Topic 生命周期操作（核心）

1️⃣ 查看所有 Topic

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--list

输出：

复制代码

__consumer_offsets
orders
logs

原理

Broker 请求 Controller：

复制代码

MetadataRequest → TopicList

2️⃣ 查看 Topic 详细信息 ⭐⭐⭐⭐⭐

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--describe \
--topic orders

示例输出：

复制代码

Topic: orders
PartitionCount: 3
ReplicationFactor: 2
Configs: segment.bytes=1073741824

Topic: orders  Partition: 0
Leader: 1
Replicas: 1,2
Isr: 1,2

字段详解（非常重要）

字段	含义
PartitionCount	分区数
ReplicationFactor	副本数
Leader	当前写入节点
Replicas	所有副本
ISR	同步副本集合
UnderReplicated	副本异常

ISR 是什么？

ISR = In Sync Replica

满足：

复制代码

leader HW == follower HW

才算同步。

3️⃣ 创建 Topic ⭐⭐⭐⭐⭐

基础创建

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--create \
--topic orders \
--partitions 3 \
--replication-factor 2

参数说明

参数	作用
--create	创建
--topic	topic 名
--partitions	分区数量
--replication-factor	副本数量

创建流程（KRaft）

复制代码

CLI
 ↓
Broker
 ↓
Controller 写 metadata log
 ↓
Raft 同步
 ↓
Topic 生效

⚠️ 生产建议

场景	推荐
普通业务	3 partitions
高吞吐	≥ CPU 核数
HA	replication=3

4️⃣ 创建 Topic（高级配置）

复制代码

--config cleanup.policy=compact
--config retention.ms=604800000

示例：

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--create \
--topic user-state \
--partitions 3 \
--replication-factor 3 \
--config cleanup.policy=compact

常见配置

配置	含义
cleanup.policy	delete / compact
retention.ms	保留时间
segment.bytes	segment大小
min.insync.replicas	最小ISR

5️⃣ 修改 Topic ⭐⭐⭐⭐

Kafka 只允许修改部分属性。

修改分区数（只能增加）

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--alter \
--topic orders \
--partitions 6

⚠️ 注意：

❌ 不能减少分区
会影响 key 顺序

修改配置

复制代码

kafka-configs.sh

（不是 topics.sh）

6️⃣ 删除 Topic

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--delete \
--topic orders

删除流程

复制代码

标记删除
 → Controller 更新 metadata
 → Broker 异步删除日志

不是立即删除。

五、批量操作（运维必会）

查看所有 Topic 详情

复制代码

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--describe

查找异常 Topic

复制代码

--under-replicated-partitions

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--describe \
--under-replicated-partitions

用于：

✅ 排查 broker 宕机

✅ 副本不同步

查看不可用分区

复制代码

--unavailable-partitions

六、生产级 Topic 设计原则（核心经验）

1️⃣ 分区数计算公式（经验）

复制代码

Partitions ≥ max(
    consumer实例数,
    producer吞吐需求
)

经验值：

复制代码

每分区 ≈ 10MB/s

2️⃣ 副本建议

集群规模	replication
3 broker	3
5 broker	3
≥7 broker	3~5

3️⃣ ISR 安全配置

强烈建议：

复制代码

min.insync.replicas=2
acks=all

否则可能丢数据。

七、最常见错误（90% 运维踩坑）

❌ 副本数 > broker 数

复制代码

Replication factor larger than available brokers

❌ 未开启删除

server.properties：

复制代码

delete.topic.enable=true

❌ 分区增加导致顺序错乱

key hash：

复制代码

hash(key) % partitions

改变 partitions → 路由改变。

八、Kafka Topic 操作速查表 ⭐⭐⭐⭐⭐

操作	命令
列表	`--list`
查看	`--describe`
创建	`--create`
删除	`--delete`
扩分区	`--alter --partitions`
异常检查	`--under-replicated-partitions`

九、生产环境最佳实践（专家建议）

✅ Topic 不要动态自动创建

复制代码

auto.create.topics.enable=false

✅ 提前规划 Topic：

分区数
副本
retention
compaction

✅ Topic 命名规范

复制代码

<env>.<system>.<event>

例如：

复制代码

prod.order.created
prod.iot.telemetry

十、企业级 Topic 管理流程（推荐）

复制代码

申请 Topic
   ↓
容量评估
   ↓
创建 Topic
   ↓
配置 retention
   ↓
监控 ISR
   ↓
周期审计