手把手教你用 Git 仓库（GitLab）管理仪表盘，轻松协作回滚

原标题：还在手动备份Grafana面板？手把手教你用 Git 仓库（GitLab）管理仪表盘，轻松协作回滚

如何将 Grafana 中的仪表盘同步存储到 Gitlab 私有代码仓库?

描述：上一篇文章说到，由于 Grafana 出现了几个高危的安全漏洞，作者将原本的 12.0.2版本，升级到最新的 grafana:13.0.1-security-01 版本，升级后发现一个新功能查看和管理已配置的存储库，其支持在 Git 中（Github、Gitlab 私有、本地网络共享目录）将数据面板作为代码进行管理，并自动预置更新，将数据面板存储在版本控制的存储中，以便更好地整理内容和跟踪历史记录。

该功能对于多人协作的团队来说非常有用，可以确保每个人都在使用最新的数据面板版本，并且可以轻松地回滚到旧版本。遂作者立马浅尝了一下，将内部搭建 Gitlab 私有仓库为例进行演示对接。

温馨提示：Grafana 缺省可配置 10 个连接的存储库，即最多可配置 10 个 Git 仓库，如果需要更多连接，则需要修改配置文件 grafan.ini 中的 max_concurrent_connections 值。

什么是 git-sync ?

描述：git-sync 是 Grafana 中的一个插件，该插件是在 Grafana v12 开源版和 Enterprise 版本中引入，Git Sync 允许你同步资源，从而将仪表盘存储为任何 Git 提供商的 JSON 文件，并以代码形式管理，我们可以高效地进行版本控制、协作和自动化部署。

工作原理：

Git Sync 允许你将外部资源与 Grafana 实例连接起来。设置后，所有同步的资源都存放在 Git 的配置文件夹下，你也可以继续使用该文件夹外的非配置资源。

Git 同步是双向的。你可以从Grafana界面或同步仓库修改已配置的资源，变更都会在两者中反映。

Git Sync 通过 Pure Git 仓库类型对任何 Git 提供商开放，并针对 GitHub、GitLab 和 Bitbucket 提供了专门的增强集成。

使用场景:

版本控制与审计: 组织可以维护 Grafana 仪表盘的结构化、版本控制历史。

自动化部署与CI/CD集成: 团队可以通过将仪表盘更新集成到CI/CD流水线中来简化工作流程。

协作仪表盘开发: 通过 Git Sync，多个用户可以同时处理仪表盘，而不会覆盖彼此的修改，基于分支的工作流程，还可合并到主分支。

多环境同步：管理多个Grafana实例（如开发、预备和生产环境）的企业可以无缝同步仪表盘。

容灾备份：通过持续同步仪表盘到GitHub，组织可以创建一个始终更新的备份，确保仪表盘不会因意外删除或系统故障而丢失。

最后，为了便于看友们实践，作者将分别介绍配置以及使用 git-sync 的操作步骤，在此之前，相信你已经准备好了 Grafana （版本：13.0.1-security-01）以及 Gitlab 代码仓库，若还没安装部署对应环境的可参考如下知识星球文章。

[Grafana | 开源的可视化平台初识到云原生环境下部署实践]：https://articles.zsxq.com/id_gkzolgtmxflo.html

[GitLab | 企业私有代码仓库介绍与快速安装部署]：https://articles.zsxq.com/id_0md13kj1zmlb.html

如何配置 git-sync 插件?

步骤 01.首先，在 Gitlab 私有代码仓库中创建一个 dashboard 项目（名称可自定义），勾选使用[v]使用自述文件初始化仓库，然后点击创建项目。

步骤 02.创建完毕后，进入到项目设置 >> 访问令牌，点击创建个人访问令牌，勾选 api 权限，然后点击创建即可，之后将生成好的令牌复制下来，例如 glpat-3QgGbNVPTYsWi_f_UXh9，稍后将用到。

步骤 03.接下来，在 Grafana 中配置 git-sync，点击 管理 >> 概况 >> Provisioning，再点击 存储库，在配置下拉按钮中选择纯 Git，将如下图所示，将第二步生成的令牌以及git 项目地址填入，然后点击配置存储库。

温馨提示：若此步骤提示错误，可在文章末尾查阅到常见错误的解决办法，这也是作者所遇到的。

步骤 04.在配置存储库界面，选择默认分支（通常为 master、main）以及文件夹（可选），然后点击选择要同步的内容，这里大家可自定义显示名称，到时会在仪表中看到，然后点击选择附加设置。

步骤 05.之后，在进行同步频率以及勾选保存时启用拉取请求选择，以及启用同步分支。

步骤 06.创建完毕后，便可在页面中查看到同步仓库的状态信息，以及操作更新日志等。

至此，我们完成了 Gitlab 私有仓库与 Grafana 的对接，接下来便可将仪表盘同步到 Gitlab 中进行版本控制了。

如何使用 git-sync 插件?

步骤 01.首先，点击仪表盘，选择前面自定义设置的仓库（存储名称）名称，例如：devops/dashboard.git 存储库。

步骤 02.接下来，创建一个名为 Test 的目录，是不是有点类似于 Gitlab 中提交文件夹的操作，没错完一致，在 Grafana 仪表盘中创建的目录，也会同时提交到 Gitlab 仓库中的 dashboard 项目中。

步骤 03.在 Test 目录下，创建一个新的仪表盘，例如：GitRsyncDashboard，创建过程中可选择目录文件，以及保存分支和仪表盘文件名称，例如：GitRsyncDashboard-2026-05-27-j746.json

步骤 04.之后，在该仪表盘下创建数据面板，例如，查询 categraf agent的 golang 版本信息，使用 Table 面板，并添加查询语句：categraf_go_info{job="categraf_linux"}。

步骤 05.创建完毕后，将会弹出一个对话框，显示已同步到的 Git 仓库。

步骤 06.接下来，进入到 Gitlab 私有仓库 dashboard 中查看，会发现已经将创建仪表盘JSON文件同步过来了。

步骤 07.然后，在 Gitlab 中尝试修改仪表盘文件，例如：将面板的名称改成 监控服务信息-更新测试，之后回到 Grafana > Provisioning 手动同步，或等待 60s 后自动同步。

步骤 08.同步完毕后，在 Grafana 中查看仪表盘，会发现面板名称已经更新为 监控服务信息-更新测试。

步骤 09.在仪表盘中添加的Git存储库，无法直接将现有的 dashboard 进行移动和导入，若要导入只能通过 git pull/push 将我们导出的面板json上传到 devops/dashboard.git 仓库中;另外，如果是同一台机器导入的记得更改面板模板文件中的 metadata.name指，不能与现有的重复，否则会导入失败。

至此, 作者已经将 Grafana 中的仪表盘同步存储到 Gitlab 私有代码仓库中了，后续便可基于此进行版本控制了。

入坑出坑

问题1.在配置 git-sync 插件连接 Git 仓库时，由于 grafana 在 k8s 中部署 集群 dns 未解析到部署的 gitlab 域名：

纯文本

Error validating repository
list refs: list refs: send ls-refs command: Post "https://git.weiyigeek.top/devops/dashboard.git/git-upload-pack": dial tcp: lookup git.weiyigeek.top on 10.96.0.10:53: no such host

解决办法：在 kubernetes 集群中使用 deployment 部署 grafana 时为其指定 hostAliases，例如：

纯文本

$ kubectl edit deployments.apps -n dashboard grafana-server
....
 dnsPolicy: ClusterFirst
  hostAliases:
  - hostnames:
    - auth.weiyigeek.top
    ip: 192.168.10.61
  - hostnames:
    - git.weiyigeek.top
    ip: 192.168.10.62
  restartPolicy: Always
....

问题2.在配置 git-sync 插件连接 Git 仓库时，由于企业内部 gitlab 服务采用自签证书，连接时报如下错误：

纯文本

Error validating repository
list refs: list refs: send ls-refs command: Post "https://git.weiyigeek.top/devops/dashboard.git/git-upload-pack": tls: failed to verify certificate: x509: certificate signed by unknown authority

问题原因：由于自签证书不被服务器信任，导致连接失败。

解决办法：使用插件时跳过证书验证，在 k8s 中编辑 configmap 配置文件，添加如下参数，之后重启 pod 即可。

纯文本

# 步骤 01.插件跳过证书验证
$ kubectl edit configmap -n dashboard grafana-server
...
[plugins]
app_tls_skip_verify_insecure=true

# 步骤 02.复制CA证书（需要先将证书复制到容器，可用 docker cp）
# docker cp your-git-ca.crt grafana:/tmp/
cd /tmp && wget http://10.20.172.106:8080/Root-CA.crt 
cp /tmp/your-git-ca.crt /usr/local/share/ca-certificates/
# 更新信任库
update-ca-certificates

# 步骤 03.将证书复制到持久化目录中，以便于下次执行。
mkdir /var/lib/grafana/certs/
cp /usr/local/share/ca-certificates/Root-CA.crt /var/lib/grafana/certs/
tee update_ssl.sh<<'EOF'
#!/bin/bash
cp /var/lib/grafana/certs/Root-CA.crt /usr/local/share/ca-certificates/
# 更新信任库
update-ca-certificates/
EOF

问题3.导入仪表盘时，由于面板模板文件中的 metadata.name 与现有的重复，导致导入失败。

错误信息：

纯文本

writing resource from file dashboard-1779928713682.json: resource validation failed: resource '5bb2b435-0bf9-48be-bc54-f95e01c98a3f' already exists and is not managed; repo 'rh2qvf' cannot take over without an explicit migration (file: dashboard-1779928713682.json, name: 5bb2b435-0bf9-48be-bc54-f95e01c98a3f, action: created)

解决办法：在导入面板模板文件前，先修改 metadata.name 字段值，在 push 到 git 仓库中。

纯文本

{
  "apiVersion": "dashboard.grafana.app/v2",
  "kind": "Dashboard",
  "metadata": {
    "name": "5bb2b435-0bf9-48be-bc54-f95e01c98a39",  // 修改此处值，使其唯一性
    "generation": 41,
    "creationTimestamp": "2026-05-21T10:53:27Z",
    "labels": {},
    "annotations": {}
  },
...
}

参考地址：https://grafana.com/docs/grafana/latest/as-code/observability-as-code/git-sync/

温馨提示：若文章代码块中存在乱码或不能复制，请联系作者，也可通过文末的阅读原文链接，加入知识星球中阅读，原文链接：https://articles.zsxq.com/id_e51g5o55wwfs.html

加入：作者知识星球