Backstage v1.55.0-next.0 版本解析Scaffolder 任务恢复机制与模板 Dry Run 权限控制的全面落地【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 仓库中的 v1.55.0-next.0 发布说明docs/releases/v1.55.0-next.0-changelog.md撰写聚焦本次预发布版本中最具分量的两项 Scaffolder 能力升级——任务自动恢复Task Recovery与模板 Dry Run 权限控制templateDryRunPermission同时系统梳理模板引擎行为修正、Kubernetes 观察者接口、搜索索引优化、Catalog 引用修复等一系列 Patch 级变更。读完本文你将掌握新版本配置项的完整语义、工作区 Provider 的选型与落地方式以及升级时需要特别留意的兼容性要点。版本概览与升级路径v1.55.0-next.0 是 v1.55.0 的第一个next预发布版本属于 Backstage 的常规 minor 发布周期。本次变更集中发生在Scaffolder 相关包上包新版本变更级别核心内容backstage/plugin-scaffolder-backend4.1.0-next.0Minor任务恢复机制、Dry Run 权限接入backstage/plugin-scaffolder1.39.0-next.0Minor新前端系统注册 Template Outputs 组件backstage/plugin-scaffolder-react2.1.0-next.0Minor新前端系统注册 Template Outputs 组件backstage/plugin-scaffolder-common2.3.0-next.0Minor新增templateDryRunPermissionbackstage/plugin-scaffolder-backend-module-workspace-database0.1.0-next.0Minor新模块数据库工作区 Providerbackstage/plugin-scaffolder-node0.13.7-next.0Patch任务恢复基础能力其余多数包backstage/ui、core-components、plugin-catalog-react、plugin-techdocs-react等均为依赖升级与零散修复仓库中的example-app、example-backend、techdocs-cli-embedded-app等示例应用同步跟随升级。升级方式官方提供的 Upgrade Helper 工具可依据当前版本自动生成依赖升级清单与迁移建议从任意历史版本一键计算到1.55.0-next.0的升级路径。发布说明原文中还包含对create-app模板版本的同步 bumpbackstage/create-app0.9.2-next.0说明npx backstage/create-app脚手架生成的工程也会直接进入该版本线。核心新特性一Scaffolder 任务自动恢复Task Recovery这是本次发布最重磅的变更对应 PRe95b649横跨 backstage/plugin-scaffolder-backend、backstage/plugin-scaffolder-backend-module-workspace-database、backstage/plugin-scaffolder-node 以及 GCP 工作区模块。解决了什么问题默认情况下当 Scaffolder 任务进程崩溃或任务超时后重试会从第一个步骤重新执行且任务一旦被 Worker 认领claim其中的 secrets 就会被清除——这意味着任何一步非幂等的操作如已经创建的外部资源都可能在重跑时重复执行或报错。任务恢复机制改变了两件事崩溃/超时任务自动恢复任务不再从头重跑而是从最后完成的步骤继续执行secrets 与步骤产物持久化secrets 在任务进入终态终态即成功/失败/取消等不可再恢复的状态之前持续保留已完成的步骤输出step outputs也被持久化保证恢复后能继续读取此前步骤的结果。新配置段scaffolder.taskRecovery本版本将此前分散的多个实验性配置项整合为一个正式配置段。在 plugins/scaffolder-backend/config.d.ts 中其 Schema 定义如下scaffolder: taskRecovery: # 是否启用任务自动恢复。启用后 # - secrets 在任务完成前持续保留 # - 每个步骤结束后保存步骤状态 # - 崩溃的任务从最后完成的步骤恢复 enabled: true # 任务被视为“过期”并进入恢复流程的超时时间。 # 默认值30 秒 staleTimeout: 30s # 用于序列化/恢复工作区workspace的 Provider 名称。 # 设置该值即启用工作区序列化未设置则关闭。 # 常见值database workspaceProvider: database各字段说明配置项类型默认值语义scaffolder.taskRecovery.enabledbooleanfalse不启用总开关。关闭时行为与旧版完全一致scaffolder.taskRecovery.staleTimeoutHumanDuration / string30s判定任务过期stale的阈值超过该时长无心跳即进入恢复流程scaffolder.taskRecovery.workspaceProviderstring未设置关闭工作区序列化工作区 Provider 名称如database或 GCP 模块对应的 Providerscaffolder.taskRecovery.gcsBucket.namestring无GCP Provider 使用的 GCS 存储桶名称scaffolder.taskRecovery.database.dangerouslyEnableInProductionbooleanfalse生产环境强制启用数据库工作区 Provider 的“危险开关”行为边界isTaskRecoveryEnabled的实现见 taskRecoveryHelper.ts先读取scaffolder.taskRecovery.enabled若未配置再回退到旧的scaffolder.EXPERIMENTAL_recoverTasks最后兜底false。这与发布说明中“旧实验性标志仍作为 fallback 生效”的描述完全一致。工作区序列化与 Provider 选型任务恢复依赖工作区workspace序列化——即把任务执行过程中的临时目录内容持久化恢复时再重新物化rehydrate。从源码结构看该能力通过WorkspaceProvider扩展点注入核心封装在 WorkspaceService.tsserializeWorkspace(path)步骤完成后序列化工作区rehydrateWorkspace(taskId, targetPath)恢复任务时重新物化工作区cleanWorkspace()任务成功后清理序列化产物。发布说明特别强调启用工作区序列化现在必须单独安装并注册一个工作区 Provider 模块即使走旧版EXPERIMENTAL_workspaceSerialization配置也是如此。两个官方选项① 数据库 Provider开发用—— 新包backstage/plugin-scaffolder-backend-module-workspace-database0.1.0-next.0// packages/backend/src/index.ts import { workspaceDatabaseModule } from backstage/plugin-scaffolder-backend-module-workspace-database; backend.add(workspaceDatabaseModule);存在50 MB的工作区大小上限官方明确不推荐用于生产首次启动时会自动迁移旧任务存储中的数据库工作区快照在NODE_ENV production下默认拒绝启用除非显式设置scaffolder.taskRecovery.database.dangerouslyEnableInProduction: true对应逻辑见 module.ts。② 外部存储 Provider生产用—— 如backstage/plugin-scaffolder-backend-module-gcpscaffolder: taskRecovery: enabled: true workspaceProvider: gcpBucket gcsBucket: name: my-scaffolder-workspacesGCP Provider 的配置路径为scaffolder.taskRecovery.gcsBucket.name旧的EXPERIMENTAL_workspaceSerializationGcpBucketName仍作为 fallback 支持当缺少桶配置时会抛出提示错误“Missing GCS bucket configuration. Set scaffolder.taskRecovery.gcsBucket.name in app-config.yaml”见 GcpBucketWorkspaceProvider.ts。此外工作区上传失败现在会被传播——任务不会在缺少对应工作区的情况下记录“步骤已完成”。③ 容错机制如果配置了某个 Provider 但未安装/注册对应模块Scaffolder 会直接拒绝运行。resolveWorkspaceProviderWorkspaceService.ts在找不到已注册 Provider 时会抛出明确错误并针对database名称附加安装指引——这从机制上杜绝了“配置了却静默失效”的隐患。恢复语义与幂等性要求启用恢复后有以下必须知悉的语义对所有任务生效恢复不是逐任务开关而是全局行为。因此任务中使用的 action 应当幂等或使用 checkpoint避免从断点续跑时重复产生副作用事件流保持终态启用崩溃恢复不会让已完成任务的 event stream 保持打开——正常完成对事件流客户端而言仍是终态恢复策略与事件裁剪从源码看任务可通过EXPERIMENTAL_recovery.EXPERIMENTAL_strategy: startOver声明“从头重跑”策略。trimEventsTillLastRecoverytaskRecoveryHelper.ts会在收到recovered类型事件后按策略裁剪事件列表避免恢复历史污染 UI 日志周期回收StorageTaskBroker.recoverTasks()StorageTaskBroker.ts按staleTimeout优先scaffolder.taskRecovery.staleTimeout回退EXPERIMENTAL_recoverTasksTimeout默认 30 秒调用存储层恢复接口发现被恢复任务后立即触发一次 dispatch 信号唤醒 Worker。旧实验性配置的兼容矩阵旧配置已标记 deprecated新配置scaffolder.EXPERIMENTAL_recoverTasksscaffolder.taskRecovery.enabledscaffolder.EXPERIMENTAL_workspaceSerializationscaffolder.taskRecovery.workspaceProvider设置即启用scaffolder.EXPERIMENTAL_workspaceSerializationProviderscaffolder.taskRecovery.workspaceProviderscaffolder.EXPERIMENTAL_recoverTasksTimeoutscaffolder.taskRecovery.staleTimeout需要留意的是旧配置中EXPERIMENTAL_workspaceSerializationProvider的默认值为database——即旧版只要开了序列化开关就隐式使用数据库 Provider而新版要求显式设置workspaceProvider且必须安装对应模块行为不再隐式。核心新特性二模板 Dry Run 权限控制templateDryRunPermission对应 PR1a705ca影响backstage/plugin-scaffolder-common与backstage/plugin-scaffolder-backend。权限定义新权限定义于 plugins/scaffolder-common/src/permissions.ts/** * This permission is used to authorize dry runs of inline scaffolder * templates. * * alpha */ export const templateDryRunPermission createPermission({ name: scaffolder.template.dry-run, attributes: {}, });并已加入scaffolderPermissions汇总列表见同一文件 scaffolderPermissions。在此之前执行 Dry Run 只需要scaffolder.task.create权限。在 Backend 的接入点在 Scaffolder 后端路由中POST /v2/dry-run端点现在同时校验两个权限router.tsawait checkPermission({ credentials, permissions: [taskCreatePermission, templateDryRunPermission], permissionService: permissions, });即发起一次内联模板 Dry Run必须同时持有scaffolder.task.create与scaffolder.template.dry-run权限。对现有策略的影响重点这是本次变更最容易造成“升级后功能悄然失效”的点凡是“拒绝未知权限”deny unknown permissions的权限策略必须显式允许scaffolder.template.dry-run否则 Dry Run 功能将被拒绝。典型策略示例在自定义权限策略中if (request.permission.name scaffolder.template.dry-run) { return { result: AuthorizeResult.ALLOW }; } // 其他权限按原有逻辑处理未知权限默认 DENY return { result: AuthorizeResult.DENY };同时发布说明也明确该权限作用于内联inlineSoftware Template 的 Dry Run 以及对应的后端 action——即通过POST /v2/dry-run提交的、尚未入库的模板片段。新前端系统的 Template Outputs 组件注册对应 PR5ff93bf影响backstage/plugin-scaffolder1.39.0-next.0与backstage/plugin-scaffolder-react2.1.0-next.0。在 Backstage 的新前端系统New Frontend System中本次新增了Template Outputs 组件Template Outputs Component的注册能力。此前模板执行结果如生成的仓库地址、文档链接等 outputs的渲染组件仅能通过旧前端系统挂载现在插件作者可以在新前端系统中显式注册 Outputs 渲染组件与backstage/frontend-plugin-api的扩展点机制对齐便于在新应用架构下自定义模板任务输出区域的展示。对于正在从旧前端系统迁移到新系统的 Backstage 应用这一变更意味着 Scaffolder 插件的“任务输出”能力在新架构下已具备等价的可扩展入口无需再依赖兼容层桥接。模板引擎行为修正Patch 级本次发布对 Software Template 的模板渲染基于 Nunjucks做了三处行为修正1. 无else的内联条件表达式PR2bf1392- id: example action: debug:log input: # 旧行为条件为 false 时可能输出 undefined 或原始 undefined # 新行为无 else 分支时渲染为空字符串与 Nunjucks 语义一致 message: {% if values.foo %}foo{% endif %}当values.foo为假值时上述表达式现在渲染为空字符串对齐 Nunjucks 原生行为。2.each拒绝原始值PRbeaa3db- id: iterate action: debug:log each: {{ values.primitive }} # 若解析结果为字符串/数字等原始值 input: message: {{ each }}Scaffolder 步骤中的each现在必须解析为数组或对象若解析结果是字符串、数字等原始值该步骤会被直接拒绝reject避免产生未定义行为。3. 恢复内置方法调用PRc1a30ef软件模板中恢复了对字符串、数字、数组、Map、Set等类型的原生内建方法的支持。例如模板参数中可以直接使用数组的map、filter、字符串的toUpperCase等内建方法进行表达式运算此前某次变更导致的部分内建方法不可用问题已修复。周边生态修复速览Catalog实体引用规范化catalog-importPR5d6a62b导入向导中选择的 owner 此前会被写入生成的catalog-info.yaml且写入的是显示名而非实体引用如写入My Team而不是my-team。本次修复后选择分组仍按显示名展示但落盘时生成合法的spec.owner实体引用例如选择My Team会得到my-teamEntityOwnerPicker 崩溃修复PRa7b14b5当owners查询参数包含由backstage/plugin-org的OwnershipCard链接生成的“人类可读实体引用”时EntityOwnerPicker曾因实体引用缺失 kind 而崩溃。根因是查询参数原样存入初始状态、仅由 effect 在首轮渲染后才转换。现在初始化状态时即通过EntityOwnerFilter规范化同时解决了崩溃与选项框首帧未选中的问题org 所有权卡片PRfe0ec65OwnershipCard生成的 catalog 链接改为使用稳定的实体引用过滤而非按显示标题过滤与上述修复配套。Kubernetes新增KubernetesWatcher接口PRd9a57debackstage/plugin-kubernetes-backend、plugin-kubernetes-common、plugin-kubernetes-node三个包新增KubernetesWatcher接口通过 async iterator 流式推送 Kubernetes 资源变更。设计要点与KubernetesFetcher分离——因为 watch 是长连接的流式连接仅适用于服务端认证server-side authProvider支持全部事件类型ADDED、MODIFIED、DELETED、BOOKMARK、ERROR错误以**数据yield as data**方式产出而非抛出异常便于消费方统一处理。同版本还修复了废弃 services 端点的实体解析PRb11c9b4。搜索索引与查询边界修复空文档类型列表不再全量查询PRb11c9b4backstage/plugin-search-backend修复了“无文档类型被允许时仍可能收到未过滤查询”的问题plugin-search-backend-module-elasticsearch修复了空文档类型列表导致查询全部索引而非返回空结果的缺陷游标分页索引优化PR979c255plugin-search-backend-module-catalog与plugin-search-backend-module-techdocs的 collator 改用**游标分页cursor pagination**抓取 TechDocs并避免计算未使用的总数显著提升大型目录的索引性能。GitLab Scaffolder ActionPR3c7c082gitlab:repo:push在“工作区没有文件变更”时例如对已是最新分支的模板重复执行会调用 GitLab 提交 API 并收到400 Bad request - Provide at least one action。现在该 action 会检测空 action 列表并跳过提交调用在allowEmpty不为true时记录警告覆盖未设置与显式false两种情形commitHash输出在 no-op 场景下省略并已声明为可选。如需保留旧行为向 GitLab 转发空提交显式传allowEmpty: true。TechDocs CLIPRde92fae修复了techdocs-cli serve在 Python 环境TechDocs 容器镜像或本地包含click8.3.x 时静默停止检测文档变更、不再刷新浏览器的问题。CLI 现在在 serve 模式下显式启用 MkDocs live reload。UI / 主题backstage/ui0.17.2-next.0PRf914343修复 BUI 样式覆盖文档与原生控件的行高的问题同时保留 BUI 组件自身的排版行高plugin-app同步修复了应用未定义全局行高时 toast 文本布局错乱的问题。CLI 工具链build-workspace显著提升大批量打包 Backstage 包时的性能PRb2b7568backstage/cli-module-build修复发布的入口点配置使其可在 Jest/Node 解析中被可靠 importPR4cba335影响cli-module-new与plugin-app-module-user-settings。认证backstage/plugin-auth-backend修复了 token 撤销token revocation中不一致的 URL 模式匹配PR08c5d9bbackstage/plugin-catalog-backend-module-gitlab修复GitlabDiscoveryEntityProvider仅处理指向已配置分支的 push 事件PR348bea1。升级注意事项清单结合以上变更升级到v1.55.0-next.0时建议重点检查Dry Run 权限最易踩坑若你的权限策略采用“拒绝未知权限”模式务必为scaffolder.template.dry-run增加显式允许规则否则内联模板 Dry Run 将被拒绝任务恢复为默认关闭scaffolder.taskRecovery.enabled默认false未配置时行为与旧版完全一致可放心升级启用时需评估任务 action 的幂等性Provider 必须显式安装即使沿用EXPERIMENTAL_workspaceSerialization旧配置也必须安装并注册workspace-database或gcp等 Provider 模块否则 Scaffolder 会拒绝启动模板行为对齐 Nunjucks无else的条件表达式、each原始值校验属于行为收紧若模板依赖旧的宽松语义需先修正模板定义gitlab:repo:push的 no-op 语义空变更提交场景不再调用 GitLab API依赖commitHash输出的流水线需处理其可能缺失的情况Kubernetes watch 认证方式KubernetesWatcher仅适用于服务端认证 Provider基于客户端证书的集群无法使用 watch 流。发布说明中其余大量 “Updated dependencies” 类条目涉及backstage/ui、core-components、plugin-catalog-react、plugin-techdocs-react等为常规依赖联动对上层应用无直接行为影响。相关实现细节可进一步查阅 plugin-scaffolder-backend 的scaffolder/tasks目录、permissions.ts 与 config.d.ts 获取一手证据。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考