Kafka单机版部署指南：从零到一快速上手

一、为什么选择Kafka单机版部署？

Kafka作为分布式流处理框架，在生产环境中通常采用集群模式部署以实现高可用与横向扩展。但在开发测试、本地调试或资源受限的场景下，单机版部署能以最小成本快速验证功能，尤其适合以下场景：

• 开发环境：开发者本地调试消息生产/消费逻辑
• 功能验证：测试Kafka与其他系统的集成能力
• 学习场景：初学者理解Kafka核心机制
• 轻量级应用：非关键业务且数据量较小的场景

单机版通过单节点运行ZooKeeper和Broker，简化了集群协调的复杂性，但需注意其不具备容错能力，节点故障会导致服务中断。

二、部署前环境准备

1. 系统要求

• 操作系统：Linux（推荐CentOS 7+/Ubuntu 18.04+）或macOS（通过Docker更便捷）
• 硬件配置：最低2核CPU、4GB内存（生产级配置建议8核+16GB）
• 磁盘空间：至少20GB可用空间（日志存储）

2. 软件依赖

• Java环境：Kafka 3.x+需JDK 11+（推荐OpenJDK或Oracle JDK）

  # 示例：安装OpenJDK 11（Ubuntu）
  sudo apt update
  sudo apt install openjdk-11-jdk -y
  java -version  # 验证安装

• 网络配置：确保9092（Broker）、2181（ZooKeeper）端口未被占用

3. 下载与解压

从Apache官网下载稳定版Kafka（以3.6.1为例）：

wget https://dlcdn.apache.org/kafka/3.6.1/kafka-3.6.1-src.tgz
tar -xzf kafka-3.6.1-src.tgz
cd kafka-3.6.1

三、单机版核心配置

1. 配置ZooKeeper

Kafka默认使用内嵌ZooKeeper，修改config/zookeeper.properties：

# 关键参数说明
dataDir=/tmp/zookeeper  # 数据存储路径
clientPort=2181         # 客户端连接端口
maxClientCnxns=0        # 允许最大连接数（0为无限制）
tickTime=2000           # 时钟间隔（毫秒）

2. 配置Broker

编辑config/server.properties，重点调整以下参数：

# 基础配置
broker.id=0             # 唯一节点ID（单机版固定为0）
listeners=PLAINTEXT://:9092  # 监听地址
advertised.listeners=PLAINTEXT://localhost:9092  # 对外暴露地址
# 日志存储
log.dirs=/tmp/kafka-logs  # 日志目录（建议单独分区）
num.partitions=3          # 默认分区数
log.retention.hours=168   # 消息保留时间（小时）
# ZooKeeper连接
zookeeper.connect=localhost:2181

参数优化建议：

• 若用于性能测试，可增加num.network.threads和num.io.threads（默认3/8）
• 开发环境可关闭auto.create.topics.enable=false避免意外创建Topic

四、启动与验证

1. 启动服务

按顺序启动ZooKeeper和Broker：

# 启动ZooKeeper（后台运行）
bin/zookeeper-server-start.sh -daemon config/zookeeper.properties
# 启动Broker（后台运行）
bin/kafka-server-start.sh -daemon config/server.properties

2. 验证服务状态

# 检查进程
jps | grep -E "QuorumPeerMain|Kafka"
# 创建测试Topic
bin/kafka-topics.sh --create --topic test-topic --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
# 发送测试消息
bin/kafka-console-producer.sh --topic test-topic --bootstrap-server localhost:9092
> Hello Kafka!  # 输入消息
# 消费测试消息
bin/kafka-console-consumer.sh --topic test-topic --from-beginning --bootstrap-server localhost:9092
# 应输出：Hello Kafka!

五、常见问题解决

1. 端口冲突

现象：启动失败，日志显示Address already in use
解决：

# 查找占用端口的进程
sudo lsof -i :9092  # 或2181
# 终止冲突进程
kill -9 <PID>

2. 日志目录权限不足

现象：Broker启动报错Permission denied
解决：

sudo chown -R $(whoami):$(whoami) /tmp/kafka-logs

3. 消息无法消费

现象：生产者发送成功但消费者无输出
排查步骤：

1. 检查Topic是否存在：bin/kafka-topics.sh --list --bootstrap-server localhost:9092
2. 验证消费者组状态：bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list
3. 检查偏移量重置策略：添加--reset-offsets参数测试

六、进阶配置建议

1. 监控集成

单机版可通过JMX暴露指标，配合Prometheus+Grafana监控：

# 在server.properties中启用JMX
export KAFKA_JMX_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9999 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false"

2. 日志持久化

建议将log.dirs配置到独立磁盘，并设置定期清理策略：

log.cleanup.policy=delete
log.segment.bytes=104857600  # 每个日志段大小（100MB）

3. 安全加固（可选）

开发环境可启用SASL认证：

# server.properties添加
security.inter.broker.protocol=SASL_PLAINTEXT
sasl.enabled.mechanisms=PLAIN
sasl.mechanism.inter.broker.protocol=PLAIN
authorizer.class.names=kafka.security.authorizer.AclAuthorizer

七、总结与最佳实践

1. 资源隔离：避免与生产环境共用同一台机器
2. 数据备份：定期备份log.dirs和ZooKeeper数据目录
3. 版本管理：记录Kafka版本与配置变更历史
4. 升级路径：单机版可平滑升级至集群模式（需调整broker.id和复制因子）

通过本文的步骤，开发者可在30分钟内完成Kafka单机版的部署与基础验证。对于长期使用的开发环境，建议结合Docker Compose实现环境快速复现（附Docker示例）：

# docker-compose.yml示例
version: '3'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
    volumes:
      - ./zookeeper-data:/var/lib/zookeeper
  kafka:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
    volumes:
      - ./kafka-data:/var/lib/kafka

单机版部署虽简单，但理解其核心机制（如日志分段、ISR复制等）对后续集群运维至关重要。建议开发者在完成部署后，进一步探索kafka-run-class.sh工具调试内部组件。