企业官网建设流程全解析

Backstage v1.2.0-next.2 变更详解：Scaffolder 用户引用、人类可读任务调度与搜索高亮增强

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

本文基于 docs/releases/v1.2.0-next.2-changelog.md 解读 Backstage 1.2.0 系列第二个预发布版本（next.2）的核心变更。该版本横跨 Scaffolder、后端公共库、任务调度、目录提供者、搜索与 TechDocs 等多个模块：既带来了template.yaml中引用当前用户、Rails 动作镜像白名单等 Scaffolder 关键能力，也通过人类可读的持续时间对象简化了任务调度配置，并为搜索索引引入了结果高亮与更大的批量写入。读完本文，你将理解这些变更的用法、破坏性影响以及它们在当前仓库源码中的落地位置，能够据此评估和升级自己的 Backstage 实例。

一、变更总览

v1.2.0-next.2 涉及数十个 npm 包的依赖联动更新，其中有实质行为变更（Minor / BREAKING）的模块如下，绝大多数包仅同步了依赖版本（Patch）：

下文按主题深入展开有实操价值的变更。

二、Scaffolder：在 template.yaml 中引用当前用户

变更f8baf7df44为@backstage/plugin-scaffolder-backend（1.2.0-next.1）与@backstage/plugin-scaffolder-common（1.1.0-next.0）同时加入了在软件模板清单template.yaml中引用当前执行用户的能力。这解决了此前模板参数中无法直接获取"谁在创建"这一关键上下文的问题，使得生成内容可以自动带上创建者信息（例如写入 README 作者、配置归属人、为仓库添加 owner 等）。

• 后端实现位于 plugins/scaffolder-backend，用户信息在任务执行上下文中被解析并注入模板输入；
• 类型与数据结构定义位于 plugins/scaffolder-common，供前后端共享；
• 关于entityRef形式的实体引用用法，可参考 plugins/scaffolder-backend/src/scaffolder/actions/builtin/catalog/fetch.examples.ts，其中演示了entityRef: 'component:default/name'与批量entityRefs的写法，是理解 Scaffolder 引用体系的良好起点。

需要说明的是：该能力在 next 版本中以 Minor 形式引入，最终随 v1.2.0 正式发布；如果你在模板中依赖$user这类上下文变量，请确保升级后的scaffolder-backend与scaffolder-common版本一致（二者在本版本中成对更新，避免类型不匹配）。

三、Scaffolder Rails 动作：新增 allowedImageNames 白名单（破坏性）

变更3d001a3bcf为@backstage/plugin-scaffolder-backend-module-rails（0.4.0-next.1）引入了BREAKING选项allowedImageNames。在此之前，Rails 动作的imageName输入可以任意指定镜像名；此后，任何镜像名都必须先列入allowedImageNames才能被接受。

升级注意事项：

• 如果你在软件模板中使用了rails:new动作并传入了imageName，升级后必须同步提供allowedImageNames列表，否则执行会因镜像未授权而失败；
• 该选项的意图是限制 Scaffolder 容器环境可拉取/使用的镜像来源，属于安全收口，应只放行受信任的镜像名称；
• 该模块的实现位于 plugins/scaffolder-backend-module-rails，其package.json同时依赖@backstage/plugin-scaffolder-backend@1.2.0-next.1，说明它直接复用 Scaffolder 后端核心的执行框架。

四、backend-common：ReadUrlResponse 流式读取与 ReadUrlResponseFactory

变更e0a6360b80为@backstage/backend-common（0.13.3-next.2）补齐了 URL 读取的流式接口：

1. ReadUrlResponse新增stream()方法，与既有的buffer()方法互补，允许以流式方式消费远程内容，适合大文件或逐块处理场景；
2. 新增ReadUrlResponseFactory工具类，为UrlReader.readUrl()的实现方提供统一、简单的响应构造方式，避免各集成各自拼装对象。

变更日志明确提示：stream()目前虽然是可选的，但在未来的某个版本中将成为UrlReader.readUrl()实现的必需方法。这意味着自定义UrlReader的开发者应当尽早适配。

该工具类的当前实现位于 packages/backend-defaults/src/entrypoints/urlReader/lib/ReadUrlResponseFactory.ts，配套测试见 packages/backend-defaults/src/entrypoints/urlReader/lib/ReadUrlResponseFactory.test.ts，可以作为编写自定义 Reader 的参考样例。

五、backend-common：Google Cloud Storage 的 UrlReader.search() 支持

变更4b811aafce为 Google Cloud Storage 实现了UrlReader.search()方法。受底层存储 API 限制，当前仅支持基于前缀的搜索，例如：

https://storage.cloud.google.com/your-bucket/some-path/*

也就是说，search()的通配符只允许出现在路径末尾（*后缀），无法像文件系统那样做任意位置的通配匹配。GCS 集成的其余解析与配置逻辑可在 packages/integration 中查看。

六、任务调度：用人类可读对象替代 luxon Duration

变更73480846dd是本版本对所有使用者都友好的改进：@backstage/backend-tasks的TaskScheduleDefinition现在允许直接使用包含days、hours、minutes、seconds等字段的对象来描述频率与超时，而不再强制import { Duration } from 'luxon'。

升级写法对照（来自变更日志原文）：

-import { Duration } from 'luxon'; // omitted other code const schedule = env.scheduler.createScheduledTaskRunner({ - frequency: Duration.fromObject({ minutes: 10 }), - timeout: Duration.fromObject({ minutes: 15 }), + frequency: { minutes: 10 }, + timeout: { minutes: 15 }, // omitted other code });

从当前仓库源码看，这一能力已沉淀进正式 API：packages/backend-plugin-api/src/services/definitions/SchedulerService.ts 中SchedulerServiceTaskScheduleDefinition.frequency的类型为Duration | HumanDuration | { trigger: 'manual' }或 cron 字符串，timeout为Duration | HumanDuration，cron 支持可选的秒字段（* * * * * *六段格式）。当前版本还额外支持{ cron: '...' }写法（见下文 GitHubOrgEntityProvider 示例），比 next.2 时更加完善。

配套变更ebbec677e1还修正了任务"下次运行时间"的计算逻辑，避免某些边界条件下调度偏移。

七、GitHubOrgEntityProvider：支持 schedule 选项

变更a7de43f648让GitHubOrgEntityProvider.fromConfig像其他实体提供者一样支持schedule选项，从而可以直接接入公共任务调度器（backend-tasks）周期性刷新 GitHub 组织成员数据，无需自行编写定时逻辑。变更日志给出的用法如下（原文档示例，位于packages/backend/src/plugins/catalog.ts）：

builder.addEntityProvider( GitHubOrgEntityProvider.fromConfig(env.config, { id: 'production', orgUrl: 'https://github.com/backstage', schedule: env.scheduler.createScheduledTaskRunner({ frequency: { cron: '*/30 * * * *' }, timeout: { minutes: 10 }, }), logger: env.logger, }), );

这里的frequency同时体现了第六节的成果：cron 表达式与人类可读对象可以混合使用。该提供者的实现位于 plugins/catalog-backend-module-github/src/providers/GithubOrgEntityProvider.ts，同目录下的GithubEntityProvider、GithubMultiOrgEntityProvider也是同类实体提供者的参考实现。

八、搜索：结果高亮与批量索引性能提升

1. 搜索结果高亮匹配词

变更3a74e203a8贯穿搜索全链路：从search-backend-module-elasticsearch生成高亮字段，到search-common/search-react传递高亮数据，再到各前端组件渲染。启用方式（来自变更日志，原文档针对packages/app/src/components/search/SearchPage.tsx）：

- {results.map(({ type, document }) => { + {results.map(({ type, document, highlight }) => { switch (type) { case 'software-catalog': return ( <CatalogSearchResultListItem key={document.location} result={document} + highlight={highlight} /> ); case 'techdocs': return ( <TechDocsSearchResultListItem key={document.location} result={document} + highlight={highlight} /> ); default: return ( <DefaultResultListItem key={document.location} result={document} + highlight={highlight} /> ); } })}

涉及包：@backstage/plugin-catalog、@backstage/plugin-techdocs、@backstage/plugin-search、@backstage/plugin-search-react、@backstage/plugin-search-common、@backstage/plugin-search-backend-module-elasticsearch等，均在本版本中同步更新。

2. 索引批量由 100 提升至 1000

变更71d3432710将搜索索引写入的批量大小从 100 提升到 1000（search-backend-module-elasticsearch与search-backend-module-pg均生效）。变更日志明确提示影响：索引运行期间后端可能略微增加内存占用，但大型文档集合的索引性能会显著提升。如果你运行的是大目录实例，升级后应留意后端内存曲线。

九、create-app 模板改进：更易维护的脚手架

@backstage/create-app（0.4.27-next.2）带来四项模板级改进：

1. 搜索 collator 调度简化：与第六节一致，移除模板中luxon依赖，改用人类可读对象。若你的实例中luxon仅用于调度，可一并移除packages/backend/package.json中的"luxon": "^2.0.2"，并将packages/backend/src/plugins/search.ts中的Duration.fromObject(...)全部替换为{ ... }对象（含initialDelay）；
2. .dockerignore优化：由原来只放行packages/backend/dist改为按目录排除源码与 node_modules，新增后端包时无需再手工维护排除规则：

cypress microsite node_modules - packages - !packages/backend/dist + packages/*/src + packages/*/node_modules plugins

3. 示例 catalog 数据：模板新增顶层examples目录，包含简单实体、组织数据与一个软件模板，方便新项目开箱即有演示数据；
4. 搜索结果高亮：模板应用同步接入第八节的highlight渲染。

十、TechDocs：Addon 生态起步（Settings 位置与 TextSize）

本版本是 TechDocs Addon 机制的重要里程碑：

• @backstage/plugin-techdocs（1.1.1-next.2）在文档页面的 sub header 中新增菜单，用于承载渲染 TechDocs Addon（变更52419be116）；
• @backstage/plugin-techdocs-react（0.1.1-next.2）新增名为Settings的 Addon 位置，专门留给"自定义阅读体验"类的 Addon；
• @backstage/plugin-techdocs-module-addons-contrib（0.1.0-next.2）提供了首个内置 AddonTextSize，允许用户把文档正文字号写入浏览器 localStorage。

在 Backstage 应用中启用TextSize的写法（来自变更日志）：

import { DefaultTechDocsHome, TechDocsIndexPage, TechDocsReaderPage, } from '@backstage/plugin-techdocs'; import { TechDocsAddons } from '@backstage/plugin-techdocs-react/alpha'; +import { TextSize } from '@backstage/plugin-techdocs-module-addons-contrib'; const AppRoutes = () => { <FlatRoutes> // other plugin routes <Route path="/docs" element={<TechDocsIndexPage />}> <DefaultTechDocsHome /> </Route> <Route path="/docs/:namespace/:kind/:name/*" element={<TechDocsReaderPage />} > <TechDocsAddons> + <TextSize /> </TechDocsAddons> </Route> </FlatRoutes>; };

自研 Addon 的声明方式（来自plugin-techdocs-react变更说明）：

const TextSize = techdocsModuleAddonsContribPlugin.provide( createTechDocsAddonExtension({ name: 'TextSize', location: TechDocsAddonLocations.Settings, component: TextSizeAddon, }), );

同时@backstage/plugin-techdocs-addons-test-utils（0.1.0-next.1）修复了 DOM 中含<img />标签时无法测试 Addon 的问题，并允许通过继承TechDocsAddonTester定制测试配置，为 Addon 开发者提供了测试基础。

十一、其他值得关注的补丁

• Kubernetes 插件（plugin-kubernetes0.6.5-next.2、plugin-kubernetes-backend0.5.1-next.1、plugin-kubernetes-common0.2.10-next.0）：新增 Azure Identity 认证提供者与 AKS 仪表盘格式化器（1ef98cfe48）；
• Catalog 后端（plugin-catalog-backend1.1.2-next.2）：修复isGroupEntity返回值类型（16a40ac4c0）；parseEntityTransformParams支持包含.的字段键（如backstage.io/origin-location），可基于带点的 annotation 查询实体（2909746147）；
• CLI（@backstage/cli0.17.1-next.2）：create-github-app命令新增读写权限交互提示，简化 GitHub App 创建流程（632be18bbc）；
• 可访问性（core-components0.9.4-next.1、plugin-catalog-react1.1.0-next.2）：Select 组件支持键盘操作（55f68c386a）、Sidebar NAV 增加aria-label、AboutField 改用 h2 变体（2bcb0a0e2b）、过滤器菜单项支持键盘访问（57f41fb8d6）；
• Azure DevOps（plugin-azure-devops0.1.21-next.2 等）：新增 Azure Git Tags 实体视图（ac14fcaf38）；
• Org 插件（plugin-org0.5.5-next.2）：修复EntitiyMembersListCard在特定屏幕宽度与名字长度组合下的溢出问题（dfee1002d7）；
• Bazaar 插件（plugin-bazaar0.1.20-next.2）：导出SortView组件供直接复用（84c9e35a2f）。

十二、升级建议

1. Rails 动作使用者优先处理：allowedImageNames是唯一标注 BREAKING 的变更，升级后立即生效，需先配置白名单；
2. 自定义 UrlReader 作者提前适配：stream()未来将成为必需方法，建议在升级backend-common时一并实现；
3. 拥抱人类可读调度：若项目未在其他地方使用luxon，可按第六、九节移除该依赖并替换调度写法，降低依赖面；
4. 搜索大目录实例关注内存：批量从 100 提到 1000 后，观察索引运行期的内存占用；
5. TechDocs 用户可选启用 TextSize：Addon 机制已可用，可按第十节接入。

完整的包级依赖变更矩阵（含所有 Patch 级依赖联动）见 docs/releases/v1.2.0-next.2-changelog.md 原文；正式版 v1.2.0 的最终说明见 docs/releases/v1.2.0.md。

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