跳转至

故障解决报告

故障一：Grafana"使用说明与阶梯电价规则"面板显示默认内容（2026-08-27）

故障时间

  • 发现：2026-08-27（用户查看大盘时发现）
  • 修复完成：2026-08-27 15:40 左右

故障现象

  • 大盘中"使用说明与阶梯电价规则"折叠行下的文本面板，始终显示 Grafana 新建面板的默认内容 （# Title / For markdown syntax help: commonmark.org/help）， 而非配置的阶梯电价规则说明。
  • 用户在 Windows 上通过本地 hosts 将 grafana.rainchen.top 解析到 k8s 高可用 VIP （haproxy+keepalived，VIP=192.168.0.8，落在 master01=192.168.0.2）， 经 traefik → IngressRoute → 集群 Grafana 访问，多轮刷新/无痕窗口均复现。

故障影响

  • 仅影响该说明类文本面板的显示，不影响用电数据指标、告警与采集链路。

根本原因

  • 大盘 JSON 中文本面板（id=18）的内容写在顶层 content 字段（Grafana 6.x 旧格式）， 而 Grafana 8.5.3 的 React TextPanel 前端只读取 options.content； options.content 缺失时前端回退渲染默认 # Title 模板。
  • 因此无论修改 ConfigMap 中的顶层 content 多少次、如何强刷浏览器，页面永远显示默认模板。
  • 排查中曾误判为"浏览器缓存/另一套 Grafana 实例/数据源陈旧"，最终通过 TRAE 内置浏览器 按用户同款链路实测复现，并经 d-solo 单面板视图对比 API 数据与渲染结果后定位真凶。

解决方案（已执行）

  1. 修改 ConfigMap electric-power-dashboard（monitoring 命名空间）：
  2. panel 18 options.content 写入完整阶梯电价规则（三档价格表+计费示例，511 字符）
  3. options.mode=markdown，顶层 content 同步保留（双格式兼容）
  4. sidecar 自动热加载，大盘版本升至 v56
  5. 同步修复本地 grafana_dashboard.json（补 options.content），防止再次导入复现。
  6. 清理排查过程中 rollout restart 遗留的 Pending Pod，Deployment 已收敛回原始单 Pod 状态。

验证结果

  • TRAE 内置浏览器经内网 VIP 链路（hosts→192.168.0.8→traefik）实测， d-solo 单面板视图渲染出完整阶梯电价规则，与 API 数据一致。

避免再次出现的建议

  • 以后修改 Grafana 8.x 文本面板内容，必须同时写 options.content（或经 UI 编辑自动生成正确结构）。
  • 本地大盘 JSON 模板已修复双格式，后续导入即正确。
  • 变更大盘配置后，用"页面实际渲染结果"（而非仅 API 返回）做最终验收。

回滚方案

kubectl apply -f backups/grafana_panel_fix_20260827/cm_backup_20260827.yaml

相关存档

  • backups/grafana_panel_fix_20260827/cm_backup_20260827.yaml（修复前原始版）
  • backups/grafana_panel_fix_20260827/cm_fixed_20260827.yaml（第一次修复版）
  • backups/grafana_panel_fix_20260827/cm_fixed_v56_final.yaml（最终生效版 v56）

附：同日其他操作记录

  1. 面板内容升级：文本面板内容由简单说明升级为"使用说明+三档阶梯价格表+3000度计费示例"。
  2. 顺带排查结论（非故障）：
  3. 内网 Grafana 访问链路：Windows hosts → VIP 192.168.0.8(haproxy+keepalived) → traefik → 集群 prometheus-grafana；
  4. 公网链路 grafana.rainchen.top(129.226.138.204 堡垒机 nginx → frps:3000 → frpc) 与内网链路最终指向同一台集群 Grafana；
  5. master01 上无独立 Grafana 实例（此前怀疑的 8.5.3 即集群 Grafana 自身版本）。

故障二：kube-prometheus-stack 跨版本升级后用电大盘丢失（2026-09-03）

故障时间

  • 2026-09-03 21:26 helm 升级（revision 22：chart 87.21.0 / Grafana 8.5.3→13.1.1 / Prometheus v0.92.1），升级后发现大盘丢失。

故障现象

  • Grafana 中"家庭日用电量监控大盘"消失；
  • MySQL-Electric 数据源消失（仅剩 Alertmanager/Prometheus）。

影响范围

  • 仅大盘可视化与数据源配置丢失；用电数据在 MySQL（server 命名空间 mysql-0，11h 未重启）完好无损，采集链路（每日20:00任务）不受影响。

根本原因

  • 大盘 ConfigMap electric-power-dashboard 当初是裸 apply 创建，未纳入任何持久管理； kube-prometheus-stack 跨版本升级过程中该 ConfigMap 被清理，sidecar 无源可加载，大盘随之消失。
  • 数据源因存在 Grafana 数据库（旧实例数据未迁移/重建），升级后同样丢失。

解决方案（已执行，全部验证通过）

  1. 校验 8-27 存档 backups/grafana_panel_fix_20260827/cm_fixed_v56_final.yaml（18面板、options.content 511字符完整）， 清理 runtime 字段后重新 kubectl apply → sidecar 自动写入并通过 Grafana 13 新版 provisioning API reload 导入成功。
  2. 按大盘面板实际引用的数据源 uid mysql-electric（非7-29旧备份的 aY8YGFEvz）重建 MySQL 数据源， 密码来自 .env，health 检查 Database Connection OK。
  3. 恢复文件纳入项目管理：k8s/grafana-dashboard-cm.yaml（以后升级后可一键重恢复）。

注意事项（版本变化）

  • Grafana service 更名：prometheus-grafana → kube-prometheus-stack-grafana（端口 3000→80），port-forward/监控集成需同步修改。
  • Grafana admin 密码已随升级更新为 secret kube-prometheus-stack-grafana 中的 Grafana@2026。
  • Grafana 13 使用新版 provisioning 体系（provisioning.grafana.app），/api/search 列表返回可能滞后，以 /api/dashboards/uid/<uid> 直查为准。

避免再次出现的建议

  • 大盘 ConfigMap 已存档于 k8s/grafana-dashboard-cm.yaml 并纳入 git 管理，今后升级后执行 kubectl apply -f k8s/grafana-dashboard-cm.yaml 即可一键恢复；
  • 数据源若也用 ConfigMap（label grafana_datasource: "1"）provisioning，可彻底避免升级丢失（后续可选优化）。

回滚/恢复命令

# 大盘恢复（本报告执行过）
kubectl apply -f k8s/grafana-dashboard-cm.yaml
# 数据源重建：见 Grafana API POST /api/datasources（uid=mysql-electric，密码在.env）

来源：/home/rain/Documents/electricity_monitoring/故障解决报告.md ｜ 最后更新：2026-09-03 22:05（由 build/sync.py 同步，请勿在站点侧修改）