Backstage v1.45.0 发布解析instanceMetadata 服务升级、UI 组件库破坏性迁移与 Catalog YAML 合并键支持【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇指南以 v1.45.0-changelog.md 为主体系统梳理 Backstage 1.45.0 版本的核心变更后端系统的instanceMetadata服务正式化、前端系统ExtensionDefinition类型重构、backstage/ui组件库的破坏性 API 迁移、Catalog 对 YAML 合并键merge keys的支持以及网关代理环路防护、LDAP 模块底层库切换等重要改动。读完本文你将掌握本次升级的破坏性变更点、迁移步骤与关键配置参数能够在自己的 Backstage 实例中顺利完成升级。一、版本概览与升级入口v1.45.0 是一次涉及面很广的版本发布横跨后端系统backend system、前端系统frontend system、组件库Backstage UI与多个核心插件。版本发布方提供的官方升级助手可用于生成从当前版本升级到 1.45.0 的步骤清单与依赖调整建议建议升级前先借助该工具梳理依赖变更。本次版本值得关注的关键主题可以归纳为以下几类后端系统服务演进instanceMetadata服务从 alpha 状态提升为主入口导出并被显式标记为 root scope 服务对应coreServices.rootInstanceMetadata。前端系统类型体系调整ExtensionDefinition被拆分为输入/输出两种类型并新增插件级相对的attachTo声明能力。UI 组件库破坏性迁移backstage/ui0.9.0 对 Avatar、Checkbox、Collapsible、Select 等组件进行了大规模 API 重构涉及 Base UI 到 React Aria Components 的底层切换。Catalog 数据解析能力增强YAML 合并键:支持被正式引入yamlPlaceholderResolver并允许按需开关。基础设施与集成更新网关代理环路检测、LDAP 模块从ldapjs迁移到ldapts、Bitbucket Cloud API Token 支持、测试工具新增 Postgres 18。二、后端系统instanceMetadata 服务正式化2.1 变更内容instanceMetadata服务在本次版本中完成正式化promote到主入口backstage/backend-app-api1.3.0instanceMetadata服务的 API 更新为返回插件列表plugins而非功能列表features。backstage/backend-plugin-api1.5.0instanceMetadata服务被提升promote到主入口导出coreServices.rootInstanceMetadata被显式标记为root service。从源码看coreServices.rootInstanceMetadata的定义位于 packages/backend-plugin-api/src/services/definitions/coreServices.ts其 ServiceRef 的scope被声明为rootid为core.rootInstanceMetadataexport const rootInstanceMetadata createServiceRef import(./RootInstanceMetadataService).RootInstanceMetadataService ({ id: core.rootInstanceMetadata, scope: root, });root scope 意味着该服务在整个后端进程中全局唯一、由根级root生命周期管理适合承载当前 Backstage 实例信息这类跨插件共享的元数据。服务返回内容从features改为plugins反映的是后端系统中功能单元的实际组织方式是插件plugins——模块modules归属于某个插件而服务按插件维度暴露元数据更贴近新后端系统的真实结构。2.2 对插件作者的影响如果你在插件代码中通过 alpha 导出使用过旧的instanceMetadataService应切换为稳定的coreServices.rootInstanceMetadata。仓库中 packages/backend-plugin-api/CHANGELOG.md 明确记录了旧 alpha API 的移除提示The oldinstanceMetadataServicehas been removed from alpha. Please switch over to using the stablecoreServices.rootInstanceMetadataand related types instead.使用方式示例import { coreServices, createBackendModule } from backstage/backend-plugin-api; createBackendModule({ pluginId: example, moduleId: metadata-consumer, register(env) { env.registerInit({ deps: { instanceMetadata: coreServices.rootInstanceMetadata, }, async init({ instanceMetadata }) { const metadata await instanceMetadata.getMetadata(); // metadata 中现在是插件plugins列表 }, }); }, });同批受影响的后端包还有backstage/plugin-gateway-backend1.1.0更新了对instanceMetadata服务的使用、backstage/backend-defaults0.13.1与backstage/backend-test-utils1.10.0等它们均同步升级了对backstage/backend-plugin-api1.5.0的依赖。三、前端系统ExtensionDefinition 类型拆分与插件级 attachTo3.1 ExtensionDefinition 重构backstage/frontend-plugin-api0.13.0对扩展定义类型做了重要拆分原ExtensionDefinition更名为OverridableExtensionDefinition保留了 override 相关方法通常作为输出类型使用新的、更精简的ExtensionDefinition类型不包含 override 方法通常作为输入类型使用。这样做的目的是减少跨版本、跨包使用时因 override 方法签名差异造成的类型冲突提升长期兼容性。对大多数插件作者而言如果只是把扩展定义作为输入传给某个 API直接使用新的ExtensionDefinition即可只有需要显式暴露可被覆盖overridable的扩展时才使用OverridableExtensionDefinition。3.2 插件级相对的 attachTo 声明attachTo声明现在支持插件相对引用扩展或扩展蓝图blueprint可以通过kind关联到同一插件内的其它扩展而不必提供精确的扩展 ID。这为一个蓝图创建出的扩展挂到另一个蓝图创建出的扩展之下这种内建层级结构提供了便利。changelog 中给出的示例是一个 TabbedPage 蓝图父与 TabContent 蓝图子的组合// kind: tabbed-page const parentPage TabbedPageBlueprint.make({ params: { /* ... */ } }); // attachTo: { kind: tabbed-page, input: tabs } const child1 TabContentBlueprint.make({ name: tab1, params: { /* ... */ } });此时TabContentBlueprint创建的扩展会自动附加到同一插件中kind: tabbed-page的扩展上并通过tabs输入input注入内容无需硬编码父扩展的完整 ID。3.3 配套改动ExtensionInput的所有类型参数变为可选[878c251]降低了声明输入时的样板代码。路由引用route reference实现做了内部重构toString实现有细微更新[4d03f08]。backstage/core-plugin-api1.12.0中的所有路由引用现在天然兼容新前端系统backstage/frontend-plugin-api不再需要通过convertLegacyRouteRef/convertLegacyRouteRefs来自backstage/core-compat-api进行转换。这大幅简化了旧插件向新前端系统迁移时对路由引用的处理。四、backstage/ui 0.9.0组件库破坏性迁移与迁移指南backstage/ui0.9.0 是本版本中破坏性变更最集中的部分核心方向是从base-ui-components/react全面迁移到 React Aria Componentsbase-ui-components/react依赖已被移除。以下逐项给出迁移要点。4.1 Avatar尺寸体系调整 移除 Base UI propsAvatar 组件改为自定义实现不再支持 Base UI 特有 props如render并新增了purposeprop 用于无障碍控制informative或decoration。新的尺寸取值如下尺寸大小说明x-small1.25rem / 20px新增small1.5rem / 24px不变medium2rem / 32px不变默认large由 3rem 改为 2.5rem / 40px变更x-large3rem / 48px新增迁移示例若需要保持原有大号视觉尺寸请改用x-large# 移除 Base UI 特有 props - Avatar src... name... render{...} / Avatar src... name... / # 原 large 尺寸改用 x-large 以保持视觉一致 - Avatar src... name... sizelarge / Avatar src... name... sizex-large /此外x-small与small尺寸的 Avatar 现在只显示一个首字母而非两个以提升小尺寸下的可读性。4.2 Checkbox迁移到 React Aria ComponentsCheckbox 组件的 API 全面对齐 React Aria 命名规范旧 API新 APIcheckedisSelecteddefaultCheckeddefaultSelecteddisabledisDisabledrequiredisRequiredlabelprop移除改用childrenCSS 类bui-CheckboxLabel移除data 属性data-checkeddata-selected同时不带 label 的用法不再被支持无障碍要求。迁移示例// Before Checkbox labelAccept terms checked{agreed} onChange{setAgreed} / // After Checkbox isSelected{agreed} onChange{setAgreed} Accept terms /Checkbox // Before Checkbox labelOption disabled / // After Checkbox isDisabledOption/Checkbox // 无可见文字时用 VisuallyHidden 保证可访问性 Checkbox VisuallyHiddenAccessible label/VisuallyHidden /Checkbox4.3 Collapsible 移除迁移到 Accordion 或 React Aria DisclosureCollapsible组件被移除官方提供两条迁移路径路径一使用 Accordion自带样式的组件- import { Collapsible } from backstage/ui; import { Accordion, AccordionTrigger, AccordionPanel } from backstage/ui; - Collapsible.Root - Collapsible.Trigger render{(props) Button {...props}Toggle/Button} / - Collapsible.PanelContent/Collapsible.Panel - /Collapsible.Root Accordion AccordionTrigger titleToggle / AccordionPanelContent/AccordionPanel /AccordionCSS 类对应关系.bui-CollapsibleRoot→.bui-Accordion.bui-CollapsibleTrigger→.bui-AccordionTrigger现在位于 heading 元素上.bui-CollapsiblePanel→.bui-AccordionPanel。路径二使用 React Aria Disclosure完全自定义样式import { Disclosure, Button, DisclosurePanel } from react-aria-components; Disclosure Button slottriggerToggle/Button DisclosurePanelContent/DisclosurePanel /Disclosure;4.4 Select泛型化 可搜索多选SelectProps接口现在接受表示选择模式的泛型参数并新增searchable、selectionMode、searchPlaceholderprops 以支持过滤与多选。如果你直接使用过SelectProps类型请更新为SelectPropssingle | multiple组件本身的 JSX 用法保持向后兼容。4.5 其它破坏性/行为变更移除componentDefinitions集中的componentDefinitions对象及ComponentDefinitionName、ComponentClassNames类型工具被移除。组件定义主要用于文档化主题theming的 CSS 类 API不应用于 JS/TS 编程。迁移建议直接使用 Backstage UI 组件作为构建块或在自有样式表中复制组件 CSS而不是依赖内部类名。className 行为变更Menu、MenuListBox、MenuAutocomplete、MenuItem、Switch、Skeleton、FieldLabel、Header、HeaderToolbar、HeaderPage、Tabs、TabList、Tab、TabPanel 等组件的classNameprop 现在会附加augment默认样式而非被忽略或覆盖默认样式。若你之前依赖旧行为传入自定义 className需要相应调整样式。SearchField 独立类名迁移到 CSS modules 后SearchField拥有独立的类名集合主题中可分别定制TextField与SearchField。4.6 常规修复与增强新增VisuallyHidden组件视觉隐藏但屏幕阅读器可读。Button / ButtonIcon 新增loadingprop用于异步操作时展示 spinner。Table Row 的hrefprop 现在支持右键/CommandClick 在新标签页打开链接。根据主题设置color-scheme属性修复暗色模式对话框 backdrop、默认字体大小/字重/字族、CSS 层加载顺序、RadioGroup 圆点变形等问题。移除了base-ui-components/react依赖并启用除*.css外的导入 tree-shaking。五、CatalogYAML 合并键支持与开关控制backstage/plugin-catalog-backend3.2.0与backstage/plugin-catalog-node1.20.0为yamlPlaceholderResolver引入了YAML 合并键merge keys:支持。合并键是 YAML 标准YAML 1.1 起提供的继承语法可以让一个映射继承另一个映射的字段例如base: owner: team-a system: example derived: : *base description: 继承自 base 并追加字段此前 Catalog 的yamlPlaceholderResolver对:的支持要么缺失、要么固定开启。本次变更一方面默认启用合并键另一方面提供了可配置开关让需要严格解析行为的场景可以显式关闭。涉及此项的变更条目包括 [2d229b2]、[9d3ec06]、[8c26af4]其中 [9d3ec06] 明确指出让 YAML 合并支持在 Backstage Catalog 中可配置而非总是启用。对维护大量使用锚点anchor与别名alias的 catalog-info.yaml 文件的团队该特性可以直接减少重复字段但对严格校验 YAML 结构的团队可通过配置关闭该行为以避免意外继承。六、网关与集成层更新6.1 Gateway代理环路检测hop count trackingbackstage/plugin-gateway-backend1.1.0新增代理跳数跟踪以防止代理环路网关通过backstage-gateway-hops请求头记录代理跳数超过3 跳的请求被拒绝返回508 Loop Detected错误。从源码看相关实现位于 plugins/gateway-backend/src/router.ts其中HOPS_HEADER backstage-gateway-hops定义了跟踪头名称并在跳数超限时以res.status(508)返回错误。对应的测试用例在 plugins/gateway-backend/src/plugin.test.ts 中验证了收到超过上限跳数时返回 508 的行为。这意味着在多网关串联的部署拓扑中配置不当造成的请求回环会被自动拦截而不是无限循环拖垮集群。6.2 Bitbucket CloudAPI Token 支持appPassword 进入弃用期由于 Bitbucket Cloud 自 2025 年 9 月 9 日起不再允许新建appPassword并将于 2026 年 6 月 9 日移除Backstage 在backstage/integration1.18.2、backstage/backend-defaults0.13.1、backstage/plugin-bitbucket-cloud-common0.3.4及多个 scaffolder bitbucket 模块中新增了对 API Token 的支持integrations: bitbucketCloud: - username: userdomain.com token: my-token同时修复了BitbucketUrlReader忽略传入 token、总是使用集成凭据的问题[b2f6a5a]issue #31348。如果你是 Bitbucket Cloud 用户建议尽快将配置从appPassword迁移到token字段。6.3 LDAP 模块ldapjs 迁移到 ldaptsbackstage/plugin-catalog-backend-module-ldap0.12.0从ldapjs迁移到ldapts带来三处破坏性变更类型迁移自定义 transformer 的 entry 参数类型从ldapjs的SearchEntry改为ldapts的Entry后者支持直接属性访问无需.object()或.raw()// Before (vendor: LdapVendor, config: UserConfig, entry: SearchEntry) PromiseUserEntity | undefined; // After (vendor: LdapVendor, config: UserConfig, entry: Entry) PromiseUserEntity | undefined;搜索选项语义反转typesOnly: false→attributeValues: trueldapjs用否定形式、ldapts用肯定形式两者效果一致都是获取属性值而非仅属性名# Before options: typesOnly: false # After options: attributeValues: trueAPI 移除LdapClient.searchStreaming()被移除统一使用LdapClient.search()。changelog 特别注明两种方法原本都是将全部条目加载进内存searchStreaming只是为适配ldapjs事件式 API 而存在的内部方法。// Before await client.searchStreaming(dn, options, async entry { // process each entry }); // After const entries await client.search(dn, options); for (const entry of entries) { // process each entry }七、通知系统整通道默认配置与立即显示默认设置backstage/plugin-notifications-backend0.6.0与backstage/plugin-notifications-common0.2.0带来两项值得关注的能力整通道channel级默认配置[87e597c]可以为整个通知通道设置默认配置该设置会向下继承到 origins 与 topics同时仍然尊重用户的个人选择。这特别适合实现opt-in默认不接收用户主动选择接收策略。立即展示默认设置[15fb764]此前用户必须至少收到过来自某个 origin 或 topic 的一条通知才能查看或修改对应通知设置现在默认设置从一开始就会展示用户可以在收到第一条通知前就完成偏好定制。结合 0001-notifications-system BEP 中描述的通知体系channel → origin → topic 的层级订阅模型本次通道级默认 继承 个人覆盖的能力让大规模租户场景下的通知治理更加灵活。八、开发者工具与工程化改进8.1 测试工具支持 Postgres 18backstage/backend-test-utils1.10.0为TestDatabases增加了 Postgres 18 支持。同时默认测试数据库集合从 Postgres 13/17 更新为Postgres 14/18外加 SQLite 3。如果默认集合不符合你的 CI 环境可以显式传入ids覆盖const databases await TestDatabases.create({ ids: [POSTGRES_17, POSTGRES_13, SQLITE_3], });此外该版本还微调了部分 mock 服务的类型精度[f3001fd]并修复了增量摄取模块在 DB count 查询返回字符串时实体移除计算错误的问题[70745c5]plugin-catalog-backend-module-incremental-ingestion0.7.6。8.2 CLIyarn new 模板增强backstage/cli0.34.5对yarn new命令做了多项改进模板现在支持对文件名进行模板化templating filenames。新增catalog entity provider模板可在根package.json中通过backstage/cli/templates/catalog-provider-module显式引入该模板create-app的--next模板也已内置。修复backstage-cli new --scope在 scope 已含符号如backstage-community时生成双重前缀的问题。修复--scope internal时包名前缀不一致的问题现在无论是否显式传入--scope均统一默认使用backstage-plugin-中缀。backstage/repo-tools0.16.0的package-docs命令现在会自动使用项目根目录的typedoc.json若存在。8.3 ESLint 新规则backstage/eslint-plugin0.2.0新增backstage/no-ui-css-imports-in-non-frontend规则确保backstage/ui的 CSS 不会被非前端应用导入帮助维护样式加载边界的整洁。九、工程化基础erasableSyntaxOnly 与 enum 迁移本次发布在几乎所有包中反复出现两类机械性变更值得升级时留意其背后原因构造函数参数属性重构[05f60e1]将构造函数参数属性constructor parameter properties即constructor(private readonly foo: Foo)这类写法重构为显式属性声明以兼容 TypeScript 的erasableSyntaxOnly编译设置。erasableSyntaxOnly要求所有类型语法在编译期可被完整擦除不产生运行时行为差异这是为了支持tsc --erasableSyntaxOnly与运行时类型剥离工具链。该重构不改变任何功能行为。enum 迁移[b2bef92]backstage/core-plugin-api、backstage/cli、core-app-api、core-components、permission-common、permission-backend、search-backend、devtools-common、scaffolder-backend-module-rails、catalog-graph等多个包将所有 enum 转为 erasable-syntax 兼容模式如使用 const 对象 联合类型代替 enum。这两类变更虽然对运行时无感知但如果你是 Backstage 插件的维护者建议在自己的包中也采用相同的模式以保持与新工具链的兼容。十、升级建议清单综合以上变更升级到 v1.45.0 时建议按以下顺序检查后端将instanceMetadataService的 alpha 用法替换为coreServices.rootInstanceMetadata确认返回结构从 features 变为 plugins 后消费方无需调整。前端检查插件中是否依赖旧的ExtensionDefinitionoverride 行为改用OverridableExtensionDefinition清理不再需要的convertLegacyRouteRef调用core-plugin-api路由引用已原生兼容新前端系统。UI 组件全仓搜索AvatarBase UI props、sizelarge、Checkboxchecked/label/disabled、Collapsible、SelectProps、自定义className覆盖这些受影响组件的代码按上文迁移指南逐一处理。Catalog如对 YAML 解析有严格校验需求确认是否需要显式关闭 merge key 支持。集成Bitbucket Cloud 配置从appPassword迁移到tokenLDAP 自定义 transformer 与搜索配置按 ldapts 新 API 调整。测试确认 CI 中的TestDatabases默认集合现在为 Postgres 14/18 SQLite 3是否与本地数据库版本匹配必要时显式指定ids。网关如存在网关链式调用注意 3 跳上限与backstage-gateway-hops头的语义。相关资源完整变更条目docs/releases/v1.45.0-changelog.md后端系统服务定义packages/backend-plugin-api/src/services/definitions/coreServices.ts后端插件 API 变更历史packages/backend-plugin-api/CHANGELOG.md网关 hop 计数实现plugins/gateway-backend/src/router.ts 与测试plugins/gateway-backend/src/plugin.test.ts通知系统设计文档beps/0001-notifications-system/README.md【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考