Event 与 State 的边界#

Kafka 保存的是“发生了什么”，数据库保存的是“现在是什么状态”：

Kafka:    OrderCreated -> OrderPaid -> OrderShipped
MySQL:    order 1001, status = SHIPPED

Kafka 不擅长 SELECT * FROM orders WHERE id = 1001 这类随机查询，也不负责 关系约束和事务更新。它适合顺序事件流，MySQL 适合当前状态和关系查询。两者 不是替代关系。

托管 Kafka 可以减少 Broker 生命周期、存储、升级和部分高可用运维，但不会 替应用处理 Topic 设计、消费幂等、Schema 兼容和 Offset 提交时机。

Key 决定消息进入哪个 Partition#

Producer 可以为消息设置 Key。默认分区器会对 Key 做哈希，再映射到某个 Partition，因此相同 Key 通常进入同一个 Partition：

Key = orderId
orderId=1001 -> Partition 2

这使“同一业务实体的局部有序”成为可能。代价是 Key 分布不均时会产生热点：

key=global

即使 Topic 有 100 个 Partition，所有消息仍可能集中到一个 Partition，形成 Hot Partition。Partition 负载严重倾斜则称为 Partition Skew。

为了全局严格有序而只使用一个 Partition，会同时限制 Producer 吞吐、Consumer 并行度和横向扩展能力。多数系统追求的是业务实体级顺序，而不是所有消息的 绝对顺序。

Partition 数量决定消费并行度#

同一个 Consumer Group 中，一个 Partition 同一时刻只能分配给一个 Consumer。 因此：

6 Partitions + 6 Consumers -> 每个 Consumer 一个 Partition
6 Partitions + 3 Consumers -> 每个 Consumer 两个 Partition
3 Partitions + 5 Consumers -> 2 个 Consumer 空闲

Partition 数量是 Consumer Group 有效并行度的上限。创建 Topic 时需要同时 考虑当前吞吐、未来扩容和 Broker 数量：

kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic order-events \
  --partitions 6 --replication-factor 3

Partition 也不是越多越好。大量 Partition 会增加元数据、文件句柄、Leader 选举、副本复制和 Controller 管理成本，Rebalance 也更重。Partition 数量可以 增加，但不能减少；增加后 Key 到 Partition 的映射可能变化，已有 Key 的顺序 保证需要重新评估。

Topic 粒度同样需要平衡。把所有事件塞进一个 global-topic，会让保留策略、 权限和消费边界互相耦合；每个业务动作都单独建 Topic，又会导致 Topic 和 Partition 数量膨胀。通常按领域、生命周期和消费边界划分。

acks 决定什么算写入成功#

acks=all 等待的是当前 ISR（In-Sync Replicas，同步副本集合）中的副本， 不是所有配置的 Replica。Follower 长期跟不上 Leader 会被移出 ISR，此时可靠 副本数量已经下降。

Replication Factor 与 min.insync.replicas#

每个 Partition 有一个 Leader 和若干 Follower。Producer 和 Consumer 主要与 Leader 交互，Follower 从 Leader 复制日志。Leader 故障时，一个合适的 Follower 可以被提升为新的 Leader，这是 Partition 级故障切换。

高可靠写入的常见组合是：

replication.factor = 3
min.insync.replicas = 2
acks = all

它表示至少要有 2 个同步副本参与确认，写入才算成功。一个 Broker 故障时， 仍有机会继续写入；在上面的组合下，如果 ISR 只剩 1 个副本，写入会被拒绝。 这是用可用性换取持久性的典型取舍，也是 Kafka 宁愿报错也不默默接受弱副本 写入的原因。

幂等 Producer 与重试#

Producer 因网络超时重试时，可能并不知道 Broker 是否已经写入成功。如果没有 去重机制，同一条 Record 可能被写入两次。

幂等 Producer 通过 Producer ID 和序列号，让 Broker 识别同一 Producer 的 重复写入。较新的 Java 客户端通常默认开启幂等，但仍应核对客户端版本和配置。 它主要解决单个 Producer 会话内的重复写入，不等同于业务端到端 Exactly Once。

enable.idempotence=true
acks=all

幂等 Producer 需要 acks=all、有限重试和合理的 max.in.flight.requests.per.connection。 如果为了吞吐随意放开并发请求数，仍可能影响顺序保证，具体限制应结合客户端 版本文档确认。

Kafka Transaction 的边界#

Kafka 支持事务性写入，把多个 Partition 的 Produce 和 Offset 提交放在同一个 Kafka 事务中。典型场景是：

Read Topic A
-> Process
-> Write Topic B
-> Commit Offset

配合 isolation.level=read_committed，Consumer 不会读到未提交或已中止事务 的消息。这使 Kafka-to-Kafka 的流处理可以获得 Exactly Once 效果。

但 Kafka Transaction 不能把 MySQL 更新和 Kafka Offset 变成一个本地 ACID 事务。它们属于两个独立系统，跨系统一致性仍要依靠幂等、Outbox 或补偿设计。

Offset 是 Group 级消费进度#

Offset 表示某条消息在 Partition 中的位置，只在当前 Partition 内有意义。 Partition 0 的 Offset 10 和 Partition 1 的 Offset 10 是两条不同的消息。它 不是全局唯一的业务消息 ID，不适合直接作为幂等键；去重应使用 eventId 之类 的稳定业务标识。

消费进度按 Group、按 Partition 记录，通常保存在 Kafka 内部主题 __consumer_offsets 中。同一个 Partition 上，不同 Group 可以有完全不同的 Offset：

notification-group: offset = 1000
analytics-group:    offset = 500

Consumer Lag 是“最新 Offset”与“已提交 Offset”的差距：

Lag = Latest Offset - Committed Offset

Lag 持续增加说明消费速度跟不上生产速度。可能原因包括 Consumer 太慢、 Partition 不够、下游数据库慢、Consumer 故障或分配不均。Kafka 集群健康 不代表业务消费健康，Lag 是必须单独监控的指标。

自动提交与手动提交#

自动提交通过 enable.auto.commit=true 周期性提交 Offset。它简单，但业务 一致性控制较弱。典型风险是：

Poll 消息
-> Offset 被自动提交
-> 业务处理
-> 应用崩溃

如果崩溃发生在提交之后、处理完成之前，Kafka 认为消息已经消费，业务却 没有完成，形成业务视角的消息丢失。

手动提交把决定权交给应用：

enable.auto.commit=false
auto.offset.reset=earliest
max.poll.records=100

典型顺序是“处理成功后再提交”：

Poll
-> Process Business
-> Success
-> Commit Offset

commitSync 等待 Broker 确认，行为明确但增加延迟；commitAsync 不阻塞， 吞吐更高，但错误处理和提交顺序更复杂。异步提交失败时通常不能简单重试， 因为后续提交可能已经覆盖了旧位置。

auto.offset.reset 只在没有已提交 Offset 或 Offset 超出保留范围时生效， 不是每次启动都重置。earliest 从仍保留的最早消息开始，latest 从最新位置 开始。

三种投递语义#

At Least Once 是 Kafka 业务系统中最常见的实际语义：处理成功但提交前崩溃， 重启后会从旧 Offset 重新投递，同一条消息可能再次处理。与其追求“绝不重复”， 不如保证重复处理不会产生重复业务副作用。

Exactly Once 需要区分 Kafka 内部语义和业务端到端语义。Kafka 事务可以保证 Kafka 读写和 Offset 的原子性，但无法自动覆盖外部数据库、HTTP 调用和缓存 更新。端到端 Exactly Once 通常还需要幂等 Consumer、事务性 Outbox 或支持 幂等的 Sink。

两个失败窗口#

第二种更危险。因此工程上通常选择“业务事务成功后再提交 Offset”，再通过 幂等处理重复：

Consume
-> Validate
-> Business Transaction
-> Success
-> Commit Offset

这不会消除重复，只是把问题转移到可控制的幂等设计上。

Inbox 与唯一约束#

幂等的基本做法是给每个事件一个稳定的业务标识，例如 eventId，并记录它 是否已经处理。更可靠的方式是把去重记录和业务修改放在同一个数据库事务：

BEGIN;

INSERT INTO processed_events(event_id, processed_at)
VALUES ('evt-10001', NOW());

UPDATE orders
SET status = 'PAID'
WHERE id = 1001;

COMMIT;

如果 event_id 上存在唯一索引，重复消息插入会失败，整个事务回滚，业务 不会被重复执行：

CREATE UNIQUE INDEX uk_processed_event
ON processed_events(event_id);

这就是 Inbox Pattern。它把“是否处理过”变成数据库可以原子判断的事实， 而不是应用内存中的临时状态。应用捕获重复键后，应把该消息视为已处理并提交 Offset，而不是把它当成需要无限重试的故障。

Outbox 解决双写问题#

Producer 侧也有类似问题。创建订单时：

INSERT orders 成功
Kafka Send 失败

数据库里有订单，但没有 OrderCreated 事件。反过来，Kafka 发送成功但数据库 事务回滚，下游会收到一个实际不存在的订单。这称为 Dual Write Problem。

Transactional Outbox 把业务数据和待发送事件写入同一个数据库事务：

BEGIN;

INSERT INTO orders(id, user_id, status)
VALUES (1001, 2001, 'CREATED');

INSERT INTO outbox_events(event_id, topic, payload)
VALUES ('evt-10001', 'order-events', '...');

COMMIT;

随后由独立 Relay 或 CDC 组件读取 outbox_events 并投递到 Kafka：

数据库事务保证业务数据与待发送事件同时存在或同时不存在。Relay 可能重复 投递，因此下游仍需按 eventId 去重。Outbox 解决的是“事件不丢”，不是 “事件只发一次”。

CDC（Change Data Capture，变更数据捕获）可以读取 MySQL Binlog 等数据库 变更日志，再把变化发送到 Kafka。它常用于 Outbox Relay、数据同步和分析 管道，但同样要处理顺序、重复和 Schema 演进。

事件本身要可追踪#

一个便于幂等、审计和回放的事件，至少应包含：

{
  "eventId": "evt-10001",
  "eventType": "ORDER_CREATED",
  "occurredAt": "2026-11-11T10:00:00Z",
  "traceId": "abc123",
  "payload": {}
}

eventId 用于去重，occurredAt 表示业务发生时间，traceId 用于跨异步 边界追踪。不要用消费时间代替业务发生时间：消息积压两小时后才处理，当前 时间已经不是事件发生时间。

事件命名也应表达已经发生的事实，例如 OrderCreated、PaymentSucceeded， 而不是 CreateOrder、DoPayment。后者更像 Command（命令），语义是“请做 某事”，和 Event 的“某事已经发生”不是一回事。

批量消费的提交边界#

Consumer 一次 Poll 可能拿到多条消息。批量处理提高吞吐，但让提交边界更 复杂：

Record 1 Success
Record 2 Success
Record 3 Failed
Record 4 Not Processed

此时不能把整个 Batch 的 Offset 直接提交到最后，否则 Record 3 会被跳过。 可以选择逐条提交、整批成功才提交、失败后 Seek 回退，或交给框架的 Ack Mode 处理。核心原则是：

Offset 不能超过尚未可靠完成的业务消息。

顺序与并发#

如果需要保持 Partition 内顺序，同一 Partition 的消息不能随意无序并发处理。 可以按 Partition 分配 Worker：

P0 -> Worker 0
P1 -> Worker 1
P2 -> Worker 2

不同 Partition 并行，Partition 内串行，既获得并行能力，又保持局部顺序。 为了让单条消息处理更快而在 Partition 内开线程池，必须自行保证提交顺序和 失败回退，否则 Offset 可能先于前一条消息完成。

Rebalance 的代价#

Consumer 加入、离开或 Partition 数量变化，都可能触发 Rebalance，重新分配 Partition Ownership。Rebalance 期间 Consumer 可能短暂停止消费；如果频繁 发生，吞吐会明显下降。

常见触发原因包括 Consumer Crash、频繁启停、处理时间过长、Heartbeat 失败 和网络抖动。Consumer 需要向 Group Coordinator 定期发送 Heartbeat，长时间 没有心跳会被认为离开 Group。

max.poll.interval.ms 控制两次 Poll 之间的最大间隔。如果 Consumer 拉取 消息后处理太久，超过这个时间没有再次 Poll，Kafka 会认为它无法正常消费并 触发 Rebalance。因此不要在 Consumer 线程里执行生成视频、等待人工审批之类 的超长任务，更合适的做法是快速接收任务并交给内部 Worker。

较新的客户端支持 Cooperative Sticky 等增量分配策略，减少全量停顿；静态 成员 group.instance.id 也能降低滚动重启造成的 Rebalance 次数。具体能力 取决于客户端和 Broker 版本。

Retention、Segment 与 Compaction#

Kafka 不会因为消息被消费就删除它，而是按 retention.ms 或 retention.bytes 保留。Partition Log 会拆成多个 Segment，旧 Segment 到 达阈值后被删除。

如果 Consumer 停止的时间超过 Retention，它原来需要的旧消息可能已经不存在。 恢复后只能按 auto.offset.reset 选择最早或最新位置，无法无缝续读。

Kafka 还支持 Log Compaction：对每个 Key 保留最新状态，适合配置、CDC 和 状态重建。Compacted Topic 中的 Value=null Record 是 Tombstone，表示该 Key 被删除。Compaction 是后台过程，不保证立即完成，也不等同于普通 Retention。

Retention 内的消息可以重置 Offset 后重新消费，这叫 Replay。Replay 可用于 修复 Consumer Bug、重建搜索索引或重算分析数据，但必须考虑副作用：重放 PaymentSuccess 时，如果 Consumer 会再次给用户加钱，后果非常严重。

Kubernetes 中的 Consumer#

Consumer 通常以 Deployment 运行，多个 Pod 使用同一个 group.id，由 Kafka 自动分配 Partition。Rolling Update 期间旧 Pod 离开、新 Pod 加入，会触发 Rebalance，因此发布本身就会影响消费稳定性。

Pod 收到 SIGTERM 后，应尽量：

1. 停止获取新消息；
2. 完成正在处理的消息；
3. 提交 Offset；
4. 关闭 Consumer；
5. 离开 Group。

这可以减少重复消费和 Rebalance 冲击。终止宽限期必须覆盖上述步骤，否则 进程会在提交前被强制结束。

Consumer Lag 可以作为 HPA 的扩缩容指标，但扩容受 Partition 数量限制。 10 个 Partition 即使扩到 100 个 Pod，同一 Group 中也只有约 10 个 Consumer 真正获得 Partition。Partition 只能增加不能减少，增加后 Key 的映射可能变化， 这两点都应在容量规划时提前考虑。

监控与容量#

Under Replicated Partition 表示副本数低于配置值，副本健康度已经下降； Offline Partition 表示没有可用 Leader，属于严重故障。Kafka 依赖磁盘保留 消息，磁盘接近满时 Broker 风险很高。

容量不能只看每天写入多少原始数据。Replication Factor 为 3 时，仅副本层面 就需要约 3 倍空间，还要乘以 Retention 天数并预留安全余量，压缩可以降低 实际占用但不能作为唯一依赖。

Kafka 是 Backpressure Buffer，不是无限缓冲区。Producer 100k msg/s、 Consumer 50k msg/s 时，Lag 会持续增长；短时峰值可以靠积压吸收，但生产速率 长期高于消费速率，最终仍会遇到 Retention、磁盘和业务时效问题。

分层定位连接失败#

“Kafka 连不上”可能发生在不同层：

不要把所有异常都归因于“Kafka 挂了”。先确认失败发生在握手、认证、授权还是 业务处理层，才能缩小范围。

用 Header 传播追踪上下文#

Kafka 消息可以携带 Record Header，把 traceId、eventType、 schemaVersion、correlationId 等元数据传给 Consumer。Consumer 读取后 继续使用同一个 Trace Context，就能把 HTTP 请求、Kafka 生产和下游消费串成 一条跨异步边界的调用链。

但不要无限制地把业务数据塞进 Header。Kafka 消息应该偏小，适合传事件元数据 和业务 Payload；大文件应放对象存储，消息里只保留 Object Key 或 URL。对象 存储的模型、分片上传和临时授权，将在 《对象存储与大文件分片传输机制》 中展开。单条消息过大会增加 Broker 内存、网络和 Consumer Fetch 压力，甚至被 直接拒绝；调整大小限制时，要同时核对 Producer、Broker 和 Topic 配置。