很多刚接触消息队列的同事问我Kafka 在 Linux 上到底怎么装网上教程五花八门有的让你先装 ZooKeeper 再装 Kafka有的说新版本根本不需要 ZooKeeper照着抄还经常报错。这篇文章我把从环境准备到功能验证的完整链路串一遍把我踩过的坑和排查思路都写出来你照着走一遍就能跑起来也能明白每一步为什么要这么做。这篇内容适合三类人看一是刚入行要搭开发环境的新手开发二是要在测试或生产环境部署 Kafka 的运维同学三是想搞懂 Kafka 安装背后那些配置参数含义、避免能启动但不好用的进阶用户。不管你是 CentOS 系还是 Ubuntu 系核心步骤都是通用的命令和配置我会分开讲清楚。下面直接进入正题。1. 环境准备与前置条件1.1 Java 环境版本别乱选Kafka 是 Java 写的跑之前必须先备好 JDK。Kafka 2.x 对 Java 8 兼容最好Kafka 3.x 支持 Java 8 / 11 / 17但新版本在 JDK 8 上运行会有不少警告某些加密和压缩相关功能表现也不太稳定。我建议直接装 JDK 11 或 17别在太老的版本上省事。先检查系统里有没有 Javajava -version如果提示 command not found就装一个。CentOS / RHEL 系用sudo yum install -y java-11-openjdkUbuntu / Debian 系用sudo apt update sudo apt install -y openjdk-11-jdk装完再执行java -version确认能够输出版本号。这里有一个容易忽略的点很多服务器默认装了 OpenJDK 8如果你要装 Kafka 3.5 以上的版本建议直接把系统默认 JDK 切到 11 或 17否则控制台会刷一堆已过时 API之类的警告虽然不致命但排查问题的时候会很干扰视线。1.2 内存、磁盘与文件描述符规划Kafka 是 JVM 应用默认启动脚本会给堆内存设一个值。官方默认的KAFKA_HEAP_OPTS一般是 1G 左右。开发环境机器有 2G 内存勉强够跑但建议单独给 Kafka 留出 1G 以上的堆空间。生产环境根据分区数和消息吞吐量堆内存通常给到 6G 到 8G不是越大越好堆太大反而会增加 GC 停顿。磁盘方面要特别注意一个概念Kafka 的消息是落盘的不是纯内存。所以log.dirs对应的数据目录要提前规划好挂载点。SSD 性能和稳定性都优于机械盘机械盘能跑但吞吐上限明显低。数据保留时间默认是log.retention.hours168也就是 7 天磁盘容量最好按每天写入量 × 保留天数再留 20% 余量去估算。文件描述符限制也要提前看一下ulimit -n如果显示 1024 或者更小Kafka 在高连接数场景下会出现 Too many open files。开发环境可以临时调大ulimit -n 65535持久化修改在/etc/security/limits.conf里加两行* soft nofile 65535 * hard nofile 65535改完重新登录再ulimit -n验证。1.3 下载 Kafka版本命名规则先搞懂到 Apache Kafka 官网下载页挑一个稳定版。下载的文件名长这样kafka_2.13-3.6.2.tgz前半段2.13是编译 Kafka 时用的 Scala 版本后半段3.6.2才是 Kafka 的版本号。这个命名经常让人迷糊记住一点平时判断 Kafka 功能特性和 API 兼容性看后半段只有个别客户端库的依赖坐标才和 Scala 版本有关安装阶段基本不用管它。下载命令wget https://downloads.apache.org/kafka/3.6.2/kafka_2.13-3.6.2.tgz下载完建议做一下校验把对应的.sha512文件也拉下来sha512sum kafka_2.13-3.6.2.tgz和官网公布的哈希值对比一致再解压。这一步看起来啰嗦但在生产环境值得做既能防止下载损坏也能确认你拿到的确实官方产物。2. 部署模式选型与核心配置2.1 先想清楚用 ZooKeeper 还是 KRaft早期 Kafka 必须搭配 ZooKeeper 做元数据管理和选主所以很多老教程都是先起 ZooKeeper再起 Kafka。Kafka 从 2.8 版本开始引入 KRaft 模式Kafka Raft把元数据管理收编进 Kafka 自身不再需要单独的 ZooKeeper 进程。3.3 之后 KRaft 达到生产可用级别新版本官方已经在推动全面切换。两种模式怎么选我直接给结论场景推荐模式新部署版本 3.6 及以上KRaft少维护一个组件少一个故障点存量 ZooKeeper 集群版本较老继续 ZooKeeper 模式稳定优先别急着折腾本地开发学习KRaft步骤少一大截专注 Kafka 本身这个决定要提前做因为同一个 Kafka 包两种模式都支持只是启动命令和配置文件不同。老教程的启动思路放在 KRaft 上会直接报错反过来也一样。搞混了最常见的现象就是启动 Kafka 时反复提示连不上 2181 端口其实你压根没起 ZooKeeper。2.2 server.properties 关键参数逐项拆解不管哪种模式最核心的配置文件都是server.propertiesKRaft 模式在config/kraft/目录下。我把最重要的参数按重要性逐个讲。broker.id每个 broker 的唯一编号集群里不能重复单节点默认 0。listeners 与 advertised.listeners这是新手最容易踩坑的地方。listeners是 Kafka 进程真正监听的地址端口advertised.listeners是要告诉客户端你该连哪个地址。如果你在云服务器上部署外网客户端连不上十有八九是advertised.listeners还写着localhost:9092。客户端拿到这个地址去连当然连不上。正确写法是listenersPLAINTEXT://0.0.0.0:9092 advertised.listenersPLAINTEXT://服务器公网IP或内网IP:90920.0.0.0表示监听所有网卡适合服务器。单机学习用localhost没问题但只要跨机器访问就必须把 advertised 改成对端可达的地址。log.dirs消息数据存放目录可以配多个逗号分隔。log.dirs/data/kafka-logs不建议放系统盘根目录下给一个独立数据盘最稳。记得先建目录mkdir -p /data/kafka-logszookeeper.connect仅 ZooKeeper 模式需要格式是host:port/chroot。单机写localhost:2181集群写node1:2181,node2:2181,node3:2181。后面的/chroot是可选路径用于多个 Kafka 集群共用一套 ZooKeeper 时做隔离新手一般用不上。副本相关参数单机跑无所谓集群环境要重点关注。比如offsets.topic.replication.factor如果集群只有 1 个 broker保持默认即可生产集群要评估每类 topic 的副本因子避免关键 topic 的副本长期处于不足状态触发无休止的报警。2.3 JVM 与网络参数调整JVM 参数通过环境变量KAFKA_HEAP_OPTS传入在启动脚本里会读取export KAFKA_HEAP_OPTS-Xms2g -Xmx2g内存紧张的机器不要把 Xms 和 Xmx 设成一样大虽然一样大能避免扩容抖动但小内存机器可能启动就 OOM。开发机我一般设-Xms512m -Xmx1g够用且不浪费。网络层面的 socket 缓冲区也建议看一下socket.send.buffer.bytes102400 socket.receive.buffer.bytes102400默认单位是字节100KB 是在内网低延迟场景下的平衡值。跨机房或公网传输时可以适当调大到 512KB 或 1MB减少网络吞吐瓶颈。不过单机开发不用动保持默认就好。3. 实操全流程从解压到消息收发3.1 解压、用户与数据目录tar -xzf kafka_2.13-3.6.2.tgz mv kafka_2.13-3.6.2 /opt/kafka cd /opt/kafka目录里几个关键子目录先说清楚bin/所有启停和运维脚本config/broker、zookeeper、kraft 等配置都在这里libs/运行依赖的 jar 包logs/运行日志默认输出目录我习惯给 Kafka 建一个独立系统用户不用 root 跑。好处是权限隔离数据和日志的属主统一进程也不会拿到过大的系统权限sudo useradd -r -s /bin/false kafka sudo chown -R kafka:kafka /opt/kafka /data/kafka-logs生产环境用非 root 用户跑 JVM 是基本素养等于给风险上了一道锁。3.2 KRaft 模式启动新版本推荐KRaft 模式不再需要启动 ZooKeeper步骤精简为三步生成集群 ID、格式化存储目录、启动。# 生成集群唯一 ID export KAFKA_CLUSTER_ID$(bin/kafka-storage.sh random-uuid) # 格式化存储目录 bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c config/kraft/server.properties # 启动 bin/kafka-server-start.sh config/kraft/server.properties启动日志里看到Startup complete之类的字样就说明起来了。如果最后一行卡住不动先别急观察 10 到 30 秒再看端口状态ss -lntp | grep 90929092 端口能被监听到就正常。特别提醒一句format命令会在log.dirs配置的目录下生成元数据如果这个目录里已有数据格式化会把它清掉。执行之前确认目录是空的或者你已经做了备份。3.3 ZooKeeper 模式启动老版本或存量环境如果你用的是 2.8 之前的版本或者公司环境要求用 ZooKeeper 模式流程是双进程# 先启动 ZooKeeper bin/zookeeper-server-start.sh -daemon config/zookeeper.properties # 再启动 Kafka bin/kafka-server-start.sh config/server.propertiesZooKeeper 默认监听 2181 端口。-daemon参数会让进程在后台运行。第一次启动时 ZooKeeper 会生成一堆初始化日志看到binding to port就可以认为起来了。这里有个常见问题ZooKeeper 还没完全就绪Kafka 就急着去连 2181会报 Connection refused。解决方案是启动 ZooKeeper 后等几秒或者看日志确认监听端口再启 Kafka。不要一看到错误就以为 ZooKeeper 装坏了顺序和时序往往才是问题根源。3.4 功能验证创建 Topic、生产与消费启动完成后用自带命令行工具验证整条链路。创建 topicbin/kafka-topics.sh --create --topic test-topic \ --bootstrap-server localhost:9092 \ --partitions 1 --replication-factor 1这里是新版客户端的连接方式。老教程里的--zookeeper参数在新版本已经废弃不要再抄了。查看 topic 列表bin/kafka-topics.sh --list --bootstrap-server localhost:9092开一个终端生产消息bin/kafka-console-producer.sh --topic test-topic --bootstrap-server localhost:9092输入几行文字CtrlC 退出。再新开一个终端消费bin/kafka-console-consumer.sh --topic test-topic \ --from-beginning --bootstrap-server localhost:9092能看到生产端输入的内容说明从安装到配置全部跑通了。新手常问的一个点如果消费端不加--from-beginning默认只消费启动之后新产生的消息。这是 Kafka 消费者 offset 机制的正常表现不是 bug。想消费历史消息就加这个参数否则默认从最新 offset 开始。3.5 注册为 systemd 服务实现开机自启手动前台启动只适合临时验证。正式环境建议注册成 systemd 服务进程崩了能自动拉起重启机器也不用操心。写一个 service 文件/etc/systemd/system/kafka.serviceKRaft 版示例[Unit] DescriptionApache Kafka Server Requiresnetwork.target remote-fs.target Afternetwork.target remote-fs.target [Service] Typesimple Userkafka Groupkafka ExecStart/opt/kafka/bin/kafka-server-start.sh /opt/kafka/config/kraft/server.properties ExecStop/opt/kafka/bin/kafka-server-stop.sh Restarton-failure LimitNOFILE65535 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable kafka sudo systemctl start kafka sudo systemctl status kafka实时看日志用journalctl -u kafka -f这里有一个坑必须提醒Kafka 自带的kafka-server-start.sh是前台阻塞方式systemd 用Typesimple正合适。千万别用Typeforking否则 systemd 会以为进程没起来反复尝试启动最后演变成端口冲突和重复进程。4. 常见问题与排查技巧实录4.1 启动失败端口被占用报错一般是Address already in use或BindException。排查思路ss -lntp | grep 9092如果端口被占先确认是残留的 Kafka 进程还是别的程序ps -ef | grep kafka解决方案是 kill 掉多余进程后重启。还有一种常见情况是重复执行了两次启动命令两个进程抢同一个端口把后启动的那个干掉就行。4.2 客户端连不上Connection refused 或 Timed out这是最高频的问题。按顺序排查本机测telnet 127.0.0.1 9092确认服务本身活着。另一台机器测telnet 服务器IP 9092不通就查防火墙和安全组规则。如果端口通但客户端依旧报Connection to node -1 could not be established重点检查advertised.listeners。客户端先连 bootstrap 地址拿到元数据之后会用 advertised 地址去连 broker。如果这里写的还是 localhost就会出现bootstrap 能连上但 broker 连不上的诡异现象。确认客户端机器能解析服务器的主机名配置里如果用了主机名而 hosts 没配好一样会连接失败。4.3 生产消息报 LEADER_NOT_AVAILABLE刚启动完立刻生产消息偶尔会报这个错。原因是 topic 的 leader 还在选举或元数据还没同步完。等几秒重试即可不用慌。但如果是集群长期报这个错就要检查副本同步状态了bin/kafka-topics.sh --describe --topic test-topic --bootstrap-server localhost:9092看Isr列里的副本是否和Replicas列一致。不一致说明有 broker 掉线或网络分区需要检查对应节点的进程和网络。4.4 消费者收不到消息先分清是收不到还是收不到历史消息。加--from-beginning能收到旧消息说明 topic 本身正常只是消费者默认从最新 offset 开始消费。如果加了参数还是收不到检查advertised.listeners和防火墙消费者和生产者不在同一个网络时最容易出这类问题。还有一个容易被忽略的点多个消费者组用了相同的组名逻辑上却各自独立维护 offset看起来像数据被别的组消费了实际是组名冲突。排查时用下面命令看消费组列表bin/kafka-consumer-groups.sh --list --bootstrap-server localhost:90924.5 日志报 Too many open files这是文件描述符资源耗尽。先看当前限制ulimit -n再看 Kafka 进程实际打开的 fd 数ls /proc/$(pgrep -f kafka | head -1)/fd | wc -l处理方式systemd 服务在 Unit 里加LimitNOFILE65535手动启动的话先ulimit -n 65535再起服务。长期高并发环境还要关注 socket 缓冲区大小必要时调大socket.send.buffer.bytes和socket.receive.buffer.bytes。4.6 磁盘空间告警Kafka 不会在磁盘满时自动清理所有数据它只按log.retention.*策略删除过期 segment。如果磁盘即将写满宁可提前调大 retention 删除频率或者手工删除不用的 topic也不要让 broker 因为磁盘写满直接挂掉。建议用df -h定期巡检生产环境把磁盘使用率接进监控告警。4.7 集群节点时间不同步分布式集群里broker 之间时间偏差过大会导致会话异常和选举混乱。集群场景务必配置好时间同步sudo timedatectl set-ntp yes单机开发不用管但只要集群超过一个节点时间同步就是前提条件。很多诡异的偶发连接断开问题最后查出来都是节点时间漂移。问题现象优先排查项解决建议9092 端口未监听启动日志、JVM 配置检查堆内存和日志输出客户端连不上advertised.listeners、防火墙改成可达地址放行端口生产报 leader 不可用副本同步状态等待选举检查 Isr消费不到消息消费者组、offset 策略加 --from-beginning 验证Too many open filesulimit、fd 数量调大 nofile 限制磁盘即将写满df 使用率清理 topic 或调短 retention最后分享一个体会我帮别人排查安装问题十次连不上有八次出在advertised.listeners上剩下两次是防火墙。这个参数的理解程度基本决定了你对 Kafka 网络模型的掌握水平。另外如果你是新部署环境直接上 KRaft 模式省掉 ZooKeeper 之后维护成本低很多如果公司已有存量 ZooKeeper 集群稳定优先别为了用新功能贸然迁移。照着这篇把环境准备、模式选型、配置修改、启动验证和问题排查过一遍你的 Kafka 服务就能稳稳跑起来了。