kafka-topics.sh 是什么
kafka-topics.sh 是 Kafka 自带的主题管理命令行工具，创建、列出、查看与删除主题都在它下面。创建主题时必须显式给出分区数与副本因子，否则会套用 Broker 的默认值（默认分区数常为 1），在测试与生产之间产生不可控的差异。
创建时定下的三件事
第一是分区数，它决定这个主题能有多少消费并行度；第二是副本因子，它决定能容忍几个 Broker 同时掉线；第三是主题级配置，例如保留时长与最小同步副本。分区数只能增不能减，所以创建前就要按预期峰值流量估算。
基本信息
| 工具路径 | bin/kafka-topics.sh（多数发行版同时提供 kafka-topics） |
|---|---|
| 执行位置 | 任一装有 Kafka 客户端工具的机器，无需在 Broker 本机 |
| 必填参数 | --bootstrap-server、--create、--topic |
| 常用参数 | --partitions、--replication-factor、--config、--if-not-exists |
| 权限要求 | 无鉴权时可任意创建；开启 ACL 后需要主题 Create 权限 |
典型使用场景
- 新业务上线前按预估流量创建主题，把分区数与副本因子一次性定对
- 为实时链路建独立主题，配合 retention.ms 控制历史消息保留窗口
- CI/CD 或初始化脚本里创建主题，用 --if-not-exists 保证重复执行不报错
- 账务、事件源等关键链路创建时同时设置 min.insync.replicas，保证 acks=all 真正生效
- 为临时排查流量建一个短保留主题，用完即删，避免污染集群
创建主题
创建主题
# 显式声明分区、副本与关键配置（生产推荐写法）
kafka-topics.sh --bootstrap-server broker1:9092 \
--create --topic orders \
--partitions 6 --replication-factor 3 \
--config retention.ms=604800000 \
--config min.insync.replicas=2 # 保留 7 天；至少 2 个副本写入成功才算成功
# 脚本里重复执行：主题已存在时直接跳过，不视为失败
kafka-topics.sh --bootstrap-server broker1:9092 \
--create --topic orders --if-not-exists \
--partitions 6 --replication-factor 3
# 创建后立即校验分区与副本分布是否与预期一致
kafka-topics.sh --bootstrap-server broker1:9092 --describe --topic orders关键参数取法
| 参数 | 含义 | 取值建议 |
|---|---|---|
| --partitions | 分区数，决定消费并行上限 | 按目标吞吐估算，只增不减，宁多勿少 |
| --replication-factor | 每分区副本数 | 生产用 3，且不得超过 Broker 总数 |
| retention.ms | 消息保留时长（毫秒） | 按重放需求定，默认 7 天 |
| min.insync.replicas | 写成功所需最少同步副本 | 副本为 3 时设 2，与 acks=all 配套 |
| --if-not-exists | 主题已存在时不报错 | 仅用于幂等的初始化脚本，不校验已有配置 |
分区数事后可以增加（--alter --partitions），但会把新分区加入再均衡，且无法减少；扩容前先确认消息键的分区语义不会被打破。
副本因子大于 Broker 数量会直接报错，跨机房集群还要确认 broker.rack 是否配置，否则副本可能集中在同一机架。
分区数怎么估
先估算目标吞吐：单分区在常见配置下每秒可承接数千到数万条消息，实际取决于消息大小、压缩方式与 acks 配置，必须以压测结果为准。稳妥的算法是「预期峰值吞吐 ÷ 单分区实测吞吐」再留一倍余量：分区数偏大只是多占一点元数据与文件句柄，偏小则会在业务高峰被迫扩容，而扩容会打乱既有消息键的分区归属。
创建后的常用运维动作
创建后的常用运维动作
# 增加分区：只增不减，会触发一次分区重新分配，业务高峰前完成
kafka-topics.sh --bootstrap-server broker1:9092 --alter --topic orders --partitions 12
# 排查期临时延长保留，先把历史消息留住，避免现场被清理
kafka-configs.sh --bootstrap-server broker1:9092 \
--entity-type topics --entity-name orders \
--alter --add-config retention.ms=1209600000
# 确认主题级覆盖配置最终生效值
kafka-configs.sh --bootstrap-server broker1:9092 \
--entity-type topics --entity-name orders --describe同一份创建脚本会跑在多套环境：把分区数、副本因子、保留时长抽成变量传入，避免测试与生产的分区数不一致，导致同一个消费程序在两边的并行度不同。
内部主题（__consumer_offsets、__transaction_state）由集群参数控制，不要在业务创建流程里手工建或改。