Grafana OnCall插件在Grafana 10/11版本中的加载问题分析与解决方案

问题现象

在Grafana OnCall v1.9.8版本中，当用户升级Grafana到10或11版本后，插件无法正常加载。主要表现包括：

1. 插件界面无法显示任何内容
2. 网络请求中出现404错误，API调用路径不正确
3. 在告警组视图中出现明显的错误提示

问题根源

经过分析，该问题主要源于以下技术原因：

1. 路径解析问题：当Grafana部署在带有路径前缀（如/grafana）的反向代理后时，插件未能正确处理基础路径，导致API请求发送到错误的URL。

2. 版本兼容性问题：Grafana 10和11版本对插件系统进行了架构调整，而早期版本的OnCall插件未能完全适配这些变更。

3. 初始化流程变更：新版本Grafana对插件的初始化流程和配置方式进行了优化，需要采用新的配置方法。

解决方案

针对这一问题，Grafana OnCall团队在后续版本中进行了多项改进：

1. 升级到最新版本：建议升级到v1.9.22或更高版本，这些版本包含了完整的修复方案。

2. 启用必要功能开关：对于Grafana 11及更新版本，必须启用externalServiceAccounts功能标记。这一设置在Docker Compose和Helm Chart中已默认配置。

3. 新的插件配置方式：首次安装时需要采用API调用的方式进行配置，示例命令如下：

curl -X POST 'http://admin:admin@localhost:3000/api/plugins/grafana-oncall-app/settings' \
-H "Content-Type: application/json" \
-d '{"enabled":true, "jsonData":{"stackId":5, "orgId":100, "onCallApiUrl":"http://engine:8080/", "grafanaUrl":"http://grafana:3000/"}}'

4. 插件安装API调用：配置完成后，需要通过API调用完成安装：

curl -X POST 'http://admin:admin@localhost:3000/api/plugins/grafana-oncall-app/resources/plugin/install'

技术建议

1. 部署架构考量：在反向代理环境中部署时，应确保所有相关服务（Grafana、OnCall引擎等）的路径配置一致。

2. 版本升级策略：建议采用渐进式升级策略，先升级OnCall插件，再升级Grafana版本，以降低兼容性风险。

3. 监控与日志：在升级过程中，应密切监控网络请求和系统日志，确保所有API调用路径正确无误。

4. 测试环境验证：在生产环境部署前，建议在测试环境中完整验证插件的各项功能，特别是告警流程和通知功能。

总结

Grafana OnCall插件与Grafana主版本的兼容性问题是一个典型的前后端集成挑战。通过理解问题本质并采用正确的配置方法，用户可以顺利解决加载失败的问题。随着OnCall项目的持续发展，建议用户保持对最新版本的关注，以获得最佳的功能体验和稳定性。