升级与回滚

升级三原则

1. 先看发布说明：每个版本的 Release Notes 与「breaking changes」列表决定了这次升级要不要额外动作，大版本跳跃前尤其要读。
2. 先在预发验证：用同一份生产数据备份，在测试环境跑一遍目标版本。
3. 永远先备份：备份成本是分钟级，没备份的回滚成本是数据级。

动手前：备份

包安装形态下，备份配置目录与数据目录即可：

sudo systemctl stop grafana-server
sudo tar czf grafana-backup-$(date +%F).tgz \
  /etc/grafana /var/lib/grafana
sudo systemctl start grafana-server   # 备份完先恢复服务,再升级

使用外部 MySQL / PostgreSQL 时，数据在数据库里，务必同时做 mysqldump 或 pg_dump。Docker 卷的备份命令见Docker 与 Docker Compose。更系统的备份与迁移方案，读迁移与备份。

各安装路径的升级命令

Debian / Ubuntu（apt）

sudo apt update
sudo apt install grafana      # 升级当前安装
sudo systemctl daemon-reload
sudo systemctl restart grafana-server

RHEL 系（dnf）

sudo dnf update grafana
sudo systemctl restart grafana-server

Docker

docker compose pull && docker compose up -d

Helm

helm repo update
helm upgrade grafana grafana/grafana \
  -n monitoring -f values.yaml

升级过程中发生了什么

• 服务启动时自动执行数据库迁移，过程可能持续几十秒到几分钟，不要中途 kill 进程。
• 多实例部署时：先升一个实例验证，再滚动其余实例；升级窗口内避免新旧大版本混跑。
• 插件需要跟进：grafana cli plugins update-all（旧版本命令名为 grafana-cli，以安装版本为准）。
• 升级完用 curl http://localhost:3000/api/health 确认 database 正常，详见日志、诊断与服务器管理。

注意： 迁移是单向的。数据库 schema 被新版本改写过之后，老版本二进制未必还能读这份数据。因此「可靠的回滚」等于「还原备份」，而不是「装回旧版本」。

回滚策略

1. Helm 一键：helm rollback grafana <REVISION> -n monitoring，只回 Chart 与镜像，数据仍可能是新版本迁移过的——所以备份不可省。
2. apt 回装旧版：apt policy grafana 找到旧版本号，sudo apt install grafana=<旧版本>。
3. dnf 降级：sudo dnf downgrade grafana。
4. Docker：把 compose 里的 tag 改回旧版本再 up -d。
5. 兜底：停服务，清空数据目录，解回升级前的备份压缩包，再启动。

跨大版本（例如 11.x 到 12.x）的回滚，强烈建议走第 5 条：恢复备份 + 旧版本，干净彻底。

常见坑

• 升完没重启：systemd 单元文件也可能随包更新，记得 daemon-reload。
• 插件与新版本不兼容：界面报插件错误时，先升级或暂时禁用对应插件。
• 外部数据库账号权限不足：迁移需要 DDL 权限，只给 SELECT 的账号会在启动时刷错误日志。
• 一步跨多个大版本：老版本直升最新版风险高，必要时逐级升级。

下一步

• 各形态的安装细节：Docker 与 Docker Compose、Kubernetes 与 Helm 部署。
• 升级后配置项行为变了？查配置文件 grafana.ini。
• 例行备份机制，见迁移与备份。