Backstage v1.24.0-next.0 深度解析新认证服务落地、EventsService 迁移与 Guest 登录【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库中的 v1.24.0-next.0 变更日志逐条剖析这一里程碑版本的核心变更BEP-0003 认证架构演进的正式落地新AuthService/HttpAuthService/UserInfoService服务工厂、事件系统从EventBroker到EventsService的整体迁移、全新的 Guest 登录提供者、Scaffolder 任务检查点幂等性以及 Notifications 插件重构。读完本文你将掌握 v1.24.0 引入的破坏性变更清单、相应的迁移代码路径以及这些新能力对应的仓库源码位置可直接用于升级你的 Backstage 实例。版本定位next.0预发布与升级前提v1.24.0-next.0是 v1.24.0 正式版之前的第一个预发布prerelease快照。与正式变更日志不同next.0快照用于在发布周期早期让社区验证破坏性变更。从本日志可以看到几乎所有包都带有-next.0后缀且存在大量BREAKING破坏性变更标注升级前应充分评估。本仓库的 docs/releases/ 目录收录了从 v1.0.0 至今的完整版本历史可作为版本演进对照参考。头条变更BEP-0003 认证架构演进正式落地v1.24.0-next.0 最核心的变化是将 BEP-0003 Auth Architecture Evolution 中设计的三个新后端服务接入到核心包中。该 BEP 提出的目标包括开箱即用地保护 Backstage 实例、以 cookie 方式认证静态资源请求、服务间通信不再直接复用用户 token改为 On-Behalf-Of 封装以及将所有权信息从用户 token 中剥离。新的核心服务工厂backstage/backend-app-api0.6.0-next.0新增了三个服务工厂对应的coreServices引用在backstage/backend-plugin-api0.6.13-next.0中同步加入authAuthService底层服务负责所有类型身份用户、服务、代表用户的服务的认证与 bearer token 签发。在 BEP 文档 中定义了BackstageCredentials以及BackstageUserPrincipal、BackstageServicePrincipal、BackstageNonePrincipal等主体类型credentials对象替代了过去到处传递的裸 token。httpAuthHttpAuthService高层服务用于保护插件路由的端点读取入站请求的凭据与身份并为出站请求签发凭据。userInfoUserInfoService负责提供用户所有权等身份信息。日志中特别提到 Made theDefaultUserInfoServiceclaims check stricter收紧了 claims 校验并指出所有权信息将从用户 token 中逐步迁移到该服务。默认认证策略拒绝未认证请求这是 v1.24.0 最重要的安全默认值变更对于已迁移到新后端系统的实例入站请求如果未携带 Backstage bearer token 或后端 token 进行正确认证将被拒绝。此前实例默认是开放的现在变成了 secure-by-default。如果你希望某些路由允许匿名访问或仅凭 cookie 访问需要在新版httpRouter服务上调用新增的addAuthPolicy方法声明豁免。这是对插件作者提出的显式 opt-out 机制由插件自身决定端点保护策略。迁移兼容层createLegacyAuthAdapters对于尚未完全迁移到新后端系统的老式插件backstage/backend-common0.21.3-next.0新增了createLegacyAuthAdapters兼容适配器它接受新的auth、httpAuth服务作为输入并同时输出旧式的IdentityService/TokenManagerService形态帮助插件逐步过渡。createLegacyAuthAdapters现在也接受UserInfoApi作为可选输入与输出。同时backstage/backend-defaults0.2.13-next.0已默认安装新认证服务。波及面最广的破坏性变更discovery服务前传为了支撑新认证服务大量后端插件的构造入口现在强制要求把discovery服务从插件环境中前传进来。日志中明确列出的受影响入口包括backstage/plugin-auth-backend0.22.0-next.0CatalogIdentityClient构造函数与createRouter函数均新增discovery依赖。backstage/plugin-azure-sites-backend0.3.0-next.0createRouter新增discovery。backstage/plugin-devtools-backend0.3.0-next.0createRouter新增discovery。backstage/plugin-jenkins-backend0.4.0-next.0createRouter与DefaultJenkinsInfoProvider.fromConfig均新增discovery同时JenkinsInfoProvider接口改为接收BackstageCredentials类型的credentials而非裸 token。backstage/plugin-kubernetes-backend0.16.0-next.0KubernetesBuilder.createBuilder新增discovery。backstage/plugin-lighthouse-backend0.4.5-next.0createScheduler新增discovery。backstage/plugin-catalog-backend1.18.0-next.0CatalogBuilder.create新增discovery选项推荐前传否则回退到HostDiscovery。典型迁移模式为在构造插件 router 时从env中取出discovery并传入构造函数/createRouter。权限系统同步演进backstage/plugin-permission-backend0.5.36-next.0createRouter新增auth、httpAuth、userInfo选项内部使用可忽略正式迁移到 BEP-0003 新认证服务。backstage/plugin-permission-node0.7.24-next.0ServerPermissionClient实现PermissionsService接口新增BackstageCredentials参数token选项标记为废弃。backstage/plugin-permission-common0.7.13-next.0PermissionEvaluator的token选项废弃后端专用选项迁移到PermissionsService。backstage/plugin-auth-node0.4.8-next.0废弃getBearerTokenFromAuthorizationHeader函数由新的HttpAuthService取代。测试工具支持backstage/backend-test-utils0.3.3-next.0在测试后端中默认提供新认证服务可通过mockServices.auth、mockServices.httpAuth、mockServices.userInfo访问 mock 版本并新增mockCredentials用于获取各类凭据的 mock方便编写新认证体系下的后端测试。事件系统从 EventBroker 全面迁移到 EventsServicev1.24.0-next.0 对事件系统做了一次彻底的重构对应 PR 56969b6 与 eff3ca9。backstage/plugin-events-node0.3.0-next.0新增EventsService接口与eventsServiceRef作为EventBroker的替代品。为什么要迁移日志给出的理由是旧的EventsExtensionPoint实现于新后端系统早期不尊重插件隔离plugin isolation与新后端系统不再兼容同时旧接口暴露了过多内部细节。新方案中发布者publisher与订阅者subscriber不再实现EventPublisher/EventSubscriber接口而是直接接收EventsService并在内部使用。废弃清单新增EventsService、eventsServiceRef、TestEventsService废弃EventBroker、EventPublisher、EventSubscriber、DefaultEventBroker、EventsBackend、EventsExtensionPointalpha的大部分、TestEventBroker、TestEventPublisher、TestEventSubscriberDefaultEventBroker被废弃但仍作为兼容包装存在内部委托给新的DefaultEventsService可传入实例以支持混合部署mixed setups。迁移示例HttpPostIngressEventPublisherbackstage/plugin-events-backend0.3.0-next.0中HttpPostIngressEventPublisher.fromConfig现在要求events: EventsService选项const http HttpPostIngressEventPublisher.fromConfig({ config: env.config, events: env.events, logger: env.logger, }); http.bind(eventsRouter); // e.g. at packages/backend/src/plugins/events.ts - await new EventsBackend(env.logger) - .setEventBroker(env.eventBroker) - .addPublishers(http) - .start(); // or for other kinds of setups - await Promise.all(http.map(publisher publisher.setEventBroker(eventBroker)));eventsPlugin现在依赖eventsServiceRef从backstage/plugin-events-node导入废弃的扩展点方法调用会直接抛错以防止意外行为。迁移示例EventRouter 实现所有EventRouter实现SubTopicEventRouter、AzureDevOpsEventRouter、BitbucketCloudEventRouter、GerritEventRouter、GithubEventRouter、GitlabEventRouter的签名全部变更涉及的模块包括plugin-events-backend-module-azure0.2.0、-bitbucket-cloud0.2.0、-gerrit0.2.0、-github0.2.0、-gitlab0.2.0。以SubTopicEventRouter子类为例import { EventParams, EventsService, SubTopicEventRouter, } from backstage/plugin-events-node; export class GithubEventRouter extends SubTopicEventRouter { - constructor() { - super(github); constructor(options: { events: EventsService }) { super({ events: options.events, topic: github, }); } protected getSubscriberId(): string { return GithubEventRouter; } // ... }直接扩展EventRouter的写法变化为构造函数接收options含events、topicssuper({ events, topics })并实现getSubscriberId()取代旧的supportsEventTopics()。迁移示例AWS SQS 消费发布者backstage/plugin-events-backend-module-aws-sqs0.3.0-next.0中AwsSqsConsumingEventPublisher.fromConfig同样要求events选项并改为直接调用publisher.start()const sqs AwsSqsConsumingEventPublisher.fromConfig({ config: env.config, events: env.events, logger: env.logger, scheduler: env.scheduler, }); await Promise.all(sqs.map(publisher publisher.start())); // e.g. at packages/backend/src/plugins/events.ts - await new EventsBackend(env.logger) - .setEventBroker(env.eventBroker) - .addPublishers(sqs) - .start();Bitbucket Cloud Catalog Provider 的配套迁移backstage/plugin-catalog-backend-module-bitbucket-cloud0.2.0-next.0同步将BitbucketCloudEntityProvider迁移到EventsServicefromConfig接受可选的events: EventsServiceEventSubscriber接口含supportsEventTopics()、onEvent(params)被移除事件订阅在connect(connection)时完成const bitbucketCloudProvider BitbucketCloudEntityProvider.fromConfig( env.config, { catalogApi: new CatalogClient({ discoveryApi: env.discovery }), events: env.events, logger: env.logger, scheduler: env.scheduler, tokenManager: env.tokenManager, }, ); - env.eventBroker.subscribe(bitbucketCloudProvider);新后端系统下可通过 alpha 入口直接添加模块事件支持始终开启但未收到事件时不会发生更新/刷新backend.add( import(backstage/plugin-catalog-backend-module-bitbucket-cloud/alpha), );新插件Guest Provider 真正签发 tokenbackstage/plugin-auth-backend-module-guest-provider0.1.0-next.0是本次发布的全新包。此前 Backstage 的 guest 登录只是纯前端行为SignInPage的guest提供者不产生真实 token新模块把 guest 用户映射为真实签发的 token。默认实体引用变更默认 guest 用户实体从旧的user:default/guest改为user:development/guest以减少与生产/真实数据的重叠。若需改回旧默认值或自定义使用新的auth.providers.guest.userEntityRef配置键auth: providers: guest: userEntityRef: user:default/guestownershipEntityRefs 配置新增ownershipEntityRefs属性控制 guest 用户的所有权实体引用auth: providers: guest: ownershipEntityRefs: - guests - development/custom从仓库源码 config.d.ts 可以看到三个配置项的完整定义与默认值userEntityRefguest 用户使用的实体引用默认user:development/guestownershipEntityRefs当 guest 用户在 catalog 中找不到时用于其所有权的一组实体引用默认[userEntityRef]dangerouslyAllowOutsideDevelopment是否允许在非开发环境NODE_ENV ! development使用 guest 提供者。安全护栏在 authenticator.ts 中可以看到实现细节authenticator 通过createProxyAuthenticator创建initialize阶段读取dangerouslyAllowOutsideDevelopment配置若处于非开发环境且未显式开启该开关认证时authenticate会抛出NotAllowedError提示必须开启auth.providers.guest.dangerouslyAllowOutsideDevelopment。也就是说guest 登录默认只在开发环境可用生产环境需显式放行。前端侧backstage/core-components0.14.1-next.0的SignInPageguest提供者支持用该模块生成 token并保留旧的前端纯认证作为回退。Scaffolder任务检查点与 Mock 上下文统一backstage/plugin-scaffolder-backend1.22.0-next.0引入checkpoints检查点用于 scaffold 任务 action 的幂等性对应 BEP-0004 主题该 BEP 在本仓库beps/目录下可查阅。检查点允许任务在失败重试时跳过已完成的 action 阶段避免重复执行副作用步骤提升任务可靠性。backstage/plugin-scaffolder-node0.3.3-next.0同步引入检查点支持。同时backstage/plugin-scaffolder-node-test-utils0.1.0-next.0作为新包发布提供createMockActionContext统一了创建 scaffold action mock 上下文的方式便于在 action context 结构变化时长期维护测试。该工具被plugin-scaffolder-backend-module-*系列azure、bitbucket、bitbucket-cloud、bitbucket-server、confluence-to-markdown、cookiecutter、gerrit、gitea、github、gitlab、rails、sentry、yeoman广泛使用。此外backstage/plugin-scaffolder-node还修复了非 UTF-8 数据在 fetch contents 时的文件损坏问题85f4723。Notifications从任务管理回归消息系统backstage/plugin-notifications0.1.0-next.0、plugin-notifications-backend0.1.0-next.0与plugin-notifications-common0.0.2-next.0三个包同时首发0.1.0前端重构通知界面重设计为列表视图 紧凑行详情。移除done属性让 Notifications 回归消息系统定位而不是任务管理器对应 BEP-0001 notifications system 的设计演进。新过滤能力支持按创建日期Created Date过滤通知。plugin-notifications-backend迁移到新认证服务84af361并依赖plugin-signals-node与plugin-events-node。Catalog 与集成相关变更自定义 EntityDataParserbackstage/plugin-catalog-backend1.18.0-next.0与backstage/plugin-catalog-node1.8.0-next.0允许通过CatalogModelExtensionPoint设置EntityDataParserdf12231为需要自定义实体数据解析逻辑的场景提供扩展入口。Catalog 性能与可用性backstage/plugin-catalog-backend在 search 表中为 original value 增加索引280edeb加速实体 facet 响应。backstage/plugin-catalog1.17.1-next.0/alpha插件的实体页面扩展现在能正确渲染实体 404 页面spec.target字段加入 catalog 表搜索范围此前仅spec.targets使GithubEntityProvider等 provider 生成的 location 可在 catalog 表中被搜索到。backstage/plugin-catalog-react1.10.1-next.0为EntityAutocompletePicker、EntityOwnerPicker、EntityProcessingStatusPicker新增root与labelclass keyplugin-scaffolder-react为TemplateCategoryPicker也新增了同类 class key。Azure DevOps自定义 README 路径backstage/plugin-azure-devops0.4.0-next.0、-backend0.6.0、-common0.4.0三包新增能力从不同的 Azure DevOps 路径拉取 README 文件。默认保持 Azure DevOps 原生行为git 仓库根目录的README.md如需自定义路径在实体上添加注解dev.azure.com/readme-path: /my-path/README.md同时AzureDevOpsClient不再需要identityApi改为要求fetchApi遵循 ADR-013 的 fetch 统一策略。其他值得关注的变更backstage/plugin-kubernetes-common0.7.5/plugin-kubernetes-react0.3.1支持获取Daemon Sets数据并以与 Deployments 相同的手风琴方式展示。backstage/theme0.5.2导出defaultTypography方便自定义主题时调整排版值。backstage/cli0.25.3新增.ico导入支持f4404e5。backstage/errors1.2.4修复ResponseError未正确报告响应 HTTP 状态的问题。backstage/backend-common0.21.3修复resolveSafeChildPath在 symlink 上的路径解析问题e0b997c。backstage/plugin-search-backend-node1.2.17从plugin-search-common抽取并导出QueryTranslator、QueryRequestOptions、SearchEngine类型token属性废弃并让位于新的 credentials 属性plugin-search-common中对应类型标记废弃。backstage/plugin-catalog-backend-module-github0.5.3GithubLocationAnalyzer迁移到新认证服务。主要依赖升级minimatch升级到 v9多个包jose升级到 v5auth 相关模块uuid/types/uuid升级到 ^9mysql2升级到 ^3、yauzl升级到 ^3、google-auth-library升级到 ^9testcontainers升级到 ^10backend-test-utilsjson-schema-to-ts升级到 ^3backend-openapi-utilsmarked升级到 ^12adr-backend升级行动清单综合以上变更升级到 v1.24.0 时建议按以下顺序处理评估认证迁移如果使用新后端系统确认新auth/httpAuth/userInfo服务已由backend-defaults默认提供为需要匿名或 cookie 访问的路由调用httpRouter.addAuthPolicy声明豁免。补齐discovery前传逐一对齐 auth-backend、azure-sites、devtools、jenkins、kubernetes、lighthouse、catalog-backend 等插件的createRouter/createBuilder调用传入env.discovery。迁移事件系统将所有EventBroker/EventPublisher/EventSubscriber用法替换为EventsService按上文 diff 示例调整EventRouter子类与各 publisher。更新权限调用将PermissionEvaluator/ServerPermissionClient的token参数改为BackstageCredentials。体验新能力接入 guest-provider注意默认实体变为user:development/guest、Scaffolder 检查点与createMockActionContext、Azure DevOpsdev.azure.com/readme-path注解。本仓库中 docs/backend-system/core-services/ 目录包含各核心服务的详细文档docs/tutorials/ 与 docs/architecture-decisions/ 可进一步了解认证迁移与 ADR-013 等决策背景beps/目录下的 0003-auth-architecture-evolution 与 0004-scaffolder-task-idempotency 则是理解本次重大变更设计动机的第一手资料。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
