企业官网建设流程全解析

还在多个系统里来回找技术资产？Backstage 搜索一个框就能搞定

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

找一个组件要在软件目录、文档站、集群控制台区之间来回切，切了半天还没切到。Backstage 内置的搜索功能把组件、文档、API 这类技术资产收进同一个搜索框，一个关键词就能检索出来。下面直接给你一条最短的可用路径。

从一个真实场景说起

下午三点，产品找你：能不能把支付服务的 API 文档链接发给她。你在目录、文档系统、集群控制台之间切了二十分钟，对方已经开始问进度了。其实不是文档不存在，是缺一个统一的检索入口。Backstage 搜索干的就是这件事——你不用记住哪个系统里放了什么，一个关键词把注册进来的技术资产都捞出来。

它能帮你做什么（能力速览）

一个框搜所有东西

组件、API 文档、TechDocs 技术文档，都从同一个搜索框进。不用背"这类资产归哪个系统管"。

结果按相关度排好序，还能按类型过滤

搜索结果按相关度排序，页面上直接按资产类型过滤，不用翻很多页才能看到想要的那条。

刚注册的组件很快就能搜到

索引按调度自动重建，目录类内容默认每 10 分钟刷一次，新实体不用你做任何事就会出现在结果里。

搜什么、不搜什么，由你决定

通过 collator 过滤条件，可以只索引生产环境的组件、只索引某一类 kind，噪音不用全吞。

从零到可用的最小可行配置

已有 Backstage 应用的话，前后端各装一次插件就行。前端装搜索页面：

yarn --cwd packages/app add @backstage/plugin-search @backstage/plugin-search-react

后端装搜索核心，再加两个默认 collator（目录 + 技术文档）：

yarn --cwd packages/backend add @backstage/plugin-search-backend @backstage/plugin-search-backend-module-catalog @backstage/plugin-search-backend-module-techdocs

然后在packages/backend/src/index.ts里注册：

backend.add(import('@backstage/plugin-search-backend')); backend.add(import('@backstage/plugin-search-backend-module-catalog')); backend.add(import('@backstage/plugin-search-backend-module-techdocs'));

重启后，侧边栏会多出搜索入口，/search是一个独立的搜索页，输入关键词就能看到目录和文档的混合结果：

搜索结果里点部署名，可以直接跳到 Kubernetes 视图：

搜索引擎按你的规模选一个：

• Lunr（内存）：零配置，只建议本地开发体验用，官方明确不建议上生产
• Postgres：要求 12 及以上，复用 Backstage 已有数据库，不用多养一个外部服务
• Elasticsearch 7.x / OpenSearch：数据量大或有独立集群时用，支持自建或云托管

选型细节见 docs/features/search/search-engines.md。

进阶玩法与扩展 🔍

用 collator 过滤收窄索引范围

在app-config.yaml里给 catalog collator 加过滤，只索引你关心的实体：

search: collators: catalog: filter: kind: [component, api] spec.lifecycle: production

过滤条件支持EntityFilterQuery语法，多组条件之间是"或"的关系，细节在 docs/features/search/collators.md。

调整索引重建节奏

同级的schedule配置能改initialDelay、frequency、timeout。数据更新慢的源可以拉长到几小时一刷，减轻索引压力。

把搜索扩到别的数据源

每个数据源就是一个 collator。仓库自带 plugins/search-backend-module-catalog/ 和 plugins/search-backend-module-techdocs/，社区还有 Confluence、Stack Overflow 等现成 collator；自己写一份可照 docs/features/search/custom-collators.md 来。

定制结果展示样式

前端用SearchResultListItemBlueprint注册自定义结果卡片，让每种资产类型有自己的排版，写法见 docs/features/search/getting-started.md 的前端部分。

容易踩的坑 ⚠️

重启后搜索结果变空现象：开发环境搜得好好的，部署多实例后结果时有时无。 原因：默认 Lunr 是内存引擎，重启即丢，且多节点各自为政。 解决：切到 Postgres 或 Elasticsearch。

新注册的组件搜不到现象：目录里已经能看到实体，搜索却查无此物。 原因：索引按调度重建，catalog 默认间隔是 10 分钟。 解决：等下一轮重建，或把frequency调短。

TechDocs 页面搜不到现象：实体在目录里，但对应文档页不出现在结果中。 原因：TechDocs collator 只索引带backstage.io/techdocs-ref注解的实体。 解决：给实体补上该注解，并确认装了 plugins/search-backend-module-techdocs/。

小规格 Elasticsearch 报 429现象：日志里出现429 Too Many Requests /_bulk。 原因：默认batchSize是 1000，对小实例偏大。 解决：在search.elasticsearch.batchSize里调小到 100 左右。

适用场景速查

下一步建议

如果你手边已有 Backstage 实例，先按上面的最小配置把默认搜索跑起来，拿自己的软件目录当试验田，感受下结果排序和过滤。确认要上生产前，把搜索引擎定下来——小规模用 Postgres 最省事，数据量大再上 Elasticsearch。

更多细节看 docs/features/search/ 和源码入口 plugins/search-backend/。

先搜自己的目录，手感很快就有了。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage