Backstage v1.44.0 版本升级指南Scaffolder 3.0 破坏性变更、后端 HTTP 配置与 UI 组件体系重构【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南以 Backstage v1.44.0 官方变更日志docs/releases/v1.44.0-changelog.md为骨架系统梳理该版本包含的 4 个破坏性变更backstage/plugin-scaffolder-backend3.0、backstage/theme0.7、backstage/ui0.8、backstage/frontend-test-utils0.4以及新增的后端 HTTP 服务器配置、外部 Token 校验扩展点、Catalog 处理器配置重构等核心能力。读完本文你将掌握 v1.44.0 升级时的完整迁移清单、新配置项的用法以及这些变更在仓库源码中的落地位置可直接用于现有 Backstage 实例的升级评估与实施。版本概览与升级入口v1.44.0 是一次以「架构清理与破坏性变更」为主题的发布Scaffolder 后端插件正式发布 3.0.0移除了新后端系统New Backend System下已无存在价值的旧类型前端 UI 组件体系backstage/ui完成从纯 CSS 到 CSS Modules 的重构主题层backstage/theme移除了内置的CssBaseline。官方为升级提供了 Upgrade Helper 工具目标版本1.44.0该工具会基于当前仓库的依赖版本自动给出升级建议与破坏性变更提示。升级涉及的核心包版本如下包版本变更级别backstage/plugin-scaffolder-backend3.0.0Major破坏性backstage/backend-defaults0.13.0Minorbackstage/frontend-test-utils0.4.0Major破坏性techdocs/cli1.10.0Minorbackstage/theme0.7.0Major破坏性backstage/ui0.8.0Major破坏性backstage/plugin-api-docs0.13.0Minorbackstage/plugin-scaffolder-node0.12.0Minorbackstage/plugin-catalog-backend3.1.2Patch一、Scaffolder 后端 3.0.0旧任务系统的类型清理1.1 被移除的废弃类型BREAKINGbackstage/plugin-scaffolder-backend3.0.0 移除了在新后端系统下已无法被消费的一批废弃类型与接口官方明确表示这些类型没有替代品且因为插件已完全迁移到新后端系统这些类型不再具有任何使用价值。受影响类型清单CreateWorkerOptionsCurrentClaimedTaskDatabaseTaskStoreDatabaseTaskStoreOptionsTaskManagerTaskStoreTaskStoreCreateTaskOptionsTaskStoreCreateTaskResultTaskStoreEmitOptionsTaskStoreListEventsOptionsTaskStoreRecoverTaskOptionsTaskStoreShutDownTaskOptionsTaskWorkerTemplateActionRegistry从源码结构看这些类型对应的是 Scaffolder 旧后端系统「任务持久化与执行」的核心抽象TaskWorker任务轮询执行器、DatabaseTaskStore基于数据库的任务存储、TemplateActionRegistry模板动作注册表等实现在 plugins/scaffolder-backend/src/scaffolder/tasks/ 与 plugins/scaffolder-backend/src/scaffolder/actions/TemplateActionRegistry.ts 中依然存在供内部使用但作为对外公开导出的类型已被彻底清理。如果你在自定义代码中 import 了以上任一类型升级到 3.0.0 后需要删除相关引用。1.2 修复分布式动作在模板动作列表中不可见本版本修复了一个与插件启动顺序相关的 Bugf222a2e当插件启动顺序不同时部分**分布式动作distributed actions**未被正确注册导致这些动作在 Scaffolder 模板的动作列表中不可见。修复后无论插件以何种顺序加载分布式动作都会被可靠地注册到模板动作列表。1.3 Scaffolder Node 0.12.0 的配套变更与 Scaffolder 后端 3.0.0 配套backstage/plugin-scaffolder-node0.12.0 同步调整了两处 APITaskBroker接口字段改为必填。cancel、recoverTasks和retry三个方法在接口中由可选变为必填如果自定义实现不需要这些函数可用() void的空实现填充。官方在变更说明中特别提示若此变更影响了你请通过 issue 反馈——因为团队正在考虑彻底移除TaskBroker扩展点并计划对scaffolder-backend插件进行新一轮架构重构他们希望收集真实的使用场景。scaffolderActionsExtensionPoint从/alpha移入主导出BREAKING ALPHA。该变更影响所有 Scaffolder 动作模块如 azure、bitbucket、gerrit、github、gitlab、confluence-to-markdown、cookiecutter、gcp、gitea、rails、sentry、yeoman、notifications 等// before import { scaffolderActionsExtensionPoint } from backstage/plugin-scaffolder-node/alpha; // after import { scaffolderActionsExtensionPoint } from backstage/plugin-scaffolder-node;一批与任务生命周期相关的类型被标记为废弃将在未来版本移除SerializedTask、SerializedTaskEvent、TaskBroker、TaskContext、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskEventType、TaskFilter、TaskFilters、TaskStatus。如果你在插件中使用了这些类型官方建议尽快通过 Discord 或 GitHub issue 反馈使用场景以便新架构覆盖这些需求。迁移建议升级后运行一次全仓库搜索确认没有残留scaffolderActionsExtensionPoint的/alpha导入路径对于使用TaskBroker等已废弃类型的自定义逻辑规划向新后端系统内置任务机制迁移。二、后端 HTTP 服务器级配置backend.server配置项backstage/backend-defaults0.13.0 新增了通过app-config.yaml中的backend.server键配置服务器级 HTTP 选项的能力变更 8b91238。这是社区长期关注的能力——此前想要调整 Node.js HTTP 服务器的超时参数只能通过代码或环境变量现在可以直接在配置文件中声明。2.1 支持的配置项配置键说明取值形式headersTimeout接收完整请求头超时数字毫秒、时长字符串如30s、ISO 时长如PT30S或时长对象如{ seconds: 30 }keepAliveTimeout保持连接空闲超时同上requestTimeout接收完整请求超时同上timeout请求总超时含响应时间同上maxHeadersCount最大请求头数量数字maxRequestsPerSocket每个 socket 最大请求数数字这些选项会直接透传给底层 Node.js HTTP 服务器http.Server实例。如果省略则使用 Node.js 默认值。2.2 配置示例backend: server: headersTimeout: 30s # 支持时长字符串 keepAliveTimeout: 60000 # 也支持毫秒数字 requestTimeout: { seconds: 60 } # 支持时长对象 timeout: 120000 maxHeadersCount: 2000 maxRequestsPerSocket: 10002.3 源码实现印证该能力的落地实现位于 packages/backend-defaults/src/entrypoints/rootHttpRouter/rootHttpRouterServiceFactory.ts 的applyDefaults()中工厂从backend.server读取配置后通过readDurationValue辅助函数解析时长值支持数字、时长字符串、ISO 时长与时长对象四种形式解析失败会输出警告日志并回退随后依次赋值给server.headersTimeout、server.requestTimeout、server.keepAliveTimeout、server.timeout数值型选项maxHeadersCount、maxRequestsPerSocket则通过getOptionalNumber读取。这意味着你可以用与 Backstage 全局时长配置一致的习惯如{ seconds: 30 }对象形式来声明这些超时。适用前提此配置作用于rootHttpRouter创建的 HTTP 服务器若你的 Backstage 后端由网关、反向代理托管代理层的超时配置仍需单独处理。2.4 外部 Token 校验扩展点externalTokenHandlersServiceRef同为backend-defaults0.13.0 的新增能力8495b18新增externalTokenHandlersServiceRef允许注册自定义的外部 Token 校验处理器。该服务引用的实现位于 packages/backend-defaults/src/entrypoints/auth/external/ExternalAuthTokenHandler.ts其定义为multiton: true的服务引用id: core.auth.externalTokenHandlers意味着可以注册多个处理器实例。从源码看默认内置了三种处理器static静态 Token、legacy旧版backend.auth.keys配置兼容、jwksJWKS 远程公钥校验。自定义处理器只需实现ExternalTokenHandler接口含type标识与verifyToken方法注册后即可通过backend.auth.externalAccess配置typeoptionsaccessRestrictions被引用处理器type必须唯一重复注册会抛出异常。完整的外部服务认证配置说明可参考 docs/auth/service-to-service-auth.md。三、Catalog 后端Provider/Processor 配置重构与新增校验动作3.1 新的providerOptions/processorOptions配置结构backstage/plugin-catalog-backend3.1.2 将 Catalog 处理器Processor与 Provider 的禁用disabled和优先级priority配置移入独立的配置对象变更 e489661。重构原因是部分现有 Provider如 GitHub的配置使用了数组语法导致原先的禁用/优先级配置方式存在兼容问题。注意新配置格式不向后兼容升级后必须更新配置文件。新格式如下catalog: providerOptions: providerA: disabled: false providerB: disabled: true processorOptions: processorA: disabled: false priority: 10 processorB: disabled: true即Provider 支持disabled布尔开关Processor 除disabled外还支持priority数值用于控制处理器执行顺序。该配置解析逻辑位于 plugins/catalog-backend/src/service/util.ts 附近的工具函数中。3.2 新增catalog:validate-entity动作Catalog 后端新增了catalog:validate-entity动作并注册到动作注册表变更 77516c5。该动作用于针对软件目录校验实体Entity典型场景是通过 Backstage MCP 服务器在本地校验catalog-info.yaml文件的改动是否合法——在提交前即可发现实体格式、关系引用等问题。3.3 其他 Catalog 相关修复修复实体 facets API 调用中重复搜索结果的问题2aaf01a在 Provider 孤立实体orphaning驱逐发生前记录日志6493c98内部重构移除旧后端系统残留代码9890488GitlabDiscoveryEntityProvider修复包含特殊字符、被重命名或移动的项目在实体拉取时不再失败0443119。四、主题与 UI 组件体系两大破坏性变更4.1backstage/theme0.7.0移除内置 CssBaselineUnifiedThemeProvider不再内置CssBaseline变更 865bce8。升级后如果 Backstage 实例的样式「看起来坏了」大概率是缺少 Backstage UI 全局 CSS。修复方式是在应用入口显式导入// packages/app/src/index.tsx import backstage/ui/css/styles.css;同时noCssBaselineprop 因变得冗余而被移除。另一个增强d5cbdba当页面渲染了多个主题 Provider 时UnifiedThemeProvider现在会在文档body上协调主题属性如data-theme避免多个 Provider 之间的主题属性冲突。4.2backstage/ui0.8.0CSS Modules 重构与组件清理backstage/ui0.8.0 是本版本中破坏性变更最集中的包破坏性变更BREAKING新增PasswordField组件同时TextField的password和search类型被移除——密码与搜索输入应改用独立组件样式体系从纯 CSS 重构为 CSS Modules所有样式通过 CSS Modules 加载生成类名但所有组件仍提供固定类名允许开发者继续为 Backstage 实例定制样式ScrollArea组件被移除原因是不符合无障碍accessibility标准Card组件中的 ScrollArea 相关属性也一并清理Icon组件被移除该组件影响 tree-shaking摇树优化官方建议在 Backstage UI 提供更好的替代方案之前使用remixicon/react中的图标。新增能力与修复新增Dialog组件2591b42新增Menu、MenuListBox、MenuAutocomplete、MenuAutocompleteListBox的virtualized、maxWidth、maxHeightprops支持长列表的虚拟化渲染8b7c3c9Box /、Container /、Flex /、Grid /支持 data 属性透传到渲染元素b940062ButtonLinks内部路由改用 react routerMenu组件的内部链接同样改用 react routerf6dff5b、5c21e45修复SearchField在 Header 中的响应式行为从 width 过渡改为 flex-basis 过渡、修复菜单打开时的滚动跳动、修复表格排序图标位置、修复 margin 工具类、为 body 添加默认背景色、CSS 分层结构重构等。迁移建议升级backstage/ui后重点排查三处——TextField的password/search类型用法改用PasswordField、ScrollArea引用删除或替换、Icon组件引用改用remixicon/react图标。同时确认已按 4.1 节导入全局样式表。4.3 配套MUI 到 BUI 的迁移辅助插件backstage/plugin-mui-to-buibackstage/plugin-mui-to-bui0.2.0 首次发布d5cbdba其源码位于 plugins/mui-to-bui。该插件在/mui-to-bui路径下新增页面可将现有的 MUI v5 主题转换为 Backstage UIBUICSS 变量并支持实时预览与复制/下载。此版本还修复了--bui-bg变量的错误转换28ee81c。对于计划从 Material UI 迁移到 Backstage UI 的实例该插件是官方提供的辅助工具。五、前端测试与组件 API 变更5.1backstage/frontend-test-utils0.4.0renderInTestApp移除extensions选项破坏性变更c41dd80renderInTestApp的extensions选项被移除。如果需要在测试应用中传递扩展extensions请改用新的renderTestApp工具。这是新前端系统下测试工具链的收敛——renderTestApp负责需要自定义扩展注入的场景而renderInTestApp保持面向简单场景。5.2 前端插件 API 与组件库的配套更新backstage/frontend-plugin-api0.12.1 新增coreExtensionData.title特别适用于构建带标签页的可扩展布局8ed53ebbackstage/plugin-app0.3.1 修复当 Page 挂载在/时NotFound页面渲染异常的问题ae1dad0backstage/plugin-user-settings0.8.27 新增用户设置存储 API 蓝图52fa068backstage/plugin-catalog-react1.21.2 修复实体表格 owner 列的翻译键从type改为owner确保正确加载翻译2a3704dbackstage/plugin-org0.6.45 为EntityMembersListCard与EntityOwnershipCard新增initialRelationAggregation和showAggregateMembersToggle选项8b7351fbackstage/plugin-scaffolder1.34.2 为RouterProps.contextMenu补充templatingExtensions选项、OwnedEntityPicker支持ui:disabled、并为新前端系统补齐缺失的表单字段。5.3 搜索体验请求取消与 PG 索引适配backstage/plugin-search与backstage/plugin-search-react实现了基于AbortController的请求取消67a3e1a用户快速输入时重叠的旧搜索请求会被正确取消避免过期结果覆盖新结果backstage/plugin-search-backend-module-pg将过长文档截断以适配 PostgreSQL 索引大小限制a919ca3并在查询过滤正则中新增字符支持8d15a51。六、TechDocs 与 CLI 工具链增强6.1 TechDocs CLI本地预览支持自动刷新techdocs/cli1.10.0 的serve命令支持自动刷新43afbe5依赖mkdocs的watch特性。在本地编写文档时yarn techdocs-cli serve会监听文件变化并自动重建预览无需手动重启。6.2 CLIpackage start新增--entrypoint选项backstage/cli0.34.4 的package start命令新增--entrypoint选项ab96bb7用于指定自定义的入口目录/文件——这对同时维护插件不同版本如 stable 与 alpha的开发应用尤其有用。示例目录结构dev/ index.tsx alpha/ index.ts默认yarn package start以dev/为入口执行dev/index.tsxyarn package start --entrypoint dev/alpha则以dev/alpha/为入口执行dev/alpha/index.ts。6.3 Yarn 插件自定义 manifest 位置Backstage yarn 插件与版本升级version bump支持通过两个环境变量配置自定义 manifest 位置33faad2适用于无法直接访问外网的环境如使用 versions API 镜像或代理BACKSTAGE_VERSIONS_BASE_URL拉取 Backstage 版本 manifest 的 base URL。默认https://versions.backstage.io/v1/releases/VERSION/manifest.json。注意该变量只填主机名路径由插件追加使用 yarn 插件执行 bump 命令时也会从同一 base URL 拉取新版 yarn 插件默认为.../v1/releases/RELEASE/yarn-pluginBACKSTAGE_MANIFEST_FILE本地 manifest 文件路径。设置后插件将不再从网络拉取 manifest适合完全没有网络也没有镜像的离线环境。6.4 其他 CLI 变更yarn new生成新包时自动检测并支持 Backstage yarn 插件插件已安装时新包的backstage/*依赖自动使用backstage:^范围d14ef24移除 Jest 配置中的 script transform 缓存与 Jest 30 不兼容f2cf564修复 module federation 配置仅对远端remote的共享库设置import: false6ebc1ea移除 CLI 中未使用的octokit/graphql、octokit/graphql-schema、octokit/oauth-app依赖024645e。七、集成、API 文档与其他插件更新7.1 Azure Blob Storage 集成增强backstage/backend-defaults的AzureBlobStorageUrlReader搜索函数支持直接 URL2d3e2b2backstage/integration1.18.1 为 Azure Blob Storage 新增配置定义84443f1并从集成类型中移除了host字段d772b51backstage/plugin-catalog-backend-module-azure同步补充了 Azure Blob Storage 配置定义。7.2 API 文档插件backstage/plugin-api-docs0.13.0 移除了对isomorphic-form-data的显式依赖b8a381e——该依赖原先是为规避swagger-ui-react的一个已解决缺陷而添加的同时将swagger-ui-react升级到 5.19.0 及以上该版本兼容最新版 OpenAPI 规范。7.3 通知系统backstage/plugin-notifications-backend-module-slack0.2.0 新增可选username配置3d09bb2当使用同一个 Slack App 服务多个系统时可以指定发送通知的用户名以便区分消息来源backstage/plugin-notifications-backend修复发送通知时排除实体引用exclude entity reference不生效的问题3b8e156。7.4 其他值得关注的点backstage/backend-app-api1.2.8 将未处理的 rejection/error 监听器的注册提前到尽可能早的阶段避免后端启动的偶发性不稳定确保这些失败始终被记录日志而非偶尔崩溃进程dd69cf6backstage/plugin-bitbucket-cloud-common0.3.3 与plugin-catalog-backend-module-bitbucket-cloud支持pagelen参数可配置BitbucketCloudEntityProvider的searchCode分页长度规避重复结果问题2aded73backstage/config1.3.5 允许使用冒号colon作为配置键b45b094config-loader同步支持backstage/plugin-kubernetes-react修复 PodTable 的 CPU 利用率计算f7a4144并新增渲染 ConfigMaps 的能力ac405f2backstage/plugin-scaffolder-backend-module-sentry新增sentry:fetch:dsn动作用于获取 Sentry 项目的 DSNeea5360backstage/core-components的DependencyGraph /新增renderEdgeprop 支持自定义边渲染431130c并修复 SVG 尺寸自适应与自动无限滚动问题6981ae6、95935fbbackstage/eslint-plugin允许前端插件从具有相同 plugin id 的另一个前端插件导入a1dae71避免新前端系统中插件覆盖所需的跨插件导入被误报backstage/create-app将better-sqlite3升级到最新版本7dcedff。八、升级行动清单综合本版本全部变更升级到 v1.44.0 前建议逐项核对Scaffolder删除对已移除类型TaskWorker、DatabaseTaskStore、TemplateActionRegistry等 14 个的引用TaskBroker自定义实现补齐cancel/recoverTasks/retry三个必填方法scaffolderActionsExtensionPoint从/alpha改为主导出导入主题与 UI在packages/app/src/index.tsx导入backstage/ui/css/styles.css移除noCssBaselineprop排查TextField的password/search类型改用PasswordField、ScrollArea与Icon组件引用Catalog 配置将 Provider/Processor 的禁用与优先级配置迁移到新的catalog.providerOptions/catalog.processorOptions结构前端测试renderInTestApp中如有extensions参数改用renderTestApp后端服务器按需在backend.server下声明超时与连接数选项外部认证如需要自定义外部 Token 校验接入externalTokenHandlersServiceRef并配置backend.auth.externalAccess离线环境按需设置BACKSTAGE_VERSIONS_BASE_URL/BACKSTAGE_MANIFEST_FILE环境变量。从源码证据看如 rootHttpRouterServiceFactory.ts、ExternalAuthTokenHandler.ts、scaffolder tasks 目录v1.44.0 的多数变更都伴随着清晰的新后端系统架构意图——移除旧抽象、收敛配置入口、为下一轮 Scaffolder 架构重构铺路。升级时如遇TaskBroker相关破坏性变更影响建议按官方指引提交 issue 反馈使用场景。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考