快速操作指南

# 概述

本文檔為 ADMQ for Kafka 極簡維運手冊，涵蓋部署架構、快速安裝、常用命令、日常維運及效能調優核心內容。

# 產品簡介

# 什麼是 ADMQ for Kafka

ADMQ for Kafka（Apusic Distributed Message Queue for Kafka）是專為 Kafka 使用者打造的信創替代型雲原生訊息中介軟體，基於 Apache Kafka 3.9.1 核心建構，完全遵循 Kafka 核心架構設計與通訊協定規範，實現協定、客戶端、生態工具的全相容。

# 核心特性

特性 說明
協定完全相容 完整實現 Kafka 生產消費協定、分割區分配協定、Offset 管理協定，行為與原生 Kafka 一致
零改造替代 支援 Java、Go、Python、C++ 等 Kafka 官方客戶端，無需修改程式碼即可替換
信創適配 適配麒麟、統信等信創作業系統，相容 ARM、RISC-V 等信創晶片
高可用架構 支援多副本冗餘、故障自動轉移、水平擴展，滿足生產環境可靠性要求
生態復用 相容 Kafka Connect、MirrorMaker、Prometheus 等原生生態工具

# 適用場景

  • 信創替代：政企信創改造中直接替換原有 Kafka 叢集
  • 高吞吐資料傳輸：日誌採集、業務資料同步、即時資料管道
  • 串流資料處理：相容 Flink、Spark Streaming 等串流計算引擎
  • 系統解耦：基於發佈訂閱模式實現分散式系統間非同步通訊

# 產品組成

元件 說明 必需
Broker（核心引擎） 訊息處理與儲存核心，受 License 控制 是
ADCC for zk（分散式協調） 叢集中繼資料管理與協調 是
管控台 可視化維運管理介面 否（可選）

# 部署架構

# 單機部署

┌─────────────────────────────────────────────────────────────┐
│                      單機部署架構                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐        ┌──────────────────┐           │
│  │   客戶端應用     │        │    管控台         │           │
│  │  (Producer/     │        │  (可選元件)       │           │
│  │   Consumer)     │        │                  │           │
│  └────────┬────────┘        └────────┬─────────┘           │
│           │                          │                     │
│           │ 9092                     │ 12305               │
│           ▼                          ▼                     │
│  ┌──────────────────────────────────────────────┐         │
│  │              單台實體機/虛擬機                 │         │
│  │                                              │         │
│  │  ┌──────────────┐    ┌──────────────────┐   │         │
│  │  │  Broker      │    │   ADCC for zk    │   │         │
│  │  │ (Standalone) │    │   (內置)          │   │         │
│  │  └──────────────┘    └──────────────────┘   │         │
│  │                                              │         │
│  │  ┌──────────────────────────────────────┐   │         │
│  │  │         License 檔案                 │   │         │
│  │  └──────────────────────────────────────┘   │         │
│  └──────────────────────────────────────────────┘         │
│                                                             │
│  適用場景：開發測試環境、小規模驗證                            │
│  特點：簡單快速，無需高可用配置                                │
└─────────────────────────────────────────────────────────────┘
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# 叢集部署（建議生產環境）

┌─────────────────────────────────────────────────────────────────────────────┐
│                            叢集部署架構                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                      │
│    │  客戶端應用  │  │  客戶端應用  │  │  客戶端應用  │                      │
│    │ (Producer)  │  │ (Consumer)  │  │ (Producer)  │                      │
│    └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                      │
│           │                │                │                              │
│           └────────────────┼────────────────┘                              │
│                            │                                               │
│                            ▼ 9092                                          │
│    ┌──────────────────────────────────────────────────────────────┐       │
│    │                           Broker 叢集                        │       │
│    │                                                              │       │
│    │   ┌──────────┐        ┌──────────┐        ┌──────────┐      │       │
│    │   │ Broker 0 │◄──────►│ Broker 1 │◄──────►│ Broker 2 │      │       │
│    │   │ (Leader) │        │(Follower)│        │(Follower)│      │       │
│    │   └────┬─────┘        └────┬─────┘        └────┬─────┘      │       │
│    │        │                   │                   │             │       │
│    │        └───────────────────┼───────────────────┘             │       │
│    │                            │                                 │       │
│    │                    資料同步/副本複製                          │       │
│    └────────────────────────────┬─────────────────────────────────┘       │
│                                 │                                          │
│                                 ▼                                          │
│    ┌──────────────────────────────────────────────────────────────┐       │
│    │                  ADCC for zk 叢集（3節點）                    │       │
│    │                                                              │       │
│    │   ┌──────────┐        ┌──────────┐        ┌──────────┐      │       │
│    │   │ADCC for  │◄──────►│ADCC for  │◄──────►│ADCC for  │      │       │
│    │   │zk Node 1 │        │zk Node 2 │        │zk Node 3 │      │       │
│    │   │ (Leader) │        │(Follower)│        │(Follower)│      │       │
│    │   └──────────┘        └──────────┘        └──────────┘      │       │
│    │                                                              │       │
│    └──────────────────────────────────────────────────────────────┘       │
│                                                                              │
│    ┌──────────────────────────────────────────────────────────────┐       │
│    │                       管控台（可選）                         │       │
│    │                        埠號：12305                          │       │
│    └──────────────────────────────────────────────────────────────┘       │
│                                                                              │
│  適用場景：生產環境、高可用業務場景                                            │
│  特點：多副本冗餘、故障自動轉移、水平擴展                                      │
└─────────────────────────────────────────────────────────────────────────────┘
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# 快速安裝

# 系統要求

元件 最低要求 建議配置
作業系統 Linux (CentOS 7+, Ubuntu 18.04+, 麒麟 V10, 統信 UOS) -
CPU 4 核心 8 核心及以上
記憶體 8 GB 16 GB 及以上
磁碟空間 100 GB 500 GB 及以上 SSD

# 埠號規劃

埠號 服務 說明
9092 Broker 生產者和消費者連線
2181 ADCC for zk 客戶端連線
2888 ADCC for zk Leader 和 Follower 通訊
3888 ADCC for zk 選舉通訊
12305 管控台 Web 介面（HTTP）

# 單機安裝（5分鐘完成）

# 1. 解壓縮
mkdir -p /apusic && cd /apusic
tar zxvf ADMQ-V2.0.6.391-Kafka-20260319.tar.gz
cd admq-kafka

# 2. 配置（修改為本機 IP）
vi config/kafka-standalone.conf
# listeners=PLAINTEXT://192.168.1.10:9092

# 3. 放置 License
cp /path/to/license.xml ./

# 4. 啟動（先 ZK，後 Broker）
bin/admq-daemon start kafka zk
sleep 3
bin/admq-daemon start kafka standalone

# 5. 驗證
netstat -nltup | grep 9092
kafka/bin/kafka-topics.sh --list --bootstrap-server 192.168.1.10:9092
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 叢集安裝（3節點）

節點規劃：

節點 IP ADCC for zk MyID Broker ID
Node 1 192.168.1.10 1 0
Node 2 192.168.1.11 2 1
Node 3 192.168.1.12 3 2

各節點執行：

# 1. 解壓縮並配置
mkdir -p /apusic && cd /apusic
tar zxvf ADMQ-V2.0.6.391-Kafka-20260319.tar.gz
cd admq-kafka

# 2. 配置 ADCC for zk（所有節點相同）
cat > config/kafka-zk.conf << 'EOF'
server.1=192.168.1.10:2888:3888:participant;2181
server.2=192.168.1.11:2888:3888:participant;2181
server.3=192.168.1.12:2888:3888:participant;2181
EOF

# 3. 建立 myid（各節點不同）
mkdir -p data/zk/data
echo "1" > data/zk/data/myid  # Node 1 寫 1，Node 2 寫 2，Node 3 寫 3

# 4. 配置 Broker（各節點修改 broker.id 和 listeners）
cat > config/kafka-broker.conf << 'EOF'
broker.id=0
listeners=PLAINTEXT://192.168.1.10:9092
zookeeper.connect=192.168.1.10:2181,192.168.1.11:2181,192.168.1.12:2181
EOF
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

啟動叢集：

# 所有節點啟動 ADCC for zk
bin/admq-daemon start kafka zk

# 所有節點啟動 Broker
bin/admq-daemon start kafka broker

# 驗證叢集
kafka/bin/kafka-broker-api-versions.sh --bootstrap-server 192.168.1.10:9092
1
2
3
4
5
6
7
8

# 常用命令速查

# 行程管理

# 啟動/停止 ADCC for zk
bin/admq-daemon start kafka zk
bin/admq-daemon stop kafka zk

# 啟動/停止 Broker（單機）
bin/admq-daemon start kafka standalone
bin/admq-daemon stop kafka standalone

# 啟動/停止 Broker（叢集）
bin/admq-daemon start kafka broker
bin/admq-daemon stop kafka broker
1
2
3
4
5
6
7
8
9
10
11

# Topic 管理

# 建立 Topic
kafka/bin/kafka-topics.sh --create \
  --bootstrap-server localhost:9092 \
  --topic my-topic --partitions 6 --replication-factor 3

# 查看 Topic 列表
kafka/bin/kafka-topics.sh --list --bootstrap-server localhost:9092

# 查看 Topic 詳情（含 ISR）
kafka/bin/kafka-topics.sh --describe \
  --bootstrap-server localhost:9092 --topic my-topic

# 刪除 Topic
kafka/bin/kafka-topics.sh --delete \
  --bootstrap-server localhost:9092 --topic my-topic

# 增加分割區（只能增加）
kafka/bin/kafka-topics.sh --alter \
  --bootstrap-server localhost:9092 \
  --topic my-topic --partitions 12
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 訊息測試

# 生產訊息
kafka/bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 --topic my-topic

# 消費訊息（從頭開始）
kafka/bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 \
  --topic my-topic --from-beginning

# 消費訊息（最新）
kafka/bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 --topic my-topic
1
2
3
4
5
6
7
8
9
10
11
12

# 消費者群組管理

# 查看消費者群組列表
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 --list

# 查看消費進度（關鍵：關注 LAG）
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group my-group --describe

# 重置 Offset 到最早
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group my-group --topic my-topic \
  --reset-offsets --to-earliest --execute

# 重置 Offset 到最新
kafka/bin/kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group my-group --topic my-topic \
  --reset-offsets --to-latest --execute
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 叢集管理

# 查看 Broker 資訊
kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092

# 首選副本選舉（Leader 不均衡時）
kafka/bin/kafka-leader-election.sh \
  --bootstrap-server localhost:9092 \
  --election-type preferred --all-topic-partitions

# 副本重新分配（擴容後使用）
kafka/bin/kafka-reassign-partitions.sh \
  --bootstrap-server localhost:9092 --generate
1
2
3
4
5
6
7
8
9
10
11

# 日常維運

# 巡檢清單

檢查項 命令 正常指標
Broker 行程 ps -ef \| grep admq-kafka 行程存在
埠號監聽 netstat -nltup \| grep 9092 LISTEN 狀態
磁碟使用率 df -h < 70%
IO 使用率 iostat -x < 80%
ISR 狀態 kafka-topics.sh --describe ISR = Replicas
消費積壓 kafka-consumer-groups.sh --describe LAG 不持續增長

# 核心配置檔案

Broker 關鍵配置 (config/kafka-broker.conf)：

# 身分與網路
broker.id=0
listeners=PLAINTEXT://192.168.1.10:9092
advertised.listeners=PLAINTEXT://192.168.1.10:9092

# 儲存
log.dirs=/data/kafka
num.partitions=6

# 可靠性（生產環境必配）
default.replication.factor=3
min.insync.replicas=2
unclean.leader.election.enable=false

# 效能
num.network.threads=16
num.io.threads=32
compression.type=zstd

# 日誌保留
log.retention.hours=168
log.segment.bytes=1073741824

# ADCC for zk
zookeeper.connect=192.168.1.10:2181,192.168.1.11:2181,192.168.1.12:2181
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

ADCC for zk 關鍵配置 (config/kafka-zk.conf)：

tickTime=2000
initLimit=10
syncLimit=5

dataDir=/apusic/admq-kafka/data/zk/data
dataLogDir=/apusic/admq-kafka/data/zk/logs

# 叢集節點
server.1=192.168.1.10:2888:3888:participant;2181
server.2=192.168.1.11:2888:3888:participant;2181
server.3=192.168.1.12:2888:3888:participant;2181

# 自動清理
autopurge.snapRetainCount=3
autopurge.purgeInterval=6
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 故障處理

故障現象 排查命令 解決方案
Broker 當機 ps -ef \| grep admq-kafka bin/admq-daemon start kafka broker
Leader 不可用 kafka-topics.sh --describe 執行首選副本選舉
ISR 不同步 kafka-topics.sh --describe 檢查磁碟 IO、網路延遲
消費積壓(LAG) kafka-consumer-groups.sh --describe 增加 Consumer/Partition
磁碟滿 df -h 擴容磁碟或縮短日誌保留時間
ADCC for zk 連線失敗 檢查 myid、埠號、防火牆 修復配置後重啟

# 效能調優

# 系統級最佳化

# 檔案描述符
ulimit -n 1000000

# 網路參數
sysctl -w net.core.rmem_max=67108864
sysctl -w net.core.wmem_max=67108864
sysctl -w net.ipv4.tcp_rmem="4096 87380 67108864"
sysctl -w net.ipv4.tcp_wmem="4096 16384 67108864"

# 禁用 swap
sysctl -w vm.swappiness=0

# 檔案系統（掛載時）
mount -o noatime,nodiratime /dev/sda1 /data/kafka
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Broker 高吞吐配置

# 網路與執行緒
num.network.threads=16
num.io.threads=32
socket.send.buffer.bytes=307200
socket.receive.buffer.bytes=307200
queued.max.requests=2000

# 日誌
log.segment.bytes=524288000
log.retention.check.interval.ms=300000

# 壓縮與副本
compression.type=zstd
replica.socket.timeout.ms=30000
replica.fetch.max.bytes=1048576
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 生產者最佳化

Properties props = new Properties();
props.put("bootstrap.servers", "192.168.1.10:9092");
props.put("acks", "all");
props.put("compression.type", "zstd");
props.put("batch.size", 32768);
props.put("linger.ms", 10);
props.put("buffer.memory", 67108864);
props.put("max.in.flight.requests.per.connection", 5);
1
2
3
4
5
6
7
8

# 消費者最佳化

Properties props = new Properties();
props.put("bootstrap.servers", "192.168.1.10:9092");
props.put("group.id", "my-group");
props.put("max.poll.records", 1000);
props.put("fetch.min.bytes", 1);
props.put("fetch.max.wait.ms", 500);
1
2
3
4
5
6

# JVM 調優

# 大堆積記憶體 + G1 GC
KAFKA_HEAP_OPTS="-Xms16g -Xmx16g -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=20 \
  -XX:InitiatingHeapOccupancyPercent=35 \
  -XX:G1HeapRegionSize=16m"

# JMX 監控
JMX_PORT=9999
1
2
3
4
5
6
7
8

# 監控指標

# 關鍵告警指標

指標 告警閾值 說明
UnderReplicatedPartitions > 0 未充分同步的分割區
OfflinePartitionsCount > 0 離線分割區數
RequestLatencyAvg > 100ms 平均請求延遲
MessagesInPerSec 根據業務 每秒訊息數
LAG 持續增長 消費積壓

# 監控工具

# JMX 連線
jconsole localhost:9999

# Prometheus 配置
scrape_configs:
  - job_name: 'kafka'
    static_configs:
      - targets: ['localhost:12305']
1
2
3
4
5
6
7
8

# 目錄結構

admq-kafka/
├── bin/                    # 啟動、停止腳本
├── config/                 # 配置檔案
│   ├── kafka-standalone.conf    # 單機配置
│   ├── kafka-broker.conf        # Broker 配置
│   └── kafka-zk.conf            # ADCC for zk 配置
├── data/                   # 資料目錄
│   ├── kafka/              # 訊息資料
│   └── zk/                 # ADCC for zk 資料
├── jdk/                    # 內置 JDK
├── logs/                   # 執行日誌
└── service/                # systemd 服務檔案
1
2
3
4
5
6
7
8
9
10
11
12

# 技術支援

  • 電話：400-855-5800
  • 信箱：support@apusic.com
  • 網址：www.apusic.com
编辑页面 (opens new window)
#运维手册

← 产品简介→