Kafka 运维实战基本操作含命令与最佳实践

1. 基础概览与工具入口

• Kafka 发行包的所有 CLI 工具均在 bin/ 目录下。
• 任何工具不带参数运行都会显示所有可用选项。
• 本文命令默认：--bootstrap-server localhost:9092；生产请替换为你的控制面或内网 VIP。

2. 主题管理（创建 / 修改 / 删除 / 命名限制）

2.1 创建主题

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

• replication-factor（副本因子） ：建议 2~3，可在不停机重启 Broker 的同时保证数据可读。
• partitions（分区数） ：决定并行度 与数据/负载可分布的最大 Broker 数（不含副本）。
• 配置覆盖 ：命令行 --config 会覆盖 Broker 的默认主题级配置（如保留时长等）。

2.2 主题命名长度限制

• 分区目录命名规则：<topic>-<partitionId>；通常文件夹名最长 255 字符。
• 假设分区数不超 100,000 （5 位），则主题名 ≤ 249 字符 （留出 - 与 5 位分区号）。

2.3 修改主题

• 增加分区（仅增不减）：

  bin/kafka-topics.sh --bootstrap-server localhost:9092 \
    --alter --topic my_topic_name --partitions 40

  ⚠️ 若你基于 hash(key) % partitions 做语义分片 ，新增分区不会重分布历史数据，可能影响消费者假设。Kafka 不会自动搬旧数据。

• 新增配置：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type topics --entity-name my_topic_name \
    --alter --add-config x=y

• 删除配置：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type topics --entity-name my_topic_name \
    --alter --delete-config x

2.4 删除主题

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --delete --topic my_topic_name

❌ 目前 Kafka 不支持减少分区数 。

🔁 调整副本因子请参考第 6.4 节「提升副本因子」。

3. 消费组可观测与管理（Consumer Groups & Share Groups）

3.1 快速查看消费位点与 Lag

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
  --describe --group my-group

输出包含：CURRENT-OFFSET / LOG-END-OFFSET / LAG / CONSUMER-ID / HOST / CLIENT-ID。

3.2 列举各类"组"

bin/kafka-groups.sh --bootstrap-server localhost:9092 --list
# 输出示例
# GROUP               TYPE      PROTOCOL
# my-consumer-group   Consumer  consumer
# my-share-group      Share     share

3.3 管理消费组（列出 / 描述 / 删除 / 重置位点）

• 列出所有消费组

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list

• 描述组（默认含 offsets）

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-group

• 查看成员

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-group --members

• 查看成员 + 分配详情

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-group --members --verbose

• 查看组状态

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-group --state

• 删除组（仅当无活动成员）

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
    --delete --group my-group --group my-other-group

🔐 使用 consumer 协议 的组需要对组订阅到的所有主题 具备 DESCRIBE 权限；classic 协议不要求。

重置位点（一次仅支持一个组）

• 支持范围：--all-topics / --topic（或 --from-file）

• 执行模式：默认预览、--execute 执行、--export 导出 CSV

• 场景举例：--to-earliest / --to-latest / --to-datetime 'YYYY-MM-DDThh:mm:ss.sss' / --shift-by n / --to-offset x / --by-duration 'PnDTnHnMnS' / --to-current

• 示例（重置到最新）：

  bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
    --reset-offsets --group my-group --topic topic1 --to-latest

3.4 管理 Share Groups（预览）

Kafka 4.1 起提供 Share Groups 预览（默认关闭），需用 kafka-features.sh 将 share.version=1 启用；详见发行说明。

• 列出

  bin/kafka-share-groups.sh --bootstrap-server localhost:9092 --list

• 描述（起始位点 / 成员 / 状态等）

  bin/kafka-share-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-share-group
  bin/kafka-share-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-share-group --members
  bin/kafka-share-groups.sh --bootstrap-server localhost:9092 \
    --describe --group my-share-group --state

• 删除主题在 share 组中的位点

  bin/kafka-share-groups.sh --bootstrap-server localhost:9092 \
    --delete-offsets --group my-share-group --topic topic1

• 删除 share 组（仅无活动成员）

  bin/kafka-share-groups.sh --bootstrap-server localhost:9092 \
    --delete --group my-share-group

🔐 管理端同样需要对组内使用的所有主题具备 DESCRIBE 权限。

👥 Share 允许多个成员共享同一分区，与传统 consumer group 的"每分区一个成员"不同。

4. 集群维护：优雅下线、Leader 平衡、机架感知

4.1 优雅下线（Graceful Shutdown）

• 作用：在计划重启时

  1. 先将日志落盘，避免重启后的日志恢复；
  2. 受控迁移该 Broker 所领导的分区到其他副本，将不可用时长压到毫秒级。

• 开关：

  controlled.shutdown.enable=true

✅ 成功前提：该 Broker 上的所有分区都存在其他存活副本（副本因子 > 1 且至少一副本在线）。

4.2 Leader 平衡（Preferred Leader）

• Kafka 维护首选副本（副本列表中越靠前越"首选"）。默认会尝试把 Leader 恢复到首选：

  auto.leader.rebalance.enable=true

• 若关闭自动平衡，可手动触发：

  bin/kafka-leader-election.sh --bootstrap-server localhost:9092 \
    --election-type preferred --all-topic-partitions

4.3 机架感知（Rack Awareness）

• 为 Broker 标注机架：

  broker.rack=my-rack-id

• 创建/修改/重分配时，Kafka 会尽量让副本跨越 min(#racks, replication-factor) 个机架；算法保证每台 Broker 承担近似相同数量的 Leader。

• 建议 ：每个机架的 Broker 数量尽量一致，否则少数机架会背更多副本，增加存储与复制开销。

5. 扩容与迁移：分区重分配全流程

新增 Broker 后不会自动承载旧分区，需分区重分配；过程由你发起，但复制与切换自动完成。

5.1 工具模式（互斥三选一）

• --generate：给定主题列表 与目标 Broker 列表，生成候选方案
• --execute：执行给定 JSON 方案
• --verify：校验上一次 --execute 的进度/结果（完成/失败/进行中）

5.2 将若干主题"整体"迁到新机器

1. 准备主题列表：

{
  "topics": [{ "topic": "foo1" }, { "topic": "foo2" }],
  "version": 1
}

2. 生成候选方案并保存"当前分配（用于回滚）"与"建议分配（用于执行）"

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --topics-to-move-json-file topics-to-move.json \
  --broker-list "5,6" --generate

3. 执行与校验

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --reassignment-json-file expand-cluster-reassignment.json --execute

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --reassignment-json-file expand-cluster-reassignment.json --verify

5.3 精细化迁移（手工编写分配）

{"version":1,"partitions":[
  {"topic":"foo1","partition":0,"replicas":[5,6]},
  {"topic":"foo2","partition":1,"replicas":[2,3]}
]}

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --reassignment-json-file custom-reassignment.json --execute

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --reassignment-json-file custom-reassignment.json --verify

5.4 下线 Broker（Decommission）

• 目前无自动 "一键下线"方案生成器；需自行列举该 Broker 上所有分区副本 ，并均衡地迁移到其他 Broker。
• 规划要点：避免把大量副本迁到同一台目标机；必要时分批分波次执行。

6. 提升副本因子（线上无感扩容可靠性）

手工指定更多副本到新的 Broker，即可在线提升副本因子：

{"version":1,"partitions":[{"topic":"foo","partition":0,"replicas":[5,6,7]}]}

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --reassignment-json-file increase-replication-factor.json --execute

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
  --reassignment-json-file increase-replication-factor.json --verify

bin/kafka-topics.sh --bootstrap-server localhost:9092 --topic foo --describe
# 观察 ReplicationFactor 与 ISR

7. 迁移限速与进度监控（Throttle & Lag）

7.1 在执行重分配时设置复制带宽上限

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --execute \
  --reassignment-json-file bigger-cluster.json \
  --throttle 50000000 \
  --replica-alter-log-dirs-throttle 100000000

• 运行中可追加执行调大限速：

  bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
    --additional --execute --reassignment-json-file bigger-cluster.json \
    --throttle 700000000

• 完成后请及时移除限速 （--verify 会帮你清理）：

  bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \
    --verify --reassignment-json-file bigger-cluster.json

7.2 验证与手工检查 throttle 配置

• Broker 级（限速值）：

  bin/kafka-configs.sh --describe --bootstrap-server localhost:9092 --entity-type brokers
  # 关注：
  # leader.replication.throttled.rate
  # follower.replication.throttled.rate
  # replica.alter.log.dirs.io.max.bytes.per.second

• Topic 级（被限速的副本集合）：

  bin/kafka-configs.sh --describe --bootstrap-server localhost:9092 --entity-type topics
  # 关注：
  # leader.replication.throttled.replicas
  # follower.replication.throttled.replicas

• 必要时可用 --alter 手动修改。

7.3 安全使用要点

1. 及时清理：重分配完成务必移除 throttle，避免影响正常复制。

2. 确保前进 ：若 max(BytesInPerSec) > throttle，复制可能追不上写入，Lag 不降；监控

   kafka.server:type=FetcherLagMetrics,name=ConsumerLag,clientId=...,topic=...,partition=...

   若无下降，调大限速。

8. 配额管理（Quotas：按用户 / client-id / 组合）

8.1 设置覆盖

• 指定 (user=user1, client-id=clientA)：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' \
    --entity-type users --entity-name user1 \
    --entity-type clients --entity-name clientA

• 仅用户：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' \
    --entity-type users --entity-name user1

• 仅 client-id：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' \
    --entity-type clients --entity-name clientA

8.2 设置默认（--entity-default）

• 用户下的默认 client-id：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' \
    --entity-type users --entity-name user1 \
    --entity-type clients --entity-default

• 默认用户：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' \
    --entity-type users --entity-default

• 默认 client-id：

  bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' \
    --entity-type clients --entity-default

8.3 查询

# 指定 (user, client-id)
bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe \
  --entity-type users --entity-name user1 \
  --entity-type clients --entity-name clientA

# 指定 user / 指定 client-id / 默认实体 / 全量列表
bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-name user1
bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type clients --entity-name clientA
bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-default
bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type clients --entity-default
bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users

9. 跨集群镜像与地理多活（Mirroring & Geo-Replication）

• Kafka 支持跨集群 / 跨机房 / 跨地域的数据流；可结合企业网络与可用区设计进行多活或异地容灾。
• 设计建议：配合主题白名单/正则 + 排除规则 、SASL/SCRAM + TLS 等安全策略与观测指标。

10. 常见风险清单（必读）

• ⛔ 不可减分区：设计初期就评估分区增长策略；语义分片要考虑"新增分区不重分布历史数据"。
• 🧯 下线前提：优雅下线需确保每个分区有其他存活副本（RF>1）。
• ⚖️ Leader 不均衡：重启后 Broker 会先当 Follower；需要开启自动平衡或手动 preferred election。
• 🛰️ Rack 规划：尽量让每个机架的 Broker 数均衡，否则复制与存储压力会偏斜。
• 🚦 Throttle 清理 ：重分配完成要立刻移除 限速；Lag 不降要检查 BytesInPerSec 与 throttle。
• 🔐 权限 ：consumer 协议的组"describe"需要对所有订阅主题 具备 DESCRIBE；权限缺失会导致组状态/位点不可见。
• 🧩 回滚准备 ：执行重分配前务必保存"当前分配 JSON"，失败可快速回滚。

11. 命令速查表（按场景）

目标	命令
创建主题	kafka-topics.sh --create --topic <t> --partitions N --replication-factor R
增分区	kafka-topics.sh --alter --topic <t> --partitions N
增/删配置	kafka-configs.sh --alter --entity-type topics --entity-name <t> --add-config/--delete-config
删主题	kafka-topics.sh --delete --topic <t>
描述消费组	kafka-consumer-groups.sh --describe --group <g>
列组成员	... --members [--verbose]
组状态	... --state
删除组	... --delete --group <g> [--group <g2>]
重置位点	... --reset-offsets --group <g> --topic <t> --to-xxx
Preferred 选主	kafka-leader-election.sh --election-type preferred --all-topic-partitions
生成重分配	kafka-reassign-partitions.sh --generate --topics-to-move-json-file ... --broker-list "..."
执行/校验重分配	... --execute / --verify --reassignment-json-file ...
迁移限速	... --throttle <B/s> --replica-alter-log-dirs-throttle <B/s>
查看 throttle（Broker/Topic）	kafka-configs.sh --describe --entity-type brokers/topics
配额设置（user/client-id）	kafka-configs.sh --alter --entity-type users/clients ... --add-config producer_byte_rate=...,consumer_byte_rate=...,request_percentage=...

12. 总结与实践建议

• 以"可观测 → 变更 → 校验 → 回滚"闭环 组织运维动作：任何重分配与限速都要有当前状态快照 与回滚 JSON。
• 把扩容当作"复制 + 切换"的受控流水线：先复制到新副本、进入 ISR，再切 Leader 与删除旧副本。
• 把消费组当作"位点与分配"的可观测对象 ：任何"延迟大"的投诉，都应先 --describe 看 LAG 与分配是否倾斜。
• 前置容量规划 ：分区与副本因子是"上限设计"，后续只能增加 （分区）或扩副本，不能"减分区"。