📚 课程目录第3章单机模式部署

3. 单机模式部署：配置文件详解与基础操作

好，到了真正动手的环节了。前面两章我们把 Kafka 的来龙去脉讲清楚了，现在咱们把袖子撸起来，真刀真枪地搭一个单机环境。这一章我会把 server.properties 里那些参数掰开揉碎讲清楚，然后带你走一遍启动、停止、验证的完整流程。最后再聊聊 kafka-topics.sh 这个最常用的命令行工具。

本章核心脉络：配置文件 → 启动/停止 → 验证部署 → 主题管理命令。这四个环节串起来，就是一个可用的单机 Kafka 环境。

3.1 server.properties：每个参数都是坑

Kafka 的配置文件在 config/server.properties。我第一次搭集群的时候，觉得这文件也就几十行，随便改改就行。结果线上出了个性能问题，查了半天才发现是某个参数没调对。嗯，从那以后我再也不敢小看这个文件了。

咱们挑几个最关键的参数来讲。其他的参数，等用到的时候再查文档也不迟。

参数名	默认值	我的建议
`broker.id`	0	单机保持 0，集群必须唯一
`listeners`	PLAINTEXT://:9092	生产环境建议绑定内网 IP
`log.dirs`	/tmp/kafka-logs	一定要改，别放 /tmp
`num.partitions`	1	测试环境可以不改，生产建议 3-6
`zookeeper.connect`	localhost:2181	单机保持默认，集群用逗号分隔

我曾经踩过的坑：log.dirs 默认指向 /tmp/kafka-logs。Linux 的 /tmp 目录在重启后会被清空！我第一次部署时没改这个参数，服务器重启后所有数据都没了。那感觉，就像写了一天代码没保存。

再看几个容易被忽略的参数：

log.retention.hours：默认 168 小时（7 天）。如果磁盘空间紧张，可以调小。我一般设 72 小时。
log.segment.bytes：默认 1GB。每个日志段文件的大小。太小会导致文件碎片多，太大会增加恢复时间。
auto.create.topics.enable：默认 true。生产环境我建议改成 false。你想想看，如果某个生产者写错了主题名，Kafka 会悄悄帮你创建一个新主题，到时候排查问题会非常头疼。

小技巧：修改配置文件前，先备份一份原始文件。我习惯在文件名上加日期后缀，比如 server.properties.20250101.bak。这样万一改错了，还能快速回退。

3.2 启动与停止：别用 kill -9

配置文件改好了，咱们来启动 Kafka。记住一个顺序：先启动 ZooKeeper，再启动 Kafka。停止的时候顺序反过来。

启动 ZooKeeper

# 启动 ZooKeeper（Kafka 自带了一个）
bin/zookeeper-server-start.sh config/zookeeper.properties

# 如果想后台运行
bin/zookeeper-server-start.sh -daemon config/zookeeper.properties

ZooKeeper 默认监听 2181 端口。启动后可以用 netstat -tlnp | grep 2181 确认一下。

启动 Kafka

# 前台启动（方便看日志）
bin/kafka-server-start.sh config/server.properties

# 后台启动
bin/kafka-server-start.sh -daemon config/server.properties

我个人习惯第一次启动用前台模式。为什么？因为如果有配置错误，前台会直接打印错误信息，方便快速定位。等确认没问题了，再切到后台模式。

优雅停止

# 停止 Kafka
bin/kafka-server-stop.sh

# 停止 ZooKeeper
bin/zookeeper-server-stop.sh

千万别用 kill -9。我曾经在测试环境图省事，直接 kill -9 干掉了 Kafka 进程。结果重启后，有些日志段文件损坏了，不得不手动修复。Kafka 的优雅关闭会做三件事：刷盘所有未写入的数据、关闭所有日志段、通知控制器进行 leader 重新选举。kill -9 会跳过这些步骤，数据丢失的风险很高。

3.3 验证部署成功：三步确认法

启动完了，怎么知道 Kafka 是不是真的跑起来了？我一般用三步来验证：

检查进程：ps aux | grep kafka，看看有没有 Kafka 进程。
检查端口：netstat -tlnp | grep 9092，确认 9092 端口在监听。
检查日志：看 logs/server.log 里有没有 started (kafka.server.KafkaServer) 字样。

如果这三步都过了，基本可以确定 Kafka 跑起来了。但说实话，这只能证明进程活着，不能证明它能正常收发消息。更靠谱的验证方式是用命令行工具创建主题、生产消费几条消息试试。

3.4 kafka-topics.sh：最常用的命令行工具

在所有命令行工具里，kafka-topics.sh 是我用得最多的一个。说白了，主题是 Kafka 的数据容器，不会管理主题就等于不会用 Kafka。

创建主题

# 创建一个名为 test-topic 的主题，1 个分区，1 个副本
bin/kafka-topics.sh --create \
  --bootstrap-server localhost:9092 \
  --topic test-topic \
  --partitions 1 \
  --replication-factor 1

这里要注意，新版本的 Kafka 推荐用 --bootstrap-server 代替老的 --zookeeper 参数。我刚开始用 2.8 版本时还习惯性地敲 --zookeeper，结果报错了。嗯，这个变化挺大的，大家注意一下。

查看主题列表

bin/kafka-topics.sh --list --bootstrap-server localhost:9092

这个命令会列出所有主题。如果刚才创建成功了，应该能看到 test-topic。

查看主题详情

bin/kafka-topics.sh --describe \
  --bootstrap-server localhost:9092 \
  --topic test-topic

输出结果会包含分区信息、leader 副本、ISR（同步副本）列表等。举个例子：

Topic: test-topic  Partition: 0  Leader: 0  Replicas: 0  Isr: 0

这个输出说明：主题 test-topic 只有一个分区（Partition 0），leader 是 broker 0，副本和 ISR 也都是 broker 0。单机模式下，这个结果很正常。

修改主题

# 增加分区数（注意：不能减少）
bin/kafka-topics.sh --alter \
  --bootstrap-server localhost:9092 \
  --topic test-topic \
  --partitions 3

分区只能增加，不能减少。这是 Kafka 的设计限制。我曾经在项目里想减少分区数，结果发现根本做不到。所以创建主题时，分区数最好一次性规划好。如果实在要减少，只能删除主题重建。

删除主题

bin/kafka-topics.sh --delete \
  --bootstrap-server localhost:9092 \
  --topic test-topic

删除主题前，记得在 server.properties 里设置 delete.topic.enable=true（默认就是 true）。否则删除命令不会生效。