3、版本号与兼容性策略：Loki语义化版本规则、API版本化策略、向后兼容性承诺与例外
在集群升级过程中，版本漂移是导致查询接口异常的首要原因。理解 Loki 的版本号规则与兼容性策略，是校准漂移、保障查询连续性的基础。本章从语义化版本、API 版本化、向后兼容承诺三个维度展开，帮助 SRE 在升级前准确评估风险。
3.1 Loki 语义化版本规则
Loki 严格遵循 语义化版本 2.0.0（SemVer）规范，版本号格式为 MAJOR.MINOR.PATCH。每个段位的变更对应不同的兼容性影响：
| 段位 | 示例 | 变更含义 | 对查询接口的影响 |
|---|---|---|---|
| MAJOR | 2.x.x → 3.x.x | 不兼容的 API 或行为变更 | 查询接口可能断裂，需适配 |
| MINOR | 2.8.x → 2.9.x | 向下兼容的功能新增 | 查询接口保持兼容，新特性可选 |
| PATCH | 2.8.1 → 2.8.2 | 向下兼容的缺陷修复 | 查询接口无感知，仅修复行为 |
SRE 实践提示： 在升级规划中，
MAJOR 版本升级必须纳入完整的回归测试周期；MINOR 版本升级建议执行查询接口冒烟测试；PATCH 版本升级可走快速通道，但仍需验证关键查询路径。
Loki 在 MAJOR 版本发布前，通常会在 MINOR 版本中提前标记废弃（Deprecated）特性，并给出至少一个 MINOR 版本的过渡期。例如，Loki 2.9 中废弃了某个查询参数，该参数在 Loki 3.0 中才会被移除。
3.2 API 版本化策略
Loki 的 HTTP API 采用 路径前缀 + 版本号 的方式进行版本化管理。当前主流版本路径如下：
/loki/api/v1— 稳定版 API，所有生产环境查询接口均基于此路径。/loki/api/v2— 实验性 API，用于引入新查询能力，可能在后续版本中调整或合并到 v1。
API 版本与 Loki 发行版本并非一一对应。一个 Loki 发行版可能同时支持多个 API 版本。例如，Loki 2.9 同时提供 v1 和 v2 接口，但 v2 接口默认处于“实验性”状态，需通过配置显式启用。
关键原则： 生产环境始终使用
/loki/api/v1 路径。实验性 API 不提供向后兼容保证，升级后可能无预警变更。
以下 SVG 展示了 Loki API 版本与发行版本之间的映射关系：
3.3 向后兼容性承诺与例外
Loki 项目对 /loki/api/v1 接口做出明确的向后兼容承诺，但存在以下例外场景，SRE 需重点关注：
3.3.1 兼容性承诺范围
- 查询路径与参数：
GET /loki/api/v1/query_range、GET /loki/api/v1/query、GET /loki/api/v1/labels、GET /loki/api/v1/label/{name}/values、GET /loki/api/v1/series等核心查询接口的路径、请求参数、响应 JSON 结构保持向后兼容。 - LogQL 语法： 已发布的 LogQL 关键字、函数、运算符在
MINOR版本内保持兼容，新增关键字不会破坏已有查询。 - 响应状态码： 成功返回 200，客户端错误返回 4xx，服务端错误返回 5xx 的语义不变。
3.3.2 例外与免责场景
| 例外类型 | 具体场景 | SRE 应对措施 |
|---|---|---|
| 安全修复 | 因安全漏洞需要修改响应内容或行为 | 关注安全公告，提前规划适配窗口 |
| 实验性 API | /loki/api/v2 及未标记为稳定的端点 |
生产环境避免依赖实验性 API |
| 内部行为变更 | 查询执行引擎优化导致结果排序、精度变化 | 在测试环境对比查询结果差异 |
| 废弃特性移除 | 已在之前版本标记废弃的参数或端点被移除 | 升级前扫描日志中的废弃警告 |
| 配置默认值变更 | 影响查询行为的配置项默认值在 MAJOR 版本调整 |
显式配置所有关键参数，不依赖默认值 |
升级前必做检查： 在目标版本的
CHANGELOG.md 中搜索 BREAKING CHANGE、deprecated、removed 关键词。同时，在测试环境执行完整的查询回归用例集，覆盖所有生产使用的查询路径和参数组合。
3.4 版本漂移校准策略总结
基于上述版本规则与兼容性策略，SRE 在集群升级后校准查询接口差异时，应遵循以下步骤：
- 识别版本跨度： 确定源版本与目标版本的
MAJOR、MINOR、PATCH差异。 - 审查 CHANGELOG： 提取所有与查询接口相关的变更条目，标记废弃与移除项。
- 锁定 API 版本： 确认客户端请求路径始终使用
/loki/api/v1。 - 执行回归测试： 在预发环境运行查询用例集，对比响应结构与数据一致性。
- 监控废弃警告： 在 Loki 日志中搜索
deprecated关键字，提前适配即将移除的特性。
以下 SVG 总结了版本漂移校准的决策流程：