Backstage 1.55 实现脚手架任务故障自动恢复，并移除废弃目录 API 及强制迁移搜索模块至 Elasticsearch 8

一句话结论

Backstage 1.55 为软件模板任务引入自动恢复机制，同时移除废弃目录 API 并强制搜索模块升级至 Elasticsearch 8，平台团队需处理多项重大变更方可完成升级。

关键要点

新增 `scaffolder.taskRecovery` 配置段，允许崩溃或超时的脚手架任务从最后完成步骤恢复执行，并在任务到达终态前持久化步骤输出。
移除已废弃的目录 API，包括 `catalog.enableRelationsCompatibility` 选项、`CodeOwnersProcessor` 和 `AnnotateScmSlugEntityProcessor`，实体关系现仅返回 `targetRef`。
Elasticsearch 模块强制要求 8.19 或更高版本，但 AWS 与 OpenSearch 提供程序不受此版本限制影响。
TechDocs 生成器不再自动加载不在内置白名单内的 MkDocs 插件，需通过 `techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins` 显式声明额外插件。
工作区序列化功能为可选，其数据库提供程序设有 50 MB 存储限制，仅适用于开发环境，生产环境需使用 GCP 模块或类似外部存储。

背景与事实

Backstage 项目发布开发者门户框架 1.55 版本，核心变更为为软件模板（Scaffolder）任务添加自动恢复能力。该功能通过新增的 `scaffolder.taskRecovery` 配置段启用，系统会在任务因崩溃或超时中断时，从最后完成的步骤继续执行，并在任务最终到达终态前保留任务密钥。同时，已完成步骤的输出会被持久化存储，供后续步骤读取。发布说明特别强调，被恢复任务所执行的动作必须具备幂等性或采用检查点机制，因为恢复流程可能导致某些动作被重复执行。这一新配置段替代了三个实验性标记，但这些旧标记仍可作为备用方案存在。

该功能回应了 2025 年 4 月 GitHub 跟踪 Issue 中长期存在的需求。维护者 Manoj Azad 当时指出，此前脚手架任务失败后不得不重新运行整个流程，不仅操作不便，从技术角度看也存在架构缺陷。1.55 版本覆盖因崩溃或超时中断的任务场景，部分解决了上述痛点。此外，工作区序列化作为可选功能需要独立的提供程序模块支持，其数据库提供程序存在 50 MB 的限制，发布建议生产环境安装 GCP 模块或类似的外部存储服务。

在重大变更方面，目录后端移除了 `catalog.enableRelationsCompatibility` 选项，实体关系现在仅返回 `targetRef`，同时删除了已废弃的 `CodeOwnersProcessor` 和 `AnnotateScmSlugEntityProcessor`，官方推荐改用社区模块替代。搜索模块迁移至 Elasticsearch 8，Elasticsearch 模块现要求 8.19 或更高版本，读取原始客户端响应的自定义代码需要相应修改。TechDocs 不再加载不在内置白名单内的 MkDocs 插件，若团队需要额外插件，必须在 `techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins` 中显式列出。其他重大变更涉及 Backstage UI 链接组件、GitHub 代码库创建动作、增量摄取权限以及 Sentry 脚手架动作。

治理与性能方面，最早在 1.54.6 补丁版本引入的 `scaffolder.requireScmUserCredentials` 选项现要求受支持的 GitHub、GitLab、Bitbucket 和 Azure DevOps 动作使用用户提供的凭证。拒绝未知权限的权限策略现在必须显式允许 `scaffolder.template.dry-run` 才能保证模板试运行正常工作。来自 Veepee 的高级 SRE Michael Todorovic 修改了 GitLab 合并请求与推送动作，改为在本地对比文件。他写道：“publish:gitlab:merge-request 在自建 GitLab 上需要耗时 5 至 15 秒。结果发现几乎所有时间都消耗在动作向 GitLab 查询它本已拥有的信息。”这一改动将一个包含数百个文件仓库的 API 请求量从约 300 次减少到 10 次以内，原本 5 至 15 秒的步骤缩短至约 3 秒。目录、搜索、TechDocs 等核心插件现在仅在页面渲染时才加载页面，减小了应用初始打包体积。

自 9 月 15 日起，维护者已发布三个补丁版本。1.55.1 版本修复了新的 `backstage-cli pm verify-patches` 命令和新前端系统的 TechDocs 附加组件；1.55.2 和 1.55.3 版本修复了 TechDocs 对 MkDocs Markdown 扩展配置的处理逻辑。该版本还列出了 7 个软件包的安全修复，包括 OIDC、Cloudflare Access 认证提供程序以及代理后端，其中 Cloudflare Access 提供程序现需在配置中填写应用受众标识。下一个次要版本 1.56.0-next.2 已于 10 月 6 日发布，进入预发布阶段。

影响分析

对于中文开发者与从业者而言，本次升级的最大实际影响在于迁移成本与兼容性风险。由于目录 API 的大量移除和 Elasticsearch 版本强制提升，现有企业环境在升级前必须完成自定义代码的适配与依赖库的版本对齐，否则将面临服务中断风险。特别是依赖 `catalog.enableRelationsCompatibility` 或旧版处理器逻辑的自定义集成将直接失效，需切换至社区模块或自行实现替代方案。分析判断认为，这一变更旨在提升长期可维护性，但短期内将显著增加升级工作量，团队需在测试环境充分验证实体关系返回 `targetRef` 的下游消费逻辑，并确认 Elasticsearch 8.19+ 集群的部署能力。此外，GitLab 动作性能优化虽显著降低了自建 GitLab 的延迟，但前提是团队需升级至 1.55 版本并重部署相关插件，对于无法频繁升级或运行在私有化受限环境的团队，需评估 5 至 15 秒延迟对 CI/CD 流水线时效性的实际影响，以及是否值得为此承担升级风险。

适用边界

该结论不适用于未部署 Backstage 脚手架功能或仅使用目录与搜索基础能力的轻量级场景，此类用户可忽略 `scaffolder.taskRecovery` 与 GitLab 动作优化部分。同时，若平台运行在 AWS 或 OpenSearch 提供程序之上，则不受 Elasticsearch 8.19 最低版本限制约束，无需升级搜索引擎集群。此外，工作区序列化功能的 50 MB 数据库提供程序限制意味着该功能不适用于产生大体积工作区输出的生产级任务场景，此类场景必须部署 GCP 模块或等价外部存储，否则将因容量超限导致任务失败。