Backstage v1.23.0-next.0 版本解读路由绑定配置简化、脚手架多选实体与 Kubernetes 认证增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文基于 v1.23.0-next.0 变更日志 编写面向需要跟随 Backstage 迭代升级的开发者与平台工程师。这一预发布版本覆盖约 90 个包的版本变化核心看点集中在四个方面新版前端系统的app.routes.bindings路由绑定配置被大幅简化破坏性变更、Scaffolder 首次引入可恢复任务Recoverable Tasks与全新的MultiEntityPicker多选字段、Kubernetes 插件在认证维度mTLS、googleServiceAccount、自定义 authMetadata上显著增强以及 OIDC/Okta 等认证 Provider 向独立模块化迁移。读完本文你将掌握这些变更的具体形态、配置写法、升级影响面以及仓库中对应的源码实现位置可直接据此规划升级路径。一、版本背景与升级定位v1.23.0-next.0是 Backstage v1.23.0 系列的第一个 next 预发布版本。在 Backstage 的发布节奏中next.0用于让社区尽早验证新功能与破坏性变更因此本文涉及的 API 形态在正式版发布前仍可能微调。从 docs/releases 目录的版本序列看这是 v1.22.0 之后、v1.23.0 正式版之前的中间快照。本次变更的包数量约 90 个其中Minor Changes新功能 / 行为变化集中在 frontend-app-api、scaffolder、scaffolder-backend、kubernetes-react、cloudbuild 等包Patch Changes缺陷修复与内部重构覆盖绝大多数插件包多为依赖更新与细节修正仓库自身的 example-app、example-backend 等示例应用也随版本同步升级可用于对照验证。二、破坏性变更app.routes.bindings配置大幅简化2.1 变更内容backstage/frontend-app-api0.6.0-next.0引入了本次版本最值得关注的破坏性变更app.routes.bindings的 app-config 映射格式被简化映射两侧不再需要完整写出plugin.id.routeId三段式标识只需指定「插件 ID 路由 ID」即可。旧格式v1.23.0-next.0 之前app: routes: bindings: plugin.catalog.externalRoutes.viewTechDoc: plugin.techdocs.routes.docRoot plugin.catalog.externalRoutes.createComponent: plugin.catalog-import.routes.importPage新格式本版本起app: routes: bindings: catalog.viewTechDoc: techdocs.docRoot catalog.createComponent: catalog-import.importPage对照可见左侧由plugin.catalog.externalRoutes.viewTechDoc简化为catalog.viewTechDoc右侧由plugin.techdocs.routes.docRoot简化为techdocs.docRoot。2.2 源码层面的解析逻辑在仓库中这段配置的实际消费逻辑位于 packages/frontend-app-api/src/routing/resolveRouteBindings.ts。该函数通过config.getOptionalConfig(app.routes.bindings)读取映射第 115-117 行随后以routesById.externalRoutes和routesById.routes两个索引查找映射两侧的路由引用左侧键必须是已注册的 external route否则报ROUTE_NOT_FOUND右侧值必须是非空字符串或falsefalse用于显式禁用某条外部路由否则报ROUTE_BINDING_INVALID_VALUE右侧值必须在routesById.routes中能找到对应路由否则报ROUTE_NOT_FOUND。同时该函数定义了完整的绑定优先级注释第 88、114、164 行代码内bindRoutes回调绑定 app-config 配置绑定 路由默认目标defaultTarget兜底。也就是说即使你不写任何app.routes.bindings配置插件声明的默认目标仍会生效配置只用于覆盖默认行为。2.3 升级影响与处理建议由于这是破坏性变更升级到该版本后检查你的app-config.yaml中是否存在app.routes.bindings配置块若存在请按上述新格式改写为pluginId.routeId形态若同时使用了backstage/core-compat-api的旧版插件兼容层本版本中convertLegacyApp转换出的插件也已将routes与externalRoutes一并纳入见 packages/core-compat-api 的变更条目可正常参与配置绑定。三、新版前端系统IconsApi 与配置式图标本版本在 frontend-plugin-api 中新增了初始版IconsApi定义packages/frontend-plugin-api/src/apis/definitions/IconsApi.ts并在 frontend-app-api 中给出了实现createApp与createSpecializedApp现在支持通过icons选项注入图标。需要特别说明的是变更日志明确标注这是一个过渡方案stop-gap——从长期看图标应当通过扩展extension机制安装而非集中配置引入IconsApi只是为了与既有前端系统在能力上对齐保证迁移期功能对等。因此生产项目不必急于迁移到配置式图标只需知晓该 API 的存在与定位。同批的backstage/core-compat-api0.1.2-next.0也做了配套工作向后兼容 Provider 在实现旧版AppContext时会使用新的ComponentsApi与IconsApi对应变更1fa5041保证旧插件在新系统下仍能正常渲染。四、软件目录可配置表格列与图标策略调整4.1CatalogTable.defaultColumnsFuncbackstage/plugin-catalog1.17.0-next.0导出了CatalogTable.defaultColumnsFunc允许你在为某些 Kind自定义CatalogTable /列的同时对其他 Kind 沿用默认列。仓库中的实现位于 plugins/catalog/src/components/CatalogTable/CatalogTable.tsx第 305 行将defaultColumnsFunc挂载为静态属性默认列逻辑定义在 plugins/catalog/src/components/CatalogTable/defaultCatalogTableColumnsFunc.tsx。典型用法是用defaultColumnsFunc得到默认列数组再针对特定 Kind 追加或替换列。4.2 图标默认值调整本版本对软件目录的默认图标做了一轮统一916da47、f899eec、797a329未知实体的默认图标由问号帮助图标help icon改为不显示图标kind: resource的默认图标改为存储storage图标修复了 System 与 Template 图标不一致的问题。这些调整同时作用于 app-defaults、catalog-graph、catalog-import、entity-validation 等相关包属于纯视觉层面的体验优化不涉及配置变更。五、ScaffolderMultiEntityPicker 字段与可恢复任务5.1 新字段MultiEntityPickerbackstage/plugin-scaffolder1.18.0-next.0引入了MultiEntityPicker表单字段用于在模板参数中一次性选择多个 Catalog 实体。其字段 Schema 位于 plugins/scaffolder/src/components/fields/MultiEntityPicker/schema.ts输出类型为z.array(z.string())实体引用字符串数组并支持以下ui:options选项类型说明defaultKindstring默认实体 Kind该 Kind 的选项在显示时不加前缀defaultNamespacestring \| false默认命名空间该命名空间的选项显示时不加前缀catalogFilter单个或数组形式的过滤表达式用于过滤可选择的实体key-value 表达式支持{ exists: boolean }与字符串数组值allowArbitraryValuesboolean是否允许任意输入默认true该字段同时提供了新前端系统下的 alpha 注册版本plugins/scaffolder/src/alpha/fields/MultiEntityPicker.ts通过createFormField注册为MultiEntityPicker。模板中的使用方式与既有EntityPicker一致区别在于输出为数组、支持catalogFilter多条件过滤。5.2 可恢复任务Recoverable Tasks首次引入11b9a08变更在 scaffolder-common、scaffolder-node、scaffolder-react、scaffolder-backend、scaffolder 五个包中同步引入了第一版可恢复任务。变更日志明确标注为 first version说明这是能力雏形脚手架任务在执行中断后具备恢复执行的基础机制后续版本会在此基础上完善。该特性面向的是长时间运行、可能被中断的模板任务场景升级后可在任务列表Task List中看到相应的状态呈现同版本还移除了任务列表标题中的 alpha 标识da059d7。5.3 内置模块清单瘦身新后端系统下需显式注册backstage/plugin-scaffolder-backend1.21.0-next.0在新后端系统下收紧了内置模块列表变更e9a5228。此前随 Scaffolder 后端自动加载的一批 Provider 模块现在需要你通过backend.add(...)显式安装涉及模块包括backstage/plugin-scaffolder-backend-module-githubbackstage/plugin-scaffolder-backend-module-gitlabbackstage/plugin-scaffolder-backend-module-bitbucketbackstage/plugin-scaffolder-backend-module-giteabackstage/plugin-scaffolder-backend-module-gerritbackstage/plugin-scaffolder-backend-module-confluence-to-markdownbackstage/plugin-scaffolder-backend-module-cookiecutterbackstage/plugin-scaffolder-backend-module-railsbackstage/plugin-scaffolder-backend-module-sentrybackstage/plugin-scaffolder-backend-module-yeoman这些模块包在同一版本中也都补齐了「默认导出模块实例」Exporting a default module for the new Backend System例如 plugins/scaffolder-backend-module-azure、plugins/scaffolder-backend-module-cookiecutter 等。迁移到新后端系统后若你的模板依赖上述任一能力GitHub 拉取/发布、cookiecutter、Rails 等必须在后端入口显式注册对应模块否则相关 action 将不可用。旧后端系统createRouter方式不受影响。5.4 Bitbucket PR 流程增强scaffolder-node变更3a9ba42新增了「克隆仓库、创建分支、添加文件、提交并推送」等函数用于在 Bitbucket 拉取请求 action 中向已存在的 PR 追加内容scaffolder-backend-module-bitbucket变更fc98bb6据此增强了 PR action。这意味着 Bitbucket 场景下的「先建 PR、后补文件」工作流从底层函数上得到支持。六、Kubernetes 插件认证能力集中增强v1.23.0-next.0中 Kubernetes 相关包kubernetes-react、kubernetes-backend、kubernetes-node、kubernetes-common迎来一波认证与配置能力更新6.1 Pod 执行终端默认关闭破坏性变更backstage/plugin-kubernetes-react0.3.0-next.0将 Pod 执行终端pod exec terminal默认改为禁用原因是官方已知其在多个场景下无法正常工作。如需按自己的风险重新启用设置kubernetes: podExecTerminal: enabled: true仓库中对应的开关读取逻辑位于 plugins/kubernetes-react/src/hooks/useIsPodExecTerminalEnabled.ts通过configApi.getOptionalBoolean(kubernetes.podExecTerminal.enabled)读取未配置时返回undefined并走禁用分支。同包还修复了 XtermJS 的 CSS 导入536f67d以及 OIDC auth provider 集群下代理端点失效的问题db1054b。6.2 新增googleServiceAccount登录方式kubernetes-backend变更7278d80新增googleServiceAccount认证方式在app-config.yaml的 kubernetes 配置中通过authProvider键即可配置使用该方式。6.3 mTLS x509 客户端证书认证变更f180cba为 Kubernetes 集群接入增加了mTLS双向 TLSx509 客户端证书认证能力相关支持落在kubernetes-backend与kubernetes-node两个包中适用于对集群启用客户端证书认证的强安全场景。6.4 自定义 authMetadata 与presentAuthMetadatakubernetes-node的AuthenticationStrategy接口新增presentAuthMetadata方法变更a775596允许自定义认证策略把自定义认证元数据暴露给前端通过 clusters endpoint 返回app-config 中集群的authMetadata属性可用于存放自定义认证元数据变更7f6ff25AWS 认证策略现在可以自定义x-k8s-aws-id头值变更daad576通过 Catalog 实体metadata.annotations中的kubernetes.io/x-k8s-aws-id或在 app-config 集群authMetadata块中指定。这对于多区域存在同名 AWS 集群的场景特别有用——可以让不同区域的集群使用不同的逻辑名称区分同时仍用同一个 ID 生成 token。该变更同时落在kubernetes-backend与kubernetes-common修复了未支持的 service locator 方法会打印误导性错误信息的问题7233f57。七、认证体系OIDC Provider 模块化与 EntraID 自定义 Scope7.1 OIDC Provider 迁移到独立模块本次版本创建了新的backstage/plugin-auth-backend-module-oidc-provider0.1.0-next.0包变更5d2fcba承载 OIDC auth provider 的迁移auth-backend同步改用该外部模块变更5d2fcba同时依赖passport升级到^0.7.0变更8afb6f4。此前已经外部化的 Microsoft Provider 也重新被auth-backend使用变更a3f1fa3。这与 Scaffolder 模块清单瘦身是同一方向新后端系统下认证 Provider 趋向于独立模块、按需注册。7.2 Okta 与 Microsoft EntraID 细节增强plugin-auth-backend-module-okta-provider0.0.3-next.0为配置 Schema 补上了缺失的additionalScopes选项变更cd5114cplugin-auth-backend-module-microsoft-provider0.1.5-next.0支持使用自定义 scope 进行 Microsoft EntraID 登录变更1ff2684。八、OpenAPI 规范以插件 ID 作为 info.title一批后端包catalog-client、catalog-backend、search-backend、todo-backend、repo-tools将 OpenAPI 规范的标题从包名改为插件 ID变更04907c3、126c2f9。对应地repo-tools的 OpenAPI 客户端模板改为读取info.title作为插件 IDinfo: title: yourPluginId - title: internal/plugin-*-backend servers: - / - - yourPluginId同时repo-tools的schema openapi generate-client命令新增了对oneOf的支持变更b10c603。若你的代码依赖从 OpenAPI 元数据中推导插件 ID需要同步适配新的info.title约定。九、测试基建与工具链更新9.1 单元测试后自动清理数据库backstage/backend-common0.21.0-next.0与backstage/backend-test-utils0.3.0-next.0现在会在数据库实例非 Docker 运行的情况下于单元测试结束后自动删除测试数据库变更e85aa98减少本地反复跑测试时的残留库。注意该行为仅在非 Docker 数据库实例下触发。9.2 前端测试工具backstage/test-utils1.5.0-next.0的TestAppOptions新增components选项会被转发给createAppbackstage/frontend-test-utils0.1.2-next.0随frontend-app-api破坏性变更同步升级。9.3 CLI 与工程化backstage/cli0.25.2-next.0为可选authapp 入口点增加实验性支持c624938后端模块模板改为将模块实例作为包默认导出c7259dcbackstage/eslint-plugin0.1.5-next.0新增backstage/no-top-level-material-ui-4-imports规则禁止从 Material UI v4 包顶层导入配合一批插件从命名导入改为默认导入为 MUI v4 到 v5 迁移铺路涉及 azure-devops、devtools、linguist 等包backstage/create-app0.5.11-next.0将packages/app与根package.json的 types 解析切换到 React 18并同步更新了testing-library/*依赖与App.test.tsx的测试写法变更aeec29cbackstage/plugin-app-backend0.3.58-next.0修复了包含注入配置的 JS 资源被强制缓存的问题9dfd57d避免配置更新后浏览器仍使用旧缓存。十、其他值得关注的插件级变更Cloud Buildcloudbuild构建列表视图默认按组件metadata.name匹配仓库名自动过滤新增可选注解google.com/cloudbuild-repo-name、google.com/cloudbuild-trigger-name、google.com/cloudbuild-location默认 global scope以调整过滤维度并将substitutions.BRANCH_NAME改为substitutions.REF_NAME使 Ref 字段正确填充同时附加 GCP 遥测 HTTP 头ef3cad4API Docsapi-docs新增supportedSubmitMethodsprop 透传给 Swagger UI可控制Try It Out允许执行的 HTTP 方法170c023Stack Overflowstack-overflow修复按 tag 查询时返回无关问题的问题c1bc331Azure DevOpsazure-devops优先使用更具体的dev.azure.com/build-definition注解可用于 monorepo 过滤cb0afaaSignalssignals、signals-backend、signals-node、signals-react四个包首次发布 0.0.1-next.0支持通过 signals 插件订阅与发布消息047beadExplore Backendexplore-backend新增对新后端系统的支持可通过backend.add(import(backstage/plugin-explore-backend))注册fd3d51c。十一、升级检查清单综合以上变更升级到v1.23.0-next.0前后建议按此清单核对路由绑定配置app.routes.bindings是否存在存在则改为pluginId.routeId新格式破坏性变更必查Scaffolder 模块使用新后端系统时检查所需 Provider 模块GitHub、GitLab、Bitbucket、cookiecutter 等是否已backend.add(...)显式注册Kubernetes确认是否需要 pod exec 终端默认已禁用如使用 AWS 多集群同名场景规划kubernetes.io/x-k8s-aws-id注解如启用新认证方式googleServiceAccount、mTLS核对 app-config 写法认证 ProviderOIDC 迁移至独立模块包确认依赖与注册方式OpenAPI若从 OpenAPI 元数据取插件 ID适配info.title新约定测试基建了解单元测试后数据库自动清理行为避免与本地数据管理方式冲突React 18create-app已切换 React 18 与新版testing-library既有测试写法可能需要对照 packages/app 更新。由于这是next.0预发布版本建议在非生产环境先行验证并持续关注后续next快照与正式版 v1.23.0 变更日志 中是否对上述行为做进一步调整。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考