Backstage v1.15.0 版本全解Material UI v5 统一主题、Scaffolder 新动作与后端缓存默认化【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 v1.15.0-changelog.md 及仓库源码系统梳理 Backstage v1.15.0 的版本升级要点平台级 Material UI v5 支持与UnifiedThemeProvider迁移、后端缓存默认化与启动机制优化、Catalog 筛选器性能重构、Scaffolder 新增的多项 GitHub/GitLab/Bitbucket 动作以及集成层的 Azure DevOps 服务主体认证、GitLab 凭据提供器等能力。读完本文你可以对照自己的app-config.yaml、AppTheme定义与自定义 Scaffolder 模板完成一次有据可依的 v1.15.0 升级评估与落地改造。一、版本概览一次横跨平台、后端与生态插件的大版本v1.15.0 涉及仓库中约 150 个包的同步发布其中出现了一批 Minor新功能与少数BREAKING破坏性变更。下表汇总了本次升级中出现 Minor Changes 的核心包及其主题包版本核心变更主题backstage/app-defaults1.4.0Material UI v5 平台级支持、UnifiedThemeProviderbackstage/theme0.4.0Material UI v5 主题支持、UnifiedThemeProvider生产环境类名去重backstage/backend-common0.19.0默认内存缓存、Azure DevOps 服务主体/托管身份认证、HostDiscovery尾斜杠处理backstage/catalog-model1.4.0target字段弃用、targetRef必填化backstage/errors1.2.0新增ServiceUnavailableErrorbackstage/integration1.5.0GitLab 凭据提供器、Azure DevOps 新认证方式backstage/types1.1.0新增durationToMilliseconds工具函数backstage/test-utils1.4.0测试 Wrapper 改用UnifiedThemeProviderbackstage/plugin-catalog-backend1.10.0冲突事件 EventBroker、OpenAPI 规范整理backstage/plugin-catalog-react1.7.0EntityOwnerPicker性能重构与mode属性backstage/plugin-scaffolder1.14.0新增MyGroupsPicker字段扩展backstage/plugin-scaffolder-backend1.15.0新增 GitHub/Bitbucket/仓库变量动作、isolated-vm沙箱backstage/plugin-catalog-backend-module-unprocessed0.1.0全新插件暴露未处理/处理失败的实体backstage/plugin-catalog-unprocessed-entities0.1.0全新插件上述能力的前端界面backstage/plugin-home-react0.1.0全新包从plugin-home抽取createCardExtensionbackstage/plugin-nomad/plugin-nomad-backend0.1.0全新插件Nomad 作业与分配列表backstage/plugin-github-actions0.6.0GitHub Enterprise 托管仓库支持BREAKINGGithubActionsClient改用scmAuthApibackstage/plugin-linguist-backend0.3.0API 接口化、SQLite 支持BREAKING移除公共构造器backstage/plugin-pagerduty0.6.0配置 schema 定义、首页组件backstage/plugin-sonarqube/sonarqube-backend0.7.0 / 0.2.0配置 schema 大小写修正、API Key 保护backstage/plugin-explore-backend0.0.8Explore 工具改为配置驱动以下各节按技术域深入展开每一节都给出可落地的配置/代码示例并标注仓库中的对应实现位置。二、平台级 Material UI v5 支持迁移到UnifiedThemeProvider2.1 变更背景v1.15.0 最引人注目的变更是Material UI v5 的平台级支持涉及backstage/app-defaults1.4.0、backstage/theme0.4.0与backstage/test-utils1.4.0三个包。此前的 Backstage 生态整体基于 Material UI v4 构建本次变更允许插件与组件在迁移期内同时运行 v4 与 v5 实例为后续逐个插件向 v5 迁移提供了过渡通道。需要说明v1.15.0 只引入 v5 的承载能力theme 与 Provider 支持并非把所有内置插件一次性重写为 v5。迁移是分阶段进行的这也是变更日志中transition phase的由来。2.2UnifiedThemeProvider的使用方式要支持未来的 v5 插件需要把AppTheme的 Provider 从原来的 v4 写法升级为UnifiedThemeProvider。变更日志给出了标准 diffProvider: ({ children }) ( - ThemeProvider theme{lightTheme} - CssBaseline{children}/CssBaseline - /ThemeProvider UnifiedThemeProvider theme{builtinThemes.light} children{children} / ),UnifiedThemeProvider的关键点在于同时为一棵树提供 v4 与 v5 两套主题上下文。从仓库实现 packages/theme/src/unified/UnifiedThemeProvider.tsx 可以看到其内部机制通过theme.getTheme(v4)/theme.getTheme(v5)从UnifiedTheme对象中取出两套主题若存在 v4 主题使用 v4 的StylesProviderThemeProvider包裹并配合createGenerateClassName({ productionPrefix: jss4- })生成独立的生产类名前缀若存在 v5 主题使用 v5 的StyledEngineProviderinjectFirstThemeProvider包裹在模块顶层调用ClassNameGenerator.configure()为 v5 组件统一加上v5-类名前缀避免与 v4 的 JSS 类名在生产环境互相覆盖。这正是 v4/v5 可以共存的底层保障两套主题各自注入、类名隔离。配套的测试位于 packages/theme/src/unified/UnifiedThemeProvider.test.tsx。backstage/test-utils1.4.0的 Test App Wrapper 同样改用UnifiedThemeProvider意味着测试环境也能同时支持 v4 与 v5 组件backstage/theme0.4.0还顺带修复了生产环境下 JSS 类名重叠的问题变更5065a5e8ebd6。2.3 迁移建议检查packages/app/src/App.tsx或自定义 app 中的AppTheme列表把所有自定义Provider改为UnifiedThemeProvider theme{...}形式优先使用内置主题builtinThemes.light/builtinThemes.dark或基于UnifiedTheme接口实现的自定义主题不要期望 v1.15.0 就绪后所有插件立刻变成 v5 渲染——这是过渡版本v4 插件依然被完整支持。三、后端基础设施缓存默认化、发现服务修复与启动健壮性3.1 默认后端缓存改为内存缓存backstage/backend-common0.19.0将默认的CacheClient实现改为内存缓存此前未显式配置缓存时后端不会启用缓存服务现在默认即为内存缓存。相应地app-config.yaml中冗余的显式内存缓存配置可以删除backend: - cache: - store: memory这一变更同样同步到了backstage/create-app0.5.2的脚手架模板中变更52d599817680。如果你在生产环境使用了 Redis/Memcached 等外部缓存backend.cache配置不受影响仅未配置时的默认行为发生了变化而如果你原本依赖无缓存的语义例如通过getClient({ type: redis })之外的代码路径需要注意默认行为已改变。3.2 HostDiscovery 尾斜杠处理与 JSDoc 修复HostDiscovery现在会在读取backend.baseUrl配置时去除尾部斜杠变更eeb3f801fddf避免生成形如https://example.com//api/...的错误服务地址同时修正了HostDiscoveryJSDoc 中的拼写错误9f47a743632c。3.3 启动阶段插件并行初始化与请求暂存机制backstage/backend-app-api0.4.4改进了后端启动流程所有插件并行初始化并接入新的启动生命周期钩子3bb4158a8aa4同时为backend-plugin-api0.5.3增加了 startup hooks在默认HttpService实现中引入内置中间件当插件尚未就绪而无法处理请求时抛出ServiceNotAvailable错误同时引入请求暂存stalling机制在插件完成初始化前暂停进入的请求避免启动窗口期的 502/错误响应2c9f67e6f166错误处理中间件新增对ServiceUnavailableError的处理c4e8fefd9f13。3.4 新错误类型ServiceUnavailableErrorbackstage/errors1.2.0新增ServiceUnavailableError实现于 packages/errors/src/errors/common.ts继承自CustomErrorBase用于表达服务器尚未准备好处理请求这类语义。它被上述后端中间件直接使用前端可借此判断 503 类场景后端错误中间件会将其翻译为对应的 HTTP 响应。四、软件目录Catalog改进4.1EntityOwnerPicker性能重构与mode属性backstage/plugin-catalog-react1.7.0对目录页的EntityOwnerPicker组件做了重要重构变更cb4c15989b6b。旧实现根据EntityListContext中已有的实体来推断 owner 列表在大型目录中会引入明显的开销新实现不再依赖EntityListContext推断而是通过新增的mode属性提供两种加载策略EntityOwnerPicker modeowners-only /默认模式通过 facets 端点异步加载 owner 数据数据缓存在内存中随用户滚动按需渲染。该模式与旧实现保持兼容。EntityOwnerPicker modeall /异步加载 Catalog 中的全部用户与组随滚动分批加载。对于超大型目录更高效缺点是会展示那些并未拥有任何实体的用户/组。前端backstage/plugin-catalog1.11.2同步在CatalogIndexPage上暴露了ownerPickerMode属性CatalogIndexPage ownerPickerModeall /适用于更大的目录规模。从仓库实现 plugins/catalog-react/src/components/EntityOwnerPicker/EntityOwnerPicker.tsx 可以看到组件通过useFetchEntities({ mode, ... })驱动数据获取滚动到底部时利用cursor续拉下一页并配合VirtualizedListbox做虚拟化渲染owners-only模式下直接以 entity ref 字符串走entityPresentationApi的缓存快照避免拉取完整实体对象。相关 hooks 位于 plugins/catalog-react/src/components/EntityOwnerPicker/useFacetsEntities.ts。同一版本还有多项配套改进useRelatedEntities底层改用getEntitiesByRefsd68692aee97e、EntityAutocompletePicker新增initialSelectedOptions属性429319d080cd、EntityLifecycleFilter改用 facets 端点加载数据429319d080cd。4.2 全新插件Unprocessed Entities本次新增了一对前后端插件用于暴露 Catalog 中尚未被处理、或处理失败的实体便于排查处理器异常backstage/plugin-catalog-backend-module-unprocessed0.1.0后端变更d44fcd9829c2backstage/plugin-catalog-unprocessed-entities0.1.0前端其请求层已改用FetchApi而非原生fetch见493eab8c577f。4.3 冲突事件与 schema 演进backstage/plugin-catalog-backend1.10.0新增可选的EventBroker当 Catalog 处理实体时出现冲突conflicts会发送包含冲突详情的事件便于在别处统一处理44c7ad6b8e11同时更新 OpenAPI 规范以符合 lint 标准ee411e7c2623并为 Catalog 添加了性能测试基座b8374d5d93b6。backstage/catalog-model1.4.0在common.schema.json中弃用target字段、将targetRef设为必填33eae4b39a95并移除了EntityRelation对target属性的要求1df5fc954798同时补充了 OpenAPI SpecificationOASv3.1.0 的示例af748a148d52。如果你的自定义 Catalog 提供者仍在写target字段升级后应迁移到targetRef。五、Scaffolder新增动作、字段扩展与沙箱替换5.1 新增字段扩展MyGroupsPickerbackstage/plugin-scaffolder1.14.0新增MyGroupsPicker字段扩展以下拉列表展示当前用户所属的组变更464125e9b1ba可用于模板中需要让用户选择自己的组的场景。实现位于 plugins/scaffolder/src/components/fields/MyGroupsPicker/MyGroupsPicker.tsx其 schema 定义与 alpha 导出分别见 plugins/scaffolder/src/components/fields/MyGroupsPicker/schema.ts 与 plugins/scaffolder/src/alpha/fields/MyGroupsPicker.ts。5.2 后端新增动作GitHub / GitLab / Bitbucketbackstage/plugin-scaffolder-backend1.15.0新增了多项发布类动作github:deployKey:create与github:environment:create1948845861b0分别为仓库创建 Deploy Key 与 Environment。注意需要为 GITHUB_TOKEN 或 Backstage GitHub App 授予 RepositoryAdministrationDeploy Key 功能与EnvironmentsEnvironment 功能的read/write权限。Repository Secrets / Variables 支持df8411779da1同时影响backstage/integration1.5.0与backstage/plugin-catalog-backend-module-github0.3.1publish:github与github:repo:create动作现在支持创建仓库级 Secrets 和 Variables同样需要为令牌/App 授予 RepositorySecrets与Variables的read/write权限。此变更同时升级了 octokit引入了一些BREAKING变化如上游 API 响应结构差异。publish:gitlab:merge-request/publish:github:pull-request新增TargetBranchName变量与输出84b0e47373db并修复了前者不清晰的错误信息b269da39ac2d与repoUrl输入描述中错误的 gitlabUrl 格式11e0f625583f。Bitbucket Server PR 动作新增一个用于在 Bitbucket Server 上创建 Pull Request 的 scaffolder action6a694ce98e32。catalog:register动作修复了optional属性的处理cc936b529676。backstage/plugin-scaffolder-backend-module-confluence-to-markdown0.1.3的confluence:transform:markdown动作新增对Confluence Cloud的支持此前仅支持 Serverc59a4b2b9e0a。5.3 沙箱替换vm2→isolated-vmscaffolder 的任务沙箱从vm2切换为isolated-vma2c70cdda202。这是一项值得特别关注的变更isolated-vm是原生native依赖必须在与运行环境相同的 Node 版本与操作系统上编译在 Docker 中运行时需要确保依赖在容器内部完成安装与编译例如在容器中安装build-essential等编译工具链若安装遇到问题可参考isolated-vm项目自身的安装要求文档变更日志原文给出了其仓库链接。因此升级 v1.15.0 后请重点验证 Docker 镜像构建与yarn install流程是否包含 native 编译能力。5.4 scaffolder-react 与前端体验backstage/plugin-scaffolder-react1.5.0为scaffolder/next体验提供了一系列改进为rjsf提供默认模板组件支持 markdown 描述6b571405f806新增ScaffolderField组件用于替代部分 Material UI 的FormControl简化FieldExtensions的编写6b571405f806搜索无结果时不再渲染TemplateGroups4505dc3b4598修复useTemplateParameterSchema的 TypeScript 类型转换问题a452bda74d7a后端断连时向用户发送通用提示并在15 秒后自动重连84a5c7724c7e从条件分支then/else的 schema 中提取ui:*字段cf34311cdbe1。六、集成与认证层Azure DevOps、GitLab 与 GitHub6.1 Azure DevOps服务主体与托管身份认证backstage/backend-common0.19.0与backstage/integration1.5.0一起支持了Azure DevOps 的服务主体service principal与托管身份managed identity认证c7f848bcea3c同步作用于plugin-catalog-backend-module-azure适用于Azure AD 托管的 Azure DevOps 组织不适用于Azure DevOps Server本地部署组织相比传统 PAT个人访问令牌服务主体/托管身份更适合自动化与云原生身份治理场景配套重构了凭据类命名ClientSecret→AzureClientSecretCredential、ManagedIdentity→AzureManagedIdentityCredential3c83550fdb62。6.2 GitLab 凭据提供器backstage/integration1.5.0为 GitLab 增加了credential providera316d226c780使集成层能以统一的方式为 GitLab 请求提供凭据。backstage/plugin-catalog-backend-module-gitlab0.2.2同步修复了用户昵称/头像缺失时的摄取错误f31fd1f8fd98、新增跳过 fork 仓库的选项66261b4ab441以及低权限 token 下getGroupMembers的修复571f78ed0ea7。6.3 GitHub Enterprise 与 GitHub Actions 插件backstage/plugin-github-actions0.6.0新增GitHub Enterprise 托管仓库支持但这是本版本的BREAKING变更之一GithubActionsClient现在接收scmAuthApi而不是原来的githubAuthApi。若你没有自行构造GithubActionsClient则无需代码改动若有自定义构造请同步更新依赖注入。6.4 其他认证与代理相关修复backstage/plugin-auth-backend0.18.4OIDC 的idToken过期时间被设置为小于 Backstage 会话过期时间d0f5b0c886c2避免 idToken 比会话更早失效导致的鉴权问题backstage/plugin-proxy-backend0.2.40将Authorization与X-Api-Key头标记为 secret避免在前端配置中暴露95987388f26bbackstage/plugin-jenkins-backend0.2.1配置了认证头时不再暴露用户名与认证头0f93b6707e04并通过 metadata 端点暴露权限6c244b42cb06backstage/plugin-kubernetes-backend0.11.1修复了 KubernetesProxy 中 Host 头未透传导致的证书问题4249f4214f9f、configClusterLocator支持加载 app.config 中定义的集群自定义资源eac59a3d0b11、修复 alpha 后端下错误的pluginID5e4879d80f4d、单集群场景下HEADER_KUBERNETES_CLUSTER变为可选91f39df52d60。七、搜索与 Explore7.1 Explore 工具配置化backstage/plugin-explore-backend0.0.8允许通过配置而非代码提供 Explore 工具列表31616c1fc4e4explore: tools: - title: New Relic description: Observability platform built to help engineers create and monitor their software url: /newrelic image: https://i.imgur.com/L37ikrX.jpg tags: - newrelic - performance - monitoring - errors - alerting - title: CircleCI description: Provides builds overview, detailed build info and retriggering functionality for CircleCI. url: /circleci image: https://miro.medium.com/max/1200/1*hkTBp22vLAqlIHkrkZHPnw.png tags: - circleci - ci - dev # [...]原先在packages/backend/src/plugins/explore.ts中以代码方式构造ExploreTool[]并调用StaticExploreToolProvider.fromData(tools)的写法可简化为直接读取配置- import { ExploreTool } from backstage/plugin-explore-common; - const exploreTools: ExploreTool[] [ - { - title: New Relic, - description: Observability platform built to help engineers create and monitor their software, - url: /newrelic, - image: https://i.imgur.com/L37ikrX.jpg, - tags: [newrelic, performance, monitoring, errors, alerting], - }, - { - title: CircleCI, - description: Provides builds overview, detailed build info and retriggering functionality for CircleCI., - url: /circleci, - image: https://miro.medium.com/max/1200/1*hkTBp22vLAqlIHkrkZHPnw.png, - tags: [circleci, ci, dev], - }, - ]; - - StaticExploreToolProvider.fromData(tools) StaticExploreToolProvider.fromData(env.config)7.2 搜索模块的多项修复backstage/plugin-search1.3.2修复SearchModal与HomePageSearchBar在按回车时使用搜索栏引用值避免等待查询状态防抖e8c55c063b88修复SearchBar样式并更新 Storybook stories2f660eb573ccbackstage/plugin-search-backend-module-explore0.1.2collator 支持可选的tokenManager以认证对 explore 后端的请求indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: ToolDocumentCollatorFactory.fromConfig(env.config, { discovery: env.discovery, logger: env.logger, tokenManager: env.tokenManager, }), });backstage/plugin-search-backend-module-pg0.5.7Postgres 搜索查询过滤器现在支持在数组字段中进行值搜索3c09e8d3cb0cbackstage/plugin-search-react1.6.2修复SearchCheckbox组件的键盘可达性无障碍问题0134c1aa4f36。八、DevTools、技术文档与其他生态插件8.1 DevTools 与配置安全backstage/plugin-devtools-backend0.1.1通过 metadata 端点暴露权限c312192e61ddbackstage/plugin-devtools0.1.1更新了 Docker 用户文档62d191f6c8b5并提示 Config 标签页中 secrets 的展示方式bbe15f70c5ccbackstage/plugin-sonarqube-backend0.2.0提供了完整的配置 schema 定义特别是保护 API Key 不被泄露到前端配置0bb0b19b0da2backstage/plugin-pagerduty0.6.0也补充了配置 schema 以通过 CLI 的--strict校验64bc274a1ee6。8.2 TechDocsbackstage/plugin-techdocs1.6.4文档页面支持打印与导出 PDFe33beb1f2a8eplugin-techdocs-node1.7.2默认使用最新的 techdocs Docker 镜像含安全更新7d4a09304f67backstage/plugin-adr0.6.2/adr-backend0.3.4为 MADR v3 格式的 ADR 渲染/解析 front matter 元数据表58524588448c。8.3 其他值得关注的点backstage/types1.1.0新增durationToMilliseconds工具函数a5c5491ff50cbackend-app-api与config-loader已改用该函数替代各自的本地实现backstage/config-loader1.3.1修复了key 中含/的配置项被错误处理的问题f25427f665f7backstage/core-app-api1.8.1修复了navigate分析事件在EntityLayout、TabbedLayout等路由扩展聚合场景下无法记录准确插件与路由数据的问题12adfbc8fe2d并支持通过discovery.endpoints配置驱动FrontendHostDiscoveryac677bc30ae0backstage/core-components0.13.2Pod Drawer 增加资源利用率展示4e697e88f0e2、SidebarSubmenuItem新增exact属性66ae4d8ca380、文档页面可打印e33beb1f2a8e等backstage/plugin-kubernetes0.9.2Pod Drawer 增加错误展示与proposed fix修复建议对话框4b230b97660d、73cc0deee48abackstage/plugin-linguist-backend0.3.0BREAKING移除LinguistBackendApi的公共构造器、移除LinguistBackendDatabase与LinguistBackendStore的导出LinguistBackendApi接口化并由新的LinguistBackendClient实现新增 SQLite 支持便于本地开发未处理实体优先于过期实体被处理数据库中已不在 Catalog 的实体将被删除backstage/cli0.22.8build-workspace新增--alwaysYarnPack标志用于在yarn pack与npm pack结果不一致的罕见场景下保证产物准确性314493fa32a0CLI 增加对 Material UI v5 的 lint 规则以控制 bundle 体积20b7da6f1311onboard 命令新增 discovery 功能6816352500a7repo-tools新增schema openapi lint命令ee411e7c2623。九、升级行动清单综合以上变更从旧版本升级到 v1.15.0 时建议按如下顺序排查主题层将自定义AppTheme的 Provider 切换为UnifiedThemeProvider参考第二节的 diff并验证 v4 插件渲染正常后端配置删除app-config.yaml中冗余的backend.cache.store: memory显式配置确认生产外部缓存配置不受影响Scaffolder若使用publish:github/github:repo:create确认 GITHUB_TOKEN 或 GitHub App 已获得 Secrets、Variables、Administration、Environments 等对应权限为 Docker 镜像补充 native 编译工具链以支持isolated-vm将GithubActionsClient的githubAuthApi替换为scmAuthApi若自定义构造Catalog把自定义处理器中已弃用的target字段迁移到targetRef如目录规模较大可选用CatalogIndexPage ownerPickerModeall /集成如需 Azure DevOps评估服务主体/托管身份认证替代 PAT为 Explore 工具列表考虑迁移到app-config.yaml配置化测试由于test-utils已改用UnifiedThemeProvider运行测试套件确认无主题相关回归CLI 已在 jest 的jsdom环境中补齐fetch5d692f72ebfb跨环境测试行为会统一。完整发布说明参见 docs/releases/v1.15.0.md历史版本对比可查阅 docs/releases 目录下的其他版本文档。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考