Kafka 4.0 从零到一8 步快速上手 + 实战要点与避坑

一. 预备知识与环境

Kafka 版本：4.0.0（Scala 2.13 发行包）
Java 要求 ：本地必须安装 Java 17+
系统：适用于 macOS / Linux / Windows（文中含 Windows 命令差异）
端口：默认对外暴露 9092

快速检查：

bash 复制代码

java -version

二. 获取与解压

bash 复制代码

tar -xzf kafka_2.13-4.0.0.tgz
cd kafka_2.13-4.0.0

三. 启动 Kafka 环境（3 选 1）

Kafka 4.0 在 Quick Start 中默认使用 KRaft 单机演示模式（无需 ZooKeeper）。

3.1 使用下载的脚本（本地进程）

生成 Cluster UUID：

bash 复制代码

KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

格式化日志目录（仅首次）：

bash 复制代码

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

启动 Broker：

bash 复制代码

bin/kafka-server-start.sh config/server.properties

看到成功日志后，即表示单机 Kafka 已就绪。

3.2 使用 JVM 版官方 Docker 镜像

bash 复制代码

docker pull apache/kafka:4.0.0
docker run -p 9092:9092 apache/kafka:4.0.0

说明：这是最简单的演示用法。若宿主机/容器网络访问有问题，可查看容器日志并按需设置 advertised.listeners 等参数。

3.3 使用 GraalVM 原生镜像（启动更快）

bash 复制代码

docker pull apache/kafka-native:4.0.0
docker run -p 9092:9092 apache/kafka-native:4.0.0

四. 创建主题（Topic）

主题是事件的"文件夹"。先开一个新终端：

bash 复制代码

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

查看主题详情（分区/副本数量等）：

bash 复制代码

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

示例输出（单机演示）：

复制代码

Topic: quickstart-events        TopicId: NPmZHyhbR9y00wMglMH2sg PartitionCount: 1 ReplicationFactor: 1 Configs:
Topic: quickstart-events Partition: 0 Leader: 0 Replicas: 0 Isr: 0

提示：生产环境通常 分区 > 1 、副本因子 ≥ 3；本地演示保持默认即可。

五. 写入事件（Producer）

启动控制台生产者（你输入的每一行都会写成一条事件）：

bash 复制代码

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

输入示例（按行回车）：

复制代码

>This is my first event
>This is my second event

使用 Ctrl-C 停止生产者。

六. 读取事件（Consumer）

开另一个终端，从头读取：

bash 复制代码

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

输出示例：

复制代码

This is my first event
This is my second event

你可以再开启一个消费者终端重复执行相同命令，验证事件可被多消费者、多次读取。

七. Kafka Connect：文件 → 主题 → 文件（源/汇示例）

目标：演示把文件中的每一行作为事件导入到 Kafka，再从 Kafka 导出到另一个文件。

7.1 配置插件路径（File 连接器）

将 connect-file-4.0.0.jar 加到 plugin.path（演示用相对路径；生产建议绝对路径）：

bash 复制代码

echo "plugin.path=libs/connect-file-4.0.0.jar" >> config/connect-standalone.properties

7.2 准备测试数据

bash 复制代码

# macOS/Linux
echo -e "foo\nbar" > test.txt

Windows：

powershell 复制代码

echo foo > test.txt
echo bar >> test.txt

7.3 以 Standalone 模式运行 Connect（1 个进程跑 2 个连接器）

bash 复制代码

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

Source ：读取 test.txt 每行 → 写入主题 connect-test
Sink ：从 connect-test 读取 → 写入 test.sink.txt

验证落地文件：

bash 复制代码

more test.sink.txt
# 输出：
foo
bar

也可以直接消费主题查看：

bash 复制代码

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning
# 示例输出（带 schema 包裹）：
{"schema":{"type":"string","optional":false},"payload":"foo"}
{"schema":{"type":"string","optional":false},"payload":"bar"}

向源文件追加一行并观察"端到端"流动：

bash 复制代码

echo "Another line" >> test.txt

八. Kafka Streams：最小 WordCount 示例

一旦数据以事件形式进入 Kafka，你就可以使用 Kafka Streams（Java/Scala） 构建实时应用/微服务 ：支持 Exactly-Once 、有状态聚合 、窗口、事件时间 、Join 等。

示例代码片段：

java 复制代码

KStream<String, String> textLines = builder.stream("quickstart-events");

KTable<String, Long> wordCounts = textLines
        .flatMapValues(line -> Arrays.asList(line.toLowerCase().split(" ")))
        .groupBy((keyIgnored, word) -> word)
        .count();

wordCounts.toStream().to("output-topic", Produced.with(Serdes.String(), Serdes.Long()));

运行方式可参考 Kafka 自带的 Streams Demo 与应用教程：启动拓扑、订阅输入主题、查看输出主题（output-topic）即可。

九. 停止与清理

使用 Ctrl-C 依次停止 Producer/Consumer
使用 Ctrl-C 停止 Kafka Broker
若需要清空本地数据（包括你刚刚写入的事件）：

bash 复制代码

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

十. 常见问题与排查

Java 版本不匹配 ：需 Java 17+ ；java -version 检查
端口被占用 ：9092 被占用会导致启动失败；释放或改端口
Docker 访问异常 ：检查容器日志、网络与 advertised.listeners 设置
Connect 启不来 ：确认 plugin.path 路径与 connect-file-4.0.0.jar 文件存在
Windows echo -e 无效：按上文 Windows 示例逐行写入