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.1next 系列预发布版本中影响最深远的变更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.0Major 版本含两处 BREAKINGbackstage/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-backend2.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解析工具parseEntityYaml2. 迁往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 退出默认处理器集合BREAKINGCodeOwnersProcessor不再出现在 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.disableDefaultProcessorsMinor新增布尔配置项catalog.disableDefaultProcessors允许完全禁用默认实体处理器从而对 catalog 处理流水线获得更细粒度的控制权。其实现逻辑位于 CatalogBuilder.tsconst 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 构造签名收紧BREAKINGDefaultSchedulerService的构造函数现在强制要求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-api1.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.omitIdentityTokenOwnershipClaimPatch 但影响面大新增配置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 中包含uipuser identity proof字段。对使用keyStore.provider: static配置项见 auth-backend/config.d.ts的部署令牌验签与解析逻辑需与标准结构对齐。auth-nodesign-in 结果携带 identitybackstage/plugin-auth-node0.6.3-next.1为BackstageSignInResult新增identity属性prepareBackstageIdentityResponse函数在 sign-in 结果携带该属性时会将其转发到响应中方便自定义 sign-in resolver 传递额外的身份信息。scaffolder-backend 1.33.0新增 workspace:template 动作系列Minorscaffolder 新增workspace:template与workspace:template:file两个动作与既有的fetch:*动作互补。两者均在工作区内部完成模板化而非从外部 SCM 拉取模板适用于模板文件已存在于工作区、或需要把模板化能力内聚到现有流程的场景。以workspace:template为例其定义位于 workspaceTemplate.ts动作 id 为workspace:template职责是对sourcePath指向的文件与目录名称、内容进行模板变量渲染并将结果放入targetPath指定的工作区子目录。支持的输入参数参数类型说明sourcePathstring必填工作区内模板源路径targetPathstring必填结果输出目录不得与 sourcePath 重叠valuesrecord可选传给模板引擎的变量值copyWithoutTemplatingstring[]可选glob 模式数组命中的文件/目录原样复制不渲染内容但路径仍参与渲染cookiecutterCompatboolean可选开启与fetch:cookiecutter模板的最大兼容templateFileExtensionstring | boolean可选仅渲染指定扩展名的文件设为true时使用默认扩展名.njkreplaceboolean可选是否覆盖 targetPath 中已存在的文件默认跳过该动作支持 dry-runsupportsDryRun: true并基于resolveSafeChildPath约束路径避免越界访问。同目录下的 workspaceTemplateFile.ts 提供面向单个文件的变体。此外本版本修复了fs:delete的一个 bug此前通配符模式无法匹配以.开头的路径如.github/现已修正。事件与集成模块变更GitHub webhook 校验方式切换backstage/plugin-events-backend-module-github0.4.0-next.1为BREAKING移除了createGithubSignatureValidator导出改为基于integrations.github[].apps[].webhookSecret配置进行 webhook 校验。使用旧校验器构建事件订阅的部署需迁移到新的集成配置驱动的校验方式。MS Graph catalog 模块支持复杂查询路径backstage/plugin-catalog-backend-module-msgraph0.7.0-next.1为各类查询新增userGroupMember.path、user.path、group.path选项允许编写更复杂的 Microsoft Graph 查询例如按嵌套路径过滤扩展了组织数据接入能力。KubernetesPinnipedHelper 改用统一日志服务backstage/plugin-kubernetes-node0.3.0-next.1为BREAKINGPinnipedHelper类现在接收新后端系统的标准LoggerService实例而非 Winston logger。同时kubernetes/client-node依赖升级到1.1.2plugin-kubernetes-backend将集群详情的日志级别降为 debug 以减少日志噪音kubernetes-react新增 headlamp formatter。权限模块请求体大小限制修复backstage/plugin-permission-backend、plugin-permission-common、plugin-permission-node共同修复了PermissionClient在高频请求场景下过快耗尽请求体大小限制的问题同一 PR4da2965提升了批量权限评估的稳定性。前端与 UI 变更速览frontend-plugin-api0.10.2createFrontendPlugin的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.0Button / IconButton 的图标必须显式作为 JSX 传入Button iconStart{ChevronDownIcon /} /BREAKING同时改进 Select 标签点击聚焦触发元素、TextField 标签交互样式并修复 DataTable.Pagination “to” 计数显示错误。search-react1.9.0搜索过滤器可分别提供 label 与 value而非只能提供值前端展示与提交值解耦。core-components0.17.2LogViewer新增textWrapprop超长日志行可自动换行而非水平滚动修复可滚动隐藏侧边栏的子菜单显示问题。theme0.6.6MuiTableSortLabel聚焦时显示排序箭头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-utilscreateMockActionContext支持可选的user字段。backend-dynamic-feature-serviceFrontendRemoteResolver的拼写错误方法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 破坏性升级与后端新能力
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.1next 系列预发布版本中影响最深远的变更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.0Major 版本含两处 BREAKINGbackstage/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-backend2.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解析工具parseEntityYaml2. 迁往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 退出默认处理器集合BREAKINGCodeOwnersProcessor不再出现在 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.disableDefaultProcessorsMinor新增布尔配置项catalog.disableDefaultProcessors允许完全禁用默认实体处理器从而对 catalog 处理流水线获得更细粒度的控制权。其实现逻辑位于 CatalogBuilder.tsconst 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 构造签名收紧BREAKINGDefaultSchedulerService的构造函数现在强制要求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-api1.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.omitIdentityTokenOwnershipClaimPatch 但影响面大新增配置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 中包含uipuser identity proof字段。对使用keyStore.provider: static配置项见 auth-backend/config.d.ts的部署令牌验签与解析逻辑需与标准结构对齐。auth-nodesign-in 结果携带 identitybackstage/plugin-auth-node0.6.3-next.1为BackstageSignInResult新增identity属性prepareBackstageIdentityResponse函数在 sign-in 结果携带该属性时会将其转发到响应中方便自定义 sign-in resolver 传递额外的身份信息。scaffolder-backend 1.33.0新增 workspace:template 动作系列Minorscaffolder 新增workspace:template与workspace:template:file两个动作与既有的fetch:*动作互补。两者均在工作区内部完成模板化而非从外部 SCM 拉取模板适用于模板文件已存在于工作区、或需要把模板化能力内聚到现有流程的场景。以workspace:template为例其定义位于 workspaceTemplate.ts动作 id 为workspace:template职责是对sourcePath指向的文件与目录名称、内容进行模板变量渲染并将结果放入targetPath指定的工作区子目录。支持的输入参数参数类型说明sourcePathstring必填工作区内模板源路径targetPathstring必填结果输出目录不得与 sourcePath 重叠valuesrecord可选传给模板引擎的变量值copyWithoutTemplatingstring[]可选glob 模式数组命中的文件/目录原样复制不渲染内容但路径仍参与渲染cookiecutterCompatboolean可选开启与fetch:cookiecutter模板的最大兼容templateFileExtensionstring | boolean可选仅渲染指定扩展名的文件设为true时使用默认扩展名.njkreplaceboolean可选是否覆盖 targetPath 中已存在的文件默认跳过该动作支持 dry-runsupportsDryRun: true并基于resolveSafeChildPath约束路径避免越界访问。同目录下的 workspaceTemplateFile.ts 提供面向单个文件的变体。此外本版本修复了fs:delete的一个 bug此前通配符模式无法匹配以.开头的路径如.github/现已修正。事件与集成模块变更GitHub webhook 校验方式切换backstage/plugin-events-backend-module-github0.4.0-next.1为BREAKING移除了createGithubSignatureValidator导出改为基于integrations.github[].apps[].webhookSecret配置进行 webhook 校验。使用旧校验器构建事件订阅的部署需迁移到新的集成配置驱动的校验方式。MS Graph catalog 模块支持复杂查询路径backstage/plugin-catalog-backend-module-msgraph0.7.0-next.1为各类查询新增userGroupMember.path、user.path、group.path选项允许编写更复杂的 Microsoft Graph 查询例如按嵌套路径过滤扩展了组织数据接入能力。KubernetesPinnipedHelper 改用统一日志服务backstage/plugin-kubernetes-node0.3.0-next.1为BREAKINGPinnipedHelper类现在接收新后端系统的标准LoggerService实例而非 Winston logger。同时kubernetes/client-node依赖升级到1.1.2plugin-kubernetes-backend将集群详情的日志级别降为 debug 以减少日志噪音kubernetes-react新增 headlamp formatter。权限模块请求体大小限制修复backstage/plugin-permission-backend、plugin-permission-common、plugin-permission-node共同修复了PermissionClient在高频请求场景下过快耗尽请求体大小限制的问题同一 PR4da2965提升了批量权限评估的稳定性。前端与 UI 变更速览frontend-plugin-api0.10.2createFrontendPlugin的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.0Button / IconButton 的图标必须显式作为 JSX 传入Button iconStart{ChevronDownIcon /} /BREAKING同时改进 Select 标签点击聚焦触发元素、TextField 标签交互样式并修复 DataTable.Pagination “to” 计数显示错误。search-react1.9.0搜索过滤器可分别提供 label 与 value而非只能提供值前端展示与提交值解耦。core-components0.17.2LogViewer新增textWrapprop超长日志行可自动换行而非水平滚动修复可滚动隐藏侧边栏的子菜单显示问题。theme0.6.6MuiTableSortLabel聚焦时显示排序箭头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-utilscreateMockActionContext支持可选的user字段。backend-dynamic-feature-serviceFrontendRemoteResolver的拼写错误方法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），仅供参考
