第 3 章 准备一个安全的练习环境

选择本地脚本路线

本书统一采用官方压缩包与本地脚本，减少“主机地址”和“容器地址”混用。命令适用于 macOS、Linux，Windows 建议在 WSL2 的 Linux 终端运行。WSL2 里的 Java 和文件目录也应在对应 Linux 环境内准备。

你需要 Java 17 或更高版本、约 2 GB 可用内存和至少数 GB 的空闲磁盘。建议使用 Java 21。先执行：

java -version

预期输出含 17、21 或更新的受支持 Java 版本。如果系统提示找不到运行时，先安装 JDK 并确认 JAVA_HOME、PATH 指向它。看到一个 java 命令路径不代表真的装好了运行时。

到 Apache 官方下载页 或 4.1.2 归档目录 获取 kafka_2.13-4.1.2.tgz。选择二进制包，不是 source 源码包。下载目录提供签名和 SHA-512 文件，可按官方说明校验。

在下载文件所在目录执行：

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

文件名里的 2.13 是构建使用的 Scala 版本标记，不要求你先学 Scala。

隔离本书的数据

Kafka 的日志数据和程序日志不是一回事。我们把数据放在解压目录下，避免误碰其他练习实例。以下操作只用于新解压的练习目录，不要拿去格式化已有集群。

mkdir -p book-data
cp config/server.properties config/book.properties
python3 - <<'PY'
from pathlib import Path
p = Path('config/book.properties')
s = p.read_text()
data = str(Path('book-data').resolve())
lines = [line for line in s.splitlines()
         if not line.strip().startswith(('log.dirs=', 'metadata.log.dir='))]
lines.append('log.dirs=' + data)
p.write_text('\n'.join(lines) + '\n')
print('练习数据目录：' + data)
PY

这一步额外需要 Python 3。若没有 Python，也可以用文本编辑器把 config/book.properties 中的 log.dirs 改成练习目录的绝对路径，并确保没有另一条 metadata.log.dir 指向旧目录。练习路径尽量不含空格。

初始化并启动

只在第一次初始化时执行这两条：

KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
bin/kafka-storage.sh format --standalone \
  -t "$KAFKA_CLUSTER_ID" -c config/book.properties

随后启动：

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

这个终端会持续显示日志。保持它开启。另开终端时，都先 cd 到同一解压目录，再执行后文命令。localhost:9092 是本机 Broker 的访问地址。

重启时只运行启动命令，不要重新生成集群 ID 或再次格式化。停止时在服务终端按 Ctrl+C，等待进程退出。本地单节点同时承担 Broker 与 KRaft Controller 角色，用于学习；生产集群需要专门规划角色、仲裁和故障域。

如果你已经熟悉 Docker，官方还有 apache/kafka:4.1.2 镜像。本文后续命令使用解压目录中的 bin/，不要直接把容器内路径与本地路径混用。