Backstage v1.39.0-next.1 预发布版本深度解读：catalog-backend 2.0 破坏性升级与后端新能力-编程实验室

Backstage v1.39.0-next.1 预发布版本深度解读：catalog-backend 2.0 破坏性升级与后端新能力

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

本篇指南面向 Backstage 维护者与升级规划人员，系统解读 v1.39.0-next.1（next 系列预发布版本）中影响最深远的变更：@backstage/plugin-catalog-backend2.0.0 的 Major 级破坏性升级（移除全部废弃导出、停止旧后端系统支持、CodeOwnersProcessor 退出默认处理器），以及调度器 REST API、Valkey 缓存支持、令牌瘦身、插件模块启动容错等一批后端新能力。读完本文，你将掌握每个包在升级时的迁移动作、新增配置项的用法，以及这些变更背后的源码实现依据，可据此制定完整的升级计划。

版本概览：next 预发布版本意味着什么

v1.39.0-next.1是 Backstage 1.39.0 正式版发布前的第二个预发布快照（后缀next.N表示版本演进中的中间态）。这类版本用于在正式发布前验证依赖链与破坏性变更的兼容性，其 API 与行为仍可能变化，不建议直接用于生产环境。该版本包含 60 余个包的同步更新，其中最核心的信号是：

@backstage/plugin-catalog-backend首次进入2.0.0（Major 版本，含两处 BREAKING）；
@backstage/backend-defaults、@backstage/backend-app-api、@backstage/plugin-auth-backend、@backstage/plugin-scaffolder-backend等核心后端包均有实质性能力增强；
大量前端包完成createFrontendPlugin的pluginId参数迁移。

完整变更记录以仓库内 docs/releases/v1.39.0-next.1-changelog.md 为准，本文按包维度展开解读。

最大变更：catalog-backend 2.0.0 的破坏性升级

@backstage/plugin-catalog-backend@2.0.0-next.1是本次发布的绝对主角，Major 变更围绕“清退历史包袱、收敛默认行为”展开，共分为四个层面。

移除全部废弃导出，并停止旧后端系统支持

BREAKING：该版本删除了plugin-catalog-backend中所有已废弃的导出，同时移除了对旧后端系统的支持。被移除的导出按去向分为三类：

1. 迁往@backstage/plugin-catalog-node（共 28 个），自定义插件与模块应从新包导入：

位置相关：locationSpecToMetadataName、locationSpecToLocationEntity
处理结果与过滤：processingResult、EntitiesSearchFilter、EntityFilter、DeferredEntity、EntityRelationSpec
处理器类型：CatalogProcessor、CatalogProcessorParser、CatalogProcessorCache、CatalogProcessorEmit、CatalogProcessorLocationResult、CatalogProcessorEntityResult、CatalogProcessorRelationResult、CatalogProcessorErrorResult、CatalogProcessorRefreshKeysResult、CatalogProcessorResult
实体提供者：EntityProvider、EntityProviderConnection、EntityProviderMutation
位置分析：AnalyzeOptions、LocationAnalyzer、ScmLocationAnalyzer
占位符解析：PlaceholderResolver、PlaceholderResolverParams、PlaceholderResolverRead、PlaceholderResolverResolveUrl
解析工具：parseEntityYaml

2. 迁往@backstage/plugin-catalog-common（共 5 个）：LocationSpec、AnalyzeLocationRequest、AnalyzeLocationResponse、AnalyzeLocationExistingEntity、AnalyzeLocationGenerateEntity。

3. 由新后端系统的@backstage/plugin-search-backend-module-catalog实现（共 3 个）：defaultCatalogCollatorEntityTransformer、CatalogCollatorEntityTransformer、DefaultCatalogCollator。即 catalog 文档的搜索索引收集逻辑已完全移交搜索模块，需在依赖与注册方式上同步调整。

从源码结构看，当前plugin-catalog-backend的公开处理器集合已收敛为 src/processors/index.ts 中导出的AnnotateLocationEntityProcessor、AnnotateScmSlugEntityProcessor、BuiltinKindsEntityProcessor、CodeOwnersProcessor、FileReaderProcessor、PlaceholderProcessor、UrlReaderProcessor等，类型层职责则明确交由plugin-catalog-node承担，这正是本次导出大迁移的落地体现。

无直接替代的移除项

以下导出被直接删除，没有替代品，若仍在引用需彻底改写调用逻辑：

移除项	说明
`DefaultCatalogCollatorFactory`/`DefaultCatalogCollatorFactoryOptions`	搜索收集器工厂，改由 search 模块负责
`LocationEntityProcessor`/`LocationEntityProcessorOptions`	位置实体处理器
`CatalogBuilder`/`CatalogEnvironment`	旧后端系统的构建器入口
`CatalogPermissionRuleInput`	权限规则输入类型
`CatalogProcessingEngine`	处理引擎类型
`createRandomProcessingInterval`/`ProcessingIntervalFunction`	随机处理间隔工具函数

CodeOwnersProcessor 退出默认处理器集合

BREAKING：CodeOwnersProcessor不再出现在 catalog 的默认处理器集合中。官方给出的理由是它运行成本高且语义模糊（通过解析仓库中的 CODEOWNERS 文件为实体注入属主信息，解析结果依赖仓库结构与文件约定）。如果仍需使用，必须自行通过catalogProcessingExtensionPoint的addProcessor将其注册回去。

这一结论在源码中可直接验证：当前默认处理器列表只包含三个轻量处理器，见 CatalogBuilder.ts 的getDefaultProcessors()：

return [ new FileReaderProcessor(), new UrlReaderProcessor({ reader, logger }), new AnnotateLocationEntityProcessor({ integrations }), ];

而CodeOwnersProcessor仍保留在包内（src/processors/CodeOwnersProcessor.ts），只是不再默认启用。在采用新后端系统的应用中，可通过catalogProcessingExtensionPoint重新接入，该扩展点由 CatalogPlugin.ts 注册，提供addProcessor、addEntityProvider、addPlaceholderResolver、setOnProcessingErrorHandler四个方法。

/alpha 导出路径取消

BREAKING ALPHA：不再允许从@backstage/plugin-catalog-backend/alpha导入 catalog 插件，请改用常规根默认导出catalogPlugin。这进一步压缩了 alpha 通道的维护面，alpha 能力被并入正式 API。

新增配置：catalog.disableDefaultProcessors

Minor：新增布尔配置项catalog.disableDefaultProcessors，允许完全禁用默认实体处理器，从而对 catalog 处理流水线获得更细粒度的控制权。其实现逻辑位于 CatalogBuilder.ts：

const disableDefaultProcessors = config.getOptionalBoolean( 'catalog.disableDefaultProcessors', ); // Add default processors if: // - processors have NOT been explicitly replaced // - and default processors are NOT disabled via config if (!this.processorsReplace && !disableDefaultProcessors) { processors.push(...this.getDefaultProcessors()); }

注意两点边界行为：即使启用该配置，PlaceholderProcessor与BuiltinKindsEntityProcessor也始终会被加入（它们被视为 catalog 运行的基础设施，见同一文件的buildProcessors()）；同时该配置只影响默认处理器，通过扩展点显式添加的处理器不受影响。对应的配置说明定义在 config.d.ts，典型用法：

catalog: disableDefaultProcessors: true

启用后如需保留某些默认能力，需通过自定义处理器模块显式注册（如上述 CodeOwnersProcessor 场景）。

backend-defaults 0.10.0：调度器 REST API 与 Valkey 缓存

DefaultSchedulerService 构造签名收紧

BREAKING：DefaultSchedulerService的构造函数现在强制要求RootLifecycleService、HttpRouterService、PluginMetadataService三个字段。这是为调度器新增 REST API 做准备——调度器将注册用于列出与触发任务的 HTTP 接口，便于运维在运行时查看与手动触发定时任务。依赖注入形式直接构造DefaultSchedulerService的自定义代码需要补齐这三个服务引用。

Valkey 缓存支持

backend-defaults的缓存客户端在 Redis 之外新增 Valkey 支持，基于新的 Keyv Valkey 包实现；backend-test-utils同步扩展，使测试环境也能使用 Valkey。对于已用 Redis 作为缓存后端的部署，Valkey 提供了另一个兼容选项。此外本版本还包含两处小修复：GitLab URL 解析器现在会透传用户提供的 token；清理了若干文档与拼写问题。

backend-app-api：插件模块启动失败容错配置

新增能力：backend-app-api@1.2.3-next.1允许配置插件模块启动失败时是否中止整个后端启动。此前任一插件模块失败都会上抛给插件并中止后端启动；现在可以按插件、按模块精确放行。粒度配置：

backend: startup: plugins: plugin-x: modules: module-y: onPluginModuleBootFailure: continue

上面的配置允许plugin-x的module-y启动失败时继续运行；省略onPluginModuleBootFailure则保持旧行为（失败即中止）。同时支持修改全局默认值，并对个别模块反向收紧：

backend: startup: default: onPluginModuleBootFailure: continue plugins: catalog: modules: github: onPluginModuleBootFailure: abort

即默认“失败继续”，但 catalog 的 github 模块例外、失败必须中止。这一配置显著提升了后端在部分模块不可用时的韧性，适合多模块集成场景下的灰度上线。

auth-backend 0.25.0：更小的身份令牌与 key store 结构统一

新配置 auth.omitIdentityTokenOwnershipClaim

Patch 但影响面大：新增配置auth.omitIdentityTokenOwnershipClaim，启用后签发的用户令牌不再包含entclaim（用户的 ownership 引用集合）。收益是令牌体积显著减小；代价是令牌不再“自包含”，任何需要 ownership 信息的消费方都必须改调/api/auth/v1/userinfo端点。Backstage 生态内已自动处理：前端客户端在认证期间仍会获得完整 claims，而插件后端通过UserInfoService按需调用 userinfo 端点。该配置的默认值及语义在 auth-backend/config.d.ts 中有详细说明。

启用该配置时的编码约束：自定义 sign-in resolver 必须直接返回issueToken的结果，否则entclaim 会被剥离。以下写法在启用后失效：

const { token } = await ctx.issueToken({ claims: { sub: entityRef, ent: [entityRef] }, }); return { token }; // WARNING: 启用该配置后此写法不生效

应改为：

return ctx.issueToken({ claims: { sub: entityRef, ent: [entityRef] }, });

static key store 令牌结构统一

auth-backend的statickey store 现在签发的令牌与其他 key store 结构一致：header 中包含typ字段，payload 中包含uip（user identity proof）字段。对使用keyStore.provider: 'static'（配置项见 auth-backend/config.d.ts）的部署，令牌验签与解析逻辑需与标准结构对齐。

auth-node：sign-in 结果携带 identity

@backstage/plugin-auth-node@0.6.3-next.1为BackstageSignInResult新增identity属性，prepareBackstageIdentityResponse函数在 sign-in 结果携带该属性时会将其转发到响应中，方便自定义 sign-in resolver 传递额外的身份信息。

scaffolder-backend 1.33.0：新增 workspace:template 动作系列

Minor：scaffolder 新增workspace:template与workspace:template:file两个动作，与既有的fetch:*动作互补。两者均在工作区内部完成模板化，而非从外部 SCM 拉取模板，适用于模板文件已存在于工作区、或需要把模板化能力内聚到现有流程的场景。

以workspace:template为例，其定义位于 workspaceTemplate.ts，动作 id 为workspace:template，职责是：对sourcePath指向的文件与目录名称、内容进行模板变量渲染，并将结果放入targetPath指定的工作区子目录。支持的输入参数：

参数	类型	说明
`sourcePath`	string（必填）	工作区内模板源路径
`targetPath`	string（必填）	结果输出目录，不得与 sourcePath 重叠
`values`	record（可选）	传给模板引擎的变量值
`copyWithoutTemplating`	string[]（可选）	glob 模式数组，命中的文件/目录原样复制（不渲染内容，但路径仍参与渲染）
`cookiecutterCompat`	boolean（可选）	开启与`fetch:cookiecutter`模板的最大兼容
`templateFileExtension`	string \| boolean（可选）	仅渲染指定扩展名的文件；设为`true`时使用默认扩展名`.njk`
`replace`	boolean（可选）	是否覆盖 targetPath 中已存在的文件（默认跳过）

该动作支持 dry-run（supportsDryRun: true），并基于resolveSafeChildPath约束路径，避免越界访问。同目录下的 workspaceTemplateFile.ts 提供面向单个文件的变体。此外本版本修复了fs:delete的一个 bug：此前通配符模式无法匹配以.开头的路径（如.github/），现已修正。

事件与集成模块变更

GitHub webhook 校验方式切换

@backstage/plugin-events-backend-module-github@0.4.0-next.1为BREAKING：移除了createGithubSignatureValidator导出，改为基于integrations.github[].apps[].webhookSecret配置进行 webhook 校验。使用旧校验器构建事件订阅的部署需迁移到新的集成配置驱动的校验方式。

MS Graph catalog 模块支持复杂查询路径

@backstage/plugin-catalog-backend-module-msgraph@0.7.0-next.1为各类查询新增userGroupMember.path、user.path、group.path选项，允许编写更复杂的 Microsoft Graph 查询（例如按嵌套路径过滤），扩展了组织数据接入能力。

Kubernetes：PinnipedHelper 改用统一日志服务

@backstage/plugin-kubernetes-node@0.3.0-next.1为BREAKING：PinnipedHelper类现在接收新后端系统的标准LoggerService实例，而非 Winston logger。同时@kubernetes/client-node依赖升级到1.1.2，plugin-kubernetes-backend将集群详情的日志级别降为 debug 以减少日志噪音，kubernetes-react新增 headlamp formatter。

权限模块：请求体大小限制修复

@backstage/plugin-permission-backend、plugin-permission-common、plugin-permission-node共同修复了PermissionClient在高频请求场景下过快耗尽请求体大小限制的问题（同一 PR4da2965），提升了批量权限评估的稳定性。

前端与 UI 变更速览

frontend-plugin-api0.10.2：createFrontendPlugin的id选项更名为pluginId，与前后端系统 API 对齐；旧id已废弃、将在后续版本移除。core-compat-api、frontend-test-utils及api-docs、catalog、home、notifications、scaffolder、search、signals、techdocs、user-settings、app-visualizer、devtools、kubernetes、org等前端插件均同步完成内部迁移。
canon0.4.0：Button / IconButton 的图标必须显式作为 JSX 传入：<Button iconStart={<ChevronDownIcon />} />（BREAKING）；同时改进 Select 标签点击聚焦触发元素、TextField 标签交互样式，并修复 DataTable.Pagination “to” 计数显示错误。
search-react1.9.0：搜索过滤器可分别提供 label 与 value，而非只能提供值，前端展示与提交值解耦。
core-components0.17.2：LogViewer新增textWrapprop，超长日志行可自动换行而非水平滚动；修复可滚动隐藏侧边栏的子菜单显示问题。
theme0.6.6：MuiTableSortLabel聚焦时显示排序箭头；user-settings语言选择器大写显示语言名；org插件在GroupProfileCard展示 entity-ref 便于获取 Group ID，并修复MyGroupsSidebarItem未渲染spec.profile.displayName的问题。

值得关注的修复

MySQL TEXT 限制修复（catalog-backend）：当 Backstage 配置 MySQL 数据库时，若一个location类型实体（如 all.yaml）引用了 70 个以上实体，点击 “Refresh” 无法按预期更新被引用实体。根因是 MySQL 的 TEXT 类型上限为 65,535 字节，不足以存储全部被引用实体导致刷新失败，本版本已修复。
plugin-catalog-react：修复选中 owner 后 user/group 类型实体显示为空的问题。
notifications-backend-module-slack：用户实体缺少metadata.annotations.slack.com/bot-notify时，改为按邮箱进行 Slack User ID 查找。
scaffolder-node-test-utils：createMockActionContext支持可选的user字段。
backend-dynamic-feature-service：FrontendRemoteResolver的拼写错误方法getAdditionaRemoteInfo已废弃，请改用正确的getAdditionalRemoteInfo。
plugin-catalog-backend-module-backstage-openapi：错误不再被吞掉，而是向上冒泡到任务调度器以便跟踪与记录日志。

升级行动清单

处理 catalog-backend 破坏性导入：将废弃导出迁移到@backstage/plugin-catalog-node与@backstage/plugin-catalog-common；搜索相关收集器改用@backstage/plugin-search-backend-module-catalog；无替代的导出需重构调用逻辑。
如需 CodeOwners 功能：通过catalogProcessingExtensionPoint的addProcessor显式注册CodeOwnersProcessor（源码参考 CatalogPlugin.ts）。
评估默认处理器策略：如需完全掌控处理流水线，启用catalog.disableDefaultProcessors: true（实现见 CatalogBuilder.ts）。
补齐 scheduler 构造依赖：直接实例化DefaultSchedulerService的代码需传入RootLifecycleService、HttpRouterService、PluginMetadataService。
令牌瘦身按需启用：评估auth.omitIdentityTokenOwnershipClaim，并检查自定义 sign-in resolver 是否直接返回issueToken结果。
配置启动容错：按模块设置onPluginModuleBootFailure，先全局 continue、对关键模块 abort。
同步前端 API：将createFrontendPlugin的id改为pluginId；核对 canon 图标 JSX 写法与 search 过滤器 label/value 用法。
GitHub webhook 迁移：从createGithubSignatureValidator迁移到integrations.github[].apps[].webhookSecret配置驱动的校验。

由于next版本 API 仍处演进中，正式版发布前可能继续调整，建议以最终稳定版 changelog 为准执行生产升级。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Backstage v1.39.0-next.1 预发布版本深度解读：catalog-backend 2.0 破坏性升级与后端新能力