Backstage v1.19.0-next.2 版本解读前端路由与扩展点重构、GitHub 多 Org 实体 Provider 与破坏性变更迁移指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇基于 docs/releases/v1.19.0-next.2-changelog.md 对 Backstage 预发布版本 v1.19.0-next.2 进行全面解读。该版本是 1.19.0 的第二个 next 预发布迭代横跨 CLI、前端应用框架、认证、Catalog、TechDocs、Scaffolder、Kubernetes 等多个核心领域其中包含多项**破坏性变更Breaking Changes**与新增模块。读者读完本文将掌握.icon.svg图标的迁移方案、attachTo扩展点新写法、认证 Provider 初始化方法签名变化、GitHub 多组织实体 Provider 的配置方法以及 TechDocs 自定义 preparer 的目录清理机制等关键升级点。版本定位与阅读说明Backstage 采用next预发布流水线v1.19.0-next.2是 1.19.0 正式版发布前的第二个候选迭代对应仓库内 docs/releases/v1.19.0-changelog.md 发布记录的组成部分。changelog 按包package维度组织每个包条目分为 Minor Changes新特性/破坏性变更与 Patch Changes缺陷修复两部分。本文按主题归类梳理并对涉及仓库源码的关键变更给出实现级验证。CLI 与构建体系变更backstage/cli0.23.0-next.2TypeScript 5.2 与 typescript-eslint 6.7.x 兼容backstage/cli将typescript-eslint升级到 6.7.x从而与 TypeScript 5.2 兼容。这是一次 typescript-eslint 的主版本升级主要影响在于 ESLint 规则的配置格式与部分规则的默认行为可能变化。升级后建议对现有代码库重新运行 lint 校验观察是否出现因规则版本差异导致的新告警。.icon.svg扩展名废弃与迁移指南重点本版本最需要关注的前端迁移项.icon.svg文件扩展名被正式废弃未来版本将移除。官方给出的理由是该扩展名的实现过度绑定特定版本的 MUI 与 SVGO阻碍了构建系统的演进未来可能通过配置方式在内部插件中重新引入类似能力但当前必须迁移。迁移方式将.icon.svg文件重命名为.tsx把svg元素替换为 MUI 的SvgIcon并补充必要导入。原文档给出的标准示例import React from react; import SvgIcon from material-ui/core/SvgIcon; import { IconComponent } from backstage/core-plugin-api; export const CodeSceneIcon (props: SvgIconProps) ( SvgIcon {...props} g path d... / /g /SvgIcon );该变更在本版本内已在多个插件中完成内部自迁移例如plugin-codescene、plugin-graphiql、plugin-ilert的 Patch Changes 均标注了“Internal refactor to avoid using the deprecated.icon.svgextension”。从源码结构看IconComponent类型定义于 packages/core-plugin-api 中是插件图标的标准类型约定迁移后图标组件将遵循 docs/architecture-decisions/adr006-avoid-react-fc.md 等 ADR 所倡导的显式props传参风格。前端应用与路由体系重构路由解析器对不安全字符进行 URL 编码backstage/core-app-api1.11.0-next.2RouteResolver以及基于它的useRouteRef现在会对若干众所周知的危险字符进行 URL 编码。这意味着插件中通过useRouteRef生成的路由参数如实体名、自定义参数中含空格、#、?等字符时将自动被安全转义避免生成非法或语义被截断的 URL。从源码结构看该逻辑位于 packages/core-app-api 的路由解析模块中对RouteRef/SubRouteRef的useRouteRef使用方式无感知属于透明增强。全应用Suspense包裹与插件外翻译支持core-app-api将整个应用包裹进Suspense从而支持在插件之外使用翻译translations能力。此前懒加载翻译资源仅能在插件组件边界内生效现在应用壳层也具备 Suspense 边界自定义的 Shell 组件、错误边界之外的公共区域也能安全使用翻译 API。新版前端系统的破坏性变更frontend-plugin-api / frontend-app-api0.2.0-next.2面向实验性新前端系统的两个包同步发布 0.2.0包含两项破坏性变更与若干补强移除新的useRouteRef支持frontend-app-api与frontend-plugin-api均移除了新路由系统下实验性的useRouteRef新增对现有路由系统的支持Added support for the existing routing system。这意味着实验性新前端插件应继续使用既有路由 API直到新路由系统正式成型。扩展点挂载配置改为attachTo: { id, input }原先通过at: id/input字符串指定扩展实例的挂载位置现改为结构化对象attachTo: { id, input }。本版本plugin-graphiql、plugin-search-react、plugin-explore、plugin-catalog等多个插件的/alpha导出均已同步更新为attachTo写法。扩展实例实现toString()与toJSON()便于调试与序列化extension instance现在可以被直接打印和 JSON 序列化。认证体系变更含两项破坏性变更GCP IAP Providerinitialize()不再为 asyncBreakingbackstage/plugin-auth-backend-module-gcp-iap-provider0.2.0-next.2将gcpIapAuthenticator.initialize()从异步方法改为同步方法。同步调整也同步到backstage/plugin-auth-node0.4.0-next.2中的ProxyAuthenticator.initialize()其目的是与 OAuth 侧等价实现保持一致。自定义 ProxyAuthenticator / GCP IAP authenticator 的调用方必须去掉await并同步初始化逻辑否则在类型检查阶段即会报错。Microsoft 认证 Provider 迁移为新独立模块Microsoft auth provider 迁移到新的独立模块包backstage/plugin-auth-backend-module-microsoft-provider0.1.0-next.0首个 0.x 版本。backstage/plugin-auth-backend0.19.3-next.2已改为依赖该新模块。这与仓库中 plugins/auth-backend-module-github-provider、plugins/auth-backend-module-google-provider 等既有 provider 模块化趋势一致——各身份提供商逐步拆分为独立 backend module 包便于按需安装。OAuth 刷新修复plugin-auth-node修复了 OAuth refresh handler 响应中 cookie 持久化的 scope 未正确返回的问题对使用带状态 cookie 的 OAuth 流程有直接影响。CatalogGitHub 多组织实体 Provider新模块新增backstage/plugin-catalog-backend-module-github-org0.1.0-next.0这是本版本 Catalog 侧最重要的新增能力新增catalogModuleGithubOrgEntityProvider用于从多个 GitHub 组织organizations摄取用户users与团队teams。同时backstage/plugin-catalog-backend-module-github0.4.4-next.2中移除了原有的catalogModuleGithubOrgEntityProvider调用方必须改为从新包导入。从 plugins/catalog-backend-module-github-org/src/module.ts 的源码可以确认其实现要点模块通过createBackendModule注册pluginId: catalogmoduleId: github-org-entity-provider注册了一个扩展点githubOrgEntityProviderTransformsExtensionPoint提供setUserTransformer与setTeamTransformer两个方法各只能设置一次重复设置会抛错用于自定义 GitHub 用户/团队到 Catalog 实体的转换逻辑每个定义会同时注册GithubOrgEntityCleanerProvider清理已不存在实体的 Provider与基于GithubMultiOrgEntityProvider的实体 Provider配置从catalog.providers.githubOrg键读取支持单对象或对象数组。从 plugins/catalog-backend-module-github-org/src/module.ts 的readDefinitionsFromConfig可确认每个 Provider 定义的可用配置项配置项类型说明idstringProvider 唯一标识必填githubUrlstringGitHub 实例地址必填支持 GitHub Enterpriseorgsstring[]要摄取的 GitHub 组织列表可选scheduleobject调度任务定义使用readSchedulerServiceTaskScheduleDefinitionFromConfig解析pageSizes.teams/pageSizes.teamMembers/pageSizes.organizationMembersnumber分页大小可选excludeSuspendedUsersboolean是否排除被停用的用户默认falseexperimental_checkForSuspendedUsersWithRestboolean实验性是否通过 REST API 检查被停用用户默认falsedefaultUserTransformer.useVerifiedEmailsboolean是否使用已验证邮箱默认false典型配置app-configcatalog: providers: githubOrg: - id: production githubUrl: https://github.com orgs: [org-a, org-b] schedule: frequency: { minutes: 30 } timeout: { minutes: 3 } excludeSuspendedUsers: true同时注意模块注册的 transformer 扩展点不允许重复设置若多个模块试图调用setUserTransformer会抛出 “User transformer may only be set once”。该模块的测试见 plugins/catalog-backend-module-github-org/src/module.test.ts。GitLab Catalog 摄取修复backstage/plugin-catalog-backend-module-gitlab0.3.3-next.2改用 REST API 获取 GitLab SaaS 用户列表的根组root group成员关系该 API 是唯一能展示企业用户email字段、并可用is_using_seat字段过滤未占用许可证的机器人用户的接口同时新增gitlab.com/saml-external-uid注解取值为groups/:group-id/members端点返回的group_saml_identity.extern_uid便于编写引用 IdP如 OneLogin用户 ID 的SignInResolver。TechDocs自定义 preparer 目录清理与 mkdocs 配置文件名shouldCleanPreparedDirectory()新方法自定义 preparer 兼容性要求backstage/plugin-techdocs-backend1.8.0-next.2与backstage/plugin-techdocs-node1.9.0-next.2允许对自定义 preparer 的 prepared 目录进行清理。背景使用自定义 preparer 时preparedDir可能持续占用磁盘空间。因此要求所有自定义 preparer 实现新的shouldCleanPreparedDirectory方法指示文档生成后是否应清理 prepared 目录。仓库源码 plugins/techdocs-backend/src/DocsBuilder/builder.ts 的finally块展示了实际调用逻辑// Remove Prepared directory since it is no longer needed. // Caveat: Can not remove prepared directory in case of git preparer since the // local git repository is used to get etag on subsequent requests. if (preparedDir this.preparer.shouldCleanPreparedDirectory()) { this.logger.debug(Removing prepared directory ${preparedDir}); try { fs.remove(preparedDir); } catch (error) { this.logger.debug(Error removing prepared directory ${...}); } }需要注意源码注释中的关键 caveatgit preparer 场景下不能清理 prepared 目录因为本地 git 仓库会被用于后续请求的 etag 计算。因此shouldCleanPreparedDirectory()应依据 preparer 类型返回相应布尔值——例如 git 类 preparer 返回false其余临时目录型 preparer 返回true。清理失败不会阻塞构建日志级别为 debug不抛异常。--mkdocs-config-file-name命令行参数techdocs/cli1.6.0-next.2以及plugin-techdocs-node为serve命令新增--mkdocs-config-file-name参数允许使用非默认名称mkdocs.yaml/mkdocs.yml之外的 mkdocs 配置文件。例如techdocs-cli serve --mkdocs-config-file-name mkdocs.custom.yamlScaffolderpublish:gitlabAction 能力扩展backstage/plugin-scaffolder-backend1.18.0-next.2对publish:gitlabaction 的属性进行扩展新增三组能力settingsGitLab 项目创建 API 支持的一般项目设置branches分支级设置可创建额外分支并将其设为保护分支projectVariables项目级环境变量设置。同时将原有属性repoVisibility与topics标记为废弃deprecated因其已被settings属性覆盖。使用示例方向模板 YAML 中steps: - id: publish action: publish:gitlab input: repoUrl: gitlab.com?ownerexamplerepomy-service defaultBranch: main settings: visibility: private topics: [backstage] branches: - name: release protected: true projectVariables: - key: DEPLOY_ENV value: production protected: true注意具体字段名与取值以该版本publish:gitlabaction 的 schema 为准迁移时需核对repoVisibility/topics的旧用法。此外本版本还补充了github:issues:label与publish:Azureaction 的示例与测试。后端基础能力调整HostDiscovery迁移破坏性变更backstage/backend-common0.19.8-next.2中的HostDiscovery导出被标记为废弃应改为从backstage/backend-app-api0.5.6-next.2导入。backend-test-utils也已同步更新为从backend-app-api导入HostDiscovery。配置加载器新增watch选项backstage/backend-app-api与backstage/config-loader1.5.1-next.1为配置加载器新增watch选项设置为false可禁用文件监听。对于容器/只读文件系统部署或配置不频繁变化的场景可减少文件系统 watcher 开销。测试工具增强backstage/backend-common新增/testUtils入口点提供用于 mockresolvePackagePath返回的包路径解析的工具函数backstage/backend-test-utils0.2.7-next.2新增createMockDirectory()简化测试中文件系统 mock 的搭建backstage/backend-common修复了基于 zip 的.readTree()响应在写临时归档时未正确关闭写流的问题。OpenAPI 工具类型backstage/backend-openapi-utils0.0.5-next.0新增面向常见 OpenAPI 值的公开工具类型请求/响应形状、端点可用参数等并将internal命名空间标记为废弃——后续应使用新的工具类型。Kubernetes 相关更新新插件backstage/plugin-kubernetes-node0.1.0-next.0用于承载 Kubernetes 后端插件的扩展点当前仅包含KubernetesObjectsProviderExtensionPointkubernetes-backend已改为使用该扩展点。这是 Kubernetes 后端插件向新后端系统扩展点模型演进的第一步。集群管理与认证策略新增backstage/plugin-kubernetes-cluster0.0.1-next.0前端插件管理员可直接在 Backstage 中查看 Kubernetes 集群kubernetes-backend/kubernetes-common/kubernetes-react当请求携带Backstage-Kubernetes-Authorization-*-*头时Kubernetes API 调用会触发认证策略Authentication Strategies执行从而支持需要额外步骤获取 Kubernetes token 的策略如 pinniped 或自定义策略。前端组件与主题细节backstage/theme0.4.3-next.0主题中的fontSize现在既支持数字也支持字符串如2.5rem并为 header 排版变体新增可选fontFamily属性便于自定义头部字体的同时保持fontSize的灵活性backstage/core-components0.13.6-next.2修复WarningPanel中消息溢出overflow的问题backstage/plugin-newrelic-dashboard0.3.0-next.2将DashboardSnapshotList组件公开、梳理导出的 API并废弃DashboardSnapshotComponentbackstage/plugin-tech-insights0.3.17-next.2导出ScorecardInfo与ScorecardsList组件允许直接使用手动查询的 check 结果backstage/plugin-jenkins-backend与backstage/plugin-nomad-backend增加对新后端系统new backend system的支持backstage/plugin-github-issues过滤掉与插件配置的 GitHub 实例不一致的实体backstage/plugin-techdocs1.7.1-next.2DocsTable的分页控件改为按需动态显示backstage/plugin-newrelic修复 NewRelic 表格中的排序与搜索问题backstage/plugin-scaffolder1.15.1-next.2仅有一个可用实体时实体选择器更可靠模板面板显示日志可见性按钮RepoUrlPickerRepoName正确处理允许仓库列表变化。升级与迁移清单按影响面从高到低整理本版本相对上一个 next需要关注的变更.icon.svg→.tsx MUISvgIcon所有前端插件图标需迁移见上文示例codescene、graphiql、ilert等插件已完成内部迁移可参考其源码HostDiscovery导入路径变更后端代码从backstage/backend-common改从backstage/backend-app-api导入gcpIapAuthenticator.initialize()/ProxyAuthenticator.initialize()同步化去掉awaitgithubOrgEntityProvider新模块迁移从backstage/plugin-catalog-backend-module-github改从backstage/plugin-catalog-backend-module-github-org导入并按上文表格配置catalog.providers.githubOrg新前端系统attachTo写法若使用实验性/alpha扩展点需将at: id/input改为attachTo: { id, input }并注意新的useRouteRef已被移除自定义 TechDocs preparer 实现shouldCleanPreparedDirectory()git 类 preparer 返回false其余返回truepublish:gitlab属性迁移repoVisibility/topics迁移到settings按需使用branches与projectVariables。如需查看完整变更明细含所有包级依赖更新请直接阅读 docs/releases/v1.19.0-next.2-changelog.md其后的正式发布记录见 docs/releases/v1.19.0-changelog.md仓库内 docs/releases 目录还维护了全部历史版本 changelog 可供对照。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考