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机制做了一次安全导向的清理主要包含两点完全移除profileEmailMatchingUserEntityEmail解析器。该解析器在用户实体未出现在软件目录Catalog时使用了不安全的回退逻辑来解析用户身份因此被彻底删除。为emailLocalPartMatchingUserEntityName新增allowedDomains选项。这一选项让运维人员可以限制仅允许来自本组织指定域名的邮箱完成登录官方强烈建议使用该解析器的安装环境配置此选项。allowedDomains配置示例在app-config.yaml中于对应 auth provider 的signIn.resolvers下配置auth: providers: github: development: ... signIn: resolvers: - resolver: emailLocalPartMatchingUserEntityName allowedDomains: - acme.orgallowedDomains是一个字符串数组可配置多个允许的域名只有邮箱域名命中白名单的用户才能完成登录否则登录会被拒绝。源码层面的实现原理在仓库源码 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并内置了对joeworkacme.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 导入改用createBackendModulecreateOAuthProviderFactory或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做了一次集中清理删除了多个已废弃命令替换关系如下表已移除命令替代命令createbackstage-cli newcreate-pluginbackstage-cli newplugin:diffbackstage-cli fixtestbackstage-cli repo test或backstage-cli package testversions:checkyarn dedupe或npx yarn-deduplicatecleanbackstage-cli package clean如果你在 CI 脚本、package.json的 scripts 或开发文档中使用了上述命令升级后需要同步替换否则会报命令不存在。Jest 配置合并策略调整除命令清理外CLI 的 Jest 集成也有一项行为变更Jest 配置不再从所有父级package.json的jest字段逐级合并而是只合并被测包自身与仓库根 monorepo两处jest配置。这意味着中间层包的jest配置将不再生效如果此前依赖中间层继承需要把相关配置显式迁移到被测包或根配置中。破坏性变更三新前端系统弃用项移除本节仅适用于新前端系统当前处于 alpha 阶段的早期使用者。v1.32.0 移除了一批此前已标记废弃的新前端系统 APIcreateExtension与createExtensionBlueprint方法包括其.make和.makeWithOverrides中已废弃的namespace选项被移除废弃的createExtensionOverrides被移除统一改用createFrontendModuleBackstagePlugin类型被移除统一使用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 依赖升级到了最新版本带来两点变化API 报告文件名格式变更改为reportentry.api.md形式例如report.api.md或report-alpha.api.md新增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 Mockv1.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 相关的专用 Mockbackstage/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 时建议按以下清单逐项核对Auth检查app-config.yaml中是否使用了已移除的profileEmailMatchingUserEntityEmail解析器若使用emailLocalPartMatchingUserEntityName为它配置allowedDomains白名单CLI 脚本全局搜索create、create-plugin、plugin:diff、test、versions:check、clean等命令并替换为上表中的新写法后端导入把packages/backend/src/index.ts中核心插件的/alpha导入替换为主入口导入排查对backstage/backend-common、backstage/backend-tasks的依赖并迁移到新后端系统新前端系统如已采用移除namespace选项、createExtensionOverrides、BackstagePlugin等废弃 APIcreateApp改从backstage/frontend-defaults导入API 报告如使用 repo-tools更新报告文件命名按需处理新增的ae-undocumented警告测试代码将旧的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考