Backstage v1.54.0-next.0 版本升级指南：连接服务重构、系统元数据服务稳定化与 OAuth 配置破坏性变更

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/?to=1.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-api@1.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-defaults@0.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-utils@1.11.6-next.0新增了mockServices.rootSystemMetadatamock 实现（见 mockServices.ts），可在测试环境中便捷替换该服务。

下游联动：OpenAPI 文档提供商自动发现插件

该服务的稳定化直接催生了一个下游改进：@backstage/plugin-catalog-backend-module-backstage-openapi@0.5.17-next.0的内部 OpenAPI 文档提供商现在通过系统元数据服务自动发现已安装插件。原配置项catalog.providers.backstageOpenapi.plugins变为可选并被标记为 deprecated——省略该配置时，将动态发现所有已安装插件。这意味着使用了该模块的部署在升级后可以逐步移除显式插件清单配置。

破坏性变更：@backstage/connections重构为公共库

为什么重构：服务契约可被同构包复用

@backstage/connections@0.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-api@1.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-backend@0.30.0-next.0对 OAuth 重定向 URI 与客户端 ID 元数据文档（Client ID Metadata Documents, CIMD）的 allowlist 模式匹配做了三项破坏性调整：

1. 按 URL 组件分别匹配：模式不再针对完整 URL 字符串匹配，而是对 host 与 path 等每个组件分别匹配；通配符不再跨越 host 与 path 边界。
2. 必须显式声明协议：模式必须包含明确的协议（如http://、https://），否则视为非法配置被拒绝，而不是静默忽略。
3. 拒绝内嵌凭据的重定向 URI：包含内嵌凭据（如https://user:pass@host/...）的重定向 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-node@0.7.4-next.0将 OAuth start 处理器在畸形 origins 下的 500 崩溃改为返回 400。

新增配置项速览

TechDocs：page:techdocs的initialFilter

@backstage/plugin-techdocs@1.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，默认 owned

Kubernetes：kubernetes.clusterLocatorContinueOnError

@backstage/plugin-kubernetes-backend@0.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-backend@0.2.1-next.0新增两项能力：

• 支持为默认服务器与命名服务器分别配置 MCP server 指令（instructions）；
• 接入 Backstage Auditor Service，为 MCP server 操作生成connection、tool-discovery、tool-execution三类审计事件，便于监控与审计 MCP 活动。

关键缺陷修复盘点

除上述新增与破坏性变更外，本版本还包含若干值得关注的修复：

升级建议与检查清单

综合以上变更，从 v1.53.x 升级到 v1.54.0-next.0 时建议按以下顺序自查：

1. 连接配置：为所有连接补齐至少一种认证方式（无需认证用none）；将 AWS CodeCommit 无认证配置迁移为 access key 或 assume role；如直接 import 过connectionsServiceRef/DefaultConnectionsService等符号，改为使用@backstage/connections-node或内部实现。
2. OAuth allowlist：重写所有allowedRedirectUriPatterns，确保含显式协议、通配符不跨组件、通配端口时显式写出路径（http://localhost:*/*）。
3. OpenAPI 文档提供商：如使用catalog-backend-module-backstage-openapi，确认catalog.providers.backstageOpenapi.plugins可以移除或保持与自动发现结果一致。
4. 新增配置按需启用：TechDocsinitialFilter、KubernetesclusterLocatorContinueOnError、MCP server instructions 均为可选，按场景开启。
5. 回归验证：重点回归 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