4. 索引文件原理（上）：偏移量索引（Offset Index）的结构与二分查找机制

在 Kafka 中，每个分区日志目录下都包含多个索引文件，其中 偏移量索引（Offset Index） 是最核心的查找结构。它负责将逻辑偏移量（Logical Offset）快速映射到物理文件位置（Physical Position），从而避免在庞大的日志段（LogSegment）中进行全量扫描。

4.1 偏移量索引的文件布局

偏移量索引文件（.index）是一个稀疏的、定长记录的、顺序写入的二进制文件。每条索引条目固定为 8 字节，结构如下：

4.2 偏移量索引的写入与增长

索引文件的写入遵循以下规则：

1. 追加写入：新条目始终追加到文件末尾，保证顺序 I/O 性能。
2. 单调递增：relativeOffset 和 position 均严格单调递增，这是二分查找的前提。
3. 稀疏间隔：由 log.index.interval.bytes 控制（默认 4096），即每写入约 4KB 消息数据才插入一条索引。
4. 文件切分：当索引文件大小达到 log.index.size.max.bytes（默认 10MB）时，触发日志段滚动，生成新的索引文件。

4.3 二分查找机制详解

Kafka 对偏移量索引的查找采用改进的二分查找（Binary Search），其核心流程如下：

1. 确定查找范围：根据目标偏移量 targetOffset 计算 targetRelativeOffset = targetOffset - baseOffset，在索引数组中划定 [low, high] 区间。
2. 快速缩小范围：每次取中间索引 mid = (low + high) / 2，读取 8 字节条目，比较 relativeOffset 与 targetRelativeOffset。
3. 返回不大于目标的最大值：当 low > high 时，返回 high 对应的条目（即最后一个小于等于目标偏移量的索引）。
4. 物理位置转换：将查到的 position 作为起始点，在 .log 文件中从该位置开始顺序扫描，直到找到精确的消息。

4.4 偏移量索引结构示意图

下图展示了偏移量索引文件与日志段文件的对应关系，以及二分查找的定位过程：

4.5 二分查找的边界处理与优化

Kafka 在实现二分查找时，针对稀疏索引的特点做了以下优化：

4.6 偏移量索引与时间索引的协作

Kafka 还提供了时间索引（Time Index）（.timeindex），用于按时间戳查找消息。两者协作流程如下：

1. 时间索引查找：根据目标时间戳，在时间索引中二分查找，获得对应的偏移量范围。
2. 偏移量索引查找：将上一步得到的偏移量作为输入，在偏移量索引中二分查找，获得物理位置。
3. 日志段扫描：从物理位置开始顺序扫描，找到精确匹配的消息。

4.7 偏移量索引的局限性

尽管偏移量索引非常高效，但在以下场景中仍需注意：

• 稀疏间隔过大：如果 log.index.interval.bytes 设置过大（如 1MB），会导致每次查找后需要扫描大量消息，增加延迟。
• 索引文件损坏：由于索引文件是二进制格式，一旦发生磁盘故障或非正常关闭，可能导致索引损坏，需要重建。
• 内存压力：虽然索引文件使用内存映射，但大量分区的索引同时加载仍可能占用较多虚拟内存地址空间（尤其在 32 位 JVM 上）。