📚 课程目录第1章时间戳索引概述

1. 时间戳索引概述

Kafka 时间戳索引（Timestamp Index）是 Kafka 日志段（Log Segment）中用于加速基于时间戳的消息定位的二级索引结构。每个日志段对应一个 .timeindex 文件，与偏移量索引（.index）协同工作，共同构成 Kafka 的索引体系。

时间戳索引本质上是一个稀疏有序映射表，记录日志段内每条消息的时间戳与相对偏移量之间的对应关系。当消费者或管理员按时间范围检索消息时，Kafka 通过二分查找时间戳索引文件，快速定位到目标日志段及段内起始偏移量，避免全量扫描。

索引类型	文件后缀	键	值	主要用途
偏移量索引	.index	相对偏移量	物理文件位置	按偏移量快速定位消息
时间戳索引	.timeindex	时间戳（毫秒）	相对偏移量	按时间戳快速定位消息

  关键定义：时间戳索引是 Kafka 实现时间维度消息检索的核心数据结构，每个索引条目占用 12 字节（8 字节时间戳 + 4 字节相对偏移量），默认每写入 4KB 消息数据生成一条索引记录。

时间戳索引在 Kafka 消息生命周期中承担三项核心作用：

时间范围检索加速：消费者通过 offsetsForTimes() 接口按时间戳查找偏移量时，Broker 在时间戳索引上执行二分查找，复杂度为 O(log N)，N 为索引条目数。
日志 compaction 与清理：Kafka 日志清理线程根据时间戳索引判断日志段是否超过保留期限，决定是否删除或合并。
Exactly-Once 语义支撑：事务协调器依赖时间戳索引定位事务日志中的事务开始/结束时间点，确保事务状态恢复的精确性。

Kafka 消息检索场景中，时间戳索引是唯一支持 O(log N) 时间维度查询的索引结构。对比全量扫描日志段的方式，时间戳索引将检索效率提升数个数量级：

检索方式	时间复杂度	10GB 日志段耗时（估算）	适用场景
全量扫描日志段	O(N)	~30 秒	无索引可用时的兜底方案
时间戳索引 + 二分查找	O(log N)	~5 毫秒	生产环境标准检索路径
偏移量索引 + 时间戳索引联合	O(log N + log M)	~8 毫秒	精确偏移量定位 + 时间范围过滤

工程经验：在日均消息量超过 1 亿条的生产集群中，时间戳索引的缺失会导致 offsetsForTimes() 接口延迟从毫秒级飙升到分钟级，直接引发消费者组重平衡超时和消息积压。

Kafka 的 Exactly-Once 语义（EOS）依赖事务日志（Transaction Log）记录事务状态变更。事务日志本身也是 Kafka 主题，时间戳索引在其中扮演两个不可替代的角色：

事务状态恢复的时间锚点：事务协调器崩溃恢复时，通过时间戳索引定位到最近一次事务提交/中止的时间点，确保事务状态不会回滚到更早的无效状态。
事务超时判定：协调器根据时间戳索引判断事务是否超时（transaction.timeout.ms），超时事务将被强制中止，防止事务悬挂导致分区不可写。