尧图网站建设 
Backstage v1.33.0-next.1 发布解析CLI 测试性能优化、增量摄取 API 演进与依赖安全升级全指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文以仓库内 docs/releases/v1.33.0-next.1-changelog.md 为骨架结合packages/cli、plugins/catalog-backend-module-incremental-ingestion、plugins/kubernetes*、plugins/scaffolder-backend等模块的当前源码系统解读本次预发布版本next.1中的 Minor 变更与关键 Patch 修复。读完本文你将掌握repo testwatch 模式的性能优化原理与--successCache缓存修复细节、incremental-ingestion从luxon迁移到HumanDuration的 API 迁移清单以及 Kubernetes 客户端升级与 Scaffolder 沙箱升级带来的兼容性影响从而判断升级到该版本时哪些代码需要改动、哪些 CI 脚本需要调整。一、版本总览本次变更波及哪些模块v1.33.0-next.1 是 v1.33.0 的第二个预览版本next.1表示在next.0基础上叠加的补丁集其变更分布在三大主线主线涉及模块变更性质CLI 工具链backstage/cli0.29.0-next.1Minorrepo testwatch 模式过滤未使用包Patch--successCache三处修复目录增量摄取backstage/plugin-catalog-backend-module-incremental-ingestion0.6.0-next.1Minor公开 API 全面改用HumanDuration依赖安全与兼容性plugin-kubernetes*、plugin-scaffolder-backend及其 moduleMinorKubernetes 客户端升级、isolated-vmv5 升级其余大量包backend-*、auth-backend、catalog-backend、search-*、techdocs-*等在本版本中主要以依赖联动Updated dependencies方式跟随升级属于常规的版本同步没有独立的 API 变化。下面按主题逐项深入。二、backstage/clirepo test的性能优化与--successCache修复2.1 Minor 变更watch 模式下自动过滤未使用包本次 CLI 最重要的功能改进来自提交6819f8crepo test命令在 watch 模式下新增了一项优化——当所有提供的 filter 都是从仓库根目录指向的具体路径时CLI 会过滤掉未使用的包只对相关的包执行测试监听。典型场景是在大型 monorepo workspace 中从根目录单独运行某个测试yarn test packages/app/src/App.test.tsx在此之前即使你只指定了一个测试文件CLI 也需要对整个 workspace 中的所有包进行监听和编排优化之后由于 filter 是明确的仓库根路径packages/app/...CLI 可以推断出只有packages/app这一个包真正参与本次测试从而跳过其他包显著缩短启动和增量重跑的耗时。该命令的完整参数形态可以在 packages/cli/cli-report.md 中查到repo test与repo lint均支持--success-cache与--success-cache-dir string参数。2.2 Patch 修复--successCache的缓存正确性问题--successCache现已推荐使用 kebab-case 写法--success-cache旧写法仍可用但会打印弃用警告详见 packages/cli/CHANGELOG.md用于在测试或 lint 成功后复用结果、跳过重复执行。本版本针对它做了三处修复直接影响 CI 的缓存命中率与正确性缓存键不应包含 workspace 路径4046d53此前生成的缓存键会包含 workspace 路径导致在不同构建环境之间例如 CI 中 checkout 路径不一致、或本地与 CI 路径不同缓存永远无法命中。修复后缓存键不再依赖工作区绝对路径。错误的包目录 tree hash6b2888crepo test使用--successCache时偶尔会用错误的包目录的 tree hash 来生成缓存键导致缓存键错乱。本次修正为使用正确包目录的哈希。lint 缓存未遵守.eslintignore4046d53repo lint的缓存键此前没有正确忽略.eslintignore中标记为忽略的文件修复后这些文件不再参与缓存键计算。升级提示如果 CI 或本地脚本仍在使用 camelCase 的--successCache建议按 packages/cli/CHANGELOG.md 中的说明迁移为--success-cache避免未来版本移除旧写法时构建失败。三、incremental-ingestion公开 API 全面迁移到 HumanDuration3.1 变更动机与影响面backstage/plugin-catalog-backend-module-incremental-ingestion0.6.0-next.1的 Minor 变更提交6cf91c5将公开 API 中所有与时序相关的类型从luxon的Duration替换为backstage/types导出的HumanDuration。二者在语义上基本兼容但存在两处需要注意的写法差异。这一迁移在当前仓库源码中已经落地。在 plugins/catalog-backend-module-incremental-ingestion/src/types.ts 中IncrementalEntityProviderOptions的所有时长字段均为HumanDurationimport { HumanDuration } from backstage/types; export interface IncrementalEntityProviderOptions { /** 两次摄入 burst 之间的等待时间 */ burstInterval: HumanDuration; /** 每个 burst 持续摄取的时长上限 */ burstLength: HumanDuration; /** 一次成功摄取后进入休息状态的时长 */ restLength: HumanDuration; /** 出错后的退避时长序列例如 [{ minutes: 1 }, { minutes: 5 }, { minutes: 30 }, { hours: 3 }] */ backoff?: HumanDuration[]; rejectRemovalsAbovePercentage?: number; rejectEmptySourceCollections?: boolean; }对应的IterationEngineOptionstypes.ts同样使用HumanDuration类型的restLength、burstLength与backoff。3.2 迁移注意事项根据变更说明升级时需要检查以下两类写法季度调度如果此前使用quarter/quartersluxon 支持的季度单位请改用{ months: 3 }// 旧写法luxon Duration // schedule: { quarter: 1 } // 新写法HumanDuration backoff: [{ months: 3 }]单数名词改复数HumanDuration只接受复数键此前形如year: 1、minute: 5的写法要改为years: 1、minutes: 5// 旧写法 // restLength: { hour: 1 } // 新写法 restLength: { hours: 1 }3.3 引擎侧如何消费这些时长从 plugins/catalog-backend-module-incremental-ingestion/src/engine/IncrementalIngestionEngine.ts 的源码可以看到引擎在构造时会把backoff归并为一个HumanDuration[]默认值序列为this.backoff options.backoff ?? [ // 默认退避序列 ];当某次 burst 抛错时IncrementalIngestionEngine.ts引擎会按失败次数Math.min(backoff.length - 1, attempts)取出对应的退避时长换算为毫秒后调度下一次重试并在日志中记录Ingestion ... threw an error ... will backoff for ...。这也解释了为什么backoff数组顺序即退避阶梯索引越靠后等待越久。四、Kubernetes 系列kubernetes/client-node 升级与 CVE 缓解本次版本中backstage/plugin-kubernetes、backstage/plugin-kubernetes-backend、backstage/plugin-kubernetes-common、backstage/plugin-kubernetes-node、backstage/plugin-kubernetes-react五个包同步执行了提交71b8704的 Minor 变更将kubernetes/client-node从 1.0.0-rc 系列的早期版本升级到1.0.0-rc7。变更说明明确指出升级目的是缓解与request和tough-cookie两个传递依赖相关的 CVE。这意味着如果你的安全扫描或漏洞治理流程会检测request/tough-cookie相关的告警升级到该版本后 Kubernetes 插件的相关告警应得到消解kubernetes/client-node处于 rc 阶段升级本身是 patch 级兼容但建议升级后在真实集群上回归一遍 Kubernetes 插件的集群列表、工作负载详情与日志查看功能。需要说明的是当前仓库中该目录插件源码已经演进到更新的版本例如plugins/kubernetes-react下的文件已与 v1.33.0-next.1 时的依赖清单不同本文所有版本号均以关联文档 docs/releases/v1.33.0-next.1-changelog.md 为准。五、Scaffolderisolated-vm v5 升级与 Bitbucket PR 修复5.1 isolated-vm 从 v4 升级到 v5放弃 Node.js 16backstage/plugin-scaffolder-backend1.27.0-next.1的 Minor 变更提交0587633将isolated-vm从 v4 升级到 v5。isolated-vm是 Scaffolder 用于在隔离沙箱中执行模板自定义脚本如javascript/jsonata等步骤中的 JS 逻辑的核心依赖因此这是一次影响运行时的升级Node.js 16 不再受支持升级后 Scaffolder 后端的最低 Node 版本要求随之提高。如果生产环境仍运行在 Node 16 上需要先升级 Node.js 再升级本包。在仓库根目录的 package.json 及 plugins/scaffolder-backend/package.json 中可以查看当前脚手架的 Node 版本约定与依赖组织方式。5.2 Bitbucket Pull Request 动作重复建分支修复backstage/plugin-scaffolder-backend-module-bitbucket-cloud与backstage/plugin-scaffolder-backend-module-bitbucket-server均升级到0.2.2-next.1修复了public:bitbucket{Cloud,Server}:pull-request动作重复创建分支的问题提交9cf827c。此前使用这两个动作时如果目标分支在创建 PR 时已经存在会报出如下错误AlreadyExistsError: Failed to create branch at create-test because it already exists.修复后动作在执行前会先检测分支是否已存在避免重复创建导致的失败。若你正在使用 Bitbucket Cloud / Server 的 PR 模板动作升级即可消除该报错该动作位于 plugins/scaffolder-backend-module-bitbucket-cloud 与 plugins/scaffolder-backend-module-bitbucket-server 两个目录下。六、其余值得关注的变更除了上述四大主线本版本还包含若干影响面较小但值得留意的修复repo-tools 新增generate-patch命令dde85eebackstage/repo-tools0.11.0-next.1新增generate-patch命令可基于源 workspace 的当前改动生成补丁供目标 workspace 安装使用。这为跨 workspace 共享本地改动提供了便捷工具具体实现可参考 packages/repo-tools。theme 避免 MUI 顶层导入ea75c37backstage/theme0.6.1-next.0做了内部重构避免从 MUI 顶层路径导入属于打包体积与模块解析层面的优化API 不变。TechDocs 配置 Schema 修复90246a9backstage/plugin-techdocs1.11.1-next.1修复了 custom elements sanitizer 的配置 schema相关配置校验行为更加准确见 plugins/techdocs。Google 认证模块配置可见性修复b833660backstage/plugin-auth-backend-module-google-provider0.2.2-next.1修复了部分配置在前端代码中的可见性声明涉及auth.providers.google相关配置项的visibility属性参见 plugins/auth-backend-module-google-provider。依赖升级del升级到^8.0.0提交6266ed3types/node等开发依赖统一提升702f41d同时backstage/create-app的 engines 已支持 Node 20 或 22。七、升级检查清单综合上述变更从 v1.33.0-next.0或更早版本升级到 v1.33.0-next.1 时建议按以下清单逐项核对CI 脚本将--successCache改写为--success-cache确认 CI 工作区路径一致性不再是缓存命中的前提。增量摄取提供者排查IncrementalEntityProviderOptions及IterationEngineOptions中的时长写法把quarter改为{ months: 3 }、单数名词改为复数。Node 版本确认运行 Scaffolder 后端的 Node.js 版本满足isolated-vmv5 的要求不再支持 Node 16。Kubernetes 插件升级后重新回归集群连接与资源查看确认kubernetes/client-node1.0.0-rc7在你的集群版本上工作正常。Bitbucket PR 模板若使用public:bitbucketCloud:pull-request/public:bitbucketServer:pull-request升级后重跑相关模板任务验证分支创建逻辑。由于本文所依据的发布说明为历史预览版本记录当前仓库源码已在此版本之上继续演进实际升级时请以仓库根目录 docs/releases 下的最新发布说明为准。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.33.0-next.1 发布解析：CLI 测试性能优化、增量摄取 API 演进与依赖安全升级全指南
Backstage v1.33.0-next.1 发布解析CLI 测试性能优化、增量摄取 API 演进与依赖安全升级全指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文以仓库内 docs/releases/v1.33.0-next.1-changelog.md 为骨架结合packages/cli、plugins/catalog-backend-module-incremental-ingestion、plugins/kubernetes*、plugins/scaffolder-backend等模块的当前源码系统解读本次预发布版本next.1中的 Minor 变更与关键 Patch 修复。读完本文你将掌握repo testwatch 模式的性能优化原理与--successCache缓存修复细节、incremental-ingestion从luxon迁移到HumanDuration的 API 迁移清单以及 Kubernetes 客户端升级与 Scaffolder 沙箱升级带来的兼容性影响从而判断升级到该版本时哪些代码需要改动、哪些 CI 脚本需要调整。一、版本总览本次变更波及哪些模块v1.33.0-next.1 是 v1.33.0 的第二个预览版本next.1表示在next.0基础上叠加的补丁集其变更分布在三大主线主线涉及模块变更性质CLI 工具链backstage/cli0.29.0-next.1Minorrepo testwatch 模式过滤未使用包Patch--successCache三处修复目录增量摄取backstage/plugin-catalog-backend-module-incremental-ingestion0.6.0-next.1Minor公开 API 全面改用HumanDuration依赖安全与兼容性plugin-kubernetes*、plugin-scaffolder-backend及其 moduleMinorKubernetes 客户端升级、isolated-vmv5 升级其余大量包backend-*、auth-backend、catalog-backend、search-*、techdocs-*等在本版本中主要以依赖联动Updated dependencies方式跟随升级属于常规的版本同步没有独立的 API 变化。下面按主题逐项深入。二、backstage/clirepo test的性能优化与--successCache修复2.1 Minor 变更watch 模式下自动过滤未使用包本次 CLI 最重要的功能改进来自提交6819f8crepo test命令在 watch 模式下新增了一项优化——当所有提供的 filter 都是从仓库根目录指向的具体路径时CLI 会过滤掉未使用的包只对相关的包执行测试监听。典型场景是在大型 monorepo workspace 中从根目录单独运行某个测试yarn test packages/app/src/App.test.tsx在此之前即使你只指定了一个测试文件CLI 也需要对整个 workspace 中的所有包进行监听和编排优化之后由于 filter 是明确的仓库根路径packages/app/...CLI 可以推断出只有packages/app这一个包真正参与本次测试从而跳过其他包显著缩短启动和增量重跑的耗时。该命令的完整参数形态可以在 packages/cli/cli-report.md 中查到repo test与repo lint均支持--success-cache与--success-cache-dir string参数。2.2 Patch 修复--successCache的缓存正确性问题--successCache现已推荐使用 kebab-case 写法--success-cache旧写法仍可用但会打印弃用警告详见 packages/cli/CHANGELOG.md用于在测试或 lint 成功后复用结果、跳过重复执行。本版本针对它做了三处修复直接影响 CI 的缓存命中率与正确性缓存键不应包含 workspace 路径4046d53此前生成的缓存键会包含 workspace 路径导致在不同构建环境之间例如 CI 中 checkout 路径不一致、或本地与 CI 路径不同缓存永远无法命中。修复后缓存键不再依赖工作区绝对路径。错误的包目录 tree hash6b2888crepo test使用--successCache时偶尔会用错误的包目录的 tree hash 来生成缓存键导致缓存键错乱。本次修正为使用正确包目录的哈希。lint 缓存未遵守.eslintignore4046d53repo lint的缓存键此前没有正确忽略.eslintignore中标记为忽略的文件修复后这些文件不再参与缓存键计算。升级提示如果 CI 或本地脚本仍在使用 camelCase 的--successCache建议按 packages/cli/CHANGELOG.md 中的说明迁移为--success-cache避免未来版本移除旧写法时构建失败。三、incremental-ingestion公开 API 全面迁移到 HumanDuration3.1 变更动机与影响面backstage/plugin-catalog-backend-module-incremental-ingestion0.6.0-next.1的 Minor 变更提交6cf91c5将公开 API 中所有与时序相关的类型从luxon的Duration替换为backstage/types导出的HumanDuration。二者在语义上基本兼容但存在两处需要注意的写法差异。这一迁移在当前仓库源码中已经落地。在 plugins/catalog-backend-module-incremental-ingestion/src/types.ts 中IncrementalEntityProviderOptions的所有时长字段均为HumanDurationimport { HumanDuration } from backstage/types; export interface IncrementalEntityProviderOptions { /** 两次摄入 burst 之间的等待时间 */ burstInterval: HumanDuration; /** 每个 burst 持续摄取的时长上限 */ burstLength: HumanDuration; /** 一次成功摄取后进入休息状态的时长 */ restLength: HumanDuration; /** 出错后的退避时长序列例如 [{ minutes: 1 }, { minutes: 5 }, { minutes: 30 }, { hours: 3 }] */ backoff?: HumanDuration[]; rejectRemovalsAbovePercentage?: number; rejectEmptySourceCollections?: boolean; }对应的IterationEngineOptionstypes.ts同样使用HumanDuration类型的restLength、burstLength与backoff。3.2 迁移注意事项根据变更说明升级时需要检查以下两类写法季度调度如果此前使用quarter/quartersluxon 支持的季度单位请改用{ months: 3 }// 旧写法luxon Duration // schedule: { quarter: 1 } // 新写法HumanDuration backoff: [{ months: 3 }]单数名词改复数HumanDuration只接受复数键此前形如year: 1、minute: 5的写法要改为years: 1、minutes: 5// 旧写法 // restLength: { hour: 1 } // 新写法 restLength: { hours: 1 }3.3 引擎侧如何消费这些时长从 plugins/catalog-backend-module-incremental-ingestion/src/engine/IncrementalIngestionEngine.ts 的源码可以看到引擎在构造时会把backoff归并为一个HumanDuration[]默认值序列为this.backoff options.backoff ?? [ // 默认退避序列 ];当某次 burst 抛错时IncrementalIngestionEngine.ts引擎会按失败次数Math.min(backoff.length - 1, attempts)取出对应的退避时长换算为毫秒后调度下一次重试并在日志中记录Ingestion ... threw an error ... will backoff for ...。这也解释了为什么backoff数组顺序即退避阶梯索引越靠后等待越久。四、Kubernetes 系列kubernetes/client-node 升级与 CVE 缓解本次版本中backstage/plugin-kubernetes、backstage/plugin-kubernetes-backend、backstage/plugin-kubernetes-common、backstage/plugin-kubernetes-node、backstage/plugin-kubernetes-react五个包同步执行了提交71b8704的 Minor 变更将kubernetes/client-node从 1.0.0-rc 系列的早期版本升级到1.0.0-rc7。变更说明明确指出升级目的是缓解与request和tough-cookie两个传递依赖相关的 CVE。这意味着如果你的安全扫描或漏洞治理流程会检测request/tough-cookie相关的告警升级到该版本后 Kubernetes 插件的相关告警应得到消解kubernetes/client-node处于 rc 阶段升级本身是 patch 级兼容但建议升级后在真实集群上回归一遍 Kubernetes 插件的集群列表、工作负载详情与日志查看功能。需要说明的是当前仓库中该目录插件源码已经演进到更新的版本例如plugins/kubernetes-react下的文件已与 v1.33.0-next.1 时的依赖清单不同本文所有版本号均以关联文档 docs/releases/v1.33.0-next.1-changelog.md 为准。五、Scaffolderisolated-vm v5 升级与 Bitbucket PR 修复5.1 isolated-vm 从 v4 升级到 v5放弃 Node.js 16backstage/plugin-scaffolder-backend1.27.0-next.1的 Minor 变更提交0587633将isolated-vm从 v4 升级到 v5。isolated-vm是 Scaffolder 用于在隔离沙箱中执行模板自定义脚本如javascript/jsonata等步骤中的 JS 逻辑的核心依赖因此这是一次影响运行时的升级Node.js 16 不再受支持升级后 Scaffolder 后端的最低 Node 版本要求随之提高。如果生产环境仍运行在 Node 16 上需要先升级 Node.js 再升级本包。在仓库根目录的 package.json 及 plugins/scaffolder-backend/package.json 中可以查看当前脚手架的 Node 版本约定与依赖组织方式。5.2 Bitbucket Pull Request 动作重复建分支修复backstage/plugin-scaffolder-backend-module-bitbucket-cloud与backstage/plugin-scaffolder-backend-module-bitbucket-server均升级到0.2.2-next.1修复了public:bitbucket{Cloud,Server}:pull-request动作重复创建分支的问题提交9cf827c。此前使用这两个动作时如果目标分支在创建 PR 时已经存在会报出如下错误AlreadyExistsError: Failed to create branch at create-test because it already exists.修复后动作在执行前会先检测分支是否已存在避免重复创建导致的失败。若你正在使用 Bitbucket Cloud / Server 的 PR 模板动作升级即可消除该报错该动作位于 plugins/scaffolder-backend-module-bitbucket-cloud 与 plugins/scaffolder-backend-module-bitbucket-server 两个目录下。六、其余值得关注的变更除了上述四大主线本版本还包含若干影响面较小但值得留意的修复repo-tools 新增generate-patch命令dde85eebackstage/repo-tools0.11.0-next.1新增generate-patch命令可基于源 workspace 的当前改动生成补丁供目标 workspace 安装使用。这为跨 workspace 共享本地改动提供了便捷工具具体实现可参考 packages/repo-tools。theme 避免 MUI 顶层导入ea75c37backstage/theme0.6.1-next.0做了内部重构避免从 MUI 顶层路径导入属于打包体积与模块解析层面的优化API 不变。TechDocs 配置 Schema 修复90246a9backstage/plugin-techdocs1.11.1-next.1修复了 custom elements sanitizer 的配置 schema相关配置校验行为更加准确见 plugins/techdocs。Google 认证模块配置可见性修复b833660backstage/plugin-auth-backend-module-google-provider0.2.2-next.1修复了部分配置在前端代码中的可见性声明涉及auth.providers.google相关配置项的visibility属性参见 plugins/auth-backend-module-google-provider。依赖升级del升级到^8.0.0提交6266ed3types/node等开发依赖统一提升702f41d同时backstage/create-app的 engines 已支持 Node 20 或 22。七、升级检查清单综合上述变更从 v1.33.0-next.0或更早版本升级到 v1.33.0-next.1 时建议按以下清单逐项核对CI 脚本将--successCache改写为--success-cache确认 CI 工作区路径一致性不再是缓存命中的前提。增量摄取提供者排查IncrementalEntityProviderOptions及IterationEngineOptions中的时长写法把quarter改为{ months: 3 }、单数名词改为复数。Node 版本确认运行 Scaffolder 后端的 Node.js 版本满足isolated-vmv5 的要求不再支持 Node 16。Kubernetes 插件升级后重新回归集群连接与资源查看确认kubernetes/client-node1.0.0-rc7在你的集群版本上工作正常。Bitbucket PR 模板若使用public:bitbucketCloud:pull-request/public:bitbucketServer:pull-request升级后重跑相关模板任务验证分支创建逻辑。由于本文所依据的发布说明为历史预览版本记录当前仓库源码已在此版本之上继续演进实际升级时请以仓库根目录 docs/releases 下的最新发布说明为准。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考