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-backend1.13.0-next.1、backstage/plugin-kubernetes-backend0.10.0-next.1表示这些包处于候选发布状态API 尚未冻结最终发布时可能还会调整变更分Minor Changes与Patch ChangesMinor 代表新增功能或能力扩展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 可以看到它支持三个输入参数参数类型说明urlstring必填指向要拉取的单文件支持相对路径相对于模板仓库或绝对 URLtargetPathstring必填在工作目录中下载文件的目标路径tokenstring可选读取资源时用于认证的可选 token实现中通过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粒度做权限控制。机制分三步在模板的某个 parameter 或 step 下声明backstage:permissions属性并用tags标记该部分后端策略policy通过权限框架给出包含scaffolderTemplateRules.hasTag规则的条件性决策conditional decision权限决策决定该参数/步骤对当前用户是可见可填、还是被隐藏/跳过。从类型定义 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-node0.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-app0.4.39-next.1一节说明新建应用脚手架默认就会把权限 API 接进 Scaffolder。3. 开箱即用的新过滤器parseEntityRef与pickScaffolder 的模板变量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-markdown0.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-backend1.3.0-next.1导出可在新后端系统中直接使用的 search 插件backstage/plugin-search-backend-node1.2.0-next.1导出可在新后端系统使用的服务services与扩展点extension pointsbackstage/plugin-search-backend-module-catalog0.1.0-next.0新包用于以新后端系统模块方式扩展搜索如注册 collatorbackstage/plugin-search-backend-module-explore0.1.0-next.0同上面向 explore 内容类型backstage/plugin-search-backend-module-techdocs0.1.0-next.0同上面向 TechDocs 内容类型backstage/plugin-search-backend-module-elasticsearch1.2.0-next.1与backstage/plugin-search-backend-module-pg0.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-nextchangelog 中可见其依赖了plugin-search-backend、search-backend-module-catalog、search-backend-module-explore、search-backend-module-techdocs等新包就是两种装配方式的对照样例。Kubernetes 后端支持新插件系统backstage/plugin-kubernetes-backend0.10.0-next.1增加了对新插件系统的支持Add support for the new plugin system to the Kubernetes plugin。这是 Kubernetes 插件向新后端系统靠拢的信号此前只能以传统方式注册本版本起可以直接作为新后端系统插件装配。Kubernetes 插件的前端/后端整体文档位于 docs/features/kubernetes。其他值得关注的修复与基础设施更新除上述 Minor Changes 外本版本还有一批值得留意的 Patch ChangesCLI 构建能力backstage/cli0.22.6-next.1修复多入口multiple entry points包构建时可能产生重复模块的问题24432ae52fb支持在构建 loader 中导入.md文件79e91d4c30apackage prepack命令与后端打包在所有操作系统上统一使用 POSIX 路径生成package.jsonb588ab73972Auth 修复backstage/core-components修复使用guest或custom认证提供方时可能导致认证失效的 bugd0befd3fb23Catalog 后端backstage/plugin-catalog-backend允许替换BuiltinKindsEntityProcessor从而可定制 schema 校验与连接relations的产出c4b846359c0Org 插件backstage/plugin-org当实体设置了 title 时Group profile card 的标题使用实体的 titled7c8d8c52ddGraphiQL 插件支持传入懒加载lazy的 GraphQL 端点 URL8b9e8ece403依赖升级zod与zod-to-json-schema全局升级1e4f5e91b8ematerial-ui/lab升级到4.0.0-alpha.6129ba8267d69以及大量包的 peer dependency 更新e0c6e8b9c3c类型与文档scaffolder 输出参数的类型检查得到改进a7eb36c6e38plugin-adr、plugin-airbrake、plugin-dynatrace等插件完善了 API Reference 文档7d75f6d9b8f。升级与验证建议由于-next.1是预发布版本生产环境应等待1.13.0正式版v1.13.0.md发布后再升级。若要在开发环境尝鲜可按以下路径验证验证fetch:plain:file在任意模板中增加上述示例步骤运行模板的干跑dry-run模式观察工作区中是否出现目标文件验证新过滤器在模板参数或步骤的input中使用${{ parameters.entity | parseEntityRef | pick(name) }}并确认输入参数中存在合法的实体三元组字符串验证权限授权参照 docs/permissions 接入权限框架编写一个包含scaffolderTemplateRules.hasTag的条件策略然后在模板参数上声明backstage:permissions.tags观察不同用户角色下该参数是否被隐藏或禁用搜索新后端系统迁移对照 docs/features/search 与 docs/backend-system 的说明将 collator 注册方式从传统工厂切换为search-backend-module-*模块。小结v1.13.0-next.1 的技术主线可以概括为三件事Scaffolder 走向精细化权限控制与更丰富的内置动作/过滤器fetch:plain:file、backstage:permissionshasTag、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考