Backstage 搜索后端选型与配置指南Lunr、Postgres 与 Elasticsearch/OpenSearch 深度实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的搜索功能允许用户跨软件目录Software Catalog、技术文档TechDocs等资源进行统一检索而搜索结果的索引与查询能力由搜索后端引擎承载。本文围绕 docs/features/search/search-engines.md 的核心内容系统讲解 Backstage 默认支持的三种搜索引擎——Lunr、Postgres 与 Elasticsearch/OpenSearch——的适用场景、安装注册步骤、完整配置项与底层实现原理帮助你在开发与生产环境中正确选型并落地。三种搜索引擎一览Backstage 开箱即用地支持 3 种搜索后端引擎它们由对应的后端模块实现并通过新后端系统New Backend System的searchEngineRegistryExtensionPoint注册到搜索后端插件中引擎实现模块适用场景生产可用性Lunrbackstage/plugin-search-backend内置本地开发、快速原型不推荐用于生产Postgresbackstage/plugin-search-backend-module-pg已使用 Postgres 作为 Backstage 数据库的中小型部署推荐需 Postgres 12Elasticsearch / OpenSearchbackstage/plugin-search-backend-module-elasticsearch大规模索引、高查询性能、托管或自建 ES 集群推荐在脚手架生成的默认应用中如果你没有做额外改动Lunr 引擎默认启用。它是零配置的起点但官方文档明确提示Lunr 仅适合在本地开发 Backstage 其他功能时作为轻量搜索后端在生产环境中强烈不推荐使用部署时应改用另外两种引擎之一。Lunr零配置的本地内存引擎Lunr 内置于backstage/plugin-search-backend搜索后端插件中因此无需单独安装额外模块。在 Backstage 根目录下添加搜索后端插件yarn --cwd packages/backend add backstage/plugin-search-backend然后在后端入口 packages/backend/src/index.ts 中注册const backend createBackend(); // Other plugins... backend.add(import(backstage/plugin-search-backend)); backend.start();Lunr 引擎将索引保存在进程内存中因此每次后端重启后都需要通过 collator收集器重新构建索引。从源码结构看Lunr 引擎随搜索后端插件一同启动不需要任何search.*配置节即可运行这也是它零配置的由来。它的优点是上手即用、无外部依赖缺点是数据不持久、索引规模受内存限制只适合开发调试。Postgres复用现有数据库的全文检索引擎Postgres 搜索引擎是不想额外维护 Elasticsearch 等外部服务的部署方案的首选。它通过 Backstage 的数据库管理器Database Manager建立连接与其它插件共用同一套 Postgres 连接配置无需为搜索单独配置连接信息。官方文档指出Postgres 引擎能提供不错的相关度排序并在上万篇索引文档的规模下表现良好。重要Postgres 搜索引擎要求数据库版本至少为 Postgres 12因为其底层依赖 Postgres 的全文检索tsvector / tsquery与高亮ts_headline能力。安装与注册yarn --cwd packages/backend add backstage/plugin-search-backend-module-pgconst backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); backend.add(import(backstage/plugin-search-backend-module-pg)); backend.start();从 plugins/search-backend-module-pg/src/module.ts 的实现可以看到模块初始化时会先调用PgSearchEngine.supported(database)检测当前数据库是否支持即是否为 Postgres 12只有通过检测才会把PgSearchEngine注册到searchEngineRegistryExtensionPoint否则会记录一条警告日志并跳过注册避免在不兼容的数据库上运行时报错。可选配置高亮选项Postgres 引擎的可选配置目前主要围绕搜索关键词高亮功能完整示例字段与注释来自 plugins/search-backend-module-pg/config.d.tssearch: pg: highlightOptions: useHighlight: true # 启用/禁用高亮功能默认 true maxWords: 35 # 输出摘要headline的最大词数默认 35 minWords: 15 # 输出摘要的最小词数默认 15 shortWord: 3 # 长度小于等于该值的词会在摘要首尾被剔除除非是查询词默认 3可过滤常见英文冠词 highlightAll: false # 为 true 时整篇文档作为摘要忽略以上三个参数默认 false maxFragments: 0 # 展示的文本片段最大数量默认 0 表示使用非片段式摘要生成方式大于 0 时启用基于片段的摘要生成 fragmentDelimiter: ... # 拼接多个片段的分隔符默认 ... 以上高亮参数直接映射到 Postgres 的ts_headline函数。从 PgSearchEngine.ts 的构造函数可见这些默认值useHighlight: true、maxWords: 35、minWords: 15、shortWord: 3、highlightAll: false、maxFragments: 0、fragmentDelimiter: ... 均与文档一致并且引擎会为高亮标签生成随机 UUID 前缀的preTag/postTag避免与文档正文中的 HTML 标签冲突。注意高亮功能使用的ts_headline已知可能影响查询性能。如果遇到性能问题只需最小化配置即可关闭高亮search: pg: highlightOptions: useHighlight: false两个值得了解的扩展配置项config.d.ts 中还声明了文档正文未展开的两个配置search.pg.normalization用于控制文档长度对排序分数影响的整数位掩码默认0。支持数字或按位或表达式字符串如1|4源码中会通过evaluateBitwiseOrExpression解析为最终的位掩码值。search.pg.indexerBatchSize批量索引时每批写入的文档数量默认1000用于控制索引吞吐与数据库压力。分页与相关度实现细节从 PgSearchEngine.ts 的translator可以看出 Postgres 引擎的查询转换逻辑它会将用户查询词按空白拆分过滤掉\0()|:*!等特殊字符然后把每个词构造成(term | term:*)的 tsquery 片段并用连接从而实现精确词或带前缀匹配的宽松检索分页则通过请求pageSize 1条记录来判断是否存在下一页游标与 Elasticsearch 引擎一样使用 base64 编码的页码。Elasticsearch (7.x) 与 OpenSearchBackstage 对 Elasticsearch 与 OpenSearch 的连接、索引和查询提供了开箱即用的支持。配置项可以覆盖三类部署形态AWS 托管的 Elasticsearch / OpenSearchprovider: awsElastic.co 托管的 Elastic Cloudprovider: elastic自建或其他标准 Elasticsearch 集群不设置 provider或provider: opensearch底层实现使用官方 Elasticsearch 客户端 7.x即仅确认支持 Elasticsearch 7.x 版本或在使用aws/opensearchprovider 时改用OpenSearch 客户端。这一点在 ElasticSearchSearchEngine.ts 的createElasticSearchClientOptions中体现它针对四种 provider 分别构造不同的客户端选项。安装与注册yarn --cwd packages/backend add backstage/plugin-search-backend-module-elasticsearchconst backend createBackend(); // Other plugins... // search plugin backend.add(import(backstage/plugin-search-backend)); backend.add(import(backstage/plugin-search-backend-module-elasticsearch)); backend.start();模块在初始化时会读取search.elasticsearch配置节如果该配置不存在会记录警告并跳过引擎初始化见 module.ts如果设置了indexPrefix则会打印日志提示索引将使用该前缀。典型配置示例以下配置均写入app-config.yaml。AWS 托管 Elasticsearch使用 AWS 托管的 Elasticsearch 时唯一必需的配置是服务 URL。实现默认遵循 AWS 默认凭证链即通过环境变量AWS_ACCESS_KEY_ID与AWS_SECRET_ACCESS_KEY或实例角色等提供凭证search: elasticsearch: provider: aws node: https://my-backstage-search-asdfqwerty.eu-west-1.es.amazonaws.com从源码看awsprovider 使用 AWS SigV4 请求签名AwsSigv4Signer配合DefaultAwsCredentialsManager获取凭证。配置 schemaconfig.d.ts还允许通过region指定区域、通过service指定签名服务类型es对应托管集群aoss对应 Serverless这两个选项主要在使用自定义 DNS 记录时需要显式设置。Elastic.coElastic CloudElastic Cloud 使用 Cloud ID 定位集群实例同时需要提供用户名与密码可直接写入配置或用环境变量等 Backstage 动态配置方式注入search: elasticsearch: provider: elastic cloudId: backstage-elastic:asdfqwertyasdfqwertyasdfqwertyasdfqwerty auth: username: elastic password: changeme自建 OpenSearchOpenSearch 可以自建例如官方 Docker 镜像配置只需节点地址与认证信息search: elasticsearch: provider: opensearch node: http://0.0.0.0:9200 auth: username: opensearch password: changeme其他标准 Elasticsearch 集群对于其它标准 Elasticsearch 实例只要集群暴露了可直接访问的 URL 并支持标准认证方式即可连接。认证可以用用户名/密码也可以用 API Key# 用户名/密码方式 search: elasticsearch: node: http://localhost:9200 auth: username: elastic password: changeme# API Key 方式 search: elasticsearch: node: http://localhost:9200 auth: apiKey: base64EncodedKey关于 API Key 的创建方法可参考 Elastic 官方Create API keys文档。需要说明的是node支持传入字符串或字符串数组多节点地址当同时提供apiKey与用户名/密码时tokenAPI Key优先。批量索引大小batchSizeElasticsearch 引擎的默认批量索引大小为1000。如果使用低配计算资源例如 AWS 小规格实例可能因集群thread_pool限制而触发429 Too Many Requests /_bulk错误。此时应在app-config.yaml中调小batchSizesearch: elasticsearch: batchSize: 100反之如果使用大型 ES 实例也可以调大批量大小以提升索引吞吐。该默认值在 ElasticSearchSearchEngine.ts 中以常量DEFAULT_INDEXER_BATCH_SIZE 1000定义并通过config.getOptionalNumber(search.elasticsearch.batchSize) ?? DEFAULT_INDEXER_BATCH_SIZE读取。批量文档标识字段batchKeyField默认情况下Elasticsearch 索引器在批量上传时为每个文档生成自动_id。如果你的场景需要频繁按固定标识查找或更新已有文档可以设置batchKeyField指定文档中的某个字段作为_id从而简化更新流程、避免重复条目search: elasticsearch: batchKeyField: document_id不配置时的默认行为自动生成_idsearch: elasticsearch: # 未指定 batchKeyField —— Elasticsearch 将自动生成 _id需要注意如果batchKeyField对应的值在文档间不唯一后写入的文档会覆盖同_id的既有文档。该逻辑在 ElasticSearchSearchEngineIndexer.ts 的onDocument回调中实现仅在配置了batchKeyField且该字段值存在时才附带_id。索引名称自定义indexPrefix默认情况下Elasticsearch 索引器按类型 分隔符 日期后缀的方式生成索引名例如software-catalog-index__20250219其中分隔符-index__定义在 ElasticSearchSearchEngine.ts 的indexSeparator字段中。可以通过indexPrefix为所有索引添加自定义前缀search: elasticsearch: indexPrefix: custom-prefix-应用后索引名变为custom-prefix-software-catalog-index__20250219从源码的constructIndexName与constructSearchAlias可以看出前缀会同时作用于查询别名alias与索引名保证查询与写入使用一致的命名空间索引切换采用创建新索引 → 旋转别名 → 清理旧索引的零停机策略。查询选项fuzziness 与 prefixLength默认查询使用 Elasticsearch 的标准配置。若需调整查询结果的模糊匹配程度可通过两个参数fuzziness定义查询词允许的最大 Levenshtein 编辑距离AUTO是默认值且为业界广泛接受的标准也可指定固定数字如1表示允许一次字符编辑。prefixLength控制查询词开头必须精确匹配的最少字符数默认0。search: elasticsearch: queryOptions: fuzziness: AUTO prefixLength: 3这两项在 ElasticSearchSearchEngine.ts 的translator中被应用到multiMatchQuery上未配置时分别回退为auto与0。另外源码还支持search.elasticsearch.highlightOptionsfragmentSize默认 1000、numFragments默认 1、fragmentDelimiter默认 ... 以及search.elasticsearch.clientOptions.ssl.rejectUnauthorized默认true等配置可按需在 schema 中查阅。自定义认证扩展点Custom Authentication Extension Point对于需要动态认证机制的企业环境例如使用自动轮换的 Bearer TokenElasticsearch 模块提供了认证扩展点。它适用于以下场景使用 OAuth2/OIDC 身份提供方进行服务间认证Token 需要自动刷新例如每小时过期的 Token集成内部身份服务运行在基于 Token 认证保护的 Elasticsearch/OpenSearch 集群上。使用方式创建一个后端模块通过elasticsearchAuthExtensionPoint提供认证 Provider。例如 packages/backend/src/modules/elasticsearchAuth.tsimport { 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() { // 从你的身份服务获取 Token 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)); backend.add(import(./modules/elasticsearchAuth)); backend.start();getAuthHeaders会在每次请求前被调用从而实现即时获取 Token 与自动轮换。从 auth.ts 的接口定义与 ElasticSearchSearchEngine.ts 的客户端构造逻辑可以确认一旦配置了自定义 auth provider它就会优先于app-config.yaml中的静态认证通过自定义 Transport 向每个请求注入认证头。注意自定义认证仅支持elastic、opensearch和默认标准 Elasticsearch三种 provider。awsprovider 使用 AWS SigV4 请求签名不支持自定义认证 Provider源码中若同时配置会直接抛出错误。选型建议与注意事项综合官方文档与源码实现可以给出如下选型参考本地开发直接使用默认的 Lunr零配置、无需外部依赖适合在开发其他 Backstage 功能时快速验证搜索行为。中小规模生产部署如果 Backstage 已使用 Postgres 作为主数据库优先考虑plugin-search-backend-module-pg避免额外引入 Elasticsearch 集群。需确保数据库版本 ≥ Postgres 12并评估ts_headline高亮带来的性能开销必要时关闭useHighlight。大规模索引 / 高性能查询选择 Elasticsearch 或 OpenSearch 引擎。注意其仅确认支持 Elasticsearch 7.x低配实例上可调小batchSize避免429错误需要幂等更新文档时配置batchKeyField多环境共用集群时用indexPrefix隔离索引命名空间对 Token 轮换等动态认证诉求使用自定义认证扩展点。无论选择哪种引擎其核心工作流一致collator 收集文档 → 引擎索引器Indexer批量写入 → 前端查询时由引擎翻译查询并返回带高亮的结果。三种引擎的查询转换、批量索引、分页游标等逻辑均可在对应模块源码ElasticSearchSearchEngine.ts、PgSearchEngine.ts中进一步追踪深入理解后可基于其公开的 translator 扩展点自定义查询行为。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考