一、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 → TopicList2️⃣ 查看 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/s2️⃣ 副本建议
| 集群规模 | 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
↓
周期审计