Backstage v1.33.0 版本升级完全指南：破坏性变更、CLI 提速与目录性能优化全解析

Backstage v1.33.0 版本升级完全指南破坏性变更、CLI 提速与目录性能优化全解析【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库的 v1.33.0 变更日志 编写系统梳理该版本中涉及 CLI、后端动态插件、Catalog 目录、认证体系、Scaffolder 等核心模块的关键变更包括必须处理的破坏性变更如LEGACY_BACKEND_START移除、scaffoldercheckpointAPI 重构、值得关注的新能力如repo test大幅提速、OpenAPI 服务端代码生成并结合仓库源码给出实现层面的佐证。读完本文你将能评估 v1.33.0 对自身工程的影响并据此规划一次低风险、可验证的升级。升级前的准备v1.33.0 是 Backstage 在 v1.30 之后持续推进新后端系统 新前端系统收敛的重要版本包含多个标记为BREAKING的变更。官方提供了 Upgrade Helper 辅助工具它可以根据你的当前版本自动生成升级命令与差异清单该链接已内置于变更日志首行升级时可直接访问。建议按以下顺序推进升级先阅读本文破坏性变更章节逐条核对是否命中你的工程配置使用 Upgrade Helper 生成版本提升命令升级后重点回归验证后端启动尤其是使用动态插件的部署、scaffolder 任务创建流程、Catalog 的读取与刷新、前端构建与测试命令。必须处理的破坏性变更1. 后端动态插件加载器logger 选项统一收拢到logger键下backstage/backend-dynamic-feature-service0.5.0对dynamicPluginsFeatureLoader的选项结构做了一次破坏性调整原先分散的根日志器行为配置transports、level、format现在必须统一放在一个logger选项下且该选项是一个接收可选Config参数、返回 logger 选项的函数。变更日志给出了两条设计动机提供 logger 选项时可能需要读取当前的Config如从配置文件中读取日志级别当未来引入根级审计服务auditing service时审计器也需要一组同名但语义不同的选项集中到logger下可以避免命名冲突。因此如果你的工程通过dynamicPluginsFeatureLoader({ ... })自定义过日志传输、级别或格式升级后必须按如下结构迁移dynamicPluginsFeatureLoader({ logger: (config?: Config) ({ level: info, format: ..., transports: ..., }), });2. CLI 移除LEGACY_BACKEND_START与新后端开发入口收窄backstage/cli0.29.0移除了LEGACY_BACKEND_START环境变量标志同时不再支持把src/run.ts作为开发入口。这意味着所有仍然通过旧标志启动后端的方式都将失效后端开发启动统一收敛到新后端系统的index.ts入口模式即createBackend()的写法。如果你的后端还存在src/run.ts或依赖LEGACY_BACKEND_START必须在升级时一并清理否则yarn dev或yarn start:backend将无法启动。3. ESLint 默认忽略生成的源码目录backstage/cli0.29.0的 ESLint 配置现在会忽略src/**/generated/**/*.ts下所有自动生成的代码。这项改动对多数工程是透明的生成的代码本就不应手工 lint但如果你在生成目录中放过需要检查的手写文件需要调整目录规划。4. AWS ALB 认证fullProfile不再自动转小写backstage/plugin-auth-backend0.24.0与backstage/plugin-auth-backend-module-aws-alb-provider0.3.0同步引入破坏性变更AWS ALB 的fullProfile中的 username/email 不再被自动转换为小写以保证用户标识的唯一处理。影响如果你的登录解析sign-in resolver或 profile 变换逻辑曾依赖ALB profile 一定是小写这一行为例如按小写用户名在 Catalog 中匹配user:default/name升级后必须显式配置自定义 sign-in resolver 或 profile transform 来执行大小写归一化否则可能出现用户匹配不到实体、登录失败的问题。5. Scaffoldercheckpoint方法改为对象参数backstage/plugin-scaffolder-backend1.27.0与backstage/plugin-scaffolder-node0.6.0对实验性的checkpointAPI 做了破坏性重构从多个位置参数改为单个对象参数并且允许 handler 返回void。// v1.33.0 之后的写法 await ctx.checkpoint({ key: repo.create, fn: () ockokit.repo.create({ ... }), });在源码层面checkpoint 的能力由plugins/scaffolder-node/src/tasks/types.ts中的UpdateTaskCheckpointOptionsupdateCheckpoint方法承载它定义在任务上下文ActionContext中供自定义 action 在长任务执行期间登记检查点、配合任务的恢复/幂等机制使用。如果你编写的自定义 action 使用旧式ctx.checkpoint(key, fn)调用必须更新为对象参数形式。CLI 工程体验测试提速与新增命令repo test监视模式的包过滤优化backstage/cli0.29.0为repo test增加了一项优化在监视watch模式下如果所有过滤器都是指向仓库根目录的路径则会过滤掉未被使用的包。对于大型 monorepo从仓库根目录运行单个测试的启动速度会显著提升yarn test packages/app/src/App.test.tsx新增rejectFrontendNetworkRequestsJest 配置CLI 新增了一个只能设置在根package.json的jest字段中的标志用于在前端或公共包测试中拒绝一切形式的网络请求且不能被单个包配置覆盖{ jest: { rejectFrontendNetworkRequests: true } }这对依赖真实网络但在测试环境中不允许出网的 CI 场景很有价值——开启后任何测试中发起的网络请求都会直接失败从而尽早暴露隐式的网络依赖。打包与链接相关命令演进build-workspace命令新增--alwaysPack替代已隐藏的--alwaysYarnPack前端构建新增--link workspace-path选项可在运行时覆盖模块解析以链接外部 workspace同时移除了旧的 Webpack linked workspace 解析插件该插件服务于已被 Yarn 废弃的 workspace 链接方式package lint支持--max-warnings -1可将所有警告视为错误repo test/repo lint的--successCache选项改为增量存储旧条目保留一周后自动清理且缓存键不再包含 workspace 路径修复了不同构建环境路径不一致导致缓存失效的问题package start的--link标志会去重react-router与react-router-dom。实验性 Rspack 构建的配置注入方式变更当使用实验性 Rspack 标志时应用构建与 dev server 改为通过index.html中的script typebackstage.io/config.../script标签注入配置而不再依赖process.env.APP_CONFIG后者将变为空数组。这要求应用使用的 config loader 至少来自 Backstage 1.31 版本若你复制过defaultConfigLoader的实现需要更新为能读取backstage.io/config类型 script 标签的新实现。此外 CLI 还补齐了对.webp图片文件的构建支持并把 Webpack 依赖范围提升到^5.94.0旧版本与当前配置不兼容。Catalog 目录读取路径性能优化backstage/plugin-catalog-backend1.28.0是本版本中值得重点关注的性能优化版本在final_entities表新增entity_ref列将实体引用从refresh_state移出读取路径使查询最终实体时不必再关联refresh_state。从源码结构看这一列已被plugins/catalog-backend/src/database/DefaultCatalogDatabase.ts中的查询逻辑实际使用如按entity_ref定位实体。清理冗余数据库索引包括final_entities_entity_id_idx与主键重叠refresh_state_entity_id_idx与主键重叠refresh_state_entity_ref_idx与唯一索引重叠search_key_idx、search_value_idx已被复合索引search_key_value_idx取代。这些索引的移除不会对终端用户造成负面影响反而因索引维护开销降低而可能带来性能提升。修复了若干查询问题如仅关系目标变化时实体未标记重新缝合restitching、前端按spec.profile.displayName搜索实体时文本过滤字段未正确应用到数据库查询导致结果为空等。配置层增强duration 支持 ISO 与毫秒字符串backstage/config1.3.0的readDurationFromConfig现在同时支持 ISO 时长格式如PT1M、P2DT6H与毫秒格式如1d、2 seconds进一步方便最终用户以习惯的文本形式填写时长。源码实现位于 packages/config/src/readDurationFromConfig.ts其解析策略如下值以P开头 → 走parseIsoDuration否则 → 走parseMsDuration依赖ms库支持1d、2 seconds等写法也可以直接传对象形式如{ days: 2, hours: 6 }键必须使用复数形式years、months、weeks、days、hours、minutes、seconds、milliseconds。配套测试位于 packages/config/src/readDurationFromConfig.test.ts覆盖了字符串、ISO、对象三种格式及非法值的报错行为。由于readDurationFromConfig被 auth-backend、scaffolder-backend、events 后端等多个模块广泛使用这一增强意味着整个生态的时长配置都获得了更宽松的书写体验。后端 API 基础设施OpenAPI 服务端代码生成本版本围绕 OpenAPI 生成能力做了一次系统性补强backstage/backend-openapi-utils0.3.0新增createValidatedOpenApiRouterFromGeneratedEndpointMap函数可基于backstage-cli package schema openapi generate --server生成的静态服务端代码创建类型安全的 express routerbackstage/repo-tools0.11.0的backstage-repo-tools package schema openapi generate --server现在会为 OpenAPI schema 中所有请求/响应对象生成完整的 TS 接口修复了递归 schema 的边界情况并使客户端与服务端生成类型保持一致同时新增--watch模式方便本地编写 schema 时实时生成backstage/repo-tools还新增了generate-patch命令用于为源 workspace 的当前改动生成补丁以安装到目标 workspacegenerate-patch在找不到匹配描述符时会回退为总是添加resolutions条目。从变更日志看plugin-catalog-backend、plugin-search-backend、plugin-events-backend等多个后端模块已内部切换到这套新的生成服务端类型属于基础设施先行落地的典型模式。认证与事件基础设施的健壮性修复大 Cookie 自动分割refresh token 防丢失backstage/plugin-auth-node0.5.4修复了一个隐蔽问题浏览器会静默丢弃超过 4KB 的 Cookie这对 refresh token 这类大 Cookie 非常致命。该版本引入了 Cookie 分割逻辑并附带相应测试。从源码结构看分割实现位于 plugins/auth-node/src/oauth/OAuthCookieManager.tscreateOAuthRouteHandlers.test.ts中以my-provider-refresh-token-n的分片命名方式验证了写入、刷新、替换与清理全流程当 token 超过阈值时会被拆分为多个分片 Cookie并支持在刷新时对旧分片做有序清理保证认证过程完整性。事件总线的重连与配置控制backstage/plugin-events-node0.4.5修复了订阅事件时一次失败就放弃的问题现在订阅方法会驱动后台轮询循环持续尝试连接事件后端即使初始请求失败。同时新增events.useEventBus配置允许显式控制行为never完全禁用对事件后端的 API 调用always永不禁止调用。backstage/plugin-events-backend0.3.16也修复了events.useEventBus配置未能传播到DefaultEventsService的问题并在RequestDetails中加入原始请求体信息用于正确校验 GitHub 等 webhook 事件的签名。AWS SDK 凭据链支持指定 regionbackstage/integration-aws-node0.1.13的getDefaultCredentialsChain函数现在接受并应用region参数避免未指定 region 时默认回退到us-east-1——这对多 region 部署的 AWS 集成如 S3 存储、EKS 集群是重要的行为修正。插件与模块速览Notifications 通知plugin-notifications0.4.0根据用户反馈改进了 View 过滤标签措辞、Created after 更名为 Sent out、标题加粗以区分描述、菜单项显示未读数量前后端同步新增用户级通知设置支持97ba58f同时作用于plugin-notifications-backend与-common。相关文档见 docs/notifications。Kubernetes 系列plugin-kubernetes0.12.0等一组包将kubernetes/client-node升级到1.0.0-rc7以缓解request与tough-cookie相关 CVEplugin-kubernetes-react0.5.0新增 Pod 删除功能plugin-kubernetes-backend适配自定义集群 authProvider 的config.d.ts。Scaffolder新增权限scaffolder.template.management控制模板管理功能访问新增fs:readdiraction 用于列出 workspace 当前内容修复public:bitbucket{Cloud,Server}:pull-request重复创建分支导致AlreadyExistsError的问题GitLab 相关 action 改进了错误信息isolated-vm从 v4 升级到 v5不再支持 Node.js v16dry-run 框架的templateInfo中现包含templateMetaData。api-docsDefaultApiExplorerPage支持分页API 定义 schema 样式改用主题值以便主题覆盖生效。GitLab Catalog 模块plugin-catalog-backend-module-gitlab0.5.0新增includeArchivedRepos配置允许把已归档项目纳入同步。LDAP 模块plugin-catalog-backend-module-ldap0.10.0新增 Google LDAP 供应商支持并增加dnCaseSensitive标志以适配混合大小写属性的 LDAP 服务器。增量摄取plugin-catalog-backend-module-incremental-ingestion0.6.0将公开 API 中的luxon类型统一替换为HumanDuration季度调度可用{ months: 3 }代替单数单位需改复数。events 与 signalsplugin-signals-backend0.2.3支持客户端连接到多实例 signals 后端之一的横向扩展部署plugin-events-backend会在超过最大存活窗口后清理事件订阅。core-componentsSupportButton在未配置 support 配置时自动隐藏新增mockBreakpoint测试工具可在测试中按断点模拟媒体查询并动态切换活动断点。typesbackstage/types1.2.0引入createDeferred与DeferredPromise并被 scaffolder-backend、incremental-ingestion 等模块内部采用。依赖基线速查本版本中多个关键依赖同步升级可据此核对版本一致性backstage/cli0.29.0vite ^5、webpack ^5.94.0、css-loader ^7、ts-morph ^24、module-federation/enhanced ^0.7backstage/config1.3.0、backstage/types1.2.0、backstage/backend-plugin-api1.0.2backstage/plugin-catalog-backend1.28.0、backstage/plugin-catalog-node1.14.0backstage/plugin-auth-backend0.24.0、backstage/plugin-scaffolder-backend1.27.0多个包内部将uuid升级到 v11并持续移除对backstage/backend-common的依赖继续向backend-common 解耦演进。升级检查清单升级到 v1.33.0 前建议逐项确认后端是否使用dynamicPluginsFeatureLoader并自定义了日志选项需迁移到logger函数形式是否残留LEGACY_BACKEND_START或src/run.ts必须删除是否依赖 AWS ALB 的自动小写化 profile需补自定义 sign-in resolver自定义 scaffold action 是否使用旧式checkpoint需改为对象参数CLI 是否使用了隐藏的--alwaysYarnPack改用--alwaysPack、process.env.APP_CONFIG注入的旧配置加载方式改用 script 标签形式若使用 Node.js 16 运行 scaffold 任务需升级运行时isolated-vmv5 不再支持。本文所有结论均以仓库 docs/releases/v1.33.0-changelog.md 为事实来源并交叉参考了 readDurationFromConfig 实现、Cookie 分割相关实现与测试、Catalog 数据库实现 与 scaffolder 任务类型定义 等源码。升级过程中如遇具体模块的迁移细节可继续查阅 docs 下的对应功能文档。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考