
Backstage v1.29.0-next.0 变更全解析Scaffolder 虚拟化、外部路由禁用、Root Health Service 与集成增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章基于 Backstage 仓库的 v1.29.0-next.0 变更日志系统梳理该版本在backstage/core-app-api、backstage/plugin-scaffolder、backstage/plugin-scaffolder-backend、backstage/backend-defaults、backstage/integration等核心包中的新增能力、行为变化与缺陷修复。阅读本文后你将掌握如何通过配置文件禁用外部路由绑定、如何利用 Scaffolder 的虚拟化列表与 Bitbucket Cloud 自动补全、如何启用后端 Root Health Service 的健康检查端点以及 GitLab 用户导入限流、通知按主题过滤等实用配置方法。1. 版本概览一次面向平台工程实战的增量发布v1.29.0-next.0 是 Backstage 1.29 系列的预发布next版本涵盖从核心运行时、CLI 到 Catalog、Scaffolder、TechDocs、通知系统等数十个包的联动升级。整体看本次版本的重点集中在三块前端应用装配层新增通过配置禁用外部路由的能力修复默认目标default target引入后外部路由无法被关闭的问题Scaffolder 体验与性能EntityPicker / MultiEntityPicker 引入虚拟化列表、RepoUrlPicker 支持 Bitbucket Cloud 自动补全、OwnedEntityPicker 支持catalogFilter数组后端新增autocomplete扩展点与 GCP 工作区序列化后端可观测性与集成backend-defaults 新增 Root Health Service健康检查端点GitLab 目录提供restrictUsersToGroup用户导入限流Bitbucket Server 模块改为动态获取默认分支等。下文按主题拆解这些变更并给出对应的配置示例与源码依据。2. 通过配置禁用外部路由core-app-api / frontend-app-api2.1 变更内容与背景backstage/core-app-api1.13.0-next.0变更号d3c39fc允许通过配置禁用外部路由external routes。此前在引入了默认目标default target机制之后外部路由一旦拥有默认目标就无法再被应用层关闭本变更恢复了这种可关闭能力。外部路由ExternalRouteRef是 Backstage 前端系统中用于跨插件链接的解耦手段插件之间不直接互相依赖而是通过外部路由引用 应用层的路由绑定route bindings把两个插件的页面链接起来。路由绑定在应用启动时解析一次之后在整个应用生命周期内用于解析具体的路由路径详见 docs/frontend-system/architecture/36-routes.md。2.2 配置示例在应用的app-config.yaml中增加如下配置即可禁用某条外部路由app: routes: bindings: # 该配置的效果是在 Scaffolder 模板列表视图中移除 # 用于注册新 Catalog 实体的按钮 scaffolder.registerComponent: false把绑定值设为false意味着外部路由不再解析到任何目标路由。例如scaffolder.registerComponent是 Scaffolder 插件暴露的外部路由引用禁用后模板列表页面上就不会再渲染注册新组件的入口按钮。2.3 源码级的解析优先级从实现看路由绑定解析逻辑位于 resolveRouteBindings.ts其处理顺序从高到低为代码内回调绑定bindRoutes具有最高优先级配置文件绑定app.routes.bindings优先级次之且只有当该外部路由尚未在代码中被绑定或禁用时才会生效默认目标default target兜底优先级最低仅对既未绑定也未禁用的外部路由生效。这意味着即使某外部路由定义了默认目标只要配置中显式将其设为false它依然可以被关闭。配置项的取值约束也可以在源码中看到app.routes.bindings的值必须是非空字符串或false否则会报错Invalid config at app.routes.bindings[...], value must be a non-empty string or false同时绑定双方必须是真实存在的路由引用否则分别报... is not a valid external route与... is not a valid route。对应的单元测试覆盖在 resolveRouteBindings.test.ts 中包括mySource: false的禁用场景。3. Scaffolder 前端虚拟化列表与 Bitbucket Cloud 自动补全backstage/plugin-scaffolder1.22.0-next.0是本次前端改动最集中的包。3.1 EntityPicker / MultiEntityPicker 虚拟化变更52b6db0和3583ce5为EntityPicker与MultiEntityPicker引入列表虚拟化virtualization解决大型数据集下的性能问题同时将可复用的VirtualizedListbox组件抽取出来。源码中EntityPicker与MultiEntityPicker都通过ListboxComponent{VirtualizedListbox}使用该组件见 EntityPicker.tsx 与 MultiEntityPicker.tsxMyGroupsPicker也同样接入可复用组件定义在 VirtualizedListbox.tsx其行为由 VirtualizedListbox.test.tsx 覆盖验证。从源码结构可以推断虚拟化列表只渲染可视区域内的行从而避免在实体数量达到数千甚至更多时一次性渲染全部 DOM 节点显著降低滚动卡顿与内存占用。对大规模 Catalog 场景下使用实体选择器的模板来说这是一项直接可感知的体验优化。3.2 RepoUrlPicker 的 Bitbucket Cloud 自动补全变更b5deed0让RepoUrlPicker在bitbucketCloud集成上支持自动补全autocompletebackstage/plugin-scaffolder-react1.10.0-next.0同步跟随。同时backstage/plugin-bitbucket-cloud-common0.2.21-next.0新增了 autocomplete handler用于为RepoUrlPicker提供自动补全选项。3.3 OwnedEntityPicker 支持 catalogFilter 数组变更89c44b3为OwnedEntityPicker增加catalogFilter数组支持允许通过多个过滤条件组合筛选我拥有的实体列表丰富了模板参数表单的过滤表达能力。3.4 Azure 仓库 owner 字段修复变更661b354修复了RepoUrlPicker在azure集成下仍然强制要求owner字段的问题该修复同样应用到backstage/plugin-scaffolder-backend-module-azure0.1.13-next.0与backstage/plugin-scaffolder-node0.4.7-next.0。4. Scaffolder 后端autocomplete 扩展点与 GCP 工作区序列化4.1 新增 autocomplete 扩展点backstage/plugin-scaffolder-backend1.23.0-next.0变更b5deed0新增autocomplete扩展点允许注册额外的 autocomplete handler。在 ScaffolderPlugin.ts 中可以看到autocompleteHandlers: Recordstring, AutocompleteHandler的装配并通过 router.ts 的autocompleteHandlers?参数注入路由层相关测试位于 router.test.ts。这为模板作者与平台团队提供了自定义仓库/字段自动补全逻辑的后端入口。4.2 GCP 工作区序列化变更0b52438为backstage/plugin-scaffolder-backend-module-gcp0.1.0-next.2与 Scaffolder 后端本体新增将 Scaffolder 工作区序列化到 GCP bucket的能力。这意味着 Scaffolder 任务的中间工作区文件可以被持久化到 Google Cloud Storage为长任务恢复、跨节点执行或多副本部署提供基础。4.3 其他后端修复62d1fe3修复 dry-run试运行模式下用户实体未被获取的问题da90cce将esbuild依赖升级到^0.21.06a4ad4ebitbucket-server 模块不再硬编码targetBranch而是从 Bitbucket 仓库动态获取默认分支避免当仓库默认分支不是master例如main时因未提供targetBranch而报错。5. GitHub 环境创建自定义标签策略backstage/plugin-scaffolder-backend-module-github0.4.0-next.0通过变更70c4b36支持在创建 GitHub 环境时自定义标签策略tag policies让github:environment:create相关动作可以按团队规范约束环境标签。同时变更4410fed修复了该动作在创建环境变量与 Secrets 时 octokit 调用缺少 owner 与 repo 参数的问题。6. 后端基础Root Health Service 与健康检查端点6.1 新增能力backstage/backend-defaults0.3.3-next.0与backstage/backend-plugin-api0.6.21-next.0通过变更53ced70新增 Root Health Service为后端提供健康检查端点backstage/backend-test-utils0.4.3-next.0同步在mockServices中加入了该服务的 mock。6.2 端点路径与行为健康路由由 createHealthRouter.ts 实现暴露两个端点端点作用/.backstage/health/v1/liveness存活探针只要服务进程仍在响应即返回成功/.backstage/health/v1/readiness就绪探针服务未就绪如仍在启动阶段时返回503在 rootHttpRouterServiceFactory.test.ts 中可以看到完整的验证用例就绪探针在服务未就绪时返回503就绪后返回200。此外该端点支持通过backend.health.headers配置自定义响应头键值必须为非空字符串配置类型错误或空值会触发对应报错。6.3 时间计划修复变更083eaf9修复了 ISO 8601 时长ISO durations无法再用于计划任务调度的问题涉及backend-defaults、backend-plugin-api、backend-tasks以及catalog-backend-module-ldap等多个包。7. 集成层与目录提供方增强7.1 Bitbucket Cloud token 支持backstage/integration1.13.0-next.0变更b5deed0为bitbucketCloud集成新增token配置支持使 Bitbucket Cloud 相关操作可以使用 token 进行认证。7.2 GitLab 用户导入限流backstage/plugin-catalog-backend-module-gitlab0.3.20-next.0变更8db30ad为 GitLab 配置新增可选布尔键catalog.providers.gitlab.your-org.restrictUsersToGroupcatalog: providers: gitlab: your-org: host: gitlab.com group: my-group restrictUsersToGroup: true设为true时Backstage 只导入group键指定组中的用户而不是组织自托管/根组SaaS下的所有用户默认值为false不设置时保持原有导入行为不变。该配置适合在 GitLab 用户规模较大、希望控制目录中用户实体数量的场景下使用。7.3 Catalog 错误日志模块变更97caf55新增backstage/plugin-catalog-backend-module-logs0.0.1-next.0该模块订阅 Catalog 事件并将其记录为日志让 Catalog 错误排查变得更简单。8. 通知系统与 TechDocs 修复backstage/plugin-notifications-backend0.3.2-next.0变更d7b8ca5新增按 topic 过滤通知的选项backstage/plugin-org0.6.27-next.0变更c307ef4为EntityMembersListCard组件新增relationType属性允许通过除memberOf之外的其他关系展示组成员同时将relationsType属性弃用改为命名更准确的relationAggregationbackstage/plugin-techdocs1.10.7-next.0与plugin-techdocs-react1.2.6-next.0变更8ac9ce5修复了TechDocsReaderPageProvider在调用setShadowDom时不重新渲染导致useShadowDomhooks 状态不一致的问题——此前该缺陷会造成 TextSize 插件的调整在页面导航后不生效backstage/plugin-catalog-react1.12.2-next.0变更2030962让EntityOwnerPicker在modeonly-owners下优先显示metadata.title或spec.profile.displayName而非metadata.namebackstage/core-components0.14.9-next.0变更d4ffdbb修复Select组件在空字符串 placeholder 时报错的问题。9. CLI 与后端模板改进backstage/cli0.26.10-next.0本次包含多项体验修复e2e320c移除后端插件模板中未使用的winston与yn依赖并将msw模板版本升级到2.3.1从 v1 起步再切换到 v2 成本较高直接以 v2 起步更省事0540c5a修正backstage-cli new创建plugin-common包时的输出文案从错误的Creating backend plugin...改为准确的Creating common plugin package...7652db4仅在真正使用时才引导bootstrapglobal-agentf0c0039修复 CLI 阻止从 1.28 升级的问题d228862默认后端插件模板改用非弃用的错误处理中间件a60d73b修复后端模板中若干导致主仓库 lint 失败的细节问题。10. 升级与版本对照速查本次发布的核心包版本对照如下均为-next.0预发布版本号包版本backstage/core-app-api1.13.0-next.0backstage/core-plugin-api1.9.3backstage/integration1.13.0-next.0backstage/plugin-scaffolder1.22.0-next.0backstage/plugin-scaffolder-react1.10.0-next.0backstage/plugin-scaffolder-backend1.23.0-next.0backstage/plugin-scaffolder-backend-module-github0.4.0-next.0backstage/backend-defaults0.3.3-next.0backstage/backend-plugin-api0.6.21-next.0backstage/cli0.26.10-next.0backstage/config1.2.0backstage/catalog-model1.5.011. 结语v1.29.0-next.0 体现了 Backstage 在大规模实体数据下的前端性能、平台自服务的可配置性与后端运维可观测性三个方向的持续投入无论是用配置关闭外部路由的灵活装配、Scaffolder 实体选择器的虚拟化渲染还是 Root Health Service 提供的标准健康检查端点都为开发者门户的生产化落地提供了更扎实的基础。若你正在升级 Backstage建议重点关注 Scaffolder 相关包与 backend-defaults 的变更前者直接影响模板表单体验后者影响后端健康检查与容器编排集成方式。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考