問題背景

近期在為項目搭建一套基于 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 界面，清理瀏覽器緩存后重新執行導入儀表盤的操作。這一次，儀表盤被順利保存，沒有再出現任何錯誤。監控圖表也成功加載并開始展示數據。問題得到圓滿解決。