升级 Prometheus 后告警规则语法不兼容怎么迁移适配

升级 Prometheus 后遇到告警规则语法报错，最稳妥的办法是先用同版本的 promtool 本地校验规则文件，再对照官方变更日志调整不兼容的 PromQL 表达式，最后通过热加载生效。

先说结论：不要直接在生产环境修改，先用工具本地校验语法，确认无误后再替换并热加载。

适合：大版本升级后出现 rule_loader 报错或告警消失的场景
先准备：备份旧规则文件，下载与新版本一致的 promtool 工具
验收：观察 Prometheus 日志无 error，且/api/v1/rules 接口返回正常

命令速用版

# 检查规则文件语法（promtool 版本需与 Prometheus 服务端一致）
promtool check rules /path/to/rules.yml

# 检查主配置文件语法
promtool check config /path/to/prometheus.yml

# 触发配置热加载（方案 A：systemd 管理的服务）
systemctl reload prometheus

# 触发配置热加载（方案 B：HTTP API，需启动参数包含 `--web`.enable-lifecycle）
curl -X POST http://localhost:9090/-/reload

为什么会这样

Prometheus 在大版本迭代时（例如从 2.x 升级到 3.x），为了维护代码库健康和性能，会移除已标记为 deprecated 的 PromQL 函数或配置项。此外，某些特性开关（feature flags）在新版本中可能默认开启或关闭，导致原有表达式行为变化。官方不会无限兼容旧语法，因此升级后规则失效是预期内的维护成本。

常见语法变更案例

以下是升级后高频出现的不兼容情况，排查时可优先对照：

变更类型	旧版本表现	新版本表现	修复建议
废弃函数	支持某些已标记 deprecated 的函数	直接报错 unknown function	查阅 changelog 替换为新函数
特性开关	需手动开启 feature flag	默认开启或强制关闭	调整启动参数或修改 PromQL 写法
标签匹配	正则匹配容错率高	严格遵循 RE2 语法	检查正则表达式是否符合 RE2 规范
时间单位	容忍非标准单位写法	严格限制为 s, m, h, d, w, y	修正范围向量选择器中的时间单位

分步处理

备份现有配置

在操作前，将当前的 rules 目录和 prometheus.yml 打包备份，确保出错能立即回滚。

cp -r /etc/prometheus/rules /etc/prometheus/rules.bak
cp /etc/prometheus/prometheus.yml /etc/prometheus/prometheus.yml.bak

获取对应版本的 promtool
promtool 的版本必须与运行的 Prometheus 服务端版本一致，否则校验结果可能不准确。可以从官方 GitHub Release 页面下载对应版本的压缩包。

本地校验规则

使用 promtool 检查规则文件，它会明确指出哪一行语法错误。

promtool check rules /etc/prometheus/rules/*.yml

报错示例与修复：

# 典型报错输出
error parsing rules: parse error at line 15: unknown function with name "old_func"

# 修复方法
# 1. 查阅官方变更日志确认该函数是否被移除
# 2. 替换为推荐的新函数或调整表达式逻辑

校验主配置
确保主配置文件也没有因为升级而产生结构不兼容。
```
promtool check config /etc/prometheus/prometheus.yml
```
应用并重载
将修改后的文件覆盖原文件，然后触发重载。
推荐方式（Systemd）：
```
systemctl reload prometheus
```
备选方式（HTTP API）：
注意：此方法要求 Prometheus 启动时添加了 `--web`.enable-lifecycle 参数，否则接口返回 403 或 404。
```
curl -X POST http://localhost:9090/-/reload
```

怎么验证是否生效

操作完成后，需要通过以下方式确认规则已正常加载：

检查日志：查看 Prometheus 启动日志或运行日志，确认没有 level=error 的规则加载失败信息。
访问 UI 页面：进入 Prometheus 网页控制台，点击 Status -> Rules，确认规则列表已显示且状态为 active。
调用 API：使用 curl 请求 http://localhost:9090/api/v1/rules，返回 JSON 中应包含你的规则组。
观察告警：确认 Alertmanager 是否开始收到预期的告警通知，排除因语法错误导致告警静默的情况。

常见坑

特性开关变化：某些 PromQL 功能在旧版本需要开启 feature flag，新版本可能默认开启或移除，需查阅变更日志。
时间单位写法：确保范围向量选择器中的时间单位（如 h, m, s）书写规范，旧版本可能容忍某些非标准写法。
标签匹配器：注意标签匹配语法是否有调整，尤其是正则匹配符的使用，新版本严格遵循 RE2 语法。
路径权限：替换规则文件后，确保 Prometheus 运行用户对新文件有读取权限，否则重载会失败。
重载方式选择：避免使用 kill -HUP，在 systemd 环境下优先使用 systemctl reload，确保配置原子性加载。

参考来源

Prometheus Official Documentation, Configuration, https://prometheus.io/docs/prometheus/latest/configuration/configuration/
Prometheus GitHub Releases, prometheus/prometheus, https://github.com/prometheus/prometheus/releases
Prometheus Official Documentation, Management API, https://prometheus.io/docs/prometheus/latest/management_api/