问题背景

近期在为项目搭建一套基于 Prometheus 和 Grafana 的可观测性体系。在完成基础部署后，我准备导入一个功能相对复杂的官方仪表盘模板，以便快速监控各项指标。然而，当上传仪表盘的 JSON 文件并点击保存时，Grafana 界面却反复提示一个模糊的错误：“Fail to save dashboard”。

这个提示信息非常笼统，没有提供任何有价值的线索。对于这种前端返回的模糊错误，我的第一反应是：查看后端服务的日志。

排查过程

我通过 Portainer 工具进入 Grafana 容器的日志界面，希望能找到具体的错误原因。刷新日志后，在尝试保存仪表盘的同一时间点，我捕获到了几条关键的 error 级别的日志记录。

logger=context userId=1 orgId=1 uname=admin t=2025-09-05T04:43:14.966823219Z level=error msg="Failed to save dashboard" error="rolling back transaction due to error failed: invalid connection: Error 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes" remote_addr=120.235.47.15 traceID=

这条日志信息非常清晰，直接指明了问题的核心。我们来拆解一下这条关键错误：

1. msg="Failed to save dashboard"：这明确了操作失败的环节，与前端界面提示一致。
2. rolling back transaction：这表明 Grafana 在尝试向其后端数据库写入数据（即仪表盘的配置信息）时，发生了一个事务回滚。这说明问题出在数据库层面。
3. Error 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes：这是决定性的线索。这是一个典型的 MySQL 数据库错误。它告诉我们，客户端（这里是 Grafana）尝试发送一个数据包给 MySQL 服务器，但这个数据包的大小超过了 MySQL 服务器配置中 max_allowed_packet 参数所允许的最大值。

根源分析

结合日志信息，整个问题的脉络就清晰了：

• Grafana 使用 MySQL 作为其后端数据存储，用于保存用户信息、仪表盘配置等数据。
• 我们导入的仪表盘 JSON 文件内容比较庞大，当 Grafana 将其作为一个数据包准备写入 MySQL 数据库时，这个数据包的体积超过了 MySQL 当前的 max_allowed_packet 限制。
• MySQL 拒绝接收这个过大的数据包，导致连接错误和事务失败。
• 最终，Grafana 无法完成写入操作，向上层返回了“保存仪表盘失败”的错误。

问题看似出在 Grafana，但实际上是其依赖的后端数据库 MySQL 的配置限制所导致的。

解决方案

定位到问题根源后，解决办法就非常直接了：调大 MySQL 服务的 max_allowed_packet 参数值。

具体操作步骤如下：

1. 定位 MySQL 配置文件：
   通常是 my.cnf 文件。如果你使用 Docker 部署，可能需要挂载自定义的配置文件或通过环境变量来修改。

2. 修改配置参数：
   在配置文件的 [mysqld] 部分下，找到或添加 max_allowed_packet 参数，并将其设置为一个更大的值。默认值通常较小（如 4M 或 16M），对于复杂的仪表盘可能不够用。这里我将其调整为 64M，以留出充足的余量。

   [mysqld]
   max_allowed_packet = 64M
   

3. 重启 MySQL 服务：
   修改配置后，必须重启 MySQL 服务才能使新的配置生效。

   # 如果是系统服务
   systemctl restart mysqld# 如果是 Docker 容器
   docker restart your-mysql-container-name
   

结果验证

在重启 MySQL 服务并确认新配置生效后，我回到 Grafana 界面，清理浏览器缓存后重新执行导入仪表盘的操作。这一次，仪表盘被顺利保存，没有再出现任何错误。监控图表也成功加载并开始展示数据。问题得到圆满解决。