2. Kafka 核心原理回顾：Topic 与 Partition、Producer/Consumer 模型、Offset 机制、日志存储结构

在深入诊断堆积问题之前，必须重新夯实 Kafka 的核心数据模型与运行时原理。堆积的本质是生产速度 > 消费速度，而这一失衡直接体现在 Partition、Offset 与日志文件的交互上。本节将围绕四个核心维度展开，为后续的 API 治理与慢查询定位建立统一的认知基线。

2.1 Topic 与 Partition：并行度的物理边界

Topic 是逻辑上的消息分类，Partition 是物理上的存储与并行单元。每个 Partition 对应一个有序、不可变的日志文件（Log），且只被同一个 Consumer Group 内的一个消费者线程持有。

2.2 Producer / Consumer 模型：推拉模式与确认机制

Kafka 采用 Producer 推（Push） + Consumer 拉（Pull） 的混合模型。这一设计直接决定了堆积产生的两个入口：生产端写入过快，或消费端拉取过慢。

2.2.1 Producer 核心参数与确认级别

2.2.2 Consumer 拉取模型与滞后根源

Consumer 通过 poll() 循环主动从 Broker 拉取消息。每次 poll() 返回的消息集合大小由 max.poll.records 控制。如果单条消息处理时间过长，或 max.poll.interval.ms 超时，Consumer 会被踢出 Group 触发 Rebalance，进一步加剧堆积。

2.3 Offset 机制：消费进度的唯一锚点

Offset 是消息在 Partition 内的唯一递增序号。Consumer 通过提交 Offset 来记录消费进度。Offset 管理不当是堆积诊断中最常见的盲区。

• 自动提交（enable.auto.commit=true）： 默认每 5 秒提交一次。若 Consumer 在两次提交之间崩溃，重启后会从上次提交的 Offset 开始消费，导致重复消费；若处理慢但 Offset 已提交，则可能丢失消息。
• 手动提交（enable.auto.commit=false）： 由业务代码控制提交时机。推荐在消息处理成功之后再提交，避免处理失败但 Offset 已前进。
• Offset 存储位置： 旧版本依赖 ZooKeeper，新版本（0.9+）使用内部 Topic __consumer_offsets（默认 50 个 Partition）。

2.4 日志存储结构：文件系统视角的堆积根源

Kafka 的日志存储设计直接决定了磁盘 IO 模式与堆积恢复速度。每个 Partition 对应一个目录，目录下包含多个 Segment 文件，每个 Segment 由 .log、.index、.timeindex 三个文件组成。

2.4.1 日志写入与刷盘策略

消息先写入操作系统的 Page Cache，然后由后台线程异步刷盘（flush）。这种设计提供了极高的写入吞吐，但也带来了数据丢失的风险。

# 关键刷盘参数（server.properties）
log.flush.interval.messages=10000        # 累积多少条消息后刷盘
log.flush.interval.ms=1000               # 间隔多少毫秒刷盘
log.segment.bytes=1073741824             # 单个 Segment 最大 1GB
log.retention.hours=168                  # 日志保留 7 天
log.retention.check.interval.ms=300000   # 每 5 分钟检查一次过期日志

2.5 核心原理与堆积诊断的映射关系

将上述原理映射到堆积诊断场景，可以归纳为以下检查清单：

1. Partition 分布检查： 确认 Topic 的 Partition 数是否 ≥ Consumer Group 内最大并发数。若不足，堆积必然集中在少数 Partition。
2. Offset 提交检查： 确认 Consumer 使用手动提交且在处理成功后提交。自动提交场景下需检查 auto.commit.interval.ms 是否过大。
3. 日志段检查： 使用 kafka-log-dirs 查看各 Partition 的 Segment 数量与磁盘占用。Segment 过多（超过 1000 个）会导致索引查询性能下降。
4. 刷盘与保留策略检查： 确认 log.retention.hours 是否过短导致历史数据被删除，或过长导致磁盘空间不足触发自动删除。