Backstage v1.29.0 版本深度解析后端服务工厂重构、Root Health Service 与权限体系升级【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南围绕 Backstage v1.29.0 版本发布说明docs/releases/v1.29.0-changelog.md展开系统梳理该版本在后端服务工厂Service Factory模式重构、健康检查服务、权限与认证体系、Scaffolder 模板引擎、Catalog 数据源等方面的破坏性变更与新特性。读完本文你将掌握 v1.29.0 升级路径中的全部 Breaking Changes、新 API 的正确使用方式以及各项新功能的配置方法可直接用于自身 Backstage 实例的升级评估与代码迁移。一、版本概览与升级路径v1.29.0 是 Backstage 在 2024 年发布的一个重要版本核心主题是后端服务依赖注入体系的现代化改造backstage/backend-plugin-api从 0.6.x 升至 0.7.0、backstage/backend-app-api升至 0.8.0、backstage/backend-defaults升至 0.4.0同时配套发布了全新的 Root Health Service、权限策略接口的PolicyQueryUser类型以及前端的「外部路由可通过配置禁用」能力。升级前务必使用官方 Upgrade Helperhttps://backstage.github.io/upgrade-helper/?to1.29.0核对依赖差异并按本文第二节逐一处理破坏性变更。若你的后端插件来自第三方包且出现“callback-form 特性安装”相关的告警需要联系包维护者升级其backstage/backend-plugin-api依赖。1.1 主要包版本变化速览包名版本变更类型backstage/backend-app-api0.8.0Minor含 Breakingbackstage/backend-defaults0.4.0Minor含 Breakingbackstage/backend-plugin-api0.7.0Minor含 Breakingbackstage/core-app-api1.14.0Minorbackstage/integration1.13.0Minorbackstage/plugin-catalog-backend1.24.0Minorbackstage/plugin-catalog-backend-module-ldap0.7.0Minor含 Breakingbackstage/plugin-permission-common0.8.0Minor含 Breakingbackstage/plugin-permission-node0.8.0Minor含 Breakingbackstage/plugin-scaffolder1.23.0Minorbackstage/plugin-scaffolder-backend1.23.0Minorbackstage/plugin-scaffolder-backend-module-gcp0.1.0新增包backstage/cli0.26.11Patchbackstage/create-app0.5.17Patch二、破坏性变更Breaking Changes与迁移指南2.1 服务工厂全面转向无回调callback-free模式这是 v1.29.0 最重要的架构性变更影响backstage/backend-plugin-api、backstage/backend-app-api、backstage/backend-defaults、backstage/backend-test-utils等多个包。变更一createServiceFactory不再支持通过 options 回调声明配置项commit062c01c。此前工厂可以写成export const fooServiceFactory createServiceFactoryFooService( (options?: { bar: string }) ({ service: fooServiceRef, deps: { logger: coreServices.logger }, factory({ logger }) { return { // Implementation of the foo service using the bar option. }; }, }), );新版本鼓励服务实现方提供“易于重新实现”的构建 API例如导出一个静态工厂方法用户可自行包装/** public */ export class DefaultFooService implements FooService { static create(options: { bar: string; logger: LoggerService }) { return new DefaultFooService(options.logger, options.bar ?? default); } private constructor( private readonly logger: string, private readonly bar: string, ) {} // The rest of the implementation }需要定制服务的用户只需定义自己的工厂通过依赖注入拿到logger再调用DefaultFooService.create传入自己的参数export const customFooServiceFactory createServiceFactoryFooService({ service: fooServiceRef, deps: { logger: coreServices.logger }, factory({ logger }) { return DefaultFooService.create({ logger, bar: baz }); }, });从 packages/backend-plugin-api/src/services/system/types.ts 的源码可以看到createServiceFactory的签名已经收窄为直接接收RootServiceFactoryOptions或PluginServiceFactoryOptions对象对应原RootServiceFactoryConfig/PluginServiceFactoryConfig的改名不再存在“先传 options 回调”的重载。官方说明给出了仍希望保留 options 模式的兼容写法——用一个函数包裹createServiceFactory再用Object.assign同时导出“可带参版本”和“默认实例”const fooServiceFactoryWithOptions (options?: { bar: string }) createServiceFactoryFooService({ service: fooServiceRef, deps: { logger: coreServices.logger }, factory({ logger }) { return { // Implementation of the foo service using the bar option. }; }, }); export const fooServiceFactory Object.assign( fooServiceFactoryWithOptions, fooServiceFactoryWithOptions(), );变更二createSpecializedBackend不再接受 callback 形式的服务工厂commitf691c9bdefaultServiceFactories选项现在只能传纯ServiceFactory对象。该函数属于低频 API官方明确指出这是即时破坏immediate breaking change。变更三以 callback 形式安装后端特性() BackendFeature已被弃用commit18b96b1。这意味着你需要将已安装的特性更新到最新版backstage/backend-plugin-api第三方特性包则需维护者跟进升级。变更四httpRouterServiceFactory的getPath选项被移除commit1cb84d7同时删除了HttpRouterFactoryOptions类型。如果你的代码通过getPath自定义路由前缀需要改用新的路由挂载方式。配套地rootHttpRouterServiceFactory与rootConfigServiceFactory也完成了内部重构commits419f387、e28af58现在允许“带 options 构造”但不再通过createServiceFactory声明 options这也印证了上述模式转变。变更五类型命名标准化commitfe47a3e。为统一前后端create*函数的签名风格ServiceRefConfig→ServiceRefOptionsRootServiceFactoryConfig→RootServiceFactoryOptionsPluginServiceFactoryConfig→PluginServiceFactoryOptions从源码结构看这些类型改动同时带来了更好的 TypeScript 报错体验——当服务工厂未正确实现服务接口时编译器能给出更精确的错误信息。2.2 权限体系token 选项移除与 PolicyQueryUser 类型PermissionsService不再支持已弃用的token选项且请求选项变为必填commit36f91e8backstage/backend-plugin-api0.7.0ServerPermissionClient同步对齐新接口backstage/plugin-permission-node0.8.0。EvaluatorRequestOptions中的token选项被移除commitf4085b8backstage/plugin-permission-common0.8.0改为由PermissionsClient自带独立的PermissionClientRequestOptions类型声明token。PermissionPolicy.handle的第二参数类型改为PolicyQueryUsercommited10fd2。旧BackstageIdentityResponse中的字段全部弃用替换为两个新字段credentials一个BackstageCredentials对象可在策略评估中代表用户调用其他服务取代已弃用的token字段。创建请求 token 的方式参见 Auth Service 文档中“Creating request tokens”一节。info一个BackstageUserInfo对象内容与原identity相同仅去掉了冗余的type字段。大多数已有策略只需两步即可完成迁移将BackstageIdentityResponse类型替换为从backstage/plugin-permission-node导出的PolicyQueryUser并把所有user?.identity替换为user?.info。import { PolicyQueryUser } from backstage/plugin-permission-node; export class MyPolicy implements PermissionPolicy { async handle(request: PolicyQuery, user?: PolicyQueryUser) { // 旧user?.identity?.ownershipEntityRefs // 新user?.info?.ownershipEntityRefs // 同时可用 user?.credentials 代表用户发起下游请求 } }2.3 LDAP Provider 支持多组配置backstage/plugin-catalog-backend-module-ldap0.7.0中readLdapOrg与LdapProviderConfig类型现在始终接收用户/用户组配置的数组commitcb32ca7而不再只是单个条目。单个 LDAP catalog provider 现在可以同时提供 list 与未定义的 user/group bindings支持用一套配置导入多个组织或用户组。三、新特性详解3.1 全新的 Root Health Service健康检查端点backstage/backend-defaults0.4.0与backstage/backend-plugin-api0.7.0新增了 Root Health Service为后端提供健康检查端点commit53ced70。从实现源码 packages/backend-defaults/src/entrypoints/rootHealth/rootHealthServiceFactory.ts 可以看到其状态机与行为getLiveness()固定返回 HTTP 200payload 为{ status: ok }用于探活。getReadiness()基于RootLifecycleService的钩子维护init → up → down三态启动钩子addStartupHook执行后进入up返回 200关闭前钩子addBeforeShutdownHook执行后进入down返回 503payload 为{ message: Backend is shutting down, status: error }处于init尚未完成启动时同样返回 503Backend has not started yet。这意味着你可以将 K8s 的livenessProbe指向 liveness 端点、将readinessProbe指向 readiness 端点让滚动发布与优雅停机更可靠。rootHealthServiceFactory本身按新工厂模式实现createServiceFactory({ service: coreServices.rootHealth, deps: { lifecycle: coreServices.rootLifecycle }, factory({ lifecycle }) {...} })。健康路由的挂载实现在 packages/backend-defaults/src/entrypoints/rootHttpRouter/createHealthRouter.ts 中。backend-test-utils也同步在mockServices中新增了 Root Health Service 的 mockcommitfce7887便于测试。3.2 前端外部路由可通过配置禁用app.routes.bindingsbackstage/core-app-api1.14.0支持通过静态配置禁用外部路由绑定commitd3c39fc——此前默认目标default targets引入后这一禁用能力反而变得不可能。现在你可以在app-config.yaml中写app: routes: bindings: # 效果移除 scaffolder 模板列表视图中“注册新 catalog 实体”的按钮 scaffolder.registerComponent: false从 packages/core-app-api/src/app/resolveRouteBindings.ts 的实现可以看到三层绑定优先级代码中的bindRoutes回调优先配置中的app.routes.bindings次之值必须是「非空字符串」或false否则抛错引用不存在的外部路由或目标路由也会抛错默认目标映射兜底。其中false会将该外部路由加入disabledExternalRefs集合从而“按掉”某个入口按钮/链接而不需要改代码。若某外部路由是必需的非 optional却被禁用解析过程会直接抛错提示。3.3 Scaffolder 多项增强Picker 虚拟化backstage/plugin-scaffolder1.23.0EntityPicker与MultiEntityPicker均改用虚拟化列表commits52b6db0、3583ce5修复大数据集下的性能问题VirtualizedListbox被抽取为可复用组件。OwnedEntityPicker支持catalogFilter数组commit89c44b3。RepoUrlPicker新增 Bitbucket Cloud 自动补全autocomplete能力commitb5deed0。Backend 侧backstage/plugin-scaffolder-backend1.23.0新增autocomplete扩展点用于向RepoUrlPicker提供额外的自动补全处理器commitb5deed0plugin-scaffolder-node同步支持。新增把 Scaffolder 工作区序列化到 GCP 存储桶的能力commit0b52438由新包backstage/plugin-scaffolder-backend-module-gcp0.1.0承载。catalog:writeaction 修复日志中文件路径显示commitb9451dddry runner 修复用户实体获取commit62d1fe3。新增 checkpoint 使用文档commitff1bb4c。GitHub 相关 actionbackstage/plugin-scaffolder-backend-module-github0.4.0创建 GitHub 环境时支持自定义 tag 策略commit70c4b36。新增启用 GitHub Pages 的 actioncommit141f366。github:publish与github:repo:push新增requireLastPushApproval输入项用于配置分支保护设置commitdfaa28d。修复github:environment:create中缺失 owner/repo 参数导致环境密钥、变量创建失败的问题commitsccfc9d1、4410fed。其他模块gitlab:pipeline:trigger支持传入variablescommit2fb0eb8。Bitbucket Server 模块不再硬编码targetBranch改为从仓库获取默认分支commit6a4ad4e避免默认分支为main时出错。RepoUrlPicker修复 Azure 仍强制要求owner字段的 bugcommit661b354。任务日志流查看器支持调整大小commit4d7e11fplugin-scaffolder-react在无输出时不再渲染输出框commit4d7e11f。3.4 Catalog 数据源增强GithubEntityProvider 支持 repository 事件backstage/plugin-catalog-backend-module-github0.6.5commit9112efcprovider 订阅github.repository主题处理archived、deleted、edited、renamed、transferred、unarchived六种 actioncreated、privatized、publicized因不需要实体变更而被跳过。当开启validateLocationsExist配置时renamed、transferred、unarchived会触发一次 API 请求来校验 location。GitLab 用户导入范围控制backstage/plugin-catalog-backend-module-gitlab0.3.21commit8db30ad新增可选布尔配置catalog.providers.gitlab.your-org.restrictUsersToGroup设为true时只导入group键定义的用户组内的用户而不是自托管实例的整个组织 / SaaS 的整个 root group 的所有用户默认false保持原有行为。MS Graph 动态 Providerplugin-catalog-backend-module-msgraph0.5.30commitf7bdcea配置可通过ProviderConfigTransformer在运行时动态调整。AWS 模块plugin-catalog-backend-module-aws0.3.17commit4afa050导出defaultEksClusterEntityTransformer便于库使用方在其之上叠加额外转换逻辑。LDAP见 2.3 节的多配置支持。3.5 其他值得关注的变更CLIbackstage/cli0.26.11新增动态前端插件构建的实验性支持通过设置EXPERIMENTAL_MODULE_FEDERATION启用 app 构建并使用新的frontend-dynamic-container包角色创建容器commit133464c两者均为实验性、未来会变化。backendPlugin/backendModule工厂会自动把新建的后端插件/模块加入后端的index.tscommit4baac0c。修复从 1.28 升级时 CLI 报错的问题commitf0c0039仅在实际使用时才引导 global-agentcommit7652db4。后端插件模板移除winston、yn两个未用依赖并将msw升级到 2.3.1commite2e320c。create-app0.5.17侧边栏新增MyGroupsSidebarItemcommit780d994模板新增 Catalog logs 模块commite90a2cd与 Postgres 搜索引擎commit3ac2a6a。org 插件useGetEntities钩子改为分批请求避免/api/catalog/entities请求头超过 Node.js 默认 16KB 上限commit5132d28EntityMembersListCard新增relationType属性可按memberOf之外的关系展示组成员同时relationsType弃用、改名为更准确的relationAggregationcommitc307ef4。Catalog 前端catalog 与 catalog-react 插件开始支持 i18ncommit06c0956EntityOwnerPicker在only-owners模式下展示metadata.title或spec.profile.displayName而非metadata.namecommit2030962。Notifications通知页工具栏在无通知时自动隐藏commit3bf0697后端新增按 topic 过滤通知的选项commitd7b8ca5通知处理器过滤器解析逻辑上移到 common 包commit4e4ef2b。TechDocs前端修复导航时页面不必要重渲染commit8fc2622、文档表默认排序改进commit6fa652c、支持按实体标题搜索commit605b691、修复阅读器双滚动条commit60caa92后端新增 publishers 扩展点commit9ecf5fd。集成integration1.13.0bitbucketCloud集成支持tokencommitb5deed0plugin-bitbucket-cloud-common同步新增autocompletehandler。四、测试工具与调度修复4.1 ServiceFactoryTest.get 更名为 getSubjectbackstage/backend-app-api中ServiceFactoryTest.get方法弃用改用语义更准确的ServiceFactoryTest.getSubjectcommit2f99178行为完全一致。backend-test-utils的 ServiceFactoryTester 提供对应的getSubject()返回被测服务实例与getService()获取任意依赖服务实例测试插件级服务时可传入 pluginId默认使用test。4.2 测试后端只接受纯工厂对象startTestBackend与ServiceFactoryTester现在只接受纯ServiceFactory或 backend feature 对象不再支持 callback 形式commit906c817与backend-plugin-api的变更保持一致通常无需改动测试代码。4.3 其他测试相关调整setupRequestMockHandlers前后端统一改名为registerMswTestHookscommit95a3a0b涉及backend-test-utils、frontend-test-utils、test-utils。isDockerDisabledForTests弃用未来将不再导出commitedf5cc3。4.4 调度与数据库依赖修复修复 ISO 时长ISO durations无法用于调度schedule的 bugcommit083eaf9影响backend-tasks、backend-defaults及多个 catalog 模块。多个包将better-sqlite3从^9.0.0升至^11.0.0commitb9ed1bb影响backend-defaults、plugin-catalog-backend、backend-common、backend-test-utils等升级后请留意 SQLite 行为差异。backend-common弃用 legacy status check 工厂、处理器与相关类型commit8c09c97并建议新脚手架生成的后端插件使用非弃用的错误处理中间件commitd228862。五、升级检查清单使用 Upgrade Helper?to1.29.0生成依赖变更清单重点核对backend-plugin-api、backend-app-api、backend-defaults、plugin-permission-node等包的版本。全局搜索createServiceFactory(中的 options 回调写法按 2.1 节模式改写为「导出静态 create 自定义工厂」如必须保留 options使用Object.assign兼容写法。检查createSpecializedBackend、httpRouterServiceFactory({ getPath })等低频用法是否受影响。权限策略中替换BackstageIdentityResponse→PolicyQueryUseruser?.identity→user?.info并移除对token选项的依赖。如需健康检查启用 Root Health Service 并将 liveness/readiness 端点接入容器探针。尝试用app.routes.bindings配置化禁用不需要的外部路由入口。回归测试 Scaffolder 模板尤其 Bitbucket、GitHub 相关 action与 Catalog 数据源GitHub repository 事件、GitLab 用户范围、LDAP 多配置。参考文件版本发布说明docs/releases/v1.29.0-changelog.md服务工厂类型与签名packages/backend-plugin-api/src/services/system/types.tsRoot Health Service 实现packages/backend-defaults/src/entrypoints/rootHealth/rootHealthServiceFactory.ts健康路由挂载packages/backend-defaults/src/entrypoints/rootHttpRouter/createHealthRouter.ts路由绑定解析packages/core-app-api/src/app/resolveRouteBindings.ts服务工厂测试工具packages/backend-test-utils/src/wiring/ServiceFactoryTester.ts【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考