› › ›

配置服务

配置服务编辑

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`	`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 服务 »