Kibana 自定义插件开发详解（Kibana Plugin Development Guide）

Kibana 自定义插件开发详解（Kibana Plugin Development Guide）

Kibana 支持通过 插件机制（Plugin System） 扩展其功能，允许开发者添加新的页面、可视化组件、API 接口、侧边栏菜单等。这对于企业定制化需求（如内部系统集成、专用分析工具、权限增强等）非常有价值。

本文将从 插件结构、开发环境、实战示例、构建发布、调试技巧 等方面，全面详解 Kibana 插件开发流程。

---

一、Kibana 插件概述

1.1 什么是 Kibana 插件？

Kibana 插件是一个可安装的模块，可以：

• 添加新页面（如 /app/my-plugin）
• 注册新功能（如自定义可视化）
• 扩展 UI（添加按钮、菜单项）
• 提供后端 API（REST 接口）
• 集成第三方服务（如钉钉、企业微信）

✅ 插件运行在 Kibana 进程中，与核心系统深度集成。

---

1.2 插件类型（Kibana 8.x）

类型	说明
UI Plugin	前端插件，提供页面和 UI 组件（最常见）
Server Plugin	后端插件，提供 API 或监听事件
Both	同时包含前端和后端逻辑（推荐方式）

自 Kibana 7.0 起，采用 新插件架构（Plugin Platform），基于 TypeScript 和 React。

---

二、开发准备

2.1 环境要求

工具	版本要求
Node.js	v18.x（与 Kibana 版本匹配）
npm / yarn	最新版
Kibana 源码	建议下载对应版本源码用于开发
Elasticsearch	运行中的实例（用于数据交互）

⚠️ Kibana 插件必须与 Kibana 主版本严格匹配（如 8.11.3 插件不能用于 8.12.0）

---

2.2 获取 Kibana 源码（可选）

# 克隆 Kibana 仓库（以 8.11 分支为例）
git clone https://github.com/elastic/kibana.git
cd kibana
git checkout v8.11.3

# 安装依赖
yarn kbn bootstrap

若仅开发简单插件，也可不下载源码。

---

三、创建自定义插件

3.1 插件目录结构

my_kibana_plugin/
├── kibana.json          # 插件元信息（必填）
├── server/              # 后端逻辑（可选）
│   └── index.ts
├── public/              # 前端逻辑（可选）
│   └── index.ts
├── common/              # 共享代码（可选）
│   └── types.ts
└── package.json         # npm 包信息（可选）

---

3.2 kibana.json（核心配置文件）

{
  "id": "my_plugin",
  "version": "1.0.0",
  "kibanaVersion": "8.11.3",
  "name": "My Custom Plugin",
  "description": "A demo plugin for Kibana",
  "main": "server/index.ts",
  "type": "plugin",
  "server": true,
  "ui": true,
  "requiredPlugins": ["kibana", "elasticsearch"],
  "optionalPlugins": [],
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  }
}

字段	说明
id	插件唯一标识（URL 路径为 /app/id）
kibanaVersion	必须与 Kibana 主版本一致
server / ui	是否启用后端/前端
requiredPlugins	依赖的插件

---

四、实战：开发一个“Hello World”插件

4.1 创建插件目录

cd /path/to/kibana/plugins
mkdir my_plugin
cd my_plugin

创建上述文件结构。

---

4.2 编写前端（public/index.ts）

// public/index.ts
import { AppMountParameters, CoreStart } from '@kbn/core/public';
import React from 'react';
import ReactDOM from 'react-dom/client';

export interface MyPluginSetupPlugins {
  // 依赖插件类型定义
}

export const renderApp = (
  { appBasePath, element }: AppMountParameters,
  core: CoreStart
) => {
  const root = ReactDOM.createRoot(element);

  root.render(
    <div style={{ padding: 20 }}>
      <h1>📘 欢迎使用 My Plugin</h1>
      <p>这是我的第一个 Kibana 插件！</p>
      <p>当前用户: <strong>{core.security?.authc?.getCurrentUser()?.username}</strong></p>
      <button onClick={() => core.notifications.toasts.addSuccess('Hello!')}>
        点我显示通知
      </button>
    </div>
  );

  return () => root.unmount();
};

---

4.3 编写后端（server/index.ts）

// server/index.ts
import { Plugin } from '@kbn/core/server';

export class MyPlugin implements Plugin {
  public setup(core) {
    // 注册插件页面
    core.application.register({
      id: 'my_plugin',
      title: '我的插件',
      order: 5000,
      mount: async (params) => {
        const { renderApp } = await import('./public');
        return renderApp(params, core);
      },
    });

    // 注册自定义 API
    core.http.createRouter('/my_plugin').get(
      { path: '/api/hello', validate: false },
      async (context, request, response) => {
        return response.ok({
          body: {
            message: 'Hello from My Plugin!',
            timestamp: new Date().toISOString(),
          },
        });
      }
    );

    return {};
  }

  public start() {}
  public stop() {}
}

---

4.4 添加 package.json（可选）

{
  "name": "my_plugin",
  "version": "1.0.0",
  "private": true
}

---

五、安装与启动

5.1 将插件放入 Kibana 插件目录

cp -r my_plugin /usr/share/kibana/plugins/

或开发时软链接：

ln -s /path/to/my_plugin /usr/share/kibana/plugins/my_plugin

---

5.2 启动 Kibana

# 方式1：直接启动
/usr/share/kibana/bin/kibana

# 方式2：开发模式（推荐）
yarn start --plugin-path /path/to/my_plugin

开发模式支持热重载，修改代码自动刷新。

---

5.3 访问插件

打开浏览器：

http://localhost:5601/app/my_plugin

你应该看到 “欢迎使用 My Plugin” 页面。

---

六、调用自定义 API

在插件中调用后端接口：

// public/index.ts 中添加
const resp = await core.http.get('/my_plugin/api/hello');
console.log(resp.message); // "Hello from My Plugin!"

---

七、插件功能扩展示例

7.1 添加侧边栏图标

在 setup 中注册应用时添加：

core.application.register({
  id: 'my_plugin',
  title: '我的插件',
  icon: 'logoKibana', // 可选图标
  navLinkStatus: 1,   // 显示在侧边栏
  // ...
});

图标列表：Kibana Icon Catalog

---

7.2 集成 Elasticsearch 查询

// 调用 ES API
const esClient = core.elasticsearch.client.asCurrentUser;
const result = await esClient.search({
  index: 'my-index-*',
  body: { query: { match_all: {} } }
});

---

7.3 添加权限控制

// 检查用户是否有权限
if (!core.application.capabilities.my_plugin?.show) {
  return response.forbidden();
}

需在 kibana.json 中定义功能权限（高级用法）。

---

八、构建与发布

8.1 打包插件（生产部署）

cd /path/to/my_plugin

# 使用 Kibana 提供的工具打包
/path/to/kibana/node_modules/.bin/kibana-plugin-helpers build

# 输出：my_plugin-1.0.0.zip

8.2 安装插件包

bin/kibana-plugin install file:///path/to/my_plugin-1.0.0.zip

会自动解压到 plugins/ 目录。

---

九、调试技巧

技巧	方法
查看日志	tail -f /var/log/kibana/kibana.log
浏览器调试	F12 → Console / Network
启用开发模式	yarn start --oss --no-base-path
使用 console.log	在 server/ 和 public/ 中均可
检查插件加载	Kibana 启动日志中搜索 Plugin "my_plugin" initialized

---

十、最佳实践

1. 命名规范：插件 ID 使用小写字母+下划线（my_org_monitoring）
2. 版本匹配：确保 kibanaVersion 与 Kibana 一致
3. 错误处理：API 返回标准 HTTP 状态码
4. 安全性：
   • 验证输入参数
   • 使用 asCurrentUser 调用 ES
   • 避免暴露敏感信息
5. 文档化：提供 README 说明安装和使用方法

---

十一、常见问题

❓ 插件未加载？

• 检查 kibana.json 格式是否正确
• 检查版本是否匹配
• 查看 Kibana 日志是否有报错

❓ 页面空白？

• 检查 mount 函数是否返回卸载函数
• 检查 React 渲染是否成功

❓ API 404？

• 检查路由前缀是否正确（/my_plugin/api/xxx）
• 确保 core.http.createRouter 正确注册

---

十二、参考资源

• 官方插件开发指南：
  👉 https://www.elastic.co/guide/en/kibana/current/plugin-api.html

• 插件示例仓库：
  👉 https://github.com/elastic/kibana/tree/main/examples

• Kibana UI 组件库（EUI）：
  👉 https://elastic.github.io/eui/

• 插件生成器（社区）：
  👉 generator-kibana-plugin

---

十三、结语

Kibana 插件开发虽然有一定门槛（需熟悉 TypeScript、React、Elastic 架构），但一旦掌握，即可实现：

• 企业级定制仪表盘
• 内部审批流程集成
• 第三方告警通知（钉钉、飞书）
• 数据导出审批系统
• 多租户权限增强

是 Kibana 高级用户和开发者的必备技能。