Backstage v1.38.0 版本解读gateway-backend 正式发布、动态前端插件与后端服务新能力全解析【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文以 Backstage 官方仓库 docs/releases/v1.38.0-changelog.md 为主线系统梳理 v1.38.0 版本中backstage/plugin-gateway-backend首个 1.0.0 正式版、backstage/frontend-dynamic-feature-loader全新前端动态加载器以及backend-defaults、scaffolder、catalog、cli、canon等核心包的破坏性变更与新增能力。读完本文你将掌握 v1.38.0 中每一个影响升级的配置项、命令迁移方式和代码调整点并能基于仓库源码理解这些变更背后的实现原理。一、版本总览本次发布的核心主题v1.38.0 是一个覆盖面极广的常规版本涉及后端核心服务、前端系统、软件目录Catalog、软件模板Scaffolder、CLI 工具链与 Canon 设计系统组件库。按变更影响力可分为四大主题分布式部署路由能力补齐backstage/plugin-gateway-backend1.0.0正式发布解决了后端拆分部署后前端无法动态路由到正确后端插件的问题。动态前端插件体系落地新增backstage/frontend-dynamic-feature-loader0.1.0配合后端动态特性服务使前端插件能够以 Module Federation 远程模块的形式被动态加载。后端基础设施增强backend-defaults0.9.0带来backend.trustProxy、SRV 记录解析、OBO 认证actor属性、Redis 客户端透传等一批实用的服务级能力。全仓库的 React 19 迁移准备CLI 与所有前端相关包移除了默认 React 导入并引入新的 ESLint 规则。二、后端核心服务更新backend-defaults0.9.0backstage/backend-defaults0.9.0是本次版本中后端侧最重要的升级包含 5 项 Minor Changes每一项都值得关注。2.1 新增backend.trustProxy配置一行配置搞定代理信任当 Backstage 部署在反向代理如 Nginx、HAProxy之后时Express 需要开启trust proxy设置才能正确读取X-Forwarded-*头例如让req.ip、协议判断等基于代理提供的转发信息。在 v1.38.0 之前这需要通过给rootHttpRouter服务编写自定义configure回调实现现在只需在 app-config 中声明即可backend: trustProxy: true从源码看该能力实现在 packages/backend-defaults/src/entrypoints/rootHttpRouter/rootHttpRouterServiceFactory.ts工厂函数在启动时读取config.getOptional(backend.trustProxy)并在默认的applyDefaults()回调中执行app.set(trust proxy, trustProxy)。该配置同样出现在 packages/backend-defaults/config.d.ts 的配置 schema 声明中。如果你已经在使用自定义的configure回调并且该回调没有调用applyDefaults()那么需要在回调中手动补上以下逻辑const trustProxy config.getOptional(backend.trustProxy); if (trustProxy ! undefined) { app.set(trust proxy, trustProxy); }trustProxy的值可以是布尔值、IP 地址列表等 Express 支持的所有形式具体取值语义与 Express.js 官方trust proxy选项一致。2.2 HostDiscovery 支持 SRV 记录解析httpsrv://协议默认的HostDiscovery服务现在支持 SRV 记录DNS Service Records的实时解析。你可以把内部 URL 写成httpsrv://some-srv-name/api/{{pluginId}}这种形式插件 ID 会在解析时被替换SRV 记录的 host 部分会被解析为真实的主机和端口——当存在多条匹配记录时会按 DNS 惯例做加权随机选择。该实现位于 packages/backend-defaults/src/entrypoints/discovery/HostDiscovery.ts 与 packages/backend-defaults/src/entrypoints/discovery/SrvResolvers.tsSrvResolvers基于 Node 内置的node:dns的resolveSrv实现并对解析结果做了带 TTL 的缓存默认缓存 1000ms。其典型用法是在discovery.endpoints中为所有插件设置动态内部地址discovery: endpoints: - target: internal: httpsrv://backstage-plugin-{{pluginId}}.http.services.company.net/api/{{pluginId}} plugins: [*]注意httpsrv://形式只能用于internal键且 URL 中不能携带端口SRV 记录本身会返回端口相关约束在 packages/backend-defaults/src/entrypoints/discovery/SrvResolvers.test.ts 中有对应测试覆盖。这对于运行在 Kubernetes 等动态网络环境、后端插件按需扩缩容的部署非常实用。2.3 认证主体验证增强BackstageUserPrincipal新增actor属性backstage/backend-plugin-api1.3.0为BackstageUserPrincipal增加了可选的actor属性它保存了最后一个代替用户执行认证的服务主体subject。这意味着在 OBOOn-Behalf-Of链式调用场景下你可以追溯用户是通过哪个服务完成认证的。类型定义位于 packages/backend-plugin-api/src/services/definitions/AuthService.tsactor的类型为BackstageServicePrincipal。该变更同时同步到了backend-defaults、backend-plugin-api、backend-test-utils三个包对审计和调试服务间调用的身份来源非常有价值。2.4 Cache 核心服务透传 Redis 客户端选项backend-defaults现在允许把 Redis client 和 cluster 选项直接透传给 Cache 核心服务。如果你使用 Redis 作为缓存后端并且需要自定义连接池、TLS、超时等底层参数不再需要绕过 Cache 服务自行创建客户端可以直接在配置中声明这些选项。2.5 移除 Bitbucket Server API 调用的节流backend-defaults与backstage/plugin-catalog-backend-module-bitbucket-server0.4.0共同移除了对 Bitbucket Server API 的节流Throttle限制配合 Bitbucket Server 自身的能力进行调用减少不必要的等待。2.6 审计日志严重级别映射backend.auditor.severityLogLevelMappings新增backend.auditor.severityLogLevelMappings配置用于把审计事件auditor的严重级别映射到日志级别方便把审计流接入统一日志体系例如把某个严重级别映射到warn或error输出。三、backstage/plugin-gateway-backend1.0.0分布式部署的网关路由方案正式发布v1.38.0 中backstage/plugin-gateway-backend迎来 1.0.0 正式版首个 Major Release。它面向已经把后端插件拆分到多个 Backstage 部署的组织虽然自定义 Discovery 服务能解决后端插件之间的互相路由但前端到后端的请求路由仍然要么靠前端硬编码 URL要么靠自建反向代理。该插件提供一种集中式路由方案在专用的 gateway Backstage 部署中注册它它会优先路由到本地的插件本地没有时再借助 Discovery 服务把前端请求转发到正确的远端后端插件。官方说明见 plugins/gateway-backend/README.md。安装与接入方式# 从仓库根目录 yarn --cwd packages/backend add backstage/plugin-gateway-backend在packages/backend/src/index.ts中注册const backend createBackend(); // ... backend.add(import(backstage/plugin-gateway-backend));并把 app-config 的backend.baseUrl指向 gateway 部署backend: # The baseUrl of your gateway Backstage deployment baseUrl: http://gateway-backstage-backend.example.com四、backstage/frontend-dynamic-feature-loader0.1.0动态前端插件加载器v1.38.0 引入全新的backstage/frontend-dynamic-feature-loader0.1.0它基于新前端系统New Frontend System实现了一个前端特性加载器能够把以 Module Federation 远程模块形式暴露的前端特性动态加载进应用。它与后端动态特性服务backstage/backend-dynamic-feature-service中新增的前端插件 Module Federation 远程模块服务器协同工作——后端负责托管这些远程模块前端加载器负责获取并挂载。其加载与容错逻辑如远程配置获取失败、JSON 解析失败的处理在 packages/frontend-dynamic-feature-loader/src/loader.test.tsx 中有完整测试覆盖。这套组合让前端插件动态加载从架构提案走向可运行实现相关背景可参考 beps/0002-dynamic-frontend-plugins。五、软件目录Catalog变更5.1 Bitbucket Server支持 push webhook 驱动的增量更新backstage/plugin-catalog-backend-module-bitbucket-server0.4.0现在可以接收来自 Bitbucket Server push webhook 的事件并据此对目录执行增量变更delta mutation而不是全量重扫。配套的新包backstage/plugin-events-backend-module-bitbucket-server0.1.0负责接入 webhook 事件。同时该模块与backend-defaults一起移除了对 Bitbucket Server API 调用的节流。5.2 GitHub 目录模块拒绝含斜杠的分支名破坏性变更backstage/plugin-catalog-backend-module-github0.8.0现在会显式拒绝filters.branch中包含斜杠的分支名因为这类分支名会让摄入流程在下游出现问题。如果现有配置在filters.branch中使用了带斜杠的分支名应用可能无法启动需要迁移到不带斜杠的分支名。此外本次为该模块补上了此前缺失的validateLocationsExist配置声明plugins/catalog-backend-module-github。5.3 CatalogFilterBlueprint 迁移到 plugin-catalog-react破坏性 ALPHA在新前端系统中使用的CatalogFilterBlueprint从backstage/plugin-catalog迁移到了backstage/plugin-catalog-react import { CatalogFilterBlueprint } from backstage/plugin-catalog-react/alpha; - import { CatalogFilterBlueprint } from backstage/plugin-catalog/alpha;5.4 新增 EntityContextMenuItemBlueprint扩展实体页上下文菜单backstage/plugin-catalog-react1.17.0新增EntityContextMenuItemBlueprint允许通过用户自定义条目扩展实体页面的上下文菜单右键菜单。支持两种形态——跳转链接与点击回调import { EntityContextMenuItemBlueprint } from backstage/plugin-catalog-react/alpha; const myCustomHref EntityContextMenuItemBlueprint.make({ name: test-href, params: { icon: spanExample Icon/span, useProps: () ({ title: Example Href, href: /example-path, disabled: false, component: a, }), }, }); const myCustomOnClick EntityContextMenuItemBlueprint.make({ name: test-click, params: { icon: spanTest Icon/span, useProps: () ({ title: Example onClick, onClick: () window.alert(Hello world!), disabled: false, }), }, });5.5 Catalog 前端与后端其他改进backstage/plugin-catalog1.29.0目录表格支持基于 system 列system columns的过滤。backstage/plugin-catalog-backend1.32.1修复了queryEntities传入orderField参数时返回重复结果的问题。backstage/plugin-catalog-react1.17.0entityRouteParams现在同时接受实体引用entity refs并能帮助编码结果参数新增overview实体内容分组useEntityList中 offset 分页在过滤条件更新时会正确重置。backstage/plugin-catalog-unprocessed-entities0.2.16删除实体时增加确认弹窗并修复了 FailedEntities 组件中 ISO 8601 日期字符串的本地时区解析。六、软件模板Scaffolder变更6.1 publish:github 默认分支改为 main破坏性变更backstage/plugin-scaffolder-backend-module-github0.7.0中publish:github动作在创建新仓库时默认使用 main 作为初始分支而不再是 master。如果你或你的组织依赖新仓库默认分支为 master必须在现有模板中显式设置defaultBranch: master- id: publish name: Publish action: publish:github input: allowedHosts: [github.com] description: This is ${{ parameters.name }} repoUrl: ${{ parameters.repoUrl }} defaultBranch: master该变更同时同步到了backstage/create-app0.6.1的模板中。6.2 大量 GitHub 动作改为幂等Idempotent本版本对 scaffolder 的多个 GitHub 动作做了幂等化处理重复执行不会产生副作用或报错publish:github0be1a1egithub:autolinks:create1af427agithub:deployKey:create79dc5acgithub:branch-protection:create180ea6egithub:actions:dispatcha833f0f类似的幂等化也覆盖了其他平台的发布动作publish:azureazure 模块、publish:bitbucket、publish:bitbucketCloud、sentry:project:create、notification:sendnotifications 模块以及github:repo:create对分支更新的支持。幂等化对自动化工作流和失败重试场景意义重大。6.3 新增 template-extensions 服务端点backstage/plugin-scaffolder-backend1.32.0新增 template-extensions 服务端点75e4db4前端侧backstage/plugin-scaffolder1.30.0与backstage/plugin-scaffolder-react1.15.0同步增加了获取模板扩展信息的 API。同时scaffolder_task_duration和scaffolder_step_duration直方图指标新增了template与step标签8685cab。createTemplateFilter与createTemplateGlobalFunction现在会基于 zod schema 校验内置过滤器与全局函数的类型497d47a。6.4 渲染 Schema 翻译键结构调整破坏性 ALPHAbackstage/plugin-scaffolder1.30.0把 schema 渲染组件抽取为独立组件相应地翻译键从actionsPage.content.tableCell.*迁移到独立的根键renderSchema.*... - tableCell: { - name: Name, - title: Title, - description: Description, - type: Type, - }, - noRowsDescription: No schema defined, ... renderSchema: { tableCell: { name: Name, title: Title, description: Description, type: Type, }, undefined: No schema defined, },6.5 GitLab 模块细节改进backstage/plugin-scaffolder-backend-module-gitlab0.9.0分支已创建时提供额外反馈gitlab:group:ensureExists的path字段支持多段路径如group/subgroupgitlab:repo:push的commitAction属性补充了更完整的说明。七、CLI 与开发体验cli0.32.07.1 新增backstage-cli repo start命令v1.38.0 引入repo start命令用于替代仓库内原有yarn dev脚本组合。它会默认运行仓库中的 app 和/或 backend 包如果无法唯一确定则回退到运行其他单个前端/后端包甚至插件开发入口。最有价值的是--plugin pluginId标志可以直接运行指定插件的开发入口。安装方式替换原有yarn start脚本{ scripts: { start: backstage-cli repo start } }为帮助已有项目迁移建议在根package.json中增加如下重定向脚本{ scripts: { dev: echo \Use yarn start instead\, start-backend: echo \Use yarn start backend instead\ } }新命令安装完成后运行yarn start --help可查看完整帮助。这与repo test的定位一致目标是把仓库内本地开发统一到yarn start一个入口。backstage/create-app0.6.1的模板也已同步移除yarn dev。7.2 React 19 迁移准备移除默认 React 导入CLI 从模板文件中移除了默认 React 导入并新增一条 ESLint 规则禁止import React from react与import * as React from react写法对应官方 JSX transform 规范。受影响的包遍及整个仓库的前端生态core-components、frontend-plugin-api、catalog、scaffolder、techdocs、home、search、kubernetes、notifications、user-settings、theme、canon等changeseta47fd39。CLI 会在检测到默认 React 导入时给出指向 JSX transform 指南的警告。7.3 其他 CLI 修复修复repo lint在带--max-warnings选项时失败的问题。修复start命令对多个--require标志的处理。为有多个入口点的包自动添加导入时避免尾部出现多余的/*。更新 TODO 插件模板不再使用已废弃的 catalog alpha 服务引用如遇相关测试失败推荐迁移到新的 catalog service reference。Dev 环境下的证书字符串改为可选。依赖升级module-federation/enhanced至^0.9.0修复安全公告 GHSA-593f-38f6-jp5m。八、Canon 组件库canon0.3.0与事件系统8.1 Canon 组件库的破坏性变更与新组件backstage/canon0.3.0是 Canon 设计系统组件库的重要迭代破坏性变更新增TextField组件以取代原有的Field与Input组件官方理由是需要构建更具主见的组件以避免未来问题。新组件Select、Collapsible、Avatar、TableCellProfile用于 Table/DataTable、DataTable含列尺寸调整支持。类名结构重构改用 data attributes 替代 class names 组织类名结构df4e292。样式与工具改进TextField/Select适配 React Hook Form新增up()、down()与当前断点相关的 breakpoint 辅助函数新增明暗主题统一的灰度色板新增全局 anchor 标签 CSS resetContainer 最大宽度调整为120rem并优化小屏内边距修复暗色主题下 Checkbox 样式、小尺寸 Select 样式、Icon组件找不到名称时返回null而非空 SVG等问题。8.2 Events 事件系统模块导出方式变更backstage/plugin-events-backend-module-github0.3.0与backstage/plugin-events-backend-module-gitlab0.3.0的模块导出方式发生 ALPHA 破坏性变更改为default导出此前为命名导出并从alpha移入public。另外GitHub/GitLab 事件后端不再因未配置webhookSecret而硬失败而是选择不添加 ingress。九、权限系统与集成改进9.1 权限后端校验增强backstage/plugin-permission-backend0.6.0改进了/authorize端点的校验当基础权限basic permission同时提供了resourceRef时会给出更清晰的错误提示同时为用户试图直接评估条件权限conditional permissions的情况引入了更明确的错误信息。9.2 OIDC 登录提供方自定义超时backstage/plugin-auth-backend-module-oidc-provider0.4.2新增自定义超时设置可在配置中声明auth: oidc: production: clientId: ${AUTH_GOOGLE_CLIENT_ID} clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET} timeout: seconds: 309.3 其他集成细节GitHubwebhookSecret配置属性标记为可选创建 GitHub App 时并非必需backstage/integration1.16.3。Bitbucket Cloud 认证模块启用 scope 持久化integration-react为 Bitbucket Cloud 增加projectscope。Bitbucket Cloud 基于事件的发现修复了触发不必要 API 调用的问题。TechDocs 的 AWS/Azure 文件检索逻辑从存入 buffer 数组改为直接 pipe 到 response降低内存占用plugins/techdocs-nodeReportIssueaddon 修复了不支持的仓库类型下的渲染问题与 shadow DOM 事件处理。十、升级到 v1.38.0 的行动清单根据上文所有变更升级前请逐项核对检查项影响包需要做什么filters.branch含斜杠catalog-backend-module-github移除斜杠改用不含斜杠的分支名publish:github默认分支scaffolder-backend-module-github如需 master模板中显式加defaultBranch: masterCatalogFilterBlueprint导入路径catalog / catalog-react改为从backstage/plugin-catalog-react/alpha导入renderSchema翻译键scaffolder把actionsPage.content.tableCell.*迁移到renderSchema.*GitHub/GitLab 事件模块导入events-backend-module-github/gitlab改为default导入Field/Input组件canon迁移到新的TextFieldyarn dev脚本create-app / cli改用backstage-cli repo start可加重定向脚本自定义 rootHttpRouter configurebackend-defaults若未调用applyDefaults()手动设置backend.trustProxy默认 React 导入全部前端包删除import React from react遵循新 ESLint 规则官方还提供了 Upgrade Helper 工具可通过指定目标版本1.38.0获得逐包升级指导。升级完成后建议运行yarn start --help熟悉新的repo start命令并重点关注 gateway-backend 与 frontend-dynamic-feature-loader 这两个新成员它们是分布式 Backstage 部署与动态前端插件体系的关键拼图。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考