Backstage v1.33.0 发布解读：目录性能优化与面包屑导航、只读文件系统配置注入、Scaffolder Node.js 22 支持等关键更新-编程实验室

Backstage v1.33.0 发布解读：目录性能优化与面包屑导航、只读文件系统配置注入、Scaffolder Node.js 22 支持等关键更新

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

导读

本文基于 Backstage 官方发布说明 docs/releases/v1.33.0.md，系统解读 v1.33.0 的核心变更：包括 Catalog 读路径性能优化与实体页面包屑导航、app-backend在只读文件系统下的内存化配置注入、LEGACY_BACKEND_START的移除（破坏性变更）、Scaffolder 对 Node.js v22 的支持、新增的scaffolder.template.management权限与fs:readdir动作，以及catalogServiceRef、generate-patchCLI 命令等开发者关注的能力。读完本文，你将掌握 v1.33.0 的完整变更清单、各破坏性变更的迁移路径，以及这些特性对应的源码级实现细节，可据此规划升级或直接使用新能力。

版本概览

Backstage v1.33.0 是一次包含性能优化、新能力与若干破坏性变更的常规版本发布。官方建议将 Backstage 项目保持在该版本及以上，具体升级指引可参考仓库内文档 docs/getting-started/keeping-backstage-updated.md。本次发布重点集中在四个方面：

Catalog（目录）：读路径性能优化、实体页默认面包屑导航；
后端部署体验：app-backend配置注入支持只读文件系统；
Scaffolder（脚手架）：Node.js v22 支持、新的管理权限与fs:readdir动作；
开发/运维工具链：catalogServiceRef服务引用、generate-patchCLI 命令、Google LDAP 支持。

下面按主题逐一展开，并结合当前仓库源码给出实现层面的印证。

Catalog 性能优化与实体面包屑

读路径不再依赖`refresh_state`表

v1.33.0 对 Catalog 后端做了一系列数据库层面的优化与修复：读路径（read path）不再需要refresh_state表，同时移除了一批索引。官方预期这不会对最终用户产生负面影响，反而会因索引维护（index churn）减少、存储占用下降而带来性能提升。

从实现结构看，Catalog 后端的核心服务位于 plugins/catalog-backend/src/service（如CatalogPlugin.ts），实体刷新与处理逻辑集中在refresh与processing相关模块中。此次优化属于对存量表结构与查询计划的调整，对使用方而言是透明的——无需修改catalog-info.yaml或 API 调用方式。

实体页默认启用面包屑

Entity 页面现在默认在页头（page header）显示面包屑控件（breadcrumb），用于展示当前实体所处的上下文，例如它属于哪个 system（系统）与 domain（域）。

面包屑依赖 Catalog 的实体关系模型。仓库中实体关系的基础类型定义在 packages/catalog-model，而实体页面的相关组件实现集中在 plugins/catalog。该特性让用户在浏览深层嵌套的实体关系时能快速定位层级位置，是 Catalog 导航体验的重要改进。

App 后端配置注入支持只读文件系统

变更内容

app-backend此前会把模板化（templated）后的index.html写入磁盘再提供静态服务；v1.33.0 改为在内存中保存模板化后的index.html，不再落盘。

这意味着：在以只读文件系统运行 Backstage 时，不再需要设置app.disableConfigInjection标志，可以直接享受配置注入（config injection）带来的运行时配置能力。

源码印证

在 plugins/app-backend/src/service/router.ts 中，app.disableConfigInjection仍作为可选配置项存在：

const disableConfigInjection = config.getOptionalBoolean( 'app.disableConfigInjection', );

但配置注入的结果现在以内存形式返回。injectConfigIntoHtml会将注入后的 HTML 作为Buffer返回（见 plugins/app-backend/src/lib/config/injectConfigIntoHtml.ts），路由层直接通过injectResult?.indexHtmlContent响应请求（见 router.ts），全程不涉及磁盘写入：

if (injectResult?.indexHtmlContent) { res.send(injectResult.indexHtmlContent); }

对部署的启示

如果你的部署方案使用只读根文件系统（例如不可变容器镜像、KubernetesreadOnlyRootFilesystem），升级到 v1.33.0 后可以移除app.disableConfigInjection: true配置，让前端应用继续获得运行时配置注入能力，而无需依赖可写的临时目录。相关配置项说明可参考 docs/conf/defining.md。

破坏性变更：`LEGACY_BACKEND_START`已移除

变更内容

CLI 不再支持LEGACY_BACKEND_START标志。这意味着旧的开发入口src/run.ts必须迁移到新的dev/index.ts结构。

迁移路径

删除src/run.ts中基于LEGACY_BACKEND_START的旧启动逻辑；
改为新后端系统（New Backend System）推荐的src/dev/index.ts入口结构。

新后端系统的完整构建方式与模块注册方法参见 docs/backend-system，其中 building-backends 与 building-plugins-and-modules 目录提供了从旧入口迁移到dev/index.ts的具体指引。

Scaffolder 支持 Node.js v22

变更内容

isolated-vm依赖升级到v5，使 Scaffolder 现在支持Node.js v22；同时意味着Node.js v16 不再支持运行 Scaffolder。

isolated-vm是 Scaffolder 在受限沙箱中执行模板自定义脚本（如fetch、parseJson等 Template 辅助函数）的关键依赖。升级到 v5 后：

✅ 支持 Node.js v22（含其更新的 V8 引擎与原生 API）；
❌ Node.js v16 环境将无法运行 Scaffolder。

对环境的约束

升级 v1.33.0 前，请确认运行 Backstage 后端的环境满足：Node.js 版本为 18 或 20 或 22（v16 已不支持）。Scaffolder 后端实现位于 plugins/scaffolder-backend，其环境要求与依赖声明可在该包的package.json与官方 Node.js 支持策略（见 docs/overview/versioning-policy.md）中进一步核对。

Scaffolder 新增权限与动作

新权限：`scaffolder.template.management`

v1.33.0 新增scaffolder.template.management权限，用于限制对前端模板管理功能（template management）的访问。该权限由社区贡献者 @stephenglass 提交（PR #26946）。

从源码看，该权限定义在 plugins/scaffolder-common/src/permissions.ts：

/** * This permission is used to authorize template management features. * * @alpha */ export const templateManagementPermission = createPermission({ name: 'scaffolder.template.management', attributes: {}, });

它被纳入scaffolderPermissions汇总列表（见同文件末尾），供权限策略（policy）统一引用。

在前端，模板管理相关 UI（如模板的创建/编辑入口）通过RequirePermission组件包裹，未授权用户将看不到这些功能（见 plugins/scaffolder/src/components/Router/Router.tsx）：

import { RequirePermission } from '@backstage/plugin-permission-react'; import { templateManagementPermission } from '@backstage/plugin-scaffolder-common/alpha'; <RequirePermission permission={templateManagementPermission}> {/* 模板管理相关 UI */} </RequirePermission>

使用建议：如果你希望在平台中仅对部分用户开放模板管理（而非所有能使用模板的人），可以在权限策略中基于scaffolder.template.management做条件授权。权限策略编写方法参见 docs/permissions/writing-a-policy.md。

新动作：`fs:readdir`

新增内置动作fs:readdir，用于读取 workspace 内指定目录的内容。该动作由社区贡献者 @secustor 提交（PR #27283）。

输入与输出 Schema

实现位于 plugins/scaffolder-backend/src/scaffolder/actions/builtin/filesystem/read.ts：

方向	字段	类型	说明
input	`paths`	`string[]`（每项非空）	相对 workspace 的目录路径列表，可传多个目录
input	`recursive`	`boolean`（默认`false`）	是否递归读取子目录
output	`files`	对象数组	命中的文件列表，每项含`name`、`path`（相对 workspace）、`fullPath`
output	`folders`	对象数组	命中的目录列表，字段同上

动作声明了supportsDryRun: true，即支持 Scaffolder 的 dry-run 试运行模式。

实现细节

fs:readdir在 handler 中使用fs.readdir(..., { recursive, withFileTypes: true })枚举目录项，并通过resolveSafeChildPath将输入路径解析到 workspace 内（防止路径逃逸），最后按dirent.isDirectory()区分文件与目录，分别写入files与folders输出。核心代码位于 read.ts。

模板使用示例

仓库内置示例见 read.examples.ts，以下三种典型用法可直接套用：

1. 读取整个 workspace：

steps: - action: fs:readdir id: read-workdir name: Read workspace directory input: paths: ['.']

2. 递归读取docs目录：

steps: - action: fs:readdir id: read-workdir name: Read workspace directory input: paths: ['docs'] recursive: true

3. 同时读取多个目录：

steps: - action: fs:readdir id: read-workdir name: Read workspace directory input: paths: ['foo', 'bar'] recursive: true

典型场景：在模板中先枚举生成后的目录结构，再结合debug:log输出、或根据目录/文件存在情况做条件分支，实现更智能的模板编排。更多自定义动作的编写方式参见 docs/plugins/creating-plugins 相关文档及 plugins/scaffolder-backend/src/scaffolder/actions/builtin 下的其它内置动作实现。

Catalog 服务引用`catalogServiceRef`

变更内容

@backstage/plugin-catalog-node新增导出catalogServiceRef，后端应迁移到基于该服务引用（service ref）来完成对 Catalog 的通信，而不再手动实例化CatalogService。

核心优势

最重要的改进是：它直接支持传入 credentials 参数，从而在调用 Catalog 时具备正确的鉴权能力，无需再借助authcore service 手动签发 token。

源码印证

catalogServiceRef定义于 plugins/catalog-node/src/catalogService.ts：

export const catalogServiceRef = createServiceRef<CatalogService>({ // ... });

并从 plugins/catalog-node/src/index.ts 对外导出；测试覆盖见 plugins/catalog-node/src/catalogService.test.ts（通过tester.getService(catalogServiceRef)获取服务实例）。

在 backend 中注册 Catalog 插件时，catalogServiceRef由插件自身绑定提供（见 plugins/catalog-backend/src/service/CatalogPlugin.ts），其它插件/模块只需在依赖中声明catalog: catalogServiceRef即可注入。

迁移建议：如果你的后端模块此前通过手写CatalogClient+ 手工造 token 的方式访问 Catalog，应改用catalogServiceRef注入，配合请求的 credentials 参数即可获得内置鉴权。后端插件依赖注入的写法参见 docs/backend-system/building-plugins-and-modules。

新 CLI 命令：`generate-patch`

v1.33.0 新增generate-patchCLI 命令（PR #27331），用于为源 workspace 中的当前改动生成补丁（patch），随后可安装到目标 workspace。这让你能够立即使用上游贡献的改动，而无需等待发布版本。

命令行为

实现位于 packages/repo-tools/src/commands/generate-patch/generate-patch.ts，核心流程：

在源仓库中找到指定包（packageArg，支持包名或相对路径）；
构建并yarn pack出目标归档（target archive）；
从 npm registry（默认https://registry.npmjs.org，可通过--registryUrl覆盖）下载指定baseVersion的基础归档；
用 git 对两个归档做 diff，生成.patch文件，写入目标仓库的.yarn/patches/目录；
更新目标仓库根package.json的resolutions字段，追加patch:条目；
默认在目标 workspace 执行yarn install（可用--skipInstall跳过）。

支持的选项

选项	说明
`packageArg`（位置参数）	要打补丁的包，包名（如`@backstage/plugin-catalog`）或源仓库内相对路径
`--target <path>`	目标 workspace 的根目录（必填）
`--query <query>`	指定匹配的包版本查询串；仅对匹配的版本生成补丁
`--registryUrl <url>`	下载基础归档的 npm registry 地址
`--baseVersion <version>`	补丁的基础版本，默认取源包当前版本
`--skipInstall`	跳过目标 workspace 的`yarn install`

生成补丁时的排除规则

补丁生成过程会自动忽略以下内容（见源码中PATCH_GITIGNORE常量）：

*.map（source map，避免无意义补丁）；
package.json（打补丁无实际效果）；
根目录/*.md与/docs（文档不参与补丁）。

同时要求：源与目标仓库均使用 Yarn（且存在.yarnrc.yml，不支持 Yarn v1 classic），且两者不是同一仓库根目录，否则命令会直接报错。

典型场景：上游 PR 修复了你依赖的某个 Backstage 包，但尚未发版。你可以把该修复合入本地源码 clone（源 workspace），然后运行generate-patch生成补丁并安装到自己的应用（目标 workspace），立即获得修复。

Google LDAP 支持

@backstage/plugin-catalog-backend-module-ldap新增对Google LDAP的支持（由社区贡献者 @megatroom 提交，PR #27373）。

LDAP 提供者用于从 LDAP/AD 目录同步用户与组到 Catalog。新增 Google LDAP 支持意味着可以在该模块的配置中使用 Google 提供的 LDAP 端点（ldap.google.com）进行组织目录同步。具体配置项（如providers、target、user、group等）与同步处理器说明参见 plugins/catalog-backend-module-ldap 包及 docs/integrations/ldap 文档。

破坏性变更：AWS ALB 认证不再小写化用户名/邮箱

变更内容

v1.33.0 中，AWS ALB 提供者（@backstage/plugin-auth-backend-module-aws-alb-provider）的fullProfile不再将 username 或 email 转换为小写，以确保用户处理的唯一性（区分大小写）。

影响与应对

如果你依赖此前的小写化行为，需要配置自定义的 sign-in resolver 或 profile transform，自行对大小写做归一化处理。

从源码看，该提供者构造fullProfile的逻辑位于 plugins/auth-backend-module-aws-alb-provider/src/authenticator.ts，其中makeProfileInfo基于fullProfile生成登录态信息。相关测试见 authenticator.test.ts。

迁移建议：检查你现有的 AWS ALB 登录流程是否依赖小写化的用户名/邮箱来匹配 Catalog 中的实体。若依赖，请在signIn.resolvers或 profile transform 中显式调用toLowerCase()，确保新旧行为一致。身份解析（identity resolver）的配置方式参见 docs/auth/identity-resolver.md。

安全修复

v1.33.0 对Kubernetes 插件进行了安全修复：升级@kubernetes/client-node依赖，以缓解与request和tough-cookie两个包相关的 CVE（由社区贡献者 @coreydaley 提交，PR #25385）。

使用 Kubernetes 插件的用户，升级到 v1.33.0 后即自动获得该依赖修复，无需额外操作。Kubernetes 插件文档参见 docs/features/kubernetes。

升级路径与注意事项汇总

官方建议保持 Backstage 项目持续跟随最新版本，升级指引详见 docs/getting-started/keeping-backstage-updated.md。

针对 v1.33.0，升级前请重点核对以下事项：

移除LEGACY_BACKEND_START：若src/run.ts仍在使用旧标志，必须迁移到dev/index.ts结构（参见 docs/backend-system）；
Node.js 版本：Scaffolder 不再支持 Node.js v16，需确保运行环境为 Node.js 18/20/22；
AWS ALB 登录：如依赖小写化用户名/邮箱，请配置自定义 sign-in resolver 或 profile transform；
只读文件系统部署：升级后可移除app.disableConfigInjection，启用内存化配置注入；
后端 Catalog 通信：逐步将手写CatalogService迁移到catalogServiceRef，获得内置 credentials 鉴权支持。

结语

v1.33.0 体现了 Backstage 在「性能优化 + 部署体验 + 脚手架能力」三个方向上的持续投入：Catalog 读路径瘦身与面包屑导航降低了大规模目录场景下的维护成本与导航成本；app-backend内存化配置注入消除了只读文件系统部署的痛点；Scaffolder 则通过 Node.js v22 支持、模板管理权限与fs:readdir动作进一步扩展了可编排性与安全边界。同时，LEGACY_BACKEND_START的移除与 AWS ALB 认证行为调整是需要升级团队提前规划的破坏性变更。对照本文给出的源码位置（如 read.ts、permissions.ts、catalogService.ts、generate-patch.ts），你可以进一步深入验证各特性的实现细节，并据此制定升级与迁移计划。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考