企业官网建设流程全解析

上一篇：【第01篇】Kafka是什么——从LinkedIn的救火队到全球消息中间件之王
下一篇：【第03篇】Kafka核心概念图解——Topic、Partition、Offset、Broker一次看懂

摘要

上回书说到，Kafka是LinkedIn工程师在数据管道危机中搓出的"救火神器"。光说不练假把式，这一篇咱们就撸起袖子，把Kafka真真切切地跑到自己电脑上。

本文将覆盖Windows、macOS和Linux三大平台的安装全流程。从JDK环境准备，到下载解压Kafka，再到核心配置文件详解，最后用一条命令验证服务启动成功。特别地，我们会重点介绍Kafka 3.3+引入的KRaft模式——它让你彻底告别ZooKeeper这个"额外包袱"，单进程就能跑起一个完整的Kafka服务，对学习和开发环境来说简直是福音。

读完这篇，你的电脑上将有一个正在运行的Kafka实例，可以收发消息——这将是后续所有实战和源码分析的基础。

一、前置准备：JDK的安装与配置

Kafka是用Java和Scala写的，所以JDK是硬性依赖。不同版本的Kafka对JDK版本要求不同：

注意：从Kafka 3.0开始，官方逐步移除了对JDK 8的支持。如果你用的是Kafka 3.7+，请至少装JDK 11。

1.1 Windows 平台安装 JDK

1. 打开浏览器，访问 https://adoptium.net/ （Eclipse Temurin，开源免费） 2. 下载 JDK 17（或JDK 21）的 Windows x64 MSI安装包 3. 双击安装，一路Next（建议安装路径不要带空格，如 C:\Java\jdk-17） 4. 安装完验证：

# 打开PowerShell或CMD，输入java-version# 输出类似：# openjdk version "17.0.9" 2023-10-17# OpenJDK Runtime Environment Temurin-17.0.9+9 (build 17.0.9+9)# OpenJDK 64-Bit Server VM Temurin-17.0.9+9 (build 17.0.9+9, mixed mode, sharing)

# 如果提示 "java 不是内部命令"，需要设置环境变量：# 1. 右键"此电脑" → 属性 → 高级系统设置 → 环境变量# 2. 新建系统变量：JAVA_HOME = C:\Java\jdk-17# 3. 编辑Path变量，新增：%JAVA_HOME%\bin# 4. 重新打开CMD，再试 java -version

1.2 macOS 平台安装 JDK

macOS上推荐用Homebrew，一行命令搞定：

# 如果没有Homebrew，先去 https://brew.sh 安装# 装完Homebrew后：brewinstallopenjdk@17# 创建软链接让系统识别sudoln-sfn/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk# 验证java-version

或者从 adoptium.net 下载 .pkg 安装包，双击安装即可。

1.3 Linux 平台安装 JDK

以Ubuntu/Debian为例：

# 更新软件源sudoaptupdate# 安装 JDK 17sudoaptinstallopenjdk-17-jdk-y# 验证java-version

以CentOS/RHEL为例：

sudoyuminstalljava-17-openjdk-devel-yjava-version

二、下载 Kafka

前往 Apache Kafka 官网下载：https://kafka.apache.org/downloads

选择版本建议：

本文以 Kafka 3.9.0 为例：

# Linux/macOSwgethttps://downloads.apache.org/kafka/3.9.0/kafka_2.13-3.9.0.tgztar-xzfkafka_2.13-3.9.0.tgzcdkafka_2.13-3.9.0# Windows（用PowerShell）# 1. 浏览器下载 kafka_2.13-3.9.0.tgz# 2. 用7-Zip或WinRAR解压到 C:\kafka# 3. PowerShell进入目录cdC:\kafka\kafka_2.13-3.9.0

文件名解读：kafka_2.13-3.9.0.tgz中2.13是Scala版本，3.9.0是Kafka版本。Kafka用Scala编写，不同Scala版本的Kafka性能略有差异但功能完全一致。

解压后的目录结构：

kafka_2.13-3.9.0/ ├── bin/ # 启动脚本和命令行工具（.sh for Linux/Mac, .bat for Windows） │ ├── kafka-server-start.sh │ ├── kafka-topics.sh │ ├── kafka-console-producer.sh │ ├── kafka-console-consumer.sh │ └── ... ├── config/ # 配置文件，我们主要改这里的文件 │ ├── server.properties │ ├── kraft/ │ │ └── server.properties # KRaft模式专用配置 │ ├── consumer.properties │ └── producer.properties ├── libs/ # Kafka依赖的所有jar包 ├── logs/ # 默认日志输出目录 └── LICENSE, NOTICE...

三、KRaft模式启动 Kafka（推荐）

Kafka从3.3.1版本开始，KRaft（Kafka Raft）模式正式进入生产可用状态。对于学习和开发环境，KRaft模式是绝对的首选——你不再需要先启动ZooKeeper再启动Kafka，一个进程搞定一切。

3.1 KRaft 模式与传统 ZooKeeper 模式对比

传统 ZooKeeper 模式： ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ZooKeeper│ │ ZooKeeper│ │ ZooKeeper│ ← 3个ZK节点（选举用） └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └───────────────┼───────────────┘ │ ┌───────────────┼───────────────┐ │ │ │ ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ │ Broker │ │ Broker │ │ Broker │ ← Kafka节点 └──────────┘ └──────────┘ └──────────┘ 至少4个进程，维护复杂 KRaft 模式（Kafka 3.3+）： ┌──────────────────────────────┐ │ Kafka (Controller + Broker) │ ← 自带Raft共识 │ 内嵌 Raft 元数据管理 │ 无需外部依赖 └──────────────────────────────┘ 单进程即可运行，清爽！

3.2 第一步：生成集群ID

# Linux/macOSbin/kafka-storage.sh random-uuid# 输出类似：7XcG9ZT4SoO0h5KjR8vBkQ# Windows PowerShell.\bin\windows\kafka-storage.bat random-uuid# 输出类似：7XcG9ZT4SoO0h5KjR8vBkQ

把这串UUID记下来，下一步要用。

3.3 第二步：格式化存储目录

# Linux/macOS（用上一步生成的UUID）bin/kafka-storage.shformat\-t<你的UUID>\-cconfig/kraft/server.properties# Windows PowerShell.\bin\windows\kafka-storage.batformat`-t<你的UUID>`-cconfig\kraft\server.properties

格式化成功后你会看到：

Formatting /tmp/kraft-combined-logs with metadata.version 3.9-IV0

3.4 第三步：启动Kafka！

# Linux/macOSbin/kafka-server-start.sh config/kraft/server.properties# Windows PowerShell.\bin\windows\kafka-server-start.bat config\kraft\server.properties

如果一切顺利，你会看到大量日志输出，最后几行类似：

[2026-05-30 10:00:00,123] INFO Kafka version: 3.9.0 (org.apache.kafka.common.utils.AppInfoParser) [2026-05-30 10:00:00,456] INFO Kafka startTimeMs: 1717056000456 (org.apache.kafka.server.KafkaServer) [2026-05-30 10:00:01,789] INFO [KafkaRaftServer nodeId=1] Kafka Server started (kafka.server.KafkaRaftServer)

Windows用户注意：如果启动报错提示找不到JAVA_HOME或java命令，请确保JDK已正确安装且PATH中包含%JAVA_HOME%\bin，然后重启PowerShell再试。

3.5 验证：创建一个Topic并收发消息

留着一个终端窗口跑Kafka，新开一个终端来验证：

# Step 1: 创建一个测试Topic# Linux/macOSbin/kafka-topics.sh--create\--topichello-kafka\--bootstrap-server localhost:9092\--partitions3\--replication-factor1# Windows PowerShell.\bin\windows\kafka-topics.bat--create`--topichello-kafka`--bootstrap-server localhost:9092`--partitions3`--replication-factor1# 输出：Created topic hello-kafka.

# Step 2: 启动一个生产者，发送消息# Linux/macOSbin/kafka-console-producer.sh\--topichello-kafka\--bootstrap-server localhost:9092# Windows PowerShell.\bin\windows\kafka-console-producer.bat`--topichello-kafka`--bootstrap-server localhost:9092# 此时终端进入交互模式，逐行输入消息：>Hello Kafka!>你好，消息队列！>This is my first message.>(按 Ctrl+C 退出)

# Step 3: 新开第三个终端，启动一个消费者# Linux/macOSbin/kafka-console-consumer.sh\--topichello-kafka\--from-beginning\--bootstrap-server localhost:9092# Windows PowerShell.\bin\windows\kafka-console-consumer.bat`--topichello-kafka`--from-beginning ` --bootstrap-server localhost:9092

如果消费者终端打印出了刚才发送的三条消息，恭喜你，Kafka已经成功跑起来了！🎉

四、KRaft模式核心配置文件详解

文件路径：config/kraft/server.properties。以下是最关键的参数：

# ==================== Broker 身份 ==================== # 集群唯一ID，单节点填1即可 node.id=1 # 控制器（负责选举和元数据管理）的角色定义 # broker：仅作为数据节点 # controller：仅作为控制器节点（生产环境推荐独立部署） # broker,controller：同时承担两个角色（开发环境用这个） process.roles=broker,controller # 控制器选举时的仲裁节点列表 # 格式：node.id@host:port # 单节点只需配自己 controller.quorum.voters=1@localhost:9093 # ==================== 网络配置 ==================== # 监听器：定义Kafka绑定的地址和端口 # 格式：协议名://主机名:端口 # PLAINTEXT表示不加密，生产环境建议用SSL listeners=PLAINTEXT://:9092,CONTROLLER://:9093 # 对外通告的地址（客户端连接用） # 如果不设置，默认用listeners中配置的地址 advertised.listeners=PLAINTEXT://localhost:9092 # 协议与监听器的映射关系 listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT # ==================== 存储配置 ==================== # 日志数据存储目录（建议用SSD） log.dirs=/tmp/kraft-combined-logs # 每个Topic默认的分区数 num.partitions=1 # 每个分区的默认副本数（单节点只能设为1） default.replication.factor=1 # ==================== 日志保留策略 ==================== # 日志保留时间（小时），默认168小时=7天 log.retention.hours=168 # 或按大小保留 # log.retention.bytes=1073741824 # 1GB # 单个日志段文件大小上限（字节），默认1GB log.segment.bytes=1073741824 # ==================== ZooKeeper相关（KRaft模式不需要） ==================== # zookeeper.connect=localhost:2181 ← 已废弃，无需配置！

关键参数速查表：

五、传统 ZooKeeper 模式启动（如果需要）

虽然KRaft是大势所趋，但如果你用的是Kafka 3.3之前的版本，或者公司还在用ZK模式，这里也给出步骤：

5.1 启动 ZooKeeper

# Linux/macOSbin/zookeeper-server-start.sh config/zookeeper.properties# Windows PowerShell.\bin\windows\zookeeper-server-start.bat config\zookeeper.properties

5.2 启动 Kafka Broker

# 新开终端（ZooKeeper需要先跑起来）# Linux/macOSbin/kafka-server-start.sh config/server.properties# Windows PowerShell.\bin\windows\kafka-server-start.bat config\server.properties

5.3 ZooKeeper vs KRaft 选择建议

哪些场景还可能需要ZK？ ├── 老项目维护：Kafka 2.x 必须用ZK ├── 公司遗留集群：暂时没计划升级 └── 某些云厂商托管Kafka可能还在用ZK 哪些场景果断用KRaft？ ├── 新项目：从Kafka 3.3+开始用KRaft ├── 学习开发：KRaft单进程更方便 ├── 容器化部署：减少一个ZK容器依赖 └── 性能敏感：KRaft控制器故障恢复比ZK快

六、系统服务化（让Kafka后台运行）

开发中每次手动启动Kafka比较烦，可以做成系统服务。

6.1 Linux systemd 服务

sudovim/etc/systemd/system/kafka.service

[Unit] Description=Apache Kafka After=network.target [Service] Type=simple User=kafka ExecStart=/opt/kafka/bin/kafka-server-start.sh /opt/kafka/config/kraft/server.properties ExecStop=/opt/kafka/bin/kafka-server-stop.sh Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target

sudosystemctl daemon-reloadsudosystemctlenablekafkasudosystemctl start kafkasudosystemctl status kafka

6.2 macOS launchd 服务

# 创建 plist 文件vim~/Library/LaunchAgents/com.kafka.server.plist# 内容略（可参考brew services模式）# 或者简单用 nohup &nohupbin/kafka-server-start.sh config/kraft/server.properties>kafka.log2>&1&

6.3 Windows 后台运行

# 方法1：用PowerShell的后台JobStart-Job-ScriptBlock{Set-LocationC:\kafka\kafka_2.13-3.9.0.\bin\windows\kafka-server-start.bat config\kraft\server.properties}# 方法2：创建一个快捷方式，配置"运行方式: 最小化"# 方法3：用NSSM（Non-Sucking Service Manager）注册为Windows服务

七、常见踩坑与解决方案

7.1 “Address already in use” 端口被占用

错误信息：java.net.BindException: Address already in use 原因：9092（客户端）或9093（控制器）端口已被占用 解决： # 查看占用端口的进程（Linux/Mac） lsof -i :9092 # 或换一个端口 # 修改 listeners=PLAINTEXT://:9094 然后再启动

7.2 “The Cluster ID doesn’t match” KRaft格式化问题

错误信息：The Cluster ID xxx doesn't match stored clusterId yyy 原因：之前格式化过，现在用了不同的cluster-id 解决：删除 log.dirs 目录，重新格式化 rm -rf /tmp/kraft-combined-logs bin/kafka-storage.sh format -t <UUID> -c config/kraft/server.properties

7.3 Windows下路径过长问题

错误信息：The filename or extension is too long 原因：Kafka日志目录嵌套太深，Windows路径长度超过260字符限制 解决： 1. 把log.dirs改到短路径，如 C:\kafka-data 2. 或者启用Windows的长路径支持（注册表修改 + 组策略）

7.4 “Kafka Server started” 但消费者连不上

现象：生产者/消费者报 Connection refused 或 timeout 排查： 1. 检查 advertised.listeners 是否正确配置 2. 检查防火墙是否阻止了9092端口 3. 如果Kafka部署在虚拟机/Docker里，确保 advertised.listeners 配置了宿主机IP而非localhost

本篇小结

本文我们从零开始，在Windows/macOS/Linux三大平台上完成了Kafka的安装部署：

1. JDK是基石——装好JDK 17是后续所有操作的前提
2. KRaft模式真香——一行格式化、一行启动，告别ZooKeeper的复杂运维
3. 关键配置心中有数——listeners控制网络、log.dirs控制存储、process.roles控制角色
4. 三端验证通过了：创建Topic → 生产者发消息 → 消费者收消息，Kafka已就绪
5. 系统服务化让Kafka开机自启，不用每次手动敲命令

现在你的电脑上有一个正在运行的Kafka实例。下一篇文章，我们将深入Kafka的核心概念——Topic、Partition、Offset、Broker、Consumer Group，把Kafka的"世界观"彻底搞懂。

上一篇：【第01篇】Kafka是什么——从LinkedIn的救火队到全球消息中间件之王
下一篇：【第03篇】Kafka核心概念图解——Topic、Partition、Offset、Broker一次看懂