Backstage v1.40.0 版本解读Scaffolder 2.0 迁移指南、后端限流与前端 Blueprint 生态演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章围绕 Backstage v1.40.0 的官方变更日志docs/releases/v1.40.0-changelog.md展开聚焦本版本最核心的三条主线plugin-scaffolder-backend迈入 2.0 大版本伴随多组破坏性变更与 Zod Schema 迁移、backend-defaults新增可配置的请求限流中间件、以及新前端系统下EntityIconLinkBlueprint与插件info元数据机制的落地。读完本文你将掌握如何迁移到 Scaffolder 2.0、如何在app-config.yaml中启用全局/插件级限流、如何自定义 Catalog About 卡片图标链接并了解新引入的 Kafka 事件模块与 MCP Actions 后端等增量能力。一、版本概览与升级路径v1.40.0 是一个横跨前后端、CLI 与多个插件的大版本其中值得重点关注的包有包名新版本变化级别backstage/plugin-scaffolder-backend2.0.0Major多组破坏性变更backstage/backend-defaults0.11.0Minor新增限流、Actions 服务默认实现backstage/backend-plugin-api1.4.0Minor新增实验性 actions 服务backstage/plugin-catalog-react1.19.0Minor新增EntityIconLinkBlueprintbackstage/plugin-catalog1.31.0MinorAbout 卡片图标链接扩展backstage/plugin-events-backend-module-kafka0.1.0全新模块backstage/plugin-mcp-actions-backend0.1.0全新后端backstage/cli0.33.0Minor模块化 CLI 入口转正升级时建议使用官方 Upgrade Helper 工具定位到1.40.0目标版本逐项核对本文列出的破坏性变更对于自建 Backstage 应用执行backstage-cli versions:bump前请先确认packages/backend与packages/app中相关依赖的锁定版本与变更日志中的依赖升级清单例如backstage/backend-defaults0.11.0、backstage/plugin-scaffolder-node0.9.0保持一致。二、Scaffolder Backend 2.0.0破坏性变更全解与迁移步骤backstage/plugin-scaffolder-backend在此版本发布 2.0.0包含了四组BREAKING CHANGES和一批弃用声明是本次升级工作量最大的部分。仓库中对应的实现位于 plugins/scaffolder-backend相关的类型与工具函数则集中在 plugins/scaffolder-node。2.1 清理长期存在的重导出re-exports第一组破坏性变更移除了从scaffolder-backend插件包中转手导出的一批函数。它们已被分拆到各自的集成模块中迁移映射如下原导入来源已移除迁移后的正确导入来源createPublishAzureActionbackstage/plugin-scaffolder-backend-module-azurecreatePublishBitbucketCloudActionbackstage/plugin-scaffolder-backend-module-bitbucket-cloudcreatePublishBitbucketServerAction、createPublishBitbucketServerPullRequestActionbackstage/plugin-scaffolder-backend-module-bitbucket-servercreatePublishBitbucketActionbackstage/plugin-scaffolder-backend-module-bitbucketcreatePublishGerritAction、createPublishGerritReviewActionbackstage/plugin-scaffolder-backend-module-gerritcreateGithubActionsDispatchAction、createGithubDeployKeyAction、createGithubEnvironmentAction、createGithubIssuesLabelAction、CreateGithubPullRequestActionOptions、createGithubRepoCreateAction、createGithubRepoPushAction、createGithubWebhookAction、createPublishGithubActionbackstage/plugin-scaffolder-backend-module-githubcreatePublishGitlabActionbackstage/plugin-scaffolder-backend-module-gitlabActionContext、createTemplateAction、executeShellCommand、ExecuteShellCommandOptions、fetchContents、TaskSecrets、TemplateActionbackstage/plugin-scaffolder-node此外还有两组类型与实现需要迁移SerializedTask、SerializedTaskEvent、TaskBroker、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskContext、TaskEventType、TaskStatus、TemplateFilter、TemplateGlobal应从backstage/plugin-scaffolder-node导入ScaffolderEntitiesProcessor应改为从backstage/plugin-catalog-backend-module-scaffolder-entity-model导入该处理器用于将 Scaffolder 生成的实体注册进 Catalog相关实体模型定义见 plugins/catalog-backend-module-scaffolder-entity-model。与此同时fetch:template动作中已弃用的copyWithoutRender选项被彻底移除请统一改名为copyWithoutTemplating。2.2/alpha导出移除与旧后端系统createRouter退役第二组破坏性变更涉及两件事backstage/plugin-scaffolder-backend/alpha不再导出插件本身请直接使用import(backstage/plugin-scaffolder-backend)旧后端系统使用的createRouter函数及其RouterOptions类型被移除。这意味着仍在用旧后端系统createRouterRouterOptions方式组装 Scaffolder 的应用必须迁移到新后端系统createBackend 插件实例化否则升级后无法编译。2.3createBuiltinActions移除与 Catalog 动作的依赖重构第三组破坏性变更createBuiltinActions方法被移除。它在旧后端系统中仅用于再次传入默认动作列表而新后端系统默认会合并所有动作因此不再需要createCatalogRegisterAction与createFetchCatalogEntityAction不再依赖AuthService且参数由CatalogClient换成CatalogService。如果你是通过scaffolderActionsExtensionPoint自定义覆盖默认动作并因此遇到类型错误可参考下面的迁移写法源码层面与此对应的扩展点声明位于 plugins/scaffolder-node/src/alphaimport { catalogServiceRef } from backstage/plugin-catalog-node; import { scaffolderActionsExtensionPoint } from backstage/plugin-scaffolder-node/alpha; export const myModule createBackendModule({ pluginId: scaffolder, moduleId: test, register({ registerInit }) { registerInit({ deps: { scaffolder: scaffolderActionsExtensionPoint, catalog: catalogServiceRef, }, async init({ scaffolder, catalog }) { scaffolder.addActions( createCatalogRegisterAction({ catalog, }), createFetchCatalogEntityAction({ catalog, integrations, }), ); }, }); }, });无独有偶plugin-scaffolder-backend-module-github的createGithubEnvironmentAction也做了同样的依赖替换AuthService→CatalogService、CatalogClient→CatalogService迁移模式与此处完全一致。这一系列的改动表明Scaffolder 动作正在全面收敛到「通过CatalogService访问目录、通过scaffolderActionsExtensionPoint注册动作」的新范式。2.4 一大批 Task/TaskStore 相关类型弃用v1.40.0 同时声明了一批弃用类型包括CreateWorkerOptions、DatabaseTaskStore、DatabaseTaskStoreOptions、TaskManager、TaskStoreCreateTaskOptions、TaskStoreCreateTaskResult、TaskStoreEmitOptions、TaskStoreListEventsOptions、TaskStoreRecoverTaskOptions、TaskStoreShutDownTaskOptions。变更日志明确说明目前没有直接的替代路径这些类型将被移除并重新设计以在新后端系统中提供更优雅的 worker 定义方式。这意味着依赖这些内部类型做深度定制的团队需要提前关注后续版本的替代方案。2.5 动作 Schema 迁移到 Zod 原生写法backstage/plugin-scaffolder-node0.9.0将定义createTemplateAction输入/输出 Schema 的旧方式替换为原生的 Zod 方式。三阶段写法对照如下// 1) 最老的 JSON Schema 写法已不推荐 createTemplateAction{ repoUrl: string }, { repoOutput: string }({ id: test, schema: { input: { type: object required: [repoUrl] properties: { repoUrl: { type: string, description: repository url description } } } } }); // 2) 旧的 Zod 写法已不推荐 createTemplateAction({ id: test schema: { input: { repoUrl: z.string({ description: repository url description }) } } }) // 3) 新的 Zod 函数式写法推荐 createTemplateAction({ id: test, schema: { input: { repoUrl: z z.string({ description: repository url description }) } } }) // 或对更复杂的联合类型使用整体函数式写法 createTemplateAction({ id: test, schema: { input: z z.object({ repoUrl: z.string({ description: repository url description }) }) } })新写法把 schema 定义从值升级为函数使得 schema 可以延迟求值并复用zod的全部类型能力联合、交叉、条件等。scaffolder-backend-module-*系列模块azure、bitbucket、bitbucket-cloud、bitbucket-server、gerrit、gitea、gitlab、confluence-to-markdown、cookiecutter、rails、sentry、yeoman 等都在本版本统一迁移到新格式。重要附带变更logStream已从ActionsContext中彻底移除ctx.logger现在直接是LoggerService实现。没有官方替代方案若仍需使用 logStream官方建议自建一个写入ctx.logger的流。相应地plugin-scaffolder-node-test-utils的createMockActionContext也移除了logStream参数。2.6 模板each步骤支持 Secrets一个很实用的新能力each步骤中可以直接引用${{ secrets.xxx }}。例如each: [ { name: Service1, token: ${{ secrets.token1 }} }, { name: Service2, token: ${{ secrets.token2 }} }, ]这意味着在软件模板的循环步骤中按元素注入机密例如批量创建带凭据的服务不再需要外部拼接。另外本版本为 Scaffolder 补充了更多测试e92e481可参考 plugins/scaffolder-backend 中的测试目录了解动作行为的既有约定。三、backend-defaults 0.11.0全局与插件级请求限流backstage/backend-defaults0.11.0引入了基于express-rate-limit的限流中间件。其实现位于 packages/backend-defaults/src/lib/rateLimitMiddleware.ts并在 packages/backend-defaults/src/entrypoints/rootHttpRouter/rootHttpRouterServiceFactory.ts 的applyDefaults()中通过app.use(middleware.rateLimit())挂载到根 HTTP 路由。对应的单元测试见 packages/backend-defaults/src/lib/rateLimitMiddleware.test.ts 与 packages/backend-defaults/src/lib/RateLimitStoreFactory.test.ts。3.1 开启全局限流在app-config.yaml中增加如下配置即可开启backend: rateLimit: window: 6s incomingRequestLimit: 100window时间窗口支持时长字符串如6s源码内部通过readDurationFromConfig解析并转为毫秒incomingRequestLimit窗口内允许的最大请求数超限返回429。从源码看该中间件还支持以下可选配置项均可写入backend.rateLimit配置键作用ipAllowList放行 IP 列表默认值为[127.0.0.1, 0:0:0:0:0:0:0:1, ::1]本机地址默认放行skipSuccessfulRequests成功请求不计入限流skipFailedRequests失败请求不计入限流passOnStoreError存储层报错时是否放行容错此外限流键生成使用ipKeyGenerator对 IPv6 地址做规范化避免客户端通过轮换块内地址绕过限制validate.trustProxy被置为false在配置backend.trustProxy时需注意代理场景下的 IP 语义。3.2 插件级限流若只想限制某个插件的流量可关闭全局限流并为指定插件单独配置backend: rateLimit: global: false # 关闭全局限流 plugin: catalog: window: 6s incomingRequestLimit: 100global: false关闭全局兜底plugin.catalog则为 catalog 插件单独设定窗口与上限适合对高频但易被打爆的插件接口做精细化保护。3.3 自定义configure回调的兼容提醒变更日志特别提醒如果你在 root HTTP router 服务的configure回调中自定义配置且没有调用applyDefaults()需要把限流中间件以及其他默认中间件自行合入你的自定义配置否则升级后不会自动获得限流能力。建议直接调用applyDefaults()并在其后追加自定义逻辑。四、实验性 Actions 服务跨插件注册与调用动作backstage/backend-plugin-api1.4.0在/alpha导出中新增了两个实验性服务actionsRegistry注册分布式动作与actions调用动作并提供了默认实现c999c25落在backend-defaults中。典型用法import { actionsRegistryServiceRef, actionsServiceRef, } from backstage/backend-plugin-api/alpha; createBackendPlugin({ pluginId: test-plugin, register({ registerInit }) { registerInit({ deps: { actions: actionsServiceRef, actionsRegistry: actionsRegistryServiceRef, }, async init({ actions, actionsRegistry }) { actionsRegistry.register({ ..., }); await actions.invoke(...); }, }); }, });与之配套backstage/plugin-catalog-backend2.1.0已用ActionsRegistry实现了get-catalog-entity动作2e7adf0而backend-test-utils1.6.0也新增了对应的 mock 工具便于为动作编写单元测试import { actionsRegistryServiceMock } from backstage/backend-test-utils/alpha; const mockActionsRegistry actionsRegistryServiceMock(); const mockCatalog catalogServiceMock({ entities: [ ... ], }); createGetCatalogEntityAction({ catalog: mockCatalog, actionsRegistry: mockActionsRegistry, }); await expect( mockActionsRegistry.invoke({ id: test:get-catalog-entity, input: { name: test }, }), ).resolves.toEqual(...)五、Catalog 新前端系统EntityIconLinkBlueprint 与 About 卡片自定义backstage/plugin-catalog-react1.19.0引入EntityIconLinkBlueprint用于自定义 Catalog 实体页 About 卡片上的图标链接。其 Blueprint 定义位于 plugins/catalog-react/src/alpha/blueprints/EntityIconLinkBlueprint.tsx它挂载在entity-card:catalog/about扩展点的iconLinks输入上通过useProps数据 ref 输出图标链接属性并支持filter按实体过滤与label/title配置覆盖。5.1useProps返回的属性表useProps钩子返回以下属性将透传给图标链接组件名称描述类型默认值icon要显示的图标JSX.Element无label元素的标签string无title元素的标题string无disabled是否禁用该元素booleanfalsehref点击后跳转的 URLstring无onClick点击回调函数() void无5.2 使用示例import { EntityIconLinkBlueprint } from backstage/plugin-catalog-react/alpha; //... EntityIconLinkBlueprint.make({ name: my-icon-link, params: { useProps() { const { t } useTranslationRef(myIconLinkTranslationRef); return { label: t(myIconLink.label), icon: MyIconLinkIcon /, href: /my-plugin, }; }, }, });5.3 通过 app-config 覆盖 label 与 title还可以在app-config.yaml中用app.extensions覆盖默认图标链接的label与titleapp: extensions: - entity-icon-link:my-plugin/my-icon-link: config: label: My Custom Icon Link label注意当没有任何图标链接扩展被启用时About 卡片头部会被整体隐藏适合把链接独立展示在别的卡片上的场景。5.4 与 About 卡片默认链接的拆分backstage/plugin-catalog1.31.0中原本内置于 Catalog About 卡片链接的「Scaffolder 启动模板」与「TechDocs 阅读文档」两个图标链接被抽取出来改由Scaffolder与TechDocs插件分别提供。这意味着未安装 TechDocs/Scaffolder 插件时对应图标将不再出现如果你为这两个链接标题配置了非默认翻译需要改用 Scaffolder/TechDocs 各自的 translation reference翻译键保持不变aboutCard.viewTechdocs与aboutCard.launchTemplate。六、事件系统全新 Kafka 消费模块backstage/plugin-events-backend-module-kafka0.1.0是全新的事件后端模块位于 plugins/events-backend-module-kafka。它提供两个核心件KafkaConsumerClient基于 KafkaJS 建立消费连接KafkaConsumingEventPublisher订阅配置的 Kafka topic并把收到的消息发布到 Backstage 事件服务Event Service。从配置解析实现plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/config.ts可以看出它支持多实例配置events.modules.kafka.kafkaConsumingEventPublisher下的每个键视为一个 publisher每个 publisher 可配置topics数组其中kafka.groupId、kafka.topics、kafka.fromBeginning为消费组与订阅主题的核心参数kafka.sessionTimeout、kafka.rebalanceTimeout、kafka.heartbeatInterval、kafka.metadataMaxAge、kafka.maxBytesPerPartition、kafka.minBytes、kafka.maxBytes、kafka.maxWaitTime等可控制消费行为kafka.autoCommit默认true与kafka.pauseOnError默认false分别控制手动提交与出错暂停策略。模块测试见 plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/module.test.ts。同时backstage/plugin-events-backend-module-google-pubsub0.1.1新增了EventConsumingGooglePubSubPublisher用于把 Backstage 事件推送回 Google Pub/Sub。七、通知系统广播与保留期策略backstage/plugin-notifications-backend0.5.7带来两个值得注意的行为变化默认自动删除一年前的通知新增的定时任务每 24 小时运行一次删除超过 1 年的通知。可通过app-config.yaml配置保留期notifications: retention: 1y若将retention设为false则禁用自动清理。广播通知的用户字段通知 API 对广播broadcast通知始终返回user: null避免误导性地暴露发送者身份。此外通知与 Scaffolder 通知模块plugin-scaffolder-backend-module-notifications都支持了在某个来源origin内按 topic 开关通知的用户级能力1fb5f06。八、前端系统插件info元数据与useAppNodebackstage/frontend-plugin-api0.10.3为createFrontendPlugin增加了可选的info选项用于提供插件元数据加载器有两种形式// 方式一加载插件自身的 package.json推荐给发布到包仓库的插件 export default createFrontendPlugin({ pluginId: ..., info: { packageJson: () import(../package.json), }, }); // 方式二加载不透明 manifest仅限组织内使用禁止用于公开发布的插件 export default createFrontendPlugin({ pluginId: ..., info: { manifest: () import(../catalog-info.yaml), }, });packageJson指向插件包内的package.json适合任何在独立包中定义、尤其是发布到公共包仓库的插件manifest仅限在单一组织内部使用的插件可携带额外内部元数据默认 manifest 解析器能解析标准catalog-info.yaml格式及spec.owner等内置字段。配套能力包括frontend-app-api为createSpecializedApp支持了pluginInfoResolver选项并新增静态配置键app.pluginOverridesbackstage/plugin-catalog等插件实例新增info.packageJson选项同时新增了useAppNode钩子可从最近的ExtensionBoundary获取AppNode引用。本版本大量插件catalog、techdocs、home、org、notifications、search、signals、user-settings、api-docs、devtools、kubernetes、catalog-import、catalog-graph、app-visualizer 等都同步接入了info.packageJson。九、CLI 与工具链更新backstage/cli0.33.0与backstage/create-app0.7.0的变化集中在开发者体验BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE标志已移除改用EXPERIMENTAL_RSPACK实验性的FORCE_REACT_DEVELOPMENT标志已移除Rspack 构建改用module-federation/enhanced/rspack的ModuleFederationPlugin仅在frontend包上启用缓存型 Jest 模块加载器避免破坏真实 ESM 导入backstage new生成的插件包模板默认在package.json中加入backstage.pluginId字段打开配置文档命令增加了浏览器打开失败时的回退提示d07fe35create-app在 gitignore 中补充了.cache目录。backstage/eslint-plugin0.1.11新增backstage/no-mixed-plugin-imports规则禁止插件之间混用前后端/公共架构导入不允许前端插件导入后端插件或其他前端插件、不允许后端插件导入前端插件或其他后端插件、不允许公共插件导入前端或后端插件。当前推荐配置下该规则给出 warning未来将升级为 error建议提前调整工作区导入结构。十、其他值得关注的变更LDAP 模块plugin-catalog-backend-module-ldap可将用户memberOf或组members的映射设为null从而只保留单向或完全禁用成员关系规避 LDAP 中两侧属性漂移导致的 Catalog 异常状态示例配置见变更日志配置项落在catalog.providers.ldapOrg.default下。GitLab 模块plugin-catalog-backend-module-gitlabUser/Group 发现默认会摄取指定根组下所有子组的用户可通过模块配置中的restrictUsersToGroup: true关闭同时为 GitLab API 调用增加了限流重试。Bitbucket Server 模块plugin-catalog-backend-module-bitbucket-server新增validateLocationsExist选项避免为源仓库中不存在的catalog-info.yaml生成 location。Bitbucket Cloud 模块plugin-catalog-backend-module-bitbucket-cloudBitbucketCloudEntityProvider构造参数由CatalogApi换成CatalogService。GitHub 组织模块plugin-catalog-backend-module-github处理事件时组织名匹配改为大小写不敏感。权限规则plugin-catalog-backendHAS_LABEL权限规则现在可像HAS_ANNOTATION一样指定可选值。TechDocs引入backstage.io/techdocs-entity-path注解可配合backstage.io/techdocs-entity深度链接到其他实体的 TechDocs 页面同时改善了键盘可访问性9dde3ba。Canon 组件库backstage/canon0.5.0Button/IconButton默认尺寸改为 smallHeading/Text用asprop 取代 render propTextField基于 React Aria 重构并新增FieldLabelGrid 根组件改名为Grid.Root /并新增Switch组件。mcp-actions 后端backstage/plugin-mcp-actions-backend0.1.0MCP Actions 后端的初始实现详见 plugins/mcp-actions-backend。auditor 服务backend-defaults错误处理增强将错误作为对象传递并统一了WinstonRootAuditorService与默认工厂的错误处理行为。catalog-backend 数据库refresh_state_references.id更新为 bigint 类型4654a78涉及数据库迁移的团队需留意。search-backend-module-techdocs导出默认文档 collator便于在搜索索引阶段做文档变换。yarn-plugin-backstage新增/更新依赖时保持backstage:^版本占位符。十一、升级建议与风险清单优先处理 Scaffolder 相关破坏性变更检查自定义动作与后端模块的所有导入来源对照本文 2.1 节的映射表逐一修正将动作 Schema 迁移到 Zod 函数式写法移除对createBuiltinActions、createRouter、logStream的使用。确认是否使用了被弃用的 Task/TaskStore 类型DatabaseTaskStore等一批类型已标记弃用且暂无替代深度定制的团队需为后续重构预留时间。限流默认关闭按需开启限流是可选能力未配置backend.rateLimit时行为不变若自定义了 root HTTP router 的configure务必合并applyDefaults()。新前端系统下检查 About 卡片若未安装 TechDocs/Scaffolder 插件对应图标链接会消失有自定义翻译的需迁移到对应插件翻译引用。关注实验性 APIactionsRegistry/actions服务与info.packageJson/info.manifest均为/alpha或实验性能力接口后续可能调整。升级顺序建议先在测试环境按依赖图backend-defaults→plugin-scaffolder-node→ 各scaffolder-backend-module-*→plugin-scaffolder-backend逐层验证再通过 Upgrade Helper 对比目标版本最后执行全量versions:bump并跑通backstage-cli repo lint、tsc与测试套件。综上v1.40.0 的核心信号是Scaffolder 彻底完成向新后端系统的收敛模块化动作、Zod Schema、服务化 Catalog 访问同时后端基础设施限流、Actions 服务与前端定制体系Blueprint、插件元数据同步走向成熟是值得认真规划的一次大版本升级。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.40.0 版本解读：Scaffolder 2.0 迁移指南、后端限流与前端 Blueprint 生态演进
Backstage v1.40.0 版本解读Scaffolder 2.0 迁移指南、后端限流与前端 Blueprint 生态演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章围绕 Backstage v1.40.0 的官方变更日志docs/releases/v1.40.0-changelog.md展开聚焦本版本最核心的三条主线plugin-scaffolder-backend迈入 2.0 大版本伴随多组破坏性变更与 Zod Schema 迁移、backend-defaults新增可配置的请求限流中间件、以及新前端系统下EntityIconLinkBlueprint与插件info元数据机制的落地。读完本文你将掌握如何迁移到 Scaffolder 2.0、如何在app-config.yaml中启用全局/插件级限流、如何自定义 Catalog About 卡片图标链接并了解新引入的 Kafka 事件模块与 MCP Actions 后端等增量能力。一、版本概览与升级路径v1.40.0 是一个横跨前后端、CLI 与多个插件的大版本其中值得重点关注的包有包名新版本变化级别backstage/plugin-scaffolder-backend2.0.0Major多组破坏性变更backstage/backend-defaults0.11.0Minor新增限流、Actions 服务默认实现backstage/backend-plugin-api1.4.0Minor新增实验性 actions 服务backstage/plugin-catalog-react1.19.0Minor新增EntityIconLinkBlueprintbackstage/plugin-catalog1.31.0MinorAbout 卡片图标链接扩展backstage/plugin-events-backend-module-kafka0.1.0全新模块backstage/plugin-mcp-actions-backend0.1.0全新后端backstage/cli0.33.0Minor模块化 CLI 入口转正升级时建议使用官方 Upgrade Helper 工具定位到1.40.0目标版本逐项核对本文列出的破坏性变更对于自建 Backstage 应用执行backstage-cli versions:bump前请先确认packages/backend与packages/app中相关依赖的锁定版本与变更日志中的依赖升级清单例如backstage/backend-defaults0.11.0、backstage/plugin-scaffolder-node0.9.0保持一致。二、Scaffolder Backend 2.0.0破坏性变更全解与迁移步骤backstage/plugin-scaffolder-backend在此版本发布 2.0.0包含了四组BREAKING CHANGES和一批弃用声明是本次升级工作量最大的部分。仓库中对应的实现位于 plugins/scaffolder-backend相关的类型与工具函数则集中在 plugins/scaffolder-node。2.1 清理长期存在的重导出re-exports第一组破坏性变更移除了从scaffolder-backend插件包中转手导出的一批函数。它们已被分拆到各自的集成模块中迁移映射如下原导入来源已移除迁移后的正确导入来源createPublishAzureActionbackstage/plugin-scaffolder-backend-module-azurecreatePublishBitbucketCloudActionbackstage/plugin-scaffolder-backend-module-bitbucket-cloudcreatePublishBitbucketServerAction、createPublishBitbucketServerPullRequestActionbackstage/plugin-scaffolder-backend-module-bitbucket-servercreatePublishBitbucketActionbackstage/plugin-scaffolder-backend-module-bitbucketcreatePublishGerritAction、createPublishGerritReviewActionbackstage/plugin-scaffolder-backend-module-gerritcreateGithubActionsDispatchAction、createGithubDeployKeyAction、createGithubEnvironmentAction、createGithubIssuesLabelAction、CreateGithubPullRequestActionOptions、createGithubRepoCreateAction、createGithubRepoPushAction、createGithubWebhookAction、createPublishGithubActionbackstage/plugin-scaffolder-backend-module-githubcreatePublishGitlabActionbackstage/plugin-scaffolder-backend-module-gitlabActionContext、createTemplateAction、executeShellCommand、ExecuteShellCommandOptions、fetchContents、TaskSecrets、TemplateActionbackstage/plugin-scaffolder-node此外还有两组类型与实现需要迁移SerializedTask、SerializedTaskEvent、TaskBroker、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskContext、TaskEventType、TaskStatus、TemplateFilter、TemplateGlobal应从backstage/plugin-scaffolder-node导入ScaffolderEntitiesProcessor应改为从backstage/plugin-catalog-backend-module-scaffolder-entity-model导入该处理器用于将 Scaffolder 生成的实体注册进 Catalog相关实体模型定义见 plugins/catalog-backend-module-scaffolder-entity-model。与此同时fetch:template动作中已弃用的copyWithoutRender选项被彻底移除请统一改名为copyWithoutTemplating。2.2/alpha导出移除与旧后端系统createRouter退役第二组破坏性变更涉及两件事backstage/plugin-scaffolder-backend/alpha不再导出插件本身请直接使用import(backstage/plugin-scaffolder-backend)旧后端系统使用的createRouter函数及其RouterOptions类型被移除。这意味着仍在用旧后端系统createRouterRouterOptions方式组装 Scaffolder 的应用必须迁移到新后端系统createBackend 插件实例化否则升级后无法编译。2.3createBuiltinActions移除与 Catalog 动作的依赖重构第三组破坏性变更createBuiltinActions方法被移除。它在旧后端系统中仅用于再次传入默认动作列表而新后端系统默认会合并所有动作因此不再需要createCatalogRegisterAction与createFetchCatalogEntityAction不再依赖AuthService且参数由CatalogClient换成CatalogService。如果你是通过scaffolderActionsExtensionPoint自定义覆盖默认动作并因此遇到类型错误可参考下面的迁移写法源码层面与此对应的扩展点声明位于 plugins/scaffolder-node/src/alphaimport { catalogServiceRef } from backstage/plugin-catalog-node; import { scaffolderActionsExtensionPoint } from backstage/plugin-scaffolder-node/alpha; export const myModule createBackendModule({ pluginId: scaffolder, moduleId: test, register({ registerInit }) { registerInit({ deps: { scaffolder: scaffolderActionsExtensionPoint, catalog: catalogServiceRef, }, async init({ scaffolder, catalog }) { scaffolder.addActions( createCatalogRegisterAction({ catalog, }), createFetchCatalogEntityAction({ catalog, integrations, }), ); }, }); }, });无独有偶plugin-scaffolder-backend-module-github的createGithubEnvironmentAction也做了同样的依赖替换AuthService→CatalogService、CatalogClient→CatalogService迁移模式与此处完全一致。这一系列的改动表明Scaffolder 动作正在全面收敛到「通过CatalogService访问目录、通过scaffolderActionsExtensionPoint注册动作」的新范式。2.4 一大批 Task/TaskStore 相关类型弃用v1.40.0 同时声明了一批弃用类型包括CreateWorkerOptions、DatabaseTaskStore、DatabaseTaskStoreOptions、TaskManager、TaskStoreCreateTaskOptions、TaskStoreCreateTaskResult、TaskStoreEmitOptions、TaskStoreListEventsOptions、TaskStoreRecoverTaskOptions、TaskStoreShutDownTaskOptions。变更日志明确说明目前没有直接的替代路径这些类型将被移除并重新设计以在新后端系统中提供更优雅的 worker 定义方式。这意味着依赖这些内部类型做深度定制的团队需要提前关注后续版本的替代方案。2.5 动作 Schema 迁移到 Zod 原生写法backstage/plugin-scaffolder-node0.9.0将定义createTemplateAction输入/输出 Schema 的旧方式替换为原生的 Zod 方式。三阶段写法对照如下// 1) 最老的 JSON Schema 写法已不推荐 createTemplateAction{ repoUrl: string }, { repoOutput: string }({ id: test, schema: { input: { type: object required: [repoUrl] properties: { repoUrl: { type: string, description: repository url description } } } } }); // 2) 旧的 Zod 写法已不推荐 createTemplateAction({ id: test schema: { input: { repoUrl: z.string({ description: repository url description }) } } }) // 3) 新的 Zod 函数式写法推荐 createTemplateAction({ id: test, schema: { input: { repoUrl: z z.string({ description: repository url description }) } } }) // 或对更复杂的联合类型使用整体函数式写法 createTemplateAction({ id: test, schema: { input: z z.object({ repoUrl: z.string({ description: repository url description }) }) } })新写法把 schema 定义从值升级为函数使得 schema 可以延迟求值并复用zod的全部类型能力联合、交叉、条件等。scaffolder-backend-module-*系列模块azure、bitbucket、bitbucket-cloud、bitbucket-server、gerrit、gitea、gitlab、confluence-to-markdown、cookiecutter、rails、sentry、yeoman 等都在本版本统一迁移到新格式。重要附带变更logStream已从ActionsContext中彻底移除ctx.logger现在直接是LoggerService实现。没有官方替代方案若仍需使用 logStream官方建议自建一个写入ctx.logger的流。相应地plugin-scaffolder-node-test-utils的createMockActionContext也移除了logStream参数。2.6 模板each步骤支持 Secrets一个很实用的新能力each步骤中可以直接引用${{ secrets.xxx }}。例如each: [ { name: Service1, token: ${{ secrets.token1 }} }, { name: Service2, token: ${{ secrets.token2 }} }, ]这意味着在软件模板的循环步骤中按元素注入机密例如批量创建带凭据的服务不再需要外部拼接。另外本版本为 Scaffolder 补充了更多测试e92e481可参考 plugins/scaffolder-backend 中的测试目录了解动作行为的既有约定。三、backend-defaults 0.11.0全局与插件级请求限流backstage/backend-defaults0.11.0引入了基于express-rate-limit的限流中间件。其实现位于 packages/backend-defaults/src/lib/rateLimitMiddleware.ts并在 packages/backend-defaults/src/entrypoints/rootHttpRouter/rootHttpRouterServiceFactory.ts 的applyDefaults()中通过app.use(middleware.rateLimit())挂载到根 HTTP 路由。对应的单元测试见 packages/backend-defaults/src/lib/rateLimitMiddleware.test.ts 与 packages/backend-defaults/src/lib/RateLimitStoreFactory.test.ts。3.1 开启全局限流在app-config.yaml中增加如下配置即可开启backend: rateLimit: window: 6s incomingRequestLimit: 100window时间窗口支持时长字符串如6s源码内部通过readDurationFromConfig解析并转为毫秒incomingRequestLimit窗口内允许的最大请求数超限返回429。从源码看该中间件还支持以下可选配置项均可写入backend.rateLimit配置键作用ipAllowList放行 IP 列表默认值为[127.0.0.1, 0:0:0:0:0:0:0:1, ::1]本机地址默认放行skipSuccessfulRequests成功请求不计入限流skipFailedRequests失败请求不计入限流passOnStoreError存储层报错时是否放行容错此外限流键生成使用ipKeyGenerator对 IPv6 地址做规范化避免客户端通过轮换块内地址绕过限制validate.trustProxy被置为false在配置backend.trustProxy时需注意代理场景下的 IP 语义。3.2 插件级限流若只想限制某个插件的流量可关闭全局限流并为指定插件单独配置backend: rateLimit: global: false # 关闭全局限流 plugin: catalog: window: 6s incomingRequestLimit: 100global: false关闭全局兜底plugin.catalog则为 catalog 插件单独设定窗口与上限适合对高频但易被打爆的插件接口做精细化保护。3.3 自定义configure回调的兼容提醒变更日志特别提醒如果你在 root HTTP router 服务的configure回调中自定义配置且没有调用applyDefaults()需要把限流中间件以及其他默认中间件自行合入你的自定义配置否则升级后不会自动获得限流能力。建议直接调用applyDefaults()并在其后追加自定义逻辑。四、实验性 Actions 服务跨插件注册与调用动作backstage/backend-plugin-api1.4.0在/alpha导出中新增了两个实验性服务actionsRegistry注册分布式动作与actions调用动作并提供了默认实现c999c25落在backend-defaults中。典型用法import { actionsRegistryServiceRef, actionsServiceRef, } from backstage/backend-plugin-api/alpha; createBackendPlugin({ pluginId: test-plugin, register({ registerInit }) { registerInit({ deps: { actions: actionsServiceRef, actionsRegistry: actionsRegistryServiceRef, }, async init({ actions, actionsRegistry }) { actionsRegistry.register({ ..., }); await actions.invoke(...); }, }); }, });与之配套backstage/plugin-catalog-backend2.1.0已用ActionsRegistry实现了get-catalog-entity动作2e7adf0而backend-test-utils1.6.0也新增了对应的 mock 工具便于为动作编写单元测试import { actionsRegistryServiceMock } from backstage/backend-test-utils/alpha; const mockActionsRegistry actionsRegistryServiceMock(); const mockCatalog catalogServiceMock({ entities: [ ... ], }); createGetCatalogEntityAction({ catalog: mockCatalog, actionsRegistry: mockActionsRegistry, }); await expect( mockActionsRegistry.invoke({ id: test:get-catalog-entity, input: { name: test }, }), ).resolves.toEqual(...)五、Catalog 新前端系统EntityIconLinkBlueprint 与 About 卡片自定义backstage/plugin-catalog-react1.19.0引入EntityIconLinkBlueprint用于自定义 Catalog 实体页 About 卡片上的图标链接。其 Blueprint 定义位于 plugins/catalog-react/src/alpha/blueprints/EntityIconLinkBlueprint.tsx它挂载在entity-card:catalog/about扩展点的iconLinks输入上通过useProps数据 ref 输出图标链接属性并支持filter按实体过滤与label/title配置覆盖。5.1useProps返回的属性表useProps钩子返回以下属性将透传给图标链接组件名称描述类型默认值icon要显示的图标JSX.Element无label元素的标签string无title元素的标题string无disabled是否禁用该元素booleanfalsehref点击后跳转的 URLstring无onClick点击回调函数() void无5.2 使用示例import { EntityIconLinkBlueprint } from backstage/plugin-catalog-react/alpha; //... EntityIconLinkBlueprint.make({ name: my-icon-link, params: { useProps() { const { t } useTranslationRef(myIconLinkTranslationRef); return { label: t(myIconLink.label), icon: MyIconLinkIcon /, href: /my-plugin, }; }, }, });5.3 通过 app-config 覆盖 label 与 title还可以在app-config.yaml中用app.extensions覆盖默认图标链接的label与titleapp: extensions: - entity-icon-link:my-plugin/my-icon-link: config: label: My Custom Icon Link label注意当没有任何图标链接扩展被启用时About 卡片头部会被整体隐藏适合把链接独立展示在别的卡片上的场景。5.4 与 About 卡片默认链接的拆分backstage/plugin-catalog1.31.0中原本内置于 Catalog About 卡片链接的「Scaffolder 启动模板」与「TechDocs 阅读文档」两个图标链接被抽取出来改由Scaffolder与TechDocs插件分别提供。这意味着未安装 TechDocs/Scaffolder 插件时对应图标将不再出现如果你为这两个链接标题配置了非默认翻译需要改用 Scaffolder/TechDocs 各自的 translation reference翻译键保持不变aboutCard.viewTechdocs与aboutCard.launchTemplate。六、事件系统全新 Kafka 消费模块backstage/plugin-events-backend-module-kafka0.1.0是全新的事件后端模块位于 plugins/events-backend-module-kafka。它提供两个核心件KafkaConsumerClient基于 KafkaJS 建立消费连接KafkaConsumingEventPublisher订阅配置的 Kafka topic并把收到的消息发布到 Backstage 事件服务Event Service。从配置解析实现plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/config.ts可以看出它支持多实例配置events.modules.kafka.kafkaConsumingEventPublisher下的每个键视为一个 publisher每个 publisher 可配置topics数组其中kafka.groupId、kafka.topics、kafka.fromBeginning为消费组与订阅主题的核心参数kafka.sessionTimeout、kafka.rebalanceTimeout、kafka.heartbeatInterval、kafka.metadataMaxAge、kafka.maxBytesPerPartition、kafka.minBytes、kafka.maxBytes、kafka.maxWaitTime等可控制消费行为kafka.autoCommit默认true与kafka.pauseOnError默认false分别控制手动提交与出错暂停策略。模块测试见 plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/module.test.ts。同时backstage/plugin-events-backend-module-google-pubsub0.1.1新增了EventConsumingGooglePubSubPublisher用于把 Backstage 事件推送回 Google Pub/Sub。七、通知系统广播与保留期策略backstage/plugin-notifications-backend0.5.7带来两个值得注意的行为变化默认自动删除一年前的通知新增的定时任务每 24 小时运行一次删除超过 1 年的通知。可通过app-config.yaml配置保留期notifications: retention: 1y若将retention设为false则禁用自动清理。广播通知的用户字段通知 API 对广播broadcast通知始终返回user: null避免误导性地暴露发送者身份。此外通知与 Scaffolder 通知模块plugin-scaffolder-backend-module-notifications都支持了在某个来源origin内按 topic 开关通知的用户级能力1fb5f06。八、前端系统插件info元数据与useAppNodebackstage/frontend-plugin-api0.10.3为createFrontendPlugin增加了可选的info选项用于提供插件元数据加载器有两种形式// 方式一加载插件自身的 package.json推荐给发布到包仓库的插件 export default createFrontendPlugin({ pluginId: ..., info: { packageJson: () import(../package.json), }, }); // 方式二加载不透明 manifest仅限组织内使用禁止用于公开发布的插件 export default createFrontendPlugin({ pluginId: ..., info: { manifest: () import(../catalog-info.yaml), }, });packageJson指向插件包内的package.json适合任何在独立包中定义、尤其是发布到公共包仓库的插件manifest仅限在单一组织内部使用的插件可携带额外内部元数据默认 manifest 解析器能解析标准catalog-info.yaml格式及spec.owner等内置字段。配套能力包括frontend-app-api为createSpecializedApp支持了pluginInfoResolver选项并新增静态配置键app.pluginOverridesbackstage/plugin-catalog等插件实例新增info.packageJson选项同时新增了useAppNode钩子可从最近的ExtensionBoundary获取AppNode引用。本版本大量插件catalog、techdocs、home、org、notifications、search、signals、user-settings、api-docs、devtools、kubernetes、catalog-import、catalog-graph、app-visualizer 等都同步接入了info.packageJson。九、CLI 与工具链更新backstage/cli0.33.0与backstage/create-app0.7.0的变化集中在开发者体验BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE标志已移除改用EXPERIMENTAL_RSPACK实验性的FORCE_REACT_DEVELOPMENT标志已移除Rspack 构建改用module-federation/enhanced/rspack的ModuleFederationPlugin仅在frontend包上启用缓存型 Jest 模块加载器避免破坏真实 ESM 导入backstage new生成的插件包模板默认在package.json中加入backstage.pluginId字段打开配置文档命令增加了浏览器打开失败时的回退提示d07fe35create-app在 gitignore 中补充了.cache目录。backstage/eslint-plugin0.1.11新增backstage/no-mixed-plugin-imports规则禁止插件之间混用前后端/公共架构导入不允许前端插件导入后端插件或其他前端插件、不允许后端插件导入前端插件或其他后端插件、不允许公共插件导入前端或后端插件。当前推荐配置下该规则给出 warning未来将升级为 error建议提前调整工作区导入结构。十、其他值得关注的变更LDAP 模块plugin-catalog-backend-module-ldap可将用户memberOf或组members的映射设为null从而只保留单向或完全禁用成员关系规避 LDAP 中两侧属性漂移导致的 Catalog 异常状态示例配置见变更日志配置项落在catalog.providers.ldapOrg.default下。GitLab 模块plugin-catalog-backend-module-gitlabUser/Group 发现默认会摄取指定根组下所有子组的用户可通过模块配置中的restrictUsersToGroup: true关闭同时为 GitLab API 调用增加了限流重试。Bitbucket Server 模块plugin-catalog-backend-module-bitbucket-server新增validateLocationsExist选项避免为源仓库中不存在的catalog-info.yaml生成 location。Bitbucket Cloud 模块plugin-catalog-backend-module-bitbucket-cloudBitbucketCloudEntityProvider构造参数由CatalogApi换成CatalogService。GitHub 组织模块plugin-catalog-backend-module-github处理事件时组织名匹配改为大小写不敏感。权限规则plugin-catalog-backendHAS_LABEL权限规则现在可像HAS_ANNOTATION一样指定可选值。TechDocs引入backstage.io/techdocs-entity-path注解可配合backstage.io/techdocs-entity深度链接到其他实体的 TechDocs 页面同时改善了键盘可访问性9dde3ba。Canon 组件库backstage/canon0.5.0Button/IconButton默认尺寸改为 smallHeading/Text用asprop 取代 render propTextField基于 React Aria 重构并新增FieldLabelGrid 根组件改名为Grid.Root /并新增Switch组件。mcp-actions 后端backstage/plugin-mcp-actions-backend0.1.0MCP Actions 后端的初始实现详见 plugins/mcp-actions-backend。auditor 服务backend-defaults错误处理增强将错误作为对象传递并统一了WinstonRootAuditorService与默认工厂的错误处理行为。catalog-backend 数据库refresh_state_references.id更新为 bigint 类型4654a78涉及数据库迁移的团队需留意。search-backend-module-techdocs导出默认文档 collator便于在搜索索引阶段做文档变换。yarn-plugin-backstage新增/更新依赖时保持backstage:^版本占位符。十一、升级建议与风险清单优先处理 Scaffolder 相关破坏性变更检查自定义动作与后端模块的所有导入来源对照本文 2.1 节的映射表逐一修正将动作 Schema 迁移到 Zod 函数式写法移除对createBuiltinActions、createRouter、logStream的使用。确认是否使用了被弃用的 Task/TaskStore 类型DatabaseTaskStore等一批类型已标记弃用且暂无替代深度定制的团队需为后续重构预留时间。限流默认关闭按需开启限流是可选能力未配置backend.rateLimit时行为不变若自定义了 root HTTP router 的configure务必合并applyDefaults()。新前端系统下检查 About 卡片若未安装 TechDocs/Scaffolder 插件对应图标链接会消失有自定义翻译的需迁移到对应插件翻译引用。关注实验性 APIactionsRegistry/actions服务与info.packageJson/info.manifest均为/alpha或实验性能力接口后续可能调整。升级顺序建议先在测试环境按依赖图backend-defaults→plugin-scaffolder-node→ 各scaffolder-backend-module-*→plugin-scaffolder-backend逐层验证再通过 Upgrade Helper 对比目标版本最后执行全量versions:bump并跑通backstage-cli repo lint、tsc与测试套件。综上v1.40.0 的核心信号是Scaffolder 彻底完成向新后端系统的收敛模块化动作、Zod Schema、服务化 Catalog 访问同时后端基础设施限流、Actions 服务与前端定制体系Blueprint、插件元数据同步走向成熟是值得认真规划的一次大版本升级。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考