首页/云/可观测性速查/看板 JSON 的结构要点
Grafana 与看板53 条

看板 JSON 的结构要点

看板以 JSON 为真源:uid/title/时间范围/变量/面板数组构成骨架;面板含 gridPos 栅格、targets 查询与 fieldConfig 字段配置,可整体导入导出。

可观测性速查云更新于 2026-10-13

看板文本是什么

看板以文本形式保存定义:标识与标题、时间范围、模板变量与面板数组构成骨架,面板内再包含栅格位置、查询与字段配置。界面上的每次调整最终都落成这份文本,因此它既是导入导出的载体,也是版本管理与批量修改的入口。

栅格模型与手工编辑

理解栅格模型能让布局可控:看板宽度固定为若干列,面板通过位置与尺寸描述自己在网格中的位置。手工修改文本时最容易出问题的是语法细节与引用关系,改完应先在副本上导入验证,再替换正式看板。

基本信息

栅格模型面板用坐标与宽高描述在网格中的位置
模板变量集中存放在变量列表中
模型版本随产品版本升级,导入旧版本会自动迁移
导入导出界面可整体导出为文本,也支持接口操作

典型使用场景

  • 看板迁移:导出后在另一套环境导入,快速复制整套视图
  • 版本管理:把看板文本纳入代码库,改动可评审可回滚
  • 批量修改:脚本化调整单位、阈值或查询模板
  • 模板复用:以现有看板为基础生成多套同构看板
  • 自动化部署:随环境初始化一起下发看板定义

精简结构示例

精简结构示例
{
  "uid": "app-overview",
  "title": "应用总览",
  "tags": ["app"],
  "refresh": "30s",
  "time": {"from": "now-6h", "to": "now"},
  "panels": [
    {"id": 1, "type": "timeseries", "title": "QPS",
     "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0},
     "targets": [{"refId": "A", "expr": "sum(rate(http_requests_total[5m]))"}]}
  ]
}

结构要点

部分作用注意
标识与标题唯一标识与展示名标识重复时导入会提示已存在
时间范围与刷新默认展示区间同一主题的看板保持一致
模板变量下拉选项定义默认值要有代表性
面板数组图表集合每个面板含位置、查询与配置
栅格位置在网格中的坐标与尺寸改动前先算好总宽度

常见问题

问题原因处理方式
导入提示已存在标识重复选择覆盖导入
导入解析失败文本语法错误先用校验工具检查一遍
面板重叠错位坐标计算错误按总宽度重新排布
同一份看板导入不同环境时,数据源引用可能失效:提前约定数据源命名,或在导入后统一替换引用。
手工编辑文本时留下多余的标点或注释会导致解析失败:先导入副本验证,再覆盖正式看板。

易错点

  • 直接编辑正式看板文本:一处语法错误会让看板打不开
  • 标识重复导入不选覆盖:改动看起来生效实际上没有生效
  • 看板不纳入版本管理:误删后只能从零重画
  • 把凭据写进看板文本:导出分享时一并泄露

数据来源与参考

  • Grafana 官方文档 · Dashboard JSON model
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌