企业官网建设流程全解析

Backstage v1.54.0 版本解读：OAuth 白名单收紧、Catalog 可靠性增强与 Agent 友好的实体刷新

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本文以 Backstage 官方仓库 docs/releases/v1.54.0.md 版本说明为骨架，系统梳理 v1.54.0 中四项 BREAKING 变更（OAuth 重定向 URI 白名单、config.schema移除、Connections 共享契约、OpenAPI 校验命令更名）、Catalog 后端可靠性优化、新增的refresh-catalog-entityAgent 动作、稳定的系统元数据服务、TechDocs 初始过滤器配置等核心更新，并结合本仓库源码与测试给出落地与升级建议。读完本文，你将能判断自己的 Backstage 实例是否受破坏性变更影响、如何针对性地调整配置与代码，并快速上手 v1.54.0 的新能力。

一、破坏性变更（BREAKING）：升级前必须处理的事项

v1.54.0 共有四项破坏性变更，升级前需逐一核对自建应用与插件的用法。

1.1 OAuth 重定向 URI 白名单匹配收紧

@backstage/plugin-auth-backend中的 OAuth 重定向 URI 与 Client ID 元数据文档（Client ID Metadata Documents）白名单，匹配方式由「对完整 URL 字符串做模式匹配」改为「对 URL 的每个组成部分分别匹配」。这意味着：

• 通配符不再跨 host 与 path 边界：例如http://*.example.com/*中的*不能同时吞掉域名段和路径段。
• 模式必须显式包含协议：不含协议（如//host/path或裸路径）的模式会被判定为非法配置而直接拒绝，不再被静默忽略。
• 内嵌凭据的重定向 URI 一律拒绝：形如http://user:pass@host/callback的 URI 不再被接受。
• 通配端口不再隐式匹配任意路径：http://localhost:*现在只匹配根路径；如需「任意端口 + 任意路径」，必须写成http://localhost:*/*。

版本说明特别强调：内置的 loopback 默认值已同步更新，因此该变更只影响显式配置的模式。从源码看，相关实现集中在 plugins/auth-backend/src/service/OidcService.ts、plugins/auth-backend/src/service/OidcRouter.ts 及其配套测试 plugins/auth-backend/src/service/OidcRouter.test.ts，测试用例覆盖了跨 host/path 通配、缺失协议、内嵌凭据等场景，升级前可对照检查自己app-config.yaml中的auth.providers回调地址配置。

另外，随本次收紧一并修复了两处关联问题：OAuth 启动请求携带畸形 origin 时由 500 改为返回 400；配置了allowedClientIdPatterns的内置 CLI 客户端不再被错误拒绝（plugins/auth-backend/src/service/CimdClient.ts）。

1.2 废弃的扩展项config.schema被移除

@backstage/frontend-plugin-api中废弃的扩展与扩展蓝图（extension blueprint）配置项config.schema已彻底移除，请改用顶层configSchema选项，并传入兼容 Standard Schema 的 schema 实现（例如 Zod v4）。若你的前端插件仍在用旧写法，升级后构建会直接报错。

1.3 Connections 迁移到共享契约

Connections API 仍处于早期阶段，此项变更只影响已在试用它的用户。需要做的调整有三点：

1. 将后端导入从@backstage/connections更新为新的共享契约来源；
2. 连接查找（connection lookups）改为传入带类型的query对象，而不再使用顶层url参数；
3. 将RootConnectionAuth重命名为ConfiguredConnectionAuth。

同时新增了 GitHub 与 AWS 两种连接类型。仓库中 packages/connections、packages/connections-node 以及示例 plugins/connections-example-backend 可作为迁移参考。

1.4 OpenAPI 校验命令更名

仓库工具链命令调整：

• backstage-repo-tools repo schema openapi verify→ 更名为backstage-repo-tools repo schema openapi validate；
• 新增backstage-repo-tools package schema openapi validate，可对单个包的 OpenAPI 3.x 文档做校验。

CI 脚本或手动流程中引用旧命令名的需要同步更新。

二、Create-app 与 Home 页更新

2.1 新应用脚手架增强

用@backstage/create-app创建的新应用现在自带：

• GitHub Actions CI 工作流：PR 上自动执行 lint、类型检查、测试、配置校验以及 Docker 镜像构建；
• 预配置的 Home 页：带可定制的小组件网格（widget grid）；
• 前置环境检查：create-app在脚手架生成前会检查 Node.js LTS 版本与 Yarn 是否可用。

2.2 Home 插件新增前端系统小组件蓝图

Home 插件（plugins/home）新增了以下前端系统（new frontend system）小组件蓝图（widget blueprints）：

• Most Visited（最常访问）
• Recently Visited（最近访问）
• World Clocks（世界时钟）
• 可配置的 Toolkit（工具箱）
• 来自 Search 插件的搜索栏

同时 Home 页布局支持通过defaultConfig在应用配置中定义初始小组件网格。相关前端实现可从 plugins/home/src/alpha.tsx（前端系统 alpha 注册）与 plugins/home/src/homePageComponents/Toolkit/Content.tsx（Toolkit 组件内容）入手阅读。

三、Catalog 后端可靠性、性能与 AiResource 增强

3.1 关系同步改为「增量 diff」

Catalog 后端的关系同步（relation sync）由「删除后全量重插」改为仅应用变更行的 diff。在稳态下，这一改动避免了不必要的写入、dead tuples、WAL 流量，以及针对未变化关系邻接点的拼接（stitching）工作，是 v1.54.0 中一项重要的性能与数据库压力优化。

3.2 写入韧性与事件过滤

• PostgreSQL：实体提供者（entity provider）变更在遇到死锁（deadlock）时自动重试；
• MySQL：并发实体处理在updateProcessedEntity事务死锁时自动重试；
• SCM：未被主动跟踪的文件触发location.moved事件时将被忽略，避免产生虚假的 location。

3.3 alphaAiResourcekind 扩展

仍处于 alpha 阶段的AiResourcecatalog kind 现在支持：

• plugin与marketplace两种 spec 类型；
• skill 资源的allowedTools、license、compatibility字段；
• 关系生成会遵循声明的 kind 组合，并补齐既有AiResource字段的逆向关系。

相关 PR（#34890、#34891、#34892）由 @nickwtan 贡献。

四、Agent 友好的 Catalog 刷新：refresh-catalog-entity

这是 v1.54.0 中最值得关注的面向 Agent/MCP 场景的能力：@backstage/plugin-catalog-backend新增了refresh-catalog-entity动作（action），允许 Agent 或 MCP 客户端在创建/更新实体后立即将单个实体重新入队处理，从而无需等待下一个调度周期即可读到最新数据——典型场景是 scaffolder 运行结束后立刻回读新实体的最新信息。

从源码 plugins/catalog-backend/src/actions/createRefreshCatalogEntityAction.ts 可以看到其完整契约：

• 输入参数（均来自z.object校验）：
  • name（必填）：要刷新的实体名称，会先trim；
  • kind（可选）：实体 kind，如Component、API、System，名称冲突时用于消歧；
  • namespace（可选）：实体命名空间，同上用于消歧。
• 输出：entityRef，被刷新实体的规范化实体引用。
• 执行逻辑：先通过catalog.queryEntities按metadata.name（可叠加kind、metadata.namespace）过滤；找不到实体抛InputError；匹配到多个实体抛ConflictError并列出候选引用；唯一命中后调用catalog.refreshEntity(entityRef, { credentials })重新入队。
• 动作属性：destructive: false、readOnly: false、idempotent: true（可安全重试）。

配套测试见 plugins/catalog-backend/src/actions/createRefreshCatalogEntityAction.test.ts，覆盖了未命中、多命中、正常刷新等路径。该功能由 @Naga15 在 PR #34447 中贡献。

五、Kubernetes 与 MCP Actions 审计日志

5.1 Kubernetes 后端审计事件

@backstage/plugin-kubernetes-backend现在会对以下请求发出审计（auditor）事件：

• 集群列表（cluster list）
• 集群代理（cluster proxy）
• 实体工作负载（entity workload）
• 自定义资源（custom resource）
• 已废弃的 services 端点

管理员可依据eventId（如cluster-fetch、resource-fetch）以及queryType元数据过滤审计日志。

API 代理缓存刷新：Kubernetes API 代理现在会在集群详情变化、超过可配置 TTL、或缓存达到大小上限时刷新缓存中间件；同时会对配置了skipTLSVerify: true的集群输出启动警告日志。

5.2 MCP Actions 审计事件与指令配置

@backstage/plugin-mcp-actions-backend现在对 MCP 服务器连接、工具发现（tool discovery）与工具执行（tool execution）操作发出审计事件。MCP 服务器还支持为默认服务器与具名服务器分别配置指令（instructions）。相关修复还包括：MCP OAuth 元数据现在能让符合 RFC 的客户端知道应请求哪些 scope，并在启用 refresh token 时正常获取刷新令牌。

六、稳定的系统元数据服务：coreServices.rootSystemMetadata

coreServices.rootSystemMetadata在 v1.54.0 中成为稳定（stable）的后端服务，用于读取当前 Backstage 系统的元数据，包括已安装的插件列表。

源码层面：

• 服务引用定义于 packages/backend-plugin-api/src/services/definitions/coreServices.ts（id: 'core.rootSystemMetadata'，scope: 'root'）；
• 接口定义于 packages/backend-plugin-api/src/services/definitions/RootSystemMetadataService.ts，核心方法为getInstalledPlugins(): Promise<ReadonlyArray<{ pluginId: string }>>。

该服务由@backstage/backend-defaults自动注册；测试工具集新增了mockServices.rootSystemMetadata；内部的 OpenAPI 文档提供者现在可以自动通过系统元数据发现已安装插件，无需手工维护插件清单。

七、TechDocs 初始过滤器配置

TechDocs 页面扩展（page:techdocs）新增initialFilter配置项，可选值：

从实现看，plugins/techdocs/src/alpha/components/TechDocsIndexPageContent.tsx 中initialFilter默认值为'owned'，并直接透传给UserListPicker（来自@backstage/plugin-catalog-react），与 Catalog 的「Owned/Starred/All」筛选语义保持一致。注意：该配置属于新前端系统（alpha）的扩展配置，配套的 alpha API 报告见 plugins/techdocs/report-alpha.api.md。

八、配置 schema 校验改进

8.1 更严格的包发布前校验

• 包发布前（package preparation）：TypeScript 配置 schema 现在会在发布前被严格校验；
• 其他构建/打包路径：schema 错误降级为警告；
• CLI 严格模式：backstage-cli config:check --strict与backstage-cli config:schema --strict现在会把 TypeScript 配置 schema 错误视为致命错误。

8.2 可恢复错误与 bug 修复

@backstage/config-loader新增onSchemaError回调，调用方可在上报 schema 错误后继续加载配置。同时修复了一个 bug：严格配置检查此前会错误拒绝合法的「开放对象 schema」（open-ended object schemas）。

九、Backstage UI（BUI）与杂项修复

• 修复了 Firefox 中Table直接位于ResizableTableContainer内时无法撑满容器宽度的问题（PR #34755，@robingileborg）；更多细节见 BUI Changelog。

其余值得关注的修复与增强（详见 docs/releases/v1.54.0.md 原文）：

• 前端系统：配置驱动的路由重定向保留原 URL 的查询串与 fragment；SubRouteRef可作为另一个SubRouteRef的父级；修复上下文未变化时的多余实体页/分析重渲染；修复目录实体页间跳转时的短暂 "Entity not found" 闪烁；目录图谱页打开时即应用配置的过滤器与图谱默认值。
• Catalog UI：EntityOwnerPicker的owners-only模式显示可读实体标题，并通过虚拟化支撑超长 owner 列表；UserListPicker修复用户无 ownership 引用时把所有实体误标为 "Owned" 的问题；About 卡字段标签不再受主题排版覆盖影响；Unprocessed Entities UI 迁移至 Backstage UI 组件，并给 pending 实体标签页增加搜索。
• 权限系统：权限规则参数 schema 现在接受兼容 JSON Schema 的 Standard Schema 实现（如 Zod v4）；Zod v3 仍支持但已标记废弃。
• 通知：修复循环组关系下的收件人解析；Slack 通知支持通过payload.metadata.slackChannel路由到指定频道。
• Kubernetes：新增kubernetes.clusterLocatorContinueOnError配置项，单个 locator 失败时可跳过并继续返回其他 locator 的集群；修复 AWS IAM 策略在按账户 assume-role 配置下的凭据解析。
• Scaffolder：任务会等待恢复检查点（recovery checkpoint）状态持久化后再继续，且恢复的检查点保留 falsy 值而不重跑回调；模板渲染不再要求原生 addon；publish:gerrit动作的description参数改为可选。
• CLI：新增backstage-cli new模板——权限策略模块、搜索 collator 模块、catalog processor 模块；修复多个模板的 "No version available" 错误；生成的插件模板改用toastApiRef、为权限策略模块注入UserInfoService、改进表格可访问性并补齐后端模块依赖。
• 其他：Catalog 导出与 Backstage ESLint 插件提升 TypeScript 7 前向兼容；Azure DevOps URL reader 把 abort 信号转发给 commits API 请求；renderInTestApp修复 mock identity 被默认 guest 回退覆盖的问题；email 通知模块的nodemailer从 v8 升级到 v9（新主版本默认在拉取远程内容如附件或 OAuth2 token 时校验 TLS 证书）；受限用户 token 在缺少用户 IP 元数据时改为抛错而非构造非法 token。

十、安全修复

v1.54.0 包含 Kubernetes 插件的关键安全修复（critical security fixes）。版本说明原文仅给出这一摘要，建议 Kubernetes 插件使用者优先升级并留意 release changelog：docs/releases/v1.54.0-changelog.md。

十一、升级建议

Backstage 官方推荐保持项目与最新 release 同步。升级时建议按以下顺序排查：

1. 对照破坏性变更清单（第一节）检查：auth.providers的 OAuth 回调白名单模式、前端插件的config.schema写法、Connections 试用代码、OpenAPI 校验命令名；
2. 确认 Kubernetes 插件安全修复已随升级生效，并检查是否配置了skipTLSVerify: true（现在会产生启动警告）；
3. 尝鲜新能力：在 MCP/Agent 工作流中接入refresh-catalog-entity动作、在 TechDocs 页面配置initialFilter、通过coreServices.rootSystemMetadata读取已安装插件、为 Home 页配置defaultConfig小组件网格；
4. 完整的升级操作指引可参考 docs/getting-started/keeping-backstage-updated.md，版本支持策略见 docs/overview/versioning-policy.md。

本仓库中该版本的完整变更明细与逐条 PR 对照，可继续阅读 docs/releases/v1.54.0-changelog.md；仓库内其他历史版本说明见 docs/releases 目录，便于做版本间行为对比。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage