Grafana 从 8.x 升级到 9.x 版本需要注意哪些破坏性变更?

文章导读
升级 Grafana 从 8.x 到 9.x 最稳妥的做法是先备份数据和配置文件,重点检查是否依赖 Angular 插件或旧版告警功能,确认无误后再执行升级操作。
📋 目录
  1. A 命令速用版
  2. B 为什么会这样
  3. C 分步处理
  4. D 怎么验证是否生效
A A

升级 Grafana 从 8.x 到 9.x 最稳妥的做法是先备份数据和配置文件,重点检查是否依赖 Angular 插件或旧版告警功能,确认无误后再执行升级操作。

先说结论:生产环境升级前必须备份,9.x 版本默认禁用了 Angular 插件支持(已弃用),可通过配置临时开启,同时启用了统一告警,旧配置可能失效。

  • 适合:希望获得更安全默认配置且不再依赖旧版面板的团队
  • 先准备:导出所有 Dashboard JSON 并确认插件兼容性列表
  • 验收:升级后检查告警规则状态及登录会话是否保持

命令速用版

如果你使用 Docker 部署,升级前请先停止容器并备份持久化卷。以下命令可用于备份配置和数据目录:

docker run `--rm` -v grafana-storage:/data -v $(pwd):/backup alpine tar czf /backup/grafana-backup.tar.gz -C /data .

升级镜像标签时,不要直接使用 latest,建议指定具体版本号,例如:

docker pull grafana/grafana:9.5.0

检查已安装插件列表,确认是否存在 Angular 插件:

Grafana 从 8.x 升级到 9.x 版本需要注意哪些破坏性变更?
grafana-cli plugins list

为什么会这样

Grafana 9.x 版本的主要变化集中在安全加固和技术债务清理。官方为了提升安全性,调整了 Cookie 的 SameSite 策略和认证令牌轮换机制,这可能导致旧浏览器或特定反向代理配置下出现登录失效。同时,为了推动生态现代化,9.x 默认禁用了基于 Angular 开发的旧版插件(已弃用),这类面板升级后会无法加载。告警系统方面,统一告警(Unified Alerting)成为默认引擎,旧版告警规则不再被主动处理,需要迁移。

分步处理

1. 备份数据:停止 Grafana 服务,备份数据库文件(通常是 grafana.db)和配置目录(/etc/grafana 或容器卷)。

2. 检查插件:在 8.x 版本运行期间,使用 grafana-cli plugins list 查看已安装插件列表。如果存在 Angular 插件,需在 9.x 配置中显式开启兼容模式或寻找替代面板。

Grafana 从 8.x 升级到 9.x 版本需要注意哪些破坏性变更?

3. 调整配置:如果需要保留旧版告警或 Angular 支持,编辑 /etc/grafana/grafana.ini 文件。在 [features] 分区中设置 angular_support_enabled = true,但建议尽快迁移。

4. 告警迁移:升级启动后,系统通常会提示迁移旧版告警至统一告警。如需手动控制,可在配置文件中确认 [unified_alerting] 相关设置,并在 UI 中完成规则迁移。

5. 执行升级:替换二进制文件或更新 Docker 镜像,启动服务。

6. 回滚准备:保留旧版本安装包或镜像,一旦验证失败,立即停止新服务并恢复备份数据。

怎么验证是否生效

升级完成后,首先访问首页确认无报错。检查告警页面,确认原有规则已迁移至统一告警列表且状态正常。尝试退出重新登录,验证会话 Cookie 是否正常工作,避免陷入登录循环。查看容器或系统日志(通常在/var/log/grafana 或 docker logs),搜索