Backstage v1.36.0-next.0 深度解读auditor 审计服务、PermissionsRegistry 与原生 ESM 支持【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术解读以 docs/releases/v1.36.0-next.0-changelog.md 为骨架围绕 Backstage 1.36.0 首个预发布版本next.0的核心变更展开全新的auditor核心服务与PermissionsRegistryService如何重塑后端插件的能力边界CLI 原生 ESM 支持带来的破坏性变更应如何迁移以及 Canon、TechDocs 自定义首页等前端增强的实战用法。读完本文你将掌握本版本中每个破坏性变更的迁移要点并能直接落地 auditor 事件埋点与权限规则注册的完整代码。版本总览一次面向新后端系统的能力升级v1.36.0-next.0 是一轮覆盖后端服务、CLI 工具链与前端组件体系的预发布迭代其中几个关键包的版本变化直接决定了升级工作的规模包新版本变更级别核心内容backstage/backend-plugin-api1.2.0-next.0Minor新增auditor服务定义与PermissionsRegistryServicebackstage/backend-defaults0.8.0-next.0Minor提供auditor服务的默认实现backstage/backend-test-utils1.3.0-next.0Minor为两个新服务提供测试 mockbackstage/cli0.30.0-next.0BREAKINGNode.js 代码原生 ESM 支持backstage/canon0.1.0-next.0首个 alphaCanon 组件库首次发布backstage/plugin-catalog-backend1.31.0-next.0Minor接入PermissionsRegistryService与auditorbackstage/plugin-scaffolder-backend1.30.0-next.0Minor接入auditor服务backstage/plugin-techdocs-node1.13.0-next.0MinorAWS S3 发布器支持可配置重试此外backstage/plugin-catalog-node1.15.2-next.0正式弃用了 alpha 状态的catalogPermissionExtensionPoint及相关类型其功能已由新的PermissionsRegistryService完全取代。auditor 服务为后端插件引入统一审计能力本版本最核心的架构级变更是在 packages/backend-plugin-api/src/services/definitions/AuditorService.ts 中新增的AuditorService接口并通过coreServices.auditorid 为core.auditor见 coreServices.ts暴露给所有后端插件。服务接口与事件模型从源码定义看AuditorService只暴露一个方法export interface AuditorService { createEvent( options: AuditorServiceCreateEventOptions, ): PromiseAuditorServiceEvent; }createEvent接收的事件选项包含四个字段eventId必填采用 kebab-case 命名如user-login、file-download、fetch表示一组相似事件或操作的逻辑聚合。例如fetch可作为事件 ID涵盖by-id、by-location等多种具体取数方式。由于pluginId已提供插件/模块上下文eventId中应避免冗余的前缀。severityLevel可选事件严重级别取值与含义在源码注释中明确给出low默认常规使用medium访问写端点high非 root 权限变更criticalroot 权限变更request可选关联的 HTTP 请求对象expressRequest。meta可选附加元数据结构化 JSON 对象。其中可含queryType字段同样使用 kebab-case用于表达主事件内的变体例如eventId为fetch时meta.queryType可为by-id或by-location。createEvent返回一个AuditorServiceEvent它提供了显式的成功/失败回调export type AuditorServiceEvent { success(options?: { meta?: JsonObject }): Promisevoid; fail(options: { meta?: JsonObject; error: Error }): Promisevoid; };这种先创建、后标记成败的模型让插件可以在操作的整个生命周期内携带审计上下文最终以成功或失败两种状态落盘。默认实现与日志输出默认实现位于 packages/backend-defaults/src/entrypoints/auditor/auditorServiceFactory.ts。从源码可以确认其依赖与行为服务工厂依赖rootConfig、logger、auth、httpAuth与pluginMetadata五个核心服务它基于logger.child({ isAuditEvent: true })派生专用审计日志器审计事件会统一打上isAuditEvent: true标记便于日志采集系统区分日志记录键为${event.plugin}.${event.eventId}即插件 ID 与事件 ID 拼接事件失败时error in event错误对象会被单独作为第二个参数传给日志方法严重级别到日志级别的映射由getSeverityLogLevelMappings(config)从配置中解析意味着审计日志的落盘级别可随配置调整。插件集成现状从变更日志看auditor服务已在本版本中完成首批落地plugins/catalog-backendCatalog 插件接入auditor服务变更 a4aa244plugins/scaffolder-backendScaffolder 插件接入auditor服务变更 a4aa244。对于插件开发者接入审计服务的方式是在插件或模块中通过依赖注入获取coreServices.auditor例如import { coreServices, createBackendModule } from backstage/backend-plugin-api; createBackendModule({ pluginId: my-plugin, moduleId: audit-demo, register(env) { env.registerInit({ deps: { auditor: coreServices.auditor }, async init({ auditor }) { const event await auditor.createEvent({ eventId: fetch, severityLevel: low, meta: { queryType: by-id }, }); try { // 执行业务操作... await event.success(); } catch (error) { await event.fail({ error }); } }, }); }, });测试支撑packages/backend-test-utils 为auditor服务提供了现成的 mock变更 a4aa244相关单元测试如DefaultAuditorService.test.ts、WinstonRootAuditorService.test.ts、auditorServiceFactory.test.ts均位于 packages/backend-defaults/src/entrypoints/auditor也随实现一同落地可在测试中直接验证事件的成功/失败路径。PermissionsRegistryService权限注册的新标准入口第二个关键架构变更是PermissionsRegistryService其接口定义在 packages/backend-plugin-api/src/services/definitions/PermissionsRegistryService.ts通过coreServices.permissionsRegistryid 为core.permissionsRegistry暴露。它取代了原先通过createPermissionIntegrationRouter来自backstage/plugin-permission-node注册权限的模式。四个核心方法从源码看该服务提供四个方法addPermissions(permissions: Permission[])为插件向权限系统注册权限。addPermissionRules(rules: PermissionRuleany, any, string[])为插件拥有的资源类型注册一组权限规则。规则应使用各插件导出的create*PermissionRule函数创建这些函数本身由makeCreatePermissionRule派生插件自身或其模块均可添加规则。addResourceType(options)注册一个新的资源类型其选项包括resourceRef标识资源类型的PermissionResourceRefpermissions该资源类型可用的权限列表rules该资源类型可用的权限规则数组描述如何过滤资源列表如 Catalog 的isEntityOwner、hasAnnotation并支持以特定参数构造条件getResources根据引用标识符加载关联资源的函数。若未提供权限系统将无法解析条件化授权决策除非直接从插件请求资源。getPermissionRuleset(resourceRef)返回已注册的规则集主要用于配合createConditionAuthorizer与createConditionTransformer使用。源码注释以 Catalog 为例说明了addResourceType的语义Catalog 围绕对具体实体的访问有条件规则resourceType是像catalog-entity这样的字符串标识它只是用于校验授权策略中条件构造正确性的类型而非对具体资源的引用。集成与弃用plugins/catalog-backend 已支持通过新的PermissionsRegistryService添加自定义权限规则变更 8805f93plugins/catalog-backend-module-unprocessed 改用新服务替代已弃用的catalogPermissionExtensionPoint变更 4e073c7plugins/catalog-node 弃用了 alpha 状态的catalogPermissionExtensionPoint及相关类型变更 4a941e7默认实现与工厂测试位于 packages/backend-defaults/src/entrypoints/permissionsRegistry配套地backstage/plugin-permission-node0.8.8-next.0中createPermissionIntegrationRouter返回的路由器变为可变对象允许在创建之后继续添加权限与资源变更 049d5d4为过渡期提供兼容空间。backstage/backend-test-utils同样为本服务提供了 mock变更 dd05a97。破坏性变更CLI 原生 ESM 支持backstage/cli0.30.0-next.0引入了 Node.js 代码的原生 ESM 支持变更 cb76663这是本轮升级中最需要关注的手工迁移点。行为变化原生 ESM 支持改变了 Node.js 代码中动态导入表达式的行为动态import(...)将不再被转译为require(...)而是原样保留。这带来的能力提升包括允许从 CommonJS 代码中通过动态导入加载 ESM 模块.mjs/.mts作为显式 ESM 文件.cjs/.cts作为显式 CommonJS 文件支持在package.json中声明type: module将包标记为 ESM 包。上述能力在类型检查、包构建、运行时转换与 Jest 测试中全部生效。迁移要点对于大多数插件/应用代码修复方式是把import(...)替换为require(...)需要类型时再配合as typeof import(...)断言// 之前会被转译为 require const mod await import(./some-module); // 之后原生动态导入 const mod require(./some-module) as typeof import(./some-module);四个重要注意事项根据变更日志以下 caveat 需要特别注意测试启用原生 ESM 需要--experimental-vm-modules通常在运行测试时通过NODE_OPTIONS--experimental-vm-modules注入。type: module的传染效应在package.json中声明type: module是受支持的但在测试环境中它会将所有本地传递依赖也视为 ESM——无论这些依赖自身是否声明了type: module。ESM 互操作层的启用条件Node.js 的 ESM/CommonJS 互操作层仅在导入带.cts或.cjs扩展名的包时启用。原因是该互操作层与 NPM 生态并不完全兼容若对.js文件启用会破坏包。避免动态导入 CommonJS 包动态导入 CommonJS 包的结果形状会随运行环境测试 vs 本地开发等变化。因此建议改用require或使用上述显式 CommonJS 扩展名如果确实需要动态导入 CommonJS 包应避免使用default导出因为其形状在不同环境间不一致否则需要根据模块对象的形状手动解包。此外backstage/cli-node0.2.13-next.0同步在BackstagePackageJson类型中增加了type字段backstage/config-loader、backstage/backend-defaults等包也进行了显式require的懒加载重构变更 f866b86。Canon全新组件库的首个 alphabackstage/canon0.1.0-next.0是 Canon 的首次 alpha 发布变更 65f4acc本次引入5 个布局layout组件7 个通用组件所有主题化均通过CSS 变量完成。这意味着开发者可以在不引入 Material UI 主题上下文的前提下通过 CSS 变量对 Canon 组件进行风格定制适合对样式控制粒度有更高要求的场景。TechDocs 自定义首页能力增强plugins/techdocs 在本次迭代中大幅增强了文档首页的自定义能力变更 1f40e6bTechDocsCustomHome 新增可选 propsTechDocsCustomHome现在支持通过tabsConfig配置多标签页的文档聚合页并通过filter精确筛选实体。一个完整的配置示例来自变更日志import { TechDocsCustomHome } from backstage/plugin-techdocs; //... const options { emptyRowsWhenPaging: false }; const linkDestination (entity: Entity): string | undefined { return entity.metadata.annotations?.[external-docs]; }; const techDocsTabsConfig [ { label: Recommended Documentation, panels: [ { title: Golden Path, description: Documentation about standards to follow, panelType: DocsCardGrid, panelProps: { CustomHeader: () ContentHeader titleGolden Path/ }, filterPredicate: entity entity?.metadata?.tags?.includes(golden-path) ?? false, }, { title: Recommended, description: Useful documentation, panelType: InfoCardGrid, panelProps: { CustomHeader: () ContentHeader titleRecommended / linkDestination: linkDestination, }, filterPredicate: entity entity?.metadata?.tags?.includes(recommended) ?? false, }, ], }, { label: Browse All, panels: [ { description: Browse all docs, filterPredicate: filterEntity, panelType: TechDocsIndexPage, title: All, panelProps: { PageWrapper: React.Fragment, CustomHeader: React.Fragment, options: options }, }, ], }, ]; const AppRoutes () { FlatRoutes Route path/docs element{ TechDocsCustomHome tabsConfig{techDocsTabsConfig} filter{{ kind: [Location, Resource, Component], metadata.annotations.featured-docs: CATALOG_FILTER_EXISTS, }} CustomPageWrapper{({ children }: React.PropsWithChildren{}) (PageWithHeader titleDocs themeIddocumentation{children}/PageWithHeader)} / } / /FlatRoutes; };新增 InfoCardGrid 与独立 CustomDocsPanel新增网格选项InfoCardGrid更可定制的文档卡片网格支持自定义linkContent与linkDestinationInfoCardGrid entities{entities} linkContentLearn more linkDestination{entity entity.metadata[external-docs]} /原有的CustomDocsPanel被导出可独立使用。借助PanelConfig数组开发者可以灵活拼装不同 panel 类型const panels: PanelConfig[] [ { description: , filterPredicate: entity {}, panelType: InfoCardGrid, title: Standards, panelProps: { CustomHeader: () ContentHeader titleRecommended / linkDestination: linkDestination, }, }, { description: , filterPredicate: entity {}, panelType: DocsCardGrid, title: Contribute, }, ]; { panels.map((config, index) ( CustomDocsPanel key{index} config{config} entities{!!entities ? entities : []} index{index} / )); }其他 TechDocs 修复addLinkClickListener的基础 URL 从window.location.origin改为app.baseUrl变更 f4be934修复了 Backstage 运行在子路径subpath时无法正确处理同源非 Backstage URL 的问题plugins/techdocs-node 与techdocs/cli1.9.0-next.0支持为 AWS S3 发布操作配置可选重试变更 8de3d2d。其余值得关注的变更本轮还包含一系列影响面较小但值得留意的更新Scaffolder 任务上下文新增taskIdplugins/scaffolder-node 的TaskContext增加可选taskId属性变更 a4aa244相关类型定义可见 plugins/scaffolder-node/src/alpha/index.ts为任务级操作如按taskId清理工作区提供依据。通知系统主题过滤backstage/plugin-notifications与backstage/plugin-notifications-backend新增 topic 过滤器变更 438c36c。搜索过滤扩展点backstage/plugin-search与backstage/plugin-search-react新增SearchFilterBlueprint与SearchFilterResultTypeBlueprint可扩展搜索过滤与结果类型变更 63e1012。Kubernetes 额外对象抓取backstage/plugin-kubernetes-backend支持指定默认对象之外的其他 Kubernetes 对象以补充secrets等资源的获取变更 ac0e1ac。Catalog 稳定性修复stitching 期间良性数据库冲突错误降级为 debug 级日志变更 c9139e1清理不再控制某refresh_state行的 processor/provider 对应的refresh_state_references变更 f178b12搜索索引的 location URL 生成改用encodeURIComponent编码实体属性值提升 URL 安全性与可靠性变更 eee8d76。前端应用树 APIfrontend-app-api与frontend-plugin-api的AppTreeApi新增getNodesByRoutePath方法变更 3e21b8d。Scaffolder 组件修复修复BitbucketRepoBranchPicker导致页面崩溃的问题变更 3107f1fmakeFieldSchema返回值新增 schema 输出返回类型变更 3edf7e7。repo-toolsapi-reports命令新增--sql-reports标志可生成 SQL 报告变更 98ddf05。后端动态特性服务packages/backend-dynamic-feature-service 确保变更被成功跟踪后再启动扫描器变更 96c20cd。升级路径建议基于以上变更从 v1.35.x 升级到 v1.36.0 正式版前建议按以下顺序自查优先处理 CLI ESM 迁移全局搜索仓库中的动态import(...)调用评估是否涉及 ESM 模块加载按照用require替代 as typeof import保类型的模式逐一替换若测试需要原生 ESM为 Jest 配置NODE_OPTIONS--experimental-vm-modules并注意type: module在测试中的传递性影响。评估权限注册迁移若插件使用了catalogPermissionExtensionPoint迁移到coreServices.permissionsRegistry若使用了createPermissionIntegrationRouter注意其返回路由器已变为可变对象可按需渐进迁移。关注服务版本对齐backend-plugin-api、backend-defaults、backend-test-utils三个包必须同步升级到 1.2.0 / 0.8.0 / 1.3.0 的 next 版本线否则新服务引用无法解析。验证 TechDocs 行为变化若运行在子路径部署升级后验证文档内链接跳转行为符合预期。完整变更条目可随时查阅仓库内的 docs/releases/v1.36.0-next.0-changelog.md升级前建议结合 docs/releases/v1.35.0-changelog.md 确认上一版本的已知问题。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考