Backstage v1.54.0-next.0 版本升级指南连接服务重构、系统元数据服务稳定化与 OAuth 配置破坏性变更【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南以 v1.54.0-next.0 changelog 为主体梳理本次预发布版本中的全部 Minor含破坏性变更与关键 Patch 修复并结合当前仓库源码说明其底层实现、配置影响与升级注意事项。读完本文你将掌握backstage/connections库化改造后的迁移要点、coreServices.rootSystemMetadata新稳定服务的用法以及 auth-backend 中 OAuth 重定向 URI 模式匹配规则的精确语义同时了解 TechDocs、Kubernetes、MCP Actions 等插件的新配置项。版本概览一次聚焦连接能力与运行时元数据的预发布v1.54.0-next.0 是 Backstage 1.54.0 的预发布next版本其升级辅助工具为 Upgrade Helper可通过https://backstage.github.io/upgrade-helper/?to1.54.0-next.0使用。本版本的核心变化集中在三条主线上连接Connections体系重构backstage/connections被改造为 common library服务实现移入内部连接类型全面转向可移植的配置 Schema 驱动系统元数据服务稳定化coreServices.rootSystemMetadata从 alpha API 晋升为稳定的公共服务并自动注册为默认服务OAuth 安全边界收紧backstage/plugin-auth-backend对重定向 URI / 客户端 ID 元数据文档的 allowlist 匹配规则做了破坏性调整。此外本版本涉及约 90 个包与示例应用的依赖联动升级主要 Patch 修复包括 Azure DevOps URL 读取器的 abort 信号、Scaffolder 陈旧任务清理、Kubernetes 集群定位容错等。核心服务升级coreServices.rootSystemMetadata走向稳定新公共服务的能力与作用域在backstage/backend-plugin-api1.10.0-next.0中新增了稳定的公共服务coreServices.rootSystemMetadata用于读取关于整个 Backstage 系统即 Backstage 实例的集合的元数据包括已安装插件的列表。此前该能力仅以 alpha API 形式存在本次正式并入标准coreServices命名空间。从源码看该服务的定义位于 packages/backend-plugin-api/src/services/definitions/coreServices.ts其 ServiceRef 的id为core.rootSystemMetadata作用域为root类型为RootSystemMetadataService。它的核心方法getInstalledPlugins()返回RootSystemMetadataServicePluginInfo[]即一组{ pluginId }结构。默认实现如何汇总插件列表该服务的默认实现在 packages/backend-defaults/src/entrypoints/rootSystemMetadata/rootSystemMetadataServiceFactory.ts 中通过createServiceFactory注册其依赖为rootLogger、rootConfig与rootInstanceMetadata实际逻辑由 DefaultRootSystemMetadataService 承载从配置中通过getEndpoints(config)解析 discovery 端点上声明的plugins列表并做去重调用rootInstanceMetadata.getInstalledPlugins()获取当前实例已安装插件将两部分合并返回因此系统级插件由 discovery 配置声明与实例级插件本实例安装都会出现在结果中构造函数中还通过config.subscribe订阅配置变更插件列表会随配置热更新单元测试 验证了配置更新后列表会即时反映新插件。使用方式与测试支持使用该服务无需手动注册工厂backstage/backend-defaults0.17.6-next.0新增了公开入口backstage/backend-defaults/rootSystemMetadata导出rootSystemMetadataServiceFactory与DefaultRootSystemMetadataService且系统元数据服务已作为默认服务自动注册。插件侧只需声明依赖即可import { coreServices, createBackendPlugin } from backstage/backend-plugin-api; export const myPlugin createBackendPlugin({ pluginId: my-plugin, register(reg) { reg.registerInit({ deps: { systemMetadata: coreServices.rootSystemMetadata, rootHttpRouter: coreServices.rootHttpRouter, }, init: async ({ systemMetadata, rootHttpRouter }) { const router Router(); router.get(/plugins, async (_, res) { res.json(await systemMetadata.getInstalledPlugins()); }); rootHttpRouter.use(/my-system, router); }, }); }, });测试方面backstage/backend-test-utils1.11.6-next.0新增了mockServices.rootSystemMetadatamock 实现见 mockServices.ts可在测试环境中便捷替换该服务。下游联动OpenAPI 文档提供商自动发现插件该服务的稳定化直接催生了一个下游改进backstage/plugin-catalog-backend-module-backstage-openapi0.5.17-next.0的内部 OpenAPI 文档提供商现在通过系统元数据服务自动发现已安装插件。原配置项catalog.providers.backstageOpenapi.plugins变为可选并被标记为 deprecated——省略该配置时将动态发现所有已安装插件。这意味着使用了该模块的部署在升级后可以逐步移除显式插件清单配置。破坏性变更backstage/connections重构为公共库为什么重构服务契约可被同构包复用backstage/connections0.3.0-next.0的定位从后端专用包变为 common library使连接类型、Schema 与服务契约可被同构isomorphic包使用——即前端、后端、CLI 等不同运行环境都能引用同一套类型与校验逻辑。对应地Node.js 侧的服务实现被移入内部不再从backstage/connections导出的后端 API 与配置类型包括connectionsServiceRef、connectionsServiceFactory、DefaultConnectionsService、declareConnection、RootConnection、AnyRootConnection这些符号的 Node.js 实现现在由内部机制承载backstage/backend-app-api1.7.3-next.0的运行时已切换为使用内部连接服务实现。因此直接 import 上述符号的代码需要迁移要么改从新的公开入口导入如果存在要么使用backstage/connections-node本版本同步升级到 0.2.2-next.0等 node 侧包。从仓库结构看packages/connections 目录下api/、config/、schema/、system/等子目录分别承载连接 API、配置构建、各服务商 Schema 与连接类型系统。配置 Schema 化JSON Schema 生成与强类型解析第二个破坏性变更涉及连接类型的定义方式根连接类型root connection types现在以可移植的配置 Schema 作为事实来源配套提供 JSON Schema 生成与强类型解析且不再暴露底层的 Zod Schema。这意味着连接配置的校验与类型推导完全由 Schema 驱动任何语言/工具链只要遵循 JSON Schema 即可消费插件开发者无法再直接操作 Zod 对象需要改用公开的 Schema 定义 API参见 packages/connections/src/system/createConnectionType.ts 与 definitions 目录。认证策略收紧每个连接必须配置认证方式本版本还同步收紧了连接配置规则每个连接必须配置至少一种认证方式对于无需认证的连接显式使用none认证方式移除了不支持的无认证 AWS CodeCommit选项AWS CodeCommit 连接现在只暴露 access key 或 assume role 两种认证方式对应 Schema 实现见 packages/connections/src/schema/awsCodeCommit.ts。升级时请检查现有连接配置为未配置认证方式的连接补充auth: { type: none }或具体认证并将 AWS CodeCommit 的无认证配置迁移为 access key / assume role。破坏性变更auth-backend 的 OAuth 重定向 URI 匹配规则backstage/plugin-auth-backend0.30.0-next.0对 OAuth 重定向 URI 与客户端 ID 元数据文档Client ID Metadata Documents, CIMD的 allowlist 模式匹配做了三项破坏性调整按 URL 组件分别匹配模式不再针对完整 URL 字符串匹配而是对 host 与 path 等每个组件分别匹配通配符不再跨越 host 与 path 边界。必须显式声明协议模式必须包含明确的协议如http://、https://否则视为非法配置被拒绝而不是静默忽略。拒绝内嵌凭据的重定向 URI包含内嵌凭据如https://user:passhost/...的重定向 URI 一律被拒绝。其中最容易踩坑的是通配端口语义的变化http://localhost:*现在只匹配根路径不再隐式匹配任意路径若希望任意端口 任意路径必须写作http://localhost:*/*。内置的 loopback 默认值已相应更新因此只有显式配置的模式会受影响。对应的配置项在 plugins/auth-backend/config.d.ts 中有详细注释例如auth: oidc: dynamicClientRegistration: allowedRedirectUriPatterns: - http://localhost:*/* - https://*.example.com/callback请对照上表逐条检查现有allowedRedirectUriPatterns配置确保每条模式带协议前缀、通配符不跨组件、不需要跨 host/path 匹配时拆分为多段。相关修复还包括backstage/plugin-auth-node0.7.4-next.0将 OAuth start 处理器在畸形 origins 下的 500 崩溃改为返回 400。新增配置项速览TechDocspage:techdocs的initialFilterbackstage/plugin-techdocs1.18.0-next.0为page:techdocs页面新增initialFilter配置可选值为all、owned、starred默认owned用于控制文档首页初始显示的过滤器类型。其实现位于 plugins/techdocs/src/alpha/index.tsx通过PageBlueprint.makeWithOverrides的configSchema声明z.enum([all, owned, starred]).default(owned)在 factory 中把config.initialFilter传给TechDocsIndexPageContent见 TechDocsIndexPageContent.tsx最终渲染为UserListPicker的初始过滤值。使用方式app: pages: - id: techdocs config: initialFilter: all # 可选 all / owned / starred默认 ownedKuberneteskubernetes.clusterLocatorContinueOnErrorbackstage/plugin-kubernetes-backend0.21.7-next.0新增配置项kubernetes.clusterLocatorContinueOnError设为true时某个 cluster locator 失败不再导致整个集群列表请求失败而是记录错误日志并继续返回其余成功 locator 的集群默认false保持原有行为。配置声明见 plugins/kubernetes-backend/config.d.ts测试覆盖见 cluster-locator/index.test.ts。适用于多集群来源并存、个别来源不稳定场景的容错部署。MCP Actions 后端指令配置与审计日志backstage/plugin-mcp-actions-backend0.2.1-next.0新增两项能力支持为默认服务器与命名服务器分别配置 MCP server 指令instructions接入 Backstage Auditor Service为 MCP server 操作生成connection、tool-discovery、tool-execution三类审计事件便于监控与审计 MCP 活动。关键缺陷修复盘点除上述新增与破坏性变更外本版本还包含若干值得关注的修复包修复内容backstage/backend-defaults修复 Azure DevOps URL reader 未将 abort signal 转发到 commits API fetch 的问题避免构建超时/取消时 fetch 无限挂起backstage/plugin-scaffolder-backend通过将 scheduler service 传给 router修复陈旧任务 janitorstale task janitor未被正确初始化的缺陷backstage/plugin-kubernetes-backend修复AwsIamStrategy在配置 assume role ARN 时解析账户级 AWS 凭据支持webIdentityTokenFile与accountDefaults在无默认 AWS 凭据环境下的使用backstage/ui修复TableRoot直接嵌套在ResizableTableContainer内时 Firefox 下表格不占满容器宽度的问题resizable 容器的overflow由hidden改为autobackstage/core-components/repo-tools/techdocs-node/kubernetes-react依赖升级js-yaml4.2.0 → 4.3.0backstage/create-appDockerfile 文档澄清host 构建步骤必须与 Docker 基础镜像使用相同的 Node 版本升级建议与检查清单综合以上变更从 v1.53.x 升级到 v1.54.0-next.0 时建议按以下顺序自查连接配置为所有连接补齐至少一种认证方式无需认证用none将 AWS CodeCommit 无认证配置迁移为 access key 或 assume role如直接 import 过connectionsServiceRef/DefaultConnectionsService等符号改为使用backstage/connections-node或内部实现。OAuth allowlist重写所有allowedRedirectUriPatterns确保含显式协议、通配符不跨组件、通配端口时显式写出路径http://localhost:*/*。OpenAPI 文档提供商如使用catalog-backend-module-backstage-openapi确认catalog.providers.backstageOpenapi.plugins可以移除或保持与自动发现结果一致。新增配置按需启用TechDocsinitialFilter、KubernetesclusterLocatorContinueOnError、MCP server instructions 均为可选按场景开启。回归验证重点回归 Azure DevOps 集成读取、Scaffolder 任务清理、Kubernetes 集群列表与 AWS 凭据解析、TechDocs 首页过滤切换等受修复影响的路径。对于生产环境建议先在测试环境验证上述破坏性变更后再推广本文所有结论均基于当前仓库的 changelog 及对应源码实现rootSystemMetadata 服务、connections 公共库、auth-backend 配置声明、TechDocs 页面蓝图。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考