Backstage v1.34.0-next.1 版本深度解读实例元数据服务、Catalog 性能优化与新后端系统演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage v1.34.0-next.1 是该 1.34 系列发布周期的第二个预发布版本next.1面向 1.34.0 正式版发布前的验证与迁移。本版围绕后端系统的实例可观测性、Catalog 后端查询性能、原生 fetch 全面落地以及新后端系统New Backend System的强制收敛展开同时覆盖了 Auth、Scaffolder、Search、Devtools 等多个插件的修复与增强。阅读本文后你将掌握本版本中instanceMetadataService新特性的工作原理与源码实现、了解 catalog 后端查询优化的具体改动以及评估升级到该版本时需要关注的全部破坏性变更与行为变化。版本概览一次跨全栈的滚动更新v1.34.0-next.1 覆盖了约 120 个backstage/*包包含 3 项 Minor 级别变更、1 项破坏性变更以及数十项 Patch 修复。整体来看本版本的核心主题可以归纳为四条主线新特性backstage/backend-app-api1.1.0-next.1与backstage/backend-plugin-api1.1.0-next.1新增实验性的instanceMetadataService用于承载单个后端实例的运行时信息。破坏性变更backstage/plugin-devtools-backend0.5.0-next.1彻底移除了对 legacy backend 的支持全面转向新后端系统。性能与正确性backstage/plugin-catalog-backend1.29.0-next.1将 facets 计算合并为单次数据库查询并修复了by-query端点可能返回 null 的问题。基础设施现代化以5c9cc05为代表的一大批包从node-fetch迁移到 Node.js 原生fetch涉及后端运行时、CLI、多个插件后端等约 40 个包。核心新特性instanceMetadataService 实例元数据服务本次版本最值得关注的新能力是instanceMetadataService变更号12eac85标注为EXPERIMENTAL。它同时出现在backstage/backend-app-api和backstage/backend-plugin-api的 Minor Changes 中定位是承载关于某个具体后端实例的信息hold information about a specific backend instance。从源码看实现在仓库中该特性的实现位于 packages/backend-defaults/src/alpha/entrypoints/instanceMetadata/instanceMetadataServiceFactory.ts。核心结构如下export type BackendFeatureMeta | { type: plugin; pluginId: string } | { type: module; pluginId: string; moduleId: string }; export interface InstanceMetadataService { getInstalledFeatures: () BackendFeatureMeta[]; } export const instanceMetadataServiceRef createServiceRefInstanceMetadataService({ id: core.instanceMetadata, }); export const instanceMetadataServiceFactory createServiceFactory({ service: instanceMetadataServiceRef, deps: { instanceMetadata: coreServices.rootInstanceMetadata }, factory: async ({ instanceMetadata }) { const plugins await instanceMetadata.getInstalledPlugins(); const features: BackendFeatureMeta[] []; for (const plugin of plugins) { features.push({ type: plugin, pluginId: plugin.pluginId }); for (const module of plugin.modules) { features.push({ type: module, pluginId: plugin.pluginId, moduleId: module.moduleId, }); } } return { getInstalledFeatures: () features }; }, });可以看到instanceMetadataService的核心能力是getInstalledFeatures()它会把当前后端实例中实际注册installed的插件与模块展开成扁平化的BackendFeatureMeta[]列表返回。这与配置里声明了哪些插件不同——它反映的是运行时真正加载成功的结果因此非常适合用于诊断预期插件未加载这类问题。源码注释NOTE(freben)还揭示了一个关键演进方向该 alpha 实现目前是基于coreServices.rootInstanceMetadata之上的兼容层BackendInitializer内部已经将元数据收集逻辑收敛到了更底层、更稳定的rootInstanceMetadata服务上。也就是说当前版本里instanceMetadataServiceRef仍然可用但实现细节已委托给根级服务未来正式化的 API 会以此为根基。底层数据从哪来instanceMetadataService的数据来源是coreServices.rootInstanceMetadata其工厂函数定义在 packages/backend-app-api/src/wiring/BackendInitializer.ts 的createRootInstanceMetadataServiceFactory中。实现逻辑为从BackendInitializer收集到的全部注册项registrations中筛选出类型为plugin/plugin-v1.1的注册作为插件列表再筛选出module/module-v1.1类型的注册并按pluginId挂到对应插件下的modules数组使用deepFreeze冻结结果保证元数据在运行时不可变最终以getInstalledPlugins()的形式暴露给上层服务。从源码结构看这套收集机制是注册驱动的只有通过新后端系统register流程真正注册进来的插件和模块才会被统计这也再次印证了它反映的是运行时真实状态。如何在插件中使用该特性的使用方式可以参考其配套测试 instanceMetadataServiceFactory.test.ts在插件初始化时声明对instanceMetadataServiceRef的依赖即可在 HTTP 路由中返回已安装特性列表import { instanceMetadataServiceRef } from backstage/backend-defaults/alpha; // 在插件 register 中 reg.registerInit({ deps: { instanceMetadata: instanceMetadataServiceRef, httpRouter: coreServices.httpRouter, }, async init({ instanceMetadata, httpRouter }) { const router Router(); router.get(/instance-metadata, async (_, res) { const metadata await instanceMetadata.getInstalledFeatures(); res.json(metadata); }); httpRouter.use(router); }, });测试用例验证了端到端行为注册一个pluginId: my-plugin的插件并启动测试后端后请求/api/my-plugin/instance-metadata会返回[{ pluginId: my-plugin, type: plugin }]。开发者可以基于该能力构建自定义的已安装功能清单诊断接口。破坏性变更devtools-backend 全面转向新后端系统backstage/plugin-devtools-backend0.5.0-next.1包含本版本唯一一项BREAKING变更c781a9a移除了对 legacy backend 的支持并明确要求使用新后端系统New Backend System。从仓库源码看该插件的服务层已经完全基于新后端系统的服务抽象构建。在 plugins/devtools-backend/src/service/router.ts 中RouterOptions依赖的注入对象包括LoggerService、RootConfigService、PermissionsService、DiscoveryService、HttpAuthService等全部来自backstage/backend-plugin-api插件入口 plugins/devtools-backend/src/plugin.ts 使用createBackendPlugin定义并通过createRouter装配路由。升级影响如果你的应用仍在使用 legacy 方式如createRouter旧式中间件或plugin.enable()旧式注册加载 devtools-backend升级到本版本后将直接失效。迁移路径很明确——改用新后端系统的backend.add(devtoolsPlugin)方式注册插件。Catalog 后端查询性能与数据正确性双管齐下backstage/plugin-catalog-backend1.29.0-next.1带来了两项与数据查询直接相关的改动1. 单次查询计算全部 facets1d0bc11此前 facets用于目录页面筛选器下拉列表的取值与计数例如按 tag、lifecycle 聚合可能通过多次数据库往返完成。本版本将其合并为在单个数据库查询中获取所有 facets减少与数据库的交互次数对大型目录而言能显著降低查询延迟。facets 的请求/响应结构定义在 plugins/catalog-backend/src/catalog/types.ts请求携带filter与facets字段数组响应返回形如facets: Recordstring, Array{ value: string; count: number }的聚合结果。该改动属于内部实现优化对外 API 形态不变因此现有调用方无需修改代码即可受益。2. 修复 by-query 端点返回 nulle4aab10该 Patch 修复了一个数据正确性问题在某些情况下by-query端点会对尚未完成 stitching拼接的实体返回null。所谓 stitching是 Catalog 将实体与其关系、处理状态等辅助数据合并成最终对外形态的过程参考 plugins/catalog-backend/src/database/operations/provider/deleteWithEagerPruningOfChildren.ts 中围绕stitch_queue的处理逻辑可以理解其机制。修复后by-query对未 stitch 完成的实体不再返回null而是返回实体本身尚未完全拼接的状态从而避免消费方因null断言失败而崩溃。3. catalogServiceMock 类型对齐8edc4cdbackstage/plugin-catalog-node1.15.0-next.1更新了catalogServiceMock的返回类型使其同时匹配CatalogService与CatalogApi两种接口。这对测试代码非常友好之前测试中若同时用到CatalogService后端与CatalogApi客户端风格的调用可能需要额外的类型断言现在一个 mock 即可同时满足两种类型的赋值要求显著减少了测试样板代码。基础设施现代化原生 fetch 全面替换 node-fetch变更5c9cc05Use native fetch instead of node-fetch是本版本波及面最广的 Patch涉及约 40 个包包括但不限于后端核心backend-app-api、backend-defaults、config-loader、create-app插件后端catalog-backend、auth-backend及其多个 provider 模块AWS ALB、Bitbucket Server、Cloudflare Access、Microsoft、GitHub、GitLab、msgraph、PuppetDB 等、notifications-backend、signals-backend、permission-backend、proxy-backend、techdocs-backend、search-backend-module-explore等工具链cli、scaffolder-backend-module-*系列这一迁移意味着 Backstage 运行时不再依赖node-fetch这个第三方 HTTP 客户端而是使用 Node.js 内置的fetch自 Node 18 起稳定可用。对使用者的影响只要你的运行环境是 Node 18 及以上版本即可正常升级若仍运行在旧版 Node 上请先升级运行时。此外backstage/release-manifests0.0.12-next.1通过b29eaea允许覆盖getManifestByVersion内部使用的 fetch 函数方便在需要自定义网络行为的场景下注入自己的实现。Auth 体系刷新链路与凭证数据修复本版本围绕 OAuth 刷新与凭证端点做了三项值得关注的修复c907440auth-backend / auth-node改进 OAuthrefresh 端点的错误转发。刷新令牌流程中的错误如令牌过期、scope 变更、provider 拒绝此前可能在层层包装中丢失原始信息本版本将其更准确地转发给调用方便于前端与客户端定位刷新失败的真实原因。40518abauth-backend修复jwks端点在底层使用firestore作为密钥存储时返回无效数据的问题确保 JWT 签名验证公钥的发布符合预期。79b055aauth-backend-module-google-providerGoogle provider 现在会透传includeGrantedScopes以在多次 refresh 调用之间持久化已授予的 scope避免刷新后用户此前授权的 scope 丢失。可观测性任务级指标 gauge 落地backstage/backend-defaults0.6.0-next.1通过fe87fbf为任务调度task增加了指标以两个 gauge 分别记录任务最近一次开始与结束的时间戳epoch 秒。这意味着运维人员可以通过 Prometheus 等监控系统直接观察某个周期性任务如 Catalog 的增量摄取、搜索索引的 collator是否仍在按预期运行——如果开始时间戳长时间不再更新即可快速判断任务已卡死。同一变更也同步进入了plugin-catalog-backend-module-incremental-ingestion。数据库连接支持 Cloud SQLcloudsqlbackend-defaults的1ac6b72为数据库客户端新增了对connection.type: cloudsql的支持用于配合google-cloud/cloud-sql-connector与iam认证。启用方式是在后端配置中声明连接类型backend: database: client: pg connection: type: cloudsql # 配合 Cloud SQL Connector 与 IAM 认证使用该能力让部署在 GCP 上的 Backstage 可以更顺畅地通过 Cloud SQL Connector 建立到 Cloud SQL 实例的连接而无需手动管理代理或证书。开发者体验与工具链CLIESLint 输出文件支持backstage/cli0.29.3-next.1a49030a为package lint与repo lint命令增加了 ESLint 的--output-file选项透传便于在 CI 中把 lint 结果落盘为文件如 SARIF 格式供后续分析。repo-toolsOpenAPI 客户端与 generate-patch 改进backstage/repo-tools0.12.0-next.1包含两项改进860e3b5生成的 OpenAPI 客户端现在支持带 tags 的路径。此前 OpenAPI 规范中按 tag 分组的路由在生成客户端时可能处理不当本版本补齐了该场景。00058d0generate-patch命令现在会为被 patch 的包生成单一 resolution 条目而不是为每个版本查询分别生成条目减少多版本场景下的冗余。前端与插件体验改进plugin-home新增QuickStartCard7248f3b在 docs 变更说明 中给出了完整用法示例——一个可展示标题、说明文字、图片、介绍视频与下载按钮的引导卡片帮助新用户快速上手 Catalog。引入方式为import { QuickStartCard } from backstage/plugin-home。core-components的Progress组件e47be38占位内容新增data-testid简化前端测试中的进度态断言。catalog-react的EntityOwnerPickerd97a2cd修复了加载更多元素时滚动位置被重置的问题。scaffolder-reactb21a5ae实体描述与步骤描述中的链接改为在新标签页打开行为更一致同时升级依赖flatted至 3.3.2。scaffolder-node1a23421确保 isomorphic-git 的push 命令不会被代理避免在配置了 HTTP 代理的环境中 git push 被错误路由。search-backend-module-elasticsearch991c9feElasticsearch 搜索引擎的查询 translator 现在支持短语搜索phrase searches提升带引号搜索词的匹配准确度。search-backend-node5ae8a2c移除了对backstage/backend-defaults的不必要依赖降低包耦合。升级注意事项小结综合本版本的全部变更升级到 v1.34.0-next.1 前请重点核对以下几点devtools-backend 破坏性变更确认你的后端已迁移到新后端系统否则 devtools 功能会失效。Node.js 版本大规模原生fetch替换要求 Node 18请确保运行环境满足要求。instanceMetadataService为实验性 API其引用 ID 为core.instanceMetadata且实现依赖底层rootInstanceMetadata服务正式 API 形态可能在未来版本调整生产使用前请关注后续版本变化。行为变化by-query不再对未 stitching 的实体返回nullOAuth 刷新错误转发更精确Google provider 刷新会保留已授予 scope——这些都属于修复型变化但依赖旧行为的代码需要留意。如需完整的逐包变更清单与依赖升级矩阵可查阅 v1.34.0-next.1 完整变更日志若你的应用仍停留在较早版本建议结合 版本发布说明总览 制定逐版本升级路径。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考