Backstage v1.3.0-next.0 版本深度解析Catalog 构建器、Scaffolder Gerrit 集成与 TechDocs 渲染重构【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章基于 Backstage 仓库的发布说明文档 docs/releases/v1.3.0-next.0-changelog.md 展开系统梳理 v1.3.0-next.0 里程碑版本中各个backstage/*包的新特性Minor Changes与缺陷修复Patch Changes。作为 Backstage 1.3 系列的首个 next 预发布版本它同时承载了 v1.3.0 的新功能演进与 v1.2.x 系列补丁的反向合入。阅读本文后你将掌握 CatalogBuilder 的新式参数调用、Scaffolder 自定义字段读取表单上下文、Gerrit 发布动作与仓库选择器的落地方式、TechDocs 影子 DOM 渲染重构以及 auth、LDAP、CLI 等多处增强的实际用法与源码依据。一、catalog-backendCatalogBuilder 支持数组参数直传变更内容backstage/plugin-catalog-backend1.2.0-next.0的 Minor Changes 允许在调用CatalogBuilder.addEntityProvider时直接传入一个实体 Provider 数组而不再需要手动展开spread。变更前必须展开数组builder.addEntityProvider(...getArrayOfProviders());变更后可以直接传入数组builder.addEntityProvider(getArrayOfProviders());源码印证这一改动的实现位于 plugins/catalog-backend/src/service/CatalogBuilder.tsaddEntityProvider( ...providers: ArrayEntityProviderEntry | ArrayEntityProviderEntry ): CatalogBuilder { this.entityProviders.push(...providers.flat()); return this; }从源码结构可以看出方法的可变参数签名同时接受EntityProviderEntry或EntityProviderEntry[]内部通过providers.flat()将嵌套数组拍平后统一 push。因此两种调用方式在语义上完全等价。类似的数组参数化风格也体现在同文件的addProcessor方法上CatalogBuilder.ts均采用ArrayT | T[]flat()的模式。该 API 的典型消费场景见 plugins/catalog-backend/src/service/CatalogPlugin.ts新后端系统中的 catalog 扩展点同样通过展开数组的方式收集 Provider测试代码中如 getEntitiesPerformance.test.ts 也以单参数形式调用catalog.addEntityProvider(new SyntheticLoadEntitiesProvider(load, {}))印证了新签名对所有既有调用点的兼容性。二、scaffolder自定义字段读取表单上下文 Gerrit 集成backstage/plugin-scaffolder1.3.0-next.0带来了两个重要能力自定义字段扩展可读取整个表单数据以及面向 Gerrit 的RepoUrlPicker。2.1 自定义字段通过 formContext 读取其他字段此前自定义字段扩展只能访问自身绑定的字段值本次新增的能力让自定义字段组件可以读取表单中其他字段的数据从而实现字段间的联动例如根据前面选择的组织动态过滤后续选项。const CustomFieldExtensionComponent (props: FieldExtensionComponentPropsstring[]) { const { formData } props.formContext; // formData 即整个表单当前已填写的全部字段值 // ... }; const CustomFieldExtension scaffolderPlugin.provide( createScaffolderFieldExtension({ name: ..., component: CustomFieldExtensionComponent, validation: ... }) );关键点在于props.formContext.formData它暴露的是完整表单的数据快照自定义字段组件可以据此读取任意其他字段的当前值配合validation函数还可以实现跨字段校验。这一能力让 Backstage 的软件模板Software Templates表单可以构建更复杂的动态交互。2.2 Gerrit 的 RepoUrlPicker同版本实现了RepoUrlPicker对 Gerrit 的支持。其前端实现位于 plugins/scaffolder/src/components/fields/RepoUrlPicker/GerritRepoPicker.tsx该组件提供两个输入框ownerGerrit 项目所有者parent必填Gerrit 中的父项目workspace用于确定新仓库在项目层级中的挂载位置。在模板的ui:options中RepoUrlPicker还支持通过 schema.ts 中的allowedHosts、allowedOrganizations、allowedOwners、allowedProjects、allowedRepos以及requestUserCredentials含gerrit作用域配置等选项来约束可选范围与动态请求用户凭据。配套的集成层变更见backstage/integration1.2.1-next.0resolveUrl现在能正确处理 Gerrit 的绝对路径变更号 72dfcbc8bf为仓库地址的解析提供基础保障。2.3 后端新增 publish:gerrit 动作backstage/plugin-scaffolder-backend1.3.0-next.0的 Minor Changes 新增了面向 Gerrit 的发布动作。发布说明文档中记录的名字为gerrit:publish而在当前仓库源码中该动作的实际实现 id 为publish:gerrit见 plugins/scaffolder-backend-module-gerrit/src/actions/gerrit.ts阅读历史版本时需注意命名差异。从实现源码可以梳理出该动作的完整工作流gerrit.ts解析 repoUrl通过parseRepoUrl拆出repo、host、owner、workspace校验集成配置通过integrations.gerrit.byHost(host)查找对应 Gerrit 实例配置若缺失则抛出InputErrorworkspace缺失同样报错创建项目调用 Gerrit REST APIPUT /a/projects/{projectName}请求体包含parent、description、branches: [defaultBranch]、owners与create_empty_commit: false以 HTTP 201 为成功判定生成带 Change-Id 的提交信息generateCommitMessage会生成随机Change-Id: I40位hex追加到提交信息中Gerrit 强制要求初始化并推送通过initRepoAndPush将工作区内容初始化 git 仓库并推送到 Gerrit支持signCommit使用 PGP 私钥签名签名密钥取自集成配置的commitSigningKey或全局scaffolder.defaultCommitSigningKey。动作的输入参数全部来自动作 schema见 gerrit.ts汇总如下参数类型必填默认值/说明repoUrlstring是仓库位置如gerrit.com?repomy-repoowneruserworkspaceparentdescriptionstring否仓库描述defaultBranchstring否默认分支默认mastergitCommitMessagestring否提交信息默认initial commit最终会追加 Change-IdgitAuthorNamestring否提交作者名默认取scaffolder.defaultAuthor.name兜底ScaffoldergitAuthorEmailstring否提交作者邮箱默认取scaffolder.defaultAuthor.emailsourcePathstring否工作区内作为仓库根目录的路径缺省为整个工作区signCommitboolean否是否用配置的 PGP 私钥签名提交动作输出三个字段remoteUrlGerrit 远端地址、repoContentsUrl基于gitilesBaseUrl拼接的文件浏览地址、commitHash初始提交哈希。动作支持 dry-run 模式supportsDryRun: true在ctx.isDryRun时会记录参数日志并输出占位哈希abcd-dry-run-1234。对应的测试与示例见 gerrit.test.ts 与 gerrit.examples.test.ts。此外scaffolder-backend 还改进了一处错误提示当publish:github动作创建仓库失败时会给出更详细的失败原因说明变更号 6901f6be4a方便定位 token 权限、仓库重名等常见问题。三、kubernetes支持 StatefulSet 数据拉取与展示backstage/plugin-kubernetes-backend0.6.0-next.0与backstage/plugin-kubernetes-common0.3.0-next.0同步引入了对StatefulSet有状态工作负载的数据获取支持变更号 4328737af6后端可以从 Kubernetes 集群拉取 StatefulSet 资源数据前端backstage/plugin-kubernetes0.6.6-next.0则以与 Deployment 一致的手风琴accordion形式展示 StatefulSet 信息。同版本 Kubernetes 插件还修复了 HPA 匹配问题当同名 HPA 部署在多个 namespace 时此前可能发生错误的匹配现已修复变更号 81304e3e91。另外kubernetes-backend 的 Patch 变更修复了 Azure token 的缓存与刷新机制变更号 0c70cd8e1d避免对 Azure Identity 的过度调用。四、TechDocs渲染管线重构与构建日志输出v1.3.0-next.0 对 TechDocs 前端渲染与后端构建日志做了一组密集改动是本次版本中改动最深入的模块之一。4.1 前端渲染重构plugin-techdocsaddons 渲染修复EntityTechdocsContent组件改为使用对象而非Route元素来挂载 addons否则子页面上的 outlet 为 null 导致 addons 无法渲染变更号 881fbd7e8d。样式转换器重构将 reader 的样式转换逻辑拆分为独立文件抽出一个处理每条规则的 hook再抽出一个返回转换器的 hook 用于把规则注入指定元素的 head 标签变更号 17c059dfd0sanitizeDOM转换器也改为 hook 形式变更号 816f7475ec。addons 渲染过程微调在页面样式加载完成并更新侧边栏位置之前不显示侧边栏避免每次渲染 reader 页面时重复创建已存在的侧边栏位置居中样式加载事件避免多个位置在 Shadow DOM 中设置 opacity 导致画面多次闪烁变更号 3b45ad701f。路由细化EntityDocsPage的路径变得更具体并补充了该页面子路由的集成测试变更号 50ff56a80f。4.2 TechDocsShadowDom 组件plugin-techdocs-react配套的backstage/plugin-techdocs-react1.0.1-next.0新增了TechDocsShadowDom组件变更号 3b45ad701f它接收一棵元素树与一个onAppend处理器在把元素树追加到 shadow root 时调用onAppend处理器同时派发一个样式已加载事件让各转换器知道 computed styles 已就绪可供消费。这为上述样式注入与侧边栏定位问题提供了统一的机制基础。4.3 构建日志输出到后端日志流plugin-techdocs-backendbackstage/plugin-techdocs-backend1.1.2-next.0支持把 TechDocs 构建日志输出到一个 logging transport变更号 5d66d4ff67从而让用户无需依赖最终用户从浏览器端抓取信息即可在后端应用日志中捕获文档构建失败的调试信息。最常见的用法是让构建日志与后端其余日志写入同一位置。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, // 传入 buildLogTransport 即可把构建日志捕获到后端日志流 buildLogTransport: env.logger, config: env.config, discovery: env.discovery, cache: env.cache, }); }4.4 create-app 模板同步注册 TechDocs addonsbackstage/create-app0.4.28-next.0的变更同步到了新应用模板在 catalog 实体页面注册 TechDocs addons。对于已有应用可手动在 packages/app/src/components/catalog/EntityPage.tsx 中按下述 diff 添加 import { TechDocsAddons } from backstage/plugin-techdocs-react; import { ReportIssue, } from backstage/plugin-techdocs-module-addons-contrib; const techdocsContent ( EntityTechdocsContent TechDocsAddons ReportIssue / /TechDocsAddons /EntityTechdocsContent ); const defaultEntityPage ( ... EntityLayout.Route path/docs titleDocs {techdocsContent} /EntityLayout.Route ... );serviceEntityPage、websiteEntityPage等页面的/docs路由也需要同样替换。五、catalog-backend-module-ldapLDAP 连接支持 TLSbackstage/plugin-catalog-backend-module-ldap0.5.0-next.0新增了向 LDAP 连接传递 TLS 配置的能力变更号 1f83f0bc84。从 plugins/catalog-backend-module-ldap/src/ldap/client.ts 的实现看TLS 配置项包含tls.certs客户端证书文件路径读取后用于创建安全上下文tls.keys客户端私钥文件路径与certs配合使用tls.rejectUnauthorized是否校验服务端证书对应 Node.jsConnectionOptions.rejectUnauthorized。只有当tlsOptions中任一字段有值时连接才会携带tlsOptions传给 LDAP 客户端保证未配置 TLS 时行为不变。对应的配置解析测试见 config.test.ts。这使 Backstage 可以对接要求双向 TLSmTLS或自定义证书链的 LDAP 目录服务。六、catalog-backend-module-gitlab跳过无精确文件匹配的仓库backstage/plugin-catalog-backend-module-gitlab0.1.4-next.0新增skipReposWithoutExactFileMatch标志变更号 3ac4522537当仓库中不存在组件定义文件时不再创建 location 对象从而显著减少对 GitLab 的 404 请求数量const processor GitLabDiscoveryProcessor.fromConfig(config, { logger, skipReposWithoutExactFileMatch: true, });警告该新功能不支持在仓库文件路径中使用 glob 通配符仅适用于精确文件路径匹配的场景。七、CLI 与 create-appyarn 锁文件与开发体验改进7.1 cli新版本 yarn 锁文件支持 baseUrl 警告backstage/cli0.17.2-next.0的两个 Patch 变更锁文件解析升级变更号 4f73352608Lockfile 解析器同时支持新版本 yarn 与传统的 yarn 1 版本baseUrl 一致性警告变更号 6de866ea74前端启动时若检测到app.baseUrl与backend.baseUrl相同会输出控制台警告——两者指向同一地址通常意味着前后端同源部署可能引发认证 cookie 或代理配置问题提示开发者检查配置。7.2 create-app--version 输出当前 release 版本backstage/create-app0.4.28-next.0的--version标志现在输出当前 Backstage release 的版本号而不再是 create-app 自身的版本变更号 935d8515da方便快速确认脚手架与主框架的对应关系。八、auth 相关TokenFactory 与 IdentityClient 的算法配置backstage/plugin-auth-backend0.14.1-next.0为TokenFactory增加了可配置的签名算法字段变更号 f6aae90e4ebackstage/plugin-auth-node0.2.2-next.0为IdentityClient增加了可配置的算法数组变更号 9079a78078。这两项改动使服务间 token 的签发与校验可以使用非默认的 JWT 签名算法适用于需要与既有身份体系对齐或遵循特定安全策略的部署。九、catalog 插件过滤器支持数组 无障碍改进backstage/plugin-catalog1.2.1-next.0isKind、isComponentType、isNamespace过滤函数现在允许传入一个可选值数组变更号 449dcef98e一次匹配多个类型/命名空间无障碍a11y改进变更号 1f70704580为默认表格的Action按钮补充了屏幕阅读器可读的描述元素backstage/plugin-catalog-react1.1.1-next.0将EntityLifecyclePicker、EntityOwnerPicker、EntityTagPicker包裹在label元素中分组名Typography组件由h6改为span并为List组件补充aria-label、为MenuItem容器设置menuitem角色。十、core-components侧边栏、无障碍与依赖更新backstage/core-components0.9.5-next.0的 Patch 变更修复侧边栏中无子菜单的条目被错误添加右箭头图标的问题变更号 65840b17be依赖react-hookz/web升级到^14.0.0变更号 6968b65ba1无障碍更新变更号 96d1e01641为Select组件添加aria-label调整Table组件头部使用的标题层级保证页面标题层级结构正确。create-app 同步要求现有应用在 packages/app/src/components/Root/Root.tsx 中为侧边栏 Logo 链接添加aria-labelHomeconst SidebarLogo () { const classes useSidebarLogoStyles(); const { isOpen } useContext(SidebarContext); return ( div className{classes.root} Link component{NavLink} to/ underlinenone className{classes.link} aria-labelHome {isOpen ? LogoFull / : LogoIcon /} /Link /div ); };十一、其他值得关注的 Patch 变更11.1 后端基础设施backstage/backend-common0.13.6-next.0合入0.13.4的luxon依赖修复f72a6b8c62与0.13.5的 AWS S3 读取补丁5b22a8c97fbackstage/backend-tasks0.3.2-next.0失败任务循环重试时每次失败都会输出包含重试次数attempts的警告日志fde10d24f6便于观察持续失败的后台任务backstage/plugin-search-backend-node0.6.2-next.0索引错误会被向上传播不再让任务调度器误以为索引进度成功e7794a0aaa。11.2 插件级小改进插件变更plugin-adrAdrSearchResultListItem支持搜索词高亮a6458a120bplugin-allure导出isAllureReportAvailable与ALLURE_PROJECT_ID_ANNOTATION供插件外部使用6387b7a98aplugin-cost-insights配置 schema 中补充缺失的exporteb2544b21bplugin-pagerduty修复创建事故后告警不显示的问题76bf6400feplugin-catalog-backend-module-aws/-gerrit内联配置接口eb2544b21bplugin-kubernetesHPA 在多个 namespace 同名时的匹配修复81304e3e9111.3 纯依赖更新包以下包在本版本中没有自身代码变更仅跟随上游依赖版本更新均为 Patch Changes在此一并列出以便升级核对依赖backend-common/integration系列plugin-app-backend、plugin-airbrake-backend、plugin-azure-devops-backend、plugin-badges-backend、plugin-code-coverage-backend、plugin-graphql-backend、plugin-jenkins-backend、plugin-kafka-backend、plugin-permission-backend、plugin-permission-node、plugin-proxy-backend、plugin-rollbar-backend、plugin-todo-backend、techdocs-cli、techdocs-common、plugin-techdocs-node等依赖core-components/plugin-catalog-react系列plugin-airbrake、plugin-api-docs、plugin-azure-devops、plugin-badges、plugin-bitrise、plugin-catalog-graph、plugin-catalog-import、plugin-circleci、plugin-cloudbuild、plugin-code-climate、plugin-codescene、plugin-config-schema、plugin-explore、plugin-firehydrant、plugin-fossa、plugin-gcalendar、plugin-gcp-projects、plugin-git-release-manager、plugin-github-actions、plugin-github-deployments、plugin-gitops-profiles、plugin-gocd、plugin-graphiql、plugin-home、plugin-ilert、plugin-jenkins、plugin-kafka、plugin-lighthouse、plugin-newrelic、plugin-newrelic-dashboard、plugin-org、plugin-rollbar、plugin-sentry、plugin-shortcuts、plugin-sonarqube、plugin-splunk-on-call、plugin-stack-overflow、plugin-tech-insights、plugin-tech-radar、plugin-user-settings、plugin-xcmetrics、app-defaults、dev-utils、integration-react、plugin-scaffolder-backend-module-cookiecutter/-rails/-yeoman、plugin-search、plugin-search-backend、plugin-search-backend-module-elasticsearch/-pg等全量依赖更新的示例应用example-app、example-backend、techdocs-cli-embedded-app、internal/plugin-todo-list、internal/plugin-todo-list-backend以及plugin-catalog-backend-module-azure/-bitbucket/-github/-msgraph等。十二、升级建议与版本注意事项锁文件与 CLI升级backstage/cli到0.17.2-next.0后可解析新版本 yarn 锁文件若前后端 baseUrl 相同启动时会看到警告提示可借此机会核对部署拓扑。create-app 模板改动若你的应用由早期 create-app 生成需要手动补上 TechDocs addonsReportIssue与侧边栏 Logo 的aria-label详见本文 4.4 与 10 节的 diff。Gerrit 发布动作的命名发布说明中的gerrit:publish在当前仓库源码中的动作 id 为publish:gerrit使用时以源码中的动作 id 为准同时需确认app-config中已配置 Gerrit 集成含username、password、gitilesBaseUrl、cloneUrl。GitLab Discovery 新标志skipReposWithoutExactFileMatch能减少 404 请求但不支持 glob 路径仅适用于精确文件路径。LDAP TLStls.certs与tls.keys是文件路径需保证后端进程可读rejectUnauthorized未配置时保持原有校验行为。总体而言v1.3.0-next.0 是一次功能与质量并进的预发布Scaffolder 的 Gerrit 支持与字段联动补全了模板工作流的关键拼图TechDocs 的 Shadow DOM 渲染重构为 addons 生态打下更稳定的基础而 catalog/kubernetes/auth 等模块的增强则持续提升 Backstage 作为开发者门户框架的工程化能力。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考