点出来的看板，就是早晚会丢的看板

一句话总结

dashboard 的事实来源必须是文件。Grafana 的数据库只不过是把该文件绘制成画面的地方。

为什么需要它

通过点击创建的 dashboard，其消失路径总是一样。

1. 故障期间匆忙创建几个 panel，它们很有用。
2. 下一周仍继续打开该 dashboard，并把链接分享给团队。
3. 六个月后迁移集群或重新搭建 Grafana。
4. 没有人能恢复这个 dashboard，创建它的人已经去了其他团队。

此外还有一种悄无声息的损失。即使有人修改阈值线或删除 panel，**也不会留下历史记录。**面对“这个 panel 以前不是存在吗？”的问题，没有任何回答方法。

它如何工作

把 dashboard 保存为文件需要两样东西：dashboard JSON，以及通知 Grafana 查看该目录的 provider 文件。混淆这两者是第一道关卡。

# provisioning/dashboards/lab.yml — JSON 이 아니라 '어디를 보라' 는 지시다
apiVersion: 1
providers:
  - name: lab
    type: file
    updateIntervalSeconds: 10
    allowUiUpdates: false
    options:
      path: /root/graf/dashboards      # ← 여기 있는 *.json 이 대시보드가 된다

以这种方式提供的 dashboard，其 API 响应中的 meta.provisioned 为 true。在该状态下尝试通过 API 覆盖 dashboard，Grafana 会以 Cannot save provisioned dashboard 拒绝，从而阻断画面与文件产生偏差的途径。

即使数据库中已经存在相同 uid 的 dashboard 也没有关系。provisioning 会接管它，因此可以把通过点击创建的 dashboard 迁移到文件。创建时可以先在 UI 中方便地制作，完成后再导出 JSON 并固化为文件。

uid 就是地址

固定 uid 是这项工作的核心。dashboard 链接形如 /d/shop-api/...，因此 uid 本身就是地址；告警、文档、书签以及其他 dashboard 的链接都会引用这个值。如果从导出的 JSON 中删除 uid 后再导入，就会出现两个相同的 dashboard，而链接仍然指向旧的那个。

常见误解

**“把 export 的 JSON 原样提交就结束了。”**该 JSON 中的数据源已经以 uid 固定引用。如果各环境的 uid 不同，在其他环境中就会显示空白。应在各环境中把 uid 固定为相同值，或者把数据源本身提取成变量。

“id 字段也可以一起提交。”id 是只在该 Grafana 实例中有意义的序号。迁移后可能与另一个 dashboard 的 id 冲突。对于需要迁移的 JSON，保留 uid、删除 id 更安全。

实际工作中真正重要的事

dashboard JSON 的 diff 很难由人阅读。坐标和字段会大量移动，review 很容易流于一句“LGTM”。

因此，团队值得制定一条规则：**要求在 PR 描述中用一句话写明修改后的 dashboard 回答什么问题。**如果写不出这句话，该变更通常只是又添加了一个 panel，而这正是走向本课程开头所说“图表墙”的道路。