1. 课程导论：版本漂移的概念、Loki 存储格式变更的背景、为什么需要数据迁移
1.1 版本漂移：日志平台的“慢性病”
在大型分布式日志平台中，版本漂移是指集群内不同组件或节点之间，因版本不一致而导致的行为差异、协议不兼容或数据格式错乱的现象。对于基于 Loki 构建的日志系统，版本漂移通常表现为以下几种形态：
- Ingester 与 Querier 版本不一致：写入端使用新格式，查询端仍按旧格式解析，导致查询结果缺失或报错。
- 存储层（对象存储）格式变更：Loki 升级后，Chunk 元数据、索引结构或压缩算法发生变化，旧版本组件无法读取新数据。
- 配置与代码逻辑漂移：同一集群中部分节点未更新配置，导致数据路由、分片策略或租户隔离规则出现偏差。
核心结论：版本漂移不是“要不要处理”的问题，而是“何时爆发”的问题。在 Loki 存储格式发生结构性变更时，数据迁移是唯一能消除漂移、恢复一致性的手段。
1.2 Loki 存储格式变更的背景
Loki 自 2.0 版本以来，存储引擎经历了多次重大迭代。每一次格式变更都直接影响到 Chunk 的编码方式、索引的构建策略以及元数据的持久化结构。以下是近几个大版本中关键的存储格式变更：
| Loki 版本 | 存储格式变更点 | 影响范围 |
|---|---|---|
| 2.0 → 2.1 | 引入 v3 Chunk 格式，支持更高效的压缩与乱序写入 | Chunk 编码、索引结构 |
| 2.4 → 2.5 | TSDB 索引替代 BoltDB，元数据存储路径变更 | 索引查询、数据目录结构 |
| 2.7 → 2.8 | Schema 版本升级，新增 v12 和 v13 模式 |
数据写入与查询兼容性 |
| 2.9 → 2.10 | Chunk 元数据增加 checksum 字段，旧版本无法解析 |
数据完整性校验、回滚能力 |
这些变更并非“向后兼容”的简单补丁，而是涉及底层数据结构的重构。例如，从 BoltDB 迁移到 TSDB 索引时，旧索引文件无法被新查询器读取；而新写入的 Chunk 如果包含旧版本不认识的元数据字段，则会导致解析失败。
⚠ 常见误区：很多团队认为“升级后不报错就代表兼容”。实际上，Loki 的存储格式变更往往是写入时兼容、读取时崩溃。数据在对象存储中静默存在，直到查询请求命中旧格式数据时才会暴露问题。
1.3 为什么需要数据迁移？
当 Loki 存储格式发生变更后，数据迁移不是可选项，而是恢复集群一致性的必要步骤。具体原因可归纳为以下三点：
- 消除读写路径的版本断层
新版本 Ingester 写入的数据，旧版本 Querier 无法正确解析。迁移可以将旧格式数据转换为新格式，使整个集群的读写路径统一。 - 释放存储与计算资源
旧格式数据往往占用更多存储空间，且查询效率低。迁移过程中可以重新压缩、去重，并应用新的索引策略，降低存储成本。 - 保障回滚与容灾能力
如果迁移后出现问题，保留一份格式转换后的数据副本，可以快速回退到旧版本集群，而不丢失历史日志。
1.4 数据迁移的核心挑战
Loki 的数据迁移并非简单的“复制粘贴”。由于日志数据具有海量、高吞吐、时间敏感的特性，迁移过程面临以下挑战：
- 数据量级巨大：单集群可能存储 PB 级日志，全量迁移耗时数天甚至数周。
- 格式转换的原子性：Chunk 文件、索引文件、元数据文件必须保持事务一致性，否则会导致数据损坏。
- 在线迁移 vs 离线迁移：在线迁移要求集群持续提供服务，对迁移工具的性能和容错能力要求极高。
- 回滚与验证：迁移完成后，必须有一套机制验证数据完整性，并支持快速回滚。
💡 课程预告：在后续章节中，我们将深入讲解 Loki 存储格式的底层结构、迁移工具链的搭建、以及生产环境中的灰度迁移策略。本课程将提供可直接复用的迁移脚本与配置模板。