菜单
文档面包屑箭头 Grafana 文档面包屑箭头 管理面包屑箭头 插件管理
Enterprise 版 Grafana Cloud 开源版 RSS

插件管理

你可以使用 plugins 增强你的 Grafana 体验，这些插件是内置 Grafana 的可视化和数据源之外的扩展。

本指南将向你展示如何安装由 Grafana Labs、商业合作伙伴、我们的社区构建的插件，或者你自己构建的插件。

插件类型

Grafana 支持三种类型的插件

  • 面板 - 这些插件使你可以轻松创建和添加任何类型的面板，以展示你的数据或改进你喜欢的仪表盘。
  • 数据源 - 这些插件允许你从各种数据源（如数据库、API、日志文件等）拉取数据，并以图表、折线图和仪表盘的形式在 Grafana 中显示。
  • 应用 - 这些插件可以将数据源、面板、仪表盘和 Grafana 页面捆绑成一个内聚的体验。

面板插件

使用面板插件向仪表盘添加新的可视化，例如时钟、马赛克和变量面板。

在以下情况下使用面板插件

  • 可视化数据源查询返回的数据。
  • 在仪表盘之间导航。
  • 控制外部系统，例如智能家居设备。

数据源插件

数据源插件增加对新数据库的支持，例如Google BigQuery。

数据源插件与外部数据源通信，并将数据以 Grafana 理解的格式返回。通过添加数据源插件，你可以立即在任何现有仪表盘中使用这些数据。

当你想查询外部或第三方系统中的数据时，使用数据源插件。

应用插件

应用，或称为 app 插件，捆绑数据源和面板以提供内聚的体验，例如 Zabbix 应用。

应用还可以添加自定义页面，例如控制面板。

当你想要开箱即用的监控体验时，使用应用插件。

管理应用插件的访问权限

使用 RBAC 自定义应用插件的访问权限。

默认情况下，Viewer、Editor 和 Admin 角色拥有其组织角色允许访问的所有应用插件的权限。权限由 fixed:plugins.app:reader 角色授予。

注意

要阻止用户查看应用插件，请参阅这些权限场景。

插件目录

Grafana 插件目录允许你在 Grafana 内部浏览和管理插件。只有 Grafana 服务器管理员和组织管理员才能访问和使用插件目录。有关 Grafana 角色和权限的更多信息，请参阅角色和权限。

以下访问规则根据用户角色而定

  • 如果你是组织管理员，你可以配置应用插件，但不能安装、卸载或更新它们。
  • 如果你是服务器管理员，你不能配置应用插件，但可以安装、卸载或更新它们。
  • 如果你既是组织管理员又是服务器管理员，你可以配置应用插件，也可以安装、卸载或更新它们。

注意

Grafana 插件目录仅设计用于单个 Grafana 服务器实例。对 Grafana 集群的支持计划在未来的 Grafana 版本中提供。

视频展示了早期版本的 Grafana 中的插件目录。

注意

如果需要，可以通过在配置文件中使用 plugin_admin_enabled 标志禁用 Grafana 插件目录。

浏览插件

浏览可用插件：

  1. 以管理员身份登录 Grafana 后，在侧边菜单中点击管理 > 插件和数据 > 插件以查看已安装和可用插件。
  2. 使用搜索功能根据名称、关键词、组织和其他元数据进行筛选。
  3. 点击数据源、面板或应用按钮按插件类型进行筛选。

安装插件

安装插件最常见的方式是通过 Grafana UI，但也提供了其他方法。

  1. 在 Grafana 中，在侧边导航菜单中点击管理 > 插件和数据 > 插件以查看所有插件。
  2. 浏览并找到插件。
  3. 点击插件图标。
  4. 点击安装。

根据你的设置，还有其他安装插件的方式。

使用 Grafana CLI 安装插件

Grafana CLI 允许你使用命令行安装、升级和管理 Grafana 插件。有关 Grafana CLI 插件命令的更多信息，请参阅插件命令。

从 ZIP 文件安装插件

此方法通常用于插件目录中不可用的插件或在没有互联网访问的环境中。

下载包含插件资产的存档，然后将其解压到插件目录中进行安装。例如：

bash 
unzip my-plugin-0.2.0.zip -d YOUR_PLUGIN_DIR/my-plugin

插件目录的路径在配置文件中定义。有关更多信息，请参阅配置。

使用 Grafana 配置安装插件

注意

此功能需要 Grafana 11.5.0 或更高版本。

通过将插件 ID 添加到 Grafana 配置文件的 plugins.preinstall 部分，可以安装插件。这可以防止插件意外卸载，并且可以自动更新。有关更多信息，请参阅配置。

在隔离环境（air-gapped environment）中安装插件

插件安装通常需要互联网连接。你可以检查在实例安装期间使用了哪些端点，并将它们添加到实例的允许列表中。

如果无法做到这一点，你可以通过使用Grafana CLI 或以 ZIP 文件的形式安装插件。

你可以按照 API 中引用的下载链接，从 Grafana.com API 获取任何插件。以下是一个基于 grafana-lokiexplore-app 插件的示例。

  1. 打开 https://grafana.org.cn/api/plugins/grafana-lokiexplore-app 并查找 links 部分
  2. 找到一个 download url，它看起来像 https://grafana.org.cn/api/plugins/grafana-lokiexplore-app/versions/1.0.2/download
  3. 使用此 URL 下载插件 ZIP 文件，然后可以按照上述方法进行安装。

使用 Grafana Helm Chart 安装插件

使用 Grafana Helm chart，可以通过在 values 文件中使用 plugins 字段，以列表形式添加要安装的插件。有关配置的更多信息，请参阅Helm chart 配置参考。

以下 YAML 代码段安装 Grafana OnCall App 插件的 v1.9.0 版本以及 Redis 数据源插件。你必须将此代码段添加到你的 Helm values 文件中。

yaml 
plugins:
  - https://grafana.org.cn/api/plugins/grafana-oncall-app/versions/v1.9.0/download;grafana-oncall-app
  - redis-datasource

更新完成后，一条确认消息将指示安装成功。

更新插件

更新插件：

  1. 在 Grafana 中，在侧边导航菜单中点击管理 > 插件和数据 > 插件以查看所有插件。
  2. 点击已安装筛选器仅显示已安装的插件。
  3. 点击插件图标。
  4. 点击更新。

更新完成后，一条确认消息将指示安装成功。

卸载插件

卸载插件：

  1. 在 Grafana 中，在侧边导航菜单中点击管理 > 插件和数据 > 插件以查看所有插件。
  2. 点击插件图标。
  3. 点击已安装筛选器仅显示已安装的插件。
  4. 点击卸载。

更新完成后，一条确认消息将指示安装成功。

插件签名

插件签名验证，也称为签名，是一项安全措施，用于确保插件未被篡改。加载时，Grafana 会在检查和验证插件的数字签名时检查插件是否已签名或未签名。

启动时，Grafana 会验证插件目录中每个插件的签名。如果插件未签名，Grafana 将既不加载也不启动它。要查看每个插件的此验证结果，请导航到配置 -> 插件。

Grafana 也会将错误消息写入服务器日志

bash 
WARN[05-26|12:00:00] Some plugin scanning errors were found   errors="plugin '<plugin id>' is unsigned, plugin '<plugin id>' has an invalid signature"

如果你是插件开发者，想了解如何签署你的插件，请参阅签署插件。

签名状态说明
核心内置于 Grafana 中的核心插件。
无效签名插件签名无效。
签名已修改插件自签名后已更改。这可能表示恶意意图。
未签名插件未签名。
已签名插件签名已成功验证。

插件签名级别

所有插件都根据签名级别进行签名。签名级别决定了插件的分发方式。

插件级别说明
私有

私有插件用于你自己的 Grafana。它们不能分发给 Grafana 社区，也不会发布在 Grafana 目录中。

社区

社区插件的依赖技术是开源且非营利的。

社区插件发布在官方 Grafana 目录中，可供 Grafana 社区使用。

商业

商业插件的依赖技术是闭源或有商业支持的。

商业插件发布在官方 Grafana 目录中，可供 Grafana 社区使用。

允许未签名的插件

注意

Grafana Cloud 不支持未签名的插件。

我们强烈建议不要在 Grafana 实例中运行未签名的插件。但是，如果你了解风险并仍然想加载未签名的插件，请参阅配置。

如果你允许加载未签名的插件，Grafana 会将警告消息写入服务器日志

bash 
WARN[06-01|16:45:59] Running an unsigned plugin   pluginID=<plugin id>

注意

如果你正在开发插件，则可以启用开发模式以允许所有未签名的插件。

集成插件

你可以配置 Grafana 实例，让已安装插件的前端可以直接在本地与已安装的其他插件的后端进行通信。默认情况下，你只能远程与插件后端通信。例如，你可以使用此配置启用Canvas 面板调用 actions_allow_post_url 选项允许的应用资源 API。

要启用插件之间的后端通信：

  1. 设置你想要通信的插件。在你的配置文件（根据操作系统不同，可以是 grafana.ini 或 custom.ini）中，移除分号以启用，然后设置以下配置选项：

    actions_allow_post_url=

    这是一个使用 glob 匹配的逗号分隔列表。

    • 允许访问所有具有后端的插件：

      actions_allow_post_url=/api/plugins/*

    • 仅访问一个插件的后端：

      actions_allow_post_url=/api/plugins/<GRAFANA_SPECIAL_APP>

插件前端沙箱

注意

插件前端沙箱目前处于公共预览阶段。Grafana Labs 提供有限支持，在该功能正式发布之前可能会发生破坏性更改。

插件前端沙箱是一项安全功能，它将插件前端代码与主 Grafana 应用程序隔离。启用后，插件在独立的 JavaScript 上下文运行，这提供了多项安全益处：

  • 防止插件修改其指定区域以外的 Grafana 界面部分
  • 阻止插件干扰其他插件的功能
  • 保护 Grafana 核心功能不被插件修改
  • 防止插件修改全局浏览器对象和行为

在前端沙箱内运行的插件应继续正常工作，其预期功能不会有任何明显变化。

启用前端沙箱

前端沙箱功能目前由 pluginsFrontendSandbox 功能标志控制。要启用它，你需要：

  1. 在 Grafana 配置中启用此功能标志。有关启用功能标志的更多信息，请参阅配置功能开关。

  2. 对于自托管的 Grafana 安装，请使用 enable_frontend_sandbox_for_plugins 配置选项将要沙箱化的插件 ID 添加到 security 部分。

对于 Grafana Cloud 用户，你只需使用插件目录页面中的切换开关即可为每个插件启用或禁用沙箱。默认情况下，所有插件的沙箱功能均已禁用。

注意

启用前端沙箱可能会影响某些插件的性能。仅在你完全信任插件并理解其安全隐患的情况下才禁用沙箱。

兼容性

前端沙箱在 Grafana >=11.5 的公共预览版中可用。它兼容所有类型的插件，包括应用插件、面板插件和数据源插件。不支持基于 Angular 的插件。由 Grafana Labs 开发和签名的插件被排除在外，无法进行沙箱化。

何时使用前端沙箱

对于允许用户编写自定义 JavaScript 代码进行数据可视化或操作的插件，我们强烈建议启用前端沙箱。这些插件虽然功能强大，但在你的 Grafana 实例中可能会执行任意 JavaScript 代码。沙箱通过限制此代码可以访问和修改的内容，提供了一层额外的安全保护。

沙箱特别重要的插件示例包括：

  • 允许用户编写自定义 JavaScript 代码的面板插件
  • 来自不受信任来源的插件

故障排除

如果插件在启用前端沙箱后无法正常工作：

  1. 暂时禁用该特定插件的沙箱
  2. 测试插件在没有沙箱的情况下是否正常工作
  3. 如果插件仅在禁用沙箱后才能工作，请在继续使用它之前确保你信任该插件来源，并且没有沙箱保护。
  4. 向插件开发者报告任何与沙箱相关的问题

了解更多