Backstage v1.13.0-next.0 版本解析认证重定向流、GitLab 发现配置迁移与 Scaffolder 增强实战指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南基于 Backstage 官方仓库发布的 v1.13.0-next.0 变更日志docs/releases/v1.13.0-next.0-changelog.md系统梳理该里程碑中涉及认证、目录发现、Scaffolder、Kubernetes 等核心模块的破坏性变更与新能力。读完本文你将掌握enableExperimentalRedirectFlow的开启方法及其与弹窗流的本质区别、GitLab 目录发现配置branch/fallbackBranch的一键迁移方案、EntitySwitch新条件辅助函数的使用姿势以及 Scaffolder 路由 API 重构后的正确写法可直接对照应用到自有 Backstage 实例的升级工作中。版本概览本里程碑涉及哪些包v1.13.0-next.0 是 v1.13.0 系列的首个预发布next版本全仓共有 60 余个包同步发布。按变更影响面可归纳为以下几大类变更主题关键包变更等级认证重定向流enableExperimentalRedirectFlowapp-defaults、core-app-api、test-utils、core-components、plugin-auth-backendMinor新增配置GitLab 目录发现配置破坏性变更plugin-catalog-backend-module-gitlabBreaking0.2.0CatalogEntitySwitch新条件plugin-catalogMinor新增 APIScaffolder 路由/上下文菜单 API 重构plugin-scaffolder、plugin-scaffolder-reactMinor含 Breaking新增 GitLab Scaffolder 插件plugin-scaffolder-backend-module-gitlabMinor0.1.0 新包Kubernetes 代理端点权限改造plugin-kubernetes-backendBreaking0.10.0实体反馈匿名聚合端点plugin-entity-feedback、plugin-entity-feedback-backendMinor新增端点Vault 后端泛化客户端plugin-vault-backendMinor此外backend-app-api、cli、backend-common、techdocs、search、tech-insights等包也有若干值得关注的 Patch 修复。认证体系开启enableExperimentalRedirectFlow切换到页内重定向登录本里程碑最受关注的变更commit7908d72e033是为全局配置引入一个新的布尔参数enableExperimentalRedirectFlow。当它被启用时Backstage 的认证过程将不再通过**弹窗popup完成而是采用窗口内重定向in-window redirect**流程。该变更同时落在backstage/app-defaults、backstage/core-app-api、backstage/test-utils、backstage/core-components以及backstage/plugin-auth-backend五个包中说明它贯穿了前端连接器与后端认证服务的完整链路。配置方式在根级app-config.yaml或任意被加载的配置文件中加入# app-config.yaml enableExperimentalRedirectFlow: true该配置项通过ConfigApi.getOptionalBoolean(enableExperimentalRedirectFlow)读取默认值为false未配置时保持原有弹窗行为。源码视角popup 与 redirect 的双路径实现在 DefaultAuthConnector.ts 中DefaultAuthConnector构造函数会解析该配置并注册认证请求器this.enableExperimentalRedirectFlow configApi ? configApi.getOptionalBoolean(enableExperimentalRedirectFlow) ?? false : false; this.authRequester oauthRequestApi.createAuthRequester({ provider, onAuthRequest: async scopes { if (!this.enableExperimentalRedirectFlow) { return this.showPopup(scopes); } return this.executeRedirect(scopes); }, });两条路径的关键差异体现在实现细节上showPopup(scopes)L221-L245拼接/start端点 URL携带scope、origin、flow: popup参数通过openLoginPopup打开 450×730可通过popupOptions.size调整的独立登录窗口等待窗口回传 payload 后再做 session 变换。executeRedirect(scopes)L247-L258拼接/start端点 URL 并额外携带redirectUrl: window.location.href与flow: redirect参数随后直接执行window.location.href ...整页跳转并返回一个永不 resolve 的 Promise登录完成后由后端重定向回redirectUrl完成会话恢复。值得注意的兼容处理在createSession中当存在instantPopup请求时两种模式下都会直接绕过authRequester走对应路径L131-L141。适用场景与注意事项命名中的Experimental表明该能力在 v1.13.0-next.0 阶段仍属实验特性启用前应充分验证自有环境的认证链路。重定向流更适合禁用弹窗的浏览器环境或需要与第三方 IdP 深度集成的部署但整页跳转会打断 SPA 状态需要确认应用能正确处理redirectUrl回跳后的会话恢复。后端侧配套变更见backstage/plugin-auth-backend0.18.2-next.0其中还包括对证书与 client secret 的密钥可见性强制校验commitd8f774c30df认证后端会强制要求证书与客户端密钥按 secret 处理并补充了各认证插件的已知配置项文档。GitLab 目录发现branch语义变更与fallbackBranch迁移backstage/plugin-catalog-backend-module-gitlab在本版本从 0.1.x 升到0.2.0包含一项破坏性配置变更commitf64345108a0直接影响使用GitlabDiscoveryEntityProvider的部署。变更前后语义对照配置键旧语义新语义branch项目未定义默认分支时使用的回退分支发现catalog-info文件所用的分支fallbackBranch不存在项目自身未定义默认分支时使用的回退分支简而言之原本branch承担的“回退分支”职责被移交给新键fallbackBranch而branch被重新定义为“从哪个分支发现 catalog-info 文件”。官方给出的迁移动作就是把旧的branch重命名为fallbackBranchcatalog: providers: gitlab: yourProviderId: host: gitlab.example.com - branch: main fallbackBranch: main若你希望在特定分支上发现 catalog-info可在迁移后显式设置branchcatalog: providers: gitlab: yourProviderId: host: gitlab.example.com branch: catalog-branch # 从该分支发现 catalog-info.yaml fallbackBranch: main # 项目未定义默认分支时的回退分支源码视角配置解析与默认值在 providers/config.ts 中readGitlabConfig对这两个键的解析如下const branch config.getOptionalString(branch); const fallbackBranch config.getOptionalString(fallbackBranch) ?? master;即branch未配置时为undefined由 provider 内部逻辑决定实际使用的分支而fallbackBranch的默认值是master与 GitLab 默认主分支命名一致。该 provider 的完整配置还支持group、host必填、entityFilename默认catalog-info.yaml、projectPattern、groupPattern、orgEnabled、relations、schedule等键均可在同一 provider 配置块中按需设置。GitLab Org 数据集成改用 GraphQL同包的另一个 Patchcommit7b1b7bfdb7b将 GitLab 组织org数据集成中 User 与 Group 实体之间关系的判定改为通过GraphQL API完成。此前该集成依赖管理员账号的个人访问令牌PAT才能读取成员关系改造后不再要求管理员级别的 PAT即可建立用户-组关系降低了接入门槛。CatalogEntitySwitch新增isResourceType与isEntityWith条件backstage/plugin-catalog1.10.0-next.0为EntitySwitch组件新增了两个条件辅助函数commit4dbf3d3e4da、fc6cab4eb48isResourceType允许根据 Resource 的spec.type展示不同视图与已有的isComponentType、isApiType对齐isEntityWith通用的条件构造器接受{ kind, type }谓词对象用于组合任意 kind 与 type 的匹配。源码视角统一的条件实现两个新 API 都定义在 conditions.ts 中。isEntityWith是底层实现其余辅助函数均基于它构建export interface EntityPredicates { kind?: string | string[]; type?: string | string[]; } export function isEntityWith(predicate: EntityPredicates) { return (entity: Entity) { if (predicate.kind !strCmpAll(entity.kind, predicate.kind)) { return false; } if (predicate.type !strCmpAll(entity.spec?.type, predicate.type)) { return false; } return true; }; } export function isResourceType(types: string | string[]) { return isEntityWith({ kind: resource, type: types }); }注意strCmpAll的匹配细节kind与type均可接受字符串或字符串数组传入数组时只要命中其中任意一个即视为匹配比较采用大小写不敏感的字符串比对L25-L35。使用示例在实体页路由中按 Resource 类型分流import { EntitySwitch, isResourceType } from backstage/plugin-catalog; import { Grid } from material-ui/core; // 对不同 spec.type 的 Resource 展示不同卡片 EntitySwitch EntitySwitch.Case if{isResourceType(kubernetes-cluster)} Grid item md{6} KubernetesClusterInfoCard / /Grid /EntitySwitch.Case EntitySwitch.Case if{isResourceType([database, message-queue])} Grid item md{6} GenericResourceCard / /Grid /EntitySwitch.Case /EntitySwitch由于isEntityWith同时接受 kind 与 type也可以用它构造任意组合例如isEntityWith({ kind: system })。该版本的plugin-catalog还清理了开发期控制台告警commit8e00acb28db主要涉及 techdocs 相关渲染路径。Scaffolder路由 API 重构、模板过滤与任务取消plugin-scaffolder1.13.0-next.0与plugin-scaffolder-react1.3.0-next.0是本版本改动最密集的模块涉及 API 重构与新能力升级时需重点关注。破坏性变更移除routeRefs改用scaffolderPlugin.routes.xcommitcdab34fd9a2移除了scaffolder/next中的routeRefs导出路由引用统一改为挂在插件实例上的scaffolderPlugin.routes.x-import { scaffolderApiRef, routeRefs } from backstage/plugin-scaffolder; import { scaffolderApiRef } from backstage/plugin-scaffolder; import { scaffolderPlugin } from backstage/plugin-scaffolder;对应到scaffolder-react侧CategoryPicker从scaffolder包移入scaffolder-reactContextMenu也一并迁移并更名为ScaffolderPageContextMenucommit259d3407b9b。同时该组件从“传布尔值开关”改为“以回调函数作为 props”commit2cfd03d7376以提供更细粒度的定制能力import { ScaffolderPageContextMenu } from backstage/plugin-scaffolder-react; ScaffolderPageContextMenu onEdit{handleEdit} onPublish{handlePublish} onRegister{handleRegister} /scaffolder-react还导出了TemplateGroupFilter与TemplateGroups这两个可扩展组件commit48da4c46e45并在plugin-scaffolder-common中导出了isTemplateEntityV1beta3类型守卫。新能力templateFilter按函数过滤模板列表Router/组件新增templateFilterpropcommit92cf86a4b5d允许通过一个纯函数对模板实体进行过滤。类型定义见 Router.tsxtemplateFilter?: (entity: TemplateEntityV1beta3) boolean;用法示例Router templateFilter{entity entity.metadata?.annotations?.[example.com/team] platform } /同时TemplateListPage与TemplateWizardPage也改为可作为 props 传入commite5ad1bd61ec便于自定义列表页与向导页的实现。新能力{ exists: true }过滤器commit57c1b4752fa为模板的catalogFilter过滤逻辑引入了{ exists: true }特殊取值用于筛选存在某个键无论其值是什么的实体。官方示例是筛选所有设置了someAnnotation注解的 Group# template.yaml ui:options: catalogFilter: kind: Group metadata.annotations.someAnnotation: { exists: true }新能力取消正在运行的任务commite27ddc36dad为 Scaffolder 增加了取消正在执行的任务模板执行的能力涉及scaffolder-backend、scaffolder-backend内部的任务存储/任务代理层DatabaseTaskStore、StorageTaskBroker以及scaffolder-node多个包的协同实现。前端可据此提供取消按钮终止长时间运行的模板任务。其他配套变更rjsf/*相关依赖升级至5.3.1rjsf/validator-ajv8升级至5.3.0commit7a6b16cc506、f84fc7fd040影响模板表单的渲染与校验行为plugin-scaffolder-backend将publish:gitlab:merge-request动作的输出参数mergeRequestURL重命名为mergeRequestUrlcommite23abb37ec1若你的模板步骤读取了该输出需要同步修改plugin-catalog-backend的by-query端点新增全文搜索支持commit899ebfd8e02供目录查询使用。新包GitLab Scaffolder 插件backstage/plugin-scaffolder-backend-module-gitlab以0.1.0首次发布commit1ad400bb2de为 Scaffolder 提供面向 GitLab 的动作集。源码结构见 plugins/scaffolder-backend-module-gitlab/src包含actions/动作实现与autocomplete/自动补全等目录。安装后即可在模板 steps 中使用 GitLab 相关的发布与集成动作例如与上述publish:gitlab:merge-request配合完成 MR 工作流。Kubernetes 后端代理端点的令牌与权限改造backstage/plugin-kubernetes-backend0.10.0-next.0包含另一项破坏性变更commit804f6d16b0c围绕权限框架与代理端点的鉴权方式KubernetesBuilder.create现在要求传入permissions字段类型为PermissionEvaluator。所有调用方都必须注入权限评估器以接入 Backstage 的权限框架/proxy端点改为需要两个 tokenBackstage-Kubernetes-Authorization请求头携带目标集群的 bearer tokenAuthorization请求头携带 Backstage 身份令牌identity token/proxy端点要求的集群标识头从X-Kubernetes-Cluster改为Backstage-Kubernetes-Cluster。plugin-kubernetes-common同步引入了用于权限框架集成的代理权限类型proxy permission types。配套修复同版本还修复了两个与健壮性相关的问题当向 Kubernetes 插件提供错误凭据时后端不再崩溃commit75d4985f5e8Kubernetes API 返回结构异常数据时的解析错误得到修复commit83d250badc6。其他值得关注的变更实体反馈匿名聚合端点plugin-entity-feedback0.2.0-next.0与plugin-entity-feedback-backend新增了从实体获取匿名聚合结果的端点commit7eba760e6f6可用于在不暴露个人反馈的前提下展示评分/汇总。Vault 后端泛化客户端plugin-vault-backend0.3.0-next.0允许向 builder 传入通用的 Vault 客户端commit5e959c9eb62不再局限于内置实现。后端进程健壮性backend-app-api0.4.2-next.0注册了unhandledRejection与uncaughtException处理器避免后端因未处理的 Promise 拒绝或异常直接崩溃commit8cce2205a39。CLIbackstage/cli0.22.6-next.0新增onboard命令仍处于开发中旨在引导用户完成 Backstage 应用的初始化配置commitc07c3b7364b同时修复了Windows 平台上后端启动命令因平台相关路径拼接导致的失败commitb9839d7135c。TechDocs CLItechdocs/cli1.4.1-next.0引入global-agent支持通过代理发布文档commitb348420a804。GitLab URL 读取backend-common0.18.4-next.0优化了GitlabUrlReader只加载请求的子路径commit420164593cf减少不必要的数据拉取。ESLint 插件backstage/eslint-plugin0.1.3-next.0的no-undeclared-imports规则支持自动修复缺失的导入commit911c25de59c。UI 细节core-components修复了BackstageHeaderLabel字体颜色跟随当前激活页面主题的问题commit7245e744ab1search-react与techdocs修复了搜索结果项文本字号/颜色渲染错误commitb2e182cdfa4shortcuts插件允许将外部链接添加为快捷方式commit99df676e324techdocs-react修复了首次生成文档时头部不渲染的问题commit7e0c7b09a47。Tech InsightsCheck类型现在可选包含runChecks调用返回的failureMetadata与successMetadatacommitf538b9c5b83。升级迁移清单将现有实例升级到 v1.13.0-next.0或后续 v1.13.0 正式版时请按以下清单逐项核对GitLab 目录发现检查catalog.providers.gitlab.*配置若使用branch表示回退分支请重命名为fallbackBranch如需指定发现分支使用新的branch键。Scaffolder 路由将routeRefs引用替换为scaffolderPlugin.routes.x同步迁移ContextMenu到ScaffolderPageContextMenu并改用回调 props。Scaffolder 输出参数若模板消费publish:gitlab:merge-request的mergeRequestURL输出改为mergeRequestUrl。Kubernetes 后端为KubernetesBuilder.create注入permissions: PermissionEvaluator更新/proxy请求的请求头Backstage-Kubernetes-Cluster、Backstage-Kubernetes-AuthorizationAuthorization。认证如需体验页内重定向登录在根配置加入enableExperimentalRedirectFlow: true并回归验证各 provider 的登录、刷新与登出流程。依赖版本确认rjsf/*已升级至 5.3.x 且模板表单行为符合预期同步升级backstage/plugin-scaffolder-backend-module-gitlab等新包如需要。更多发布相关文档可参阅仓库中的 docs/releases 目录其中按版本归档了各里程碑的完整 changelogBackstage 的升级流程总体介绍见 docs/getting-started/keeping-backstage-updated.md。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
