单机部署Kafka全攻略：从零开始的实践指南

一、单机部署Kafka的适用场景与优势

在分布式消息队列系统中，Kafka以其高吞吐、低延迟的特性被广泛采用。单机部署Kafka虽不具备分布式系统的容错能力，但在开发测试、本地环境验证、小型应用等场景中具有独特优势：

1. 开发测试环境：开发者可在本地快速搭建Kafka环境，验证消息生产消费逻辑，无需依赖远程集群
2. 小型应用场景：对于数据量不大、可靠性要求不高的系统，单机部署可降低运维复杂度
3. 教学演示：在技术培训中，单机环境更便于展示Kafka核心功能
4. 成本敏感型项目：避免初期投入多台服务器的硬件成本

单机部署的典型架构为单节点Broker，同时运行ZooKeeper服务（Kafka 3.3+版本支持KRaft协议可无需ZooKeeper）。建议配置不低于4核CPU、8GB内存、50GB磁盘空间的服务器。

二、环境准备与依赖安装

1. 系统要求

• 操作系统：Linux（推荐CentOS 7+/Ubuntu 20.04+）或macOS
• Java环境：JDK 11或更高版本（推荐OpenJDK）
• 磁盘空间：根据数据留存策略准备足够空间

2. 安装步骤（以CentOS为例）

# 安装OpenJDK 11
sudo yum install -y java-11-openjdk-devel
# 验证Java版本
java -version
# 应输出：openjdk version "11.0.xx"
# 创建kafka用户（安全最佳实践）
sudo useradd kafka -m
sudo passwd kafka

3. 下载与解压

# 下载Kafka二进制包（以3.6.0版本为例）
wget https://archive.apache.org/dist/kafka/3.6.0/kafka_2.13-3.6.0.tgz
# 解压到指定目录
tar -xzf kafka_2.13-3.6.0.tgz -C /opt/
sudo chown -R kafka:kafka /opt/kafka_2.13-3.6.0

三、核心配置文件详解

1. server.properties关键配置

# 基本配置
broker.id=0  # 单机环境保持0
listeners=PLAINTEXT://:9092  # 监听地址
advertised.listeners=PLAINTEXT://localhost:9092  # 对外暴露地址
# 日志存储配置
log.dirs=/tmp/kafka-logs  # 建议修改为持久化目录
num.partitions=3  # 默认分区数
log.retention.hours=168  # 消息保留时间（小时）
# ZooKeeper配置（KRaft模式可跳过）
zookeeper.connect=localhost:2181

2. KRaft模式配置（可选）

Kafka 3.3+版本支持KRaft协议替代ZooKeeper：

# config/kraft/server.properties新增配置
process.roles=broker,controller
node.id=1
controller.quorum.voters=1@localhost:9093

3. 环境变量设置

# 编辑~/.bashrc或/etc/profile
export KAFKA_HOME=/opt/kafka_2.13-3.6.0
export PATH=$PATH:$KAFKA_HOME/bin
source ~/.bashrc

四、启动与验证流程

1. 启动服务（传统模式）

# 启动ZooKeeper（如使用KRaft可跳过）
$KAFKA_HOME/bin/zookeeper-server-start.sh -daemon $KAFKA_HOME/config/zookeeper.properties
# 启动Kafka Broker
$KAFKA_HOME/bin/kafka-server-start.sh -daemon $KAFKA_HOME/config/server.properties

2. 创建测试Topic

$KAFKA_HOME/bin/kafka-topics.sh --create \
  --topic test-topic \
  --bootstrap-server localhost:9092 \
  --partitions 3 \
  --replication-factor 1

3. 生产消费测试

# 启动生产者
$KAFKA_HOME/bin/kafka-console-producer.sh \
  --topic test-topic \
  --bootstrap-server localhost:9092
# 启动消费者（新窗口）
$KAFKA_HOME/bin/kafka-console-consumer.sh \
  --topic test-topic \
  --from-beginning \
  --bootstrap-server localhost:9092

五、运维管理与故障排查

1. 常用管理命令

# 查看Topic列表
kafka-topics.sh --list --bootstrap-server localhost:9092
# 查看消费者组
kafka-consumer-groups.sh --list --bootstrap-server localhost:9092
# 删除Topic（谨慎使用）
kafka-topics.sh --delete --topic test-topic --bootstrap-server localhost:9092

2. 日志分析

Kafka主要日志位于logs/server.log，关键错误类型包括：

• NotEnoughReplicasException：副本不可用
• LeaderNotAvailableException：Leader选举失败
• DiskFullException：磁盘空间不足

3. 性能调优建议

• 内存配置：调整heap.opts中的Xms/Xmx（建议4G-8G）
• 网络优化：增大socket.send.buffer.bytes和socket.receive.buffer.bytes
• 磁盘IO：使用SSD并调整num.io.threads（默认8）

六、安全增强方案

1. SASL_SSL认证配置

# server.properties新增配置
listeners=SASL_SSL://:9093
sasl.enabled.mechanisms=SCRAM-SHA-256
sasl.mechanism.inter.broker.protocol=SCRAM-SHA-256
security.inter.broker.protocol=SASL_SSL
ssl.keystore.location=/path/to/keystore.jks
ssl.keystore.password=keystore_password

2. ACL权限控制

# 添加用户
kafka-configs.sh --zookeeper localhost:2181 --alter --add-config 'SCRAM-SHA-256=[password=admin-secret]' --entity-type users --entity-name admin
# 授权Topic访问
kafka-acls.sh --authorizer-properties zookeeper.connect=localhost:2181 --add --allow-principal User:admin --operation WRITE --topic test-topic

七、升级与迁移指南

1. 版本升级步骤

1. 下载新版本二进制包
2. 停止Broker服务
3. 备份元数据（meta.properties和日志目录）
4. 更新配置文件（注意新增参数）
5. 启动新版本服务

2. 数据迁移工具

使用MirrorMaker进行跨版本数据迁移：

$KAFKA_HOME/bin/connect-mirror-maker.sh \
  --consumer.config source.properties \
  --producer.config target.properties \
  --whitelist ".*" \
  --num.streams 3

八、最佳实践总结

1. 资源隔离：建议使用独立磁盘存储日志，避免与系统盘混用
2. 监控告警：集成Prometheus+Grafana监控关键指标（如UnderReplicatedPartitions）
3. 备份策略：定期备份meta.properties和重要Topic数据
4. 版本管理：保持与生产环境相同的次要版本号（如3.5.x）

单机部署Kafka为开发测试提供了高效便捷的解决方案，但需注意其局限性。对于生产环境，建议至少部署3节点集群以保障可用性。通过合理配置和监控，单机Kafka完全能满足中小规模应用的消息处理需求。