阅读目标#

第一篇建立了 Kafka 的核心世界观：Topic 由多个 Partition 组成，每个 Partition 是一条有序、可持久化、可按 Offset 读取的 Log。

但这仍然只是逻辑模型。

第二篇要把一个 Partition 放大到磁盘和内核层，回答两个真正决定 Kafka 工程能力的问题：

1. 一批 Record 如何从 Broker 网络请求进入 Partition Log，并最终形成磁盘文件？
2. Consumer 请求 Offset=36891 时，Broker 如何找到对应 RecordBatch，并高效返回数据？

完成本篇后，你应该能够：

• 区分 Record、RecordBatch、LogSegment、Partition Log 四个层次；
• 解释 .log、.index、.timeindex 与 .txnindex 的职责；
• 手工推导一次 Offset → Segment → Relative Offset → Physical Position → RecordBatch；
• 画出 Broker 侧 Produce 和 Fetch 的核心执行链；
• 区分 Kafka Offset 与文件字节 Position；
• 区分“写入 Page Cache”和“同步到物理介质”；
• 准确解释 Page Cache、批处理、压缩和高效文件传输在 Kafka 数据路径中的作用；
• 不再用“因为顺序写和零拷贝”这一句空泛结论回答 Kafka 为什么快。

本文以 Apache Kafka 4.3 文档和当前 4.x 源码结构为主线。Kafka 4.3 的消息格式仍以 RecordBatch 为磁盘和协议数据单元；生产级源码阅读时，应固定到实际使用的 4.3.x Tag，避免把不断变化的 trunk 行号当作稳定接口。110

1.1 逻辑 Log 与物理文件不是同一个概念#

第一篇中的 Partition 是一条逻辑上连续增长的 Log：

1
Partition 3
2

3
Offset
4
0 → 1 → 2 → 3 → 4 → 5 → 6 → ...

这种表示非常适合解释顺序、Replay 和 Consumer Position，但它隐藏了真实物理结构。

在磁盘上，一个 Partition 通常对应一个独立目录，目录中由多个 Segment 文件集合共同组成这条 Log：

1
Partition Directory
2
        │
3
        ├── Segment 0
4
        ├── Segment 1
5
        ├── Segment 2
6
        └── Active Segment

因此需要建立第一组映射：

这里最容易混淆的是：

1
Kafka Offset ≠ 文件字节 Position

Offset=36891 并不意味着文件的第 36891 个字节。

因为每条 Record 的 Key、Value、Header 长度都可能不同；RecordBatch 还包含批头、压缩数据、CRC 和变长编码。逻辑 Offset 与物理字节位置之间不存在简单的一一等长关系。

1.2 为什么不能只使用一个无限增长的文件#

假设一个 Partition 永远只写：

1
partition.log

随着业务运行，这个文件可能达到几百 GB 甚至数 TB。此时系统需要处理：

• 删除七天前的数据；
• 重建损坏索引；
• 崩溃后检查尾部不完整写入；
• 对历史 Key 做 Log Compaction；
• 把冷数据迁移到远程存储；
• 迁移或重新分配 Partition；
• 对文件做关闭、回收和生命周期管理。

如果只有一个大文件，删除旧数据就意味着修改或重写文件前半部分；索引损坏时可能扫描整条超大 Log；Compaction 也缺少可控的处理边界。

Kafka 因而把 Partition 拆成多个 Segment：

1
Partition 3
2

3
Segment 0       [0      … 31999]
4
Segment 1       [32000  … 63999]
5
Segment 2       [64000  … 95999]
6
Active Segment  [96000  …     ]

Segment 为以下工程操作提供了独立边界：

1
Roll
2
Retention Delete
3
Compaction
4
Recovery
5
Transfer
6
Tiering

Segment 不是为了改变 Partition 的逻辑连续性，而是为了让持续增长的 Log 可以被分块管理。

1.3 Active Segment 与 Closed Segment#

一个 Partition 在任意时刻通常只有一个当前写入 Segment：

1
[Closed Segment]
2
[Closed Segment]
3
[Closed Segment]
4
[Active Segment] ← 新 RecordBatch 追加到这里

1.4 Partition 是“有序 Segment 集合”#

所以，一个更接近实现的 Partition 模型是：

1
Partition
2
   ↓
3
Ordered Segment Collection
4
   ↓
5
Closed Segments + One Active Segment
6
   ↓
7
Each Segment = Data File + Index Files

第一篇说 Partition 是一条 Log；第二篇需要补充：

Partition 在逻辑上连续，在物理上由多个按照 Base Offset 排序的 Segment 拼接而成。

2.1 错误认知：Kafka 一次只处理一条消息#

初学者很容易把 Kafka 想象成：

1
Record 1 → 一次网络请求 → 一次磁盘写入
2
Record 2 → 一次网络请求 → 一次磁盘写入
3
Record 3 → 一次网络请求 → 一次磁盘写入

如果真的如此，每条小消息都可能重复承担：

• 请求头；
• 协议解析；
• 系统调用；
• CRC 处理；
• 压缩上下文；
• 网络包与磁盘写入调度。

Kafka 的当前消息格式以 RecordBatch 为核心：消息始终以 Batch 形式写入；即便 Batch 只有一条 Record，它仍是一个 RecordBatch。1

1
Record 1
2
Record 2
3
Record 3
4
Record 4
5
    │
6
    ▼
7
RecordBatch
8
    ├── 共享批头
9
    ├── 共享 CRC 边界
10
    ├── 共享压缩边界
11
    ├── 连续网络传输
12
    └── 连续磁盘追加

2.2 四层数据结构必须分清#

1
Record
2
   ↓
3
RecordBatch
4
   ↓
5
LogSegment
6
   ↓
7
Partition Log

1
Key
2
Value
3
Timestamp Delta
4
Offset Delta
5
Headers

2.3 RecordBatch Header#

Kafka 4.3 文档给出的当前 RecordBatch 磁盘格式包含以下核心字段：1

1
RecordBatch
2
├── baseOffset: int64
3
├── batchLength: int32
4
├── partitionLeaderEpoch: int32
5
├── magic: int8
6
├── crc: uint32
7
├── attributes: int16
8
│   ├── compressionType
9
│   ├── timestampType
10
│   ├── isTransactional
11
│   └── isControlBatch
12
├── lastOffsetDelta: int32
13
├── baseTimestamp: int64
14
├── maxTimestamp: int64
15
├── producerId: int64
16
├── producerEpoch: int16
17
├── baseSequence: int32
18
├── recordsCount: int32
19
└── records[]

本篇重点关注：

• baseOffset：Batch 第一条 Record 的绝对 Offset；
• lastOffsetDelta：Batch 最后一条 Record 相对 Base Offset 的增量；
• baseTimestamp：Batch 时间戳基准；
• attributes：压缩类型等 Batch 属性；
• crc：Batch 数据完整性校验；
• recordsCount：Batch 中 Record 数量。

而以下字段只先认识，不展开机制：

1
producerId
2
producerEpoch
3
baseSequence
4
isTransactional
5
isControlBatch

它们与幂等 Producer、事务和 Control Batch 密切相关，将在第五篇完整展开。

2.4 Base Offset 与 Offset Delta#

假设：

1
baseOffset = 1000

Batch 内部四条 Record 可以保存：

1
Record A: offsetDelta = 0 → Offset 1000
2
Record B: offsetDelta = 1 → Offset 1001
3
Record C: offsetDelta = 2 → Offset 1002
4
Record D: offsetDelta = 3 → Offset 1003

最终 Offset 的计算是：

1
absoluteOffset = baseOffset + offsetDelta

这样不需要每条 Record 都重复保存完整 64 位绝对 Offset。

时间戳也使用类似思路：

1
baseTimestamp = T₀
2

3
Record A: timestampDelta = 0
4
Record B: timestampDelta = 12 ms
5
Record C: timestampDelta = 24 ms

这体现了一种典型的批数据编码方式：

1
Batch 共享元数据
2
+
3
Record 保存局部 Delta
4
=
5
减少重复字段和编码体积

2.5 为什么压缩边界是 Batch#

如果逐条压缩：

1
compress(record1)
2
compress(record2)
3
compress(record3)

压缩算法很难充分利用不同 Record 之间的重复模式。

而业务事件通常具有高度相似的结构：

1
{
2
  "orderId": "...",
3
  "userId": "...",
4
  "eventType": "OrderCreated",
5
  "timestamp": "..."
6
}

字段名、Schema 和许多枚举值会反复出现。将多条 Record 放进同一个 Batch 后再压缩：

1
compress(record1 + record2 + record3 + ...)

可以获得更好的压缩比，同时减少 Broker 磁盘占用与网络字节数。

Kafka 设计文档强调：Record 可以成批分组、压缩后发送，Broker 校验 Batch 后仍可以把压缩后的 Batch 写入 Log，并继续以压缩形式传给 Consumer。2

但这里存在明确权衡：

1
Batch 更充分
2
    → 吞吐与压缩率通常更好
3
    → 可能等待更多数据
4
    → 单条消息端到端延迟可能增加

本篇只解释存储与协议为什么以 Batch 为边界；batch.size、linger.ms、RecordAccumulator 和 ProducerBatch 如何真正形成 Batch，将在第三篇沿 Producer 执行链展开。

2.6 CRC 校验边界#

RecordBatch Header 中包含 CRC。它主要用于发现：

• 网络传输损坏；
• 磁盘数据损坏；
• 不完整或非法 Batch；
• 结构字段与数据不一致。

Kafka 的 CORRUPT_MESSAGE 错误也明确包含 CRC 失败等消息损坏场景。13

这里必须区分：

1
CRC 完整性校验
2
        ≠
3
副本一致性保证

CRC 回答的是“这批字节是否被损坏”；副本、ISR、Leader Election 和 ACK 回答的是“在机器故障后哪些数据仍然算已提交”。后者属于第五篇。

2.7 RecordBatch 为什么是 Kafka 性能的核心#

RecordBatch 同时贯穿：

1
Producer 聚合
2
    ↓
3
ProduceRequest
4
    ↓
5
Broker 校验
6
    ↓
7
Segment Append
8
    ↓
9
磁盘保存
10
    ↓
11
FetchResponse
12
    ↓
13
Consumer 解压和迭代

因此 Kafka 的批处理不是 Producer 端的局部优化，而是一条跨客户端、协议、Broker、磁盘和 Consumer 的端到端数据边界。

3.1 一个 Segment 不是一个文件#

一个 Partition 目录可能是：

1
order-events-3/
2
├── 00000000000000000000.log
3
├── 00000000000000000000.index
4
├── 00000000000000000000.timeindex
5
├── 00000000000000000000.txnindex
6
│
7
├── 00000000000000320000.log
8
├── 00000000000000320000.index
9
├── 00000000000000320000.timeindex
10
├── 00000000000000320000.txnindex
11
│
12
├── 00000000000000640000.log
13
├── 00000000000000640000.index
14
├── 00000000000000640000.timeindex
15
└── 00000000000000640000.txnindex

拥有相同文件名前缀的一组文件构成一个 Segment：

1
00000000000000320000.log
2
00000000000000320000.index
3
00000000000000320000.timeindex
4
00000000000000320000.txnindex

它们共享：

1
Segment Base Offset = 32000

从对象模型看，可以把 LogSegment 简化理解为：

1
final class LogSegment {
2
    FileRecords log;
3
    OffsetIndex offsetIndex;
4
    TimeIndex timeIndex;
5
    TransactionIndex transactionIndex;
6
    long baseOffset;
7
}

这不是 Kafka 原始源码，而是为了保留关键组成关系的概念伪代码。

当前 Kafka 源码中的 LogSegment、OffsetIndex、TimeIndex 和 TransactionIndex 正是这一层的重要阅读入口。10

3.2 文件名为什么是 Base Offset#

文件名：

1
00000000000000320000.log

不是时间戳，也不是随机 UUID，而是 Segment Base Offset 的补零表示：

1
Base Offset = 32000

假设 Segment 集合为：

1
Segment A: baseOffset = 0
2
Segment B: baseOffset = 32000
3
Segment C: baseOffset = 64000

目标 Offset=36891 时，可以先选择：

1
最大的 baseOffset ≤ 36891

即 Segment B。

Base Offset 同时承担：

• Segment 排序键；
• 文件名；
• 绝对 Offset 与相对 Offset 的换算基准；
• 定位某个 Offset 所属 Segment 的边界。

3.3 .log 文件保存什么#

.log 不是文本日志，也不是一行一条 JSON。

它保存二进制编码的连续 RecordBatch：

1
.log
2

3
┌──────────────────┐
4
│ RecordBatch 32000│
5
├──────────────────┤
6
│ RecordBatch 32071│
7
├──────────────────┤
8
│ RecordBatch 32146│
9
├──────────────────┤
10
│ RecordBatch 32219│
11
└──────────────────┘

两个相邻 Batch 的 Base Offset 不一定只相差 1，因为一个 Batch 内可能包含数十、数百甚至更多 Record。

.log 是 Segment 的主要事实数据；其他索引结构都是为了加速对它的读取。

3.4 .index：Offset 到 Physical Position#

Offset Index 的核心映射是：

1
Relative Offset → Physical Position

假设当前 Segment Base Offset=32000：

绝对 Offset 与相对 Offset 的关系：

1
relativeOffset = absoluteOffset - segmentBaseOffset
2
absoluteOffset = segmentBaseOffset + relativeOffset

例如：

1
Target Offset = 36891
2
Base Offset   = 32000
3
Relative      = 4891

Offset Index 不保存业务 Value，也不一定为每条 Record 保存一项。它只提供一个接近目标的物理文件起点。

3.5 为什么使用 Relative Offset#

Partition Offset 使用长整型，是全 Partition 范围内持续增长的逻辑位置。

但一个 Segment 内只需要表示：

1
目标 Offset 离 Base Offset 有多远

使用 Relative Offset 可以采用更紧凑的索引条目，减少索引文件体积和内存映射压力。

同时，这也说明 Segment 不能无限增长：当相对 Offset 的可表示范围、索引容量或其他边界接近限制时，需要 Roll 出新的 Segment。

3.6 .timeindex：Timestamp 到 Relative Offset#

Time Index 的核心映射是：

1
Timestamp → Relative Offset

而不是：

1
Timestamp → `.log` Physical Position

因此按时间查找通常需要两次映射：

1
Timestamp
2
    ↓
3
TimeIndex
4
    ↓
5
Approximate Offset
6
    ↓
7
OffsetIndex
8
    ↓
9
Physical Position
10
    ↓
11
.log Scan

Kafka Topic 配置文档还说明，时间索引只有在时间戳大于上一个已索引时间戳时才插入对应项。3

3.7 .txnindex：事务读取的辅助结构#

Transaction Index 与被中止事务范围有关，用于事务隔离读取时识别不应向 read_committed Consumer 暴露的事务数据。

本篇只建立它的文件职责：

1
.txnindex = 事务相关的派生辅助索引

以下内容留到第五篇：

1
Transaction Coordinator
2
Commit / Abort Marker
3
Last Stable Offset
4
Aborted Transaction
5
read_committed

3.8 Primary Data 与 Derived Index#

需要建立一个非常重要的存储系统认知：

1
.log
2
=
3
Primary Data / Source of Truth
4

5
.index / .timeindex
6
=
7
Derived Acceleration Structures

索引的职责是加速查找；如果索引损坏，系统可以通过扫描 .log 中的 RecordBatch 重建索引。

因此，Kafka 没有把所有信息都不可恢复地压进索引，而是把事实数据和查询加速结构分开。

4.1 第一阶段：定位 Segment#

假设 Partition 的 Segment Base Offset 为：

1
0
2
32000
3
64000
4
96000

目标：

1
Offset = 36891

Kafka 需要找到：

1
最大的 Base Offset ≤ 36891

即：

1
floorEntry(36891) = 32000

因此选中：

1
00000000000000320000.log

这一步把搜索范围从整个 Partition 缩小到了一个 Segment。

4.2 第二阶段：计算 Relative Offset#

1
Target Offset = 36891
2
Segment Base  = 32000
3

4
Relative Offset
5
= 36891 - 32000
6
= 4891

OffsetIndex 在 Segment 内保存的是 Relative Offset，因此需要先完成这一坐标转换。

4.3 第三阶段：查询稀疏 OffsetIndex#

假设 .index 中存在：

目标 Relative Offset=4891。

不能选择 5120，因为它可能已经越过目标位置；应寻找：

1
最大的 indexedOffset ≤ 4891

因此得到：

1
Relative Offset = 4096
2
Physical Position = 153800

4.4 第四阶段：从附近 Position 顺序扫描#

索引并没有精确保存 Offset=4891 的字节位置。

Kafka 只知道：

从 .log 的 Position 153800 开始扫描，目标 RecordBatch 应该位于其后不远处。

于是顺序解析 RecordBatch：

1
Batch Base Offset = 36096
2
Batch Base Offset = 36320
3
Batch Base Offset = 36672
4
Batch Base Offset = 36864

如果最后一个 Batch 的范围覆盖 36891，就完成定位。

完整过程：

1
Offset 36891
2
      ↓
3
Segment Floor Lookup
4
      ↓
5
Segment Base Offset 32000
6
      ↓
7
Relative Offset 4891
8
      ↓
9
Sparse OffsetIndex
10
      ↓
11
Nearest Position 153800
12
      ↓
13
Sequential RecordBatch Scan
14
      ↓
15
Target RecordBatch

4.5 为什么不是稠密索引#

如果每条 Record 都维护：

1
Offset 0 → Position 0
2
Offset 1 → Position 125
3
Offset 2 → Position 284
4
...

查找会更精确，但代价也非常明确：

• 索引条目数量接近 Record 数量；
• 索引文件显著膨胀；
• 写入时需要更频繁更新索引；
• Page Cache 和地址空间消耗增加；
• 恢复与重建成本上升。

Kafka 选择：

1
小型稀疏索引
2
+
3
邻近定位
4
+
5
短距离顺序扫描

本质上是在权衡：

1
Index Size ↔ Scan Distance

由于 .log 本身按照 Offset 顺序保存 RecordBatch，在找到邻近物理位置后做有限顺序扫描非常自然。

因此，稀疏索引不是“查询不够快的低配方案”，而是充分利用有序 Log 特征后的工程选择。

4.6 index.interval.bytes 不是“每隔多少条消息”#

Kafka Topic 配置中的 index.interval.bytes 控制大约累计写入多少消息字节后添加一条 Offset Index，并在满足时间条件时添加 Time Index。Kafka 4.3 默认大约每 4096 字节创建索引项。3

正确理解：

1
每累计约 N 字节数据
2
创建一个稀疏索引点

错误理解：

1
每 N 条消息创建一个索引点

因为不同 Record 和 Batch 大小并不固定。

索引更密：

1
查询更接近目标
2
扫描更少
3
索引文件更大
4
写索引更频繁

索引更稀：

1
索引更小
2
查询后需要多扫描一点数据

通常没有充分基准测试和明确瓶颈时，不应随意修改这一参数。

4.7 TimeIndex 为什么还要经过 OffsetIndex#

假设业务希望：

查找时间戳大于等于 10:30:00 的第一条 Record。

读取链是：

1
Target Timestamp
2
       ↓
3
TimeIndex Binary Search
4
       ↓
5
Approximate Relative Offset
6
       ↓
7
Absolute Offset
8
       ↓
9
OffsetIndex Lookup
10
       ↓
11
Physical Position
12
       ↓
13
.log Sequential Scan
14
       ↓
15
Target Record

TimeIndex 解决的是：

1
时间坐标 → Offset 坐标

OffsetIndex 解决的是：

1
Offset 坐标 → 文件字节坐标

两个索引不是重复设计，而是连接三种不同坐标系：

1
Timestamp
2
Offset
3
Physical Position

4.8 mmap 在索引层的意义#

Kafka 的索引文件适合：

• 条目固定、体积相对可控；
• 按位置随机访问；
• 频繁二分查找；
• 不希望完整复制进 JVM Heap。

索引实现会使用内存映射文件相关机制，让操作系统按页加载需要访问的区域。

需要避免两个极端误解：

错误一：

1
用了 mmap，索引就一定永久全部驻留物理内存。

实际页面仍由 OS 根据内存压力调度。

错误二：

1
mmap 等于 Kafka 自己在 JVM Heap 中缓存全部索引。

内存映射文件并不等价于普通 Java Heap 对象数组。

当前源码阅读可从 OffsetIndex、TimeIndex 及其共同抽象进入，重点观察查找、扩展、截断、重映射与关闭逻辑。10

4.9 本章完整算例#

最终把一次定位压缩成可脱稿复述的算例：

1
Target Offset = 36891
2

3
Segment Base Offsets:
4
0, 32000, 64000
5

6
Step 1:
7
选择 floor segment = 32000
8

9
Step 2:
10
relativeOffset = 36891 - 32000 = 4891
11

12
Step 3:
13
OffsetIndex 中查找 <= 4891 的最大条目
14
得到 4096 → position 153800
15

16
Step 4:
17
从 .log position 153800 顺序解析 RecordBatch
18
直到找到覆盖 Offset 36891 的 Batch

如果只能说“Kafka 用二分查找找消息”，说明理解还不够精确。

Kafka 实际上组合了：

1
Segment Floor Lookup
2
+
3
Sparse Index Lookup
4
+
5
Sequential Batch Scan

5.1 Broker 写入主链#

为了建立源码地图，可以先记住一条经过压缩的主链：

1
SocketServer / Processor
2
        ↓
3
RequestChannel
4
        ↓
5
KafkaRequestHandler
6
        ↓
7
KafkaApis.handleProduceRequest
8
        ↓
9
ReplicaManager.appendRecords
10
        ↓
11
Partition Leader
12
        ↓
13
UnifiedLog.appendAsLeader
14
        ↓
15
Active LogSegment.append
16
        ↓
17
FileRecords.append

当前 Kafka Broker 的请求处理、Replica 管理和存储层仍可以沿 SocketServer、KafkaRequestHandler、KafkaApis、ReplicaManager、Partition、UnifiedLog 与 LogSegment 建立阅读路线。911

注意：类名和核心职责相对稳定，但方法签名、异步封装、错误处理和模块位置会随版本演进。阅读实际生产版本时应固定 Tag。

5.2 为什么网络线程不直接执行完整存储写入#

Broker 接受大量客户端连接。如果网络线程在读完请求后直接完成全部校验、Leader 检查、Log Append 和等待逻辑：

1
某个请求处理变慢
2
      ↓
3
Network Thread 长时间被占用
4
      ↓
5
同一 Processor 上其他连接无法及时读写
6
      ↓
7
网络层吞吐和延迟抖动

因此 Broker 将职责拆分：

1
接受连接
2
读取 Socket 数据
3
协议帧处理
4
Request 入队
5
Response 写回

1
API 分发
2
授权与参数校验
3
调用 ReplicaManager
4
执行 Produce / Fetch 等业务请求逻辑

1
Partition Leader 检查
2
Log Append / Read
3
Segment / Index 管理
4
副本相关状态

5.3 Produce 请求进入 Broker 后校验什么#

真实源码中校验和错误分支很多，本篇只保留与存储主线直接相关的类别：

1
Topic / Partition 是否存在
2
当前 Broker 是否承载对应 Replica
3
当前 Replica 是否为可写 Leader
4
RecordBatch 格式是否合法
5
CRC 与长度是否一致
6
Batch / Record 大小是否超限
7
时间戳规则是否满足
8
幂等与事务元数据是否合法

这里不能把所有校验都归为“消息格式校验”。

例如：

• NOT_LEADER_OR_FOLLOWER 属于 Partition 角色和 Metadata 问题；
• CORRUPT_MESSAGE 可能来自 CRC、尺寸或 Batch 结构；
• MESSAGE_TOO_LARGE 属于消息大小边界；
• 幂等序列检查属于 Producer 状态验证。

本篇只关注校验之后，Batch 如何进入 Leader Log。

5.4 最终 Offset 为什么由 Leader Log 决定#

Producer 可以在客户端构造 Batch，但 Partition 的最终 Offset 必须符合 Leader Log 当前顺序。

假设 Leader 当前：

1
Log End Offset = 36891

新 Batch 有 100 条 Record，则可抽象为：

1
firstOffset = 36891
2
lastOffset  = 36990
3
newLogEndOffset = 36991

简化伪代码：

1
AppendResult appendAsLeader(Records records) {
2
    long firstOffset = currentLogEndOffset();
3
    assignOffsets(records, firstOffset);
4
    activeSegment().append(records);
5
    updateLogEndOffset(records);
6
    return result;
7
}

这段代码不是 Kafka 原始实现，只表达三个关键顺序：

1. 根据 Leader Log 当前末尾确定新 Batch 的位置；
2. 对 Batch 分配或校正最终 Offset；
3. 追加后推进 Log End Offset。

为什么不能由每个 Producer 自己决定最终 Offset？

因为多个 Producer 会并发写同一 Partition。Offset 表达的是 Leader Log 中的全局追加顺序，只有掌握该 Log 写入权的一方才能确定最终顺序。

5.5 为什么只向 Active Segment 追加#

Partition 中的写入目标不是随机 Segment：

1
Closed Segment 0
2
Closed Segment 1
3
Closed Segment 2
4
Active Segment 3 ← append here

这使主要写入路径集中在：

1
当前文件尾部

避免：

• 修改历史文件中间位置；
• 在大量 Segment 间随机选择写入点；
• 维护复杂的可变页更新；
• 对历史记录执行原地覆盖。

Kafka 所谓“顺序写”首先来自这个数据模型：

1
Append-only Partition Log
2
+
3
One Active Segment
4
=
5
Tail Append Path

顺序写不是后来附加的磁盘优化，而是 Log 抽象的自然结果。

5.6 什么时候需要 Roll#

在追加前后，Broker 需要判断当前 Active Segment 是否应当关闭并创建新 Segment。

Roll 条件可归纳为：

1
Segment Size
2
Segment Age
3
Index Capacity
4
Relative Offset Range
5
特定管理条件

若需要 Roll：

1
Old Active Segment
2
      ↓ close
3
Closed Segment
4

5
Current Log End Offset
6
      ↓ becomes new base offset
7
New Active Segment

Roll 的完整生命周期放在第八章。

5.7 .log 与索引如何共同推进#

简化写入过程：

1
解析与校验 RecordBatch
2
          ↓
3
确定 Batch Offset 范围
4
          ↓
5
必要时 Roll Segment
6
          ↓
7
追加 Batch 到 .log 文件尾部
8
          ↓
9
达到 index.interval.bytes 时追加 OffsetIndex
10
          ↓
11
满足时间索引条件时追加 TimeIndex
12
          ↓
13
更新 Log End Offset 与状态

关键点：

不是每写一条 Record 就一定新增一条 OffsetIndex 或 TimeIndex。

.log 保存完整 Batch；索引按间隔采样，因此形成稀疏结构。

5.8 写入 Page Cache 不等于物理落盘#

应用程序调用文件写入后，数据通常先进入操作系统 Page Cache：

1
Kafka Broker
2
      ↓ write
3
OS Page Cache / Dirty Pages
4
      ↓ flush / writeback
5
Storage Device

需要区分三个时刻：

1
1. Java 写入调用返回
2
2. 数据进入内核 Page Cache
3
3. 脏页真正写入物理介质

它们不一定同时发生。

所以，不能看到 Broker Append 成功就简单断言：

1
每条消息已经立即 fsync 到磁盘硬件

但也不能反过来断言 Kafka 因而不可靠。Kafka 的可靠性模型组合了：

1
Leader Append
2
Replica Fetch
3
ISR
4
acks
5
min.insync.replicas
6
故障选主

这些属于第五篇。

本篇只需要记住：

Kafka 的高吞吐写路径通常依赖 OS 缓存和异步刷盘，而不是每条 Record 都执行一次同步物理写入。

5.9 为什么 Kafka 不在 JVM Heap 里缓存全部消息#

假设 Broker 自己维护一个巨大 Java 消息缓存：

1
Disk File
2
   ↓ copy
3
OS Page Cache
4
   ↓ copy
5
JVM Heap Message Cache
6
   ↓ copy
7
Socket Output

会产生：

• Page Cache 与 JVM Cache 双份占用；
• 大量长生命周期大对象；
• GC 扫描、晋升和停顿压力；
• 缓存淘汰逻辑重复；
• Broker 重启后 JVM Cache 全部重建；
• 数据仍然要经过内核网络栈。

操作系统已经非常擅长：

• 缓存最近读写文件页；
• 在内存压力下回收页面；
• 预读连续文件；
• 在文件和网络之间组织高效传输。

Kafka 设计文档明确强调利用文件系统 Page Cache，而不是维护等量的应用层内存缓存。2

这并不表示 Kafka 不使用 Heap。Broker 仍需要大量对象管理请求、Metadata、索引状态、网络和控制逻辑。真正的区别是：

Kafka 不试图把完整消息数据集再次复制成一套巨大 JVM Heap Cache。

5.10 Broker 写入链伪代码#

把真实代码压缩为学习伪代码：

1
ProduceResponse handleProduceRequest(ProduceRequest request) {
2
    Map<TopicPartition, Records> batches = request.partitionRecords();
3

4
    for (var entry : batches.entrySet()) {
5
        Partition partition = replicaManager.requirePartition(entry.getKey());
6
        partition.appendRecordsToLeader(entry.getValue());
7
    }
8

9
    return buildResponse();
10
}

继续向下：

1
AppendResult appendRecordsToLeader(Records records) {
2
    ensureCurrentReplicaIsLeader();
3
    return unifiedLog.appendAsLeader(records);
4
}

存储主路径：

1
AppendResult appendAsLeader(Records records) {
2
    validate(records);
3
    assignOffsets(records, logEndOffset());
4

5
    if (shouldRoll(records)) {
6
        roll();
7
    }
8

9
    activeSegment().append(records);
10
    updateLogState(records);
11
    return appendResult();
12
}

阅读源码时，应该不断问：

1
输入是什么？
2
输出是什么？
3
这个对象持有什么状态？
4
线程边界在哪里？
5
异常由谁转换为协议错误？
6
什么时候只完成本地 Append？
7
什么时候等待副本 ACK？

最后一个问题涉及延迟请求和可靠性，将在第五篇再展开。

6.1 Consumer 请求的不是“一条消息”#

Consumer 可能发送：

1
TopicPartition = order-events-3
2
Fetch Offset   = 36891
3
Max Bytes      = 1 MiB
4
Isolation      = read_uncommitted / read_committed

这里的 Offset 表达：

从这个位置开始读取。

Broker 通常返回满足协议和字节限制的一批连续 RecordBatch：

1
36891
2
36892
3
36893
4
...

不是像数据库主键查询一样，只返回 Offset=36891 对应的一条 Record。

Kafka Consumer 配置文档明确说明 Consumer 以 Batch 形式 Fetch Record；即使第一个非空 Partition 的首个 Batch 超过配置限制，Broker 也可能返回它，以保证 Consumer 能继续前进。5

6.2 Broker Fetch 主链#

可以先建立以下主路径：

1
FetchRequest
2
    ↓
3
KafkaApis
4
    ↓
5
ReplicaManager.fetchMessages
6
    ↓
7
Partition.readRecords
8
    ↓
9
UnifiedLog.read
10
    ↓
11
Locate Segment
12
    ↓
13
OffsetIndex Lookup
14
    ↓
15
LogSegment.read
16
    ↓
17
FileRecords
18
    ↓
19
FetchResponse

这一链路和写入链形成对称：

6.3 读取前需要确定可见边界#

并不是 Log 中所有已存在字节都一定能对当前 Consumer 可见。

Broker 还需要根据请求类型和隔离级别确定读取上界，例如后续文章会区分：

1
Log End Offset
2
High Watermark
3
Last Stable Offset

本篇只保留抽象：

1
requestedOffset
2
      ↓
3
validate range
4
      ↓
5
determine max readable offset
6
      ↓
7
read within visible boundary

如果当前请求 Offset 不在 Broker 保留的范围内，可能产生 OFFSET_OUT_OF_RANGE。13

不要在本篇提前展开 HW、LSO 与事务可见性的精确计算，它们属于第四、五篇。

6.4 Segment 与 Index 再次参与#

UnifiedLog.read 收到目标 Offset 后，复用第四章的定位过程：

1
Target Offset
2
      ↓
3
Segment Floor Lookup
4
      ↓
5
Relative Offset
6
      ↓
7
OffsetIndex Lookup
8
      ↓
9
Physical Position
10
      ↓
11
LogSegment / FileRecords Read

读取返回的通常是从目标位置开始、受字节上限和可见边界约束的一段连续 Records。

因此，索引层并不负责“反序列化业务对象”。它只负责找到二进制 RecordBatch 在文件中的范围。

6.5 热数据 Tail Read#

Kafka 最典型的实时流场景是：

1
Producer 正在写 Partition 尾部
2
Consumer 也正在追赶 Partition 尾部

写入刚刚进入 Page Cache 的数据页，可能立即被 Consumer Fetch 复用：

1
Producer Append
2
      ↓
3
OS Page Cache
4
      ↓
5
Consumer Tail Fetch

这时不需要每次重新从物理介质读取相同数据。

Kafka 4.3 Tiered Storage 文档明确描述：流式消费大多属于 Tail Read，利用 OS Page Cache 提供数据；较旧数据通常在回填或故障恢复时才更频繁地从磁盘读取。7

6.6 冷数据历史读取#

如果 Consumer：

• 长时间离线后重新追赶；
• 执行大规模历史 Replay；
• 进行数据回填；
• 读取已经被 Page Cache 淘汰的 Segment；

则可能发生：

1
Fetch
2
  ↓
3
Page Cache Miss
4
  ↓
5
Storage Read / Page Fault
6
  ↓
7
Load Pages into Page Cache
8
  ↓
9
Return Data

读取延迟会更明显地受：

• 磁盘介质；
• I/O 队列；
• Segment 位置；
• 其他工作负载；
• 远程 Tier；
• 网络带宽；
• 文件系统状态；

影响。

所以：

Kafka 快不意味着读取任意历史 Offset 都等价于纯内存读取。

必须区分：

1
Hot Tail Read
2
Cold Historical Read
3
Remote Tier Read

6.7 传统用户态数据复制路径#

一个传统的读取再发送模型可能是：

1
Storage Device
2
      ↓
3
Kernel Page Cache
4
      ↓ copy
5
Application User Buffer / JVM Buffer
6
      ↓ copy
7
Kernel Socket Buffer
8
      ↓
9
NIC

其中应用程序把文件数据读入自己的用户态 Buffer，然后再写入 Socket。

代价包括：

• 数据进入用户态再返回内核态；
• 大型 Buffer 管理；
• JVM Heap 或 Direct Buffer 压力；
• 更多 CPU Copy；
• 更多上下文切换和系统调用开销。

6.8 高效文件传输路径#

更高效的目标是：

1
File / Page Cache
2
       ↓
3
Kernel Network Path
4
       ↓
5
NIC

应用程序主要描述：

1
哪个文件
2
从什么 Position
3
传输多少字节

而尽量避免把完整 Batch 再复制到大型 JVM Heap Buffer 中转。

Kafka 设计文档将 Page Cache 与 Zero-Copy 优化联系起来：数据可以在 Page Cache 中复用，并在消费时减少应用层复制，使消费吞吐更接近网络上限。2

6.9 “Zero Copy”不是“物理世界零复制”#

这是 Kafka 面试和技术文章中最容易被过度简化的概念。

更准确的表述是：

Zero Copy 优化的核心是减少不必要的用户态数据复制和 JVM 中转。

实际硬件与内核路径仍可能发生：

• Storage Device 与内存之间的 DMA；
• 内核页面与 NIC 队列之间的数据描述或搬运；
• TLS 加密 Buffer 处理；
• 网络设备内部复制；
• 特定操作系统和文件系统的实现差异。

所以不要写：

1
Kafka 数据从磁盘直接飞到网卡，全程一个字节都不复制。

更好的回答是：

1
Kafka 借助操作系统的文件传输能力，
2
尽量绕过“文件 → JVM 用户态大 Buffer → Socket”的重复中转。

6.10 哪些情况会破坏理想路径#

Kafka 的高效读取路径有明确边界：

1
Kafka 永远零拷贝，所以一定快。

6.11 Broker 读取链伪代码#

1
Records read(TopicPartition tp, long offset, int maxBytes) {
2
    Partition partition = replicaManager.requirePartition(tp);
3
    return partition.readRecords(offset, maxBytes);
4
}

存储层：

1
Records read(long offset, int maxBytes) {
2
    long maxReadableOffset = determineVisibleBoundary();
3
    ensureOffsetInRange(offset, maxReadableOffset);
4

5
    LogSegment segment = segments.floorSegment(offset);
6
    OffsetPosition start = segment.offsetIndex().lookup(offset);
7

8
    return segment.read(
9
        offset,
10
        start.position(),
11
        maxBytes,
12
        maxReadableOffset
13
    );
14
}

仍然是概念伪代码，目的在于保留核心决策顺序。

阅读源码时应追问：

1
Segment 在哪里被选择？
2
读取上界在哪里确定？
3
返回的是 Records 还是业务对象？
4
什么时候只返回部分 Batch？
5
什么时候触发延迟 Fetch？
6
数据如何进入 Network Send？

7.1 Log 模型把主要写入变成 Tail Append#

关系型数据库的某些更新需要：

1
查找数据页
2
修改页中记录
3
维护多个索引
4
处理随机位置更新

Kafka 的 Partition Log 主要做：

1
确定当前 Active Segment
2
        ↓
3
向文件尾部追加 RecordBatch

所以，顺序访问首先来自数据模型，而不是一句独立调优技巧。

1
Append-only Log
2
+
3
Active Segment
4
=
5
集中尾部写入

7.2 Batch 贯穿整个 Data Path#

1
Business Records
2
       ↓
3
RecordBatch
4
       ↓
5
ProduceRequest
6
       ↓
7
Broker Append
8
       ↓
9
Segment File
10
       ↓
11
FetchResponse
12
       ↓
13
Consumer

批处理可以摊薄：

1
协议头
2
请求次数
3
系统调用
4
校验边界
5
压缩上下文
6
磁盘追加操作
7
网络发送调度

Kafka 的性能优势不是“Broker 收到单条消息后再偷偷拼 Batch”，而是客户端、协议和存储格式从设计上共享批处理边界。1

7.3 压缩后的 Batch 尽量保持压缩#

理想路径：

1
Producer Compression
2
        ↓
3
Network
4
        ↓
5
Broker Validation
6
        ↓
7
Compressed Log Storage
8
        ↓
9
Network
10
        ↓
11
Consumer Decompression

避免每一层都：

1
解压 → 重建 → 再压缩

这同时减少：

• 网络流量；
• 磁盘空间；
• Broker CPU 重复压缩；
• 用户态数据重建。

但要保留边界：Broker 仍需要进行必要校验，特殊兼容和转换场景可能改变路径。

7.4 Page Cache 让写后即读非常高效#

1
Producer Append
2
      ↓
3
Page Cache
4
      ↓
5
Consumer Tail Read

实时流场景天然具有较好的时间局部性：刚刚被写入的数据很快被下游读取。

Kafka 不需要额外复制一份完整消息缓存，就能让 OS 缓存热数据。

7.5 稀疏索引避免“索引比数据还重”#

Kafka 不为每条 Record 维护复杂索引树，而是：

1
Segment Base Offset
2
+
3
Sparse OffsetIndex
4
+
5
Short Sequential Scan

这使索引文件相对紧凑，查询仍然能迅速接近目标位置。

7.6 减少用户态数据复制#

读取路径尽量复用：

1
File / Page Cache → Kernel Network Path

而不是：

1
File → JVM 大 Buffer → Socket

这降低 CPU 和内存中转成本。

7.7 Partition 提供水平并行#

单 Partition 保持局部顺序：

1
P0: ordered append and fetch

多个 Partition 可以分布到多个 Broker：

1
P0 → Broker 1
2
P1 → Broker 2
3
P2 → Broker 3
4
P3 → Broker 4

形成：

• 并行写入；
• 并行读取；
• 存储容量扩展；
• 网络吞吐扩展。

Partition 数量和分布不是越多越好，容量设计与治理放在第七篇。

7.8 一个概念性能模型#

可以用以下关系帮助记忆：

1
Kafka Throughput
2
≈
3
Partition Parallelism
4
× Batch Efficiency
5
× Sequential Access Efficiency
6
× Cache Hit Efficiency
7
× Network Transfer Efficiency

它不是可以直接代入生产容量的数学公式，只表达：

Kafka 吞吐取决于多层设计共同工作，而不是单点优化。

7.9 正确回答“Kafka 为什么快”#

不合格回答：

1
因为 Kafka 顺序写、Page Cache、零拷贝。

更完整的回答：

Kafka 先用 Append-only Partition Log 把主写路径收束为 Active Segment 尾部追加，再用 RecordBatch 让压缩、网络协议、CRC、磁盘写入和 Fetch 共享批处理边界；Segment 与稀疏索引在可管理文件大小和查询效率之间平衡；消息数据主要复用 OS Page Cache，并在读取时尽量减少 JVM 用户态中转；最后通过多个 Partition 将存储和吞吐水平分布到多个 Broker。

可以进一步收束为：

1
Log Data Model
2
+
3
Segmented Storage
4
+
5
Batch-oriented Format
6
+
7
Sparse Index
8
+
9
OS Page Cache
10
+
11
Efficient File Transfer
12
+
13
Partition Parallelism

8.1 为什么需要 Roll#

Active Segment 不能无限增长。

达到一定条件后：

1
Active Segment
2
      ↓ Roll
3
Closed Segment
4

5
Current Log End Offset
6
      ↓
7
New Segment Base Offset
8
      ↓
9
New Active Segment

8.2 Roll 条件#

Roll 判断可从以下维度理解：

1
segment.bytes

1
segment.ms
2
segment.jitter.ms

8.3 Roll 后发生什么#

概念链：

1
停止向旧 Segment 追加
2
        ↓
3
旧 Segment 成为 Closed
4
        ↓
5
以当前 Log End Offset 创建新文件组
6
        ↓
7
新 Segment 成为 Active
8
        ↓
9
后续 RecordBatch 继续追加

例如：

1
Old active baseOffset = 32000
2
Current LEO           = 64000
3

4
New files:
5
00000000000000640000.log
6
00000000000000640000.index
7
00000000000000640000.timeindex
8
00000000000000640000.txnindex

8.4 Retention Delete 以 Segment 为主要边界#

Kafka Log 保留不是：

1
Consumer ACK 一条，就立刻删除一条。

而是：

1
Closed Segments
2
      ↓
3
达到 retention 时间或大小条件
4
      ↓
5
标记并删除整个 Segment 文件集合

cleanup.policy=delete 是默认清理策略，可按照保留时间或总大小清理旧 Segment。3

这种设计再次体现 Queue 与 Log 的差异：

1
消费进度
2
≠
3
数据保留生命周期

Consumer 已经读过的数据，仍可在 Retention 窗口内供其他 Consumer 或 Replay 使用。

8.5 为什么 Active Segment 通常不能直接按 Retention 删除#

Active Segment 仍在持续追加，其文件和索引边界尚未稳定。

如果直接删除其中“过期的前半部分”，又会回到修改大文件内部的问题。

因此 Kafka 通过 Roll 产生 Closed Segment，再以 Segment 为单位进行清理。

这也说明：

segment.ms 不仅影响文件大小，还会间接影响低流量 Topic 旧数据形成可清理 Segment 的及时性。

8.6 Log Compaction 不是按时间删除#

假设：

1
Offset 0: Key=A Value=1
2
Offset 1: Key=B Value=3
3
Offset 2: Key=A Value=2
4
Offset 3: Key=A Value=5

Compaction 目标是保留每个 Key 的最新值：

1
Key=B Value=3
2
Key=A Value=5

cleanup.policy=compact 用于保留每个 Key 的最后已知值，也可以和 delete 组合。3

必须避免以下错误：

1
Compaction = 删除超过 N 天的数据

错误。那是 Retention Delete 的主要语义。

1
Compaction 后 Offset 会重新连续编号

错误。Offset 作为 Log 中的位置标识不会因为中间 Record 被压缩清理而重新编号。

可能出现：

1
Offset 100 存在
2
Offset 101 已被压缩移除
3
Offset 102 存在

Consumer 从 101 开始 Fetch 时，可以继续前进到后续有效 Batch，而不是要求所有 Offset 对应一条仍存在的业务 Record。

8.7 Tiered Storage#

Tiered Storage 将数据分成：

1
Local Tier
2
+
3
Remote Tier

当前尾部和热 Segment 保留在 Broker 本地；完成的冷 Segment 可以迁移到远程存储。Kafka 4.3 官方文档将本地层描述为现有 Broker Local Disk，将远程层描述为 HDFS、S3 等外部存储实现所承载的 Completed Log Segments。7

本篇只需要建立：

1
Segment 也是远程迁移的重要边界

RemoteLogManager、远程 Metadata Topic、Follower 从远程层恢复和生产参数治理将在第七篇生产架构中再讨论。

9.1 第一层：消息格式#

优先理解：

1
Records
2
RecordBatch
3
DefaultRecordBatch
4
Record
5
DefaultRecord
6
MemoryRecords
7
FileRecords

重点问题：

1. Batch Header 如何解析？
2. baseOffset 和 offsetDelta 在哪里组合？
3. Compression Type 存在哪里？
4. CRC 覆盖哪些区域？
5. FileRecords 如何表达文件中的 Records 范围？
6. Batch 如何写入或传输到 NIO Channel？

Kafka 4.3 官方 Message Format 文档应当和源码一起阅读，而不是只看类名猜格式。1

9.2 第二层：索引#

阅读：

1
OffsetIndex
2
TimeIndex
3
TransactionIndex
4
AbstractIndex

重点问题：

1. 为什么 OffsetIndex 保存 Relative Offset？
2. lookup() 返回的是最终 Record 还是邻近 Position？
3. 索引如何做二分查找？
4. Index File 如何扩展、截断和重新映射？
5. TimeIndex 为什么保存 Timestamp 到 Relative Offset？
6. Index 损坏后如何依赖 .log 重建？

9.3 第三层：Segment#

阅读：

1
LogSegment

重点问题：

1. 一个 Segment 持有哪些 File 与 Index？
2. append 如何同时推进数据和索引？
3. read 如何使用开始 Position？
4. recover 如何扫描 RecordBatch？
5. shouldRoll 的条件来自哪里？
6. Segment 关闭、截断和删除如何协调文件？

9.4 第四层：逻辑 Log#

阅读：

1
UnifiedLog
2
LocalLog
3
LogSegments
4
LogManager

重点问题：

1. Partition 的 Segment 集合如何管理？
2. floorSegment(offset) 如何实现？
3. Active Segment 如何取得？
4. appendAsLeader 的 Offset 分配和验证顺序是什么？
5. read 如何确定可见上界？
6. Roll 如何创建新 Segment？
7. Log End Offset、恢复点和快照如何维护？

当前 4.x 的 UnifiedLog、LocalLog 和 LogSegment 已位于存储模块，阅读旧教程时要警惕类所在模块和实现语言已经发生变化。10

9.5 第五层：Partition 与 ReplicaManager#

阅读：

1
Partition
2
ReplicaManager

重点问题：

1. TopicPartition 如何映射到本地 Partition？
2. 如何判断当前 Replica 是 Leader 还是 Follower？
3. Produce 如何进入 appendRecordsToLeader？
4. Fetch 如何进入本地 Log？
5. 哪些请求要等待副本条件满足？
6. Delayed Produce / Delayed Fetch 如何与主链配合？

第五和第六个问题牵涉可靠性与 Purgatory，在第五篇展开。

9.6 第六层：Broker 请求入口#

阅读：

1
SocketServer
2
KafkaRequestHandler
3
KafkaApis
4
RequestChannel

重点问题：

1. Socket 数据如何变成 Request？
2. Processor 与 Handler Thread 如何分工？
3. Produce、Fetch 在哪个 API Handler 分发？
4. 错误如何转成协议 Response？
5. Records 如何进入 Network Send？

9.7 推荐顺序#

1
Message Format 文档
2
        ↓
3
DefaultRecordBatch / FileRecords
4
        ↓
5
OffsetIndex / TimeIndex
6
        ↓
7
LogSegment
8
        ↓
9
UnifiedLog / LocalLog
10
        ↓
11
Partition
12
        ↓
13
ReplicaManager
14
        ↓
15
KafkaApis
16
        ↓
17
SocketServer

先从底层数据结构向调用者反推，比从网络入口一路陷入所有分支更容易形成稳定模型。

9.8 源码阅读规范#

建议每条链都使用固定模板记录：

1
入口方法
2
    ↓
3
输入对象
4
    ↓
5
关键状态
6
    ↓
7
线程边界
8
    ↓
9
核心数据结构变化
10
    ↓
11
输出对象
12
    ↓
13
错误边界

例如 OffsetIndex.lookup(targetOffset)：

1
输入：Absolute / Relative Offset?
2
状态：Base Offset、Mapped Index File
3
动作：Binary Search
4
输出：OffsetPosition
5
边界：结果是否精确等于目标？
6
下游：LogSegment 从该 Position 顺序扫描

这种阅读方式比复制源码注释更接近工程专家需要的能力。

10.1 实验目录#

1
kafka-storage-lab/
2
├── docker-compose.yml
3
└── data/

10.2 Docker Compose#

1
services:
2
  kafka:
3
    image: apache/kafka:4.3.0
4
    container_name: kafka-ch02
5
    hostname: kafka
6
    ports:
7
      - "9092:9092"
8
    environment:
9
      KAFKA_NODE_ID: 1
10
      KAFKA_PROCESS_ROLES: broker,controller
11
      KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
12
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
13
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
14
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
15
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
16
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
17
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
18
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
19
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
20
      KAFKA_LOG_DIRS: /var/lib/kafka/data
21
    volumes:
22
      - ./data:/var/lib/kafka/data

启动：

1
docker compose up -d
2

3
docker logs -f kafka-ch02

看到 Broker 启动完成后，再执行后续命令。

不同 Docker Desktop、文件权限和镜像小版本可能需要调整挂载目录权限。若本地挂载失败，可以先改用 Docker Named Volume，确认 Kafka 正常运行后再观察容器内部文件。

10.3 创建容易发生 Roll 的 Topic#

1
docker exec kafka-ch02 \
2
  /opt/kafka/bin/kafka-topics.sh \
3
  --bootstrap-server localhost:9092 \
4
  --create \
5
  --topic order-events \
6
  --partitions 1 \
7
  --replication-factor 1 \
8
  --config segment.bytes=1048576 \
9
  --config index.interval.bytes=4096 \
10
  --config retention.ms=86400000

这里故意将：

1
segment.bytes = 1 MiB

设得很小，以便少量测试数据就生成多个 Segment。

验证：

1
docker exec kafka-ch02 \
2
  /opt/kafka/bin/kafka-topics.sh \
3
  --bootstrap-server localhost:9092 \
4
  --describe \
5
  --topic order-events

查看 Topic 配置：

1
docker exec kafka-ch02 \
2
  /opt/kafka/bin/kafka-configs.sh \
3
  --bootstrap-server localhost:9092 \
4
  --entity-type topics \
5
  --entity-name order-events \
6
  --describe

10.4 批量发送测试数据#

Linux / macOS / WSL：

1
python3 - <<'PY' | docker exec -i kafka-ch02 \
2
  /opt/kafka/bin/kafka-console-producer.sh \
3
  --bootstrap-server localhost:9092 \
4
  --topic order-events
5
import json
6
for i in range(30000):
7
    print(json.dumps({
8
        "eventId": i,
9
        "orderId": f"ORD-{i:08d}",
10
        "eventType": "OrderCreated",
11
        "payload": "x" * 180
12
    }))
13
PY

如果 30,000 条仍不足以产生多个 Segment，可继续增加消息数量或 Payload 大小。

10.5 观察 Partition 目录#

1
docker exec kafka-ch02 sh -lc \
2
  'ls -lh /var/lib/kafka/data/order-events-0'

预期看到多组：

1
*.log
2
*.index
3
*.timeindex

并观察：

1. 文件名前缀是否递增；
2. .log 是否接近配置的 1 MiB 后生成新文件；
3. 最后一个 Active Segment 是否可能明显小于前面 Segment；
4. .index 是否远小于 .log；
5. 多个文件是否共享相同 Base Offset 前缀。

如果目录名称或数据路径与示例不同，先执行：

1
docker exec kafka-ch02 \
2
  /opt/kafka/bin/kafka-log-dirs.sh \
3
  --bootstrap-server localhost:9092 \
4
  --describe \
5
  --topic-list order-events

再根据实际路径检查。

10.6 使用 kafka-dump-log.sh 查看 RecordBatch#

先找到某个 .log 文件：

1
docker exec kafka-ch02 sh -lc \
2
  'find /var/lib/kafka/data/order-events-0 -name "*.log" | sort | head -1'

假设输出：

1
/var/lib/kafka/data/order-events-0/00000000000000000000.log

执行：

1
docker exec kafka-ch02 \
2
  /opt/kafka/bin/kafka-dump-log.sh \
3
  --files /var/lib/kafka/data/order-events-0/00000000000000000000.log \
4
  --print-data-log