Backstage v1.41.0 升级指南catalog-backend 3.0.0 破坏性变更与 Scaffolder 任务权限模型重构【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage v1.41.0 是一次包含多个 Major 版本升级的重要发布其中最核心的是backstage/plugin-catalog-backend迎来 3.0.0 大版本涉及缝补stitching策略、孤儿实体处理策略、UrlReader 搜索行为等多处默认行为切换同时 Scaffolder 的任务权限从基础权限升级为 Resource Permissionsbackstage/canon也正式更名为backstage/ui。阅读本文后你将掌握 v1.41.0 中每项破坏性变更的具体含义、如何通过配置适配新行为以及 Scaffolder 新的任务级条件授权规则isTaskOwner的编写与验证方式。本文基于仓库内官方发布说明 docs/releases/v1.41.0-changelog.md 整理并辅以对应源码佐证帮助你快速评估升级影响面并规划迁移动作。升级前必读总体变更概览v1.41.0 的变更集中在以下几个方面关注点涉及包变更类型影响Catalog 默认策略切换backstage/plugin-catalog-backend3.0.0Major / BREAKING需检查app-config.yaml中相关配置Scaffolder 任务权限模型plugin-scaffolder、plugin-scaffolder-backend、plugin-scaffolder-common、plugin-scaffolder-node、plugin-scaffolder-reactMinor / BREAKING (/alpha)自定义权限策略需适配UI 组件库更名backstage/canon→backstage/uiMinor / Breaking涉及组件 API 与 CSS 类名通知与邮件处理器plugin-notifications-backend、notifications-backend-module-emailPatch新增配置项向后兼容Scaffolder 模块plugin-scaffolder-backend-module-github等Patch新增filesToDelete能力此外backstage/core-app-api1.18.0、backstage/repo-tools0.15.0、backstage/backend-test-utils1.7.0也有少量增强例如 credentials 对象新增标准toString方法、package-docs命令会先清空输出目录并跳过内部包等。catalog-backend 3.0.0四项默认行为切换backstage/plugin-catalog-backend从 2.x 直接升到 3.0.0携带四项 Breaking 变更全部与默认行为有关。多数情况下你不需要改任何代码但需要确认既有配置没有依赖旧默认值。1. 默认缝补策略切换为deferred变更内容默认的catalog.stitchingStrategy由原来的{ mode: immediate }切换为{ mode: deferred }对应提交5127ebe。源码层面stitching/types.ts 中的stitchingStrategyFromConfig已经不再接受immediate模式if (strategyMode immediate) { // 记录一条弃用警告并回退到 deferred options?.logger?.warn( The immediate stitching strategy mode has been removed and is no longer supported. Falling back to deferred stitching. Please remove the catalog.stitchingStrategy.mode configuration key., ); }从源码看immediate模式在 v1.41.0 中已被彻底移除配置了该值会打印警告并自动回退到deferred。deferred 模式通过后台 worker 异步完成实体与关系数据的缝合配置项为catalog: stitchingStrategy: # mode 已不再需要显式声明immediate 已失效 pollingInterval: { seconds: 1 } # 默认 1 秒deferred worker 轮询间隔 stitchTimeout: { seconds: 60 } # 默认 60 秒单次缝合超时在 DefaultStitcher.ts 中可以看到缝合器正是通过stitchingStrategyFromConfig读取以上配置。若你此前显式配置了mode: immediate请在升级时删除该键。2. 关系兼容模式不再默认开启变更内容d675d96关系relations兼容模式不再默认启用同时删除了disableRelationsCompatiblity开关需要兼容旧行为时改用新增的enableRelationsCompatibility标志重新开启。这属于默认值反转型破坏性变更如果你的后端此前依赖旧的关系读写行为且从未配置过相关标志升级后行为会变化如需保留旧行为配置为catalog: enableRelationsCompatibility: true3. 移除实验性开关catalog.useUrlReadersSearch变更内容2339363v1.36 引入的实验性配置catalog.useUrlReadersSearch被移除。UrlReaderProcessor现在始终调用UrlReaders的search方法。行为变化在于职责转移旧行为只有当解析出的 Git URL 文件名包含通配符时才调用search方法否则走readUrl新行为每个UrlReaderService实现必须在自己的search方法内部判断传入的是具体 URL 还是包含通配符的搜索模式并使用各自 provider 特有的逻辑处理。内置的UrlReaderService实现已随本版本完成适配相关修改在backstage/backend-defaults0.11.1与backstage/integration1.17.1中。如果你维护自定义的UrlReaderService实现必须同步改写其search方法以正确处理这两类输入否则目录处理将出现回归。仓库内搜索useUrlReadersSearch已无任何命中说明该开关在源码中已彻底移除。4. 孤儿实体处理策略默认改为删除两项相关变更catalog.orphanStrategy默认值切换为delete687bfc8处理引擎在发现孤儿实体其来源 location 已不再被跟踪的实体时默认删除catalog.orphanProviderStrategy默认值切换为delete5de7a9d对于由 Entity Provider 提供、但 provider 已不再汇报的实体同样默认删除。源码佐证在 DefaultCatalogProcessingEngine.ts 中处理引擎读取catalog.orphanStrategy未配置时回退为delete在 CatalogBuilder.ts 中start()阶段会调用evictEntitiesFromOrphanedProviders清理孤儿 provider 实体——只有显式配置catalog.orphanProviderStrategy: keep才会跳过该清理。如需保留旧行为不自动删除请显式配置catalog: orphanStrategy: keep # 或 delete默认 orphanProviderStrategy: keep # 或 delete默认5. 其他值得注意的 catalog 相关修复plugin-catalog在新前端系统中默认开启分页pagination并支持配置6991dab新前端系统的卡片扩展改用新的实体谓词且 User/Group 页面不再显示 about 卡片3ab9b96plugin-catalog-react修复了 alpha 实体谓词中$in操作符误区分大小写的问题a07feb7plugin-catalog-import修复了ResponseError抛出后的错误信息展示问题406b8b8InMemoryCatalogClient现在支持以数组形式过滤实体6fb4143。Scaffolder 任务权限升级为 Resource Permissionsv1.41.0 中 Scaffolder 系列包plugin-scaffolder、plugin-scaffolder-backend、plugin-scaffolder-common、plugin-scaffolder-node、plugin-scaffolder-react共同完成了一次/alpha级别的权限模型重构提交c1ce316对自定义权限策略的使用者有直接影响。变更一scaffolder.task.read与scaffolder.task.cancel变为 Resource Permissions此前这两个权限是普通权限现在它们都关联到新的资源类型scaffolder-task。在 permissions.ts 中可以看到export const RESOURCE_TYPE_SCAFFOLDER_TASK scaffolder-task; export const taskReadPermission createPermission({ name: scaffolder.task.read, attributes: { action: read }, resourceType: RESOURCE_TYPE_SCAFFOLDER_TASK, }); export const taskCancelPermission createPermission({ name: scaffolder.task.cancel, attributes: {}, resourceType: RESOURCE_TYPE_SCAFFOLDER_TASK, });scaffolder.task.create仍是普通权限无资源类型。这意味着你的权限策略PermissionPolicy在处理scaffolder.task.read/scaffolder.task.cancel时可以通过resourceRef拿到具体的SerializedTask从而按任务维度做条件授权。变更二新增条件规则isTaskOwner为配合资源化改造新增了条件规则isTaskOwner用于限制谁能读取 / 取消某任务。规则实现在 rules.tsexport const isTaskOwner createTaskPermissionRule({ name: IS_TASK_OWNER, description: Allows tasks created by certain users to be accessible, resourceType: RESOURCE_TYPE_SCAFFOLDER_TASK, paramsSchema: z.object({ createdBy: z .array(z.string()) .describe(List of creator entity refs; only tasks created by these users will be viewable), }), apply: (resource, { createdBy }) { if (!resource.createdBy) { return false; } return createdBy.includes(resource.createdBy); }, toQuery: ({ createdBy }) { return { key: created_by, values: createdBy, }; }, });该规则参数createdBy为实体引用entity ref数组apply阶段判断任务的createdBy是否命中列表任务无创建者时直接拒绝同时提供toQuery将条件转换为数据库查询条件created_by IN (...)使得列表查询阶段即可完成过滤无需逐条加载任务。配合测试用例 rules.test.ts 可以看到该规则的apply与toQuery行为均有覆盖验证。变更三重试任务所需权限变化重试retry一个任务从原先要求scaffolder.task.readscaffolder.task.cancel改为要求scaffolder.task.readscaffolder.task.create。如果你用权限策略而非 Allow-All管控 Scaffolder需要在策略中同步更新重试操作所需权限。权限策略适配示例假设你希望只有任务创建者本人可以查看和取消自己的任务可以基于isTaskOwner编写条件规则import { createConditionalDecision, PermissionCriteria, } from backstage/plugin-permission-common; import { isTaskOwner } from backstage/plugin-scaffolder-backend; // 在 PermissionPolicy 的 handle 中 if (isPermission(request.permission, taskReadPermission) || isPermission(request.permission, taskCancelPermission)) { return createConditionalDecision(request.permission, { anyOf: [{ allOf: [{ rule: isTaskOwner, params: { createdBy: [userEntityRef] } }] }], }); }同时注意重试操作现在需要taskCreatePermission请确保策略中对该权限给出允许或条件判断。其他 Scaffolder 变更Scaffolder 审计日志现在包含taskId和createdBy424610a模板表单在步骤间切换时自动滚动回页面顶部94c11a5MultiEntityPicker会基于渲染后的选项值过滤选项289e4a1publish:github:pull-requestaction 新增filesToDelete输入可在 PR 中删除文件f36bcf9- action: publish:github:pull-request id: clean-up-pr input: description: This is the description filesToDelete: - outdated/changelog.md - sample-file.txt owner: owner repo: repo title: Title Goes HereUI 组件库更名canon → Backstage UIv1.41.0 完成了组件库的品牌与包名迁移backstage/canon弃用正式更名为backstage/uie92bb9b所有 CSS 变量前缀从--canon改为--bui组件类名从.canon-*改为.bui-*8fd6fcb所有 CSS 文件合并为单一的styles.css140f652。如果你的项目直接使用 Canon 组件或覆盖了相关 CSS 变量/类名升级时需要同步替换前缀。涉及的新增与调整还包括新增Card、SearchField、Header、RadioGroupRadio、Skeleton组件以及Button/ButtonIcon/ButtonLink新增 tertiary 变体等。Canon 组件向 React Aria 迁移BreakingCanon/UI 的多个基础组件底层切换到 React Aria带来以下 API 破坏性变化组件变化Linkto属性改为href以统一内部与外部路由1d64db6Select大部分 props 与事件按 React Aria 底层 API 调整83fd7f4Tabs基于 React Aria 重构并直接兼容 react-router-domcae63dfButton系列新增ButtonLink取代 render-prop 模式IconButton更名为ButtonIcon移除所有按钮组件上的 render prop4c6d891Tooltip组件结构与 props 按 React Aria 底层结构调整2e30459通知、认证与其他基础设施更新通知系统plugin-notifications-backend支持通过配置定义默认通知设置4401dfb并为已有user_settings的场景修复了addTopic迁移问题9a5a73fnotifications-backend-module-email为 SES 邮件选项新增可选配置sourceArn、fromArn、configurationSetNamef92c9fc适合通过 AWS SES 发送通知邮件的场景。认证与会话core-app-api1.18.0会话刷新失败时如果当前不是即时弹窗模式将重新创建会话5ddc0fe改善登录会话过期后的恢复体验core-components为 OAuth 请求对话框新增可选message字段便于向用户展示友好提示f6ffea6登录与登出新增signIn/signOut分析事件aa3b054。后端与基础设施backend-defaults0.11.1修复了 GitLab readURL 请求的访问令牌处理以及 GitLab 用户令牌与集成令牌被合并的问题e0189b8、d1e4a6dsearch-backend2.0.4不再在 API 响应中返回后端 SQL 查询字符串错误只记录日志、对用户返回空响应69fb975避免信息泄露auth-backend将userInfo数据库从tokenIssuer中拆出UserInfo不再存储exp改用数据库中的created_at/updated_ate88cb70config/config-loader放宽了合法配置键的要求ff23618plugin-app的AppRoutes扩展移除尾部斜杠保证嵌套路由行为正确09f5e36yarn-plugin-backstage修复了backstage:^协议安装新依赖失败的问题d6084b8。升级建议与检查清单结合仓库内的 versioning-policy 与官方升级工具指引建议按以下顺序执行升级检查配置全文搜索app-config.yaml中catalog.stitchingStrategy删除mode: immediate、catalog.orphanStrategy、catalog.orphanProviderStrategy、catalog.useUrlReadersSearch移除、disableRelationsCompatiblity改为enableRelationsCompatibility等键检查自定义 UrlReaderService确认search方法能同时处理具体 URL 与通配符搜索模式参考backstage/backend-defaults内置实现检查 Scaffolder 权限策略将scaffolder.task.read/scaffolder.task.cancel按 Resource Permission 处理并确认重试任务的新权限组合readcreate检查自定义样式若使用 Canon将--canon前缀与.canon-类名替换为--bui/.bui-并迁移受 React Aria 影响的组件 props回归测试重点模块Catalog 的缝补与孤儿清理、Scaffolder 任务读取/取消/重试、通知默认设置与邮件处理器、GitLab 集成。官方发布的changesets均可在 docs/releases 目录下对照查阅升级后建议运行backstage-cli repo fix或对应 lint/test 流程确认依赖与代码兼容性。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考