Grafana版本升级失败：MySQL迁移索引错误

概述

在运维 Grafana 实例时，版本升级是一项常规但关键的变更操作，通常需要执行数据库迁移以适配新版本的数据结构。此问题描述了在使用外部 MySQL（版本 8）作为数据库时，从 Grafana 10.1.9 升级到更高版本（如 10.4）过程中，因数据库迁移脚本失败而导致升级中断的典型场景。失败的根本原因在于 Grafana 迁移脚本尝试在一个 TEXT 类型的列（name）上创建唯一索引，而 MySQL 不允许在未指定键长度的 BLOB/TEXT 列上创建此类索引。理解并解决此类问题对于保障监控平台服务的连续性和可升级性至关重要。

核心概念

  • Grafana 迁移器 (Migrator)：Grafana 内置的组件，负责在版本升级过程中自动执行数据库架构变更（DDL）。它会根据新旧版本的差异，运行预定义的 SQL 脚本来创建表、添加列、建立索引等。迁移失败会直接阻断应用启动。
  • MySQL 索引约束：MySQL 对索引创建有特定限制。对于 TEXT、BLOB 及其衍生类型（如 MEDIUMTEXT、LONGTEXT），在创建普通索引或唯一索引时，必须为索引指定一个最大长度（例如 name(100)），否则会引发 Error 1170 (42000): BLOB/TEXT column 'name' used in key specification without a key length。这是 MySQL 的固有行为，旨在避免因索引过大而影响性能。
  • 问题场景：Grafana 的 library_element 表中存在一个 TEXT 类型的 name 列。在升级到特定版本时，迁移脚本试图为该列（连同其他列）创建一个复合唯一索引 UQE_library_element_org_id_folder_uid_name_kind。由于脚本未为 name 列指定长度，导致 MySQL 拒绝执行该 DDL 语句。

实践

当遇到此升级错误时，可以采取以下步骤进行诊断和解决：

1. 确认问题

检查 Grafana 的日志，寻找与迁移失败相关的关键错误信息，例如： Error 1170 (42000): BLOB/TEXT column 'name' used in key specification without a key length

2. 诊断表结构

连接到 Grafana 所使用的 MySQL 数据库，检查出问题的表结构。

DESCRIBE library_element;

确认 name 列的数据类型确实为 TEXT 或类似类型。

3. 解决方案

根据实际情况，选择以下一种或多种方案：

  • 方案 A（推荐）：手动修正表结构（谨慎操作） 此方案旨在使现有表结构符合 Grafana 迁移脚本的预期。在执行任何操作前，请务必完整备份数据库。

    -- 1. 查看当前表的索引情况
SHOW INDEX FROM library_element;

-- 2. 如果确认该索引不存在且迁移失败，可以尝试为 TEXT 列添加一个指定长度的索引来“欺骗”迁移器，或者考虑修改列类型。
-- 注意：直接修改线上生产环境表结构风险极高，建议在预演环境测试。
-- 示例（仅示意，非标准操作）：为一个带长度的虚拟列创建索引，但这可能不是迁移器期望的。更稳妥的方式是查阅 Grafana 官方 issue 或更新日志，看是否有官方补丁。
-- 最安全的路径是：备份数据库 -> 停止 Grafana -> 按照官方修复指南操作 -> 启动 Grafana。

  • 方案 B：调整 Grafana 配置以跳过特定迁移（临时方案） Grafana 支持通过配置跳过失败的迁移步骤，但这可能导致功能不完整或后续迁移再次失败。此方法仅可用于紧急恢复，不推荐作为长期解决方案。 在 Grafana 配置文件（grafana.ini 或环境变量）中设置：

    [database]
skip_migrations = true

    或者通过环境变量：

    GF_DATABASE_SKIP_MIGRATIONS=true

    启动 Grafana 后，它将跳过所有数据库迁移。你需要手动应用必要的架构变更，或者等待 Grafana 提供修复版本后，关闭此配置并重新运行迁移。

  • 方案 C：联系官方支持或降级 查阅 Grafana 官方 GitHub Issue（如引用来源），查看是否有其他用户遇到相同问题以及官方的建议修复方案（例如发布补丁版本）。在获得明确指导前，可考虑暂时回退到已知可工作的旧版本（10.1.9），直至问题解决。

4. 升级与验证

无论采用哪种解决方案，在重新尝试升级前，都建议：

  1. 在与生产环境隔离的测试环境中验证整个升级流程。
  2. 升级完成后，登录 Grafana 界面，验证仪表盘、告警规则、数据源等核心功能是否正常。
  3. 持续监控 Grafana 的启动日志，确保后续的数据库迁移均成功执行。

SRE 要点

  • 与可靠性、可观测性的关联：此故障直接阻碍了软件升级流程。及时升级对于获取安全补丁、性能改进和功能新特性至关重要。升级失败会阻碍 SRE 团队维护系统可靠性和安全性的能力，同时 Grafana 作为监控平台，其自身的稳定性是保障全局可观测性的基础。
  • 最佳实践与常见反模式：
    • 最佳实践：任何重大版本升级都应在预演环境中进行全流程测试，特别要测试数据库迁移。维护一份完整的数据库备份，以便在迁移失败时能快速恢复。在升级计划中明确包含回滚步骤。
    • 常见反模式：直接在生产环境执行未经测试的升级；忽视迁移失败日志，尝试反复重启应用；在没有备份和回滚计划的情况下进行数据库结构变更。
  • 相关指标（SLI/SLO/SLA）：
    • SLI：升级操作的成功率、从迁移失败到服务恢复的平均时间（MTTR）。
    • SLO：可设定“Grafana 主要版本升级操作应在测试环境验证通过，且生产环境升级成功率 > 99%”。
    • SLA：此问题本身不直接影响对外服务的 SLA，但长期未解决的升级阻塞可能导致无法修复影响 SLA 的安全漏洞或关键缺陷。

此问题是一个典型的 grafana-migration-troubleshooting 案例，体现了应用程序与外部数据库交互时，对数据库平台特性和约束的依赖。SRE 在处理此类问题时，需要结合应用程序日志、数据库元数据以及官方文档进行综合分析。