Backstage v1.40.0 版本解析Scaffolder 2.0 破坏性变更、Actions Registry、后端限流与 MCP 集成【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇基于 docs/releases/v1.40.0.md 发布说明逐项解析 Backstage v1.40.0 的核心更新Scaffolder 2.0 对模板 Action 定义方式的破坏性变更与迁移路径、新增的 Actions Registry 与mcp-actions插件、后端内置限流、TechDocs 深链、通知保留策略等。读完本文你将掌握如何将存量 Scaffolder Action 迁移到新的 zod 函数式格式、如何通过backend.rateLimit与notifications.retention配置新能力以及各新模块/新规则的启用与排错方式。总体概览v1.40.0 是一次以「Scaffolder 架构清理」为核心的大版本plugin-scaffolder-backend彻底转向仅支持新后端系统New Backend System并移除了大量陈旧 API同时社区贡献的 Actions Registry含 MCP 服务暴露、Kafka 事件模块、后端限流等新能力正式登场。版本不含任何安全修复官方推荐通过 keeping Backstage updated 指南将项目升级至该版本。Scaffolder 2.0模板 Action 定义格式的破坏性变更旧格式已全部移除迁移到 zod 函数式写法过去createTemplateAction曾先后支持两种 schema 定义方式最老的是裸 JSON Schema 对象type: object/properties随后引入的旧 zod 写法是直接传入z.string(...)的 ZodType 实例。v1.40.0 中这两者均被移除统一为「zod 工厂函数」格式即每个字段的值是一个接收z实现并返回 ZodType 的函数// 已移除老的 JSON Schema 写法 createTemplateAction{ repoUrl: string }, { repoOutput: string }({ id: test, schema: { input: { type: object, required: [repoUrl], properties: { repoUrl: { type: string, description: repository url description, }, }, }, }, }); // 已移除旧 zod 写法直接传实例 createTemplateAction({ id: test, schema: { input: { repoUrl: z.string({ description: repository url description }), }, }, }); // 新格式zod 工厂函数z ... createTemplateAction({ id: test, schema: { input: { repoUrl: z z.string({ description: repository url description }), }, }, });这一变更同时清理了旧模式中遗留的logStream与WinstonLogger用法。从源码看新的createTemplateAction位于 plugins/scaffolder-node/src/actions/createTemplateAction.ts其内部通过parseSchemas将 zod schema 转换为 JSON Schema 供全系统使用并利用 TypeScript 泛型从z.infer推导出 Action 的输入/输出类型以获得端到端的类型安全模板 Action 选项类型TemplateActionOptions的schema.input/schema.output均被约束为(zImpl: typeof z) z.ZodType的映射或函数形式。更严格的校验多余属性会触发 InputError由于新的 zod 格式校验更严格如果软件模板 YAML 中定义的 Action 带有 schema 之外的多余属性运行时会抛出InputError。官方给出的示例错误信息为InputError: Invalid input passed to action publish:github, instance is not allowed to have the additional property allowedHosts修复方式是在软件模板 YAML 中删除 Action 定义里多余的属性例如上面的allowedHosts。plugin-scaffolder-backend 只支持新后端系统scaffolder-backend插件已转换为 New Backend System only大量公共 API 被清理createRouter与createBuiltinActions被移除——它们仅服务于旧后端系统。从 plugins/scaffolder-backend/src/ScaffolderPlugin.ts 可以看到现在插件通过createBackendPlugin注册内置 Action 以显式列表形式组装fetch:plain、fetch:template、debug:log、wait、catalog:register等并由createScaffolderActions写入 actions 注册表。-backend包中从-common、-node重新导出的大量废弃类型被删除需改为从正确来源包导入。fetch:template的废弃选项copyWithoutRender已移除应重命名为copyWithoutTemplating。在 plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/template.ts 中当前 schema 仅保留copyWithoutTemplatingglob 数组匹配的文件/目录内容不做模板渲染但路径仍参与渲染旧的copyWithoutRender不再存在于选项定义中。提供方包中重新导出的 Action 工厂如createPublishAzureAction、createPublishGithubAction改为从各自 provider 模块如backstage/plugin-scaffolder-backend-module-github直接导入。此外plugin-scaffolder-node仍导出一批类型官方已预告这些类型将在未来版本中随着 Scaffolder 架构重构被移除迁移时应关注 plugins/scaffolder-backend/CHANGELOG.md 与 plugins/scaffolder-node/CHANGELOG.md 的详细记录。Actions Registry 与 MCP 集成alphav1.40.0 新增两个alpha服务用于跨 Backstage 定义分布式 Actions插件可以通过ActionsRegistry声明随插件自动安装的 Action。在此基础上还提供了全新的mcp-actions后端插件将注册表中的 Action 以工具tools形式暴露为 MCP 服务器供 Cursor、Claude、ChatGPT 等 AI 工具调用。从 plugins/mcp-actions-backend/src/plugin.ts 的实现可以看到插件依赖actionsServiceRef与actionsRegistryServiceRef均来自backstage/backend-plugin-api/alpha默认服务器始终挂载在/v1路径命名服务器mcpActions.servers配置以/v1/key挂载作为默认服务器的子集而非分区支持mcpActions.name、mcpActions.description、mcpActions.instructions、mcpActions.namespacedToolNames等配置项以及mcpActions.tracing.capture.toolPayload用于可选捕获工具调用负载当auth.experimentalDynamicClientRegistration.enabled或 clientId 元数据文档启用 OAuth 时会额外注册 RFC 8414OAuth 授权服务器元数据与 RFC 9728受保护资源元数据端点支持 MCP 客户端的 OAuth 发现与刷新令牌offline_access。该功能当前高度实验性未来版本可能发生破坏性变更官方欢迎为插件创建 Action 并暴露到 MCP 服务器的反馈。官方明确计划在下一版本中让 Scaffolder 能够从模板调用这些注册的 Action。相关设计背景可参阅社区 RFC见发布说明中引用的 issue #30218。TechDocs 深链新增techdocs-entity-path注解TechDocs 新增backstage.io/techdocs-entity-path注解与已有的backstage.io/techdocs-entity配合使用可从一个实体的 TechDocs 页面深度链接到另一个实体的文档目录。在仓库中该注解常量定义于 plugins/techdocs-common/src/constants.tsexport const TECHDOCS_ANNOTATION backstage.io/techdocs-ref; export const TECHDOCS_EXTERNAL_ANNOTATION backstage.io/techdocs-entity; export const TECHDOCS_EXTERNAL_PATH_ANNOTATION backstage.io/techdocs-entity-path;前端侧plugins/techdocs/src/reader/components/TechDocsReaderPageContent/TechDocsReaderPageContent.tsx 的defaultPathprop 专门用于处理指定了该注解的实体渲染它作为默认渲染的文档路径实现深链到另一实体文档的效果对应的重定向行为在 useExternalRedirect.test.tsx 中有测试覆盖例如注解值为/inner-component-docs的深链用例。该特性由社区贡献者 csuich2 在 PR #29760 中引入。Catalog 模块的破坏性变更BitbucketCloudEntityProvider的构造参数由CatalogApi改为CatalogService。在 plugins/catalog-backend-module-bitbucket-cloud/src/providers/BitbucketCloudEntityProvider.ts 中私有字段与构造函数均已使用来自backstage/backend-plugin-api的CatalogService类型对应新后端系统的服务接口。GitLab 的 User/Group 发现行为变化默认将摄取指定根组下所有子组sub groups中的用户。若想恢复旧行为可在 app-config 的模块配置中设置restrictUsersToGroup: true。该选项在 plugins/catalog-backend-module-gitlab/src/lib/types.ts 中定义为restrictUsersToGroup?: boolean其分支逻辑SaaS 取根组用户、自托管实例取实例用户在 GitlabOrgDiscoveryEntityProvider.ts 中实现测试覆盖可见于 GitlabOrgDiscoveryEntityProvider.test.ts。新模块backstage/plugin-events-backend-module-kafka该模块为 Backstage 事件系统新增 Kafka 支持核心包含两个类KafkaConsumerClient创建用于建立消费者连接的 Kafka 客户端KafkaConsumingEventPublisher订阅配置的 Kafka topics将收到的消息发布到 Backstage 事件服务供插件消费。从 KafkaConsumingEventPublisher.ts 的实现与 config.ts 的配置解析看该 publisher 支持按 topic 配置kafka.groupId、kafka.topics、kafka.autoCommit默认 true、kafka.pauseOnError默认 false、maxBytesPerPartition、minBytes、maxBytes、fromBeginning等参数并支持clientId的全局配置。该模块由 Jonas-Beck 在 PR #29315 中贡献。新 lint 规则backstage/no-mixed-plugin-imports默认 lint 配置新增backstage/no-mixed-plugin-imports规则将此前隐式成立的约束显式化不得跨前后端包边界导入、同构isomorphic包不得导入非同构包等。v1.40.0 中该规则初始为 warning 级别官方建议关注构建输出中新增的告警——它们可能暴露此前未注意的依赖问题并计划在后续版本提升为 error 级别。规则支持excludedTargetPackages选项可在特定包中豁免。在根.eslintrc.js中配置示例module.exports { root: true, plugins: [spotify, react, testing-library, backstage], rules: { backstage/no-mixed-plugin-imports: [ error, // 若想提前启用严格检查 { excludedTargetPackages: [ internal/plugin-foo, // ... 其他需要豁免的包 ], }, ], }, };该规则由 drodil 在 PR #30227 中贡献。CLI向 rspack 演进CLI 构建链路继续向rspack迁移BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE标志被彻底移除若曾使用请改用EXPERIMENTAL_RSPACK实验性FORCE_REACT_DEVELOPMENT标志同样被移除。官方目标是在不远的将来默认启用 rspack。后端内置限流Rate Limiting新后端系统现已内置对入站请求的限流支持可作用于整个后端或按插件粒度配置状态存储默认支持内存与 Redis 两种实现。该能力为 opt-in完整文档见 docs/backend-system/core-services/http-router.md。启用方式app-configbackend: rateLimit: true按插件细化参数backend: rateLimit: global: true # 对所有插件启用/禁用限流 window: 6s # 单客户端的限流时间窗口 incomingRequestLimit: 100 # 时间窗口内单个客户端允许的请求数 ipAllowList: [127.0.0.1] # 豁免限流的 IP skipSuccessfulRequests: false # 是否对成功请求也限流 skipFailedRequests: false # 是否对失败请求也限流 plugin: # 插件级限流 catalog: window: 3s incomingRequestLimit: 50默认限流状态按实例保存在内存中如需在多实例间共享计数配置 Redis 存储backend: rateLimit: global: true store: type: redis connection: redis://127.0.0.1:16379如果实例位于代理之后需配置backend.trustProxy: true以便限流正确区分客户端 IP详见文档中对 express trust proxy 的说明。对于更高级的自定义backstage/backend-defaults/httpRouter导出的createRateLimitMiddleware等中间件可在自定义 httpRouter 服务实现中组合使用。该特性由 drodil 在 PR #28708 中贡献。新前端系统插件信息Plugin Info新前端系统中的插件现在可以暴露丰富、可扩展的自身元数据并在应用运行时访问——例如联系人、支持信息等也可以在开源插件提供的信息之上叠加自定义数据。根据 docs/frontend-system/architecture/10-app.md 的说明应用默认会从插件的package.json及catalog-info.yaml清单中提取公共字段通过插件实例的info()方法返回FrontendPluginInfo结构。三类自定义方式扩展类型通过 TypeScript 模块增强module augmentation为FrontendPluginInfo增加字段例如新增slackChannel字段自定义解析向createApp传入自定义pluginInfoResolver在默认解析结果基础上补充自定义字段与链接静态覆盖使用 app-config 的app.pluginOverrides键在解析完成后覆盖插件信息尤其适用于第三方插件app: pluginOverrides: - match: pluginId: catalog info: ownerEntityRefs: [catalog-owners]match支持pluginId与packageName正则写法如/acme/.*/可用于按命名空间批量覆盖 owner 等信息。Notifications 保留策略通知后端插件存储的通知现在默认保留一年后自动删除以控制存储规模。可通过 app-config 中的notifications.retention时长设置覆盖notifications: retention: 6 months从 plugins/notifications-backend/src/service/NotificationCleaner.ts 的实现看默认保留时长为{ years: 1 }若将notifications.retention显式设为布尔值false则禁用清理任务日志输出 Notification retention is disabled, skipping notification cleaner task设置为时长值时通过readDurationFromConfig解析并用于clearNotifications({ maxAge })清理。相关行为在 NotificationCleaner.test.ts 中有测试覆盖。该特性由 drodil 在 PR #30206 中贡献。i18n 与设计系统进展v1.40.0 在若干插件中推进了 i18n国际化/翻译支持至少涉及core components、org 插件、catalog import 插件、home 插件、search 插件与 user settings 插件由 mario-mui 贡献。此外canon 设计系统仍在持续演进新增了若干控件并做了多项改进。升级路径与参考官方建议将 Backstage 项目保持更新到最新版本升级指引见 keeping Backstage updated版本与支持策略见 docs/overview/versioning-policy.md。针对本文涉及的破坏性变更重点排查项可归纳为将模板 Action schema 全部改写为z z.string(...)工厂函数格式并删除软件模板 YAML 中 schema 之外的多余属性避免InputError将fetch:template的copyWithoutRender重命名为copyWithoutTemplating从正确的 provider 模块导入 Action 工厂如从backstage/plugin-scaffolder-backend-module-github导入createPublishGithubAction废弃类型改从-common/-node正确来源导入若使用 GitLab 组织发现且不希望摄取子组用户配置restrictUsersToGroup: true关注新 lint 规则产生的 warning并可将BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE迁移为EXPERIMENTAL_RSPACK。v1.40.0 的完整变更记录可继续查阅 docs/releases/v1.40.0-changelog.md。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考