企业官网建设流程全解析

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 余个包同步发布。按变更影响面，可归纳为以下几大类：

此外，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-backend@0.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承担的“回退分支”职责被移交给新键fallbackBranch，而branch被重新定义为“从哪个分支发现 catalog-info 文件”。官方给出的迁移动作就是把旧的branch重命名为fallbackBranch：

catalog: providers: gitlab: yourProviderId: host: gitlab.example.com - branch: main + fallbackBranch: main

若你希望在特定分支上发现 catalog-info，可在迁移后显式设置branch：

catalog: 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

同包的另一个 Patch（commit7b1b7bfdb7b）将 GitLab 组织（org）数据集成中 User 与 Group 实体之间关系的判定改为通过GraphQL API完成。此前该集成依赖管理员账号的个人访问令牌（PAT）才能读取成员关系；改造后，不再要求管理员级别的 PAT即可建立用户-组关系，降低了接入门槛。

Catalog：EntitySwitch新增isResourceType与isEntityWith条件

@backstage/plugin-catalog（1.10.0-next.0）为EntitySwitch组件新增了两个条件辅助函数（commit4dbf3d3e4da、fc6cab4eb48）：

• isResourceType：允许根据 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-scaffolder（1.13.0-next.0）与plugin-scaffolder-react（1.3.0-next.0）是本版本改动最密集的模块，涉及 API 重构与新能力，升级时需重点关注。

破坏性变更：移除routeRefs，改用scaffolderPlugin.routes.x

commitcdab34fd9a2移除了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-react，ContextMenu也一并迁移并更名为ScaffolderPageContextMenu（commit259d3407b9b）。同时该组件从“传布尔值开关”改为“以回调函数作为 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/>组件新增templateFilterprop（commit92cf86a4b5d），允许通过一个纯函数对模板实体进行过滤。类型定义见 Router.tsx：

templateFilter?: (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.1，@rjsf/validator-ajv8升级至5.3.0（commit7a6b16cc506、f84fc7fd040），影响模板表单的渲染与校验行为；
• plugin-scaffolder-backend将publish:gitlab:merge-request动作的输出参数mergeRequestURL重命名为mergeRequestUrl（commite23abb37ec1），若你的模板步骤读取了该输出，需要同步修改；
• 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-backend（0.10.0-next.0）包含另一项破坏性变更（commit804f6d16b0c），围绕权限框架与代理端点的鉴权方式：

1. KubernetesBuilder.create现在要求传入permissions字段，类型为PermissionEvaluator。所有调用方都必须注入权限评估器，以接入 Backstage 的权限框架；
2. /proxy端点改为需要两个 token：
   • Backstage-Kubernetes-Authorization请求头：携带目标集群的 bearer token；
   • Authorization请求头：携带 Backstage 身份令牌（identity token）；
3. /proxy端点要求的集群标识头从X-Kubernetes-Cluster改为Backstage-Kubernetes-Cluster。

plugin-kubernetes-common同步引入了用于权限框架集成的代理权限类型（proxy permission types）。

配套修复

同版本还修复了两个与健壮性相关的问题：当向 Kubernetes 插件提供错误凭据时后端不再崩溃（commit75d4985f5e8）；Kubernetes API 返回结构异常数据时的解析错误得到修复（commit83d250badc6）。

其他值得关注的变更

• 实体反馈匿名聚合端点：plugin-entity-feedback（0.2.0-next.0）与plugin-entity-feedback-backend新增了从实体获取匿名聚合结果的端点（commit7eba760e6f6），可用于在不暴露个人反馈的前提下展示评分/汇总。
• Vault 后端泛化客户端：plugin-vault-backend（0.3.0-next.0）允许向 builder 传入通用的 Vault 客户端（commit5e959c9eb62），不再局限于内置实现。
• 后端进程健壮性：backend-app-api（0.4.2-next.0）注册了unhandledRejection与uncaughtException处理器，避免后端因未处理的 Promise 拒绝或异常直接崩溃（commit8cce2205a39）。
• CLI：@backstage/cli（0.22.6-next.0）新增onboard命令（仍处于开发中），旨在引导用户完成 Backstage 应用的初始化配置（commitc07c3b7364b）；同时修复了Windows 平台上后端启动命令因平台相关路径拼接导致的失败（commitb9839d7135c）。
• TechDocs CLI：@techdocs/cli（1.4.1-next.0）引入global-agent，支持通过代理发布文档（commitb348420a804）。
• GitLab URL 读取：backend-common（0.18.4-next.0）优化了GitlabUrlReader，只加载请求的子路径（commit420164593cf），减少不必要的数据拉取。
• ESLint 插件：@backstage/eslint-plugin（0.1.3-next.0）的no-undeclared-imports规则支持自动修复缺失的导入（commit911c25de59c）。
• UI 细节：core-components修复了BackstageHeaderLabel字体颜色跟随当前激活页面主题的问题（commit7245e744ab1）；search-react与techdocs修复了搜索结果项文本字号/颜色渲染错误（commitb2e182cdfa4）；shortcuts插件允许将外部链接添加为快捷方式（commit99df676e324）；techdocs-react修复了首次生成文档时头部不渲染的问题（commit7e0c7b09a47）。
• Tech Insights：Check类型现在可选包含runChecks调用返回的failureMetadata与successMetadata（commitf538b9c5b83）。

升级迁移清单

将现有实例升级到 v1.13.0-next.0（或后续 v1.13.0 正式版）时，请按以下清单逐项核对：

1. GitLab 目录发现：检查catalog.providers.gitlab.*配置，若使用branch表示回退分支，请重命名为fallbackBranch；如需指定发现分支，使用新的branch键。
2. Scaffolder 路由：将routeRefs引用替换为scaffolderPlugin.routes.x；同步迁移ContextMenu到ScaffolderPageContextMenu并改用回调 props。
3. Scaffolder 输出参数：若模板消费publish:gitlab:merge-request的mergeRequestURL输出，改为mergeRequestUrl。
4. Kubernetes 后端：为KubernetesBuilder.create注入permissions: PermissionEvaluator；更新/proxy请求的请求头（Backstage-Kubernetes-Cluster、Backstage-Kubernetes-Authorization+Authorization）。
5. 认证：如需体验页内重定向登录，在根配置加入enableExperimentalRedirectFlow: true，并回归验证各 provider 的登录、刷新与登出流程。
6. 依赖版本：确认@rjsf/*已升级至 5.3.x 且模板表单行为符合预期；同步升级@backstage/plugin-scaffolder-backend-module-gitlab等新包（如需要）。

更多发布相关文档可参阅仓库中的 docs/releases 目录，其中按版本归档了各里程碑的完整 changelog；Backstage 的升级流程总体介绍见 docs/getting-started/keeping-backstage-updated.md。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage