Backstage v1.4.0-next.2 变更深度解析Catalog 实体处理状态过滤、Msgraph Provider 迁移与 Scaffolder 新 Action【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库中的 v1.4.0-next.2 变更日志逐条拆解该预发布版本中真正影响开发者的功能变更EntityProcessingStatusPicker与GroupDefaultParentEntityPolicy两项 Catalog 能力、backstage/plugin-catalog-backend-module-msgraph从处理器Processor到 Provider 的迁移指南、Scaffolder 新增的github:repo:create/github:repo:pushAction以及主题、Markdown 渲染、搜索与安全依赖升级等横向更新。读完本文你将掌握这些新能力的配置方式、迁移路径与源码级实现原理。说明v1.4.0-next.2是正式版v1.4.0发布前的第二个预发布候选-next 后缀表示 next 分支上的迭代版本本文涉及的 API 与配置均以当前仓库实际内容为准。一、Catalog 核心能力处理状态过滤与组默认父实体策略1.1 新增EntityProcessingStatusPicker一眼定位孤儿与出错实体本次版本为 Catalog 引入了一个新的过滤组件EntityProcessingStatusPicker用于按实体的**处理状态processing status**过滤列表——具体包含两类异常状态Is Orphan孤儿实体在软件目录中已经不存在对应描述文件如 YAML 已被删除或不再被拉取但仍残留在 Catalog 中的实体Has Error处理出错在解析/处理过程中出现错误的实体。从源码看该组件位于 plugins/catalog-react/src/components/EntityProcessingStatusPicker/EntityProcessingStatusPicker.tsx其核心实现是通过useEntityList()的updateFilters来下发过滤条件import { EntityErrorFilter, EntityOrphanFilter } from ../../filters; function orphanChange(value: boolean) { updateFilters({ orphan: value ? new EntityOrphanFilter(value) : undefined, }); } function errorChange(value: boolean) { updateFilters({ error: value ? new EntityErrorFilter(value) : undefined, }); } const availableAdvancedItems [Is Orphan, Has Error];组件基于CatalogAutocomplete渲染一个多选下拉框选项为Is Orphan与Has Error勾选后即把对应的EntityOrphanFilter/EntityErrorFilter注入实体列表的过滤链从而在表格中只保留满足条件的实体。这正是日常运维中最常见的两个排查场景清理失效实体、定位处理失败的配置项。接入方式默认 Catalog 页面无需任何改动——DefaultFilters会自动挂载该 Picker参见 plugins/catalog-react/src/components/DefaultFilters/DefaultFilters.tsx自定义了 Catalog 页面的用户需要手动添加变更日志给出了完整的接入示例import { CatalogFilterLayout, EntityTypePicker, UserListPicker, EntityTagPicker, EntityProcessingStatusPicker, } from backstage/plugin-catalog-react; export const CustomCatalogPage ({ columns, actions, initiallySelectedFilter owned, }: CatalogPageProps) { return ( EntityListProvider CatalogFilterLayout CatalogFilterLayout.Filters EntityKindPicker initialFiltercomponent hidden / EntityTypePicker / UserListPicker initialFilter{initiallySelectedFilter} / EntityTagPicker / EntityProcessingStatusPicker / /CatalogFilterLayout.Filters CatalogFilterLayout.Content CatalogTable columns{columns} actions{actions} / /CatalogFilterLayout.Content /CatalogFilterLayout /EntityListProvider ); };同一变更同时落在backstage/plugin-catalog与backstage/plugin-catalog-react两个包中be26d95141默认 Catalog 页的自动化挂载逻辑位于插件前端而组件本身由plugin-catalog-react导出便于被其他自定义页面复用。1.2GroupDefaultParentEntityPolicy为组实体兜底默认父级backstage/catalog-model1.1.0-next.2引入了GroupDefaultParentEntityPolicy变更4cc81372f8这是一个EntityPolicy实体策略用于给没有父级的Group实体补上默认父级。其设计动机很明确Backstage 的组织结构User/Group通常由多套数据源如 LDAP、Microsoft Graph混合导入很难保证每棵组织树都存在单一根节点。该策略可以在保留既有层级结构的前提下确保整个组层级拥有一个唯一的全局根节点——即最后兜底的父级parent of last resort。源码位于 packages/catalog-model/src/entity/policies/GroupDefaultParentEntityPolicy.ts核心逻辑如下export class GroupDefaultParentEntityPolicy implements EntityPolicy { private readonly parentRef: string; constructor(parentEntityRef: string) { const { kind, namespace, name } parseEntityRef(parentEntityRef, { defaultKind: Group, defaultNamespace: DEFAULT_NAMESPACE, }); if (kind.toUpperCase() ! GROUP) { throw new TypeError(group parent must be a group); } this.parentRef stringifyEntityRef({ kind, namespace, name, }); } async enforce(entity: Entity): PromiseEntity { if (entity.kind ! Group) { return entity; } const group entity as GroupEntity; if (group.spec.parent) { return group; // 已有父级保持原样 } // 避免让实体成为自己的父级 if (stringifyEntityRef(group) ! this.parentRef) { group.spec.parent this.parentRef; } return group; } }实现要点构造函数接收一个父实体引用如group:default/root-group通过parseEntityRef解析若解析出的 kind 不是Group会直接抛出TypeErrorenforce只对kind Group的实体生效其他实体原样放行已有spec.parent的组不会被改写从而保留既有层级带有防御性检查不会把组设为自身的父级。该策略通过EntityPolicy机制注册进 Catalog 处理管线与DefaultProcessingDatabase等处理流程共同作用于实体入库阶段。其配套测试位于 packages/catalog-model/src/entity/policies/GroupDefaultParentEntityPolicy.test.ts可用于了解各边界行为的预期表现。1.3 实体页面的其他 Catalog 变更plugin-catalog1.4.0-next.2为 Catalog 表格与 API 表格增加了隐藏的 title 列a274fe38b9使表格可按实体的title而非仅name进行过滤同时不改变表格的视觉呈现unregister entity注销实体菜单项新增visible/hidden/disabled三态定制能力258057a4b9旧有的布尔输入将在未来版本弃用visible保持可点击hidden从上下文菜单中隐藏该项disabled保留菜单项但置灰不可点击EntityLayout的表头样式修复b4b711bcc2修复鼠标悬停时EntityContextMenu按钮显示形状异常的问题。二、Microsoft Graphmsgraph集成迁移从 Processor 到 Providerbackstage/plugin-catalog-backend-module-msgraph0.4.0-next.1是一次破坏性deprecation变更为了让该插件的实体提供配置与其他 Provider 对齐官方将旧的entity processor用法与旧版配置标记为弃用统一迁移到entity provider用法。日志中会持续输出警告直到你完成迁移弃用部分将在过渡期后移除。2.1 旧用法回顾旧版存在两种使用方式——处理器或 Provider方式一注册为处理器Processor// packages/backend/src/plugins/catalog.ts builder.addProcessor( MicrosoftGraphOrgReaderProcessor.fromConfig(env.config, { logger: env.logger, // [...] }), );方式二注册为实体 ProviderEntityProvider// packages/backend/src/plugins/catalog.ts builder.addEntityProvider( MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { id: https://graph.microsoft.com/v1.0, target: https://graph.microsoft.com/v1.0, logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), // [...] }), );旧版配置文件两种方式共用# app-config.yaml catalog: processors: microsoftGraphOrg: providers: - target: https://graph.microsoft.com/v1.0 # [...]2.2 新配置与注册方式迁移后的配置以catalog.providers.microsoftGraphOrg为根每个 Provider 用稳定的 providerId作为键该 ID 会成为所有摄入数据 location key 的一部分# app-config.yaml catalog: providers: microsoftGraphOrg: # 若你曾使用弃用的 entity provider 配置 # 沿用 target 的值可保持所有数据的 location key 不变 providerId: # 稳定的 ID将作为所有摄入数据 location key 的一部分 target: https://graph.microsoft.com/v1.0 # [...]对应的后端注册代码则不再需要在fromConfig中传id/target这些信息改由配置提供// packages/backend/src/plugins/catalog.ts builder.addEntityProvider( MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), // [...] }), );2.3 多 Provider 差异化 Transformer 的场景如果你此前注册了多个 entity provider并且每个 provider 都配有各自不同的 transformer迁移后可以直接在同一个fromConfig调用中通过以 provider ID 为键的 Record一次性传入这些 transformer从而让配置驱动的多 Provider 与各自的转换逻辑一一对应。这是本次迁移最值得注意的细节它把原来分散在代码里的多份addEntityProvider调用收敛为一份配置 一个注册点。迁移提示变更日志指出完整的配置选项文档含 config 与 provider 注册方式收录于该插件目录下的 READMEplugins/catalog-backend-module-msgraph。三、Scaffolder 新 Action 与参数能力增强3.1 新增github:repo:create与github:repo:pushbackstage/plugin-scaffolder-backend1.4.0-next.2新增两个 GitHub Action变更2db07887cb实现在 plugins/scaffolder-backend-module-github/src/actionsgithub:repo:creategithubRepoCreate.ts直接创建一个 GitHub 仓库空仓库不依赖本地工作目录内容github:repo:pushgithubRepoPush.ts将本地已生成的内容推送到新建/已有仓库。两者配合可覆盖生成代码 - 建仓 - 推送的完整链路。以github:repo:create为例从源码可以确认其输入参数非常丰富return createTemplateAction({ id: github:repo:create, description: Creates a GitHub repository., examples, schema: { input: { ...inputProps, }, output: { remoteUrl: outputProps.remoteUrl, repoContentsUrl: outputProps.repoContentsUrl, }, }, async handler(ctx) { const { repoUrl, description, homepage, access, repoVisibility private, // 默认私有 deleteBranchOnMerge false, allowMergeCommit true, // 默认允许 merge commit allowSquashMerge true, // 默认允许 squash merge squashMergeCommitTitle COMMIT_OR_PR_TITLE, squashMergeCommitMessage COMMIT_MESSAGES, allowRebaseMerge true, // 默认允许 rebase merge allowAutoMerge false, allowUpdateBranch false, collaborators, hasProjects undefined, hasWiki undefined, hasIssues undefined, topics, repoVariables, secrets, // ... } ctx.input;要点输入侧通过repoUrl指定目标仓库可配置可见性repoVisibility默认private、描述、主页、协作者collaborators、主题topics、仓库级变量repoVariables与密钥secrets等输出侧提供remoteUrl与repoContentsUrl便于后续 Action如github:repo:push或模板步骤引用大量布尔选项带有默认值如allowMergeCommit、allowSquashMerge、allowRebaseMerge默认开启未显式配置时行为可预期示例定义见 githubRepoCreate.examples.ts配套测试见 githubRepoCreate.test.ts 与 githubRepoPush.test.ts。3.2 GitLab Merge Request Action支持删除源分支plugin-scaffolder-backend1.4.0-next.2同时更新了 GitLab Merge Request Action变更4baf8a4ece现在允许在合并后删除源分支source branch便于模板在合并请求被接受后自动清理分支减少仓库中的残留分支。3.3RepoUrlPicker与OwnedEntityPicker的表单选项增强backstage/plugin-scaffolder1.4.0-next.2带来两处与模板表单体验相关的改动RepoUrlPicker新增allowedReposui:optiond8eb82f447允许限定用户在创建模板时只能选择指定仓库集合适用于将模板发布范围收敛到特定仓库的治理场景同时repoName字段被拆分为独立组件便于单独定制OwnedEntityPicker新增allowArbitraryValuesui:option14146703e5与EntityPicker中已有的同名选项行为对齐允许用户在候选实体之外输入任意值适用于目标实体尚未入库、或需手工指定任意实体引用的场景。# 模板参数中启用任意值输入的示意OwnedEntityPicker 或 EntityPicker ui:options: allowArbitraryValues: true四、前端核心MarkdownContent 支持链接与图片 URI 转换backstage/core-components0.10.0-next.2为MarkdownContent组件新增transformLinkUri与transformImageUri两个 props变更32204fa794。源码位于 packages/core-components/src/components/MarkdownContent/MarkdownContent.tsxtype Props { content: string; dialect?: gfm | common-mark; linkTarget?: Options[linkTarget]; transformLinkUri?: (href: string) string; transformImageUri?: (href: string) string; className?: string; }; export function MarkdownContent(props: Props) { const { content, dialect gfm, linkTarget, transformLinkUri, transformImageUri, className, } props; // ... return ( ReactMarkdown remarkPlugins{dialect gfm ? [gfm] : []} rehypePlugins{dialect gfm ? gfmRehypePlugins : []} className{${classes.markdown} ${className ?? }.trim()} children{content} components{components} linkTarget{linkTarget} transformLinkUri{transformLinkUri} transformImageUri{transformImageUri} / ); }使用方式非常直接传入一个(href: string) string的函数即可在渲染前改写 Markdown 中的链接与图片地址。典型场景包括将相对路径链接解析为绝对 URL过滤或重写外部链接如强制 HTTPS、追加安全 token为内嵌图片拼接 CDN 前缀或鉴权参数。这两个 props 最终透传给底层的react-markdown因此行为与 react-markdown 的transformLinkUri/transformImageUri语义一致。需要注意的是MarkdownContent默认启用 GFM 方言且通过rehype-sanitize对 HTML 做白名单过滤配合Link组件统一渲染站内/站外链接配套测试见 MarkdownContent.test.tsx。此外core-components还同步将依赖rc-progress升级到3.4.015201b1032并移除了主题调色板中bursts对象的引用385389d23c配合下方theme的弃用变更。五、主题系统bursts弃用与genPageTheme增强backstage/theme0.2.16-next.1做了两件事变更ff4f56eb49bursts对象正式标记弃用BackstagePaletteAdditions中的bursts对象被 deprecated将在未来版本移除。此前许多页面标题的背景图案依赖bursts现在应迁移到新的页面标题方案genPageTheme新增可选fontColor选项genPageTheme函数现在接受一个可选的 options 对象其中包含可选的fontColor未提供时默认使用白色。这意味着自定义页面主题时可以显式控制标题文字的字体颜色而不必再依赖bursts提供的默认前景色。对主题开发者的迁移建议凡是在自定义主题中读取palette.bursts的地方都应改为基于genPageTheme的 options 传入fontColor避免在未来版本升级时出现编译错误或样式缺失。六、后端基础设施与安全依赖升级本次版本在横向上做了一轮基础设施依赖升级尤其是围绕knex与git-url-parse两条线6.1knex升级到^2.0.0以下后端包统一将knex依赖升级为^2.0.0变更679b32172e涉及几乎所有使用数据库的后端模块包括但不限于backstage/backend-common、backstage/backend-tasks、backstage/backend-test-utilsbackstage/plugin-catalog-backend、backstage/plugin-scaffolder-backend、backstage/plugin-tech-insights-backendbackstage/plugin-auth-backend、backstage/plugin-app-backend、backstage/plugin-techdocs-backendbackstage/plugin-bazaar-backend、backstage/plugin-code-coverage-backendbackstage/plugin-search-backend-module-pg由于knex2.x属于大版本升级其行为与 1.x 存在差异升级到该版本前建议阅读 knex 2.0 的迁移说明重点关注查询构造与配置项的变化。6.2git-url-parse升级到 12.0.0修复 CVEgit-url-parse被升级到12.0.0变更e2d7b76f43官方给出的动机是传递依赖parse-url存在多个被 Snyk 检测到的 CVE 漏洞SNYK-JS-PARSEURL-2935944SNYK-JS-PARSEURL-2935947SNYK-JS-PARSEURL-2936249涉及包包括backstage/backend-common、backstage/integration、backstage/plugin-catalog-backend、backstage/plugin-catalog-import、backstage/plugin-scaffolder、backstage/plugin-scaffolder-backend、backstage/plugin-techdocs、backstage/plugin-techdocs-node、backstage/plugin-techdocs-module-addons-contrib、backstage/plugin-adr等。这提醒维护者升级依赖不仅是为了新功能也是供应链安全的重要一环。6.3 其他后端与工具链变更plugin-auth-backend0.15.0-next.2Auth provider 新增导出createAuthProviderIntegration8e03db907a为自定义 auth provider 的集成方式提供更统一的工厂入口plugin-search-backend-module-pg0.3.5-next.2PgSearchEngine的静态from方法被标记弃用423e3d8e95改用fromConfig方法实例化同时搜索结果数据新增命中关键词高亮支持highlighting matched termsplugin-search-react0.2.2-next.2修复搜索分页在清空关键词后未重置分页游标的问题60408ca9d4backstage/cli0.18.0-next.2test命令在打印--help时确保退出前刷新所有 IOf6b6fb7165避免帮助信息被截断backstage/create-app0.4.29-next.2支持通过BACKSTAGE_APP_NAME环境变量指定 Backstage 应用名称f281ad17c0适合在 CI/脚本化初始化场景中避免交互式输入BACKSTAGE_APP_NAMEmy-portal npx backstage/create-appplugin-jenkins/plugin-jenkins-backendJenkinsApi新增多分支支持8747824221plugin-kubernetes-backend/plugin-kubernetes-common修复默认从 Kubernetes API 拉取的对象列表中缺少limitranges的问题60e5f9fe68plugin-kafka-backendkafkajs升级到^2.0.08751667541plugin-vault/plugin-vault-backend除密钥名外新增path路径维度用于区分子路径下的同名密钥7ee4abdcc9plugin-badges-backend补充缺失的安装说明58fd5ee9d5plugin-catalog-backend-module-openapiopenapi-types升级到^12.0.04881dc4c84。七、插件生态横向更新一览本版本对大量既有插件仅做了依赖同步Patch 级别更新核心可见行为不变主要目的是一致地跟进core-components0.10.0-next.2、catalog-model1.1.0-next.2、theme0.2.16-next.1、plugin-catalog-react1.1.2-next.2等基础包。涉及插件包括不限于云原生/部署类plugin-kubernetes、plugin-azure-devops、plugin-cloudbuild、plugin-github-actions、plugin-github-deployments、plugin-gitops-profiles、plugin-lighthouse、plugin-newrelic、plugin-newrelic-dashboard、plugin-dynatrace可观测性/告警类plugin-sentry、plugin-rollbar、plugin-pagerduty、plugin-ilert、plugin-splunk-on-call、plugin-firehydrant、plugin-periskop、plugin-grafana依赖rc-progress升级、plugin-sonarqube、plugin-code-climate、plugin-xcmetricsCI/CD 类plugin-circleci、plugin-jenkins、plugin-buildkite、plugin-gocd、plugin-bitrise、plugin-git-release-manager搜索/文档类plugin-search、plugin-techdocs、plugin-techdocs-addons-test-utils、plugin-techdocs-react、plugin-stack-overflow、plugin-adr其他工具plugin-airbrake、plugin-allure、plugin-apache-airflow、plugin-badges、plugin-bazaar、plugin-codescene、plugin-config-schema、plugin-cost-insights、plugin-explore、plugin-fossa、plugin-gcalendar、plugin-gcp-projects、plugin-graphiql、plugin-home、plugin-kafka、plugin-org、plugin-shortcuts、plugin-todo、plugin-user-settings、plugin-tech-insights、plugin-tech-radar、plugin-vault、plugin-api-docs、plugin-catalog-graph、plugin-catalog-import、plugin-github-pull-requests-board、plugin-azure-sites等另外示例应用与示例后端example-app0.2.73-next.2、example-backend0.2.73-next.2以及techdocs-cli-embedded-app0.2.72-next.2、internal/plugin-todo-list1.0.3-next.2也都同步了上述依赖。7.1 值得关注的两个新包backstage/plugin-cost-insights-common0.1.0-next.0全新包将 cost insights 的数据层 API 类型非 React 部分抽取为独立的 isomorphic 包81dd5ea989、3e032a5de2使这些类型可以被任意后端包或其他 cost-insights 模块共享。这是本次版本中唯一以0.x新包形式亮相的模块对打算基于 cost insights 做二次开发的用户尤为重要backstage/plugin-catalog-backend-module-openapi0.1.0-next.1处于早期迭代的 OpenAPI 支持模块本次仅同步了openapi-types^12.0.0依赖。7.2tech-insights可注入的FactRetrieverRegistrybackstage/plugin-tech-insights-backend0.5.0-next.2允许将FactRetrieverRegistry注入buildTechInsightsContext变更818fa28d71从而覆盖默认的 registry 实现。这为需要自定义事实检索器注册逻辑如动态加载、远程同步事实检索器的场景提供了扩展点。八、升级与验证建议对于希望升级到该预发布版本的用户建议按以下步骤操作优先处理弃用项检查后端日志中 msgraph 的弃用警告并完成 Processor → Provider 迁移见第二节检查自定义主题代码中对palette.bursts的引用并迁移到genPageTheme的fontColor见第五节检查搜索后端对PgSearchEngine.from的调用并改用fromConfig回归验证数据库层由于knex升级到^2.0.0波及面广建议对 Catalog、Scaffolder、TechDocs、搜索等所有依赖数据库的功能做一次完整回归确认前端自定义页面自定义 Catalog 页面的团队按第一节示例手动补充EntityProcessingStatusPicker避免遗漏处理状态的过滤能力安全扫描确认git-url-parse/parse-url相关的 CVE 告警在本版本升级后消除。结语v1.4.0-next.2虽然只是预发布版本但其变更密度并不低Catalog 侧新增了处理状态过滤与默认组父级策略两个实用能力msgraph 集成的 Processor → Provider 迁移为多数据源组织架构提供了更规范的配置模型Scaffolder 则通过github:repo:create/github:repo:push补全了 GitHub 仓库操作链路并为表单控件提供了更细粒度的治理选项横向上knex2与git-url-parse12的升级则同时兼顾了功能演进与供应链安全。对使用 Backstage 构建开发者门户的团队而言这份变更日志值得逐一核对尤其是涉及弃用项的三处迁移msgraph、bursts、PgSearchEngine.from尽早迁移可以显著降低后续正式版本升级的成本。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage v1.4.0-next.2 变更深度解析：Catalog 实体处理状态过滤、Msgraph Provider 迁移与 Scaffolder 新 Action
Backstage v1.4.0-next.2 变更深度解析Catalog 实体处理状态过滤、Msgraph Provider 迁移与 Scaffolder 新 Action【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库中的 v1.4.0-next.2 变更日志逐条拆解该预发布版本中真正影响开发者的功能变更EntityProcessingStatusPicker与GroupDefaultParentEntityPolicy两项 Catalog 能力、backstage/plugin-catalog-backend-module-msgraph从处理器Processor到 Provider 的迁移指南、Scaffolder 新增的github:repo:create/github:repo:pushAction以及主题、Markdown 渲染、搜索与安全依赖升级等横向更新。读完本文你将掌握这些新能力的配置方式、迁移路径与源码级实现原理。说明v1.4.0-next.2是正式版v1.4.0发布前的第二个预发布候选-next 后缀表示 next 分支上的迭代版本本文涉及的 API 与配置均以当前仓库实际内容为准。一、Catalog 核心能力处理状态过滤与组默认父实体策略1.1 新增EntityProcessingStatusPicker一眼定位孤儿与出错实体本次版本为 Catalog 引入了一个新的过滤组件EntityProcessingStatusPicker用于按实体的**处理状态processing status**过滤列表——具体包含两类异常状态Is Orphan孤儿实体在软件目录中已经不存在对应描述文件如 YAML 已被删除或不再被拉取但仍残留在 Catalog 中的实体Has Error处理出错在解析/处理过程中出现错误的实体。从源码看该组件位于 plugins/catalog-react/src/components/EntityProcessingStatusPicker/EntityProcessingStatusPicker.tsx其核心实现是通过useEntityList()的updateFilters来下发过滤条件import { EntityErrorFilter, EntityOrphanFilter } from ../../filters; function orphanChange(value: boolean) { updateFilters({ orphan: value ? new EntityOrphanFilter(value) : undefined, }); } function errorChange(value: boolean) { updateFilters({ error: value ? new EntityErrorFilter(value) : undefined, }); } const availableAdvancedItems [Is Orphan, Has Error];组件基于CatalogAutocomplete渲染一个多选下拉框选项为Is Orphan与Has Error勾选后即把对应的EntityOrphanFilter/EntityErrorFilter注入实体列表的过滤链从而在表格中只保留满足条件的实体。这正是日常运维中最常见的两个排查场景清理失效实体、定位处理失败的配置项。接入方式默认 Catalog 页面无需任何改动——DefaultFilters会自动挂载该 Picker参见 plugins/catalog-react/src/components/DefaultFilters/DefaultFilters.tsx自定义了 Catalog 页面的用户需要手动添加变更日志给出了完整的接入示例import { CatalogFilterLayout, EntityTypePicker, UserListPicker, EntityTagPicker, EntityProcessingStatusPicker, } from backstage/plugin-catalog-react; export const CustomCatalogPage ({ columns, actions, initiallySelectedFilter owned, }: CatalogPageProps) { return ( EntityListProvider CatalogFilterLayout CatalogFilterLayout.Filters EntityKindPicker initialFiltercomponent hidden / EntityTypePicker / UserListPicker initialFilter{initiallySelectedFilter} / EntityTagPicker / EntityProcessingStatusPicker / /CatalogFilterLayout.Filters CatalogFilterLayout.Content CatalogTable columns{columns} actions{actions} / /CatalogFilterLayout.Content /CatalogFilterLayout /EntityListProvider ); };同一变更同时落在backstage/plugin-catalog与backstage/plugin-catalog-react两个包中be26d95141默认 Catalog 页的自动化挂载逻辑位于插件前端而组件本身由plugin-catalog-react导出便于被其他自定义页面复用。1.2GroupDefaultParentEntityPolicy为组实体兜底默认父级backstage/catalog-model1.1.0-next.2引入了GroupDefaultParentEntityPolicy变更4cc81372f8这是一个EntityPolicy实体策略用于给没有父级的Group实体补上默认父级。其设计动机很明确Backstage 的组织结构User/Group通常由多套数据源如 LDAP、Microsoft Graph混合导入很难保证每棵组织树都存在单一根节点。该策略可以在保留既有层级结构的前提下确保整个组层级拥有一个唯一的全局根节点——即最后兜底的父级parent of last resort。源码位于 packages/catalog-model/src/entity/policies/GroupDefaultParentEntityPolicy.ts核心逻辑如下export class GroupDefaultParentEntityPolicy implements EntityPolicy { private readonly parentRef: string; constructor(parentEntityRef: string) { const { kind, namespace, name } parseEntityRef(parentEntityRef, { defaultKind: Group, defaultNamespace: DEFAULT_NAMESPACE, }); if (kind.toUpperCase() ! GROUP) { throw new TypeError(group parent must be a group); } this.parentRef stringifyEntityRef({ kind, namespace, name, }); } async enforce(entity: Entity): PromiseEntity { if (entity.kind ! Group) { return entity; } const group entity as GroupEntity; if (group.spec.parent) { return group; // 已有父级保持原样 } // 避免让实体成为自己的父级 if (stringifyEntityRef(group) ! this.parentRef) { group.spec.parent this.parentRef; } return group; } }实现要点构造函数接收一个父实体引用如group:default/root-group通过parseEntityRef解析若解析出的 kind 不是Group会直接抛出TypeErrorenforce只对kind Group的实体生效其他实体原样放行已有spec.parent的组不会被改写从而保留既有层级带有防御性检查不会把组设为自身的父级。该策略通过EntityPolicy机制注册进 Catalog 处理管线与DefaultProcessingDatabase等处理流程共同作用于实体入库阶段。其配套测试位于 packages/catalog-model/src/entity/policies/GroupDefaultParentEntityPolicy.test.ts可用于了解各边界行为的预期表现。1.3 实体页面的其他 Catalog 变更plugin-catalog1.4.0-next.2为 Catalog 表格与 API 表格增加了隐藏的 title 列a274fe38b9使表格可按实体的title而非仅name进行过滤同时不改变表格的视觉呈现unregister entity注销实体菜单项新增visible/hidden/disabled三态定制能力258057a4b9旧有的布尔输入将在未来版本弃用visible保持可点击hidden从上下文菜单中隐藏该项disabled保留菜单项但置灰不可点击EntityLayout的表头样式修复b4b711bcc2修复鼠标悬停时EntityContextMenu按钮显示形状异常的问题。二、Microsoft Graphmsgraph集成迁移从 Processor 到 Providerbackstage/plugin-catalog-backend-module-msgraph0.4.0-next.1是一次破坏性deprecation变更为了让该插件的实体提供配置与其他 Provider 对齐官方将旧的entity processor用法与旧版配置标记为弃用统一迁移到entity provider用法。日志中会持续输出警告直到你完成迁移弃用部分将在过渡期后移除。2.1 旧用法回顾旧版存在两种使用方式——处理器或 Provider方式一注册为处理器Processor// packages/backend/src/plugins/catalog.ts builder.addProcessor( MicrosoftGraphOrgReaderProcessor.fromConfig(env.config, { logger: env.logger, // [...] }), );方式二注册为实体 ProviderEntityProvider// packages/backend/src/plugins/catalog.ts builder.addEntityProvider( MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { id: https://graph.microsoft.com/v1.0, target: https://graph.microsoft.com/v1.0, logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), // [...] }), );旧版配置文件两种方式共用# app-config.yaml catalog: processors: microsoftGraphOrg: providers: - target: https://graph.microsoft.com/v1.0 # [...]2.2 新配置与注册方式迁移后的配置以catalog.providers.microsoftGraphOrg为根每个 Provider 用稳定的 providerId作为键该 ID 会成为所有摄入数据 location key 的一部分# app-config.yaml catalog: providers: microsoftGraphOrg: # 若你曾使用弃用的 entity provider 配置 # 沿用 target 的值可保持所有数据的 location key 不变 providerId: # 稳定的 ID将作为所有摄入数据 location key 的一部分 target: https://graph.microsoft.com/v1.0 # [...]对应的后端注册代码则不再需要在fromConfig中传id/target这些信息改由配置提供// packages/backend/src/plugins/catalog.ts builder.addEntityProvider( MicrosoftGraphOrgEntityProvider.fromConfig(env.config, { logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), // [...] }), );2.3 多 Provider 差异化 Transformer 的场景如果你此前注册了多个 entity provider并且每个 provider 都配有各自不同的 transformer迁移后可以直接在同一个fromConfig调用中通过以 provider ID 为键的 Record一次性传入这些 transformer从而让配置驱动的多 Provider 与各自的转换逻辑一一对应。这是本次迁移最值得注意的细节它把原来分散在代码里的多份addEntityProvider调用收敛为一份配置 一个注册点。迁移提示变更日志指出完整的配置选项文档含 config 与 provider 注册方式收录于该插件目录下的 READMEplugins/catalog-backend-module-msgraph。三、Scaffolder 新 Action 与参数能力增强3.1 新增github:repo:create与github:repo:pushbackstage/plugin-scaffolder-backend1.4.0-next.2新增两个 GitHub Action变更2db07887cb实现在 plugins/scaffolder-backend-module-github/src/actionsgithub:repo:creategithubRepoCreate.ts直接创建一个 GitHub 仓库空仓库不依赖本地工作目录内容github:repo:pushgithubRepoPush.ts将本地已生成的内容推送到新建/已有仓库。两者配合可覆盖生成代码 - 建仓 - 推送的完整链路。以github:repo:create为例从源码可以确认其输入参数非常丰富return createTemplateAction({ id: github:repo:create, description: Creates a GitHub repository., examples, schema: { input: { ...inputProps, }, output: { remoteUrl: outputProps.remoteUrl, repoContentsUrl: outputProps.repoContentsUrl, }, }, async handler(ctx) { const { repoUrl, description, homepage, access, repoVisibility private, // 默认私有 deleteBranchOnMerge false, allowMergeCommit true, // 默认允许 merge commit allowSquashMerge true, // 默认允许 squash merge squashMergeCommitTitle COMMIT_OR_PR_TITLE, squashMergeCommitMessage COMMIT_MESSAGES, allowRebaseMerge true, // 默认允许 rebase merge allowAutoMerge false, allowUpdateBranch false, collaborators, hasProjects undefined, hasWiki undefined, hasIssues undefined, topics, repoVariables, secrets, // ... } ctx.input;要点输入侧通过repoUrl指定目标仓库可配置可见性repoVisibility默认private、描述、主页、协作者collaborators、主题topics、仓库级变量repoVariables与密钥secrets等输出侧提供remoteUrl与repoContentsUrl便于后续 Action如github:repo:push或模板步骤引用大量布尔选项带有默认值如allowMergeCommit、allowSquashMerge、allowRebaseMerge默认开启未显式配置时行为可预期示例定义见 githubRepoCreate.examples.ts配套测试见 githubRepoCreate.test.ts 与 githubRepoPush.test.ts。3.2 GitLab Merge Request Action支持删除源分支plugin-scaffolder-backend1.4.0-next.2同时更新了 GitLab Merge Request Action变更4baf8a4ece现在允许在合并后删除源分支source branch便于模板在合并请求被接受后自动清理分支减少仓库中的残留分支。3.3RepoUrlPicker与OwnedEntityPicker的表单选项增强backstage/plugin-scaffolder1.4.0-next.2带来两处与模板表单体验相关的改动RepoUrlPicker新增allowedReposui:optiond8eb82f447允许限定用户在创建模板时只能选择指定仓库集合适用于将模板发布范围收敛到特定仓库的治理场景同时repoName字段被拆分为独立组件便于单独定制OwnedEntityPicker新增allowArbitraryValuesui:option14146703e5与EntityPicker中已有的同名选项行为对齐允许用户在候选实体之外输入任意值适用于目标实体尚未入库、或需手工指定任意实体引用的场景。# 模板参数中启用任意值输入的示意OwnedEntityPicker 或 EntityPicker ui:options: allowArbitraryValues: true四、前端核心MarkdownContent 支持链接与图片 URI 转换backstage/core-components0.10.0-next.2为MarkdownContent组件新增transformLinkUri与transformImageUri两个 props变更32204fa794。源码位于 packages/core-components/src/components/MarkdownContent/MarkdownContent.tsxtype Props { content: string; dialect?: gfm | common-mark; linkTarget?: Options[linkTarget]; transformLinkUri?: (href: string) string; transformImageUri?: (href: string) string; className?: string; }; export function MarkdownContent(props: Props) { const { content, dialect gfm, linkTarget, transformLinkUri, transformImageUri, className, } props; // ... return ( ReactMarkdown remarkPlugins{dialect gfm ? [gfm] : []} rehypePlugins{dialect gfm ? gfmRehypePlugins : []} className{${classes.markdown} ${className ?? }.trim()} children{content} components{components} linkTarget{linkTarget} transformLinkUri{transformLinkUri} transformImageUri{transformImageUri} / ); }使用方式非常直接传入一个(href: string) string的函数即可在渲染前改写 Markdown 中的链接与图片地址。典型场景包括将相对路径链接解析为绝对 URL过滤或重写外部链接如强制 HTTPS、追加安全 token为内嵌图片拼接 CDN 前缀或鉴权参数。这两个 props 最终透传给底层的react-markdown因此行为与 react-markdown 的transformLinkUri/transformImageUri语义一致。需要注意的是MarkdownContent默认启用 GFM 方言且通过rehype-sanitize对 HTML 做白名单过滤配合Link组件统一渲染站内/站外链接配套测试见 MarkdownContent.test.tsx。此外core-components还同步将依赖rc-progress升级到3.4.015201b1032并移除了主题调色板中bursts对象的引用385389d23c配合下方theme的弃用变更。五、主题系统bursts弃用与genPageTheme增强backstage/theme0.2.16-next.1做了两件事变更ff4f56eb49bursts对象正式标记弃用BackstagePaletteAdditions中的bursts对象被 deprecated将在未来版本移除。此前许多页面标题的背景图案依赖bursts现在应迁移到新的页面标题方案genPageTheme新增可选fontColor选项genPageTheme函数现在接受一个可选的 options 对象其中包含可选的fontColor未提供时默认使用白色。这意味着自定义页面主题时可以显式控制标题文字的字体颜色而不必再依赖bursts提供的默认前景色。对主题开发者的迁移建议凡是在自定义主题中读取palette.bursts的地方都应改为基于genPageTheme的 options 传入fontColor避免在未来版本升级时出现编译错误或样式缺失。六、后端基础设施与安全依赖升级本次版本在横向上做了一轮基础设施依赖升级尤其是围绕knex与git-url-parse两条线6.1knex升级到^2.0.0以下后端包统一将knex依赖升级为^2.0.0变更679b32172e涉及几乎所有使用数据库的后端模块包括但不限于backstage/backend-common、backstage/backend-tasks、backstage/backend-test-utilsbackstage/plugin-catalog-backend、backstage/plugin-scaffolder-backend、backstage/plugin-tech-insights-backendbackstage/plugin-auth-backend、backstage/plugin-app-backend、backstage/plugin-techdocs-backendbackstage/plugin-bazaar-backend、backstage/plugin-code-coverage-backendbackstage/plugin-search-backend-module-pg由于knex2.x属于大版本升级其行为与 1.x 存在差异升级到该版本前建议阅读 knex 2.0 的迁移说明重点关注查询构造与配置项的变化。6.2git-url-parse升级到 12.0.0修复 CVEgit-url-parse被升级到12.0.0变更e2d7b76f43官方给出的动机是传递依赖parse-url存在多个被 Snyk 检测到的 CVE 漏洞SNYK-JS-PARSEURL-2935944SNYK-JS-PARSEURL-2935947SNYK-JS-PARSEURL-2936249涉及包包括backstage/backend-common、backstage/integration、backstage/plugin-catalog-backend、backstage/plugin-catalog-import、backstage/plugin-scaffolder、backstage/plugin-scaffolder-backend、backstage/plugin-techdocs、backstage/plugin-techdocs-node、backstage/plugin-techdocs-module-addons-contrib、backstage/plugin-adr等。这提醒维护者升级依赖不仅是为了新功能也是供应链安全的重要一环。6.3 其他后端与工具链变更plugin-auth-backend0.15.0-next.2Auth provider 新增导出createAuthProviderIntegration8e03db907a为自定义 auth provider 的集成方式提供更统一的工厂入口plugin-search-backend-module-pg0.3.5-next.2PgSearchEngine的静态from方法被标记弃用423e3d8e95改用fromConfig方法实例化同时搜索结果数据新增命中关键词高亮支持highlighting matched termsplugin-search-react0.2.2-next.2修复搜索分页在清空关键词后未重置分页游标的问题60408ca9d4backstage/cli0.18.0-next.2test命令在打印--help时确保退出前刷新所有 IOf6b6fb7165避免帮助信息被截断backstage/create-app0.4.29-next.2支持通过BACKSTAGE_APP_NAME环境变量指定 Backstage 应用名称f281ad17c0适合在 CI/脚本化初始化场景中避免交互式输入BACKSTAGE_APP_NAMEmy-portal npx backstage/create-appplugin-jenkins/plugin-jenkins-backendJenkinsApi新增多分支支持8747824221plugin-kubernetes-backend/plugin-kubernetes-common修复默认从 Kubernetes API 拉取的对象列表中缺少limitranges的问题60e5f9fe68plugin-kafka-backendkafkajs升级到^2.0.08751667541plugin-vault/plugin-vault-backend除密钥名外新增path路径维度用于区分子路径下的同名密钥7ee4abdcc9plugin-badges-backend补充缺失的安装说明58fd5ee9d5plugin-catalog-backend-module-openapiopenapi-types升级到^12.0.04881dc4c84。七、插件生态横向更新一览本版本对大量既有插件仅做了依赖同步Patch 级别更新核心可见行为不变主要目的是一致地跟进core-components0.10.0-next.2、catalog-model1.1.0-next.2、theme0.2.16-next.1、plugin-catalog-react1.1.2-next.2等基础包。涉及插件包括不限于云原生/部署类plugin-kubernetes、plugin-azure-devops、plugin-cloudbuild、plugin-github-actions、plugin-github-deployments、plugin-gitops-profiles、plugin-lighthouse、plugin-newrelic、plugin-newrelic-dashboard、plugin-dynatrace可观测性/告警类plugin-sentry、plugin-rollbar、plugin-pagerduty、plugin-ilert、plugin-splunk-on-call、plugin-firehydrant、plugin-periskop、plugin-grafana依赖rc-progress升级、plugin-sonarqube、plugin-code-climate、plugin-xcmetricsCI/CD 类plugin-circleci、plugin-jenkins、plugin-buildkite、plugin-gocd、plugin-bitrise、plugin-git-release-manager搜索/文档类plugin-search、plugin-techdocs、plugin-techdocs-addons-test-utils、plugin-techdocs-react、plugin-stack-overflow、plugin-adr其他工具plugin-airbrake、plugin-allure、plugin-apache-airflow、plugin-badges、plugin-bazaar、plugin-codescene、plugin-config-schema、plugin-cost-insights、plugin-explore、plugin-fossa、plugin-gcalendar、plugin-gcp-projects、plugin-graphiql、plugin-home、plugin-kafka、plugin-org、plugin-shortcuts、plugin-todo、plugin-user-settings、plugin-tech-insights、plugin-tech-radar、plugin-vault、plugin-api-docs、plugin-catalog-graph、plugin-catalog-import、plugin-github-pull-requests-board、plugin-azure-sites等另外示例应用与示例后端example-app0.2.73-next.2、example-backend0.2.73-next.2以及techdocs-cli-embedded-app0.2.72-next.2、internal/plugin-todo-list1.0.3-next.2也都同步了上述依赖。7.1 值得关注的两个新包backstage/plugin-cost-insights-common0.1.0-next.0全新包将 cost insights 的数据层 API 类型非 React 部分抽取为独立的 isomorphic 包81dd5ea989、3e032a5de2使这些类型可以被任意后端包或其他 cost-insights 模块共享。这是本次版本中唯一以0.x新包形式亮相的模块对打算基于 cost insights 做二次开发的用户尤为重要backstage/plugin-catalog-backend-module-openapi0.1.0-next.1处于早期迭代的 OpenAPI 支持模块本次仅同步了openapi-types^12.0.0依赖。7.2tech-insights可注入的FactRetrieverRegistrybackstage/plugin-tech-insights-backend0.5.0-next.2允许将FactRetrieverRegistry注入buildTechInsightsContext变更818fa28d71从而覆盖默认的 registry 实现。这为需要自定义事实检索器注册逻辑如动态加载、远程同步事实检索器的场景提供了扩展点。八、升级与验证建议对于希望升级到该预发布版本的用户建议按以下步骤操作优先处理弃用项检查后端日志中 msgraph 的弃用警告并完成 Processor → Provider 迁移见第二节检查自定义主题代码中对palette.bursts的引用并迁移到genPageTheme的fontColor见第五节检查搜索后端对PgSearchEngine.from的调用并改用fromConfig回归验证数据库层由于knex升级到^2.0.0波及面广建议对 Catalog、Scaffolder、TechDocs、搜索等所有依赖数据库的功能做一次完整回归确认前端自定义页面自定义 Catalog 页面的团队按第一节示例手动补充EntityProcessingStatusPicker避免遗漏处理状态的过滤能力安全扫描确认git-url-parse/parse-url相关的 CVE 告警在本版本升级后消除。结语v1.4.0-next.2虽然只是预发布版本但其变更密度并不低Catalog 侧新增了处理状态过滤与默认组父级策略两个实用能力msgraph 集成的 Processor → Provider 迁移为多数据源组织架构提供了更规范的配置模型Scaffolder 则通过github:repo:create/github:repo:push补全了 GitHub 仓库操作链路并为表单控件提供了更细粒度的治理选项横向上knex2与git-url-parse12的升级则同时兼顾了功能演进与供应链安全。对使用 Backstage 构建开发者门户的团队而言这份变更日志值得逐一核对尤其是涉及弃用项的三处迁移msgraph、bursts、PgSearchEngine.from尽早迁移可以显著降低后续正式版本升级的成本。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
