Backstage v1.31.0 版本深度解析Backend System 1.0 稳定发布与新前端系统演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage v1.31.0 是开发者门户框架演进历程中的一个标志性版本全新的后端系统Backend System在历经多轮迭代后正式以 1.0 版本稳定发布同时新前端系统New Frontend System完成多轮 API 收口应用运行时模板化App Runtime Templating机制落地。本文以 官方 v1.31.0 发布说明 为骨架结合仓库内 v1.31.0 完整变更日志 及对应包源码逐项解读本版本的核心变更、破坏性改动与升级要点帮助你评估现有部署的迁移成本并快速完成版本升级。一、版本概览与升级路径v1.31.0 的完整包级变更记录保存在 docs/releases/v1.31.0-changelog.md 中按backstage/*包逐个列出 Major / Minor / Patch 变更。官方强烈建议所有 Backstage 项目紧跟最新版本具体升级操作步骤可参考 keeping-backstage-updated 指南。本次发布的核心主题可以概括为三个层面后端体系收编新后端系统稳定为 1.0旧式createRouter形态的后端插件开始进入淘汰通道前端体系收编新前端系统移除 V1 扩展支持全面转向 Blueprint 与模块Module模型运行时能力增强前端应用支持运行时配置模板化多个组件获得新的配置项与测试工具。需要特别提醒的是本版本包含多处BREAKING破坏性变更升级前建议对照本文第四、五节逐项检查自己的代码。二、核心里程碑Backend System 1.0 稳定发布原发布说明将本版本称为 Backend System 1.0 意味着新后端系统的 API 已经稳定在 2.0 之前不应再出现破坏性变更具体约束见 package versioning policy。新后端系统相比旧式“基于约定convention-based”的插件结构核心变化在于后端及其功能features通过依赖注入像拼图一样组合在一起插件可以动态扩展彼此的行为并复用一系列强大的核心服务core services。官方文档对后端系统的架构说明见 docs/backend-system/index.md迁移指引见 migrating backends 与 migrating plugins。主仓库与 community-plugins 仓库已经基本完成向新后端系统的迁移社区也正推进对已迁移插件的旧后端能力进行弃用清理。2.1 包版本状态与技术细节从 v1.31.0-changelog 可以确认以下包级事实晋升为 major version 1停止接收 0.x 的功能更新包v1.31.0 版本说明backstage/backend-app-api1.0.0后端应用运行时backend instance核心实现backstage/backend-plugin-api1.0.0后端插件 / 模块 / 服务工厂的公开 APIbackstage/backend-test-utils1.0.0后端测试工具含mockServices与createServiceMock等弃用并冻结停止更新backstage/backend-common0.25.0最后一个版本backstage/backend-tasks官方建议用上表中的三个 1.x 包加backstage/backend-defaults进行替换在渐进迁移期间仍可短期使用backstage/backend-common中的兼容适配器例如legacyPlugin/makeLegacyPlugin会自带 identity 与 token manager 的 shim 实现。被完全移除的核心服务coreServices.identitycoreServices.tokenManager这两项需要迁移到新的认证系统见 docs/auth/index.md 与仓库内相关教程。此外backstage/backend-defaults中旧式 token manager 的向后兼容回退也被移除——这意味着对新后端实例中不支持新认证系统的插件发起的请求将直接失败而不再静默回退到旧 token manager。因此升级时必须确保部署中的所有插件都运行在同一个新后端系统实例内新旧混合部署会引发认证问题。2.2 创建 API 的返回值形态变化重要破坏性变更changelog 中 ID 为d425fc4的变更贯穿了几乎所有后端包是本次升级中最需要留意的行为变化createBackendPlugin、createBackendModule、createServiceFactory的返回值从“一个返回 feature 的函数”变为直接返回BackendFeature/ServiceFactory对象createServiceFactory不再接受“以函数形式直接传入 options”的回调写法受此影响coreServices.*的 service ref 形态也随之变化。对测试代码的影响最直接如果之前写的是createBackendModule({...})()注意末尾多余的一对括号现在可以直接去掉这对括号。同样的写法也可能出现在packages/backend/src/index.ts中——在该文件中以backend.add(...)方式注册插件、模块与服务时请确认传入的是 feature 本身而不是调用后的结果。若之前依赖createServiceFactory传函数来注入选项可以改用新的 multiton 模式或将相关设置挪到 app-config 中。2.3 特性发现机制的演进discoveryFeatureLoaderbackstage/backend-defaults中弃用了featureDiscoveryServiceFactory/featureDiscoveryServiceRef取而代之的是新的discoveryFeatureLoader。它作为一个后端系统 feature loader会从当前package.json及其依赖中自动发现后端特性。changelog 给出的用法如下import { createBackend } from backstage/backend-defaults; import { discoveryFeatureLoader } from backstage/backend-defaults; const backend createBackend(); // ... backend.add(discoveryFeatureLoader); // ... backend.start();同样地backstage/backend-dynamic-feature-service中弃用了dynamicPluginsServiceRef/dynamicPluginsServiceFactory/dynamicPluginsServiceFactoryWithOptions改为使用dynamicPluginsFeatureDiscoveryLoader且该 loader 支持传入选项例如自定义moduleLoaderimport { createBackend } from backstage/backend-defaults; import { dynamicPluginsFeatureDiscoveryLoader } from backstage/backend-dynamic-feature-service; import { myCustomModuleLoader } from ./myCustomModuleLoader; const backend createBackend(); backend.add( dynamicPluginsFeatureDiscoveryLoader({ moduleLoader: myCustomModuleLoader, }), ); backend.start();2.4 其余值得关注的后端行为变化backstage/backend-app-api所有 backend 实例共享同一组process退出监听器退出时会等待所有实例关闭后再结束进程修复了测试中的EventEmitter泄漏告警依赖缺失时的错误信息现在会附带插件与模块 ID更易于定位问题。backstage/backend-defaultsDatabaseManager.forPlugin现在要求传入depslogger 与 lifecycle 服务并直接返回DatabaseServiceCacheManager.forPlugin直接返回CacheService不再需要额外的.getClient()调用新增skipMigrations: true配置项可在全局或按插件 ID 跳过数据库迁移cache 服务的 TTL 现在支持人类可读的时长格式如2h。backstage/backend-commonhost discovery 实现不再接受basePath选项dropDatabase函数被移除且无替代品。backstage/backend-test-utils新增mockErrorHandler工具用于在测试中 mock 错误中间件mockServices.rootConfig.mock与mockServices.rootHttpRouter.factory的定义得到修正。如果确实还有依赖 identity / token manager 的存量插件changelog 提供了在自有后端中手动重建这两个服务的示例identity 基于DefaultIdentityClienttoken manager 基于ServerTokenManager并开启allowDisabledTokenManager可作为短期过渡手段。三、新前端系统持续演进模块化收口v1.31.0 在新前端系统上做了一轮密集的 API 收口涉及多个破坏性移除与替代方案。3.1 新增 backstage/plugin-app 包新引入的 backstage/plugin-app 包plugins/app/src/plugin.ts负责承载内建扩展built-in extensions并为覆盖它们提供入口——通过appPlugin.override()可以对内建扩展进行定制。其配套的后端包backstage/plugin-app-backend也同步修复了依赖元数据问题。从源码结构看该插件下还细分了apis、extensions、components等目录体现了“内建能力模块化、可替换”的设计意图。3.2 namespace 不再必填默认取 pluginIdcreateExtension/createExtensionBlueprint/createFrontendModule等 API 的namespace参数不再要求显式提供未提供时默认使用其安装所在插件的 ID。这也意味着通过 ID 直接覆盖 API 时ID 可能因包含 pluginId 而发生变化见backstage/core-compat-api的对应破坏性说明。3.3 createExtensionOverrides 弃用改用 createFrontendModulecreateExtensionOverrides被弃用新方法 createFrontendModule 需要提供必填的pluginId用于声明所提供扩展要关联/覆盖/补全的目标插件。changelog 给出了对照迁移示例// Before createExtensionOverrides({ extensions: [ createExtension({ name: my-extension, namespace: my-namespace, kind: test, // ... }), ], }); // After createFrontendModule({ pluginId: my-namespace, extensions: [ createExtension({ name: my-extension, kind: test, // ... }), ], });从 createFrontendModule.ts 的源码可以确认模块会以pluginId作为解析扩展定义的默认 namespace并生成$$type: backstage/FrontendModule的模块对象当模块提供的扩展与插件内建扩展 ID 相同时模块中的扩展总是优先若目标插件不在应用中模块会被直接忽略。源码注释还推荐模块变量的命名规范为pluginIdModuleModuleName。此外createExtensionInput新增replaces选项允许将缺失的attachTo点重定向到新创建扩展的输入上例如attachTo: { id: app, input: themes }被重定向到api:app-theme的themes输入这是内建 API 从 app 扩展迁移到独立 API 扩展的技术基础。3.4 createApp 迁移到 frontend-defaultsbackstage/frontend-app-api中导出的createApp已被弃用应从backstage/frontend-defaults导入同名函数。这一设计与新后端系统“从backend-defaults获取默认实现”的模式对齐。新包 packages/frontend-defaults/src/createApp.tsx 提供默认的应用装配并附带CreateAppOptions类型与createPublicSignInApp用于创建公开入口的应用。同时createSpecializedApp现在创建的是不含默认结构/API 的“裸应用”如需原功能可安装app插件补齐。3.5 V1 扩展支持移除与 Blueprint 化V1 扩展支持被移除所有扩展必须使用数组形式的 outputs此前已弃用的对象形式不再被支持。旧式扩展创建器全部移除所有存在 Blueprint 对等物的createKindExtension创建器均已删除应迁移到KindBlueprint.make唯一的例外是createComponentExtension得以保留。createExtensionTester的.render()方法被移除应直接使用renderInTestApp配合tester.reactElement()完成渲染。ExtensionDefinition/ExtensionBlueprint类型参数收口为单一对象参数例如ExtensionDefinitionany, any改为ExtensionDefinitionExtensionDefinitionTConfig改为ExtensionDefinition{ config: TConfig }如需推断参数可借助ExtensionDefinitionParameters。这是一次即刻生效的破坏性变更但仅影响类型层面的使用不影响运行时行为。这些移除项对应的迁移指引记录在 前端系统迁移文档 的 1.30 / 1.31 小节。本版本另一个运行时细节是defaultConfigLoader现在会优先读取页面中script[typebackstage.io/config]标签内的 JSON 序列化AppConfig数组实现见 defaultConfigLoader.ts若存在这些标签则不再使用静态资源中注入的配置——这一机制与下文的 App Runtime Templating 直接衔接。四、App 运行时模板化App Runtime Templatingbackstage/plugin-app-backend在本版本获得重大能力升级支持在运行时注入前端配置的所有部分包括 public path 与模板化进index.html的配置值。4.1 构建产物变化index.html.tmplbackstage/cli的前端构建流程现在会额外输出一个index.html.tmpl文件详见 packages/cli/CHANGELOG.md 中0e1a817相关条目。该文件是未做模板化的index.html并带有一个backstage-public-pathmeta 标签由backstage/cli/config/webpack-public-path.js入口脚本在运行时据此设置 Webpack bundle 的运行时 public path。4.2 运行时模板化原理如果构建产物中存在index.html.tmplapp后端将基于自身持有的配置用它模板化生成新的index.html。核心实现在 injectConfigIntoHtml.ts读取index.html.tmpl内容常量HTML_TEMPLATE_NAME第 23 行通过 lodash 的compileTemplate以% ... %插值语法编译模板第 44-46 行向模板上下文注入config与publicPathpublicPath由app.baseUrl的路径部分解析而来见第 73-78 行的resolvePublicPath在/head前插入script[typebackstage.io/config]标签内含完整的AppConfig数组第 54-68 行并对/script、!--等序列做转义处理以避免注入破坏。从 router.ts 可以看到readFrontendConfig会结合后端配置、process.env与 config schema 读取前端配置若配置了app.disableConfigInjection: true则跳过该注入流程。4.3 关键行为影响Breakingchangelog590fb2d条目明确指出这是破坏性变更对部署形态产生两点影响必须把构建期配置交给后端模板化依赖 app 后端在运行时持有正确的前端配置public path 无需再在构建期硬编码只需在运行时为 app 后端插件提供正确的app.baseUrl即可。副作用是index.html会以易读的形式直接呈现前端配置这些数据此前也存在于前端但被注入并隐藏在静态 bundle 深处这反而有利于调试。该行为默认开启可通过配置关闭app: disableConfigInjection: true五、认证与权限相关变化5.1 Guest 认证不再阻塞生产启动backstage/plugin-auth-backend-module-guest-provider的行为发生重要变化不再因未设置dangerouslyAllowOutsideDevelopment而在生产环境启动时让后端直接启动失败改为在认证尝试时拒绝请求。此前“启动即失败”的模式可能引发连锁问题例如数据库迁移表被长期锁定。源码佐证位于 authenticator.ts当非开发环境且未开启auth.providers.guest.dangerouslyAllowOutsideDevelopment时抛出拒绝错误resolvers.ts 中的 sign-in resolver 也给出对应的提示信息指引在生产环境显式开启该配置项不建议。5.2 最后两个 auth provider 完成迁移Auth0 与 Bitbucket Server 两个后端认证 provider 迁移到了新后端模块backstage/plugin-auth-backend-module-auth0-provider0.1.0changelogd908d8c条目backstage/plugin-auth-backend-module-bitbucket-server-provider0.1.0changelog527d973条目。至此社区推动的 auth providers 迁移工作backstage/plugin-auth-backend内部实现全面改为基于新模块正式收官。相关模块与文档可在仓库的 plugins/auth-backend-module-* 系列 中找到。5.3 Catalog 新增权限点如果启用了权限系统见 permissions 概览需要关注两个新的权限保护点定义于 catalog-common/src/permissions.ts端点新增权限影响analyze-locationcatalog.location.analyze分析/注册位置的接口受权限保护validate-entitycatalog.entity.validate实体校验接口受权限保护若未调整策略启用了权限系统的部署中这些接口可能默认被拒绝访问请务必按需更新 permission policy。六、Catalog 生态改进6.1 新的 catalogServiceMock 测试工具backstage/plugin-catalog-node的/testUtils子路径新增catalogServiceMock用于在测试中注入 mock 或 fake 的 catalog 客户端。实现位于 catalog-node/src/testUtils/catalogServiceMock.tscatalogServiceMock(options?)返回一个基于内存存储的 fake catalog 客户端InMemoryCatalogClient可预置静态实体集合catalogServiceMock.factory(...)以createServiceFactory形式返回可注册到测试后端的 catalog 服务工厂catalogServiceMock.mock基于createServiceMock生成各方法均为jest.fn()的 mock 客户端getEntities、queryEntities、addLocation、validateEntity、analyzeLocation等约 20 个方法可按需覆写以做断言。用法示例测试中注入带预置实体的 fake catalogimport { catalogServiceMock } from backstage/plugin-catalog-node/testUtils; import { catalogServiceRef } from backstage/plugin-catalog-node; import { startTestBackend } from backstage/backend-test-utils; const fakeCatalog catalogServiceMock({ entities: [ { apiVersion: backstage.io/v1alpha1, kind: Component, metadata: { name: example } }, ], }); await startTestBackend({ features: [ catalogServiceMock.factory({ entities: /* ... */ }), // 或在需要断言时使用 catalogServiceMock.mock ], });这与其姊妹能力backstage/catalog-client/testUtils的InMemoryCatalogClient相互配合显著降低了测试涉及 catalog 交互时的 mock 成本。6.2 Catalog Client 性能优化与排序语义变化changelog1882cfe条目说明getEntities的排序逻辑从 catalog 客户端移入数据库查询完成。此前调用方在客户端侧执行排序在拉取大量实体时会产生显著 CPU 热点服务端化后大规模拉取场景下的调用方 CPU 占用有望明显下降。需要留意的是行为差异升级后客户端返回的实体顺序可能与旧版本不同。如果业务代码依赖旧客户端排序结果需要相应更新后端插件或调用代码同时by-query调用还修复了“按并非所有实体都存在的字段排序导致结果缺失”的问题53cce86条目。另外catalog-model为 Component kind 新增了dependencyOf属性配合既有dependsOn可双向构建依赖关系图。6.3 GitLab 组织 providerrelations 配置backstage/plugin-catalog-backend-module-gitlab的 GitLab org entity provider 新增relations配置项用于控制 GitLab 成员关系在 Backstage 中的建模方式原有allowInherited选项被弃用因为其语义现在可用relations: [INHERITED]表达。依据 config.d.tsrelations数组支持以下值对应 GitLab GraphQL 的GroupMemberRelation枚举取值含义DIRECT组的直接成员。始终包含即使未显式列出也无法排除INHERITED从父祖先组继承的成员DESCENDANTS来自子后代组的成员SHARED_FROM_GROUPS从其他组共享而来的成员配置示例CHANGELOG 原文catalog: providers: gitlab: development: relations: - INHERITED从 lib/client.ts 的实现可以看到relations会作为 GraphQL 分页查询的变量传入测试代码src/__testUtils__/handlers.ts也验证了不同relations组合下的成员拉取行为。同模块还新增includeUsersWithoutSeat配置项允许导入无付费席位的用户如 GitLab Free/SaaS默认false。七、Scaffolder 表单与字段修复7.1 liveOmit 与 omitExtraDataScaffolder 表单基于 rjsf新增对liveOmit与omitExtraData两个选项的支持用于裁剪用户提交数据中的多余字段避免最终收集到的参数包含 schema 之外的冗余数据。该能力由backstage/plugin-scaffolder与backstage/plugin-scaffolder-react同步提供changelog4baad34条目官方计划在本版本先行测试若表现稳定将在下一个 mainline 版本中提升为默认行为。7.2 SecretField 增强与 ReviewState 修复SecretField密钥字段现在支持从 schema 设置disabled、required以及minLength/maxLength约束并修复了嵌套对象中 required/disabled 不生效的问题changelog3ebb64f条目。ReviewState组件修复了嵌套字段ui:backstage选项的解析问题带重复尾段 key 的字段现在能全部展示key 的格式化改为以分隔完整 schema 路径8dd6ef6条目多步模板中 schema 选项处理问题也得到修复1f3c5aa条目secret 字段在 review 页面以固定数量的星号展示9a0672a条目。新增ui:backstage.review.name选项可为 review 页的自定义条目命名并支持渲染 schema 的title属性而非 key 名4512f71条目。7.3 其他 Scaffolder 相关变化新增publish:bitbucketCloud:pull-requestscaffolder actiondf9ae9e条目debug:logaction 支持列出文件内容f0c6b25条目OwnedEntityPicker的ui:options现在透传给EntityPicker因此可使用allowArbitraryValues、defaultNamespace等选项b0a5c9f条目TemplateListPage新增EntityOwnerPicker用于按 owner 过滤并移除重复标题5143616/0944334条目MultiEntityPicker在达到 JSONSchemamaxItems上限后自动禁用7976081条目backstage/plugin-scaffolder-backend的createRouter及关联类型被标记为 deprecated明确指引改用新后端系统初始化。八、Yarn v4 成为新项目默认使用backstage/create-app创建的新仓库现在默认采用 Yarn 4含其后的多个版本改进改善了开箱即用的体验。仍在 Yarn 1.x 的既有仓库官方建议尽快迁移到新版本相关迁移教程位于 docs/tutorials 目录。Yarn 1.x 已进入官方建议退役的名单长期维护角度应尽早脱离。九、安全修复本版本包含三处安全修复详见发布说明 Security Fixes 一节Catalog 后端修复了一个可被利用来破坏后端实例可用性的漏洞TechDocs 后端修复了外部托管内容场景下可能被未授权访问 TechDocs 内容的漏洞TechDocs 后端修复了已认证用户可绕过脚本注入防护的漏洞。建议所有使用 Catalog 与 TechDocs 的部署尽快升级。十、升级建议与相关资源综合以上变更升级到 v1.31.0 时建议按以下清单逐项核对后端确认packages/backend/src/index.ts中backend.add(...)传入的是BackendFeature/ServiceFactory本身移除对coreServices.identity/coreServices.tokenManager的依赖必要时按 changelog 示例自行重建服务将featureDiscoveryServiceFactory替换为discoveryFeatureLoader确保所有插件运行在同一新后端实例中避免新旧混跑导致认证失败。前端将扩展 outputs 改为数组形式用对应Blueprint.make替换createKindExtensioncreateExtensionOverrides迁移到createFrontendModule({ pluginId, ... })createApp改从backstage/frontend-defaults导入测试中的tester.render()改用renderInTestApptester.reactElement()。配置为 app 后端提供正确的构建期配置与app.baseUrl如需可设app.disableConfigInjection按需调整 permission policy 以放行新增的catalog.location.analyze与catalog.entity.validateGitLab 组织 provider 如有allowInherited请替换为relations。行为变化关注 cataloggetEntities排序语义变化与 guest provider 在生产环境的启动行为变化。关于本版本的完整包级变更可继续查阅 docs/releases/v1.31.0-changelog.md后端系统与新前端系统的深入文档分别位于 docs/backend-system 与 docs/frontend-system相关源码入口包括 packages/backend-plugin-api、packages/frontend-plugin-api、plugins/app-backend 与 plugins/catalog-node。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考