开始使用
欢迎来到 Grafana 插件创建的世界,在这里您可以增强 Grafana 的基础功能。 在本指南中,您将学习如何开始,包括搭建插件、在高效的开发环境中运行它以及使用其基本功能。
观看我们的入门视频,观看关于开始使用您的第一个 Grafana 插件的分步指南。 这个可视化教程补充了下面的详细说明,并提供实用的见解,以帮助您一路前行。
快速开始
使用单个命令搭建新插件! 运行以下命令并回答提示
- npm
- Yarn
- pnpm
npx @grafana/create-plugin@latest
yarn dlx @grafana/create-plugin@latest
pnpm dlx @grafana/create-plugin@latest
为什么要创建 Grafana 插件?
Grafana 插件开发允许您创建多种不同的用户体验。 例如,您可以制作
- 面板插件 - 可视化数据的新方法
- 数据源插件 - 连接到新数据库或其他数据源
- 应用插件 - 集成的开箱即用体验
如果这是您第一次创建插件,我们建议您熟悉插件类型、后端插件、数据帧和其他基本要素的基础知识。 了解更多关于 Grafana 插件开发的主要概念。
Grafana 插件的分类
我们建议您熟悉 Grafana 插件的标志性分类,例如私有插件和公共插件之间的区别。 请注意,如果您想将与商业产品相关的插件发布到官方 Grafana 目录,通常需要付费订阅。 了解更多关于 我们的插件政策。
使用插件工具更快地开发您的插件
Grafana 的插件工具提供了一种官方支持的方式来扩展 Grafana 的核心功能。 我们设计这些工具旨在帮助您使用现代化的构建设置更快地开发插件,而无需额外的配置。
插件工具包含两个软件包
create-plugin
:一个 CLI,用于搭建新插件或迁移使用@grafana/toolkit
创建的插件。sign-plugin
:一个 CLI,用于对插件进行签名以进行分发。
如果您之前使用 @grafana/toolkit
构建过插件,则可以使用我们的插件工具跳转到我们的最新工具。 有关更多信息,请参阅 从 toolkit 迁移。
开始之前
请确保您正在使用受支持的操作系统、Grafana 版本和工具。
受支持的操作系统
Grafana 插件工具适用于以下操作系统
- Linux
- macOS
- 带有 WSL(Windows Subsystem for Linux)的 Windows 10+
受支持的 Grafana 版本
我们通常建议您为 v10.0 以后的 Grafana 版本构建。 有关使用 Grafana 进行开发时的要求和依赖关系的更多信息,请参阅 Grafana 开发者指南。
推荐工具
您需要设置以下工具
受支持的包管理器
当您第一次运行 @grafana/create-plugin
时,请选择您的包管理器:npm
、pnpm
或 yarn
。
::: note 本网站上的 Yarn 命令与 Yarn Berry (>=2.0.0) 兼容。 如果您正在使用 Yarn 1.x.x,我们建议您升级到 Yarn Berry。 或者,您可以使用 yarn create @grafana/plugin
以使用 Yarn 1.x.x 运行命令。 ::
搭建插件
运行 create-plugin
工具
运行以下命令并回答提示
- npm
- Yarn
- pnpm
npx @grafana/create-plugin@latest
yarn dlx @grafana/create-plugin@latest
pnpm dlx @grafana/create-plugin@latest
如需提示方面的帮助,请参阅 CLI 命令。
打开生成的文件夹结构
打开插件文件夹以浏览生成的插件
目录名称 <orgName>-<pluginName>-<pluginType>
基于您对提示的回答。 出现提示时,请使用生成的文件夹的名称。 此目录包含启动插件开发的初始项目结构。
文件结构应如下所示
<orgName>-<pluginName>-<pluginType>
├── .config/
├── .eslintrc
├── .github
│ └── workflows
├── .gitignore
├── .nvmrc
├── .prettierrc.js
├── CHANGELOG.md
├── LICENSE
├── Magefile.go
├── README.md
├── cypress
│ └── integration
├── docker-compose.yaml
├── go.mod
├── go.sum
├── jest-setup.js
├── jest.config.js
├── node_modules
├── package.json
├── pkg
│ ├── main.go
│ └── plugin
├── src
│ ├── README.md
│ ├── components
│ ├── datasource.ts
│ ├── img
│ ├── module.ts
│ ├── plugin.json
│ └── types.ts
└── tsconfig.json
有关这些文件的更多信息,请参阅 插件的结构。
在 Docker 中构建和运行您的插件
使用 create-plugin
工具,您可以使用 Docker 容器来简化配置、加载和开发过程。 有关更多信息,请参阅 设置开发环境。
请参阅新插件搭建之后的“下一步”终端输出,以安装依赖项、构建和运行您的插件。
示例输出
## What's next?
Run the following commands to get started:
* cd ./orgName-pluginName-app
* npm install to install frontend dependencies.
* npm exec playwright install chromium to install e2e test dependencies.
* npm run dev to build (and watch) the plugin frontend code.
* mage -v build:backend to build the plugin backend code. Rerun this command every time you edit your backend files.
* docker compose up to start a grafana development server.
* Open https://127.0.0.1:3000 in your browser to create a dashboard to begin developing your plugin.
Note: We strongly recommend creating a new Git repository by running git init in ./org-pluginname-app before continuing.
* Learn more about Grafana Plugin Development at https://grafana.org.cn/developers/plugin-tools
安装依赖项
- npm
- Yarn
- pnpm
cd <orgName>-<pluginName>-<pluginType>
npm install
cd <orgName>-<pluginName>-<pluginType>
yarn install
cd <orgName>-<pluginName>-<pluginType>
pnpm install
构建前端
要在开发中以监视模式构建插件,持续监视更改,请运行
- npm
- Yarn
- pnpm
npm run dev
yarn dev
pnpm run dev
要为生产环境构建,请运行
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build
构建后端
如果您的插件包含 后端 组件,您可以使用 mage 进行构建
mage -v build:linux
构建目标
选项 | 描述 | 示例 |
---|---|---|
build:[arch] | 为特定架构构建二进制文件。 | mage -v build:Linux |
列出所有可用的 Mage 目标以获取其他命令
mage -l
运行 Grafana 服务器
要使用 Docker 启动 Grafana 开发服务器,请运行
docker compose up --build
恭喜! 您刚刚搭建了您的第一个插件,现在可以在 https://127.0.0.1:3000 访问它。