Backstage Scaffolder Action RollbackBEP-0006解析为任务失败提供回滚机制【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于仓库内beps/0006-scaffolder-action-rollback/README.mdBackstage Enhancement Proposal 0006状态 provisional撰写系统讲解 Backstage Scaffolder软件模板引擎中Action 回滚这一能力的设计动机、提案方案并结合当前仓库源码梳理任务恢复Task Recovery机制的实现现状与落地路径。读完本文你将理解为什么需要为 Scaffolder Action 增加回滚能力、BEP 提案设计的 API 形态是什么、当前仓库中任务恢复/回滚相关的底层实现细节以及该提案与现有代码之间的差距。BEP 背景为什么需要 Action 回滚Backstage 的 Scaffolder 通过模板 一系列步骤steps的方式编排软件交付流水线每个步骤调用一个模板 Action例如创建仓库、推送分支、发布 GitHub 资源等。当模板执行到中途某个步骤失败时前面步骤已经产生的资源仓库、分支、PR、文件等往往已经部分落盘到外部系统形成半成品。在没有回滚能力之前处理这类问题的唯一手段是人工手动清理这些部分创建的资源——这既耗时又容易遗漏。BEP-0006 的提出者bnechyporenkobol.com 与 benjaminlspotify.com归属backstage/scaffolder-maintainers维护正是希望用程序化的方式解决这一痛点Introducing the rollback to scaffolder actions provides the mean to come back to the initial state.即为 Scaffolder Action 引入回滚能力让任务失败后能够回到初始状态。Goals目标扩展 Action 的 API使其能够对失败的任务执行回滚rollback回滚必须是可选的optional——不是所有 Action 都被强制要求实现回滚逻辑。Non-Goals非目标不会为所有内置 Action 都覆盖回滚功能。这意味着回滚是一个渐进式能力先由部分 Action 实现再逐步扩展。Proposal回滚在什么时机执行BEP 明确指出回滚会在以下两种情形下被触发用户手动决定执行回滚操作——即用户在 UI 或 API 层面主动对失败任务发起回滚任务被恢复recovered且 TaskRecoverStrategy 被设置为rollback——即系统在自动恢复失败任务时按照任务规格中声明的恢复策略以回滚作为恢复手段。这里引入了一个关键概念TaskRecoverStrategy任务恢复策略。需要特别说明的是当前仓库中该策略的实际取值与 BEP 提案存在差异详见下文与现状的差距一节。Design DetailsAction API 的扩展形态BEP 给出的核心设计是在现有模板 Action 的创建函数createTemplateAction中新增一个可选的rollback异步函数与既有handler平级。提案中的示例代码如下const createPublishGitHubAction createTemplateAction({ id: publish:github, async handler() {}, async rollback() {}, });设计要点handler负责 Action 的正常执行逻辑创建资源rollback负责在任务失败时撤销handler已产生的副作用删除资源、关闭 PR、恢复分支等rollback是可选属性——对于无法实现回滚或回滚无意义的 Action可以直接省略这正是Rollback will be optional目标的落地形态。从语义上看rollback的设计与handler保持对称两者都接收相同的 Action 上下文输入参数、工作目录、日志器等因此回滚逻辑可以复用与执行逻辑相同的上下文信息。仓库现状任务恢复机制的源码级剖析虽然 BEP-0006 目前仍是 provisional暂定状态、rollback函数尚未合入 Action API但与之配套的任务恢复Task Recovery机制在当前仓库中已经相当成熟。理解这套机制是评估 BEP 落地可行性的关键。1. TaskRecoverStrategy 的类型定义任务恢复策略定义在 plugins/scaffolder-common/src/TaskSpec.ts/** * none - not recover, let the task be marked as failed * startOver - do recover, start the execution of the task from the first step. */ export type TaskRecoverStrategy none | startOver; export interface TaskRecovery { EXPERIMENTAL_strategy?: TaskRecoverStrategy; }none默认值不恢复任务直接从processing状态标记为failedstartOver恢复任务从头开始重新执行所有步骤。该策略通过任务规格上的EXPERIMENTAL_recovery字段见 TaskSpec.ts声明在 Template 中/** * How to recover the task after system restart or system crash. */ EXPERIMENTAL_recovery?: TaskRecovery;注意当前仓库中TaskRecoverStrategy只有none | startOver两种取值并没有 BEP 提案中提到的rollback。这正是该 BEP 尚未落地为代码的实证——提案中的回滚式恢复是startOver之外的第三种策略设想。2. 任务恢复的开关与事件裁剪plugins/scaffolder-backend/src/scaffolder/tasks/taskRecoveryHelper.ts 提供了两个核心函数isTaskRecoveryEnabled(config)判断自动恢复是否开启。读取scaffolder.taskRecovery.enabled并向后兼容旧配置scaffolder.EXPERIMENTAL_recoverTasks两者都未配置时默认falsetrimEventsTillLastRecovery(events)当任务发生过recovered事件且恢复策略为startOver时将事件列表裁剪到最近一次恢复之后避免日志/事件展示被历史恢复过程污染。3. 恢复循环与 Worker 执行在 plugins/scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts 中任务恢复由 Worker 周期驱动async recoverTasks() { await this.options.taskBroker.recoverTasks?.(); } private async runTaskRecoveryLoop() { // ... await this.recoverTasks(); }Worker 在启动后通过runTaskRecoveryLoop()定期调用taskBroker.recoverTasks()而DatabaseTaskStore与StorageTaskBroker分别实现了对应的recoverTasks方法见 DatabaseTaskStore.ts 与 StorageTaskBroker.ts。在 DatabaseTaskStore.ts 中可以推断是否将一个任务标记为可恢复取决于recoverTasksEnabled配置与任务规格是否满足可恢复条件isRecoverableTask(spec)。4. 恢复相关的配置项配置声明位于 plugins/scaffolder-backend/config.d.tsscaffolder.taskRecovery.enabled是否启用自动任务恢复scaffolder.taskRecovery.staleTimeout任务被视为过期stale并进入可恢复队列的等待时长旧配置scaffolder.EXPERIMENTAL_recoverTasks、EXPERIMENTAL_recoverTasksTimeout等已被标记为 deprecated统一迁移到taskRecovery命名空间下。5. 前端OngoingTask 中的恢复交互前端侧任务执行页面 plugins/scaffolder/src/components/OngoingTask/OngoingTask.tsx 通过useTaskEventStream订阅任务事件流并提供取消/恢复任务的交互入口依赖taskCancelPermission、taskCreatePermission、taskReadPermission等权限控制。这为 BEP 中用户手动决定执行回滚的交互场景提供了现成的承载页面——一旦rollback合入 Action API这类页面即可扩展出回滚按钮。与现状的差距BEP 落地还差什么对比 BEP 提案与仓库现状可以明确以下差距维度BEP-0006 提案当前仓库现状Action API 形态createTemplateAction新增可选rollback()plugins/scaffolder-node/src/actions/types.ts 中TemplateAction仅有handler无rollback字段恢复策略取值包含rollbackplugins/scaffolder-common/src/TaskSpec.ts 中仅有none \| startOver内置 Action 覆盖逐步覆盖尚无任何内置 Action 提供回滚实现也就是说BEP-0006 是一份尚未实施的设计蓝图任务恢复的基础设施恢复开关、过期检测、Worker 循环、事件裁剪已经就绪但Action 回滚这一上层能力仍待实现。落地路径大致为在 plugins/scaffolder-node/src/actions/types.ts 的TemplateAction类型中增加可选的rollback字段在TaskRecoverStrategy中引入rollback取值plugins/scaffolder-common/src/TaskSpec.ts并让任务执行器在恢复时根据策略调用各步骤已执行 Action 的rollback为部分内置 Action如publish:github、publish:gitlab等发布类 Action编写回滚实现在前端任务页OngoingTask.tsx增加手动回滚入口。Alternatives备选方案BEP 文档的 Alternatives 章节当前为占位状态仅保留了说明性注释应当记录还考虑过哪些其他方案以及为什么排除它们。从既有实现可以推断社区目前的恢复策略是startOver从头重跑而非撤销式回滚——两者本质差异在于startOver需要模板本身具备幂等性以承受重复执行而回滚则试图通过撤销副作用回归初始状态对模板幂等性的要求更低但对 Action 实现者提出了编写逆向逻辑的要求。这也是 BEP 选择回滚可选、逐步覆盖作为折中方案的原因。总结BEP-0006Scaffolder Action Rollback为 Backstage 模板引擎规划了一条从人工清理半成品资源走向程序化回滚的演进路径通过在createTemplateAction中新增可选的rollback函数、并将rollback纳入任务恢复策略让任务失败后既可以由用户手动触发回滚也可以在自动恢复时按策略执行回滚。当前仓库已具备完整的任务恢复基础设施恢复开关配置、过期检测、Worker 恢复循环、恢复事件裁剪但 Action 级rollbackAPI 尚未合入——对于希望参与 Backstage 插件生态的开发者而言这正是值得关注的扩展点与潜在贡献方向。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage Scaffolder Action Rollback（BEP-0006）解析：为任务失败提供回滚机制
Backstage Scaffolder Action RollbackBEP-0006解析为任务失败提供回滚机制【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于仓库内beps/0006-scaffolder-action-rollback/README.mdBackstage Enhancement Proposal 0006状态 provisional撰写系统讲解 Backstage Scaffolder软件模板引擎中Action 回滚这一能力的设计动机、提案方案并结合当前仓库源码梳理任务恢复Task Recovery机制的实现现状与落地路径。读完本文你将理解为什么需要为 Scaffolder Action 增加回滚能力、BEP 提案设计的 API 形态是什么、当前仓库中任务恢复/回滚相关的底层实现细节以及该提案与现有代码之间的差距。BEP 背景为什么需要 Action 回滚Backstage 的 Scaffolder 通过模板 一系列步骤steps的方式编排软件交付流水线每个步骤调用一个模板 Action例如创建仓库、推送分支、发布 GitHub 资源等。当模板执行到中途某个步骤失败时前面步骤已经产生的资源仓库、分支、PR、文件等往往已经部分落盘到外部系统形成半成品。在没有回滚能力之前处理这类问题的唯一手段是人工手动清理这些部分创建的资源——这既耗时又容易遗漏。BEP-0006 的提出者bnechyporenkobol.com 与 benjaminlspotify.com归属backstage/scaffolder-maintainers维护正是希望用程序化的方式解决这一痛点Introducing the rollback to scaffolder actions provides the mean to come back to the initial state.即为 Scaffolder Action 引入回滚能力让任务失败后能够回到初始状态。Goals目标扩展 Action 的 API使其能够对失败的任务执行回滚rollback回滚必须是可选的optional——不是所有 Action 都被强制要求实现回滚逻辑。Non-Goals非目标不会为所有内置 Action 都覆盖回滚功能。这意味着回滚是一个渐进式能力先由部分 Action 实现再逐步扩展。Proposal回滚在什么时机执行BEP 明确指出回滚会在以下两种情形下被触发用户手动决定执行回滚操作——即用户在 UI 或 API 层面主动对失败任务发起回滚任务被恢复recovered且 TaskRecoverStrategy 被设置为rollback——即系统在自动恢复失败任务时按照任务规格中声明的恢复策略以回滚作为恢复手段。这里引入了一个关键概念TaskRecoverStrategy任务恢复策略。需要特别说明的是当前仓库中该策略的实际取值与 BEP 提案存在差异详见下文与现状的差距一节。Design DetailsAction API 的扩展形态BEP 给出的核心设计是在现有模板 Action 的创建函数createTemplateAction中新增一个可选的rollback异步函数与既有handler平级。提案中的示例代码如下const createPublishGitHubAction createTemplateAction({ id: publish:github, async handler() {}, async rollback() {}, });设计要点handler负责 Action 的正常执行逻辑创建资源rollback负责在任务失败时撤销handler已产生的副作用删除资源、关闭 PR、恢复分支等rollback是可选属性——对于无法实现回滚或回滚无意义的 Action可以直接省略这正是Rollback will be optional目标的落地形态。从语义上看rollback的设计与handler保持对称两者都接收相同的 Action 上下文输入参数、工作目录、日志器等因此回滚逻辑可以复用与执行逻辑相同的上下文信息。仓库现状任务恢复机制的源码级剖析虽然 BEP-0006 目前仍是 provisional暂定状态、rollback函数尚未合入 Action API但与之配套的任务恢复Task Recovery机制在当前仓库中已经相当成熟。理解这套机制是评估 BEP 落地可行性的关键。1. TaskRecoverStrategy 的类型定义任务恢复策略定义在 plugins/scaffolder-common/src/TaskSpec.ts/** * none - not recover, let the task be marked as failed * startOver - do recover, start the execution of the task from the first step. */ export type TaskRecoverStrategy none | startOver; export interface TaskRecovery { EXPERIMENTAL_strategy?: TaskRecoverStrategy; }none默认值不恢复任务直接从processing状态标记为failedstartOver恢复任务从头开始重新执行所有步骤。该策略通过任务规格上的EXPERIMENTAL_recovery字段见 TaskSpec.ts声明在 Template 中/** * How to recover the task after system restart or system crash. */ EXPERIMENTAL_recovery?: TaskRecovery;注意当前仓库中TaskRecoverStrategy只有none | startOver两种取值并没有 BEP 提案中提到的rollback。这正是该 BEP 尚未落地为代码的实证——提案中的回滚式恢复是startOver之外的第三种策略设想。2. 任务恢复的开关与事件裁剪plugins/scaffolder-backend/src/scaffolder/tasks/taskRecoveryHelper.ts 提供了两个核心函数isTaskRecoveryEnabled(config)判断自动恢复是否开启。读取scaffolder.taskRecovery.enabled并向后兼容旧配置scaffolder.EXPERIMENTAL_recoverTasks两者都未配置时默认falsetrimEventsTillLastRecovery(events)当任务发生过recovered事件且恢复策略为startOver时将事件列表裁剪到最近一次恢复之后避免日志/事件展示被历史恢复过程污染。3. 恢复循环与 Worker 执行在 plugins/scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts 中任务恢复由 Worker 周期驱动async recoverTasks() { await this.options.taskBroker.recoverTasks?.(); } private async runTaskRecoveryLoop() { // ... await this.recoverTasks(); }Worker 在启动后通过runTaskRecoveryLoop()定期调用taskBroker.recoverTasks()而DatabaseTaskStore与StorageTaskBroker分别实现了对应的recoverTasks方法见 DatabaseTaskStore.ts 与 StorageTaskBroker.ts。在 DatabaseTaskStore.ts 中可以推断是否将一个任务标记为可恢复取决于recoverTasksEnabled配置与任务规格是否满足可恢复条件isRecoverableTask(spec)。4. 恢复相关的配置项配置声明位于 plugins/scaffolder-backend/config.d.tsscaffolder.taskRecovery.enabled是否启用自动任务恢复scaffolder.taskRecovery.staleTimeout任务被视为过期stale并进入可恢复队列的等待时长旧配置scaffolder.EXPERIMENTAL_recoverTasks、EXPERIMENTAL_recoverTasksTimeout等已被标记为 deprecated统一迁移到taskRecovery命名空间下。5. 前端OngoingTask 中的恢复交互前端侧任务执行页面 plugins/scaffolder/src/components/OngoingTask/OngoingTask.tsx 通过useTaskEventStream订阅任务事件流并提供取消/恢复任务的交互入口依赖taskCancelPermission、taskCreatePermission、taskReadPermission等权限控制。这为 BEP 中用户手动决定执行回滚的交互场景提供了现成的承载页面——一旦rollback合入 Action API这类页面即可扩展出回滚按钮。与现状的差距BEP 落地还差什么对比 BEP 提案与仓库现状可以明确以下差距维度BEP-0006 提案当前仓库现状Action API 形态createTemplateAction新增可选rollback()plugins/scaffolder-node/src/actions/types.ts 中TemplateAction仅有handler无rollback字段恢复策略取值包含rollbackplugins/scaffolder-common/src/TaskSpec.ts 中仅有none \| startOver内置 Action 覆盖逐步覆盖尚无任何内置 Action 提供回滚实现也就是说BEP-0006 是一份尚未实施的设计蓝图任务恢复的基础设施恢复开关、过期检测、Worker 循环、事件裁剪已经就绪但Action 回滚这一上层能力仍待实现。落地路径大致为在 plugins/scaffolder-node/src/actions/types.ts 的TemplateAction类型中增加可选的rollback字段在TaskRecoverStrategy中引入rollback取值plugins/scaffolder-common/src/TaskSpec.ts并让任务执行器在恢复时根据策略调用各步骤已执行 Action 的rollback为部分内置 Action如publish:github、publish:gitlab等发布类 Action编写回滚实现在前端任务页OngoingTask.tsx增加手动回滚入口。Alternatives备选方案BEP 文档的 Alternatives 章节当前为占位状态仅保留了说明性注释应当记录还考虑过哪些其他方案以及为什么排除它们。从既有实现可以推断社区目前的恢复策略是startOver从头重跑而非撤销式回滚——两者本质差异在于startOver需要模板本身具备幂等性以承受重复执行而回滚则试图通过撤销副作用回归初始状态对模板幂等性的要求更低但对 Action 实现者提出了编写逆向逻辑的要求。这也是 BEP 选择回滚可选、逐步覆盖作为折中方案的原因。总结BEP-0006Scaffolder Action Rollback为 Backstage 模板引擎规划了一条从人工清理半成品资源走向程序化回滚的演进路径通过在createTemplateAction中新增可选的rollback函数、并将rollback纳入任务恢复策略让任务失败后既可以由用户手动触发回滚也可以在自动恢复时按策略执行回滚。当前仓库已具备完整的任务恢复基础设施恢复开关配置、过期检测、Worker 恢复循环、恢复事件裁剪但 Action 级rollbackAPI 尚未合入——对于希望参与 Backstage 插件生态的开发者而言这正是值得关注的扩展点与潜在贡献方向。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考