运维手册

# 前言

本文档为金蝶Apusic分布式消息队列for Kafka（Apusic Distributed Message Queue，简称：ADMQ for Kafka）的运维手册，旨在为中间件运维人员提供ADMQ for 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

您在取得技术支持时，请提供如下信息：

您的姓名
公司信息与联系方式
操作系统及其版本
产品版本号
出现异常及错误的日志、截图等详细信息

# 概述

ADMQ Kafka是一个高吞吐的分布式消息系统，常用于日志收集、数据管道和实时流处理。

# 基本概念

组件	说明
Broker	Kafka服务节点
Topic	消息分类
Partition	Topic的分区
Producer	生产者
Consumer	消费者
Consumer Group	消费者组

简单数据流：Producer→ Broker→ Topic→ Partition→ Consumer 特点： • 高吞吐 • 分布式 • 顺序写入磁盘 • 副本机制保证可靠性

# 常用运维命令

进程控制的命令在 admq-kafka/bin目录，需要的配置文件在 admq-kafka/config目录。支持开源 kafka脚本，可以进入到 admq-kafka/kafka/bin目录执行对应的脚本。

# 进程管理

# 启动/停止 kafka zk节点

bin/admq-daemon start kafka zk

bin/admq-daemon stop kafka zk

1
2
3

# 启动/停止 kafka broker节点

bin/admq-daemon start kafka broker 1
bin/admq-daemon stop kafka broker 2

1
2

# Topic管理

# 查看 Topic

kafka-topics.sh --bootstrap-server localhost:9092 --list

# 查看 Topic详情

kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic test

# 创建 Topic

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--create \
--topic test \
--partitions 3

1
2
3
4
5

# 删除 Topic：

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--delete \
--topic test

1
2
3
4

# Consumer管理

# 查看 consumer group

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

1
2
3

# 查看消费情况

kafka-consumer-groups.sh \
--bootstrap-server localhost:9092 \
--describe \
--group test-group

1
2
3
4

关键指标：

指标	含义
CURRENT-OFFSET	当前消费
LOG-END-OFFSET	最新消息
LAG	积压

# 生产/消费

# 生产消息

kafka-console-producer.sh \
--broker-list localhost:9092 \
--topic test

1
2
3

# 消费消息

kafka-console-consumer.sh \
--bootstrap-server localhost:9092 \
--topic test \
--from-beginning

1
2
3
4

# 日常巡检

# Broker状态

检查 broker是否在线：

ps -ef | grep admq-kafka

或

netstat -ntlp | grep 9092

# ISR状态

检查：

kafka-topics.sh --describe

判断：

ISR < Replicas

说明副本同步异常。

# 消费积压

检查：

kafka-consumer-groups.sh --describe

判断：

LAG > 0

如果持续增长，需要排查。

# 磁盘使用率

检查：

df -h

建议：

指标	建议
磁盘使用率	<70%
IO util	<80%

# 常见故障处理

# Consumer积压

现象：

LAG持续增长

原因：

• 消费能力不足 • Broker性能瓶颈 • 网络问题

解决：

方法	说明
增加Consumer	提高并行度
增加Partition	提升吞吐
优化业务逻辑	减少处理时间

# Broker宕机

现象：

Leader not available

检查：

ps -ef |grep admq-kafka

查看日志：

cat logs/server.log

处理：

bin/admq-daemon start kafka broker/standalone

# ISR不同步

现象：

ISR < Replicas

原因：

原因	说明
磁盘IO高	follower同步慢
网络延迟	副本复制慢
CPU负载高	Broker压力大

检查：

iostat -x

# Topic无 Leader

现象：

Leader: none

处理：

# 执行 leader选举
kafka-leader-election.sh \
--bootstrap-server localhost:9092 \
--all-topic-partitions \
--election-type preferred

1
2
3
4
5

# 其他问题

ADCC for zk 启动失败，日志报 Connection refused 或 **Session expired
- 检查 myid 文件是否存在且内容正确。
- 检查 zookeeper.properties 中 server.x 的 IP 是否可达，端口 2888/3888 是否被防火墙拦截。
Kafka 启动失败，日志报 **Broker ID 0 is already registered
- 检查是否有残留的旧 ADCC for zk 数据。如果是新部署，清空 ADCC for zk 的 dataDir 和 Kafka 的 log.dirs 后重试。
- 确认各节点 broker.id 不重复。
ISR 集合不全 (Isr: 0,1 而不是 0,1,2)**
- 说明某个 Follower 同步太慢或网络不通。检查该节点的日志和网络带宽。
Kafka 启动失败，日志报 Failed to bind to port 9092
- 检查 9092 端口是否被其他进程占用（使用 netstat -tulpn | grep 9092 或 lsof -i:9092 命令）。
- 检查 server.properties 中 listeners 配置的端口是否与实际要使用的端口一致，避免配置冲突。
- 确认防火墙未拦截 9092 端口，或已在防火墙规则中放行该端口。
Kafka 生产者发送消息失败，报 Leader not available
- 检查对应的 Topic 是否存在，若不存在需先创建（kafka-topics.sh --create 命令）。
- 检查 Kafka 集群是否正常启动，Broker 节点是否全部在线。
- 检查 Topic 的副本配置是否合理，若副本数大于可用 Broker 数，会导致 Leader 无法选举。
Kafka 消费者消费失败，报 No offset found for partition
- 若为新消费者组，首次消费无偏移量属于正常情况，可配置 auto.offset.reset 为 earliest 或 latest。
- 若为旧消费者组，检查是否手动删除过 ADCC for zk/ Kafka 中的偏移量数据，或消费者组长时间未消费导致偏移量过期（需调整 offsets.retention.minutes 配置）。
ADCC for zk 集群启动后，部分节点无法加入集群，日志报 Cannot open channel to x at election address
- 检查所有 ADCC for zk 节点的 zoo.cfg 中 server.x 配置的 IP / 端口是否一致，无拼写错误。
- 检查各节点之间的时间是否同步（时间差超过 2000ms 会导致选举失败），可通过 ntpdate 同步时间。
- 确认 dataDir 目录权限为 ADCC for zk 运行用户可读写，避免权限不足导致 myid 文件无法读取。
Kafka 日志报 Not enough replicas，消息无法持久化
- 检查 Topic 的 min.insync.replicas 配置值是否大于当前可用的同步副本数（ISR）。
- 若为单 Broker 部署，需将 min.insync.replicas 改为 1（默认 1，若手动修改过需调整）。
- 检查 Follower 节点是否正常同步，排查网络延迟、磁盘 IO 过高导致同步慢的问题。
Kafka 启动后，JVM 内存溢出（OOM），进程直接崩溃
- 检查 kafka-server-start.sh 中的 JVM 配置（KAFKA_HEAP_OPTS），默认堆内存可能过大 / 过小。
- 单机测试环境可调整为 -Xmx512M -Xms512M，生产环境根据服务器内存配置（建议不超过物理内存的 50%）。
- 检查是否开启了过多的 Topic / 分区，导致内存占用过高，需合理规划分区数。
连接 Kafka 时报 SSL handshake failed
- 若开启了 SSL 认证，检查客户端 / 服务端的 SSL 证书路径、密码配置是否正确。
- 确认证书未过期，且服务端 listeners 配置为 SSL:// 而非 PLAINTEXT://。
- 检查客户端是否正确配置了 SSL 相关参数（如 security.protocol=SSL）

# Kafka扩容与维护

# 增加 Partition

kafka-topics.sh \
--bootstrap-server localhost:9092 \
--alter \
--topic test \
--partitions 6

1
2
3
4
5

注意：扩容后消息顺序可能改变。

# 分区重分配

生成计划：

kafka-reassign-partitions.sh \
--bootstrap-server localhost:9092 \
--generate

1
2
3

执行：

kafka-reassign-partitions.sh \
--execute

1
2

# Kafka性能调优

# Broker参数

关键参数：

num.network.threads=8
num.io.threads=16
log.segment.bytes=1GB
log.retention.hours=168

1
2
3
4

# Producer优化

# Consumer优化

fetch.min.bytes=1
fetch.max.wait.ms=500
max.poll.records=500

1
2
3

# 日志管理

日志路径：admq-kafka/logs

常见错误：

Leader not available
NotEnoughReplicas
Connection refused

1
2
3

# 配置管理

# 默认配置

路径：admq-kafka/configs

kafka-zk.conf： zk用到的配置文件
**kafka-broker.conf：**集群部署时，broker节点用到的配置
**kafka-standalone.conf：**单机部署时，broker节点用到的配置

# 核心配置项

listeners=PLAINTEXT://192.168.1.10:9092
# 若需外网访问，可加：EXTERNAL://your.public.ip:9093
advertised.listeners=PLAINTEXT://192.168.1.10:9092
# 安全协议映射（如使用多 listener）
listener.security.protocol.map=PLAINTEXT:PLAINTEXT
# 日志保留时间（7天）
log.retention.hours=168
# 或按大小保留（例如每个 partition 最多 10GB）
# log.retention.bytes=10737418240
# 日志段文件大小（默认 1GB）
log.segment.bytes=1073741824
# 后台日志刷新策略（依赖 OS 刷盘更高效 机械硬盘不主动刷盘）
log.flush.interval.messages=9223372036854775807
log.flush.interval.ms=9223372036854775807

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 安全加固

# 1. 网络安全

# 1.1 防火墙策略

生产环境应严格限制 Kafka 端口访问：

# 仅允许内网访问 Kafka 端口
iptables -A INPUT -p tcp --dport 9092 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p tcp --dport 9092 -j DROP

# 仅允许管控台管理 IP 访问
iptables -A INPUT -p tcp --dport 12305 -s 10.0.0.10 -j ACCEPT
iptables -A INPUT -p tcp --dport 12305 -j DROP

1
2
3
4
5
6
7

# 1.2 网络隔离

将 Kafka 集群部署在独立的安全组/VPC 中
禁止 Kafka 端口直接暴露在互联网
使用 VPN 或专线进行跨机房访问

# 2. 认证授权

# 2.1 启用 SASL 认证

# broker 配置
listeners=SASL_PLAINTEXT://0.0.0.0:9092
security.inter.broker.protocol=SASL_PLAINTEXT
sasl.mechanism.inter.broker.protocol=SCRAM-SHA-512
sasl.enabled.mechanisms=SCRAM-SHA-512

# 启用 ACL
authorizer.class.name=kafka.security.authorizer.AclAuthorizer
allow.everyone.if.no.acl.found=false

1
2
3
4
5
6
7
8
9

# 2.2 配置用户认证

# 创建用户并设置密码
kafka-configs.sh --zookeeper localhost:2181 \
  --alter --add-config 'SCRAM-SHA-512=[password=your-secure-password]' \
  --entity-type users --entity-name admin

# 查看用户列表
kafka-configs.sh --zookeeper localhost:2181 \
  --describe --entity-type users

1
2
3
4
5
6
7
8

# 2.3 配置 ACL 规则

# 生产环境权限控制
kafka-acls.sh --authorizer-properties zookeeper.connect=localhost:2181 \
  --add --allow-principal User:app-producer \
  --operation Write --topic order-topic

kafka-acls.sh --authorizer-properties zookeeper.connect=localhost:2181 \
  --add --allow-principal User:app-consumer \
  --operation Read --topic order-topic \
  --group order-consumer-group

# 禁止匿名访问
kafka-acls.sh --authorizer-properties zookeeper.connect=localhost:2181 \
  --add --deny-principal User:ANONYMOUS \
  --operation All --cluster

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 3. 数据加密

# 3.1 SSL/TLS 配置

# 启用 SSL
listeners=SSL://0.0.0.0:9093
security.inter.broker.protocol=SSL

# SSL 证书配置
ssl.keystore.location=/path/to/server.keystore.jks
ssl.keystore.password=your-keystore-password
ssl.key.password=your-key-password
ssl.truststore.location=/path/to/server.truststore.jks
ssl.truststore.password=your-truststore-password
ssl.client.auth=required

1
2
3
4
5
6
7
8
9
10
11

# 3.2 证书管理

# 生成自签名证书（测试环境）
keytool -keystore server.keystore.jks -alias localhost -validity 365 -genkey

# 导出证书
keytool -keystore server.keystore.jks -alias localhost -export -file cert.crt

# 导入信任库
keytool -keystore server.truststore.jks -alias ca-cert -import -file ca-cert.crt

1
2
3
4
5
6
7
8

# 4. 审计与监控

# 4.1 启用审计日志

# log4j 配置
log4j.logger.kafka.authorizer.logger=WARN, authorizerAppender
log4j.additivity.kafka.authorizer.logger=false
log4j.appender.authorizerAppender=org.apache.log4j.DailyRollingFileAppender
log4j.appender.authorizerAppender.File=${log.dir}/kafka-authorizer.log
log4j.appender.authorizerAppender.layout=org.apache.log4j.PatternLayout
log4j.appender.authorizerAppender.layout.ConversionPattern=[%d] %p %m (%c)%n

1
2
3
4
5
6
7

# 4.2 监控告警项

监控项	告警阈值	说明
认证失败次数	> 10次/分钟	可能存在暴力破解
未授权访问	> 0	需立即排查
SSL 证书过期	< 30天	需提前续期
ACL 变更	任何变更	需审计确认

# 5. 系统安全

# 5.1 运行用户

# 创建专用用户
useradd -r -s /bin/false admq-kafka

# 修改文件属主
chown -R admq-kafka:admq-kafka /apusic/admq-kafka

# 限制目录权限
chmod 750 /apusic/admq-kafka
chmod 600 /apusic/admq-kafka/config/*.conf
chmod 600 /apusic/admq-kafka/license.xml

1
2
3
4
5
6
7
8
9
10

# 5.2 systemd 安全选项

[Service]
User=admq-kafka
Group=admq-kafka
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

1
2
3
4
5
6
7

# 6. 安全巡检清单

检查项	检查方法	合格标准
防火墙规则	`iptables -L`	仅开放必要端口
认证状态	查看配置	已启用 SASL/SCRAM
ACL 配置	`kafka-acls.sh --list`	无匿名访问权限
SSL 证书	`keytool -list`	证书未过期
文件权限	`ls -la`	配置文件 600
运行用户	`ps -ef`	非 root 用户
审计日志	`ls -la logs/`	存在 authorizer 日志

# 运维经验总结

Kafka故障大多集中在：

问题	占比
消费积压	50%
Broker宕机	20%
ISR不同步	15%
磁盘满	10%
网络问题	5%

运维口诀：先看 Broker、再看 Leader、再看 ISR、再看 Lag、最后看 IO

编辑页面

#运维手册

← 迁移手册性能优化手册→

运维手册

# 前言

# 适用对象

# 相关文档

# 技术支持

# 概述

# 基本概念

# 常用运维命令

# 进程管理​

# 启动/停止 kafka zk节点

# 启动/停止 kafka broker节点​

# Topic管理​

# 查看 Topic​

# 查看 Topic详情

# 创建 Topic

# 删除 Topic：​

# Consumer管理​

# 查看 consumer group​

# 查看消费情况

# 生产/消费

# 生产消息

# 消费消息

# 日常巡检

# Broker状态​

# ISR状态​

# 消费积压​

# 磁盘使用率​

# 常见故障处理

# Consumer积压​

# Broker宕机​

# ISR不同步​

# Topic无 Leader​

# 其他问题

# Kafka扩容与维护​

# 增加 Partition​

# 分区重分配​

# Kafka性能调优​

# Broker参数​

# Producer优化​

# Consumer优化​

# 日志管理

# 配置管理

# 默认配置

# 核心配置项

# 安全加固

# 1. 网络安全

# 1.1 防火墙策略

# 1.2 网络隔离

# 2. 认证授权

# 2.1 启用 SASL 认证

# 2.2 配置用户认证

# 2.3 配置 ACL 规则

# 3. 数据加密

# 3.1 SSL/TLS 配置

# 3.2 证书管理

# 4. 审计与监控

# 4.1 启用审计日志

# 4.2 监控告警项

# 5. 系统安全

# 5.1 运行用户

# 5.2 systemd 安全选项

# 6. 安全巡检清单

# 运维经验总结

# 进程管理

# 启动/停止 kafka broker节点

# Topic管理

# 查看 Topic

# 删除 Topic：

# Consumer管理

# 查看 consumer group

# Broker状态

# ISR状态

# 消费积压

# 磁盘使用率

# Consumer积压

# Broker宕机

# ISR不同步

# Topic无 Leader

# Kafka扩容与维护

# 增加 Partition

# 分区重分配

# Kafka性能调优

# Broker参数

# Producer优化

# Consumer优化