遷移手冊

# 前言

本文檔為金蝶Apusic分散式訊息佇列for Kafka（Apusic Distributed Message Queue，簡稱：ADMQ for Kafka）的遷移手冊，詳細介紹了如何將Kafka遷移到ADMQ for Kafka。

# 適用對象

本文檔適用於IT資訊化業務負責人、研發經理、軟體專案經理、軟體架構師、維運工程師。

# 相關文件

了解更多ADMQ for Kafka產品相關的資訊，請參閱以下ADMQ for Kafka產品手冊文件集：

序號 手冊文件 說明
1 金蝶Apusic分散式訊息佇列for Kafka 快速使用手冊 簡單介紹了如何快速上手使用ADMQ for Kafka。
2 金蝶Apusic分散式訊息佇列for Kafka 安裝手冊 詳細介紹如何在各作業系統上安裝ADMQ for Kafka，以及ADMQ for Kafka服務啟停等操作。
3 金蝶Apusic分散式訊息佇列for Kafka 訊息引擎使用者手冊 詳細介紹 ADMQ for Kafka 訊息引擎相關功能的使用、配置、管理及配套工具的使用方法。
4 金蝶Apusic分散式訊息佇列for Kafka 管控台使用者手冊 詳細介紹ADMQ for Kafka管控台相關功能的使用和操作說明。
5 金蝶Apusic分散式訊息佇列for Kafka 開發手冊 詳細介紹基於各開發語言進行ADMQ for Kafka客戶端應用開發的說明。
6 金蝶Apusic分散式訊息佇列for Kafka 遷移手冊 詳細介紹從Kafka遷移到ADMQ for Kafka的說明。
7 金蝶Apusic分散式訊息佇列for Kafka 維運手冊 詳細介紹ADMQ for Kafka的監控、維運、安全強化等維運說明。
8 金蝶Apusic分散式訊息佇列for Kafka 效能最佳化手冊 詳細介紹ADMQ for Kafka效能調校的說明。

# 技術支援

ADMQ for Kafka產品提供全面的技術支援服務，您可以透過以下方式獲得技術支援：

  • 網址：www.apusic.com
  • 電話：400-855-5800
  • 信箱：support@apusic.com
  • 金蝶雲社群：https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

您在取得技術支援時，請提供如下資訊：

  1. 您的姓名
  2. 公司資訊與聯絡方式
  3. 作業系統及其版本
  4. 產品版本號
  5. 出現異常及錯誤的日誌、截圖等詳細資訊

# 概述

本文檔詳細介紹將現有 Kafka 叢集遷移到 ADMQ for Kafka V2.0.6 的最佳實踐，包含相容版本、配置遷移、元資料遷移和資料遷移。

# 相容的 Kafka 版本

ADMQ for Kafka V2.0.6 相容以下版本的 Kafka：

源 Kafka 版本 相容性 說明
2.4.x 完全相容 推薦遷移版本
2.5.x 完全相容 推薦遷移版本
2.6.x 完全相容 推薦遷移版本
2.7.x 完全相容 推薦遷移版本
2.8.x 完全相容 推薦遷移版本
3.0.x 完全相容 推薦遷移版本
3.1.x 完全相容 推薦遷移版本
3.2.x 完全相容 推薦遷移版本
3.3.x 完全相容 推薦遷移版本
3.4.x 完全相容 推薦遷移版本
3.5.x 完全相容 推薦遷移版本
3.6.x 完全相容 推薦遷移版本
3.7.x 完全相容 推薦遷移版本
3.8.x 完全相容 推薦遷移版本

# 遷移策略

策略 適用場景 優點 缺點
滾動升級 同版本內小版本升級 無需停機 不適用於跨大版本
雙叢集遷移 異構叢集遷移 遷移風險低 需要雙倍資源
漸進式遷移 生產環境遷移 逐步驗證 遷移週期長

# 遷移前準備

# 1. 環境評估

# 檢查源叢集狀態
kafka/bin/kafka-broker-api-versions.sh --bootstrap-server <source-kafka>:9092

# 檢視叢集資訊
kafka/bin/kafka-topics.sh --list --bootstrap-server <source-kafka>:9092
kafka/bin/kafka-consumer-groups.sh --list --bootstrap-server <source-kafka>:9092
1
2
3
4
5
6

# 2. 資料量評估

# 檢視 Topic 數量
kafka/bin/kafka-topics.sh --list --bootstrap-server <source-kafka>:9092 | wc -l

# 檢視訊息總量
kafka/bin/kafka-run-class.sh kafka.admin.ConsumerGroupCommand \
  --bootstrap-server <source-kafka>:9092 \
  --list
1
2
3
4
5
6
7

# 3. 安裝 ADMQ

按照安裝手冊部署 ADMQ for Kafka 叢集，確保：

  • 網路與源叢集互通
  • 配置與源叢集相容的參數

# 配置遷移

# Broker 配置遷移

需要遷移的關鍵配置：

配置項 說明 遷移建議
broker.id Broker ID 保持一致或重新分配
listeners 監聽位址 根據新環境調整 IP
log.dirs 資料目錄 重新指定目錄
zookeeper.connect ADCC for zk 位址 指向新 ADCC for zk 叢集
advertised.listeners 廣播位址 配置為新叢集位址
compression.type 壓縮類型 保持原配置
log.retention.* 日誌保留 按需調整
num.partitions 預設分割區數 保持一致

# 配置映射範例

# 源叢集配置 (server.properties)
broker.id=0
listeners=PLAINTEXT://192.168.1.10:9092
log.dirs=/data/kafka
zookeeper.connect=zk1:2181,zk2:2181,zk3:2181/kafka

# ADMQ 配置 (kafka-broker.conf)
broker.id=0
listeners=PLAINTEXT://192.168.1.20:9092
log.dirs=/apusic/admq-kafka/data
zookeeper.connect=192.168.1.20:2181,192.168.1.21:2181,192.168.1.22:2181/admq
1
2
3
4
5
6
7
8
9
10
11

# JAAS 配置遷移

如果使用 SASL 認證：

# 遷移 JAAS 配置（以下密碼僅為範例，生產環境請使用強密碼）
KafkaServer {
  org.apache.kafka.common.security.plain.PlainLoginModule required
  username="admin"
  password="admin-secret"
  user_admin="admin-secret"
  user_producer="producer-secret"
  user_consumer="consumer-secret";
};
1
2
3
4
5
6
7
8
9

# 元資料遷移

# Topic 遷移

# 方法一：使用 kafka-reassign-partitions（推薦）

# 1. 產生遷移方案
kafka/bin/kafka-reassign-partitions.sh \
  --bootstrap-server <source-kafka>:9092 \
  --topics-to-move-json-file topics.json \
  --broker-list "0,1,2" \
  --generate

# topics.json 格式
{
  "topics": [{"topic": "topic1"}, {"topic": "topic2"}]
}

# 2. 執行遷移
kafka/bin/kafka-reassign-partitions.sh \
  --bootstrap-server <source-kafka>:9092 \
  --reassignment-json-file reassign.json \
  --execute

# 3. 驗證遷移進度
kafka/bin/kafka-reassign-partitions.sh \
  --bootstrap-server <source-kafka>:9092 \
  --reassignment-json-file reassign.json \
  --verify
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 方法二：匯出匯入 Topic 配置

# 匯出 Topic 配置
kafka/bin/kafka-configs.sh --bootstrap-server <source-kafka>:9092 \
  --entity-type topics \
  --entity-name my-topic \
  --describe > topic-config-backup.txt

# 在 ADMQ 中建立同名 Topic
kafka/bin/kafka-topics.sh --create \
  --bootstrap-server <admq-kafka>:9092 \
  --topic my-topic \
  --partitions 6 \
  --replication-factor 3
1
2
3
4
5
6
7
8
9
10
11
12

# ACL 遷移

# 匯出 ACL
kafka/bin/kafka-acls.sh --bootstrap-server <source-kafka>:9092 \
  --list > acls-backup.txt

# 在 ADMQ 中建立相同 ACL
kafka/bin/kafka-acls.sh --bootstrap-server <admq-kafka>:9092 \
  --add --allow-principal User:producer \
  --operation Write --topic my-topic
1
2
3
4
5
6
7
8

# 消費者群組 Offset 遷移

# 匯出消費者群組 Offset
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server <source-kafka>:9092 \
  --group my-group \
  --describe > offset-backup.txt

# 重置 Offset（適用於需要保留消費進度的場景）
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server <admq-kafka>:9092 \
  --group my-group \
  --topic my-topic \
  --reset-offsets --to-offset <offset-number> \
  --execute
1
2
3
4
5
6
7
8
9
10
11
12
13

# 資料遷移

# 使用 MirrorMaker 2 遷移

MirrorMaker 2 是 Kafka 官方推薦的資料遷移工具，支援：

  • 主題資料同步
  • ACL 同步
  • 配置同步
  • 消費者群組 Offset 同步

# 配置 MirrorMaker 2

# mm2.properties
clusters=source,target
source.bootstrap.servers=<source-kafka>:9092
target.bootstrap.servers=<admq-kafka>:9092

source->target.enabled=true
source->target.topics.regex=.*

# 內部 Topic 配置
source->target.emit.syncs.interval.seconds=60
source->target.sync.group.offsets.enabled=true
source->target.sync.group.offsets.interval.seconds=60

# 命名空間配置
source->target.renames=sourcePrefixTransformerClass=org.apache.kafka.connect.transforms.LogRename
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 啟動 MirrorMaker 2

# 使用 connect-mirror-maker.sh
kafka/bin/connect-mirror-maker.sh mm2.properties &

# 或者使用分散式模式
kafka/bin/connect-distributed.sh connect-distributed.properties
1
2
3
4
5

# 使用 Kafka Connect 遷移

// source-connector.json
{
  "name": "source-connector",
  "config": {
    "connector.class": "org.apache.kafka.connect.mirror.MirrorSourceConnector",
    "source.cluster.alias": "source",
    "target.cluster.alias": "target",
    "source.bootstrap.servers": "<source-kafka>:9092",
    "target.bootstrap.servers": "<admq-kafka>:9092",
    "topics": ".*",
    "sync.group.offsets.enabled": "true"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
# 建立 Connector
curl -X POST -H "Content-Type: application/json" \
  --data @source-connector.json \
  http://localhost:8083/connectors/
1
2
3
4

# 資料驗證

# 驗證資料完整性
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server <admq-kafka>:9092 \
  --group mirror-consumer-group \
  --describe

# 比對源叢集和目標叢集訊息數量
kafka/bin/kafka-run-class.sh kafka.tools.GetOffsetShell \
  --broker-list <source-kafka>:9092 \
  --topic my-topic \
  --time -2 | tail -1

kafka/bin/kafka-run-class.sh kafka.tools.GetOffsetShell \
  --broker-list <admq-kafka>:9092 \
  --topic my-topic \
  --time -2 | tail -1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 客戶端遷移

# 切換客戶端連線位址

將客戶端配置中的 bootstrap.servers 從源叢集位址改為 ADMQ 位址：

# 原配置
bootstrap.servers=192.168.1.10:9092,192.168.1.11:9092

# 新配置（ADMQ）
bootstrap.servers=192.168.1.20:9092,192.168.1.21:9092
1
2
3
4
5

# 程式碼層面無需修改

由於 ADMQ 完全相容 Kafka 協定，以下方面無需修改：

  • 生產者/消費者程式碼
  • 序列化/反序列化方式
  • 消費者群組管理方式
  • 主題操作方式

# 驗證客戶端遷移

# 測試生產者
kafka/bin/kafka-console-producer.sh \
  --bootstrap-server <admq-kafka>:9092 \
  --topic test-migration

# 測試消費者
kafka/bin/kafka-console-consumer.sh \
  --bootstrap-server <admq-kafka>:9092 \
  --topic test-migration \
  --from-beginning
1
2
3
4
5
6
7
8
9
10

# 遷移步驟

# 步驟 1：部署 ADMQ 叢集

按照安裝手冊完成 ADMQ 部署。

# 步驟 2：驗證叢集

# 驗證 ADMQ 叢集健康
kafka/bin/kafka-broker-api-versions.sh --bootstrap-server <admq-kafka>:9092
kafka/bin/kafka-topics.sh --create --topic test --partitions 3 --replication-factor 3
1
2
3

# 步驟 3：配置遷移

將源叢集的配置檔參數對應遷移到 ADMQ 配置中。

# 步驟 4：元資料遷移

使用工具同步 Topic、ACL、消費者群組等元資料。

# 步驟 5：資料遷移

使用 MirrorMaker 2 或 Kafka Connect 同步資料。

# 步驟 6：客戶端切換

分批將客戶端切換到 ADMQ 叢集。

# 步驟 7：驗證

  • 驗證訊息完整性
  • 驗證消費進度
  • 驗證業務功能

# 步驟 8：清理

確認遷移成功後，下線源叢集。

# 遷移風險控制

# 回滾方案

  1. 保留源叢集一段時間
  2. 客戶端配置支援快速切換
  3. 記錄關鍵配置和狀態

# 遷移窗口

資料量 預計遷移時間 說明
< 1TB 2-4 小時 小型叢集
1-10TB 4-12 小時 中型叢集
> 10TB 1-3 天 大型叢集

# 注意事項

  1. 網路頻寬：確保源叢集到 ADMQ 叢集的網路頻寬充足
  2. 磁碟空間：ADMQ 叢集需要足夠的磁碟空間儲存資料
  3. 業務離峰期：建議在業務離峰期進行資料遷移
  4. 監控告警：開啟監控告警，及時發現異常

# 常見問題

# Topic 建立失敗

原因：Topic 名稱衝突或分割區數超過 Broker 數量 解決：檢查 Topic 名稱，確保分割區數 ≤ Broker 數

# 資料同步延遲

原因：網路頻寬不足或同步任務配置不當 解決：檢查網路，增加 MirrorMaker 並發數

# 消費進度丟失

原因：未同步消費者群組 Offset 解決：啟用 sync.group.offsets.enabled 配置

# ACL 不生效

原因：ACL 配置未同步 解決：手動同步 ACL 配置

编辑页面 (opens new window)
#迁移手册

← 維運手冊→