2. Logging Platform 架构概览：核心组件、数据流路径与版本依赖关系图
在深入版本漂移自动校准之前，必须对 Logging Platform 的整体架构建立清晰的认知。一个生产级的日志平台通常由四个核心组件构成：Agent、Collector、Storage 和 Indexer。它们之间的版本依赖关系是导致漂移的根本原因，也是校准流程的管控对象。
2.1 核心组件职责与版本敏感点
| 组件 | 主要职责 | 版本敏感点 |
|---|---|---|
| Agent | 部署在业务节点上，负责采集日志文件、容器 stdout/stderr，并执行轻量级解析与转发。 | Agent 版本必须与 Collector 的接收协议（如 gRPC、HTTP）兼容；旧版 Agent 可能不支持新版 Collector 的压缩或认证方式。 |
| Collector | 作为中间层，接收来自大量 Agent 的日志流，进行聚合、缓冲、去重和初步路由。 | Collector 的配置格式（如 YAML schema）随版本变化；下游 Storage 的写入 API 版本变更会导致 Collector 写入失败。 |
| Storage | 持久化存储原始日志数据，通常基于分布式文件系统或对象存储（如 HDFS、S3 兼容存储）。 | Storage 的索引格式、数据块编码方式在 major 版本升级时可能不兼容，导致旧数据无法被 Indexer 读取。 |
| Indexer | 对 Storage 中的日志建立倒排索引，提供全文检索、聚合查询能力。 | Indexer 的索引 schema 与 Storage 的数据格式强绑定；Indexer 版本落后或超前都会导致查询结果异常或索引重建失败。 |
版本漂移高发区： 实际故障案例中，超过 70% 的版本漂移问题发生在 Collector → Storage 和 Storage → Indexer 这两个接口边界上。Agent 与 Collector 之间通常有较好的向前兼容性，但 Storage 与 Indexer 的耦合度最高。
2.2 数据流路径与版本约束点
日志数据从产生到可查询，经历一条完整的流水线。每个环节的版本约束点决定了数据能否顺利通过。
- 采集阶段： Agent 读取日志文件 → 序列化为 Protobuf/JSON → 发送至 Collector。版本约束：序列化协议版本必须一致。
- 聚合阶段： Collector 接收数据 → 写入本地缓冲（如 Kafka/RingBuffer）→ 批量转发至 Storage。版本约束：缓冲区的数据格式版本、转发 API 版本。
- 存储阶段： Storage 写入数据块 → 更新元数据 → 返回确认。版本约束：数据块编码版本、元数据 schema 版本。
- 索引阶段： Indexer 读取 Storage 中的数据块 → 构建倒排索引 → 写入索引文件。版本约束：索引文件格式版本、分词器版本。
关键观察： 数据流路径上的每个箭头都代表一个 版本契约。当任意两个相邻组件的版本不满足契约时，数据流就会中断或产生静默错误。版本漂移自动校准的核心目标就是检测并修复这些契约断裂点。
2.3 版本依赖关系图
下图展示了 Logging Platform 各组件的版本依赖关系。箭头方向表示“依赖方向”：A → B 表示 A 的版本必须与 B 的版本兼容。
2.4 版本依赖矩阵
为了更精确地描述版本兼容性，我们使用版本依赖矩阵来定义组件之间的兼容范围。该矩阵是自动校准流程的决策依据。
| 上游组件 | 下游组件 | 兼容版本范围 | 不兼容后果 |
|---|---|---|---|
| Agent v2.x | Collector v3.x | Agent v2.1+ ↔ Collector v3.0+ | Agent v2.0 与 Collector v3.0 的 gRPC 压缩算法不兼容，导致连接断开 |
| Agent v3.x | Collector v4.x | Agent v3.0+ ↔ Collector v4.0+ | Agent v3.0 的认证 格式在 Collector v4.0 中被废弃，导致鉴权失败 |
| Collector v3.x | Storage v5.x | Collector v3.2+ ↔ Storage v5.1+ | Collector v3.1 使用旧版写入 API，Storage v5.0 已移除该 API，写入返回 404 |
| Collector v4.x | Storage v6.x | Collector v4.0+ ↔ Storage v6.0+ | Collector v4.0 的批量写入请求体格式与 Storage v6.0 不匹配，导致反序列化失败 |
| Storage v5.x | Indexer v4.x | Storage v5.0+ ↔ Indexer v4.1+ | Storage v5.0 的数据块使用旧版编码，Indexer v4.0 无法解码，索引构建失败 |
| Storage v6.x | Indexer v5.x | Storage v6.0+ ↔ Indexer v5.0+ | Storage v6.0 引入新的元数据字段，Indexer v5.0 忽略该字段，导致索引不完整 |
版本漂移的隐蔽性： 并非所有版本不兼容都会立即导致错误。例如，Storage v6.0 引入的新元数据字段被 Indexer v5.0 忽略时，日志数据仍然可以写入和查询，但部分字段的索引会丢失，导致搜索召回率下降。这种 静默漂移 比显式错误更难发现，也是自动校准流程需要重点检测的场景。
2.5 组件间接口契约定义
每个组件间的接口契约由三部分组成，版本漂移检测就是对比这些契约的实际值与期望值：
- 协议版本： 如 gRPC service 版本号、HTTP API 版本路径（/v1/logs vs /v2/logs）。
- 数据格式版本： 如 Protobuf schema 版本、JSON 字段集合、Avro schema ID。
- 配置版本： 如 Collector 的 pipeline 配置版本、Storage 的存储策略版本。