搜索引擎

Backstage 默认支持 3 个搜索引擎，分别是名为 Lunr 的内存引擎、Elasticsearch 和 Postgres。 你可以通过实现所提供的接口来配置自己的搜索引擎，如在搜索后端文档。

所提供的搜索引擎实现有自己的查询构造方法，这可能是你想要修改的地方。 通过提供你自己的 QueryTranslator 接口实现，就可以修改搜索引擎的查询逻辑。 通过使用公开的 setter 将修改后的查询翻译器设置到实例中，就可以在不接触所提供的搜索引擎的情况下完成这种修改。

const searchEngine = new LunrSearchEngine({ logger: env.logger });
searchEngine.setTranslator(new MyNewAndBetterQueryTranslator());

Lunr

如果您没有对脚手架应用程序进行其他更改，Lunr 搜索引擎将默认在Backstage实例中启用。

Lunr 可以这样实例化：

// app/backend/src/plugins/search.ts
const searchEngine = new LunrSearchEngine({ logger: env.logger });
const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });

注意：在本地开发 > Backstage 的其他部分时，Lunr 适合作为零配置搜索引擎，但在 > 生产中运行 Backstage 时，强烈建议不要使用它。 部署 Backstage 时，请使用 > 其他搜索引擎之一。

Postgres

基于 Postgres 的搜索引擎只需要将 postgres 配置为 Backstage 的数据库引擎即可，因此它的目标用户是那些希望避免维护 Elasticsearch 等其他外部服务的用户。 搜索可提供不错的结果，并在索引文档数以万计的情况下表现出色。 与 postgres 的连接是通过数据库管理器建立的，其他插件也在使用该管理器。

重要：搜索插件至少需要 Postgres 12！

要使用PgSearchEngine请确保配置了 Postgres 数据库，并对后端进行以下更改：

1.在后端的package.json中添加对@backstage/plugin-search-backend-module-pg的依赖。 2.初始化搜索引擎。 如果在本地使用 SQLite 运行 Backstage for development，建议使用回退到 lunr 搜索引擎进行初始化：

// In packages/backend/src/plugins/search.ts

// Initialize a connection to a search engine.
const searchEngine = (await PgSearchEngine.supported(env.database))
  ? await PgSearchEngine.fromConfig(env.config, { database: env.database })
  : new LunrSearchEngine({ logger: env.logger });

可选配置

以下是使用 Postgres 作为搜索后端时可应用的可选配置示例。 目前，这主要只针对高亮功能：

search:
  pg:
    highlightOptions:
      useHighlight: true # Used to enable to disable the highlight feature. The default value is true
      maxWord: 35 # Used to set the longest headlines to output. The default value is 35.
      minWord: 15 # Used to set the shortest headlines to output. The default value is 15.
      shortWord: 3 # Words of this length or less will be dropped at the start and end of a headline, unless they are query terms. The default value of three (3) eliminates common English articles.
      highlightAll: false # If true the whole document will be used as the headline, ignoring the preceding three parameters. The default is false.
      maxFragments: 0 # Maximum number of text fragments to display. The default value of zero selects a non-fragment-based headline generation method. A value greater than zero selects fragment-based headline generation (see the linked documentation above for more details).
      fragmentDelimiter: ' ... ' # Delimiter string used to concatenate fragments. Defaults to " ... ".

**注：**高亮搜索词功能使用ts_headline如果出现问题，只需进行最基本的配置即可禁用它：

search:
  pg:
    highlightOptions:
      useHighlight: false

的 Postgres 文档突出显示结果有更多详细信息。

Elasticsearch

Backstage 支持 Elasticsearch(和 OpenSearch)搜索引擎连接、索引和查询。 可用的配置选项可以使用 AWS 或 Elastic.co 托管解决方案，或自定义自托管解决方案。

与上述 Lunr 类似，Elasticsearch 也可以这样设置：

// app/backend/src/plugins/search.ts
const searchEngine = await ElasticSearchSearchEngine.fromConfig({
  logger: env.logger,
  config: env.config,
});
const indexBuilder = new IndexBuilder({ logger: env.logger, searchEngine });

要使引擎可用，您的后端软件包需要依赖于软件包@backstage/plugin-search-backend-module-elasticsearch.

在您的实例中使用 Elasticsearch 之前，还需要进行一些额外的配置。 配置选项在配置模式定义文件。

底层功能使用官方 Elasticsearch 客户端 7.x 版本(这意味着 Elasticsearch 版本 7 是唯一确认支持的版本)，或者 OpenSearch 客户端，当aws或opensearch提供商已配置。

如果您需要创建自己的定制搜索体验，而不仅仅需要一个查询翻译器(如分面搜索或中继分页)，您可以访问搜索引擎的配置，以创建新的 Elasticsearch 客户端。 客户端的版本不必与 Elasticsearch 引擎插件内部使用的版本相同。 例如，您可以使用 Elasticsearch 客户端的配置，创建新的 Elasticsearch 客户端：

import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module-elasticsearch';
import { Client as ElasticClient } from '@elastic/elasticsearch';
import { Client as OpenSearchClient } from '@opensearch-project/opensearch';

// Return an Elasticsearch client
const esClient = searchEngine.newClient<ElasticClient>(options => {
  if (!isOpenSearchCompatible(options)) {
    return new ElasticClient(options);
  }

  throw new Error('Incompatible options');
});

// Return an OpenSearch client
const osClient = searchEngine.newClient<OpenSearchClient>(options => {
  if (isOpenSearchCompatible(options)) {
    return new OpenSearchClient(options);
  }

  throw new Error('Incompatible options');
});

设置自定义索引模板

如果需要，Elasticsearch 引擎可为您提供设置自定义索引模板的功能。

索引模板定义了可自动应用于新索引的设置、映射和别名。

// app/backend/src/plugins/search.ts
const searchEngine = await ElasticSearchSearchEngine.initialize({
  logger: env.logger,
  config: env.config,
});

searchEngine.setIndexTemplate({
  name: '<name-of-your-custom-template>',
  body: {
    index_patterns: ['<your-index-pattern>'],
    template: {
      mappings: {},
      settings: {},
    },
  },
});

配置示例

AWS

使用 AWS 托管的 Elasticsearch，唯一需要的配置选项是指向 Elasticsearch 服务的 URL。 实现时假定 AWS 访问密钥 id 和Secret访问密钥的环境变量已根据默认 AWS 凭据链。.

search:
  elasticsearch:
    provider: aws
    node: https://my-backstage-search-asdfqwerty.eu-west-1.es.amazonaws.com

Elastic.co

Elastic Cloud 托管的 Elasticsearch 使用云 ID 来确定要连接的托管 Elasticsearch 实例。 此外，还需要直接提供用户名和密码，或使用环境变量(如在Backstage文件。

search:
  elasticsearch:
    provider: elastic
    cloudId: backstage-elastic:asdfqwertyasdfqwertyasdfqwertyasdfqwerty==
    auth:
      username: elastic
      password: changeme

OpenSearch

OpenSearch 可以自行托管，例如使用官方 docker 映像配置只需要节点和身份验证。

search:
  elasticsearch:
    provider: opensearch
    node: http://0.0.0.0:9200
    auth:
      username: opensearch
      password: changeme

其他

其他 Elasticsearch 实例可通过使用标准 Elasticsearch 身份验证方法和暴露的 URL 连接，前提是集群支持该方法。 所需的配置选项是节点的 URL 和身份验证信息。 身份验证可通过提供用户名/密码或 API 密钥来处理。 有关如何创建 API 密钥的更多信息，请参阅关于应用程序接口密钥的弹性文档.

配置示例

使用用户名和密码

search:
  elasticsearch:
    node: http://localhost:9200
    auth:
      username: elastic
      password: changeme

使用 API 密钥

search:
  elasticsearch:
    node: http://localhost:9200
    auth:
      apiKey: base64EncodedKey

Elasticsearch 批量大小

Elasticsearch 引擎的默认批量大小设置为 1000。 如果您使用的是较低规格的计算资源(如 AWS 小型实例)，您可能会因有限的批量大小而出错。thread_pool配置。429 Too Many Requests /_bulk)

在这种情况下，您需要减小批量大小来索引资源，以防止出现此类错误。 您可以在您的app-config.yaml使用batchSize选项提供的 Elasticsearch 配置。

配置示例

将批量设置为 100

search:
  elasticsearch:
    batchSize: 100

如果使用的是大型 ES 实例，还可以增加批量大小。