10.2.7 常见部署问题与处理

常见部署问题与处理#

0. 原理草图：客户端连接与控制器选举关系#

1. 启动失败与进程反复退出#

现象：Kafka 启动后立即退出或无法启动。
排查要点：
查看日志：logs/server.log、logs/controller.log（KRaft）
检查 JAVA_HOME 与 JVM 版本（建议 JDK 11/17）
确认 log.dirs 是否存在且可写

示例：标准启动与日志检查

# 假设安装目录 /opt/kafka
cd /opt/kafka

# 启动服务（KRaft 示例）
bin/kafka-server-start.sh -daemon config/kraft/server.properties

# 查看运行状态与日志
ps -ef | grep kafka
tail -n 80 logs/server.log

典型修复：目录权限与配置检查

# 创建数据目录并授权
mkdir -p /data/kafka
chown -R kafka:kafka /data/kafka

# 检查配置文件
grep -E 'log.dirs|listeners|advertised.listeners' config/kraft/server.properties

解释：
- log.dirs 为日志存储目录，不存在会直接启动失败
- listeners/advertised.listeners 错误会导致启动或客户端无法连接

练习：
- 故意设置不存在的 log.dirs，观察 server.log 报错并修复

2. 端口不可达或客户端连接失败#

现象：客户端连接 Broker 超时或握手失败。
排查要点：
ss -lntp 是否监听 9092/9093
防火墙、云安全组、SELinux 是否放行
advertised.listeners 是否为客户端可访问地址

示例：多监听与内外网访问

# config/server.properties
listeners=INTERNAL://0.0.0.0:9092,EXTERNAL://0.0.0.0:19092
advertised.listeners=INTERNAL://10.0.0.10:9092,EXTERNAL://1.2.3.4:19092
listener.security.protocol.map=INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
inter.broker.listener.name=INTERNAL

验证命令

# 本机检查端口
ss -lntp | grep -E '9092|19092'

# 从客户端测试
bin/kafka-broker-api-versions.sh --bootstrap-server 1.2.3.4:19092

练习：
- 修改 advertised.listeners 为错误 IP，观察客户端报错并修复

3. Broker 无法加入集群或元数据不一致#

现象：新节点加入后不显示或报错 InconsistentClusterId。
排查要点：
broker.id 是否唯一
meta.properties 中 cluster.id 是否一致

修复示例：KRaft 重新格式化

# 查看当前 cluster.id
cat /data/kafka/meta.properties

# 重新格式化（清理错误数据目录后）
rm -rf /data/kafka/*
bin/kafka-storage.sh format -t <cluster-id> -c config/kraft/server.properties

解释：
- cluster.id 必须与集群一致，否则无法加入

练习：
- 用错误的 cluster.id 格式化一个节点并观察报错

4. ZooKeeper 连接异常#

现象：Kafka 报错 ConnectionLoss、SessionExpired。
排查要点：
zookeeper.connect 配置与端口是否正确
ZooKeeper 是否健康

示例：ZK 连接与会话超时调整

# config/server.properties
zookeeper.connect=10.0.0.11:2181,10.0.0.12:2181,10.0.0.13:2181
zookeeper.session.timeout.ms=18000

健康检查

echo ruok | nc 10.0.0.11 2181   # 预期输出: imok

练习：
- 关闭一个 ZK 节点，观察 Kafka 日志并恢复

5. 复制因子不足或分区无法分配#

现象：创建主题失败 InvalidReplicationFactor。
排查要点：
Broker 数量是否满足副本数

示例：创建主题

# 2 台 Broker，只能设置副本数 <=2
bin/kafka-topics.sh --create --topic test --partitions 3 --replication-factor 2 \
--bootstrap-server 10.0.0.10:9092

练习：
- 将副本数设置为 3，观察失败提示并修正

6. ISR 收缩与持续重平衡#

现象：ISR 频繁变动，消费者频繁重平衡。
排查要点：
磁盘 I/O 是否瓶颈
GC 停顿或网络抖动

排查命令

# 查看 ISR 与副本状态
bin/kafka-topics.sh --describe --topic test --bootstrap-server 10.0.0.10:9092

# 查看 JVM GC
grep -i gc logs/server.log | tail -n 20

优化配置示例

# config/server.properties
num.network.threads=6
num.io.threads=16
replica.lag.time.max.ms=30000

练习：
- 限制磁盘 I/O（如使用 tc 或压测），观察 ISR 变化

7. 磁盘空间不足与日志滚动异常#

现象：磁盘告警、写入失败或日志无法滚动。
排查要点：
log.retention.hours 是否过大
log.segment.bytes 是否过大

示例：多目录与保留策略

# config/server.properties
log.dirs=/data/kafka1,/data/kafka2
log.retention.hours=72
log.segment.bytes=1073741824

清理验证

df -h /data/kafka1 /data/kafka2

练习：
- 将保留时间设为 1 小时，观察旧日志自动删除

8. 时钟偏差导致认证或选举异常#

现象：KRaft 选举异常或请求超时。
排查要点：
NTP 是否同步

修复示例：chrony

# 安装并启用
yum -y install chrony
systemctl enable --now chronyd

# 查看时间状态
chronyc tracking

练习：
- 将一台节点时间手动调整 5 分钟，观察选举异常并恢复

9. TLS/SASL 配置错误#

现象：握手失败、SaslAuthenticationException。
排查要点：
证书路径与密码
listener.security.protocol.map 是否一致

示例：单监听排错

listeners=SASL_PLAINTEXT://0.0.0.0:9092
advertised.listeners=SASL_PLAINTEXT://10.0.0.10:9092
listener.security.protocol.map=SASL_PLAINTEXT:SASL_PLAINTEXT
sasl.enabled.mechanisms=PLAIN

客户端测试

bin/kafka-broker-api-versions.sh --bootstrap-server 10.0.0.10:9092 \
--command-config /opt/kafka/config/client.properties

练习：
- 修改 client.properties 密码错误，观察认证失败

10. KRaft 模式下控制器不可用#

现象：控制器反复切换或无法选举。
排查要点：
controller.quorum.voters 是否一致
控制器端口是否监听

示例：控制器配置

# config/kraft/server.properties
process.roles=broker,controller
controller.listener.names=CONTROLLER
listeners=PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
controller.quorum.voters=1@10.0.0.10:9093,2@10.0.0.11:9093,3@10.0.0.12:9093

验证

ss -lntp | grep 9093

练习：
- 停止一台控制器节点，观察其他节点是否能完成选举