没有人教你如何构建 Kibana 插件，所以我把所有知识打包了

Source: Dev.to

请提供您希望翻译的具体文本内容，我将为您翻译成简体中文。

没人谈论的问题

尝试在 Google 上搜索 “how to build a Kibana external plugin”。

去吧，我等着。

你会找到：

• Elastic 官方文档（内容稀疏）
• 2018 年的一个已废弃的 Yeoman 生成器
• 少数几篇来自放弃者的 Stack Overflow 帖子

基本上就这么多。

当我在 UNIBERG 开始编写 Kibana 插件时，我的主要学习资源是……阅读 Kibana 的源代码：实际的 Kibana 仓库，超过 20 万个文件。我在其中搜索模式，希望我看到的内部插件是以“正确”的方式实现的，而不是某个尚未清理的旧式 hack。

没有教程，没有课程，没有《Kibana 插件开发入门》之类的东西。只能自己摸索。

这倒也无妨——我其实挺喜欢这种探索的过程。但在摸索了 6 + 年之后，我脑子里（以及散落在大约 40 份 notes.md 文件中的）大量知识本可以帮助别人省去数月的痛苦。

为什么使用 Claude Code 插件？

我已经使用 Claude Code 有一段时间了。一天，我查看插件文档，发现其结构与我熟悉的 Kibana 插件奇怪地相似：

• Manifest 文件
• 目录结构
• 配置

…只是简单得多。Claude Code 插件基本上是：

• 一个 JSON manifest
• 一些用于命令/技能/代理的 markdown 文件

没有编译代码。没有构建步骤。

我的第一个想法：“我可以把整个 Kibana 知识库放进一个 skill 文件，Claude 就会……知道它。”

我的第二个想法：“这根本不可能。”

结果真的可以。

我实际构建的内容

在一个星期六下午开始。原以为只需要几个小时。

实际用了整整两天，加上一周的不断添加，因为我一直在想“哦，还有这个模式”。

插件包含

• 10 条斜杠命令 – 例如

  • /scaffold – 生成完整的插件骨架（server + public + types + manifest）
  • /route – 创建带有正确 @kbn/config-schema 验证的服务器路由
  • /component – 生成基于 EUI 的 React 组件
  • /security – 设置 RBAC
  • …以及其他几项

• 6 个专用代理 – 一个审查插件结构的架构师，一个检查身份验证绕过和数据泄漏的安全审计员，一个用于版本升级的迁移助手，等等。

• 1 个庞大的技能文件 – 大约 400 行凝聚的 Kibana 插件知识：插件生命周期、路由模式、ES 客户端使用、EUI 组件、认证中间件、测试模式、常见陷阱。

这个技能文件是我最自豪的部分（也是耗时最长的部分，因为我一直在说“等等，我忘记了 saved‑object 迁移”，于是又添加了一个章节）。

难以做好之处

路由身份验证模式

这听起来很无聊。确实很无聊。但如果搞错了，就会在租户之间泄露用户数据。我见过这种情况，也曾导致过这种情况。

插件默认在 每个 生成的路由中嵌入安全检查，因为我吃过苦头，知道“以后再加认证”往往会变成“在生产环境中才发现认证 bug”。

每个 /route 命令生成的路由都会以以下代码开头：

const user = security.authc.getCurrentUser(request);
if (!user) return response.forbidden();

很无聊，但我曾因为没有这段代码而留下伤痕。

EUI 组件模式

Elastic UI 大约有 80 + 个组件。有的文档齐全，有的没有，有的属性行为并不像表面看起来的那样。我曾花整整一天时间调试为什么 EuiBasicTable 的分页没有正确渲染——结果是我把 totalItemCount 当 字符串 传入，而它应该是 数字。因为属性类型是 any，TypeScript 并没有捕获到错误。

/component 命令生成的组件已经处理了我曾遇到的各种边缘情况：

• 暗黑模式兼容
• 响应式布局
• 加载状态
• 错误边界

这些是我以前常常忘记、然后在生产环境中补救的内容。

Elasticsearch 客户端集成

Kibana 的 ES 客户端并不等同于普通的 @elastic/elasticsearch 客户端。它被包装过，错误类型不同，认证处理方式也不同，并且在不同的 Kibana 小版本之间会有未必有文档记录的变化。

我在技能中写了一个服务层模式，处理以下事项：

• 类型强制转换
• 错误映射
• 对每个 ES 响应的防御性默认值

这大约有 200 行代码，我不想再看它们，但我构建的每个插件都会复制这段代码。

Source: …

我对一切产生疑问的那一段

把你的专业知识开源有点奇怪：有人可以直接安装这个插件，省去多年的学习。

• 我在一次安全审计中几乎心脏骤停才弄清的认证模式？它们都在里面。
• 那个让我整整浪费了一个星期三的 EUI 暗色模式 bug？已经自动处理。
• 我凌晨 2 点写的 Elasticsearch 响应转换层，因为生产数据的时间戳有三种不同的格式？已经内置在技能里。

我把自己的经验免费送出去，是不是在贬值自己的价值？

也许是。但大概不是。插件可以帮你搭建代码骨架、传授模式，但它不能在星期四晚上 11 点帮你调试具体的生产问题。它也看不出你的数据模型会在 10 万条记录后无法扩展。它也不能坐在会议里向产品经理解释为什么多租户要花三周而不是三天。

工具并不能取代经验。 它们只是让枯燥的部分更快完成。

实际使用时会发生什么

下面是一个真实的例子。你输入：

/scaffold

Claude 会询问你在构建什么。你说 “带 RBAC 的用户管理插件”。

两分钟后，你得到：

• 包含正确 Kibana 版本目标的插件清单
• 带有路由注册的服务器端设置
• 使用 React 的前端应用挂载
• 你的领域的 TypeScript 类型定义
• 带导航的基础 EUI 页面布局
• 包含功能权限的安全配置
• 一个可用的 kibana.jsonc

在有了这个插件之前，这套配置我大约需要 4 小时。我仍然会忘记某些细节——通常是 kibana.jsonc 配置，因为这个文件很容易写错，且调试起来很困难。

仍未完成的内容

老实说，目前还有以下内容未完善：

• 状态管理模式 – 我有自己的看法（使用 React context + 自定义 Hook，而不是 Redux），但尚未把它们正式写成指令。
• 日志与监控 – 生产插件必不可少；我一直拖延，因为这不是有趣的部分。
• 插件间依赖 – Kibana 的依赖注入系统功能强大，却让人困惑。我使用多年，仍然每次都要仔细核对文档。
• 实时数据模式 – 通过 Kibana 实现 WebSocket 式的更新。我已经实现过，但相关模式还不够简洁，尚未形成可复用的模板。

开源焦虑

发布它让我感到不舒服。

不是因为代码——代码本身没问题。而是因为它基本上是我的大脑写进了一个 markdown 文件。每一个模式都是我通过错误学到的。安全代理中的每一个反模式检查都是我造成或捕获的 bug。

• 如果有人发现了问题怎么办？
• 如果在我的使用场景下有效的模式在别人的场景中失效怎么办？
• 如果 Elastic 的工程师看到它说“这不是我们内部的做法”怎么办？

然后…他们会打开一个 issue，我会修复它或学到新东西。

这大概就是重点。

实际使用方法

如果你正在构建 Kibana 插件（或在考虑构建）：

/plugin marketplace add ch-bas/kibana-plugin-helper
/plugin install kibana-plugin-helper@kibana-plugin-helper

然后尝试 /scaffold，看看会发生什么。

如果你没有构建 Kibana 插件——说实话，大多数人也没有——这篇文章实际上是关于别的：将你辛苦获得的知识打包成他人可以使用的东西。

无论你的细分领域是什么，你都有可以帮助他人节省数月时间的模式和经验教训。形式并不重要（插件、博客文章、GitHub 仓库中的 markdown 文件）。关键是把它从你的脑子里拿出来，放到能帮助别人的地方。

我恰好选择了 Claude Code 插件，因为其结构我很熟悉，而且我是一名开发者，所以当然把它过度设计了。

我想了解的

• 如果你在进行 Kibana 插件开发： 第一天你最希望有人告诉你的事情是什么？我可能会把它加进去。
• 如果你曾经开源过你的专长： 这对你的职业有帮助还是有害？我真的很想知道。
• 如果你使用过 Claude Code 插件： 人们真的通过市场发现它们，还是主要靠口口相传？

把你的答案贴出来——我会全部阅读。

GitHub:
License: MIT（随意使用）

Tags: Kibana ElasticStack OpenSource ClaudeCode WebDevelopment React