Kafka 这套东西我第一次接触的时候是被它的概念绕晕的Topic、Partition、Offset、Consumer Group、ISR、Rebalance名词一箩筐文档一翻开就是拓扑图和配置表。但真正把它跑起来、丢几条消息进去、再从另一端捞出来你会发现核心逻辑其实很朴素——它就是一个高吞吐、可持久化、支持多消费者重复读的分布式消息队列。这篇内容面向的是准备把 Kafka 用起来的开发者可能你是个后端要给系统解耦可能你在做数据管道要把业务库的变更同步到分析侧也可能你只是面试被问烦了想亲手搭一套环境把概念坐实。我下面写的都是单机可复现的路径从环境搭建、命令行验证、客户端代码、参数取舍到踩坑排查一步步来你照着敲基本能跑通。1. 先搞清楚 Kafka 到底解决什么问题很多人学 Kafka 的第一步是背概念我觉得顺序反了。先想明白它替你挡掉了哪些麻烦后面那些名词才有落脚点。这一节我把常见的认知误区和我自己的理解路径摊开说你对照自己的业务场景能判断出到底该不该上 Kafka。1.1 消息队列的共性需求以及 Kafka 的差异点传统消息队列的诉求无非三条异步解耦、削峰填谷、广播通知。比如下单之后要发短信、加积分、写日志同步调用会让主链路变长且脆弱扔进队列让下游自己消费主流程就轻了。这部分任何队列都能做Kafka 的差异在于它把消息当成追加写的日志文件来对待而不是消费完就删的临时缓冲。这个设计带来两个直接结果。第一是持久化能力强消息按分区顺序落盘保留时间由你配置几天到几个月都行消费完不删除靠 offset 标记读到哪里。第二是吞吐量高顺序写盘加上批量发送、零拷贝单机几十万条每秒不算夸张。代价是它不擅长低延迟的单条投递也不适合做复杂的路由和优先级队列。我见过有团队拿它当 RPC 用每条消息等响应延迟抖动非常难看这是用错了地方。所以判断标准很清晰你的场景是流式数据、日志、事件、需要回放或多消费方订阅Kafka 合适你的场景是任务分发、需要精确的单条确认、消息优先级和延迟队列那还是看看别的东西。这个前置判断不做后面参数怎么调都是白费劲。1.2 三个必须刻进脑子里的概念Topic、Partition、Offset这三个词是所有困惑的源头我用一个类比讲透。把 Topic 想成一类数据的总账本比如订单事件Partition 是这本账被拆成的若干分册每册独立编号、独立追加Offset 是每册里的行号从 0 开始递增永不回退。为什么要拆成多个 Partition因为单机的写入能力有上限拆分之后不同分册可以落在不同机器上并行写、并行读这就是水平扩展的来源。但拆分也带来了两个必须接受的现实同一条消息只会落在某一个分册里所以全局顺序是没有的只有分区内有序以及消费者数量超过分区数就是浪费多出来的消费者分不到活只能干等。Offset 由消费者自己维护这也是 Kafka 和推模式队列最大的区别——消费者主动拉取并自己记录读到哪里。好处是消费节奏由自己控制慢一点也不会被服务端踢掉除非超过会话超时坏处是位移提交这件事必须自己管好提交早了会丢消息提交晚了会重复消费。后面讲消费者代码的时候这两个坑我都会展开。1.3 什么规模值得上 Kafka什么情况是杀鸡用牛刀我见过最小的一个 Kafka 集群只有一个 broker跑在一个 4 核 8G 的机器上每天处理几万条消息。这不算错但如果你只是想要一个进程间的异步通知Redis 的 List 或者更轻量的方案可能更省心。Kafka 的运维成本是实打实的你要管磁盘、管分区分布、管消费者组的位移动、管监控告警这些在小体量下并不划算。我的经验阈值是这样的日消息量在百万级以下、消费方不超过两三个、没有回放需求先别急着上用简单的队列方案过渡一旦出现多个下游各自独立消费同一份数据、需要按时间回溯重放、写入峰值是均值的数倍需要缓冲Kafka 的价值就出来了。另外还有个隐性收益它天然是一份事件日志出了问题可以拿 offset 回放复现这个排查能力在复杂系统里非常值钱。提醒一句分区数在创建 topic 时定下之后只能增加不能减少。减分区意味着数据要重新分布Kafka 不做这件事只能新建 topic 迁移。所以初始分区数宁可留点余量也别拍脑袋定太小。2. 环境搭建与第一个 Demo 跑通概念说再多不如亲手发一条消息。这一节走完整条链路起一个单机 broker、用命令行验证收发、再写一段 Java 客户端代码。所有操作都在本地完成不需要任何外部依赖。2.1 单机环境的选择与部署方式现在主流版本已经不需要额外部署协调组件了新模式叫KRaft把元数据管理内置到 Kafka 自身省掉一个进程对新手非常友好。我建议直接用它别再去折腾老的双进程组合配置项多、启动顺序还容易搞错。准备一台 Linux 或者装了 WSL 的机器装好 JDK 17Kafka 3.6 之后对 JDK 17 支持很好JDK 11 也能跑。下载二进制包解压然后改config/kraft/server.properties几个关键项# 节点角色单机就同时承担 broker 和 controller process.rolesbroker,controller node.id1 # 控制器的投票成员单机就写自己 controller.quorum.voters1localhost:9093 # 监听地址内网测试用 PLAINTEXT 即可 listenersPLAINTEXT://:9092,CONTROLLER://:9093 advertised.listenersPLAINTEXT://localhost:9092 # 日志目录别放系统盘 log.dirs/data/kafka-logs # 单机测试先把副本因子调成 1后面讲生产配置再改 offsets.topic.replication.factor1 transaction.state.log.replication.factor1 transaction.state.log.min.isr1配置写完要先生成集群 ID 并格式化存储目录两条命令# 生成一个集群唯一标识输出一串 base64 字符串 bin/kafka-storage.sh random-uuid # 用上面拿到的 ID 格式化注意替换 uuid bin/kafka-storage.sh format -t uuid -c config/kraft/server.properties # 启动 bin/kafka-server-start.sh -daemon config/kraft/server.properties这里有个非常高频的坑advertised.listeners写的是localhost本机客户端能连上但局域网里另一台机器连过来就会拿到localhost:9092这个地址然后连接超时。原因是客户端首次连上后broker 会返回它对外宣告的地址用于后续通信。跨机器访问时这里必须写成对端可达的 IP 或域名。我第一次部署就栽在这排查了半天以为是防火墙。2.2 用命令行把收发链路先验证一遍服务起来之后别急着写代码先用自带脚本确认 broker 是活的。这套脚本在bin/目录下创建、查看、生产、消费一条龙。# 创建一个 3 分区 1 副本的 topic bin/kafka-topics.sh --bootstrap-server localhost:9092 \ --create --topic order-events \ --partitions 3 --replication-factor 1 # 看看有哪些 topic顺便确认分区分布 bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic order-events # 开一个控制台生产者回车后输入内容即发送 bin/kafka-console-producer.sh --bootstrap-server localhost:9092 \ --topic order-events # 另开一个终端做消费者从头读 bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 \ --topic order-events --from-beginning发几条消息消费者那边应该能立刻看到。这时候可以做个实验加深理解生产者加参数--property parse.keytrue --property key.separator:然后发送k1:hello、k2:world、k1:again这样的带 key 消息。你会发现相同 key 的消息总是落在同一个分区里消费者加--property print.partitiontrue能看到分区号。这就是 Kafka 保证同一业务主键有序的机制下单事件用订单号做 key同一订单的创建、支付、发货就一定按顺序被消费到。2.3 用 Java 客户端写第一个生产者和消费者命令行验证完接下来上代码。Maven 引一个依赖就够了dependency groupIdorg.apache.kafka/groupId artifactIdkafka-clients/artifactId version3.7.0/version /dependency生产者最简版本长这样我加了注释说明每一行的意图Properties props new Properties(); props.put(bootstrap.servers, localhost:9092); // key 和 value 的序列化方式字符串最直观 props.put(key.serializer, org.apache.kafka.common.serialization.StringSerializer); props.put(value.serializer, org.apache.kafka.common.serialization.StringSerializer); // 可靠性等级这里先给 1后面章节详细分析取舍 props.put(acks, 1); // 开启幂等防止网络重试导致的重复写入 props.put(enable.idempotence, true); try (KafkaProducerString, String producer new KafkaProducer(props)) { for (int i 0; i 100; i) { String key order- (i % 10); String value {\orderId\:\ key \,\amount\: (i * 10) }; // 异步发送回调里处理成功和失败 producer.send(new ProducerRecord(order-events, key, value), (meta, ex) - { if (ex ! null) { System.err.println(发送失败: ex.getMessage()); } else { System.out.printf(写入分区 %d位移 %d%n, meta.partition(), meta.offset()); } }); } // 关闭前必须 flush否则缓冲区里的消息会丢 producer.flush(); }消费者要注意的点更多。记住一条铁律不要在 poll 循环里做耗时操作处理一条消息花三秒max.poll.records又设了 500一批要跑 25 分钟早就超过max.poll.interval.ms了消费者会被踢出组触发重平衡然后陷入消费一点→被踢→重平衡→再消费一点的死循环。Properties props new Properties(); props.put(bootstrap.servers, localhost:9092); props.put(group.id, order-consumer-group); props.put(key.deserializer, org.apache.kafka.common.serialization.StringDeserializer); props.put(value.deserializer, org.apache.kafka.common.serialization.StringDeserializer); // 组内没有提交过位移时的策略earliest 从头读latest 只读新消息 props.put(auto.offset.reset, earliest); // 关掉自动提交改为处理完业务逻辑再手动提交 props.put(enable.auto.commit, false); // 单次拉取上限根据单条处理耗时反推 props.put(max.poll.records, 100); try (KafkaConsumerString, String consumer new KafkaConsumer(props)) { consumer.subscribe(List.of(order-events)); while (true) { ConsumerRecordsString, String records consumer.poll(Duration.ofMillis(500)); for (ConsumerRecordString, String record : records) { // 业务处理放这里 System.out.printf(分区%d 位移%d key%s value%s%n, record.partition(), record.offset(), record.key(), record.value()); } // 一批处理完再同步提交语义上是至少一次 if (!records.isEmpty()) { consumer.commitSync(); } } }这段代码跑起来你应该能在控制台看到和命令行消费者一样的消息。到这一步链路就通了剩下的全是怎么让它稳、快、不丢不重的问题这才是真正的门槛所在。3. 核心配置与参数调优的底层逻辑参数表在官方文档里一大堆逐个背没意义真正要理解的是每个参数在可靠性、吞吐量、延迟这个三角里站在哪一边。这一节我按生产者、消费者、服务端三块讲每个参数都说明白改大改小分别牺牲了什么。3.1 生产者的可靠性与吞吐取舍acks是第一个要拍板的参数它决定生产者认为写成功的门槛acks 取值含义可靠性吞吐适用场景0发出即算成功不等确认最低broker 挂了就丢最高日志采集等可容忍丢失的场景1主副本写入即确认中等主副本挂掉且未同步时可能丢中等一般业务多数团队的实际选择all (-1)所有 ISR 副本都写入才确认最高最低需等最慢副本订单、资金等不可丢场景选all的时候必须配min.insync.replicas否则只有主副本存活时写入依然算成功保护就形同虚设。常规组合是副本数 3、min.insync.replicas2、acksall意思是至少两份落盘才确认能容忍一台机器宕机。另外两个影响吞吐的参数是batch.size和linger.ms。生产者不是来一条发一条而是先在内存缓冲区攒批攒满batch.size默认 16KB或者等够linger.ms默认 0就发出去。把linger.ms调到 5 到 20 毫秒配合大一点的 batch吞吐能提升数倍代价是每条消息多了这点等待延迟。我一般在离线数据管道里设 20ms在线业务设 5ms 以内别为了吞吐把实时性牺牲过头。还有个参数容易被忽略max.in.flight.requests.per.connection。它控制单个连接上未确认请求的数量默认 5。在没开幂等的情况下如果前一批失败重试、后一批成功消息顺序就乱了。所以要用enable.idempotencetrue配合它会把默认值降到 5 且保证重试不会导致乱序和重复。这个组合我建议直接作为默认配置几乎没有额外代价。3.2 消费者组的分配机制与位移提交策略消费者组是 Kafka 实现一条消息只被组内一个消费者处理的机制。组里每个消费者分到若干分区分区数和消费者数决定了并行度。分配策略有几种默认那种在消费者变动时会尽量少挪动分区减少重平衡的影响。这里的关键认知是重平衡期间整个组是停止消费的所以频繁重平衡是吞吐杀手。位移提交这块enable.auto.committrue看起来省事但它是在 poll 的时候顺带提交上一批的位移如果你的业务处理还没完成、或者处理失败了位移已经提交消息就永久丢了。所以我强烈建议关掉自动提交改成处理完再手动提交语义是至少一次代价是极端情况下会重复重复的问题靠业务幂等比如用订单号做唯一键来解决比丢消息好处理得多。auto.offset.reset是个常见误解重灾区它只在组内找不到已提交位移时才生效不是每次启动都从头读。想让一个已有位移的组重新消费得用kafka-consumer-groups.sh --reset-offsets显式重置而且必须先把组内消费者全停掉否则会报错。3.3 分区数与副本数怎么算才不拍脑袋分区数的估算有个粗公式目标吞吐 ÷ 单分区实测吞吐。单分区在普通机械盘上大概能跑到 10MB/s 到 50MB/sSSD 上更高。假设你要支撑 200MB/s 的写入按 20MB/s 保守算就是 10 个分区再留一倍余量给峰值定 20 个。消费者侧也一样你想用 8 个实例并行消费分区数就不能少于 8否则有实例分不到活。副本数直接关系到可用性。1 副本没有任何冗余机器挂了数据就没了2 副本能容忍一台挂但写入时只剩一份min.insync.replicas没法定 23 副本是生产环境的通行做法能容忍一台挂机且保持写入可用。副本多了网络和磁盘开销同步上升是实打实的成本。还有个服务端参数值得单独提unclean.leader.election.enable默认 false。它控制当所有同步副本都挂掉时是否允许一个不同步的副本当主。允许的话可用性上去了但会丢数据不允许的话就等副本恢复期间该分区不可写。金融类业务绝不要开日志类业务可以考虑。4. 常见问题与排查技巧实录这部分是我踩坑最多的地方也是新手最容易卡住的地方。我把问题按现象归类配上排查命令和判断逻辑你可以当成速查手册用。4.1 消息丢失、重复、乱序三类经典故障丢失的三个典型入口生产者acks0或1且 broker 恰好在落盘前挂掉消费者自动提交位移但业务还没处理完服务端副本因子为 1 导致单点故障即丢。排查方法是先确认链路每一环的配置再看 broker 日志里有没有LeaderNotAvailable或者写入失败记录。生产者的发送回调一定要写send()是异步的不检查回调相当于闭眼开车。重复几乎是必然的因为至少一次语义下处理成功但提交失败就会重放。别想着彻底消灭它正确做法是消费侧做幂等用消息里的业务唯一 ID 建唯一索引或者维护一张已处理消息表。Kafka 也提供事务机制做精确一次但那要求消费和生产的位移都在 Kafka 事务内把业务数据库操作排除在外实际落地成本很高大多数团队还是走幂等路线。乱序通常来自重试。没开幂等又设了较大的max.in.flight.requests失败重试的消息可能排到新消息后面。解决办法就是前面说的开幂等。另外分区本身的顺序保证只在单分区内成立如果你用随机 key 或不设 key默认轮询就别指望全局有序。4.2 消费者卡住不动与重平衡风暴最常见的现象消费者进程活着日志也不报错但监控上的消费延迟lag一直涨。这时候先跑这条命令看组状态bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \ --describe --group order-consumer-group输出里重点看三列CURRENT-OFFSET、LOG-END-OFFSET和LAG。如果 LAG 持续增长而消费者没有报错基本是处理速度跟不上生产速度要么加消费者实例前提是分区数够要么优化单条处理耗时要么批量处理。如果STATE显示在PreparingRebalance和Stable之间反复跳那就是重平衡风暴常见原因是max.poll.interval.ms太小而单批处理耗时太长或者消费者启动太慢导致session.timeout.ms内没完成心跳。还有个隐蔽的坑消费者实例数超过分区数。多出来的实例分不到分区看起来闲着一旦有实例抖动就频繁触发分配。所以扩容消费者前先确认分区数必要时先扩分区。4.3 服务端异常与监控指标速查现象可能原因排查手段处理方向客户端连不上日志显示连接超时advertised.listeners 配错看 broker 配置与客户端实际拿到的地址改为对端可达地址写入报 NOT_ENOUGH_REPLICASISR 副本数低于 min.insync.replicas--describe看 UnderReplicated 分区查宕机节点、网络、磁盘磁盘使用率持续上涨保留策略设置过长或流量突增看 log.retention.hours 与分区大小缩短保留时间或扩盘消费延迟缓慢增长处理能力不足看 LAG 曲线与消费者 CPU扩实例、扩分区、优化处理集群响应变慢分区过多、请求排队看请求队列长度与 IO 等待合并小分区、升级磁盘几个我常看的指标UnderReplicatedPartitions副本落后数量长期非零说明有节点异常、ActiveControllerCount正常应该只有一个 1多个说明有脑裂风险、RequestHandlerAvgIdlePercent低于 30% 说明 broker 忙不过来、消费组 lag最直观的业务健康度。把这几项接进告警大部分问题能在爆发前发现。一个反直觉的经验不要频繁创建和删除 topic。每个 topic 的分区都会在服务端产生目录和文件句柄几千个 topic 的小分区会让元数据管理变慢请求延迟抖动明显。合并同类 topic、用 key 区分数据类型往往比开一堆小 topic 更省心。5. 从跑通到用稳的几段实战心得我把几个只在真实运维里才会浮现的体会放在这里跟上面的配置项对照着看理解会更立体。5.1 先小规模压测再谈参数结论网上的调优建议大多是别人的机器跑出来的你抄过来不一定对。我的做法是新集群上线前用一个简单的压测脚本按目标流量的 1.2 倍灌数据观察吞吐、延迟、磁盘增长速度和 CPU 分布。压测里重点看两件事一是单分区吞吐的实际值用它去校准分区数二是攒批参数的效果把linger.ms从 0 调到 10、20看吞吐和延迟的曲线拐点在哪。这套数据拿到手后续扩容和故障定位都有了基准线比凭感觉调参数靠谱得多。压测时别忘了模拟消费者慢速场景人为在消费逻辑里加个 sleep看看 lag 涨到什么程度、恢复需要多久。这一步能把重平衡的触发条件提前暴露出来比线上出事再查强。5.2 监控先于优化别等出事才加指标我见过太多团队在集群跑了大半年之后才发现没有 lag 监控等业务方反馈数据延迟了才开始翻日志。正确的顺序是上线当天就把核心指标接上至少包含 broker 的存活与副本同步状态、topic 的写入速率和分区水位、消费组的 lag 和重平衡次数。指标本身不难接难的是养成看它的习惯。我的习惯是每天早上扫一眼 lag 曲线异常抬头的趋势比绝对值更重要。另外建议给消费者加一个处理耗时的埋点记录每批消息的处理时间。当它逼近max.poll.interval.ms的一半时就该动手优化或者调整参数了这是重平衡风暴最有效的预警信号。5.3 代码层面的三个习惯能省掉大量后续麻烦第一生产者的 send 回调必须处理异常并且失败要有重试或落库补偿逻辑别让异常悄悄吞掉。第二消费者的处理逻辑和提交逻辑要绑在一起处理失败就别提交让消息重放配合业务幂等这比任何保证不丢的配置都实在。第三消息体里带上业务唯一 ID 和产生时间戳排查问题时能直接定位到是哪笔业务、什么时候产生的比翻日志猜强太多。还有个小技巧本地开发环境可以给消息加一个env字段或者在 header 里标记来源避免测试流量混进生产 topic 造成脏数据。这个成本极低但救过我不止一次。5.4 版本与升级这件事别跟风Kafka 的版本迭代不算激进但跨大版本升级会涉及协议变更和配置废弃。我的建议是生产环境跟住一个稳定的小版本线比如在 3.x 的某个补丁版本上待着除非有明确需要的特性不要追最新。升级前先在预发环境把生产者消费者客户端一起升注意客户端版本和服务端版本要兼容客户端太老可能连不上新协议的服务端。升级窗口选在低峰过程中盯着 ISR 收缩和请求延迟一旦异常立刻回滚别硬扛。写到这里该讲的链路、配置、排查都覆盖到了。Kafka 的学习曲线陡在概念密度平在跑通之后。你只要把单机环境跑起来、把带 key 的分区实验做一遍、把消费位移的提交时机想明白剩下的优化都是在这三条主线上加细节。真正让人头疼的从来不是 API 怎么写而是这条消息到底丢在哪一环——把监控和回调先做扎实这个问题就不会成为噩梦。 
长河君 · 2026/10/26 13:16:51 · 阅读 1.2k Kafka 入门实战：核心概念、环境搭建、参数调优与故障排查
Kafka 这套东西我第一次接触的时候是被它的概念绕晕的Topic、Partition、Offset、Consumer Group、ISR、Rebalance名词一箩筐文档一翻开就是拓扑图和配置表。但真正把它跑起来、丢几条消息进去、再从另一端捞出来你会发现核心逻辑其实很朴素——它就是一个高吞吐、可持久化、支持多消费者重复读的分布式消息队列。这篇内容面向的是准备把 Kafka 用起来的开发者可能你是个后端要给系统解耦可能你在做数据管道要把业务库的变更同步到分析侧也可能你只是面试被问烦了想亲手搭一套环境把概念坐实。我下面写的都是单机可复现的路径从环境搭建、命令行验证、客户端代码、参数取舍到踩坑排查一步步来你照着敲基本能跑通。1. 先搞清楚 Kafka 到底解决什么问题很多人学 Kafka 的第一步是背概念我觉得顺序反了。先想明白它替你挡掉了哪些麻烦后面那些名词才有落脚点。这一节我把常见的认知误区和我自己的理解路径摊开说你对照自己的业务场景能判断出到底该不该上 Kafka。1.1 消息队列的共性需求以及 Kafka 的差异点传统消息队列的诉求无非三条异步解耦、削峰填谷、广播通知。比如下单之后要发短信、加积分、写日志同步调用会让主链路变长且脆弱扔进队列让下游自己消费主流程就轻了。这部分任何队列都能做Kafka 的差异在于它把消息当成追加写的日志文件来对待而不是消费完就删的临时缓冲。这个设计带来两个直接结果。第一是持久化能力强消息按分区顺序落盘保留时间由你配置几天到几个月都行消费完不删除靠 offset 标记读到哪里。第二是吞吐量高顺序写盘加上批量发送、零拷贝单机几十万条每秒不算夸张。代价是它不擅长低延迟的单条投递也不适合做复杂的路由和优先级队列。我见过有团队拿它当 RPC 用每条消息等响应延迟抖动非常难看这是用错了地方。所以判断标准很清晰你的场景是流式数据、日志、事件、需要回放或多消费方订阅Kafka 合适你的场景是任务分发、需要精确的单条确认、消息优先级和延迟队列那还是看看别的东西。这个前置判断不做后面参数怎么调都是白费劲。1.2 三个必须刻进脑子里的概念Topic、Partition、Offset这三个词是所有困惑的源头我用一个类比讲透。把 Topic 想成一类数据的总账本比如订单事件Partition 是这本账被拆成的若干分册每册独立编号、独立追加Offset 是每册里的行号从 0 开始递增永不回退。为什么要拆成多个 Partition因为单机的写入能力有上限拆分之后不同分册可以落在不同机器上并行写、并行读这就是水平扩展的来源。但拆分也带来了两个必须接受的现实同一条消息只会落在某一个分册里所以全局顺序是没有的只有分区内有序以及消费者数量超过分区数就是浪费多出来的消费者分不到活只能干等。Offset 由消费者自己维护这也是 Kafka 和推模式队列最大的区别——消费者主动拉取并自己记录读到哪里。好处是消费节奏由自己控制慢一点也不会被服务端踢掉除非超过会话超时坏处是位移提交这件事必须自己管好提交早了会丢消息提交晚了会重复消费。后面讲消费者代码的时候这两个坑我都会展开。1.3 什么规模值得上 Kafka什么情况是杀鸡用牛刀我见过最小的一个 Kafka 集群只有一个 broker跑在一个 4 核 8G 的机器上每天处理几万条消息。这不算错但如果你只是想要一个进程间的异步通知Redis 的 List 或者更轻量的方案可能更省心。Kafka 的运维成本是实打实的你要管磁盘、管分区分布、管消费者组的位移动、管监控告警这些在小体量下并不划算。我的经验阈值是这样的日消息量在百万级以下、消费方不超过两三个、没有回放需求先别急着上用简单的队列方案过渡一旦出现多个下游各自独立消费同一份数据、需要按时间回溯重放、写入峰值是均值的数倍需要缓冲Kafka 的价值就出来了。另外还有个隐性收益它天然是一份事件日志出了问题可以拿 offset 回放复现这个排查能力在复杂系统里非常值钱。提醒一句分区数在创建 topic 时定下之后只能增加不能减少。减分区意味着数据要重新分布Kafka 不做这件事只能新建 topic 迁移。所以初始分区数宁可留点余量也别拍脑袋定太小。2. 环境搭建与第一个 Demo 跑通概念说再多不如亲手发一条消息。这一节走完整条链路起一个单机 broker、用命令行验证收发、再写一段 Java 客户端代码。所有操作都在本地完成不需要任何外部依赖。2.1 单机环境的选择与部署方式现在主流版本已经不需要额外部署协调组件了新模式叫KRaft把元数据管理内置到 Kafka 自身省掉一个进程对新手非常友好。我建议直接用它别再去折腾老的双进程组合配置项多、启动顺序还容易搞错。准备一台 Linux 或者装了 WSL 的机器装好 JDK 17Kafka 3.6 之后对 JDK 17 支持很好JDK 11 也能跑。下载二进制包解压然后改config/kraft/server.properties几个关键项# 节点角色单机就同时承担 broker 和 controller process.rolesbroker,controller node.id1 # 控制器的投票成员单机就写自己 controller.quorum.voters1localhost:9093 # 监听地址内网测试用 PLAINTEXT 即可 listenersPLAINTEXT://:9092,CONTROLLER://:9093 advertised.listenersPLAINTEXT://localhost:9092 # 日志目录别放系统盘 log.dirs/data/kafka-logs # 单机测试先把副本因子调成 1后面讲生产配置再改 offsets.topic.replication.factor1 transaction.state.log.replication.factor1 transaction.state.log.min.isr1配置写完要先生成集群 ID 并格式化存储目录两条命令# 生成一个集群唯一标识输出一串 base64 字符串 bin/kafka-storage.sh random-uuid # 用上面拿到的 ID 格式化注意替换 uuid bin/kafka-storage.sh format -t uuid -c config/kraft/server.properties # 启动 bin/kafka-server-start.sh -daemon config/kraft/server.properties这里有个非常高频的坑advertised.listeners写的是localhost本机客户端能连上但局域网里另一台机器连过来就会拿到localhost:9092这个地址然后连接超时。原因是客户端首次连上后broker 会返回它对外宣告的地址用于后续通信。跨机器访问时这里必须写成对端可达的 IP 或域名。我第一次部署就栽在这排查了半天以为是防火墙。2.2 用命令行把收发链路先验证一遍服务起来之后别急着写代码先用自带脚本确认 broker 是活的。这套脚本在bin/目录下创建、查看、生产、消费一条龙。# 创建一个 3 分区 1 副本的 topic bin/kafka-topics.sh --bootstrap-server localhost:9092 \ --create --topic order-events \ --partitions 3 --replication-factor 1 # 看看有哪些 topic顺便确认分区分布 bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic order-events # 开一个控制台生产者回车后输入内容即发送 bin/kafka-console-producer.sh --bootstrap-server localhost:9092 \ --topic order-events # 另开一个终端做消费者从头读 bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 \ --topic order-events --from-beginning发几条消息消费者那边应该能立刻看到。这时候可以做个实验加深理解生产者加参数--property parse.keytrue --property key.separator:然后发送k1:hello、k2:world、k1:again这样的带 key 消息。你会发现相同 key 的消息总是落在同一个分区里消费者加--property print.partitiontrue能看到分区号。这就是 Kafka 保证同一业务主键有序的机制下单事件用订单号做 key同一订单的创建、支付、发货就一定按顺序被消费到。2.3 用 Java 客户端写第一个生产者和消费者命令行验证完接下来上代码。Maven 引一个依赖就够了dependency groupIdorg.apache.kafka/groupId artifactIdkafka-clients/artifactId version3.7.0/version /dependency生产者最简版本长这样我加了注释说明每一行的意图Properties props new Properties(); props.put(bootstrap.servers, localhost:9092); // key 和 value 的序列化方式字符串最直观 props.put(key.serializer, org.apache.kafka.common.serialization.StringSerializer); props.put(value.serializer, org.apache.kafka.common.serialization.StringSerializer); // 可靠性等级这里先给 1后面章节详细分析取舍 props.put(acks, 1); // 开启幂等防止网络重试导致的重复写入 props.put(enable.idempotence, true); try (KafkaProducerString, String producer new KafkaProducer(props)) { for (int i 0; i 100; i) { String key order- (i % 10); String value {\orderId\:\ key \,\amount\: (i * 10) }; // 异步发送回调里处理成功和失败 producer.send(new ProducerRecord(order-events, key, value), (meta, ex) - { if (ex ! null) { System.err.println(发送失败: ex.getMessage()); } else { System.out.printf(写入分区 %d位移 %d%n, meta.partition(), meta.offset()); } }); } // 关闭前必须 flush否则缓冲区里的消息会丢 producer.flush(); }消费者要注意的点更多。记住一条铁律不要在 poll 循环里做耗时操作处理一条消息花三秒max.poll.records又设了 500一批要跑 25 分钟早就超过max.poll.interval.ms了消费者会被踢出组触发重平衡然后陷入消费一点→被踢→重平衡→再消费一点的死循环。Properties props new Properties(); props.put(bootstrap.servers, localhost:9092); props.put(group.id, order-consumer-group); props.put(key.deserializer, org.apache.kafka.common.serialization.StringDeserializer); props.put(value.deserializer, org.apache.kafka.common.serialization.StringDeserializer); // 组内没有提交过位移时的策略earliest 从头读latest 只读新消息 props.put(auto.offset.reset, earliest); // 关掉自动提交改为处理完业务逻辑再手动提交 props.put(enable.auto.commit, false); // 单次拉取上限根据单条处理耗时反推 props.put(max.poll.records, 100); try (KafkaConsumerString, String consumer new KafkaConsumer(props)) { consumer.subscribe(List.of(order-events)); while (true) { ConsumerRecordsString, String records consumer.poll(Duration.ofMillis(500)); for (ConsumerRecordString, String record : records) { // 业务处理放这里 System.out.printf(分区%d 位移%d key%s value%s%n, record.partition(), record.offset(), record.key(), record.value()); } // 一批处理完再同步提交语义上是至少一次 if (!records.isEmpty()) { consumer.commitSync(); } } }这段代码跑起来你应该能在控制台看到和命令行消费者一样的消息。到这一步链路就通了剩下的全是怎么让它稳、快、不丢不重的问题这才是真正的门槛所在。3. 核心配置与参数调优的底层逻辑参数表在官方文档里一大堆逐个背没意义真正要理解的是每个参数在可靠性、吞吐量、延迟这个三角里站在哪一边。这一节我按生产者、消费者、服务端三块讲每个参数都说明白改大改小分别牺牲了什么。3.1 生产者的可靠性与吞吐取舍acks是第一个要拍板的参数它决定生产者认为写成功的门槛acks 取值含义可靠性吞吐适用场景0发出即算成功不等确认最低broker 挂了就丢最高日志采集等可容忍丢失的场景1主副本写入即确认中等主副本挂掉且未同步时可能丢中等一般业务多数团队的实际选择all (-1)所有 ISR 副本都写入才确认最高最低需等最慢副本订单、资金等不可丢场景选all的时候必须配min.insync.replicas否则只有主副本存活时写入依然算成功保护就形同虚设。常规组合是副本数 3、min.insync.replicas2、acksall意思是至少两份落盘才确认能容忍一台机器宕机。另外两个影响吞吐的参数是batch.size和linger.ms。生产者不是来一条发一条而是先在内存缓冲区攒批攒满batch.size默认 16KB或者等够linger.ms默认 0就发出去。把linger.ms调到 5 到 20 毫秒配合大一点的 batch吞吐能提升数倍代价是每条消息多了这点等待延迟。我一般在离线数据管道里设 20ms在线业务设 5ms 以内别为了吞吐把实时性牺牲过头。还有个参数容易被忽略max.in.flight.requests.per.connection。它控制单个连接上未确认请求的数量默认 5。在没开幂等的情况下如果前一批失败重试、后一批成功消息顺序就乱了。所以要用enable.idempotencetrue配合它会把默认值降到 5 且保证重试不会导致乱序和重复。这个组合我建议直接作为默认配置几乎没有额外代价。3.2 消费者组的分配机制与位移提交策略消费者组是 Kafka 实现一条消息只被组内一个消费者处理的机制。组里每个消费者分到若干分区分区数和消费者数决定了并行度。分配策略有几种默认那种在消费者变动时会尽量少挪动分区减少重平衡的影响。这里的关键认知是重平衡期间整个组是停止消费的所以频繁重平衡是吞吐杀手。位移提交这块enable.auto.committrue看起来省事但它是在 poll 的时候顺带提交上一批的位移如果你的业务处理还没完成、或者处理失败了位移已经提交消息就永久丢了。所以我强烈建议关掉自动提交改成处理完再手动提交语义是至少一次代价是极端情况下会重复重复的问题靠业务幂等比如用订单号做唯一键来解决比丢消息好处理得多。auto.offset.reset是个常见误解重灾区它只在组内找不到已提交位移时才生效不是每次启动都从头读。想让一个已有位移的组重新消费得用kafka-consumer-groups.sh --reset-offsets显式重置而且必须先把组内消费者全停掉否则会报错。3.3 分区数与副本数怎么算才不拍脑袋分区数的估算有个粗公式目标吞吐 ÷ 单分区实测吞吐。单分区在普通机械盘上大概能跑到 10MB/s 到 50MB/sSSD 上更高。假设你要支撑 200MB/s 的写入按 20MB/s 保守算就是 10 个分区再留一倍余量给峰值定 20 个。消费者侧也一样你想用 8 个实例并行消费分区数就不能少于 8否则有实例分不到活。副本数直接关系到可用性。1 副本没有任何冗余机器挂了数据就没了2 副本能容忍一台挂但写入时只剩一份min.insync.replicas没法定 23 副本是生产环境的通行做法能容忍一台挂机且保持写入可用。副本多了网络和磁盘开销同步上升是实打实的成本。还有个服务端参数值得单独提unclean.leader.election.enable默认 false。它控制当所有同步副本都挂掉时是否允许一个不同步的副本当主。允许的话可用性上去了但会丢数据不允许的话就等副本恢复期间该分区不可写。金融类业务绝不要开日志类业务可以考虑。4. 常见问题与排查技巧实录这部分是我踩坑最多的地方也是新手最容易卡住的地方。我把问题按现象归类配上排查命令和判断逻辑你可以当成速查手册用。4.1 消息丢失、重复、乱序三类经典故障丢失的三个典型入口生产者acks0或1且 broker 恰好在落盘前挂掉消费者自动提交位移但业务还没处理完服务端副本因子为 1 导致单点故障即丢。排查方法是先确认链路每一环的配置再看 broker 日志里有没有LeaderNotAvailable或者写入失败记录。生产者的发送回调一定要写send()是异步的不检查回调相当于闭眼开车。重复几乎是必然的因为至少一次语义下处理成功但提交失败就会重放。别想着彻底消灭它正确做法是消费侧做幂等用消息里的业务唯一 ID 建唯一索引或者维护一张已处理消息表。Kafka 也提供事务机制做精确一次但那要求消费和生产的位移都在 Kafka 事务内把业务数据库操作排除在外实际落地成本很高大多数团队还是走幂等路线。乱序通常来自重试。没开幂等又设了较大的max.in.flight.requests失败重试的消息可能排到新消息后面。解决办法就是前面说的开幂等。另外分区本身的顺序保证只在单分区内成立如果你用随机 key 或不设 key默认轮询就别指望全局有序。4.2 消费者卡住不动与重平衡风暴最常见的现象消费者进程活着日志也不报错但监控上的消费延迟lag一直涨。这时候先跑这条命令看组状态bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 \ --describe --group order-consumer-group输出里重点看三列CURRENT-OFFSET、LOG-END-OFFSET和LAG。如果 LAG 持续增长而消费者没有报错基本是处理速度跟不上生产速度要么加消费者实例前提是分区数够要么优化单条处理耗时要么批量处理。如果STATE显示在PreparingRebalance和Stable之间反复跳那就是重平衡风暴常见原因是max.poll.interval.ms太小而单批处理耗时太长或者消费者启动太慢导致session.timeout.ms内没完成心跳。还有个隐蔽的坑消费者实例数超过分区数。多出来的实例分不到分区看起来闲着一旦有实例抖动就频繁触发分配。所以扩容消费者前先确认分区数必要时先扩分区。4.3 服务端异常与监控指标速查现象可能原因排查手段处理方向客户端连不上日志显示连接超时advertised.listeners 配错看 broker 配置与客户端实际拿到的地址改为对端可达地址写入报 NOT_ENOUGH_REPLICASISR 副本数低于 min.insync.replicas--describe看 UnderReplicated 分区查宕机节点、网络、磁盘磁盘使用率持续上涨保留策略设置过长或流量突增看 log.retention.hours 与分区大小缩短保留时间或扩盘消费延迟缓慢增长处理能力不足看 LAG 曲线与消费者 CPU扩实例、扩分区、优化处理集群响应变慢分区过多、请求排队看请求队列长度与 IO 等待合并小分区、升级磁盘几个我常看的指标UnderReplicatedPartitions副本落后数量长期非零说明有节点异常、ActiveControllerCount正常应该只有一个 1多个说明有脑裂风险、RequestHandlerAvgIdlePercent低于 30% 说明 broker 忙不过来、消费组 lag最直观的业务健康度。把这几项接进告警大部分问题能在爆发前发现。一个反直觉的经验不要频繁创建和删除 topic。每个 topic 的分区都会在服务端产生目录和文件句柄几千个 topic 的小分区会让元数据管理变慢请求延迟抖动明显。合并同类 topic、用 key 区分数据类型往往比开一堆小 topic 更省心。5. 从跑通到用稳的几段实战心得我把几个只在真实运维里才会浮现的体会放在这里跟上面的配置项对照着看理解会更立体。5.1 先小规模压测再谈参数结论网上的调优建议大多是别人的机器跑出来的你抄过来不一定对。我的做法是新集群上线前用一个简单的压测脚本按目标流量的 1.2 倍灌数据观察吞吐、延迟、磁盘增长速度和 CPU 分布。压测里重点看两件事一是单分区吞吐的实际值用它去校准分区数二是攒批参数的效果把linger.ms从 0 调到 10、20看吞吐和延迟的曲线拐点在哪。这套数据拿到手后续扩容和故障定位都有了基准线比凭感觉调参数靠谱得多。压测时别忘了模拟消费者慢速场景人为在消费逻辑里加个 sleep看看 lag 涨到什么程度、恢复需要多久。这一步能把重平衡的触发条件提前暴露出来比线上出事再查强。5.2 监控先于优化别等出事才加指标我见过太多团队在集群跑了大半年之后才发现没有 lag 监控等业务方反馈数据延迟了才开始翻日志。正确的顺序是上线当天就把核心指标接上至少包含 broker 的存活与副本同步状态、topic 的写入速率和分区水位、消费组的 lag 和重平衡次数。指标本身不难接难的是养成看它的习惯。我的习惯是每天早上扫一眼 lag 曲线异常抬头的趋势比绝对值更重要。另外建议给消费者加一个处理耗时的埋点记录每批消息的处理时间。当它逼近max.poll.interval.ms的一半时就该动手优化或者调整参数了这是重平衡风暴最有效的预警信号。5.3 代码层面的三个习惯能省掉大量后续麻烦第一生产者的 send 回调必须处理异常并且失败要有重试或落库补偿逻辑别让异常悄悄吞掉。第二消费者的处理逻辑和提交逻辑要绑在一起处理失败就别提交让消息重放配合业务幂等这比任何保证不丢的配置都实在。第三消息体里带上业务唯一 ID 和产生时间戳排查问题时能直接定位到是哪笔业务、什么时候产生的比翻日志猜强太多。还有个小技巧本地开发环境可以给消息加一个env字段或者在 header 里标记来源避免测试流量混进生产 topic 造成脏数据。这个成本极低但救过我不止一次。5.4 版本与升级这件事别跟风Kafka 的版本迭代不算激进但跨大版本升级会涉及协议变更和配置废弃。我的建议是生产环境跟住一个稳定的小版本线比如在 3.x 的某个补丁版本上待着除非有明确需要的特性不要追最新。升级前先在预发环境把生产者消费者客户端一起升注意客户端版本和服务端版本要兼容客户端太老可能连不上新协议的服务端。升级窗口选在低峰过程中盯着 ISR 收缩和请求延迟一旦异常立刻回滚别硬扛。写到这里该讲的链路、配置、排查都覆盖到了。Kafka 的学习曲线陡在概念密度平在跑通之后。你只要把单机环境跑起来、把带 key 的分区实验做一遍、把消费位移的提交时机想明白剩下的优化都是在这三条主线上加细节。真正让人头疼的从来不是 API 怎么写而是这条消息到底丢在哪一环——把监控和回调先做扎实这个问题就不会成为噩梦。