企业官网建设流程全解析

Backstage v1.32.0 版本解读：Auth 身份解析安全加固、CLI 命令重构与新前端系统演进

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

本文基于 Backstage 仓库的 v1.32.0 官方发布说明 编写，系统梳理该版本引入的破坏性变更、新特性与升级路径：包括移除不安全的profileEmailMatchingUserEntityEmail登录解析器、为emailLocalPartMatchingUserEntityName新增allowedDomains域名白名单、CLI 大量废弃命令的替换方案、新后端系统插件导出从/alpha提升为默认导出、以及新前端系统与 Scaffolder 模板编辑器的一系列增强。读者在阅读后可以掌握从 v1.31.x 平滑升级到 v1.32.0 的完整改造清单，并理解每个变更背后的源码级原理。

版本总览与升级建议

v1.32.0 是一次包含多项BREAKING（破坏性）变更的版本，涉及认证（Auth）、CLI、新前端系统（alpha）等多个层面，同时也带来 Scaffolder UI、事件服务、测试工具等方向的功能增强。官方在发布说明中指出，本版本不包含任何安全修复（Security Fixes）。

升级建议与常规做法一致：保持你的 Backstage 项目与最新版本同步，详细升级指引可参考 keeping Backstage updated。逐条变更的完整记录见 v1.32.0-changelog。此外，Backstage 的版本化与支持策略遵循其 versioning policy，升级前建议先阅读该策略以了解各版本线的支持周期。

破坏性变更（一）：Auth 身份解析器安全加固

v1.32.0 对登录身份解析（sign-in resolver）机制做了一次安全导向的清理，主要包含两点：

1. 完全移除profileEmailMatchingUserEntityEmail解析器。该解析器在用户实体未出现在软件目录（Catalog）时使用了不安全的回退逻辑来解析用户身份，因此被彻底删除。
2. 为emailLocalPartMatchingUserEntityName新增allowedDomains选项。这一选项让运维人员可以限制仅允许来自本组织指定域名的邮箱完成登录，官方强烈建议使用该解析器的安装环境配置此选项。

allowedDomains配置示例

在app-config.yaml中，于对应 auth provider 的signIn.resolvers下配置：

auth: providers: github: development: ... signIn: resolvers: - resolver: emailLocalPartMatchingUserEntityName allowedDomains: - acme.org

allowedDomains是一个字符串数组，可配置多个允许的域名；只有邮箱域名命中白名单的用户才能完成登录，否则登录会被拒绝。

源码层面的实现原理

在仓库源码 plugins/auth-node/src/sign-in/commonSignInResolvers.ts 中，emailLocalPartMatchingUserEntityName的实现逻辑清晰可查：

• 它通过profile.email.split('@')提取邮箱的 local part（@前部分）作为 Catalog 中用户实体的name；
• 若配置了allowedDomains，则对邮箱域名做精确匹配（allowedDomains.includes(domain)），不匹配时抛出NotAllowedError('Sign-in user email is not from an allowed domain')拒绝登录；
• 该解析器还支持dangerouslyAllowSignInWithoutUserInCatalog选项，用于在 Catalog 中不存在对应用户时仍允许登录（注意选项名中的 "dangerously" 提示，需谨慎使用）。

同样位于该文件的emailMatchingUserEntityProfileEmail解析器（按邮箱完整匹配spec.profile.email）仍然保留，它同样支持allowedDomains，并内置了对joe+work@acme.com这类 plus addressing 邮箱的处理逻辑（commonSignInResolvers.ts）。多个 auth provider 模块的config.d.ts（例如 google provider 配置、oidc provider 配置）也都声明了allowedDomains字段，说明该选项对所有通用解析器生效。

移除后的替代方案：自定义 sign-in resolver

如果你原本依赖profileEmailMatchingUserEntityEmail的"Catalog 中无用户也能登录"能力，官方建议通过自定义 sign-in resolver 来实现。完整的身份解析器文档见 identity-resolver，其中"Building Custom Resolvers"一节给出了标准实现模式：移除默认的 provider module 导入，改用createBackendModule+createOAuthProviderFactory（或createProxyAuthProviderFactory）构造自定义 provider，并在signInResolver(info, ctx)回调中编写自己的身份映射逻辑。

一个典型的最小示例（源自 identity-resolver 文档）：

import { createBackendModule } from '@backstage/backend-plugin-api'; import { githubAuthenticator } from '@backstage/plugin-auth-backend-module-github-provider'; import { authProvidersExtensionPoint, createOAuthProviderFactory, } from '@backstage/plugin-auth-node'; const customAuth = createBackendModule({ pluginId: 'auth', moduleId: 'custom-auth-provider', register(reg) { reg.registerInit({ deps: { providers: authProvidersExtensionPoint }, async init({ providers }) { providers.registerProvider({ providerId: 'github', factory: createOAuthProviderFactory({ authenticator: githubAuthenticator, async signInResolver(info, ctx) { const { profile: { email } } = info; if (!email) { throw new Error('User profile contained no email'); } // 在这里加入自定义校验逻辑，抛错即可阻止登录 myEmailValidator(email); const [name] = email.split('@'); return ctx.signInWithCatalogUser({ entityRef: { name } }); }, }), }); }, }); }, }); backend.add(import('@backstage/plugin-auth-backend')); backend.add(customAuth);

需要注意：使用自定义解析器时，app-config.yaml中该 provider 下不应再包含任何resolvers字段，否则配置中的内置解析器会优先于代码生效。

破坏性变更（二）：CLI 废弃命令清理

v1.32.0 对backstage-cli做了一次集中清理，删除了多个已废弃命令，替换关系如下表：

如果你在 CI 脚本、package.json的 scripts 或开发文档中使用了上述命令，升级后需要同步替换，否则会报命令不存在。

Jest 配置合并策略调整

除命令清理外，CLI 的 Jest 集成也有一项行为变更：Jest 配置不再从所有父级package.json的jest字段逐级合并，而是只合并"被测包自身"与"仓库根 monorepo"两处jest配置。这意味着中间层包的jest配置将不再生效，如果此前依赖中间层继承，需要把相关配置显式迁移到被测包或根配置中。

破坏性变更（三）：新前端系统弃用项移除

本节仅适用于新前端系统（当前处于 alpha 阶段）的早期使用者。

v1.32.0 移除了一批此前已标记废弃的新前端系统 API：

• createExtension与createExtensionBlueprint方法（包括其.make和.makeWithOverrides）中已废弃的namespace选项被移除；
• 废弃的createExtensionOverrides被移除，统一改用createFrontendModule；
• BackstagePlugin类型被移除，统一使用FrontendPlugin（与新后端系统命名对齐）；
• createApp现在应从@backstage/frontend-defaults导入，而不再是先前已废弃的@backstage/frontend-app-api。

如果你的代码中仍在使用上述 API，升级后需按新写法迁移；若尚未接入新前端系统，可暂不关注本节。

新后端系统：核心插件导出提升为默认导出

新后端系统此前已作为 1.0 正式发布，v1.32.0 在此基础上把核心插件的导出位置从/alpha子路径提升到包的主入口。也就是说，packages/backend/src/index.ts中的插件导入可以这样简化：

-backend.add(import('@backstage/plugin-catalog-backend/alpha')); +backend.add(import('@backstage/plugin-catalog-backend'));

其他核心插件同理。旧的/alpha导出在一段时间内仍然可用，但会在后续版本中彻底移除；不过许多插件模块（module）的接口仍在定型中，可能还会继续保留/alpha导出一段时间。

同时，属于旧后端系统的@backstage/backend-common与@backstage/backend-tasks两个包已被完全弃用并从仓库代码中移除，不再发布新版本。如果尚未迁移出这两个包提供的功能，建议尽快参考 new backend system 文档完成迁移。

Scaffolder UI 改进：模板编辑器升级

v1.32.0 针对 Scaffolder 的模板创建体验做了一系列改进：

• 支持从零绘制模板：现在可以直接使用 Template Editor 从空白开始草拟模板，无需先有一个完整模板再编辑；
• 编辑器布局优化：编辑模板文件时，可以快速访问 Custom Fields Explorer 和已安装 Actions 的文档，方便在编写时查阅可用的自定义字段与内置操作；
• 新增 Publish 按钮：点击后弹出模态框，展示如何将新模板投入生产环境使用的指引。

这些改进降低了模板作者的上手门槛，把"编写—校验—发布"的流程集中到了编辑器内。

新前端系统更新：Blueprint 参数覆盖与 App 默认扩展

本节同样仅适用于新前端系统（alpha）的早期使用者。

通过params覆盖 Blueprint 创建的扩展

现在可以对 Blueprint 创建的扩展通过传递params进行覆盖：

const myExtension = MyBlueprint.make({ params: { myParam: 'myDefault', }, }); const myOverride = myExtension.override({ params: { myParam: 'myOverride', }, });

app插件新增三个默认扩展

app插件现在额外提供三个默认扩展，意味着使用新前端系统起步时无需再手动提供它们：

• scmAuthApiRef的默认实现；
• scmIntegrationsApiRef的默认实现；
• 默认的SignInPage（默认配置为以 Guest 身份登录）。

如需覆盖默认实现，可以在app插件上使用.withOverrides，或者为app插件提供一个FrontendModule并注册另一个SignInPage扩展。需要留意的是，Guest 登录仅适合本地开发与测试环境，生产环境应配置真实的 auth provider（参见 auth overview）。

CLI 改进：缓存、rspack 支持与打包元数据

v1.32.0 的 CLI 面向大型 monorepo 场景做了性能和功能增强：

--successCache选项

backstage-cli repo lint和backstage-cli repo test新增--successCache选项，可以复用此前 CI 构建的成功运行结果，跳过未变更包的重复 lint / test，从而显著加快命令执行。该选项仅建议在 CI 中使用。根据 packages/cli/CHANGELOG.md 的后续演进记录，还可以配合--successCacheDir <path>覆盖默认缓存目录，缓存采用增量存储并在约一周后自动清理旧条目。

注意：在 v1.32.0 之后的版本中，CLI 已迁移参数解析库并将多个 camelCase 标志废弃为 kebab-case 写法（如--successCache→--success-cache），旧写法虽仍可用但会输出弃用警告。新建或维护 CI 脚本时建议直接使用 kebab-case 形式。

rspack 实验性支持

CLI 增加了对 rspack 的实验性支持，通过环境变量EXPERIMENTAL_RSPACK开启（该特性由社区贡献，详见发布说明中的 PR 引用）。开启后前端构建将使用 rspack 作为打包器，适合希望在大型项目中尝试更快构建速度的用户；作为实验特性，建议先在小范围验证。

prepack 自动写入导出特性元数据

对于发布 Backstage 包的用户，CLI 的prepack脚本现在会自动把"导出的特性（feature）信息"写入发布产物中的package.json。这为后续"插件的动态发现与动态加载"等功能打下了数据基础。

API Extractor 更新（repo-tools）

本节仅适用于使用@backstage/repo-toolsCLI 生成 API 报告的场景。

@backstage/repo-tools的 API Extractor 依赖升级到了最新版本，带来两点变化：

1. API 报告文件名格式变更：改为report<entry>.api.md形式，例如report.api.md或report-alpha.api.md；
2. 新增ae-undocumented警告：如果不需要该警告，可通过-o ae-undocumented选项关闭。

仓库内各包的 API 报告文件（如 auth-node 的 report.api.md、oidc provider 的 report.api.md）即采用该命名格式，可对照查看。

事件服务默认全局化

此前，使用events服务的后端实例，其事件只分发给同一实例上的本地观察者，这迫使需要通过事件机制互相通信的插件必须共同部署在同一个后端实例上。

v1.32.0 改进了这一限制：只要部署了@backstage/plugin-events-backend，在采用拆分部署（split deployments）架构时，它会自动充当一个高效的中介总线，在所有后端实例之间分发事件。因此，升级到该版本后，你可能会观察到事件开始在机器之间流动——这是预期行为。

从 plugins/events-backend/CHANGELOG.md 可以看到该能力的实现脉络：events 后端内置了跨实例事件总线，暴露/bus/v1/HTTP API 用于发布与读取事件，并自带存储与事件通知机制。这也呼应了 BEP 中 0014-connection-service 等关于后端连接能力演进的方向。拆分部署的架构说明可参考 new backend system 文档。

新的测试工具：mockApis 与 Catalog Mock

v1.32.0 在测试设施方面有一批实用的新增：

mockApis统一导出

• @backstage/test-utils与@backstage/frontend-test-utils新增mockApis导出，可一键创建常见 utility API 的 fake / mock 实现；
• 这与后端已有的@backstage/backend-test-utils中的mockServices相对应；
• 随着新导出引入，旧的Mock*Api类被标记为废弃，请改用mockApis.*。仓库源码中可看到各旧 Mock 类的废弃注释（例如 MockConfigApi 标注了"UsemockApis.(config:namespace)instead"）。

Catalog 相关的专用 Mock

• @backstage/plugin-catalog-react/testUtils提供catalogApiMock，可以构造一个"行为与真实 Catalog 客户端一致、内部填充一组伪造实体"的测试客户端；
• @backstage/plugin-catalog-node/testUtils提供catalogServiceMock，用于后端侧的服务级 Mock。

在仓库测试代码中已有大量应用示例，例如 EntityLifecyclePicker.test.tsx 通过catalogApiMock.mock()一行即可获得完整的 Catalog API Mock。

其他测试体验改进

• API JSON 响应默认美化输出：在开发环境（仅限开发）下，API 的 JSON 响应会默认进行 pretty-print，便于调试；
• OpenAPI 测试设施增强：现在可以基于现有测试直接获得简单的 schema 校验能力，无需额外搭建设施。

升级检查清单

综合以上变更，从旧版本升级到 v1.32.0 时建议按以下清单逐项核对：

1. Auth：检查app-config.yaml中是否使用了已移除的profileEmailMatchingUserEntityEmail解析器；若使用emailLocalPartMatchingUserEntityName，为它配置allowedDomains白名单；
2. CLI 脚本：全局搜索create、create-plugin、plugin:diff、test、versions:check、clean等命令并替换为上表中的新写法；
3. 后端导入：把packages/backend/src/index.ts中核心插件的/alpha导入替换为主入口导入；排查对@backstage/backend-common、@backstage/backend-tasks的依赖并迁移到新后端系统；
4. 新前端系统（如已采用）：移除namespace选项、createExtensionOverrides、BackstagePlugin等废弃 API，createApp改从@backstage/frontend-defaults导入；
5. API 报告（如使用 repo-tools）：更新报告文件命名，按需处理新增的ae-undocumented警告；
6. 测试代码：将旧的Mock*Api迁移到mockApis.*，可按需引入catalogApiMock/catalogServiceMock简化测试。

完成以上核对后，即可按 keeping Backstage updated 的标准流程完成版本升级，并配合 v1.32.0-changelog 核对每个变更的具体实现细节。

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