Backstage v1.29.0 版本解析新后端系统收敛、Root Health 服务与 Catalog 生态增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章以官方发布说明 docs/releases/v1.29.0.md 为核心骨架结合本仓库源码系统梳理 Backstage v1.29.0 的 Breaking Changes、弃用清单与新增能力。读完本文你将掌握新后端系统 1.0 稳定化过程中的关键迁移动作PermissionsService 凭据化、路由绑定显式移除、PolicyQueryUser 权限策略改造、Root Health 服务与/.backstage/health/*端点的实现原理以及 Catalog Logs 模块、GitHubrepository事件、i18n 等 Catalog 生态增强的接入方式。版本概览与升级指引v1.29.0 的核心工作是继续推进新后端系统new backend system向 1.0 稳定版收敛与此同批次落地了一批面向运维与插件作者的实用能力新增 Backend Health Service、新增 Catalog 错误日志模块、为create-app模板默认引入 Postgres 搜索与 Catalog 日志能力并对权限策略、测试工具、LDAP 模块与 Scaffolder 字段做了兼容性调整。官方对升级的总体建议是保持你的 Backstage 项目与最新版本同步。升级方法与常规流程一致可参考 docs/getting-started/keeping-backstage-updated.md完整的逐条变更清单见 docs/releases/v1.29.0-changelog.md。BREAKING新后端系统的弃用与移除围绕 新后端系统 1.0 稳定版的目标工作v1.29.0 对后端系统包做了一批清理。这些变更影响所有使用新后端系统 API 的插件与自定义代码升级时需要逐项核对。三项 Breaking 变更PermissionsService的token选项被移除请求选项request options现在为必填项且必须包含credentials对象。所有依赖旧token字段发起授权请求的代码都必须改为传递BackstageCredentials。httpRouterServiceFactory的getPath选项被移除插件路由路径现在固定为/api/pluginId不再允许自定义路径前缀。createSpecializedBackend的defaultServiceFactories不再接受 service factory 回调该选项现在只接受 service factory 实例旧式回调写法会直接报错。一批新的 Deprecations通过createServiceFactory为 service factory 定义可配置选项options的能力被弃用。自定义可配置服务的新做法参考 服务架构文档对应仓库路径 packages/backend-plugin-api/src/services/definitions。以回调形式安装后端特性即() BackendFeature被弃用这也波及startTestBackend以及动态导入的后端特性。官方说明指出大多数项目无需手动修改因为所有后端特性创建函数backend feature creators已统一改为直接返回BackendFeature实例。测试辅助类ServiceFactoryTest.get方法重命名为ServiceFactoryTest.getSubject旧名已弃用。三个类型改为*Options后缀命名ServiceRefConfig、RootServiceFactoryConfig、PluginServiceFactoryConfig旧名称继续以弃用形式保留。backstage/backend-common中与旧式状态检查器legacy status checker相关的所有导出被弃用其职责由下文介绍的 Root Health Service 接管。backstage/backend-test-utils导出的isDockerDisabledForTests函数被弃用。新增 Backend Health Service/.backstage/health/*端点v1.29.0 在新后端系统中新增了Root Health Service根健康服务用于为整个后端实例提供健康检查端点并取代backstage/backend-common中的createStatusCheckRouter。它实现了两个标准端点/.backstage/health/v1/readiness就绪检查反映后端是否已启动完成、可对外服务/.backstage/health/v1/liveness存活检查反映后端进程是否仍在运行。服务接口定义在 packages/backend-plugin-api/src/services/definitions/RootHealthService.ts 中服务接口非常精简export interface RootHealthService { /** Get the liveness status of the backend. */ getLiveness(): Promise{ status: number; payload?: JsonValue }; /** Get the readiness status of the backend. */ getReadiness(): Promise{ status: number; payload?: JsonValue }; }该服务引用在 packages/backend-plugin-api/src/services/definitions/coreServices.ts 中注册为core.rootHealth作用域为rootexport const rootHealth createServiceRefRootHealthService({ id: core.rootHealth, scope: root, });默认实现的判定逻辑默认实现DefaultRootHealthService位于 packages/backend-defaults/src/entrypoints/rootHealth/rootHealthServiceFactory.ts其内部维护一个三态状态机init后端尚未完成启动up已通过启动钩子addStartupHook确认启动完成down已触发关闭前钩子addBeforeShutdownHook正在关停。对应的端点行为如下表端点状态HTTP 状态码payloadgetLiveness()任意200{ status: ok }getReadiness()up200{ status: ok }getReadiness()init503{ message: Backend has not started yet, status: error }getReadiness()down503{ message: Backend is shutting down, status: error }也就是说liveness 只要进程存活即返回 200而 readiness 在后端尚未启动完成或正在关停时返回 503——这与 Kubernetes 等编排平台对存活探针/就绪探针的语义约定完全一致可以直接用于 Pod 的livenessProbe与readinessProbe配置。对应的测试用例见 packages/backend-defaults/src/entrypoints/rootHealth/rootHealthServiceFactory.test.ts。新模块backstage/plugin-catalog-backend-module-logs该模块是一个极简的 Catalog 后端模块作用是订阅 Catalog 发布的所有错误事件并写入日志确保 Catalog 的处理错误在日志中可见。官方同时提示如果默认日志过于冗长建议替换为更定制化的解决方案。源码实现在 plugins/catalog-backend-module-logs/src/module.ts 中模块通过createBackendModule声明pluginId: catalog、moduleId: logs在初始化时订阅CATALOG_ERRORS_TOPIC主题export const catalogModuleLogs createBackendModule({ pluginId: catalog, moduleId: logs, register(env) { env.registerInit({ deps: { events: eventsServiceRef, logger: coreServices.logger, }, async init({ events, logger }) { events.subscribe({ id: catalog, topics: [CATALOG_ERRORS_TOPIC], async onEvent(params: EventParams): Promisevoid { const event params as EventsParamsWithPayload; const { entity, location, errors } event.eventPayload; for (const error of errors) { logger.warn(error.message, { entity, location }); } }, }); }, }); }, });事件负载EventsPayload包含entity实体引用、location位置和errors错误数组每条错误以logger.warn级别输出并附带实体与位置上下文便于日志检索与排障。该模块依赖backstage/plugin-events-node提供的事件服务因此启用它需要后端已具备事件总线能力。接入方式在packages/backend/src/index.ts中添加一行即可启用backend.add(import(backstage/plugin-catalog-backend-module-logs));create-app模板更新Catalog Logs 与 Postgres 搜索从 v1.29.0 起通过backstage/create-app新建的项目默认包含两项能力Catalog Logs 模块记录 Catalog 错误事件Postgres Search Engine 支持启用backstage/plugin-search-backend-module-pg作为搜索后端。仓库中的默认模板 packages/create-app/templates/default-app/packages/backend/src/index.ts 已给出完整的接线示例// catalog plugin backend.add(import(backstage/plugin-catalog-backend)); backend.add( import(backstage/plugin-catalog-backend-module-scaffolder-entity-model), ); // See https://backstage.io/docs/features/software-catalog/configuration#subscribing-to-catalog-errors backend.add(import(backstage/plugin-catalog-backend-module-logs)); // search plugin backend.add(import(backstage/plugin-search-backend)); // search engine backend.add(import(backstage/plugin-search-backend-module-pg));对于存量项目可按同样方式手动添加这两个模块Postgres 搜索需确保后端数据库为 PostgreSQL并完成对应数据库初始化。Permission Policy 弃用改用PolicyQueryUserPermissionPolicy接口随认证系统的最新演进做了对齐调整handle方法的第二个参数由旧的BackstageIdentityResponse改为新的PolicyQueryUser类型。旧类型的所有字段均已弃用取而代之的是两个新字段credentialsBackstageCredentials对象可用于在评估策略时代表用户向其他服务发起请求替代已弃用的token字段infoBackstageUserInfo对象包含与旧identity相同的信息剔除了冗余的type字段。源码中的类型定义在 plugins/permission-node/src/policy/types.ts 中export type PolicyQueryUser { /** * The credentials of the user making the request. */ credentials: BackstageCredentials; /** * The information for the user making the request. * * deprecated This field is deprecated and will be removed in a future release. */ info: BackstageUserInfo; };对应接口签名同文件 plugins/permission-node/src/policy/types.tsexport interface PermissionPolicy { handle(request: PolicyQuery, user?: PolicyQueryUser): PromisePolicyDecision; }该类型由backstage/plugin-permission-node导出见 plugins/permission-node/src/policy/index.ts。迁移示例大多数现有策略的迁移非常机械将BackstageIdentityResponse替换为PolicyQueryUser并把所有user?.identity出现处替换为user?.infoimport { PermissionPolicy, PolicyQueryUser } from backstage/plugin-permission-node; export class MyPolicy implements PermissionPolicy { async handle(request: PolicyQuery, user?: PolicyQueryUser) { const userRef user?.info?.userEntityRef; // 原来是 user?.identity?.userEntityRef // ... } }如需在策略中携带用户凭据调用下游服务并换取新的请求 token可基于user.credentials按认证服务文档中的“创建请求令牌”指引操作。测试工具重命名registerMswTestHooksbackstage/test-utils与backstage/backend-test-utils导出的setupRequestMockHandlers工具函数被重命名为registerMswTestHooks以更准确地反映其“在测试生命周期中注册 MSWMock Service Worker请求拦截钩子”的用途。旧名称已弃用将在未来版本中移除建议在测试代码中同步更新命名。Catalog GitHub 模块支持repository事件Catalog 的 GitHub Provider 模块与GithubEntityProvider新增了对 GitHubrepository事件的订阅支持可实现仓库的事件驱动摄取event driven ingestion覆盖以下动作archived归档deleted删除edited编辑renamed重命名transferred转移unarchived取消归档这是对既有push事件支持用于基于 GitHub Discovery 的事件驱动摄取的补充。对应实现位于 plugins/catalog-backend-module-github配合事件后端backstage/plugin-events-backend及其 GitHub 模块即可在 GitHub Webhook 到达时自动刷新/移除 Catalog 中的对应实体。Catalog 插件与 Catalog React 库i18n 支持Catalog 插件及其 React 库backstage/plugin-catalog、backstage/plugin-catalog-react在 v1.29.0 起支持国际化i18n。这意味着可以自定义 Catalog 界面中的文案为 Catalog 组件提供多语言翻译。接入方式遵循 Backstage 统一的国际化机制参考 docs/plugins/internationalization.md 与 docs/plugins/internationalization.md 同目录下的相关文档。实现集中在 plugins/catalog/src 与 plugins/catalog-react/src 中通过createTranslationRef等 API 声明翻译引用。Route Binding 配置改进显式移除默认绑定新后端系统此前会为插件路由建立默认绑定例如 Scaffolder 模板列表页上“注册 Catalog 实体”的按钮。v1.29.0 允许在配置中显式将某条路由绑定设为false从而彻底移除该绑定适用于“不期望任何目标承载这条路由”的场景。app: routes: bindings: # 效果移除 scaffolder 模板列表视图中“注册新 catalog 实体”的按钮 scaffolder.registerComponent: false在源码侧路由绑定解析器已对false值做了专门校验与处理配置值必须是非空字符串或false否则会抛出配置错误value must be a non-empty string or false。对应测试见 packages/frontend-app-api/src/routing/resolveRouteBindings.test.ts其中{ mySource: false }的用例正是验证“显式移除绑定”的场景。Scaffolder Fields 性能改进EntityPicker与MultiEntityPicker两个 Scaffolder 表单字段针对大型 Catalog场景做了性能优化改善了大实体列表下的渲染与选择体验。相关代码位于 plugins/scaffolder-react/src 的字段实现中使用这两个字段的现有模板无需任何改动即可受益。BREAKINGCatalog LDAP 模块增强backstage/plugin-catalog-backend-module-ldap模块做了破坏性增强现在支持多个或零个user/group 配置声明readLdapOrg与LdapProviderConfig现在始终接受users和groups配置数组若某个配置数组为空/未声明对应类型的实体将不会被摄取。这对从 LDAP 目录中仅同步用户、仅同步组或从多个 LDAP 源聚合数据的场景更友好。升级此模块时需将配置中的users、groups调整为数组形态并同步更新直接调用readLdapOrg的代码。安全修复说明v1.29.0不包含任何安全修复。如果你的项目之前因安全原因滞后于某个版本本次升级主要动机是保持功能与 API 对齐并为后续版本铺路安全补丁的发布节奏请持续关注后续版本发布说明。结语v1.29.0 是一次“收敛型”发布新后端系统通过移除token/getPath等过渡期 API 向 1.0 稳定版靠拢Root Health Service 为后端可观测性提供了标准化的/.backstage/health/*探针端点Catalog 生态则通过错误日志模块、repository事件与 i18n 补齐了运维与本地化能力。升级时建议优先处理本文列出的 Breaking Changes凭据化改造、路径固定化、PolicyQueryUser迁移、LDAP 数组化再渐进采纳新能力。完整的逐项变更可对照 docs/releases/v1.29.0-changelog.md 核对。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考