› › ›

配置服务

Kibana 为希望支持其插件可调整运行时行为的插件开发者提供了 ConfigService。插件只能读取自己的配置值，无法直接访问 Kibana Core 或其他插件的配置值。

配置服务仅在服务端可用。

// in Legacy platform
const basePath = config.get('server.basePath');
// in Kibana Platform 'basePath' belongs to the http service
const basePath = core.http.basePath.get(request);

要访问您的插件配置，您应该

在您的插件定义中声明插件特定的 configPath（如果未指定，则会回退到插件 id）。
从插件的主文件导出配置的架构验证。架构是强制性的。如果插件在没有架构声明的情况下读取配置，ConfigService 将抛出错误。

my_plugin/server/index.ts

import { schema, TypeOf } from '@kbn/config-schema';
export const plugin = …
export const config = {
  schema: schema.object(…),
};
export type MyPluginConfigType = TypeOf<typeof config.schema>;

读取通过 PluginInitializerContext 公开的配置值

my_plugin/server/plugin.ts

import type { PluginInitializerContext } from '@kbn/core/server';
export class MyPlugin {
  constructor(initializerContext: PluginInitializerContext) {
    this.config$ = initializerContext.config.create<MyPluginConfigType>();
    // or if config is optional:
    this.config$ = initializerContext.config.createIfExists<MyPluginConfigType>();
  }
  ...
}

如果您的插件也有客户端部分，您还可以使用配置的 exposeToBrowser 允许列表属性将其配置属性公开给客户端。

my_plugin/server/index.ts

import { schema, TypeOf } from '@kbn/config-schema';
import type { PluginConfigDescriptor } from '@kbn/core/server';

const configSchema = schema.object({
  secret: schema.string({ defaultValue: 'Only on server' }),
  uiProp: schema.string({ defaultValue: 'Accessible from client' }),
});

type ConfigType = TypeOf<typeof configSchema>;

export const config: PluginConfigDescriptor<ConfigType> = {
  exposeToBrowser: {
    uiProp: true,
  },
  schema: configSchema,
};

仅包含公开属性的配置将通过插件的 initializerContext 在客户端可用。

my_plugin/public/index.ts

interface ClientConfigType {
  uiProp: string;
}

export class MyPlugin implements Plugin<PluginSetup, PluginStart> {
  constructor(private readonly initializerContext: PluginInitializerContext) {}

  public async setup(core: CoreSetup, deps: {}) {
    const config = this.initializerContext.config.get<ClientConfigType>();
  }

默认情况下，所有插件都被认为是启用的。如果您想禁用您的插件，可以在插件配置中声明 enabled 标志。这是一个特殊的 Kibana 平台键。Kibana 读取其值，如果 enabled: false，则不会创建插件实例。

export const config = {
  schema: schema.object({ enabled: schema.boolean({ defaultValue: false }) }),
};

处理插件配置弃用

编辑

如果您的插件具有已弃用的配置键，您可以使用 deprecations 配置描述符字段来描述它们。弃用是按插件管理的，这意味着您不需要指定整个属性路径，而是使用相对于插件配置根的相对路径。

my_plugin/server/index.ts

import { schema, TypeOf } from '@kbn/config-schema';
import type { PluginConfigDescriptor } from '@kbn/core/server';

const configSchema = schema.object({
  newProperty: schema.string({ defaultValue: 'Some string' }),
});

type ConfigType = TypeOf<typeof configSchema>;

export const config: PluginConfigDescriptor<ConfigType> = {
  schema: configSchema,
  deprecations: ({ rename, unused }) => [
    rename('oldProperty', 'newProperty'),
    unused('someUnusedProperty'),
  ],
};

在某些情况下，访问整个配置以进行弃用是必要的。对于这些边缘情况，在声明弃用时也可以访问 renameFromRoot 和 unusedFromRoot。

my_plugin/server/index.ts

export const config: PluginConfigDescriptor<ConfigType> = {
  schema: configSchema,
  deprecations: ({ renameFromRoot, unusedFromRoot }) => [
    renameFromRoot('oldplugin.property', 'myplugin.property'),
    unusedFromRoot('oldplugin.deprecated'),
  ],
};

根据上下文引用验证您的配置

编辑

某些功能在不同的模式（dev/prod/dist，甚至无服务器）下运行时需要特殊的配置。为此，核心在验证的上下文中注入以下引用

上下文引用	潜在值	描述
`dev`	`true`\|`false`	Kibana 是否在开发模式下运行？
`prod`	`true`\|`false`	Kibana 是否在生产模式下运行（从二进制文件运行）？
`dist`	`true`\|`false`	Kibana 是否从可分发的构建版本运行（不是从源代码运行）？
`serverless`	`true`\|`false`	Kibana 是否在无服务器产品中运行？
`version`	`8.9.0`	当前 Kibana 的版本
`buildNum`	`12345`	构建编号
`branch`	`main`	当前运行的分支
`buildSha`	`12345`	构建 SHA（通常指最后一次提交的 SHA）
`buildDate`	`2023-05-15T23:12:09+0000`	构建的 ISO 8601 日期

要在配置验证架构中使用上面列出的任何引用，可以通过 schema.contextRef('{CONTEXT_REFERENCE}') 来访问它们。

export const config = {
  schema: schema.object({
    // Enabled by default in Dev mode
    enabled: schema.boolean({ defaultValue: schema.contextRef('dev') }),

    // Setting only allowed in the Serverless offering
    plansForWorldPeace: schema.conditional(
      schema.contextRef('serverless'),
      true,
      schema.string({ defaultValue: 'Free hugs' }),
      schema.never()
    ),
  }),
};

对于无服务器与传统配置，建议使用 offeringBasedSchema 辅助函数

import { schema, offeringBasedSchema } from '@kbn/config-schema'

export const config = {
  schema: schema.object({
    // Enabled by default in Dev mode
    enabled: schema.boolean({ defaultValue: schema.contextRef('dev') }),

    // Setting only allowed in the Serverless offering
    plansForWorldPeace: offeringBasedSchema({
      serverless: schema.string({ defaultValue: 'Free hugs' }),
    }),
  }),
};

« 应用服务 Elasticsearch 服务 »