Backstage Search 从零到生产搜索插件的安装、配置与深度定制指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage Search 是 Backstage 开发者门户中负责全域搜索能力的插件体系它本身不是搜索引擎而是连接 Backstage 与 Lucene 系、Postgres、Elasticsearch 等底层引擎的抽象层通过 Collator文档采集器把软件目录实体、TechDocs 文档等内容索引起来统一检索。本文以官方入门文档 docs/features/search/getting-started.md 为主线结合本仓库源码与配套文档完整覆盖前端安装、后端接入、三种搜索引擎的选型配置、内置 Collator 的调度与过滤以及基于 Blueprint 和IndexBuilder的前后端深度定制读完后你将能在自己的 Backstage 实例上从零搭起一套可搜索、可定制、可上生产的搜索功能。背景Search 在 Backstage 中的定位与架构Backstage Search 的目标是让开发者能够跨整个 Backstage 生态进行检索检索内容不仅限于软件目录中的实体还包括 TechDocs 文档、API 定义等。其架构设计追求三件事支持多种搜索引擎、给插件开发者提供简单的开发体验、给终端用户开箱即用的体验。相关架构目标记录在 docs/features/search/architecture.md 中其中明确提到任何插件都可以向搜索暴露新内容例如实体元数据、TechDocs 文档任何插件都可以为既有内容追加元数据例如 TechDocs 页面的路径可以精炼搜索查询排序、打分等可以定制搜索 UI目前不支持事件驱动或增量式的索引管理而是聚焦于定时、批量的索引重建。Search 相关代码在本仓库中的技术栈分布如下与 docs/features/search/architecture.md 的 Tech Stack 表格一致技术栈包名前端插件backstage/plugin-search前端插件库backstage/plugin-search-react同构插件库backstage/plugin-search-common后端插件backstage/plugin-search-backend后端插件库backstage/plugin-search-backend-node后端插件模块Elasticsearchbackstage/plugin-search-backend-module-elasticsearch后端插件模块Postgresbackstage/plugin-search-backend-module-pg从前端插件源码 plugins/search/src/alpha.tsx 可以看到backstage/plugin-search通过createFrontendPlugin注册了三个核心扩展searchApi负责与 search-backend 通信的 API、searchPage挂在/search路径的页面、homePageSearchBarWidget首页搜索框部件。其中searchPage由PageBlueprint.makeWithOverrides创建内置了noTrack配置项、并声明了items搜索结果项、resultTypes结果类型过滤、searchFilters搜索过滤器三个扩展输入——这正是页面可被插件扩展的架构落点。在动手安装前请先确保已经搭建好 Backstage 实例若尚未搭建可参考 docs/getting-started/index.md。另外本文面向新前端系统新 Backstage 应用默认启用如果你仍在使用旧前端系统请阅读对应的旧版指南 docs/features/search/getting-started--old.md。核心概念搜索引擎、Collator 与索引调度在开始安装之前理解几个贯穿全文的核心概念会很有帮助详见 docs/features/search/concepts.mdSearch Engine搜索引擎SearchEngine是一个接口具体实现负责与不同搜索引擎Elasticsearch、Lunr、Solr 等通信。Backstage 自身不是搜索引擎只是你的 Backstage 实例与所选搜索引擎之间的接口。开箱即用时Backstage 内置了一个基于 Lunr 的内存搜索引擎实现。Query Translator查询翻译器因为可以自带搜索引擎、而各家引擎又有独特的查询语言因此需要一个翻译层把抽象搜索查询搜索词、过滤器、文档类型翻译成具体引擎的查询。搜索引擎通常自带简单的翻译器你也可以提供自己的翻译器来调优组织内的搜索结果。Document 与 Index文档是抽象概念代表任何可以被搜索到的对象一个软件实体、一个 TechDocs 页面等至少包含 title、text、locationURL等元数据字段Index 是某一类型文档的集合。Collator采集器定义什么可以被搜索本质上是符合最小字段要求的可读对象流负责采集某一类型的文档。Catalog Backend 等插件提供了开箱即用的默认 Collator 工厂。Decorator装饰器位于 Collator读流与 Indexer写流之间的变换流可在索引过程中为文档增加额外字段例如实体使用率、质量评分也可以删除元数据、过滤甚至增加文档。The Scheduler调度器Backstage Search 采用按计划整体重建索引的策略不同 Collator 可以配置不同的刷新间隔当搜索索引分布在多个后端节点时通常由分布式的SchedulerServiceTaskRunner协调避免冲突。在前端安装 Search 插件Search 以插件的形式工作因此必须基于 Backstage 使用。在 Backstage 根目录执行以下命令把前端插件安装到packages/appyarn --cwd packages/app add backstage/plugin-search backstage/plugin-search-react安装完成后得益于默认的插件特性发现机制feature discoverySearch 插件会自动出现在你的应用中并提供以下开箱即用的能力位于/search的搜索页面侧边栏中的搜索导航项可从侧边栏打开的搜索弹窗Search Modal。更多安装细节与替代安装方式可参考 docs/frontend-system/building-apps/05-installing-plugins.md。从前端插件 READMEplugins/search/README.md可以看到该插件的主要职责就是提供可路由的SearchPage /扩展并暴露SearchModal /、SidebarSearch /等可组合组件而backstage/plugin-search-react负责SearchContextProvider管理搜索状态与后端通信、SearchApi、SearchBar、SearchFilter等可复用组件。通过 app-config.yaml 配置搜索页搜索页支持通过app-config.yaml配置。例如要关闭搜索结果跟踪noTrackapp: extensions: - page:search: config: noTrack: true这个noTrack配置在源码中有直接对应plugins/search/src/alpha.tsx 中searchPage的configSchema定义为{ noTrack: z.boolean().default(false) }默认值为false即默认开启跟踪你可以看到它通过PageBlueprint.makeWithOverrides被传入SearchPage组件的noTrack属性。另外前端插件还支持在app-config.yaml中配置搜索的默认行为见 plugins/search/README.md# app-config.yaml search: defaultType: software-catalog query: pageLimit: 50其中pageLimit的合法取值为10、25、50或100。需要注意该配置只反映 Search React 组件的初始状态即组件首次加载或重置时的行为。搜索结果列表项Search Result List Items搜索页会自动发现并使用已安装插件提供的搜索结果列表项扩展。例如catalog 插件提供CatalogSearchResultListItemTechDocs 插件提供TechDocsSearchResultListItem。这些扩展在相应插件安装时即被自动注册无需额外配置。你也可以使用backstage/plugin-search-react/alpha中的SearchResultListItemBlueprint安装额外的搜索结果列表项扩展用法见下文定制前端搜索体验。搜索过滤器Search Filters与搜索结果列表项类似搜索过滤器扩展也是自动发现的。你可以使用backstage/plugin-search-react/alpha中的SearchFilterBlueprint或SearchFilterResultTypeBlueprint添加自定义过滤器。在后端接入 Search后端需要接入的包有四个核心的 search-backend 插件、Postgres 搜索引擎模块、以及 Catalog 与 TechDocs 两个采集器模块。首先在 Backstage 根目录执行yarn --cwd packages/backend add backstage/plugin-search-backend backstage/plugin-search-backend-module-pg backstage/plugin-search-backend-module-catalog backstage/plugin-search-backend-module-techdocs然后在packages/backend/src/index.ts中注册这些插件const backend createBackend(); // Other plugins... /* highlight-add-start */ // search plugin backend.add(import(backstage/plugin-search-backend)); // search engines backend.add(import(backstage/plugin-search-backend-module-pg)); // search collators backend.add(import(backstage/plugin-search-backend-module-catalog)); backend.add(import(backstage/plugin-search-backend-module-techdocs)); /* highlight-add-end */ backend.start();完成上述配置后如果你的数据库没有配置 PostgresSearch 将使用Lunr 内存搜索引擎如果配置了 Postgres 作为数据库则会自动使用Postgres 作为搜索引擎。两种引擎的详细说明见下文与 docs/features/search/search-engines.md。同时会自动设置两个 Collator——Catalog与TechDocs它们负责把这两个数据源的内容索引起来使你可以轻松检索它们详见 docs/features/search/collators.md。选择并配置你的搜索引擎Backstage 默认支持三种搜索引擎内存引擎 Lunr、Postgres、以及 Elasticsearch7.x/OpenSearch。完整对比与配置细节见 docs/features/search/search-engines.md。Lunr零配置的内存引擎Lunr 内置于 search-backend 插件中是脚手架应用未做改动时的默认引擎。添加方式即上文后端的核心步骤backstage/plugin-search-backend即可const backend createBackend(); // Other plugins... /* highlight-add-start */ backend.add(import(backstage/plugin-search-backend)); /* highlight-add-end */ backend.start();注意Lunr 适合在本地开发其他 Backstage 功能时作为零配置引擎使用强烈不建议在生产环境使用。部署 Backstage 时请改用其他搜索引擎。Postgres免维护外部服务的引擎Postgres 搜索引擎只需要把 Postgres 配置为 Backstage 的数据库引擎即可适合希望避免额外维护 Elasticsearch 这类外部服务的场景。它在数万文档量级下表现良好连接通过其他插件共用的数据库管理器建立。重要Postgres 搜索引擎要求Postgres 12 及以上版本。安装与注册方式yarn --cwd packages/backend add backstage/plugin-search-backend-module-pgconst backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); /* highlight-add-start */ backend.add(import(backstage/plugin-search-backend-module-pg)); /* highlight-add-end */ backend.start();Postgres 可选配置Postgres 引擎目前的可选配置主要用于**搜索结果高亮highlight**功能search: pg: highlightOptions: useHighlight: true # 启用/禁用高亮功能默认 true maxWord: 35 # 输出的最长标题长度默认 35 minWord: 15 # 输出的最短标题长度默认 15 shortWord: 3 # 长度不超过该值的单词会在标题首尾被丢弃除非是查询词默认 3 会剔除常见英文冠词 highlightAll: false # 为 true 时整个文档作为标题忽略上面三个参数默认 false maxFragments: 0 # 显示的最大文本片段数默认 0 表示非片段式标题生成方式大于 0 则采用片段式生成 fragmentDelimiter: ... # 拼接片段的定界符默认 ... 注意高亮功能基于 Postgres 的ts_headline已知可能影响性能。如果遇到问题只需关闭即可search: pg: highlightOptions: useHighlight: falseElasticsearch7.x与 OpenSearchBackstage 开箱即用地支持 Elasticsearch 与 OpenSearch 的连接、索引与查询。配置选项支持 AWS 托管、Elastic.co 托管或自建方案。安装方式与 Postgres 类似yarn --cwd packages/backend add backstage/plugin-search-backend-module-elasticsearchconst backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); /* highlight-add-start */ backend.add(import(backstage/plugin-search-backend-module-elasticsearch)); /* highlight-add-end */ backend.start();底层实现使用官方 Elasticsearch 客户端 7.x即确认支持 Elasticsearch 7或在使用aws/opensearchprovider 时使用 OpenSearch 客户端。各类环境的配置示例AWS 托管 Elasticsearch——只需配置服务 URL实现假定环境变量中已按 AWS 默认凭证链配置好 access key 与 secret keysearch: elasticsearch: provider: aws node: https://my-backstage-search-asdfqwerty.eu-west-1.es.amazonaws.comElastic.co 云托管——使用 Cloud ID 定位实例并提供用户名密码可直接写死或通过环境变量注入search: elasticsearch: provider: elastic cloudId: backstage-elastic:asdfqwertyasdfqwertyasdfqwertyasdfqwerty auth: username: elastic password: changeme自建 OpenSearch——只需 node 地址与认证信息search: elasticsearch: provider: opensearch node: http://0.0.0.0:9200 auth: username: opensearch password: changeme其他 Elasticsearch 实例——使用标准认证方式与暴露的 URL 即可认证支持用户名密码或 API Keysearch: elasticsearch: node: http://localhost:9200 auth: username: elastic password: changemesearch: elasticsearch: node: http://localhost:9200 auth: apiKey: base64EncodedKeyElasticsearch 批量写入与索引名调优batchSize批量大小默认 1000。在低配资源如 AWS 小型实例上可能因thread_pool限制报429 Too Many Requests /_bulk错误此时应调低批量大小大实例则可以调高search: elasticsearch: batchSize: 100batchKeyField批量写入的 ID 字段默认情况下批量上传时每条文档使用自动生成的_id。如果频繁需要按固定标识查询或更新文档可设置batchKeyField提供一致的标识符避免重复条目注意若该字段值不唯一Elasticsearch 会以相同_id覆盖已有文档search: elasticsearch: batchKeyField: document_idindexPrefix索引名前缀默认索引名形如software-catalog-index__20250219类型名 分隔符 日期后缀。可自定义前缀search: elasticsearch: indexPrefix: custom-prefix-应用后索引名变为custom-prefix-software-catalog-index__20250219。queryOptions查询模糊度可通过fuzziness最大 Levenshtein 距离默认AUTO与prefixLength查询词开头必须精确匹配的最小字符数默认 0调优查询结果search: elasticsearch: queryOptions: fuzziness: AUTO prefixLength: 3;自定义认证扩展点对于需要动态认证机制如自动轮换的 bearer token的企业环境Elasticsearch 模块提供了认证扩展点适用于使用 OAuth2/OIDC 身份提供方进行服务认证、token 需要自动刷新如每小时过期、对接内部身份服务、运行在基于 token 认证保护的 Elasticsearch/OpenSearch 集群等场景。创建一个后端模块来提供认证 Providerimport { createBackendModule } from backstage/backend-plugin-api; import { elasticsearchAuthExtensionPoint } from backstage/plugin-search-backend-module-elasticsearch; export default createBackendModule({ pluginId: search, moduleId: elasticsearch-custom-auth, register(env) { env.registerInit({ deps: { elasticsearchAuth: elasticsearchAuthExtensionPoint, }, async init({ elasticsearchAuth }) { elasticsearchAuth.setAuthProvider({ async getAuthHeaders() { // Fetch token from your identity service const token await myTokenService.getToken(); return { Authorization: Bearer ${token} }; }, }); }, }); }, });然后在后端注册该模块const backend createBackend(); // Other plugins... backend.add(import(backstage/plugin-search-backend)); backend.add(import(backstage/plugin-search-backend-module-elasticsearch)); /* highlight-add-start */ backend.add(import(./modules/elasticsearchAuth)); /* highlight-add-end */ backend.start();getAuthHeaders会在每次请求前被调用从而支持即时取 token 与自动轮换。配置了认证 Provider 时其优先级高于app-config.yaml中的静态认证。注意自定义认证仅对elastic、opensearch和默认 provider 生效awsprovider 使用 AWS SigV4 请求签名不支持自定义认证 Provider。内置 CollatorCatalog 与 TechDocsBackstage 为 Catalog 和 TechDocs 各内置了一个 Collator二者默认每 10 分钟运行一次并支持在app-config.yaml中自定义调度与过滤规则详见 docs/features/search/collators.md。Catalog CollatorCatalog Collator 会索引软件目录中的所有实体。默认随安装生效如需手动添加yarn --cwd packages/backend add backstage/plugin-search-backend-module-catalogconst backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); /* highlight-add-start */ backend.add(import(backstage/plugin-search-backend-module-catalog)); /* highlight-add-end */ backend.start();调度配置search: collators: catalog: schedule: # 与 SchedulerServiceTaskScheduleDefinition 相同的选项 # 支持 cron、ISO 时长、人类可读时长与代码中用法一致 initialDelay: { seconds: 90 } # 支持 cron、ISO 时长、人类可读时长与代码中用法一致 frequency: { hours: 6 } # 支持 ISO 时长、人类可读时长与代码中用法一致 timeout: { minutes: 3 }实体过滤如果只想采集目录中特定的实体子集可使用filter配置。基础示例——只采集kind为component或api且spec.lifecycle为production的实体search: collators: catalog: filter: kind: [component, api] spec.lifecycle: production更高级的过滤示例——采集kind为api且spec.type为openapi的实体或kind为component且spec.lifecycle为experimental的实体数组中的每个元素是一组与条件元素之间是或关系search: collators: catalog: filter: - kind: [API] spec.type: openapi - kind: [Component] spec.lifecycle: experimental提示该过滤配置基于EntityFilterQuery语法实现详情可参考backstage/catalog-client中EntityFilterQuery的参考文档。TechDocs CollatorTechDocs Collator 会索引目录中的所有 TechDocs 文档默认随安装生效也可手动添加yarn --cwd packages/backend add backstage/plugin-search-backend-module-techdocsconst backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); /* highlight-add-start */ backend.add(import(backstage/plugin-search-backend-module-techdocs)); /* highlight-add-end */ backend.start();调度配置默认每 10 分钟运行一次可自定义search: collators: techdocs: schedule: # 与 SchedulerServiceTaskScheduleDefinition 相同的选项 # 支持 cron、ISO 时长、人类可读时长与代码中用法一致 initialDelay: { seconds: 90 } # 支持 cron、ISO 时长、人类可读时长与代码中用法一致 frequency: { hours: 6 } # 支持 ISO 时长、人类可读时长与代码中用法一致 timeout: { minutes: 3 }通过 Catalog Collator 过滤实体TechDocs Collator 默认过滤掉没有metadata.annotations.backstage.io/techdocs-ref注解的目录实体。如需进一步过滤可通过techDocsCollatorEntityFilterExtensionPoint以两种方式实现export const exampleCustomCatalogFiltering createBackendModule({ pluginId: search, moduleId: search-techdocs-collator-entity-filter, register(reg) { reg.registerInit({ deps: { customCollatorFilter: techDocsCollatorEntityFilterExtensionPoint, }, async init({ customCollatorFilter }) { /* 按目录参数过滤 */ customCollatorFilter.setCustomCatalogApiFilters([ { kind: [API, Component, ...] }, { metadata: [...more filters] }, ]); /* 按自定义函数过滤 */ customCollatorFilter.setEntityFilterFunction((entities: Entity[]) entities.filter( entity entity.metadata?.annotations?.abc xyz, ), ); }, }); }, });社区 Collator 与自定义 Collator除内置的两个 Collator 外Backstage 社区还提供了多个可用的 Collator例如backstage-community/plugin-search-backend-module-explore索引 Explore 插件内容、backstage/plugin-search-backend-module-stack-overflow-collator索引 Stack Overflow 内容、以及 ADR、Announcements、Azure DevOps、Confluence、GitHub Discussions、ReportPortal 等对应的采集器模块完整列表见 docs/features/search/collators.md 的 Community Collators 一节。本仓库中也包含 Stack Overflow collator 的实现plugins/search-backend-module-stack-overflow-collator。如需编写自己的 Collator请参考 docs/features/search/custom-collators.md 指南。深度定制前端搜索体验前端定制主要通过 Blueprint 体系完成可添加自定义搜索结果列表项、过滤器与结果类型过滤器。自定义搜索结果列表项使用backstage/plugin-search-react/alpha的SearchResultListItemBlueprint创建import { SearchResultListItemBlueprint } from backstage/plugin-search-react/alpha; export const MySearchResultListItem SearchResultListItemBlueprint.make({ name: my-result-item, params: { predicate: result result.type my-custom-type, component: async () { const { MyResultItem } await import(./components/MyResultItem); return MyResultItem; }, }, });如果这个扩展来自插件将其从插件 alpha 入口导出即可在插件安装时被自动发现见 docs/features/search/how-to-guides.md。如果希望从应用侧提供该扩展则把它包装进一个前端模块并传给createAppimport { createFrontendModule } from backstage/frontend-plugin-api; import { MySearchResultListItem } from ./MySearchResultListItem; export const searchCustomizations createFrontendModule({ pluginId: search, extensions: [MySearchResultListItem], });import { createApp } from backstage/frontend-defaults; import { searchCustomizations } from ./search/searchModule; const app createApp({ features: [searchCustomizations], }); export default app.createRoot();关于多个结果列表项扩展的渲染顺序搜索页会按谓词predicate匹配结果第一个匹配的扩展负责渲染该结果没有predicate的扩展充当兜底渲染器应排在最后。自定义搜索 API默认情况下Search 插件通过SearchApi与 search-backend 通信以查询结果实现见 plugins/search/src/apis.ts 中的SearchClient。当你有自己的搜索后端需要对接时可以实现SearchApi接口并使用backstage/frontend-plugin-api的createApiExtension创建自定义 API 扩展覆盖默认实现参见 docs/frontend-system/utility-apis/01-index.md。自定义搜索结果高亮样式默认情况下搜索结果的匹配词高亮使用浏览器对markHTML 标签的默认样式。如需自定义可通过统一主题Unified Theme方法覆盖BackstageHighlightedSearchResultText组件样式例如让高亮词变为加粗加下划线import { createBaseThemeOptions, createUnifiedTheme, palettes, UnifiedTheme, } from backstage/theme; export const myLightTheme: UnifiedTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), defaultPageTheme: home, components: { /** ts-ignore This is temporarily necessary until MUI V5 transition is completed. */ BackstageHighlightedSearchResultText: { styleOverrides: { highlight: { color: inherit, backgroundColor: inherit, fontWeight: bold, textDecoration: underline, }, }, }, }, });自定义主题在新前端系统中作为扩展安装详见 docs/frontend-system/building-apps/02-configuring-extensions.md。深度定制后端IndexBuilder、Collator 与调度后端定制的核心是IndexBuilder——通过它注册任意数量的 Collator每个 Collator 负责提供待索引的文档。使用 IndexBuilder 注册多个 Collatorconst indexBuilder new IndexBuilder({ logger: env.logger, searchEngine }); const every10MinutesSchedule env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 10 }, timeout: { minutes: 15 }, initialDelay: { seconds: 3 }, }); const everyHourSchedule env.scheduler.createScheduledTaskRunner({ frequency: { hours: 1 }, timeout: { minutes: 90 }, initialDelay: { seconds: 3 }, }); indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, }), }); indexBuilder.addCollator({ schedule: everyHourSchedule, factory: new MyCustomCollatorFactory(), });自定义索引重建频率Backstage Search 按计划重建并维护索引见 docs/features/search/concepts.md 的 The Scheduler 一节。如果你的文档更新频率不同可以调整某类文档的索引重建频率只需配置一个调度化的SchedulerServiceTaskRunner传给schedule值const every10MinutesSchedule env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 10 }, timeout: { minutes: 15 }, initialDelay: { seconds: 3 }, }); indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, }), });多节点场景下的非分布式调度如果你使用内存 Lunr 搜索引擎并且运行着多个 search 后端节点建议实现一个非分布式的SchedulerServiceTaskRunner以保证索引一致性另一种做法是把 search 插件配置为使用非分布式数据库例如 docs/tutorials/configuring-plugin-databases.md 中介绍的 SQLite。import { SchedulerServiceTaskRunner, SchedulerServiceTaskInvocationDefinition, } from backstage/backend-plugin-api; const schedule: SchedulerServiceTaskRunner { run: async (task: SchedulerServiceTaskInvocationDefinition) { const startRefresh async () { while (!task.signal?.aborted) { try { await task.fn(task.signal); } catch { // ignore intentionally } await new Promise(resolve setTimeout(resolve, 600 * 1000)); } }; startRefresh(); }, }; indexBuilder.addCollator({ schedule, factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, }), });定制 Catalog 与 TechDocs 索引字段如果你希望控制进入搜索索引的字段可以给DefaultCatalogCollatorFactory或DefaultTechDocsCollatorFactory传入entityTransformer回调TechDocs 还支持documentTransformer回调详见 docs/features/search/how-to-guides.mdconst catalogEntityTransformer: CatalogCollatorEntityTransformer ( entity: Entity, ) { if (entity.kind SomeKind) { return { // customize here output for SomeKind kind }; } return { // and customize default output ...defaultCatalogCollatorEntityTransformer(entity), text: my super cool text, }; }; indexBuilder.addCollator({ collator: DefaultCatalogCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, /* highlight-add-next-line */ entityTransformer: catalogEntityTransformer, }), }); const techDocsEntityTransformer: TechDocsCollatorEntityTransformer ( entity: Entity, ) { return { // add more fields to the index tags: entity.metadata.tags, }; }; const techDocsDocumentTransformer: TechDocsCollatorDocumentTransformer ( doc: MkSearchIndexDoc, ) { return { // add more fields to the index bost: doc.boost, }; }; indexBuilder.addCollator({ collator: DefaultTechDocsCollatorFactory.fromConfig(env.config, { discovery: env.discovery, tokenManager: env.tokenManager, /* highlight-add-next-line */ entityTransformer: techDocsEntityTransformer, /* highlight-add-next-line */ documentTransformer: techDocsDocumentTransformer, }), });提示authorization与location字段无法通过entityTransformer修改其中location只能通过locationTemplate修改。生产环境部署建议综合官方文档与源码信息将 Search 投入生产时建议遵循以下原则不要在生产使用 Lunr 内存引擎它只适合本地开发生产环境请选用 Postgres 或 Elasticsearch/OpenSearch 引擎见 docs/features/search/search-engines.md。多节点部署注意索引一致性使用内存引擎且多节点运行时务必采用非分布式SchedulerServiceTaskRunner或非分布式数据库避免各节点索引不一致。按数据更新频率配置调度不同 Collator 的schedule独立配置更新频繁的内容可缩短frequency反之则延长以平衡索引新鲜度与资源消耗。高亮功能按需开启Postgres 的ts_headline高亮已知可能影响性能若索引规模大或查询压力高可设置search.pg.highlightOptions.useHighlight: false。低配 Elasticsearch 调低批量大小遇到429 Too Many Requests /_bulk时通过batchSize调低批量写入大小。至此你已经掌握了 Backstage Search 从安装、引擎选型、Collator 配置到前后端深度定制的完整链路。进一步可阅读 docs/features/search/architecture.md 了解架构设计意图、docs/features/search/concepts.md 回顾核心概念、docs/features/search/custom-collators.md 学习编写自定义 Collator或直接查看前端插件源码 plugins/search/src/alpha.tsx 验证本指南中提到的扩展机制。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考