Backstage v1.13.0-next.1 深度解析：Scaffolder 权限授权、新 Action 与搜索后端新系统迁移

Backstage v1.13.0-next.1 深度解析：Scaffolder 权限授权、新 Action 与搜索后端新系统迁移

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本篇文章以 Backstage 官方仓库docs/releases/v1.13.0-next.1-changelog.md为核心，深入拆解这一预发布版本中plugin-scaffolder-backend的重大能力升级（模板参数/步骤权限授权、fetch:plain:file动作、parseEntityRef/pick新过滤器）、全新confluence:transform:markdown动作，以及搜索后端向新后端系统（new backend system）的整体迁移，并结合仓库源码给出可验证的实现依据。读完本文，你将掌握 v1.13.0 版本线的技术脉络、这些新特性如何在模板中落地使用，以及升级时需要关注的依赖与破坏性变化。

版本背景：-next.1预发布意味着什么

v1.13.0-next.1是 Backstage 1.13.0 正式版（对应仓库中的 docs/releases/v1.13.0.md）发布之前的第二个预发布快照（next 序列）。这类 changelog 通常被搜索引擎与自动化发布工具消费，用于生成最终 Release Notes。它有两个典型特征：

• 版本号带-next.N后缀：例如@backstage/plugin-scaffolder-backend@1.13.0-next.1、@backstage/plugin-kubernetes-backend@0.10.0-next.1，表示这些包处于候选发布状态，API 尚未冻结，最终发布时可能还会调整；
• 变更分Minor Changes与Patch Changes：Minor 代表新增功能或能力扩展，Patch 代表缺陷修复与依赖升级。本文重点讲解 Minor Changes，因为它们是这一版本真正"上新"的部分。

如果你想查看完整内容，可直接阅读仓库中的 v1.13.0-next.1-changelog.md 与最终版 v1.13.0.md。

Scaffolder 三大能力升级（本版本的核心）

1. 新增内置动作fetch:plain:file：单文件拉取

此前的fetch:plain动作以整个目录为单位从远端仓库/URL 拉取内容；v1.13.0-next.1 新增了fetch:plain:file，用于只拉取单个文件并放置到任务工作区（task workspace）中。变更说明原文为：

Addedfetch:plain:fileaction to fetch a single file, this action is also added to the list of built-in actions.

该动作已加入 Scaffolder 的内置动作列表，无需额外安装模块。从源码实现 plainFile.ts 可以看到它支持三个输入参数：

实现中通过resolveSafeChildPath将targetPath安全解析到工作区内（防止路径穿越），并通过assertScmUserCredentials校验 SCM 凭据（当requireScmUserCredentials开启时），最后调用fetchFile完成下载。它同样声明了supportsDryRun: true，支持干跑模式。

仓库自带的官方示例 plainFile.examples.ts 展示了最基础的用法：

steps: - action: fetch:plain:file id: fetch-plain-file name: Fetch plain file input: url: 'https://github.com/backstage/community/tree/main/backstage-community-sessions/assets/Backstage%20Community%20Sessions.png' targetPath: 'target-path'

典型场景：在模板中只下载某个配置文件、Logo 图片或 LICENSE 文件，而无需把整个仓库目录拉进工作区。对应的单元测试见 plainFile.test.ts。

2. 模板参数与步骤的权限授权（Permission Framework 集成）

这是本版本 Scaffolder 最具分量的变更，原文为：

Added the possibility to authorize parameters and steps of a template. The scaffolder plugin is now integrated with the permission framework. It is possible to toggle parameters or actions within templates by marking each section with specifictags, inside abackstage:permissionsproperty under each parameter or action. Each parameter or action can then be permissioned by using a conditional decision containing thescaffolderTemplateRules.hasTagrule.

翻译成大白话：Scaffolder 从此可以按"参数（parameters）"和"步骤（steps）"粒度做权限控制。机制分三步：

1. 在模板的某个 parameter 或 step 下声明backstage:permissions属性，并用tags标记该部分；
2. 后端策略（policy）通过权限框架给出包含scaffolderTemplateRules.hasTag规则的条件性决策（conditional decision）；
3. 权限决策决定该参数/步骤对当前用户是可见可填、还是被隐藏/跳过。

从类型定义 TemplateEntityV1beta3.ts 可以看到，TemplateParametersV1beta3与TemplateStepsV1beta3都新增了可选的'backstage:permissions'?: TemplatePermissionsV1beta3字段，这正是上述声明在模板 schema 层面的落点。同一变更还在plugin-scaffolder-common中"Added permissions for authorizing parameters and steps"。

配合使用的基础规则是scaffolderTemplateRules.hasTag，而权限框架侧的关键设施由@backstage/plugin-permission-node提供——本版本为其新增了createConditionAuthorizer工具函数（见 changelog 中plugin-permission-node@0.7.7-next.1一节）：它接收若干权限条件，返回一个根据"决策+资源"得出确定性授权结果的函数，是实现上述条件授权的基础设施。

模板侧声明示例（结合 changelog 描述与 schema 组织方式）：

apiVersion: scaffolder.backstage.io/v1beta3 kind: Template spec: parameters: - title: Project details properties: owner: type: string backstage:permissions: tags: - admin-only steps: - id: debug action: debug:log input: message: hello backstage:permissions: tags: - debug-only

权限框架的完整接入与策略编写方法，可参考仓库 docs/permissions 目录（概念见 docs/permissions/concepts.md、策略编写见 docs/permissions/writing-a-policy.md）。另外注意，create-app在本版本为 scaffolder-backend 插件加入了permissionApi依赖（changelog 中@backstage/create-app@0.4.39-next.1一节），说明新建应用脚手架默认就会把权限 API 接进 Scaffolder。

3. 开箱即用的新过滤器：parseEntityRef与pick

Scaffolder 的模板变量（Nunjucks）过滤器体系在本版本得到扩展，且官方对过滤器应用方式做了重构。新增两个默认过滤器：

• parseEntityRef：接收一个字符串形式的实体三元组（entity triplet），返回解析后的对象；
• pick：从流水线传入的对象中引用指定属性。

因此你现在可以这样组合：

${{ parameters.entity | parseEntityRef | pick('name') }} ${{ parameters.repoUrl | parseRepoUrl | pick('owner') }}

第一行取出某个实体的name，第二行取出仓库 URL 的owner。这与变更说明给出的示例完全一致：

So you can now combine things like this:${{ parameters.entity | parseEntityRef | pick('name') }}to get the name of a specific entity, or${{ parameters.repoUrl | parseRepoUrl | pick('owner') }}to get the owner of a repo.

从源码看，parseEntityRef直接复用了@backstage/catalog-model的parseEntityRef（见 filter.ts），支持字符串紧凑引用与CompoundEntityRef对象两种输入，并可传入defaultKind/defaultNamespace作为缺省值；pick则基于 lodash 的get实现（见 filter.ts）。这两个过滤器与已有的parseRepoUrl、projectSlug一起，由createDefaultFilters统一注册进SecureTemplater（见 createDefaultFilters.ts），开箱即用，无需额外配置。

新模块：confluence:transform:markdown动作

v1.13.0-next.1 引入了全新独立包@backstage/plugin-scaffolder-backend-module-confluence-to-markdown@0.1.0-next.0，提供confluence:transform:markdown动作，用于把 Confluence 文档转换为 Markdown 后落入 Scaffolder 工作区。仓库中的实现见 confluenceToMarkdown.ts，并配有示例 confluenceToMarkdown.examples.ts、单元测试 confluenceToMarkdown.test.ts 以及一份可直接参考的 sample-template.yaml。

典型用途：企业内网知识库沉淀在 Confluence，而研发团队希望在生成项目时自动把相关 Confluence 文档转成 Markdown 写入仓库（例如架构说明、规范文档）。该模块依赖@backstage/plugin-scaffolder-backend与@backstage/integration（用于解析 Confluence 的 SCM 配置与认证信息），使用时需将其作为独立模块安装并注册到 Scaffolder。需要注意这是全新的0.1.0包，API 后续仍可能演进。

搜索后端：整体迁移到新后端系统

本版本在搜索领域的一次"集体搬迁"，涉及 6 个包，主线是让搜索能力可通过新后端系统（new backend system）的插件/模块方式装配：

• @backstage/plugin-search-backend@1.3.0-next.1：导出可在新后端系统中直接使用的 search 插件；
• @backstage/plugin-search-backend-node@1.2.0-next.1：导出可在新后端系统使用的服务（services）与扩展点（extension points）；
• @backstage/plugin-search-backend-module-catalog@0.1.0-next.0：新包，用于以新后端系统模块方式扩展搜索（如注册 collator）；
• @backstage/plugin-search-backend-module-explore@0.1.0-next.0：同上，面向 explore 内容类型；
• @backstage/plugin-search-backend-module-techdocs@0.1.0-next.0：同上，面向 TechDocs 内容类型；
• @backstage/plugin-search-backend-module-elasticsearch@1.2.0-next.1与@backstage/plugin-search-backend-module-pg@0.5.5-next.1：迁移到新后端系统。

同时，plugin-catalog-backend、plugin-explore-backend、plugin-techdocs-backend中原来直接实例化的 collator 工厂被"新后端系统模块实例化 + 标记为 deprecated"，并明确"在新后端系统完全铺开前会继续公开导出"。这意味着：

• 如果你正在使用传统后端（legacy backend），原有 collator 注册方式仍然可用，但已进入弃用通道；
• 如果你使用新后端系统，应改为通过search-backend-module-*模块装配搜索能力。

本仓库的新后端系统文档见 docs/backend-system，架构说明可参考 docs/backend-system/architecture；搜索功能整体文档见 docs/features/search。仓库中的示例后端 packages/backend 与example-backend-next（changelog 中可见其依赖了plugin-search-backend、search-backend-module-catalog、search-backend-module-explore、search-backend-module-techdocs等新包）就是两种装配方式的对照样例。

Kubernetes 后端支持新插件系统

@backstage/plugin-kubernetes-backend@0.10.0-next.1增加了对新插件系统的支持（"Add support for the new plugin system to the Kubernetes plugin"）。这是 Kubernetes 插件向新后端系统靠拢的信号：此前只能以传统方式注册，本版本起可以直接作为新后端系统插件装配。Kubernetes 插件的前端/后端整体文档位于 docs/features/kubernetes。

其他值得关注的修复与基础设施更新

除上述 Minor Changes 外，本版本还有一批值得留意的 Patch Changes：

• CLI 构建能力（@backstage/cli@0.22.6-next.1）：修复多入口（multiple entry points）包构建时可能产生重复模块的问题（24432ae52fb）；支持在构建 loader 中导入.md文件（79e91d4c30a）；package prepack命令与后端打包在所有操作系统上统一使用 POSIX 路径生成package.json（b588ab73972）；
• Auth 修复（@backstage/core-components）：修复使用guest或custom认证提供方时可能导致认证失效的 bug（d0befd3fb23）；
• Catalog 后端（@backstage/plugin-catalog-backend）：允许替换BuiltinKindsEntityProcessor，从而可定制 schema 校验与连接（relations）的产出（c4b846359c0）；
• Org 插件（@backstage/plugin-org）：当实体设置了 title 时，Group profile card 的标题使用实体的 title（d7c8d8c52dd）；
• GraphiQL 插件：支持传入懒加载（lazy）的 GraphQL 端点 URL（8b9e8ece403）；
• 依赖升级：zod与zod-to-json-schema全局升级（1e4f5e91b8e），@material-ui/lab升级到4.0.0-alpha.61（29ba8267d69），以及大量包的 peer dependency 更新（e0c6e8b9c3c）；
• 类型与文档：scaffolder 输出参数的类型检查得到改进（a7eb36c6e38）；plugin-adr、plugin-airbrake、plugin-dynatrace等插件完善了 API Reference 文档（7d75f6d9b8f）。

升级与验证建议

由于-next.1是预发布版本，生产环境应等待1.13.0正式版（v1.13.0.md）发布后再升级。若要在开发环境尝鲜，可按以下路径验证：

1. 验证fetch:plain:file：在任意模板中增加上述示例步骤，运行模板的干跑（dry-run）模式，观察工作区中是否出现目标文件；
2. 验证新过滤器：在模板参数或步骤的input中使用${{ parameters.entity | parseEntityRef | pick('name') }}，并确认输入参数中存在合法的实体三元组字符串；
3. 验证权限授权：参照 docs/permissions 接入权限框架，编写一个包含scaffolderTemplateRules.hasTag的条件策略，然后在模板参数上声明backstage:permissions.tags，观察不同用户角色下该参数是否被隐藏或禁用；
4. 搜索新后端系统迁移：对照 docs/features/search 与 docs/backend-system 的说明，将 collator 注册方式从传统工厂切换为search-backend-module-*模块。

小结

v1.13.0-next.1 的技术主线可以概括为三件事：Scaffolder 走向精细化权限控制与更丰富的内置动作/过滤器（fetch:plain:file、backstage:permissions+hasTag、parseEntityRef/pick），搜索能力完成向新后端系统的整体迁移（search-backend与各search-backend-module-*包），以及Kubernetes 后端开始支持新插件系统。对于模板作者，建议优先体验parseEntityRef/pick组合与fetch:plain:file；对于平台管理员，则需要关注权限框架在 Scaffolder 中的落地方式，以及搜索模块的装配方式变化。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage