Kafka 4.3.0 单节点（Standalone）完整教程

一、环境要求

组件	版本/位置
Kafka	kafka_2.13-4.3.0（KRaft 模式，无 Zookeeper）
Java	JDK 17 或 21
主机名	lihaozhe（需在 `/etc/hosts` 中映射到本机 IP）

验证主机名解析：

bash 复制代码

ping -c 1 lihaozhe

二、目录规划

复制代码

/home/lhz/opt/kafka/                # Kafka 安装目录（$KAFKA_HOME）
/home/lhz/data/kraft-combined-logs/ # 数据日志目录（log.dirs）
/home/lhz/data/kafka-server.log     # 启动日志

三、配置 server.properties

编辑 /home/lhz/opt/kafka/config/server.properties：

properties 复制代码

############################# Server Basics #############################
# 节点角色：同时作为 broker 和 controller
process.roles=broker,controller

# 节点 ID（单节点必须为整数 1）
node.id=1

# Controller quorum 配置（关键，单节点）
controller.quorum.voters=1@lihaozhe:9093

############################# Socket Server Settings #############################
# 监听地址
listeners=PLAINTEXT://:9092,CONTROLLER://:9093

# 对外广播地址（必须是客户端能解析的地址）
advertised.listeners=PLAINTEXT://lihaozhe:9092,CONTROLLER://lihaozhe:9093

# Broker 间通信 listener
inter.broker.listener.name=PLAINTEXT

# Controller listener 名称映射
controller.listener.names=CONTROLLER

# 安全协议映射
listener.security.protocol.map=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,SSL:SSL,SASL_PLAINTEXT:SASL_PLAINTEXT,SASL_SSL:SASL_SSL

############################# Log Basics #############################
# 数据存储目录
log.dirs=/home/lhz/data/kraft-combined-logs

# 默认分区数
num.partitions=1

############################# Internal Topic Settings #############################
# 单节点必须设为 1
offsets.topic.replication.factor=1
share.coordinator.state.topic.replication.factor=1
share.coordinator.state.topic.min.isr=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1

四、首次启动流程

4.1 创建数据目录

bash 复制代码

mkdir -p /home/lhz/data/kraft-combined-logs

4.2 生成 Cluster ID

bash 复制代码

KAFKA_CLUSTER_ID=$(kafka-storage.sh random-uuid)
echo "Cluster ID: $KAFKA_CLUSTER_ID"
# 输出示例：Cluster ID: nSACPZHKQGKhR29_WM-gpw

4.3 格式化存储

方式 A：使用 --standalone（推荐，最简单）

bash 复制代码

kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID \
  -c $KAFKA_HOME/config/server.properties

方式 B：不使用 --standalone（需在 server.properties 中设置 controller.quorum.voters）

bash 复制代码

kafka-storage.sh format -t $KAFKA_CLUSTER_ID \
  -c $KAFKA_HOME/config/server.properties

成功输出：

复制代码

Formatting dynamic metadata voter directory /home/lhz/data/kraft-combined-logs
with metadata.version 4.3-IV0.

注意： 格式化只执行一次，重复执行会清空所有数据。

4.4 启动 Kafka

bash 复制代码

# 前台启动（调试用，Ctrl+C 停止）
kafka-server-start.sh $KAFKA_HOME/config/server.properties

# 后台启动（生产用）
nohup kafka-server-start.sh $KAFKA_HOME/config/server.properties \
  > /home/lhz/data/kafka-server.log 2>&1 &

五、验证启动

5.1 进程检查

bash 复制代码

jps -l | grep Kafka
# 输出：22796 kafka.Kafka

5.2 端口检查

bash 复制代码

ss -tlnp | grep -E '9092|9093'
# tcp6  0  0  :::9092  :::*  LISTEN  22796/java
# tcp6  0  0  :::9093  :::*  LISTEN  22796/java

5.3 健康检查

bash 复制代码

# 查看 topic 列表（应返回空或已有 topic）
kafka-topics.sh --bootstrap-server lihaozhe:9092 --list

# 查看 broker 状态
kafka-broker-api-versions.sh --bootstrap-server lihaozhe:9092

六、Topic 管理

6.1 创建 Topic

bash 复制代码

# 单分区单副本
kafka-topics.sh --bootstrap-server lihaozhe:9092 \
  --create --topic test \
  --partitions 1 --replication-factor 1

# 多分区
kafka-topics.sh --bootstrap-server lihaozhe:9092 \
  --create --topic user-events \
  --partitions 3 --replication-factor 1

6.2 查看 Topic

bash 复制代码

# 列出所有 topic
kafka-topics.sh --bootstrap-server lihaozhe:9092 --list

# 查看详情
kafka-topics.sh --bootstrap-server lihaozhe:9092 --describe --topic test

6.3 修改 Topic

bash 复制代码

# 增加分区（只能增加，不能减少）
kafka-topics.sh --bootstrap-server lihaozhe:9092 \
  --alter --topic test --partitions 5

# 删除 topic
kafka-topics.sh --bootstrap-server lihaozhe:9092 --delete --topic test

七、生产者 & 消费者

7.1 命令行生产者

bash 复制代码

kafka-console-producer.sh --bootstrap-server lihaozhe:9092 --topic test
> hello kafka
> 这是第二条消息
> Ctrl+D 退出

7.2 命令行消费者

bash 复制代码

# 从头消费
kafka-console-consumer.sh --bootstrap-server lihaozhe:9092 \
  --topic test --from-beginning

# 指定消费组
kafka-console-consumer.sh --bootstrap-server lihaozhe:9092 \
  --topic test --group my-group --from-beginning

7.3 消费组管理

bash 复制代码

# 列出所有消费组
kafka-consumer-groups.sh --bootstrap-server lihaozhe:9092 --list

# 查看消费组详情
kafka-consumer-groups.sh --bootstrap-server lihaozhe:9092 \
  --describe --group my-group

# 重置消费位点
kafka-consumer-groups.sh --bootstrap-server lihaozhe:9092 \
  --group my-group --reset-offsets --to-earliest \
  --topic test --execute

八、停止 Kafka

8.1 优雅停止

bash 复制代码

kafka-server-stop.sh

8.2 强制停止

bash 复制代码

# 找到 PID
jps -l | grep Kafka
# 停止
kill <PID>
# 如果不退出
kill -9 <PID>

九、彻底重置（清空所有数据）

bash 复制代码

# 1. 停止 Kafka
kill 22796

# 2. 删除数据
rm -rf /home/lhz/data/kraft-combined-logs/*

# 3. 重新生成 Cluster ID
KAFKA_CLUSTER_ID=$(kafka-storage.sh random-uuid)
echo "New Cluster ID: $KAFKA_CLUSTER_ID"

# 4. 重新格式化
kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID \
  -c $KAFKA_HOME/config/server.properties

# 5. 重新启动
nohup kafka-server-start.sh $KAFKA_HOME/config/server.properties \
  > /home/lhz/data/kafka-server.log 2>&1 &

十、开机自启动（可选）

创建 /home/lhz/opt/kafka/start-kafka.sh：

bash 复制代码

#!/bin/bash
export JAVA_HOME=/home/lhz/opt/jdk-21
export KAFKA_HOME=/home/lhz/opt/kafka
export PATH=$JAVA_HOME/bin:$KAFKA_HOME/bin:$PATH

# 检查是否已启动
if pgrep -f "kafka.Kafka" > /dev/null; then
    echo "Kafka 已经在运行"
    exit 0
fi

# 启动
nohup kafka-server-start.sh $KAFKA_HOME/config/server.properties \
  > /home/lhz/data/kafka-server.log 2>&1 &
echo "Kafka 启动中，PID: $!"

创建 /home/lhz/opt/kafka/stop-kafka.sh：

bash 复制代码

#!/bin/bash
PID=$(jps -l | grep kafka.Kafka | awk '{print $1}')
if [ -n "$PID" ]; then
    kill $PID
    echo "Kafka 已停止，PID: $PID"
else
    echo "Kafka 未运行"
fi

赋权并加入 crontab：

bash 复制代码

chmod +x /home/lhz/opt/kafka/start-kafka.sh /home/lhz/opt/kafka/stop-kafka.sh

# 编辑 crontab
crontab -e
# 添加：@reboot /home/lhz/opt/kafka/start-kafka.sh

十一、常见问题

Q1：`UnsupportedClassVersionError`

Java 版本太低。Kafka 4.x 需要 JDK 17+，推荐 JDK 21。

bash 复制代码

export JAVA_HOME=/home/lhz/opt/jdk-21

Q2：`controller.quorum.voters is not set`

Kafka 4.x 单节点必须使用 --standalone 或配置 controller.quorum.voters。

Q3：`Address already in use`

端口被占用。修改 listeners 配置或停止占用进程。

bash 复制代码

lsof -i :9092
lsof -i :9093

Q4：`NodeExistsException: Node 1 already exists`

重复格式化了。删除 log.dirs 目录下的 meta.properties 即可：

bash 复制代码

rm /home/lhz/data/kraft-combined-logs/meta.properties

Q5：客户端连接 `lihaozhe:9092` 失败

检查 /etc/hosts 是否配置了主机名映射，以及 advertised.listeners 是否正确。

Q6：`Node 1 disconnected` 或 `Connection to node -1 could not be established`

通常是 advertised.listeners 返回了客户端无法解析的地址。修改：

properties 复制代码

advertised.listeners=PLAINTEXT://lihaozhe:9092

并确保 lihaozhe 在客户端和服务器的 /etc/hosts 中都能解析。

Q7：日志清理策略调整

properties 复制代码

# 保留时间（小时）
log.retention.hours=168
# 日志段大小
log.segment.bytes=1073741824
# 清理检查间隔
log.retention.check.interval.ms=300000

修改后重启 Kafka 生效。

十二、目录结构

复制代码

/home/lhz/opt/kafka/
├── bin/                          # 启动脚本
│   ├── kafka-server-start.sh
│   ├── kafka-server-stop.sh
│   ├── kafka-topics.sh
│   ├── kafka-console-producer.sh
│   ├── kafka-console-consumer.sh
│   ├── kafka-consumer-groups.sh
│   ├── kafka-storage.sh
│   └── kafka-broker-api-versions.sh
├── config/
│   └── server.properties         # 核心配置
├── libs/                         # 依赖 JAR
├── logs/                         # Kafka 自身日志
└── start-kafka.sh                # 自启动脚本

十三、常用命令速查

功能	命令
查看所有 topic	`kafka-topics.sh --bootstrap-server lihaozhe:9092 --list`
创建 topic	`kafka-topics.sh --bootstrap-server lihaozhe:9092 --create --topic T --partitions N --replication-factor 1`
删除 topic	`kafka-topics.sh --bootstrap-server lihaozhe:9092 --delete --topic T`
查看 topic 详情	`kafka-topics.sh --bootstrap-server lihaozhe:9092 --describe --topic T`
生产消息	`kafka-console-producer.sh --bootstrap-server lihaozhe:9092 --topic T`
消费消息	`kafka-console-consumer.sh --bootstrap-server lihaozhe:9092 --topic T --from-beginning`
列出消费组	`kafka-consumer-groups.sh --bootstrap-server lihaozhe:9092 --list`
查看消费进度	`kafka-consumer-groups.sh --bootstrap-server lihaozhe:9092 --describe --group G`
重置 offset	`kafka-consumer-groups.sh --bootstrap-server lihaozhe:9092 --group G --reset-offsets --to-earliest --topic T --execute`
启动 Kafka	`kafka-server-start.sh -daemon $KAFKA_HOME/config/server.properties`
停止 Kafka	`kafka-server-stop.sh`

附录：Kafka 4.3 KRaft 模式 vs 旧版本 Zookeeper 模式

特性	KRaft 模式（4.x）	Zookeeper 模式（3.x 及更早）
协调服务	内置 controller（基于 Raft）	依赖 Zookeeper
启动速度	快	慢（需先启动 ZK）
部署复杂度	简单（单进程）	复杂（需维护 ZK 集群）
元数据扩展性	支持百万级 partition	万级 partition
推荐使用	✅ 4.x 默认模式	已逐步淘汰

自 Kafka 3.3 起，KRaft 模式已生产就绪；Kafka 4.0 完全移除 ZK 模式代码。

Kafka 4.3.0 单节点（Standalone）完整教程