科技资讯
Backstage 1.55 发布之后，不少平台团队的第一反应是「终于不用把中断的脚手架任务从头再跑一遍了」。但站在内部开发者门户（IDP）的运营视角，这个版本更像一次预算评审：一个新开关、一批破坏性变更、一份新增的持久化数据，被同时摆到桌面上【1】。
先把结论放在前面：模板里挂着镜像构建、环境开通、多云资源申请这类分钟级流程的团队，值得为 1.55 排一次升级窗口；模板以秒级为主、自研插件又特别多的团队，可以先观察一个补丁周期再动手。真正决定升级成败的，往往不是 scaffolder.taskRecovery 这个配置段本身，而是动作层的幂等改造与中间产物的存储合规。
图：来源页面配图（已本地备份）。引用：【1】Backstage 1.55 新增脚手架任务恢复功能，并移除已废弃的目录 API — https://www.infoq.cn/article/hilBQCk7QcvclfrgZbSf?utm_source=rss&utm_medium=article
图：示意图（AI 生成，非原文截图；模型 nano-banana-2）。仅作阅读辅助，事实以正文与参考文献为准。
一、先做判断题：三类团队，三种节奏
升级不是统一动作，建议先按模板形态分档：
- 长流程为主：单个模板跑几分钟到几十分钟，中途涉及多个外部系统。恢复能力的价值最直接，值得优先评估，并把它对准流程里最贵的那一步。
- 秒级模板为主：任务本来就一闪而过，崩溃重跑的成本低于改造幂等的成本，恢复开关先别急着打开。
- 自研插件密集、且有内审要求：升级窗口要留足，重点不在新特性，而在破坏性变更清理与数据落点说明。
这张判断表的价值在于：它把「要不要升 1.55」从一个技术偏好问题，变成一个有明确输入输出的决策问题。
二、恢复能力的边界：它救进程，不救逻辑
1.55 通过新增的 scaffolder.taskRecovery 配置段开启恢复，任务可以从最后完成的步骤继续执行，在到达终态之前保留任务密钥，已完成步骤的输出会被持久化，供后续步骤读取【1】。
边界需要说清楚：它覆盖的是崩溃与超时导致的中断，属于进程层面的失败。模板参数写错、下游接口返回 4xx、业务校验不通过，这些都不在恢复范围内——重试多少次结果都一样。公开报道提到，社区早在 2025 年 4 月就在跟踪脚手架任务重试的议题中反映过「整条流程重跑既不便利、技术上也有问题」，而 1.55 覆盖的是其中一部分场景【1】。
对平台团队的实际含义是：不要把它当成「任务一定成功」的保障，而应把它当成「长流程被打断时少损失一点已完成的算力与等待」。预期摆正，后面评估收益才不会失真。
三、第一笔账：幂等改造，成本落在动作层
发布说明里有一句常被略过的话：被恢复的任务所执行的动作应当具备幂等性，或使用检查点机制，因为恢复后的任务可能重复执行某个动作【1】。
这句话的分量在于，它把框架层面的能力，兑换成了动作层的改造工作量。现实中的自定义 action 大量按「只执行一次」的前提写就——直接建仓库、直接写库、直接开工单、直接发通知。一旦恢复触发重放，轻则多出重复工单和重复仓库，重则写入脏数据，事后清理的成本远高于升级本身。
落地时建议按三类归档，而不是逐个凭感觉判断：
- 天然幂等：只读查询、覆盖式写入、按固定键 upsert。这类基本不用动。
- 需要幂等键：建仓库、建项目、开资源单。建议引入模板执行 ID + 步骤 ID 作为去重键，让下游系统自己识别重复请求。
- 需要改写成「先查后建」：对外发通知、触发审批流、调用不支持去重的第三方接口。这类改造量最大，也最容易被漏掉。
工作量估算可以用一个朴素办法：统计高频模板里的 action 数量，乘以单点改造工时，再乘以模板复用权重，先做覆盖 80% 调用量的那批模板。剩下的长尾模板，可以先用「恢复时不重放该类动作」的方式规避，而不是一次全改完。
四、第二笔账：持久化输出是数据资产，也是合规责任
工作区序列化是可选项，需要单独安装提供程序模块。新的数据库提供程序带有 50 MB 限制，定位在开发环境；生产环境发布说明建议使用 GCP 模块或类似的外部存储方案【1】。
这在中国企业环境下会引出两个很实际的问题。
其一是选型适配。如果主云不在 GCP，通常需要按提供程序接口自行适配对象存储，这部分工作量不能按「装个包」来估。它涉及凭证管理、读写权限、失败重试与清理逻辑，属于典型的小而杂的工程。
其二是数据归口。已完成步骤的输出被持久化之后，里面可能包含中间产物、构建日志，甚至配置片段与环境信息。上线前建议先把四个问题答清楚：谁写入、存在哪、留多久、能不能删。这四问恰恰是内部审计与等级保护测评最常追问的，临时补材料远比事先设计规则更费劲。可行的做法包括：对中间产物做字段级脱敏、给序列化数据设置 TTL、把审计读取权限单独收口到只读账号。见下文配图。
五、破坏性变更：按「会不会炸」排序处理
升级工作量的大头在这里。按影响面从高到低，建议这样排【2】：
- 搜索模块：要求 Elasticsearch 8.19 或更高版本，AWS 与 OpenSearch 提供程序不受影响；但读取原始客户端响应的自研代码需要调整。这一条最容易在升级后才暴露，务必先核集群版本、客户端调用方式、自研解析逻辑三样。
- 目录后端：移除
catalog.enableRelationsCompatibility，实体关系现在只返回targetRef；同时移除废弃的CodeOwnersProcessor与AnnotateScmSlugEntityProcessor，官方建议改用社区模块。凡是自研页面直接消费关系数据的，都要跟着改。 - TechDocs：不再加载内置白名单之外的 MkDocs 插件，需要额外插件时必须显式写入
techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins。配置项名字里的 dangerously 不是修辞。 - 其他：涉及 Backstage UI 链接组件、GitHub 代码库创建动作、增量摄取权限以及 Sentry 脚手架动作，属于「看清单逐条核对」的类型。
操作建议是先起一个影子实例，把自研插件与自定义 action 全量跑一遍，把报错整理成清单，再定升级窗口与灰度节奏。比起在主干上直接试错，这个前置动作通常能省下好几轮返工。
六、两处容易被当成 bug 的坑，和一笔实惠账
治理侧有两个点在升级后极易被误判为故障。其一，scaffolder.requireScmUserCredentials 要求受支持的 GitHub、GitLab、Bitbucket 与 Azure DevOps 动作使用用户提供的凭证；这对审计是好事——谁发起的变更，SCM 上就留谁的名【3】。其二，拒绝未知权限的权限策略，必须显式允许 scaffolder.template.dry-run，否则模板试运行会失效【3】。后者如果不提前写进升级检查表，排查起来往往要耗掉半天。
性能侧则有一笔实打实的收益。有实践者把 GitLab 合并请求与推送动作改为在本地对比文件，原因是原动作在自建 GitLab 上单步耗时 5 至 15 秒，时间几乎都花在向 GitLab 查询自己本就掌握的信息上；改造后，数百文件规模仓库的 API 请求量从约 300 次降到 10 次以内，该步骤缩短至约 3 秒【3】。此外目录、搜索、TechDocs 等核心插件改为页面渲染时才加载，减小了应用初始打包体积【3】。对自建 GitLab、跨地域调用 API 的国内团队，这类改动的体感会更明显。
七、30/60 天落地节奏
把上面的判断折成一张可执行表：
- 第 1–2 周：影子实例上线，全量跑自研插件；同步产出三张清单——自研 action 幂等性清单、TechDocs 插件白名单清单、Elasticsearch 客户端调用清单。
- 第 3–4 周：完成高频模板的幂等改造；确定工作区序列化的存储方案与留存策略，和安全团队对齐数据归口。
- 第 5–6 周：灰度上线，
taskRecovery只对长流程模板开启，观察一到两个迭代再扩散；requireScmUserCredentials与 dry-run 权限同步配置。 - 第 7–8 周：全量推进并复盘。补丁版本要跟上——1.55.1 修复了新的
backstage-cli pm verify-patches命令与新前端系统的 TechDocs 附加组件，1.55.2 与 1.55.3 修复了 TechDocs 对 MkDocs Markdown 扩展配置的处理逻辑【4】。 - 全程并行：盯安全修复。本版本列出 7 个软件包的安全修复，涉及 OIDC、Cloudflare Access 认证提供程序与代理后端，其中 Cloudflare Access 提供程序现在需要在配置中填写应用受众标识【4】。
Backstage 的次要版本升级从来不是点一下就完的事。1.55 把任务恢复能力递到手上，同时也把幂等改造和存储治理的责任一并递了过来。先判断自己接不接得住，再决定什么时候升，比抢着升级更有价值。
参考文献
【1】Backstage 1.55 新增脚手架任务恢复功能，并移除已废弃的目录 API — https://www.infoq.cn/article/hilBQCk7QcvclfrgZbSf?utm_source=rss&utm_medium=article
【2】编辑注：破坏性变更条目（搜索模块 Elasticsearch 8.19 门槛、目录后端关系字段与 Processor 移除、TechDocs 插件白名单等）均转述自同一来源 — https://www.infoq.cn/article/hilBQCk7QcvclfrgZbSf?utm_source=rss&utm_medium=article
【3】编辑注：治理配置项与实践者性能数据（SCM 用户凭证要求、dry-run 权限、GitLab 动作本地对比的耗时与请求量变化）转述自同一来源 — https://www.infoq.cn/article/hilBQCk7QcvclfrgZbSf?utm_source=rss&utm_medium=article
【4】编辑注：补丁版本修复点与安全修复范围（1.55.1 至 1.55.3、7 个软件包、Cloudflare Access 受众标识）转述自同一来源 — https://www.infoq.cn/article/hilBQCk7QcvclfrgZbSf?utm_source=rss&utm_medium=article
编辑注：本文基于上述来源的二次解读，版本特性、变更清单与性能数据均转述自该报道，未做额外测算；文中升级节奏与合规建议为编辑视角的原创判断，仅供参考。
