@grafana/plugin-validator

中文文档
0.53.9发布于 2026/11/16Apache-2.0CommonJS构建来源已验证近 30 天下载 5959

Grafana 插件验证器

中文使用文档
文档目录18 节
  1. 安装和使用
  2. 多克( 建议)
  3. 国家PX
  4. 当地
  5. MCP 服务器( 用于 AI 助手)
  6. 生成本地文件进行校验
  7. 选项
  8. 使用配置文件
  9. 源代码
  10. 支持远程 Git 服务
  11. 调试模式
  12. LLM 提供者配置
  13. 安保工具
  14. 分析器
  15. 产出
  16. 严重性
  17. 获取帮助
  18. 许可证

Grafana 插件验证器

License Go Report Card

此工具有助于加快出版插件的进程 Grafana.com (英语)它运行一系列 分析器 确保插件遵循最佳做法、检查安全和结构问题以及出版方面的具体要求。 对这些要求的概述可参见本文: https://grafana.com/docs/grafana/latest/developers/plugins/出版和签署标准/。 。 。 .

它需要指定远程或本地 ZIP 插件存档的路径, 例如 :

  • 远程数字 : https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
  • 当地数字 : file://Users/me/Downloads/grafana-clock-panel-2.1.2.zip

你们可以 额外 为工程提供源代码链接 -sourceCodeUri 以启用诸如 " 脆弱性扫描 " 等额外分析器.

安装和使用

确保您的 Go 版本符合 go.mod 避免相容性问题的文件

使用 Docker 图像来运行工具很容易,因为它包含所有 安全扫描工具 全套分析器需要 - 所以你不需要在你的系统中安装这些额外的工具.

docker run --pull=always grafana/plugin-validator-cli [options] [http://yourdomain/plugin_archive.zip]

例1(基础)

docker run --pull=always grafana/plugin-validator-cli https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip

例2(具体说明源代码位置)

docker run --pull=always grafana/plugin-validator-cli -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip

使用带有 Docker 的本地归档文件

要使用本地归档来运行工具, 您需要挂载它作为嵌入器的分量 。 举个例子:

docker run --pull=always -v /path/to/plugin_archive.zip:/archive.zip grafana/plugin-validator-cli /archive.zip

[注] 如果使用相对路径, 您的路径必须从 ./

使用本地归档文件和本地源代码

docker run --pull=always -v /path/to/plugin_archive.zip:/archive.zip -v /path/to/source_code:/source_code grafana/plugin-validator-cli -sourceCodeUri file:///source_code /archive.zip

[注] 如果使用相对路径, 您的路径必须从 ./

国家PX

npx -y @grafana/plugin-validator@latest -sourceCodeUri [options] [path/to/plugin_archive.zip]

当地

首先, 您必须编译并安装 :

git clone [email protected]:grafana/plugin-validator.git
cd plugin-validator/pkg/cmd/plugincheck2
go install

然后您可以运行此工具 :

plugincheck2 -sourceCodeUri [source_code_location/] [plugin_archive.zip]

MCP 服务器( 用于 AI 助手)

插件验证器可以用作MCP(模式上下文协议)服务器,允许克洛德,克莱恩等AI助手,以及其他MCP相容工具验证Grafana插件.

见 MCP 服务器读取器 用于配置指令.

生成本地文件进行校验

你必须创建一个 .zip 包含 dist/ 目录但命名为您的插件 ID :

PLUGIN_ID=$(grep '"id"' < src/plugin.json | sed -E 's/.*"id" *: *"(.*)".*/\1/')
cp -r dist "${PLUGIN_ID}"
zip -qr "${PLUGIN_ID}.zip" "${PLUGIN_ID}"
npx @grafana/plugin-validator@latest -sourceCodeUri file://. "${PLUGIN_ID}.zip"

您可以选择删除生成的文件 :

rm -r "${PLUGIN_ID}" "${PLUGIN_ID}.zip"

选项

其他选项可以传递给工具 :

❯ plugincheck2 -help
Usage plugincheck2:
  -config string (optional)
        Path to configuration file
  -sourceCodeUri string (optional)
        URI to the source code of the plugin. If set, the source code will be downloaded and analyzed. This can be a ZIP file URL, a URL to git repository or a local file (starting with `file://`)
  -strict (optional)
        If set, plugincheck returns non-zero exit code for warnings
  -checksum string (optional)
        If set, the checksum of the plugin archive will be checked against this value. MD5 and SHA256 are supported.
  -analyzer string (optional)
        If set, only an specific analyzer and it's dependencies will run.
  -severity string (optional)
        If used, it will set the severity of the analyzer (it has the highest priority).

使用配置文件

您可以用 : -config 选项。 这里可以使用几个配置示例: https://github.com/grafana/plugin-validator/tree/main/config 页面存档备份,存于互联网档案馆。 。 。 .

通过配置使分析器能够和丧失功能

如果您想要禁用特定检查( analyzer), 您可以在您的 配置文件,添加一个 analyzers 区域,并指定哪个分析或分析规则以启用和禁用.

例如,禁用 version 分析器 :

global:
  enabled: true
  jsonOutput: false
  reportAll: false

analyzers:
  version:
    enabled: false

您也可以禁用特定规则或改变其严重程度 :

global:
  enabled: true
  jsonOutput: false
  reportAll: false

analyzers:
  readme:
    rules:
      missing-readme:
        enabled: true
        severity: warning

临界值可以是: error, (中文(简体) ), warning,或 ok。 。 。 .

有些规则默认被禁用, 仅在分析器或规则配置设置时运行 enabled: true。 。 。 .

注意:Grafana Labs对插件提交执行自己的配置,而您自己的配置文件无法改变这些规则.

从分析器或规则中排除插件

也可以将特定插件排除在分析器或分析器内部的特定规则之外. 当特定检查不适用于您的插件时,此功能是有用的 .

要禁用插件的全部分析器,请添加 exceptions 列表中包含插件 ID.

analyzers:
  some-analyzer:
    enabled: true
    # This entire analyzer will be skipped for 'my-plugin-id'
    exceptions:
      - my-plugin-id

要禁用插件的单一规则,请添加 exceptions 列表到规则的配置.

analyzers:
  some-analyzer:
    rules:
      some-rule:
        enabled: true
        # This rule will be skipped for 'my-plugin-id'
        exceptions:
          - my-plugin-id

源代码

您可以用 : -sourceCodeUri 选项。 这样做可以增加 分析器 以进行更完整的扫描.

支持远程 Git 服务

以下内容: 公开 支持 Git 服务 :

  • GitHub 图像
  • 吉特拉布语Name
  • 键盘

目前不支持私人寄存器 .

确保包括 ref 对应源代码的(分支或标记).

例如: 您正在验证版本 v2.1.2 你的项目在GitHub 确保您创建相应的标签或分支并使用 URL https://github.com/grafana/clock-panel/tree/v2.1.2。 。 。 .

调试模式

您可以在调试模式下运行验证器,以获取更多关于运行中的检查和可能出错的信息.

嵌入器 :

docker run --pull=always -e DEBUG=1 grafana/plugin-validator-cli -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip

NPX : (英语)

DEBUG=1 npx -y @grafana/plugin-validator@latest -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip

当地:

DEBUG=1 plugincheck2 -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip

LLM 提供者配置

这个 llmreview 财务报告和审定财务报表 codediff 分析者使用LLM来审查插件源代码. 支持三个提供者: 安东尼, (中文(简体) ), 开放AI,以及 谷歌( 格米尼 )。 。 。 .

设置以下环境变量之一,以允许基于LLM的分析. 使用的是第一个发现的密钥(顺序如下):

环境变量提供者默认模式
ANTHROPIC_API_KEY安东尼claude-opus-4-6
OPENAI_API_KEY开放AIgpt-5.4
GEMINI_API_KEY谷歌gemini-3.1-flash-lite-preview

示例

ANTHROPIC_API_KEY=sk-ant-... plugincheck2 -sourceCodeUri https://github.com/org/repo/tree/v1.0.0 plugin.zip

您可以跳过单个 LLM 分析器 SKIP_LLM_REVIEW=1 或者说 SKIP_LLM_CODEDIFF=1。 。 。 .

安保工具

此校验器使用下列开源安全工具:

如果您在本地运行或通过 NPX 运行验证器, 您可以在您的系统中安装这些工具, 让它们成为您验证检查的一部分 .


分析器

该工具运行了一系列分析器,以确保提交的插件遵循了最佳做法,并加快批准出版插件的过程,详情见下表. 这个 分析器 栏中包含更改给定检查行为所需的名称 配置文件编辑 依赖关系 栏中指定分析器是否要求提供插件的源代码 sourceCodeUri 或任何额外的 安全扫描工具 将在场.

分析器说明依赖关系
归档名称 / archivename档案名称应当正确格式化.无
存档结构 / archive确保zip文件的内容具有预期布局.无
后端二进制 / backendbinary验证二进制文件的存在与插件.json声明是否一致,用于后端或提醒.无
后端调试 / backenddebug检查后端插件的独立调试文件是否不存在 .无
二进制权限 / binarypermissions对于带有二进制的数据源和应用程序,这保证了插件在被提取到一个系统中时能够运行.无
断开链接 / brokenlinks检测到是否有URL无法解析到有效位置.无
构建标记 / buildtags检查 对不允许的构建标记, 选择后端可执行文件 .无
构建工具 / buildtools检查插件是否使用Grafana的标准创建-插件构建工具.无
变化日志( 存在) / changelog确保 CHANGELOG.md 文件存在于zip文件中.无
校验和 / checksum验证所通过校验和( 作为验证器 arg) 是从归档文件中计算出来的 .checksum
循环依赖/ circulardependencies确保插件之间没有任何循环依赖关系( Q)plugin.json, (中文(简体) ), dependencies.plugins 页:1.无
代码 Diff / codediffAnthropic(ANTHROPIC API KEY),OpenAI(OPENAI API KEY),或Google(GEMINI API KEY)之一的API密钥
守则规则/ code-rules检查禁止访问环境变量,文件系统或使用syscall模块.链条, (中文(简体) ), sourceCodeUri
开发者 Jargon / jargon一般来说,不鼓励在文档中使用密码术语.无
可发现性/ discoverability关于目录中用于插件索引的缺失关键词和描述的警告.无
显示/ go-manifest验证建筑清单.无
安全检查器 / go-sec通过扫描"去AST"来检查安全问题的源代码.目标, (中文(简体) ), sourceCodeUri
脆弱性检查器/ govulncheck扫描 为已知弱点去后端源和插件后端二进制(govulncheck).govuln 检查, (中文(简体) ), sourceCodeUri 用于源扫描
联合来文来源图/ jsMap需要检查 module.js.map 存档中的文件.sourceCodeUri
格拉法纳工具包的使用/ legacybuilder检测使用支持时间不长的Grafana工具包.无
遗产平台/ legacyplatform检测到使用角质被腐烂.无
许可证类型 / license请检查date=中的日期值 (帮助) BSD, MIT, Apache 2.0, LGPL3, GPL3, AGPL3.无
LLM 语言 审查/ llmreview通过 LLM 运行代码以检查安全问题或不允许的使用 .Anthropic(ANTHROPIC API KEY),OpenAI(OPENAI API KEY),或Google(GEMINI API KEY)之一的API密钥
标记 / logos检测插件是否包含要显示在插件目录中的大小标识 .无
说明(签署)/ manifest当一个插件签名时, zip 文件将包含一个签名 MANIFEST.txt 文档.无
元数据 / metadata检查一下 plugin.json 存在且有效.无
元数据Grafana依赖性/ grafanadependency请检查date=中的日期值 (帮助) Grafana Dependency in plugin.json 无效.无
元数据路径 / metadatapaths确保所有路径都有效,且引用的图像存在.无
元数据有效性 / metadatavalid确保元数据有效并匹配插件计划 .无
模块.js(性别)/ modulejs所有插件都需要一个 module.js 将被装入.无
巢穴包括元数据 / includesnested验证嵌入插件有正确的元数据 .无
嵌入元数据 / nestedmetadata递归检查所有 plugin.json 已存在且有效.无
无跟踪脚本 / trackingscripts检测到是否有已知的跟踪脚本,这些脚本是不允许的.无
组织(存在)/ org验证插件 ID 中指定的 org 存在 .无
软件包.json / packagejson确保软件包.json存在,版本与插件.json匹配无
插件文档 / plugindocs运行 @grafana/plugin-docs-cli validate --dist 命令以检查归档中包含的多页文档(仅用于设置的插件) docsPath 内 plugin.json) (中文(简体) ).node, (中文(简体) ), npx
插件 名称格式 / pluginname验证所用的插件 ID 符合我们的命名惯例 .无
证明证明 / provenance如果插件是用管道支持出处的证明(例如:Github Actions)来建造,则验证出处证明.无
发表/ published-plugin检测 Grafana 插件目录中是否存在此插件的任何版本 .无
反应 19 兼容性 / reactcompat检测使用 React API 在 React 19 中被移除或贬值 .npx 数据
读取(性别)/ readme确保 README.md 文件存在于zip文件中.无
需要链接 / requiredlinks检查一下 plugin.json 拥有有效的 https URL 的许可证、 隐私政策和支持链接。 默认禁用 .无
限制性依赖性/ restrictivedep指定与此版本插件配合的 Grafana 版本的有效范围.无
安全链接 / safelinks检查链接从 plugin.json 这是安全的.无
截图 / screenshots屏幕截图在 plugin.json 用于 Grafana 插件目录.无
SDK 使用量 / sdkusage确保 grafana-plugin-sdk-go 是最新的.无
签署/ signature确保插件有有效的签名 .无
源代码 / sourcecode在zip文件与源代码之间进行比较,以确保所放出的内容与与之相匹配的回波相匹配.sourceCodeUri
类型后缀(平面/app/数据源) / typesuffix确保插件具有指定的有效类型.无
独一无二的读取ME.md / templatereadme确保插件不会从中重新使用模板 create-plugin 工具.无
不安全的 SVG / unsafesvg检查是否有基于元素和属性的白名单的 svg 文件是安全的 .无
版本数 / version确保提交的版本比当前已发布的插件更新 。 如果这是新/ 未发布的插件, 则跳过 .无
病毒扫描/ virusscan在插件归档和源代码上运行病毒扫描 clamscan (单位:千美元)clamav) (中文(简体) ).蛤丝
扫描仪/ osv-scanner检测 Go 模块和纱锁文件中的关键弱点 .osv 扫描器, (中文(简体) ), sourceCodeUri

产出

默认情况下,该工具输出产生如下所示的纯文本.

默认 :

warning: README.md: possible broken link: https://www.d3js.org (404 Not Found)
detail: README.md might contain broken links. Check that all links are valid and publicly accessible.
warning: README.md contains developer jargon: (yarn)
detail: Move any developer and contributor documentation to a separate file and link to it from the README.md. For example, CONTRIBUTING.md, DEVELOPMENT.md, etc.
error: osv-scanner detected a critical severity issue
detail: SEVERITY: CRITICAL in package immer, vulnerable to CVE-2021-23436
error: osv-scanner detected a critical severity issue
detail: SEVERITY: CRITICAL in package json-schema, vulnerable to CVE-2021-3918
error: Plugin version 0.0.9 is invalid.
detail: The submitted plugin version 0.0.9 is not greater than the latest published version 0.0.9 on grafana.com.

这可以通过通过一个配置文件(包括:

global:
  jsonOutput: true

输出结果类似于:

{
  "id": "briangann-gauge-panel",
  "version": "0.0.9",
  "plugin-validator": {
    "brokenlinks": [
      {
        "Severity": "warning",
        "Title": "README.md: possible broken link: https://www.d3js.org (404 Not Found)",
        "Detail": "README.md might contain broken links. Check that all links are valid and publicly accessible.",
        "Name": "broken-link"
      }
    ],
    "jargon": [
      {
        "Severity": "warning",
        "Title": "README.md contains developer jargon: (yarn)",
        "Detail": "Move any developer and contributor documentation to a separate file and link to it from the README.md. For example, CONTRIBUTING.md, DEVELOPMENT.md, etc.",
        "Name": "developer-jargon"
      }
    ],
    "osv-scanner": [
      {
        "Severity": "error",
        "Title": "osv-scanner detected a critical severity issue",
        "Detail": "SEVERITY: CRITICAL in package immer, vulnerable to CVE-2021-23436",
        "Name": "osv-scanner-critical-severity-vulnerabilities-detected"
      },
      {
        "Severity": "error",
        "Title": "osv-scanner detected a critical severity issue",
        "Detail": "SEVERITY: CRITICAL in package json-schema, vulnerable to CVE-2021-3918",
        "Name": "osv-scanner-critical-severity-vulnerabilities-detected"
      },
    ],
    "version": [
      {
        "Severity": "error",
        "Title": "Plugin version 0.0.9 is invalid.",
        "Detail": "The submitted plugin version 0.0.9 is not greater than the latest published version 0.0.9 on grafana.com.",
        "Name": "wrong-plugin-version"
      }
    ]
  }
}

严重性

默认情况下,该工具将显示分析器产生的任何警告或出错级别结果. 要看到包括成功在内的所有结果,您可以通过一个配置文件,其中包括:

global:
  reportAll: true

获取帮助

许可证

Grafana 插件校验器在 Apache 2.0 许可证。 。 。 .

版本与发布记录

@grafana/plugin-validator 共发布 137 个版本,首次发布于 2023/03/01;过去 12 个月发布了 69 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.53.9latest2026/11/16今天
0.53.62026/11/115 天前
0.53.52026/11/097 天前
0.53.42026/11/097 天前
0.53.32026/11/0413 天前
0.53.22026/11/0313 天前

关于 @grafana/plugin-validator 的常见问题

@grafana/plugin-validator 是什么?

Grafana 插件验证器

如何安装 @grafana/plugin-validator?

在项目目录运行 npm install @grafana/plugin-validator,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 plugin-validator,可以用 npx plugin-validator 直接运行。

@grafana/plugin-validator 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/grafana__plugin-validator 是否存在。

@grafana/plugin-validator 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@grafana/plugin-validator 可以商用吗?

@grafana/plugin-validator 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/plugin-validator 的下载量有多少?

根据 npm 官方下载统计,@grafana/plugin-validator 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,959 次,日均约 199 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/plugin-validator 还在维护吗?

最新版本 0.53.9 发布于 2026/11/16(今天);至今共发布 137 个版本,其中过去 12 个月发布了 69 个;首次发布于 2023/03/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。