Backstage v1.3.0 版本深度解析Token 安全强化、Catalog Entity Provider 迁移与 Scaffolder 任务管理【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南基于 Backstage 官方 v1.3.0 变更日志docs/releases/v1.3.0-changelog.md系统性梳理该版本引入的破坏性变更与核心新能力ServerTokenManager强制校验exp声明、Catalog 发现机制从 Processor 向 Entity Provider 迁移Bitbucket Cloud / Azure DevOps / GitLab、Scaffolder 任务列表页与 Gerrit 支持、搜索结果的rank与discover分析事件等。阅读本文后你将掌握 v1.2.0 → v1.3.0 升级过程中需要处理的全部迁移要点并能直接复刻各插件的新配置与代码写法。v1.3.0 版本主题概览v1.3.0 是 Backstage 在 1.0 系列稳定期的一次重要功能版本涉及数十个backstage/*包同步发版核心主题集中在以下几个方面主题领域涉及包关键变化服务间认证安全backstage/backend-common0.14.0破坏性变更服务端 token 必须携带未过期的exp声明Catalog 发现机制演进catalog-backend-module-bitbucket-cloud、-azure、-gitlab新增/补全 Entity Provider替代传统 Discovery Processor脚手架任务可观测性backstage/plugin-scaffolder1.3.0、scaffolder-backend1.3.0新增/create/tasks任务列表页、listTasksAPI、/v2/tasks路由搜索与分析plugin-search、plugin-catalog、plugin-techdocs搜索结果新增rank点击事件升级为discover事件新插件dynatrace、vault、github-pull-requests-board三个全新插件首次发布下文按升级必读 → 迁移实操 → 新功能的顺序展开。服务端 Token 强制校验expv1.3.0 最重要的破坏性变更backstage/backend-common0.14.0的 Minor Changes 中有一条BREAKING声明所有由ServerTokenManager认证的服务端到服务端server-to-servertoken现在必须携带尚未过期的exp声明。凡是exp缺失或已过期的 token 一律视为无效并抛出错误。这条变更承接自 v1.2.0 中对永久 tokenperpetual tokens的弃用声明是对该弃用的最终落地。升级后必须注意更新所有getToken()的调用方式每次需要 token 时都重新调用不要在应用启动时获取一次然后长期存储复用由于 token 现在带有过期时间任何获取一次、反复使用的缓存逻辑都会在过期后触发认证失败仓库当前代码中仍能看到该管理器的使用痕迹例如 packages/backend-defaults/CHANGELOG.md 记录的ServerTokenManager.fromConfig(config, ...)构造方式它是后端默认服务装配中 token 管理的标准入口。从架构角度看这一变更让 Backstage 的插件后端之间通信具备了真正的时效性安全边界即使 token 意外泄露其有效窗口也受到exp限制而不是无限期有效。同时它也提醒所有插件作者token 的获取与使用应当按需即取与服务生命周期解耦。Catalog 发现机制演进从 Processor 到 Entity Providerv1.3.0 在 Catalog 后端模块上集中发力将多个 Git 托管平台的自动发现能力从处理器Processor模式迁移到实体提供者Entity Provider模式。后者由调度器Scheduler驱动周期性拉取仓库列表并注册catalog-info.yaml相比 Processor 具备更明确的配置结构、支持多实例并行与更细粒度的过滤。新增backstage/plugin-bitbucket-cloud-common统一的 Bitbucket Cloud 客户端该版本新增了通用库backstage/plugin-bitbucket-cloud-common0.1.0提供一个可复用的 Bitbucket Cloud API 客户端。变更日志明确指出这个客户端可以在所有包之间复用未来很可能成为承载限流管理等额外能力的公共基础层客户端部分代码由openapitools/openapi-generator-cli生成。它被随后发布的新 Entity Provider 模块作为底层依赖引用。新模块catalog-backend-module-bitbucket-cloud用 Provider 取代 Discovery Processor新发布的backstage/plugin-catalog-backend-module-bitbucket-cloud0.1.0提供了BitbucketCloudEntityProvider官方定位是BitbucketDiscoveryProcessor在Bitbucket Cloud仅限云端场景下的替代品明确覆盖原先使用searchtrue的用例并可作为完整替代。迁移步骤如下。迁移前Processor 模式在 packages/backend/src/plugins/catalog.ts 中注册处理器并在app-config.yaml中配置 location// packages/backend/src/plugins/catalog.ts builder.addProcessor( BitbucketDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }), );# app-config.yaml catalog: locations: - type: bitbucket-discovery target: https://bitbucket.org/workspaces/workspace-name/projects/apis-*/repos/service-*?searchtruecatalogPath/catalog-info.yaml迁移后Entity Provider 模式// packages/backend/src/plugins/catalog.ts builder.addEntityProvider( BitbucketCloudEntityProvider.fromConfig(env.config, { logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), }), );# app-config.yaml catalog: providers: bitbucketCloud: yourProviderId: # identifies your ingested dataset catalogPath: /catalog-info.yaml # default value filters: # optional projectKey: ^apis-.*源码级配置说明。结合 plugins/catalog-backend-module-bitbucket-cloud/config.d.ts 与 plugins/catalog-backend-module-bitbucket-cloud/src/providers/BitbucketCloudEntityProviderConfig.ts 的解析逻辑配置项细节如下workspace必填指定要发现的 Bitbucket 工作区。注意config.d.ts中该字段被标记为 RequiredcatalogPath可选默认/catalog-info.yaml常量DEFAULT_CATALOG_PATH定义于配置解析文件中filters.projectKey/filters.repoSlug可选正则表达式分别按项目 Key 与仓库 slug 过滤。底层compileRegExp会自动为模式补全^与$锚点BitbucketCloudEntityProviderConfig.ts因此无论你写不写锚点匹配都是整行全匹配语义schedule可选调度定义也可在代码中通过env.scheduler.createScheduledTaskRunner(...)传入。从 BitbucketCloudEntityProvider.ts 的实现可见代码与配置二者必须提供其一否则fromConfig会直接抛出Either schedule or scheduler must be provided.异常pagelen可选每页从 Bitbucket API 拉取的结果数默认 100配置支持单配置变体直接写workspace键与命名多 Provider 变体两种形式当配置顶层存在workspace字段时按default作为 provider id 解析否则遍历所有子键作为多个独立 provider见 BitbucketCloudEntityProviderConfig.ts。此外该 Provider 与事件系统集成源码顶部常量TOPIC_REPO_PUSH、TOPIC_REPO_UPDATED见 BitbucketCloudEntityProvider.ts可响应仓库推送等事件实现增量发现。Azure DevOpsAzureDevOpsEntityProvider迁移指南backstage/plugin-catalog-backend-module-azure0.1.4新增AzureDevOpsEntityProvider作为AzureDevOpsDiscoveryProcessor的替代。迁移前后对比如下。迁移前使用azure-discovery类型的 location 与 Processor# app-config.yaml catalog: locations: - type: azure-discovery target: https://dev.azure.com/myorg/myproject/_git/service-*?path/catalog-info.yaml/* packages/backend/src/plugins/catalog.ts */ import { AzureDevOpsDiscoveryProcessor } from backstage/plugin-catalog-backend-module-azure; const builder await CatalogBuilder.create(env); /** ... other processors ... */ builder.addProcessor(new AzureDevOpsDiscoveryProcessor(env.reader));迁移后改用catalog.providers.azureDevOps配置与AzureDevOpsEntityProvider.fromConfig# app-config.yaml catalog: providers: azureDevOps: anyProviderId: host: selfhostedazure.yourcompany.com # This is only really needed for on-premise user, defaults to dev.azure.com organization: myorg # For on-premise this would be your Collection project: myproject repository: service-* path: /catalog-info.yaml/* packages/backend/src/plugins/catalog.ts */ import { AzureDevOpsEntityProvider } from backstage/plugin-catalog-backend-module-azure; const builder await CatalogBuilder.create(env); /** ... other processors and/or providers ... */ builder.addEntityProvider( AzureDevOpsEntityProvider.fromConfig(env.config, { logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), }), );要点host仅本地部署on-premise才需要显式配置默认为dev.azure.comorganization在本地部署场景对应你的 Collectionrepository支持service-*这样的通配符匹配。GitLabGitlabDiscoveryEntityProvider与性能优化标志backstage/plugin-catalog-backend-module-gitlab0.1.4新增GitlabDiscoveryEntityProvider实现见 plugins/catalog-backend-module-gitlab/src/providers/GitlabDiscoveryEntityProvider.ts替代GitlabDiscoveryProcessor。迁移前# app-config.yaml catalog: locations: - type: gitlab-discovery target: https://company.gitlab.com/prefix/*/catalog-info.yaml/* packages/backend/src/plugins/catalog.ts */ import { GitlabDiscoveryProcessor } from backstage/plugin-catalog-backend-module-gitlab; const builder await CatalogBuilder.create(env); /** ... other processors ... */ builder.addProcessor( GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }), );迁移后# app-config.yaml catalog: providers: gitlab: yourProviderId: # identifies your dataset / provider independent of config changes host: gitlab-host # Identifies one of the hosts set up in the integrations branch: main # Optional. Uses master as default group: example-group # Group and subgroup (if needed) to look for repositories entityFilename: catalog-info.yaml # Optional. Defaults to catalog-info.yaml/* packages/backend/src/plugins/catalog.ts */ import { GitlabDiscoveryEntityProvider } from backstage/plugin-catalog-backend-module-gitlab; const builder await CatalogBuilder.create(env); /** ... other processors and/or providers ... */ builder.addEntityProvider( ...GitlabDiscoveryEntityProvider.fromConfig(env.config, { logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), }), );注意 Provider 返回的是数组注册时需用展开运算符...展开。该模块还带了两项值得关注的优化首次查询 GitLab API 时不再携带last_activity_after时间戳新增skipReposWithoutExactFileMatch标志当仓库中不存在catalog-info.yaml时不再创建 location 对象从而显著降低 GitLab 返回 404 的请求量const processor GitLabDiscoveryProcessor.fromConfig(config, { logger, skipReposWithoutExactFileMatch: true, });警告该新功能不支持在仓库文件路径中使用 glob 通配符。Scaffolder 增强任务列表页、listTasksAPI 与 Gerrit 支持v1.3.0 对 Scaffolder 的改进覆盖前后端使模板执行任务的可见性与控制能力大幅提升。新增/create/tasks任务列表页backstage/plugin-scaffolder1.3.0新增/create/tasks页面用于展示 Scaffolder 已运行的任务并支持按当前登录用户与全部任务两种维度过滤。其前端路由定义可见 plugins/scaffolder/src/routes.ts 中的scaffolderListTaskRouteRef路径为/tasks挂在/create之下构成/create/tasks。对应地ScaffolderApi接口新增了可选的listTasks方法调用时需传入必填参数filterByOwnership用于按归属过滤任务。后端/v2/tasks列表路由backstage/plugin-scaffolder-backend1.3.0为TaskBroker与TaskStore接口新增了可选的list方法按可选的userEntityRef过滤并在DatabaseTaskStore中实现了该方法。同时新增/v2/tasks路由可通过createdBy查询参数按用户实体引用userEntityRef列出任务。当前仓库中该路由的实现位于 plugins/scaffolder-backend/src/service/router.tsGET /v2/tasks会解析createdBy参数并透传给任务存储层进行过滤。同文件还提供了/v2/tasks/:taskId、cancel、retry、eventstream等任务生命周期管理端点。表单字段访问自定义字段读取其他表单数据ScaffolderApi与字段扩展机制支持自定义字段组件通过props.formContext.formData读取表单中其他字段的值const CustomFieldExtensionComponent (props: FieldExtensionComponentPropsstring[]) { const { formData } props.formContext; ... }; const CustomFieldExtension scaffolderPlugin.provide( createScaffolderFieldExtension({ name: ..., component: CustomFieldExtensionComponent, validation: ... }) );这一能力让字段间的联动如根据仓库类型动态调整可见选项成为可能。新的 Gerrit 集成与gerrit:publish动作前端新增针对 Gerrit 的RepoUrlPickerbackstage/plugin-scaffolder1.3.0后端新增gerrit:publishscaffolder 动作backstage/plugin-scaffolder-backend1.3.0backstage/integration1.2.1同步修复了 Gerrit 集成中resolveUrl对绝对路径的处理。publish:github协作者参数修复破坏性行为变化publish:github动作修复了无法添加用户为协作者的缺陷但代价是参数语义发生了变化添加团队为协作者使用team字段username字段仍可用但已弃用官方建议迁移到team添加用户为协作者使用user字段。- id: publish name: Publish action: publish:github input: repoUrl: ... collaborators: - access: ... team: my_team - access: ... user: my_username同时publish:gitlab:merge-request动作的projectid输入参数被弃用——它已能从repoUrl中解码不再需要单独传入其projectid输出也被projectPath取代。另外该版本还新增了不保护默认分支的选项并在仓库创建失败时给出更详尽的错误说明。模板脱离default命名空间运行Scaffolder 前端与后端均新增了对非default命名空间模板的支持backstage/plugin-scaffolder1.3.0与backstage/plugin-scaffolder-backend1.3.0各自的f93af969cd变更并修复了MultistepJsonForm的 review mask 行为设置 mask 后不再需要额外的show: true以及 dry-run 内容上传时对二进制文件与超大文件的处理。搜索体验升级结果rank与discover分析事件v1.3.0 围绕搜索体验做了一轮跨插件联动优化核心是让搜索结果的可分析性更强backstage/plugin-search-common0.3.5在Result类型上新增可选的rank属性表示某结果在结果集中的排名从 1 开始backstage/plugin-search-backend0.5.3以及-elasticsearch0.1.5、-pg0.3.4提供的搜索引擎现在都会为所有结果附加分页感知pagination-aware的rank值backstage/plugin-catalog1.3.0、backstage/plugin-techdocs1.2.0提供的*ResultListItem /组件将点击分析事件从click升级为discover事件以结果排名作为value属性同时保留点击目标作为to属性。这一设计简化了搜索漏斗分析——discover事件语义上代表发现比点击更贴合搜索结果场景。应用侧如需让自定义搜索组件参与分析可在渲染结果项时透传rank。此外backstage/plugin-search0.9.0移除了SearchPageNext、SearchBarNext等 pre-alpha 组件请改用backstage/plugin-search-react或backstage/plugin-search中的非*Next等价组件DefaultResultListItem、SearchBar含SearchBarBase、SearchFilter含.Checkbox/.Select/.Autocomplete、SearchResult、SearchResultPager等组件均已从backstage/plugin-search迁移至backstage/plugin-search-react导出旧位置已弃用、未来将移除。TechDocs 改进并发构建限制与构建日志输出backstage/plugin-techdocs-backend1.1.2带来两项运维向增强并发构建上限当techdocs.builder配置为local时并发构建数被限制为 10超出部分将排队等待。若确有更高并发需求官方建议横向扩容 TechDocs 后端部署或改用external构建方式构建日志输出到日志传输层createRouter新增buildLogTransport参数可将构建日志同时输出到后端日志流而不只是前端事件流便于在浏览器之外捕获构建失败原因。典型用法如下完整示例见 plugins/techdocs-backend 相关代码import { DockerContainerRunner } from backstage/backend-common; import { createRouter, Generators, Preparers, Publisher, } from backstage/plugin-techdocs-backend; import Docker from dockerode; import { Router } from express; import { PluginEnvironment } from ../types; export default async function createPlugin( env: PluginEnvironment, ): PromiseRouter { const preparers await Preparers.fromConfig(env.config, { logger: env.logger, reader: env.reader, }); const dockerClient new Docker(); const containerRunner new DockerContainerRunner({ dockerClient }); const generators await Generators.fromConfig(env.config, { logger: env.logger, containerRunner, }); const publisher await Publisher.fromConfig(env.config, { logger: env.logger, discovery: env.discovery, }); await publisher.getReadiness(); return await createRouter({ preparers, generators, publisher, logger: env.logger, // Passing a buildLogTransport as a parameter in createRouter will enable // capturing build logs to a backend log stream buildLogTransport: env.logger, config: env.config, discovery: env.discovery, cache: env.cache, }); }同期前端backstage/plugin-techdocs1.2.0的改进包括EntityTechdocsContent改用对象而非Route元素以修复子页面 outlet 为空导致 addon 不渲染的问题读者页样式转换逻辑被重构为若干 hookssanitizeDOM等转换器改为 hookaddons 渲染过程修复了侧边栏闪烁与重复创建的问题TechDocsReaderPageHeader与TechDocsSearch优先使用实体标题作为文案并为 Catalog / TechDocs 搜索结果新增可选图标。其他值得关注的新插件与能力新插件首发backstage/plugin-dynatrace0.1.0Dynatrace 观测平台前端插件backstage/plugin-vault0.1.0与backstage/plugin-vault-backend0.1.0HashiCorp Vault 密钥管理的前后端插件首次实现详情见各插件 READMEbackstage/plugin-github-pull-requests-board0.1.0GitHub Pull Requests 看板插件。Kubernetes 支持扩展backstage/plugin-kubernetes-backend0.6.0与backstage/plugin-kubernetes-common0.3.0新增对 StatefulSet 的数据拉取支持前端backstage/plugin-kubernetes0.6.6以与 Deployments 相同的折叠面板方式展示 StatefulSet并新增 CPU/内存 request/limit 展示、Kubernetes 页签刷新间隔可配置、多命名空间下 HPA 匹配修复、Azure token 缓存刷新等改进。权限体系完善backstage/plugin-permission-node0.6.2新增权限元数据聚合端点/.well-known/backstage/permissions/metadata默认返回插件支持的权限规则信息插件作者可通过createPermissionIntegrationRouter的可选permissions参数补充Permission对象未来该参数将变为必填。Catalog 杂项CatalogBuilder.addEntityProvider支持以数组形式一次传入多个 Provider无需再逐个展开builder.addEntityProvider(getArrayOfProviders())Catalog 后端禁止通过 location 服务注册除url类型以外的任何 location 类型plugin-catalog1.3.0的isKind、isComponentType、isNamespace过滤器支持传入值数组进行匹配plugin-org0.5.6的MyGroupsSidebarItem新增filter属性可按spec.type等条件过滤所展示的组例如filter{{ spec.type: team }}LDAP 模块新增 TLS 连接配置支持plugin-catalog-backend-module-github0.1.4为 GitHub Teams Group 实体补充了编辑 URL。升级到 v1.3.0 的检查清单综合上文从 v1.2.0 升级到 v1.3.0 时建议逐项核对Token 生命周期检查所有getToken()调用点确保每次按需获取不缓存复用为旧 token 的exp过期留出切换窗口Git 平台发现迁移若使用 Bitbucket Cloud / Azure DevOps / GitLab 的 discovery Processor迁移到对应的 Entity Provider 并补充schedule配置代码或配置二选一Scaffolder核对publish:github协作者字段user/team评估是否迁移publish:gitlab:merge-request的projectid用法搜索组件导入将SearchBar、SearchFilter、DefaultResultListItem等组件改从backstage/plugin-search-react导入删除*Next组件引用TechDocs如需构建日志在createRouter中传入buildLogTransport评估local构建模式下 10 并发上限是否满足需求权限端点可选地在createPermissionIntegrationRouter中补充permissions参数为元数据端点提供更丰富的信息。本文所有代码示例均来自变更日志原文与仓库当前实现如 plugins/catalog-backend-module-bitbucket-cloud 的 Provider 与配置解析源码、plugins/scaffolder-backend/src/service/router.ts 的/v2/tasks实现可在对应路径继续深入研读。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考