生产陷阱：机制被违反时的失败模式

这一章按根因与严重度排序，不按出现频率。数据丢失放最前：丢掉的记录不会回来，而重复和乱序还能在下游补救。每条失败模式都标注它违反了 02 章的哪条机制——失败模式不是孤立的故障，是某个设计取舍在被忽略时显形。

4.1数据丢失类（最严重，不可逆）

数据丢失的共同根因是持久性保证被高估：producer 以为记录已经安全落地，实际上它只到了一台机器、或还没复制就因故障消失。全部回溯到 §2.3 副本与 ISR 里 HW（高水位）与 ISR 的语义。

陷阱 1：acks=1 丢数据（leader ack 后未复制即崩溃）

症状：producer 端 send() 全部返回成功、回调拿到了 offset；某次 broker 故障切换后，下游消费者读到的最高 offset 比 producer 确认过的要小——中间一段记录凭空消失，且无任何异常抛出。

根因：acks=1 表示 leader 把记录写进自己的日志就立即 ack，不等待 follower 复制。回链 §2.3：HW 只在 ISR 中所有副本都 fetch 到之后才推进。acks=1 在"leader 已写、follower 未同步"这个窗口里 ack 了 producer；若 leader 此刻崩溃，新 leader 从某个 follower 选出，那段没复制出去的记录随旧 leader 的磁盘一起丢失。这是用持久性换延迟。

# 错误写法：leader 单方面确认，复制前的崩溃窗口会丢已 ack 的记录
acks=1

# 正确写法：等所有 ISR 成员都复制到才确认
acks=all
# 注意 acks=all 本身不够，必须搭配陷阱 3 的 min.insync.replicas，否则会静默退化

如何避免再次触发：把 acks=all 写进生产 producer 的基线配置模板，不要让它停留在各服务自行决定。对吞吐敏感、可容忍丢失的旁路链路（如可重算的指标采样）才显式降到 acks=1，并在代码注释里写明"此链路接受丢失"——把例外变成需要主动声明的决定，而不是默认。

陷阱 2：unclean leader election 丢已提交数据

症状：一次多 broker 同时故障后集群恢复了可用性、分区重新可写，但已经确认给 producer、甚至已经被消费过的一段记录消失了。这比陷阱 1 更隐蔽——丢的是已经越过 HW、对消费者可见过的记录。

根因：unclean.leader.election.enable=true 允许一个不在 ISR 里、落后的副本当选 leader，以便在所有同步副本都不可用时恢复写入。回链 §2.3：假设 producer 已 ack 到 offset 100、HW=100，落后副本只复制到 offset 80 就被选为 leader，它会把日志截断到 80，81–100 永久丢失。这是用一致性换可用性，且丢失静默发生。

# 错误写法：允许落后副本上位，截断已提交记录换取可用性
unclean.leader.election.enable=true

# 正确写法（4.x 默认即 false，但旧集群/旧 topic 可能残留 true）
unclean.leader.election.enable=false
# 代价：所有 ISR 副本都挂时分区停写，直到某个同步副本恢复——这是刻意的

如何避免再次触发：把它当成一个持久性 vs 可用性的显式声明而非性能开关。金融、订单、计费类不能丢数据的 topic 一律 false；同时在 broker 默认值与 topic 级覆盖两处都核对——一个老 topic 上残留的 true 会绕过 broker 默认。监控 UncleanLeaderElectionsPerSec 指标，任何非零都该告警。

陷阱 3：acks=all 静默退化成 acks=1（ISR 缩到 1）

症状：配置审计显示 acks=all 一切合规，但某次故障后仍然丢了已 ack 的记录。看上去和陷阱 1 矛盾——明明设了最强确认。

根因：acks=all 的语义是"所有 ISR 成员确认"，不是"所有副本确认"。回链 §2.3 的关键洞察：当 follower 落后超过 replica.lag.time.max.ms 被踢出 ISR，ISR 可能收缩到只剩 leader 一台。此时 acks=all 等价于 acks=1——写到一台就算"全部 ISR 确认"，下一次故障即丢。持久性的真正来源是 min.insync.replicas，不是 acks。

# 错误写法：只设 acks=all，ISR 缩到 1 时静默退化成单副本写入
acks=all
# （未设 min.insync.replicas，默认 1）

# 正确写法：broker / topic 端要求至少 2 个 ISR 成员在线
acks=all                       # producer 端
min.insync.replicas=2          # broker / topic 端
replication.factor=3           # topic 端
# 效果：ISR 缩到 1 时写入被 NotEnoughReplicas 拒绝，而不是默默欠复制

如何避免再次触发：持久性是 acks=all + min.insync.replicas=2 + replication.factor=3 三者同时成立才有的属性，缺一即降级。设计原则：min.insync.replicas = replication.factor - 1——这样允许挂一台仍可写、挂两台才停写。把"宁可拒绝写入也不欠复制"作为默认立场（fail-closed），让丢失窗口根本不存在，而不是事后补救。

陷阱 4：replication.factor=1 与 fetch/message 尺寸错配

症状：两种形态。其一，单个 broker 下线整个分区彻底不可用、其上记录全丢。其二，producer 能成功写入大消息（broker 收下了），但这条记录始终复制不到 follower，于是它从不越过 HW、消费者永远读不到，或在故障时丢失。

根因：replication.factor=1 意味着每个分区只有一份，没有任何冗余——这通常是开发环境单节点默认值泄漏到了生产。第二种形态回链 §2.3 的复制路径：follower 像消费者一样 fetch，单次 fetch 上限由 replica.fetch.max.bytes 控制；若它小于 message.max.bytes，一条合法大消息能被 leader 接收却无法被 follower 拉取，复制就此卡死。

# 错误写法：dev 默认漏到 prod + 复制拉取上限小于单条消息上限
replication.factor=1
replica.fetch.max.bytes=1048576    # 1 MiB
message.max.bytes=10485760         # 10 MiB —— 大消息能写入却无法被复制

# 正确写法：生产至少 3 副本，且复制拉取上限 ≥ 单条消息上限
replication.factor=3
message.max.bytes=10485760              # broker
replica.fetch.max.bytes=10485760       # >= message.max.bytes

如何避免再次触发：生产集群把 default.replication.factor=3 设为集群级默认，并禁用或受控 auto.create.topics.enable——自动建 topic 极易带出 RF=1。尺寸三件套（producer max.request.size、broker message.max.bytes、consumer fetch.max.bytes，外加 replica.fetch.max.bytes）必须当成一组联动配置统一推导，见陷阱 15。

陷阱 5：auto-commit 丢消息（提交的是 poll 返回的，不是处理过的）

症状：消费者进程崩溃或被杀后重启，发现中间一批消息从未被业务处理，但它们的 offset 已经提交、不会再投递——消息在"已消费"账面上存在，实际从未落地。

根因：enable.auto.commit=true（默认）按 auto.commit.interval.ms（默认 5s）定时提交最近一次 poll() 返回的 offset，而不是业务实际处理完的 offset。回链 §2.4 的 offset 提交语义：offset 由消费者侧维护、提交到 __consumer_offsets。设想 poll() 返回 1000 条，处理到第 501 条时定时器触发、把 offset 提交到了 1000，紧接着进程 OOM 被杀——重启从 1001 开始，502–1000 这段未处理却已提交，永久跳过。

// 错误写法：自动提交按定时器走，提交的是 poll 返回的、不是处理完的
Properties bad = new Properties();
bad.put("enable.auto.commit", "true");      // 默认值
bad.put("auto.commit.interval.ms", "5000");
KafkaConsumer<String, String> c = new KafkaConsumer<>(bad);
while (true) {
    var records = c.poll(Duration.ofMillis(100));
    for (var r : records) process(r);       // 处理到一半崩溃 → 已提交的尾段丢失
}

// 正确写法：关掉自动提交，处理完整批后再同步提交
Properties good = new Properties();
good.put("enable.auto.commit", "false");
KafkaConsumer<String, String> consumer = new KafkaConsumer<>(good);
while (true) {
    var records = consumer.poll(Duration.ofMillis(100));
    for (var r : records) process(r);       // 先把这一批全部处理掉
    consumer.commitSync();                  // 再提交——崩溃只会重投，不会丢
}

如何避免再次触发：默认就关掉 enable.auto.commit，把 offset 提交作为业务处理成功后的显式动作。这把失败模式从"丢失"翻转成"重复"——重复可以靠消费侧幂等兜住（见陷阱 8），丢失无法补救。需要更细粒度时用 commitSync(offsets) 提交到确切处理位置。

4.2正确性类（重复与乱序）

这一类的共同根因是对投递语义的边界误判：把"至少一次"当成了"恰好一次"，或把幂等的去重范围想得比实际大。全部回链 §2.5 投递语义。和数据丢失不同，重复与乱序能在下游补救（幂等处理、去重键），所以严重度低一档——但若误以为已经"恰好一次"而不做补救，等于把可补救的问题留成了脏数据。

陷阱 6：重试导致静默乱序

症状：单分区内消息顺序被打乱。比如同一个 key 的"创建—更新—删除"三条消息，下游收到的却是"创建—删除—更新"，状态机错乱。无任何异常。

根因：max.in.flight.requests.per.connection>1（默认 5）允许同一连接上多个未确认批次并发在途。回链 §2.2 分区与顺序：顺序只在单分区内、且依赖写入到达顺序。当批次 N 失败重试、而批次 N+1 已经先落盘，重试后的 N 排到了 N+1 后面——顺序就此颠倒。

# 错误写法：多个在途批次 + 重试 → 重试的批次可能排到后面，顺序颠倒
max.in.flight.requests.per.connection=5
retries=2147483647
# 未开幂等

# 正确写法：开启幂等，broker 按序列号保序并去重
enable.idempotence=true
# 开启后 Kafka 自动约束 in.flight<=5、acks=all、retries>0；
# 序列号机制拒绝乱序 batch，所以重试也不会打乱顺序

如何避免再次触发：enable.idempotence=true 在 4.x 已是默认，但旧配置模板或显式覆盖可能关掉它。把它当成顺序保证的开关而不只是去重开关——它通过 broker 端维护 (PID, partition) → 最高 seq、只接受 seq 恰好 +1 的 append，顺带把"重试乱序"和"重试重复"两个问题一起解决。除非有明确理由，永远不要关。

陷阱 7：ACK 丢失致重复，且幂等跨会话失效

症状：下游出现重复记录。排查发现 producer 开了幂等，单进程内确实不重复；但 producer 重启或崩溃恢复后，重复又出现了。

根因：两层。第一层，broker 写入成功但 ack 在网络上丢了，producer 超时重发——幂等 producer 靠 (PID, seq) 能识别并丢弃这个重复。第二层（边界）回链 §2.5 的 EOS 真实边界：幂等去重只在同一个 PID + 同一 producer 会话内有效。producer 重启会拿到新的 PID，broker 视之为全新生产者，旧会话发过的记录无法再去重，跨重启的重复就此漏过。

// 错误写法：以为开了幂等就跨重启不重复——新 PID 让跨会话去重失效
props.put("enable.idempotence", "true");   // 只在单会话内去重

// 正确写法：要跨重启的恰好一次，用事务（transactional.id 靠 epoch 跨会话存活）
props.put("enable.idempotence", "true");
props.put("transactional.id", "order-writer-1");  // 稳定 ID，重启后复用
KafkaProducer<String, String> producer = new KafkaProducer<>(props);
producer.initTransactions();
try {
    producer.beginTransaction();
    producer.send(record);
    // 把消费 offset 也纳入同一事务，构成消费-转换-生产闭环
    producer.sendOffsetsToTransaction(offsets, groupMetadata);
    producer.commitTransaction();
} catch (KafkaException e) {
    producer.abortTransaction();
}

如何避免再次触发：先界定需求边界。仅需"重试不重复"用幂等即可；需要跨进程重启的恰好一次，必须上事务——稳定的 transactional.id 通过 epoch 隔离僵尸实例、跨会话存活。同时记住事务的恰好一次只在 Kafka 的消费-转换-生产闭环内成立，不覆盖外部副作用（DB 写、HTTP 调用、发邮件），那些仍需自己做幂等。

陷阱 8：再平衡后重复处理；"先提交后处理"反而丢失

症状：一次消费组再平衡（扩容、重启、或处理超时驱逐）之后，一批消息被重复处理了一遍——下游收到重复副作用。有人为消灭重复而改成"先提交 offset 再处理"，结果重复消失了，但崩溃时变成了丢失。

根因：默认是至少一次（先处理后提交）。回链 §2.4 消费组与再平衡：消费者在处理完、提交 offset 之前崩溃或被驱逐，那批在途消息会在新 owner 上重投——这是至少一次的固有代价，正确做法是让处理幂等。反向的"先提交后处理"把语义改成了至多一次：offset 已提交但处理还没做就崩溃，那批消息再也不会投递，从重复翻转成丢失。感觉更安全的早提交，其实更危险。

// 错误写法：先提交后处理 → 崩溃时消息丢失（at-most-once）
for (var r : records) {
    consumer.commitSync();   // 先提交
    process(r);              // 还没处理就崩溃 → 这条永久跳过
}

// 正确写法：先处理后提交（at-least-once）+ 处理本身做成幂等
for (var r : records) {
    // 用业务唯一键去重：同一 key 重复到达时是 no-op
    upsertByBusinessKey(r.key(), r.value());   // 例如 INSERT ... ON CONFLICT DO NOTHING
}
consumer.commitSync();       // 处理完整批再提交；崩溃只会重投，幂等吸收

如何避免再次触发:接受"至少一次 + 消费侧幂等"是默认且正确的组合，不要试图靠调整提交时机消灭重复——那只会把丢失风险引进来。幂等的实现方式：业务唯一键 upsert、去重表、或下游天然幂等的操作。需要真正端到端恰好一次时回到陷阱 7 的事务方案。

陷阱 9：schema 演进卡死消费者

症状：producer 上线了一个新版本消息格式后，部分消费者开始大面积反序列化失败、整个消费组卡在某个 offset 推进不动，错误是 schema 不兼容。

根因:producer 发布了一个不兼容的 schema 变更（如删字段、改类型、加无默认值的必填字段）。Schema Registry 默认兼容模式是 BACKWARD——只保证新 schema 能读旧数据，且只对紧邻的上一版、非传递。在 producer 和 consumer 混版本部署、消费者读到比自己新的 schema 写的数据时，BACKWARD 兜不住。这条不直接对应 02 章某机制，根因在 schema 契约管理而非 broker——但它和顺序/投递一样属于"正确性"失败：消息在但读不出。

# 错误写法：默认 BACKWARD，混版本舰队中新写旧读会失败
# （删字段 / 改类型 / 加必填无默认值字段都会破坏兼容）

# 正确写法：混版本部署用 FULL_TRANSITIVE，并约束变更类型
# Schema Registry subject 级配置：
compatibility=FULL_TRANSITIVE
# 变更纪律：只新增可选字段 / 带默认值字段；不删、不改类型、不加必填项

如何避免再次触发:对生产者消费者混版本滚动部署的 topic，把 subject 兼容模式设为 FULL_TRANSITIVE（新旧互相可读、且对所有历史版本传递成立）。配套变更纪律：只加可选/带默认值的字段，绝不删字段、改类型或加必填项。把 schema 变更纳入 CI 校验，不兼容的变更在合并前就拦下。

4.3性能与运维类

这一类严重度最低——不丢数据、不破坏正确性，但会让吞吐归零或资源耗尽。共同根因是把并行单位（分区）和协调成本（再平衡）想得太理想，全部回链 §2.2 分区 与 §2.4 再平衡。

陷阱 10：再平衡风暴，吞吐归零

症状:消费组 lag 持续上涨、吞吐周期性归零，日志里反复出现成员离组又入组。集群没挂、消息也没丢，但消费几乎停滞。

根因:单批处理时间超过 max.poll.interval.ms（默认 5 分钟），或 session.timeout.ms 设得过紧。回链 §2.4 的关键代价：心跳跑在后台线程，但成员存活由 poll() 调用证明。处理太慢 → 两次 poll() 间隔超限 → coordinator 判定成员死亡 → 触发再平衡 → 分区重分配 → 慢消费者重新加入又再次超时 → 循环。在 eager（急切式）协议下每次再平衡都是 stop-the-world，整组停摆。

# 错误写法：批太大处理超时 + eager 协议 + 无 static membership
max.poll.records=500
session.timeout.ms=30000           # 滚动重启首次心跳就可能超

# 正确写法：减小批量 + 协作式增量再平衡 + 静态成员
max.poll.records=100                       # 缩短单批处理时间
partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor
group.instance.id=consumer-instance-7      # 每实例唯一且稳定 → 重启不触发再平衡
session.timeout.ms=45000                   # 给滚动重启留出首次心跳余量

如何避免再次触发:三管齐下。① 把单批处理时间控制在 max.poll.interval.ms 内（减小 max.poll.records 或加速处理）；② 用协作式增量再平衡（CooperativeStickyAssignor），只移交需要变动的分区、其余继续消费，没有全局 stop-the-world；③ 给每个实例配稳定的 group.instance.id 启用 static membership，让重启不触发再平衡。4.0 的 KIP-848 把再平衡逻辑移到 broker 端、增量收敛，进一步压缩 churn。

陷阱 11：加消费者反而 lag 增大

症状:lag 高，于是给消费组扩容；扩容后吞吐没上去，lag 反而比扩容前更大。

根因:回链 §2.4。在 eager 协议下，每加入一个新成员都触发一次 stop-the-world 再平衡——全组暂停消费、重算分配、重新拉起。如果组本身已经不稳定（处理偏慢、临近超时），新成员加入引发的再平衡会进一步挤占处理时间，把组推向陷阱 10 的风暴。另一种情形：分区数已经等于消费者数，再加的消费者分不到分区、纯闲置，却仍参与了那次再平衡的代价。

如何避免再次触发:扩容前先确认两件事——组是否稳定（不在临界超时），以及分区数是否还有余量（消费并行度上限 = 分区数）。先切到协作式增量再平衡再扩容，避免扩容动作本身引发 stop-the-world。若分区数已是瓶颈，问题在分区规划（陷阱 14），加消费者无效。

陷阱 12：慢消费者阻塞 poll 线程

症状:消费者偶尔因下游（数据库、HTTP）变慢而处理时间拉长，紧接着就被判死、触发再平衡，形成"下游抖动 → 再平衡 → 更慢"的连锁。

根因:在 poll() 循环里直接做重活（同步 DB 写、外部 HTTP 调用）。回链 §2.4：poll() 既拉消息又承担"成员存活"的证明，处理阻塞在 poll 线程上就等于心跳停摆。一旦单批处理超过 max.poll.interval.ms，成员被判死。

// 错误写法：重活直接堵在 poll 线程上，下游变慢即超时被驱逐
while (true) {
    var records = consumer.poll(Duration.ofMillis(100));
    for (var r : records) slowDbWrite(r);   // 阻塞 → 错过下一次 poll → 判死
}

// 正确写法：卸到工作线程，poll 线程用 pause/resume 维持存活而不超时
var partitions = consumer.assignment();
while (true) {
    var records = consumer.poll(Duration.ofMillis(100));
    if (!records.isEmpty()) {
        consumer.pause(partitions);          // 暂停拉取，但继续 poll 维持心跳
        submitToWorkerPool(records);         // 重活交给工作线程
    }
    if (workerPoolIdle()) {
        consumer.resume(partitions);         // 处理跟上后恢复拉取
        commitProcessedOffsets(consumer);    // 按已完成进度提交
    }
}

如何避免再次触发:保持 poll 线程轻量——只拉取和派发，重活卸到工作线程池。用 pause()/resume() 在工作线程忙时停止拉取新数据、同时继续调用 poll() 维持存活计时器，避免假死驱逐。offset 严格按工作线程实际完成的进度提交。

陷阱 13：热分区 / key 倾斜

症状:某一个消费者实例 CPU/lag 居高不下、其余实例几乎空闲，整组吞吐被这一个实例拖住。扩容无效。

根因:回链 §2.2:相同 key 经 murmur2 哈希落到同一分区以保证顺序。若 key 选择导致分布极度不均（例如按租户分区、而某个大租户占了大半流量），该租户的分区成为热点、承接它的消费者过载。Kafka 不会自动均衡倾斜的负载——分区是固定归属的。

如何避免再次触发:选高基数、分布均匀的分区 key（用 orderId 而非 userId，用 userId 而非 tenantId）。若业务要求按某低基数维度保序、又无法承受倾斜，考虑复合 key（如 tenantId + orderId）在保序粒度和均衡之间折中。规划阶段就用真实流量分布压测分区热度，别等上线发现单分区被打爆。

陷阱 14：分区数过多/过少，不可减，加分区破坏顺序

症状:三种。其一，消费并行度卡死——消费者数想加却加不上去（分区太少）。其二，controller 故障切换慢、broker 文件句柄耗尽报错（分区太多）。其三，给一个有 key 的 topic 加了分区后，下游按 key 的顺序全乱了。

根因:回链 §2.2。分区是并行的单位，消费者数不能超过分区数，过少则并行度被锁死。过多则每个 segment 占 2 个文件句柄（默认 ulimit 1024 很快耗尽）、且抬高 controller 元数据与故障切换开销（KRaft 缓解但不消除）。最隐蔽的是：分区数只能加不能减，而给有 key 的 topic 加分区会改变 key % 分区数 的映射——同一个 key 从此哈希到不同分区，历史顺序与未来顺序在不同分区之间永久错位。

如何避免再次触发:分区数当成难以回退的容量决策来定——按目标吞吐、单分区吞吐上限、未来消费并行需求保守预估，留一定余量但不盲目设大。确需调整且不能容忍顺序错乱时，新建一个分区数合适的 topic、双写或迁移，而不是在原 topic 上加分区。无 key（顺序无关）的 topic 加分区才是安全的。

陷阱 15：消息过大，三个尺寸配置不匹配

症状:producer 抛 RecordTooLargeException，或消费端拉取失败/卡住，或大消息能写入却复制不出去（与陷阱 4 的第二形态同源）。

根因:四个尺寸配置分散在三端、彼此不一致——producer 的 max.request.size、broker 的 message.max.bytes、consumer 的 fetch.max.bytes，以及复制路径的 replica.fetch.max.bytes。任意一个小于实际消息体，对应环节就断：producer 端拒发、broker 端拒收、consumer 端拉不动、follower 端复制不了。回链 §2.1 存储:记录是顺序写进 segment 的字节流，每一跳都有自己的尺寸上限。

# 错误写法：四个尺寸各自为政，某一跳卡住
max.request.size=1048576           # producer 1 MiB
message.max.bytes=10485760         # broker 10 MiB
fetch.max.bytes=1048576            # consumer 1 MiB —— 拉不动 broker 上的大消息

# 正确写法：四者按同一上限对齐推导（示例统一到 10 MiB）
max.request.size=10485760          # producer
message.max.bytes=10485760         # broker
replica.fetch.max.bytes=10485760   # broker 复制路径，>= message.max.bytes
fetch.max.bytes=10485760           # consumer

如何避免再次触发:把四个尺寸当成一组联动配置、从单一上限统一推导，写进配置模板而非各端独立设置。更根本的设计：大对象不要走 Kafka。Kafka 适合高吞吐的小记录；大文件用 claim-check 模式——把对象存到 S3/对象存储，消息体里只放一个指针（URL/key），消费者凭指针去取。这同时避开了尺寸配置地狱和大消息对 page cache 的污染。

4.4反模式与"什么时候不要用 Kafka"

前面 15 条失败模式的总和，反过来勾出 Kafka 的适用边界。它是分布式可重放的分区日志——这套设计在某些场景是错的工具，硬上会持续与机制对抗。这一节服务后面的选型判断。

常见反模式

• 把 Kafka 当请求-响应的 RPC 用:日志模型是单向追加 + 异步消费，没有内建的"响应"通道。硬做要靠关联 ID + 临时响应 topic，延迟和复杂度都远高于直接用 RPC。
• 用消费者数超过分区数来追求并行:并行上限是分区数，多出的消费者纯闲置（陷阱 11、14）。
• 用大量短命 topic 或海量分区做隔离:抬高 controller 负担、文件句柄、故障切换时间（陷阱 14）。
• 把大文件直接塞进消息体:污染 page cache、撞尺寸上限——用 claim-check（陷阱 15）。
• 靠默认配置上生产:RF=1、auto-commit、ISR 无下限都是会丢数据的默认（陷阱 3、4、5）。

什么时候不要用 Kafka