
Backstage v1.32.0-next.2 预发布解读认证安全强化、Catalog 否定过滤与 Scaffolder 分支保护动作【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章围绕 Backstage 官方仓库的 v1.32.0-next.2 变更日志 展开系统梳理该预发布版本在认证身份解析、Catalog 实体过滤、Scaffolder 模板动作、CLI 工具链、后端优雅关闭与 TechDocs 渲染等方向的核心变更并逐一结合仓库源码给出实现依据。读完本文你将掌握本次迭代中所有 Minor Changes含 BREAKING CHANGES的来龙去脉、受影响包清单与升级注意事项能够在实际升级到该版本时快速定位需要调整的配置与代码。版本定位与升级方式v1.32.0-next.2是 Backstage 1.32.0 正式发布前的第二个预发布next版本属于候选迭代的一部分。整个变更日志覆盖 90 余个包包含 7 个 Minor Changes其中 3 个标注 BREAKING CHANGES以及大量 Patch Changes。升级时可通过官方提供的 Upgrade Helper 工具生成从当前版本到目标版本的升级脚本该工具按版本差异自动比对依赖与配置可显著降低逐包手动升级的成本对于国内用户建议优先参考仓库内的 官方升级指南 与 版本策略 了解 Backstage 的语义化版本约定。按语义化版本规则-next预发布版本不等于最终正式版本正式发布前仍可能继续引入调整生产环境升级建议等待 1.32.0 正式版发布后再执行。需要特别注意的是本次迭代中的三个 BREAKING CHANGES 主要影响认证模块与旧版legacy后端系统的用户下文逐一展开。认证与身份解析删除不安全回退、新增域名白名单本次迭代中认证方向共有两个 Minor Changes一个删除、一个新增共同目标是收紧用户身份解析的安全性。BREAKING移除profileEmailMatchingUserEntityEmail解析器backstage/plugin-auth-backend-module-vmware-cloud-provider0.4.0-next.1将profileEmailMatchingUserEntityEmail登录解析器sign-in resolver标记为BREAKING 删除。变更日志给出的原因是该解析器依赖一种不安全的用户身份回退机制当目录中找不到对应用户时直接以邮箱构造身份完成登录存在被冒用身份的风险。该模块的认证器实现位于 authenticator.ts 及配套测试解析器层面的安全边界统一由 commonSignInResolvers.ts 维护。官方文档 identity-resolver 提供了目录中无用户时如何登录的完整指导如需替代方案可按该文档自行编写自定义解析器并显式决定是否启用目录外登录回退。新增emailLocalPartMatchingUserEntityName支持allowedDomains域名白名单backstage/plugin-auth-node0.5.3-next.1为通用解析器emailLocalPartMatchingUserEntityName新增了allowedDomains配置项该变更同步写入多个认证提供方模块Atlassian、AWS ALB、Bitbucket、Cloudflare、GCP IAP、GitHub、GitLab、Google、Microsoft、OAuth2、OIDC、Okta、OneLogin 等的配置 schema。从源码看该解析器位于 commonSignInResolvers.ts#L94-L131其工作流程为从用户资料中取出profile.email若缺失则直接报错拒绝登录以切分邮箱取 local part 作为 Catalog 中用户实体的name匹配键若配置了allowedDomains则校验邮箱域名是否在白名单内不在则抛出NotAllowedError最终调用ctx.signInWithCatalogUser完成登录可通过dangerouslyAllowSignInWithoutUserInCatalog显式开启目录外回退。对应的选项 schema 定义report.api.md为allowedDomains?: string[]。典型配置示例以 GitHub 提供方为例auth: providers: github: production: clientId: ${AUTH_GITHUB_CLIENT_ID} clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} signIn: resolvers: - resolver: emailLocalPartMatchingUserEntityName allowedDomains: - example.com - corp.example.org配置后仅来自上述域名的邮箱允许通过该解析器登录其它域名的用户会被拒绝并收到 Sign-in user email is not from an allowed domain 错误。这是对企业邮箱域名管控场景的直接增强。Catalog实体过滤新增否定关键字backstage/plugin-catalog1.24.0-next.2的 Minor Changecec8e8c为前端实体过滤entity filtering新增了否定negation关键字允许用户表达不包含某标签/某类型的过滤语义。实现位于 parseFilterExpression.ts核心要点过滤表达式解析器新增negation标记L102-L127通过!前缀识别否定项例如!typefoo在匹配阶段否定项被包装为(entity) !matcher(entity)L81即取反原匹配结果语法上支持!与普通项混用例如kindcomponent,!typefoo表示类型为 component 且不是 foo。配套测试 parseFilterExpression.test.ts 覆盖了否定与肯定表达式混用、多参数如kindcomponent,user、冒号值withmultiple:colons等边界场景验证了negation: true与negation: false的解析结果。该能力对在 Catalog 页面上编写更精确的筛选条件非常实用。Scaffolder新增github:branch-protection:create动作backstage/plugin-scaffolder-backend-module-github0.5.1-next.2新增模板动作github:branch-protection:create用于为已存在的仓库创建分支保护规则。变更日志给出的完整用法示例- id: set-branch-protection name: Set Branch Protection action: github:branch-protection:create input: repoUrl: github.com?repobackstageownerbackstage branch: master enforceAdmins: true # default requiredApprovingReviewCount: 1 # default requireBranchesToBeUpToDate: true # default requireCodeOwnerReviews: true dismissStaleReviews: true requiredConversationResolution: true从源码看该动作的实现封装在 gitHelpers.ts底层调用 GitHub REST API 的repos.updateBranchProtection默认值enforceAdmins true被直接映射为 GitHub 的enforce_admins参数。测试用例 githubBranchProtection.test.ts 与 githubBranchProtection.examples.test.ts 对updateBranchProtection的调用参数分支名、review 数量、code owner 审查等做了逐项断言。该动作可与publish:github等发布动作串联在软件模板中实现创建仓库后自动配置分支保护的完整自动化链路。同版本还有两个相关小改进publish:gitlab的output.projectId类型修正为 numberbackstage/plugin-scaffolder-backend-module-gitlab0.6.0-next.2以及publish:bitbucketServer:pull-request新增reviewers输入参数。CLI 与构建工具链--successCache加速 CIbackstage/cli0.28.0-next.2在命令backstage-cli repo test与backstage-cli repo lint上新增--successCache选项缓存各包上次成功运行的校验结果若包未发生变更则跳过重复执行主要面向 CI 场景同时提供--successCacheDir path覆盖默认缓存目录。该功能在 packages/cli/CHANGELOG.md 中有完整演进记录后续版本将缓存键生成与工作区路径解耦、改用加性存储旧条目保留一周后自动清理、并让 lint 缓存尊重.eslintignore与.gitignore。需要提醒的是随 CLI 参数解析迁移到cleye--successCache这类驼峰写法在后续版本已弃用建议直接使用 kebab-case 形式--success-cache以避免未来告警。同版本 CLI 其它变更包括CommonJS 构建输出保留目录结构与 ESM 一致利于 tree shaking 与按需加载、后端包构建时关闭新增包特性检测、--max-warnings支持 lint 命令、SWC 的 Jest 转换关闭输入 source map 解析以及cli-node新增lockfile.getDependencyTreeHash(name)工具方法。后端优雅关闭按顺序执行生命周期钩子backstage/backend-app-api1.0.1-next.1与backstage/backend-defaults0.5.1-next.2共同完善了后端关闭流程插件plugin的生命周期关闭钩子现在先于根root生命周期关闭钩子执行保证业务插件先完成收尾、基础设施后释放资源数据库管理器在根生命周期关闭钩子中尝试关闭所有数据库连接任务调度器在检测到 Backstage 正在关闭时尝试中止所有任务。对应的数据库关闭实现见 DatabaseManager.ts注册关闭钩子与 L117-L144遍历 connector 调用shutdown测试用例 DatabaseManager.test.ts 验证了关闭钩子的注册与调用行为。这些改进让容器滚动更新、SIGTERM 退出等场景下的资源释放更加可靠避免连接泄漏。TechDocs 与主题代码块自定义背景色backstage/theme0.6.0-next.1与backstage/plugin-techdocs1.11.0-next.2共同引入e77ff3dTechDocs 内代码块code block与行内代码inline code的自定义背景色支持主题侧通过 palettes.ts 中新增的backgroundColor字段定义深浅两种配色方案下的默认色板。主题与渲染侧core-components协同使文档阅读体验与 Backstage 全局主题保持一致。同版本 TechDocs 相关改进还包括支持 mkdocs material palette 条件哈希e918061导航侧边栏使用更多可用空间e8b4966同时作用于techdocs-module-addons-contribGCS Publisher 支持传入 StorageOptionsfbdc631作用于 techdocs-node依赖git-url-parse升级至^15.0.0。Bitbucket Cloud 实体提供方以 AuthService 替换 tokenManagerbackstage/plugin-catalog-backend-module-bitbucket-cloud0.4.0-next.2修复了事件驱动的实体更新event-based updates回归问题并伴随BREAKING CHANGES问题背景该实体提供方此前对旧版后端支持可选的catalogApi、events、tokenManager注入新版后端系统的catalog.bitbucket-cloud-entity-provider默认开启事件支持。最近一次改动移除了模块对tokenManager的依赖导致事件驱动更新失效并伴随 info 日志级别的运行时异常修复方式用authAuthService取代tokenManager生成插件间请求令牌同时将catalogApi与events提升为必填依赖影响范围仅影响旧版后端用户——此前可选的catalogApi、events现在必须显式传入并新增必填依赖auth新版后端用户无需任何操作。源码中 BitbucketCloudEntityProvider.ts 的构造函数已改为接收auth: AuthServiceL70、L83、L127印证了依赖注入方式的变更。测试体验OpenAPI 校验内联化与新的 Mock 工具本次迭代在测试基建上有多项值得关注的改进backstage/backend-openapi-utils0.2.0-next.1OpenAPI 校验可以直接在 Jest 测试编写过程中进行不再需要预先运行repo schema openapi test命令同时plugin-search-backend修复了 schema 不允许任意 query 参数的问题backstage/plugin-catalog-react1.14.0-next.2新增/testUtils子路径导出提供 catalog 服务 mock可直接写出const catalog catalogApiMock.mock()并对其getEntities等调用做断言省去繁琐的类型强转backstage/frontend-test-utils0.2.1-next.2新增与后端ServiceMock对应的ApiMock0801db6。其它值得留意的功能与修复plugin-home的 visits API.list()真正实现limit查询参数BREAKING见 VisitsStorageApi.ts、VisitsApi.tsplugin-user-settings的useUserProfile在 IdP 不返回头像时回退使用 Catalog 中存储的用户图片plugin-app-backend修复APP_CONFIG_*环境变量未按配置 schema 过滤的问题plugin-catalog-graph的CatalogGraphCard新增action属性plugin-search的 SearchType.Accordion 在选择结果类型后保持展开以降低点击次数。BREAKING CHANGES 汇总与升级清单包变更类型影响人群需要采取的行动plugin-auth-backend-module-vmware-cloud-provider删除解析器使用 VMware Cloud 认证的用户若依赖profileEmailMatchingUserEntityEmail按 identity-resolver 编写自定义解析器替代plugin-auth-node及多个 provider 模块新增配置使用emailLocalPartMatchingUserEntityName的用户可选配置allowedDomains白名单收紧域名plugin-catalog-backend-module-bitbucket-cloud依赖必填化旧版后端用户为BitbucketCloudEntityProvider显式传入catalogApi、events与authplugin-homelimit 参数生效visits API 调用方确认调用方传入的limit符合预期此前被忽略其余大量 Patch Changes 均为依赖升级如cookie0.6.0 → 0.7.0、kubernetes-models/apimachinery2.0、azure-devops-node-api14.0、git-url-parse15.0与文档补全升级后建议运行yarn tsc与yarn test验证。结语v1.32.0-next.2 是一个典型的安全加固 体验优化 基础设施打磨预发布版本认证侧删除不安全解析器并新增域名白名单、Catalog 引入否定过滤、Scaffolder 补齐分支保护动作、CLI 为 CI 提供缓存加速、后端关闭流程更可靠。升级时请重点对照上文的 BREAKING CHANGES 清单逐项检查尤其是认证配置与旧版后端系统的依赖注入。正式版发布前建议持续关注后续 next 版本变更日志仓库内 docs/releases 目录持续更新再决定最终升级窗口。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考