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 將若干主題“整體”遷到新機器

準備主題列表：

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

生成候選方案并保存“當前分配（用于回滾）”與“建議分配（用于執行）”

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

執行與校驗

bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \--reassignment-json-file expand-cluster-reassignment.json --executebin/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 --executebin/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 --executebin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \--reassignment-json-file increase-replication-factor.json --verifybin/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 安全使用要點

及時清理：重分配完成務必移除 throttle，避免影響正常復制。
確保前進：若 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=...`