安装与配置

Kafka 在 Windows 下的两种安装方式（Zookeeper 模式 / KRaft 模式）、启停脚本，以及 Broker / Topic / JVM 核心配置参数详解。

适用 Kafka 版本: 3.x / 4.x（KRaft 模式）

Windows

方式一：Zookeeper 模式（Kafka 3.x 及之前）

Kafka 下载地址

Windows 选择 Binary download，推荐选择稳定版本。

配置步骤

1. 在 Kafka 根目录中创建一个 kafka-logs 目录，用于存放消息日志：

   

2. 配置 config 目录下的 server.properties 文件：

   # 指定日志存储路径
   log.dirs=/kafka-logs

   注意：路径中使用正斜杠 /，避免 Windows 反斜杠转义问题。

启动 Zookeeper

注意：Kafka 默认解压后的目录名较长，在 Windows 下可能因路径过长导致命令执行失败。建议将 Kafka 根目录重命名为短名称，例如 kafka。

进入 Kafka 根目录，执行：

# 启动 Zookeeper（第一个窗口）
.\bin\windows\zookeeper-server-start.bat .\config\zookeeper.properties

看到上述日志输出即表示 Zookeeper 启动成功。

启动 Kafka

保持 Zookeeper 窗口不关闭，新建一个 cmd 窗口，进入 Kafka 根目录，执行：

# 启动 Kafka Broker（第二个窗口）
.\bin\windows\kafka-server-start.bat .\config\server.properties

等待片刻，看到如下日志即表示 Kafka Broker 启动成功：

启停注意事项

一键启动脚本

将以下内容保存为 start-kafka.bat，注意将 KAFKA_HOME 替换为你的实际路径：

@echo off
chcp 65001 > nul
TITLE Kafka 启动器 - kafka_2.13-3.9.0

SETLOCAL

set KAFKA_HOME=D:\dev\Kafka\kafka

if not exist "%KAFKA_HOME%" (
    echo ❌ 错误：KAFKA_HOME 路径不存在: %KAFKA_HOME%
    pause
    exit /b 1
)

cd /d %KAFKA_HOME%

:: 清理残留的锁文件和 PID 文件（防止上次异常退出导致启动冲突）
if exist "logs\*.lock" del /Q "logs\*.lock"
if exist "logs\*.pid"  del /Q "logs\*.pid"

:: 启动 ZooKeeper
echo ▶️ 正在启动 ZooKeeper...
start "ZooKeeper" /D "%KAFKA_HOME%" call bin\windows\zookeeper-server-start.bat config\zookeeper.properties

:: 等待 ZooKeeper 初始化完成
timeout /t 7 > NUL

:: 启动 Kafka
echo ▶️ 正在启动 Kafka Server...
call bin\windows\kafka-server-start.bat config\server.properties

echo ✅ Kafka 已成功启动！
pause

一键关闭脚本

将以下内容保存为 stop-kafka.bat：

@echo off
chcp 65001 > nul
TITLE Kafka 关闭器 - kafka_2.13-3.9.0

SETLOCAL

set KAFKA_HOME=D:\dev\Kafka\kafka

if not exist "%KAFKA_HOME%" (
    echo ❌ 错误：KAFKA_HOME 路径不存在: %KAFKA_HOME%
    pause
    exit /b 1
)

cd /d %KAFKA_HOME%

:: 优雅停止 Kafka
echo ⏹️ 正在尝试优雅地停止 Kafka...
call "%KAFKA_HOME%\bin\windows\kafka-server-stop.bat"

:: 等待 Kafka 进程结束（最多等待 30 秒）
call :wait_for_process_exit "kafka" 30
if errorlevel 1 (
    echo ⚠️ Kafka 进程未能在指定时间内退出，请检查日志或手动终止。
)

:: 优雅停止 ZooKeeper
echo ⏹️ 正在尝试优雅地停止 ZooKeeper...
call "%KAFKA_HOME%\bin\windows\zookeeper-server-stop.bat"

:: 等待 ZooKeeper 进程结束（最多等待 30 秒）
call :wait_for_process_exit "zookeeper" 30
if errorlevel 1 (
    echo ⚠️ ZooKeeper 进程未能在指定时间内退出，请检查日志或手动终止。
)

echo ✅ Kafka 和 ZooKeeper 已尝试优雅关闭。
pause
exit /b 0


:: ============ 函数区 ============

:: 等待指定关键字的 Java 进程退出
:wait_for_process_exit
setlocal
set keyword=%~1
set timeout=%~2
set count=0

echo 🔍 正在等待 [%keyword%] 进程退出，最多等待 %timeout% 秒...

:loop
tasklist | findstr /i java >nul && (
    tasklist | findstr /i %keyword% >nul && (
        if %count% lss %timeout% (
            timeout /t 1 >nul
            set /a count+=1
            goto loop
        ) else (
            endlocal
            exit /b 1
        )
    )
)

endlocal
exit /b 0

安装注意事项与常见问题

1. 目录与路径

• 避免路径中包含空格和特殊字符（如中文、括号等）
• Windows 路径有长度限制（260 字符），建议将 Kafka 放在盘符根目录下
• 配置文件中使用正斜杠 / 替代反斜杠 \

2. 内存与 JVM 配置

• Kafka 默认 JVM 堆内存较大（1GB+），本地开发可根据机器配置适当调小 KAFKA_HEAP_OPTS
• JDK 版本匹配：Kafka 3.x 和 4.x 建议使用 JDK 11 或 JDK 17

3. KRaft 模式

• Kafka 4.x 开始默认采用 KRaft 模式管理集群（不再依赖 Zookeeper）
• 启动前必须执行 kafka-storage.bat format 格式化元数据，否则 Broker 会因找不到 meta.properties 文件而启动失败
• 在 server.properties 中，process.roles 决定节点的角色：broker（存储数据）、controller（管理集群）或 broker,controller（两者兼有）。本地单机测试建议保持默认即可

参考资料：Windows 下 Kafka 安装教程（保姆级）

方式二：KRaft 模式（Kafka 4.x 推荐，无需 Zookeeper）

KRaft（Kafka Raft）是 Kafka 自 3.x 开始引入的元数据管理协议，用于替代 Zookeeper。在 4.x 版本中已成为默认模式。

使用 Scoop 安装

scoop search kafka
scoop install kafka

配置步骤

1. 配置日志生成路径

• 在 Kafka 目录中创建一个日志文件夹：

  

• 修改 server.properties，将 log.dirs 指向该路径：

  

  注意：Windows 下路径中的反斜杠需要使用 \\ 进行转义。

2. 生成集群 ID

kafka-storage.bat random-uuid

执行后会生成一串 UUID，将其复制下来备用。

3. 格式化元数据日志目录

这一步告诉 Kafka 当前节点在集群中的角色以及如何初始化共识机制：

kafka-storage.bat format -t <你的集群ID> -c ..\..\config\server.properties --standalone

参数说明：

执行格式化命令后，日志目录下会生成三个文件夹（图中因为已经运行过，所以会多一些运行时文件）。

4. 启动 Kafka

kafka-server-start.bat ..\..\config\server.properties

出现以上日志提示即表示 Kafka 启动成功。

Linux

暂时未涉及，后续补充。

Docker

暂时未涉及，后续补充。

Kafka 重要配置

Broker 端配置

broker.id

每个 Broker 的唯一标识符，默认值为 0。在集群中必须唯一，可以设为任意整数值。

port

Kafka 默认监听 9092 端口。可修改为任意端口，但注意使用 1024 以下的端口需要 root 权限。

zookeeper.connect（Zookeeper 模式）

指定 Zookeeper 地址，格式为 hostname:port/path。多个地址用逗号分隔。

• hostname：Zookeeper 服务器的机器名或 IP
• port：Zookeeper 客户端端口（默认 2181）
• /path：可选的 Zookeeper 路径（chroot 环境）。如果不指定，默认使用根路径。

示例：如果有两套 Kafka 集群 kafka1 和 kafka2，可以这样配置：

• kafka1：zk1:2181,zk2:2181,zk3:2181/kafka1
• kafka2：zk1:2181,zk2:2181,zk3:2181/kafka2

log.dirs

Kafka 将所有消息持久化到磁盘，日志片段的存放目录通过 log.dirs 指定（用逗号分隔多个本地路径）。此参数没有默认值，必须手动指定。

还有一个 log.dir 参数（不含末尾的 s），一般情况下只配置 log.dirs 即可。例如：/home/kafka1,/home/kafka2,/home/kafka3

num.recovery.threads.per.data.dir

在以下三种情况下，Kafka 会使用可配置的线程池来处理日志片段：

• 服务器正常启动，打开每个分区的日志片段
• 服务器崩溃后重启，检查和截断每个分区的日志片段
• 服务器正常关闭，关闭日志片段

默认每个日志目录只使用 1 个线程。对于分区数量较多的服务器，增大此值可以显著缩短崩溃恢复时间（可能省下数小时）。注意：该数值对应的是每个日志目录的线程数。例如设为 8 且 log.dirs 指定了 3 个路径，则总共需要 24 个线程。

auto.create.topics.enable

默认情况下，Kafka 在以下三种场景会自动创建不存在的 Topic：

• 生产者开始往某个 Topic 写入消息
• 消费者开始从某个 Topic 读取消息
• 任意客户端向某个 Topic 发送元数据请求

建议：生产环境将 auto.create.topics.enable 设为 false，避免因拼写错误意外创建 Topic。

Topic 默认配置

Kafka 为新创建的主题提供了丰富的默认配置参数：

num.partitions

新创建 Topic 的默认分区数，默认值为 1。

注意：分区数可以后续增加，但不能减少。创建时应合理预估分区数。

default.replication.factor

消息的默认副本数，默认值为 1。如果副本失效，其他副本可以继续提供服务。该参数仅在启用了自动创建 Topic 时有效。

log.retention.ms

Kafka 根据时间判断数据可以保留多久。log.retention.ms 是最推荐使用的配置参数（另有 log.retention.hours 和 log.retention.minutes，作用相同），默认值为 168 小时（7 天）。

log.retention.bytes

按磁盘空间大小判断消息是否过期。该参数作用在每个分区上。例如，一个 8 分区的 Topic，log.retention.bytes 设为 1GB，则 Topic 最多保留 8GB 数据。分区数增加时，整个 Topic 可保留的总数据量也随之增加。

log.segment.bytes

日志是按"片段（Segment）“管理的。当消息到达 Broker 时，它们被追加到当前片段。当片段大小达到 log.segment.bytes 上限（默认 1GB）时，当前片段被关闭并创建新片段。被关闭的片段开始等待过期清理。该值设得太小会导致频繁关闭和创建新文件，降低磁盘写入效率。

log.segment.ms

指定日志片段在多长时间后被强制关闭。和 log.segment.bytes 不互斥——哪个条件先触发就按哪个执行。

message.max.bytes

限制单条消息的最大大小（压缩后），默认 1MB。如果生产者发送超过此限制的消息，Broker 会拒绝并返回错误。

该值越大，处理网络连接和请求的线程耗时越长，磁盘写入块也越大，影响 I/O 吞吐量。

retention.ms（Topic 级别）

指定该 Topic 的消息保存时长，默认 7 天。该值设置后会覆盖 Broker 端的全局参数。

retention.bytes（Topic 级别）

指定为该 Topic 预留的最大磁盘空间。默认值 -1 表示无限使用。多租户 Kafka 集群中特别有用。

JVM 参数配置

JDK 版本推荐：新项目直接选择 JDK 17（很多框架新版本已不再支持 JDK 8）。以下以 JDK 8 为例讲解 GC 配置。

堆内存（Heap Size）

业界广泛推荐直接将 JVM 堆大小设为 6GB，这样能避免很多内存相关的异常。

垃圾回收器（GC）选择

• 如果还在使用 Java 7：
  • CPU 资源充裕 → 使用 CMS 收集器（-XX:+UseConcMarkSweepGC）
  • 否则 → 使用吞吐量收集器（-XX:+UseParallelGC）
• Java 8 及以上 → 直接使用默认的 G1 收集器即可。在无任何调优的情况下，G1 表现优于 CMS（更少的 Full GC、更少的调优参数）。

G1 的两个关键参数：

参考资料

• Windows 下 Kafka 安装教程（保姆级）
• Kafka 中文文档 - ApacheCN