Backstage v1.19.0 版本深度解析新后端启动命令转正、声明式前端集成持续演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南基于 docs/releases/v1.19.0-changelog.md 编写。Backstage 是一个用于构建开发者门户Developer Portal的开源框架v1.19.0 是其在「新后端系统new backend system」与「声明式前端集成declarative integration」两条主线上取得关键进展的版本EXPERIMENTAL_BACKEND_START启动方式正式转正为默认行为前端frontend-plugin-api/frontend-app-api的 API 形态进一步收敛同时 TechDocs、Scaffolder、Catalog、Auth、Kubernetes 等多个插件迎来功能性增强。读完本文你将掌握 v1.19.0 的全部破坏性变更、迁移路径与关键新能力并能对照仓库源码验证其底层实现。一、backstage/cli0.23.0新后端start命令成为默认这是 v1.19.0 中最具里程碑意义的变化。1.1 环境变量开关翻转EXPERIMENTAL_BACKEND_START→ 默认 →LEGACY_BACKEND_START此前通过设置EXPERIMENTAL_BACKEND_START开启的新后端start命令在本版本中正式成为默认行为。如果你尚未迁移到新后端系统官方给出的回退方式是设置LEGACY_BACKEND_START环境变量# 使用新后端 start 命令v1.19.0 起为默认 yarn start-backend # 尚未迁移到新后端系统时回退到旧行为 LEGACY_BACKEND_START1 yarn start-backend在仓库的 packages/cli/CHANGELOG.md 中可以确认这一变更提交7077dbf131也可以看到后续版本中该标志逐步被标记为 deprecated 并最终移除的完整生命周期。升级提示如果你还在使用旧的 Webpack 构建方式启动后端建议在升级到 v1.19.0 之前优先完成新后端系统的迁移而不是长期依赖LEGACY_BACKEND_START。1.2 底层机制从 Webpack 到 Node.js Loaders新命令在实现机制上有根本性改变不再基于 Webpack而是使用 Node.js 的 loader 机制在运行时即时转译transpile on the flyTypeScript 与模块代码不再做模块级热重载hot reload而是在代码变更时重启整个后端进程为了不让重启影响开发体验SQLite 数据库状态通过一个父进程得以跨重启保持。这一设计变化带来的好处是启动链路更轻量、与 Node.js 生态更贴近代价则是抛弃了 Webpack 的模块热替换能力。本版本还修复了多个与它相关的细节问题Windows 下的运行支持68158034e8、Windows 下无法优雅关闭后端进程d0f26cfa4f、以及递归监听导致的重复重启425203f898起因是误监听了无关文件。1.3 配套工程化变更backstage/cli0.23.0还包含一批影响日常开发的变更typescript-eslint 升级到 6.7.x8defbd5434更新typescript-eslint/eslint-plugin至6.7.5新增对TypeScript 5.2的兼容React 18 环境标记9468a67b92前端构建与测试中若存在react-dom/client即使用 React 18会定义process.env.HAS_REACT_DOM_CLIENT从而支持对react-dom/client的条件导入yarn new新增node-library模板21cd3b1b24方便快速创建 Node 库包CJS 构建显式设置exports: named3ef18f8c06保证如exports[default] catalogPlugin;这样的具名导出形态scaffolder 模块模板推荐用createMockDirectory替代mock-fsb9ec93430e实验性包发现机制改为始终以包名而非完整模块 id做 include/exclude 过滤指向 subpath 导出的条目改用新增的export字段描述子路径7187f2953e。1.4.icon.svg扩展废弃与迁移示例CLI 对.icon.svg文件扩展的支持已被废弃并计划移除2ef6522552。原因是该扩展的实现与特定版本的 MUI 和 SVGO 绑定过深阻碍了构建系统的演进。官方给出的迁移方式是将.icon.svg文件重命名为.tsx把svg元素替换为 MUI 的SvgIcon并补充必要导入import React from react; import SvgIcon from material-ui/core/SvgIcon; import { IconComponent } from backstage/core-plugin-api; export const CodeSceneIcon (props: SvgIconProps) ( SvgIcon {...props} g path d... / /g /SvgIcon );本版本中已有多个插件如 codescene、graphiql、ilert完成内部重构绕开了该废弃扩展9c9a9100b0。未来 Backstage 可能通过配置方式为内部插件重新引入此类能力但当前阶段必须迁移。二、前端声明式集成系统frontend-app-api/frontend-plugin-api0.2.0v1.19.0 对「下一代前端系统」基于扩展 extension 的声明式集成做了大量 API 收敛这些变化全部是Minor含破坏性级别值得正在体验 alpha 集成能力的开发者重点关注。2.1 扩展挂载点语法重构at→attachTofrontend-plugin-api0.2.0将扩展的挂载点配置从at: id/input改为结构化对象06432f900c// 旧写法 createExtension({ at: app/router, }) // v1.19.0 新写法 createExtension({ attachTo: { id: app/router, input: default }, })同时前端应用会拒绝挂载到不存在 input 的扩展68ffb9e67d并阻止 root 扩展被覆盖以及插件扩展重复注册66d51a4827。2.2createApp选项重塑frontend-app-api0.2.0对createApp的参数进行了系统性调整9d03dfe5e3、d920b8c343、2ecd33618a旧选项新选项说明createApp的config选项configLoader配置加载方式改为函数注入pluginsfeatures支持安装ExtensionOverrides含义更宽泛pluginLoaderfeatureLoader动态加载插件/特性的加载器—新增bindRoutes为应用绑定路由—新增configLoader/featureLoader动态加载能力配套能力还包括主题可配置化新增createThemeExtension与coreExtensionData.theme52366db5b3默认主题改为通过扩展实现开发者可通过扩展覆盖主题扩展覆盖机制createExtensionOverrides用于安装一组会替换现有扩展的扩展集合c1e9ca6500路由系统兼容新增对既有路由系统的支持1718ec75b7同时移除了对新增useRouteRef的支持4461d87d5a并修复子路由无法匹配的问题1e60a9c3a5可观测性为扩展实例实现toString()与toJSON()5072824817便于调试与序列化运行时包过滤对已发现包的过滤条件现在也在运行时生效可通过app.experimental.packages配置在运行时禁用包f78ac58f88隐藏的root扩展移除改为作为core扩展的 input校验逻辑同步迁移d7c5d80c57。2.3 各插件的/alpha实验性集成本轮版本中大量插件开始提供/alpha子路径下的声明式集成入口包括plugin-catalogCatalogSearchResultItemExtension、Catalog API 迁移至声明式集成e5a2956dd2plugin-techdocsTechDocs 声明式集成27740caa2d与TechDocsSearchResultItemExtensionplugin-search兼容声明式集成系统的实验性 search 插件以及createSearchResultListItemalpha 版本plugin-adr/plugin-explore各自的*SearchResultItemExtensionplugin-user-settings、plugin-tech-radar实验性声明式集成支持frontend-plugin-apiSidebar item 扩展新增SidebarGroup支持d3a37f55c0插件创建时可分配routes与externalRoutes2ecd33618a。三、实验性插件配置 API 移除迁移到国际化i18n方案core-plugin-api1.7.0移除了实验性插件配置 API322bbcae24插件选项中的__experimentalReconfigure()插件实例上的__experimentalConfigure()方法plugin-catalog1.14.0同步去掉了对实验性重配置 API 的实现创建按钮标题改由实验性国际化 API 配置通过/alpha导出的catalogTranslationRef实现import { catalogTranslationRef } from backstage/plugin-catalog/alpha; const app createApp({ __experimentalTranslations: { resources: [ createTranslationMessages({ ref: catalogTranslationRef, catalog_page_create_button_title: Create Software, }), ], }, });类似的迁移也出现在 cost-insights 插件中959aa2a09f趋势线隐藏改为通过配置costInsights.hideTrendLine true实现。test-utils同步移除了 alpha 的MockPluginProvider导出322bbcae24。四、TechDocsmkdocs 配置文件名可自定义 自定义 preparer 目录清理4.1serve命令新增--mkdocs-config-file-name此前techdocs-cli serve只能识别名为mkdocs.yaml/mkdocs.yml的配置文件。v1.19.0 为serve命令新增了--mkdocs-config-file-name参数d06b30b050同时作用于techdocs/cli与plugin-techdocs-nodeyarn techdocs-cli serve --mkdocs-config-file-name site-config.yml仓库源码可以完整验证这条链路参数定义位于 packages/techdocs-cli/src/commands/index.ts-c, --mkdocs-config-file-name FILENAMEpackages/techdocs-cli/src/commands/serve/serve.ts 将其透传给getMkdocsYml解析配置路径底层 packages/techdocs-cli/src/lib/mkdocsServer.ts 中的runMkdocsServer会把该值转换为 mkdocs 自身的--config-file参数在 Docker 模式第 58-60 行与本地模式第 79-81 行下都会生效。4.2 自定义 preparer 的shouldCleanPreparedDirectoryplugin-techdocs-backend1.8.0与plugin-techdocs-node1.9.0允许自定义 preparer 控制 prepared 目录的清理344cfbcfbc。使用自定义 preparer 时preparedDir可能长期占用磁盘空间因此所有自定义 preparer 需要实现新的shouldCleanPreparedDirectory方法声明在文档生成后是否应清理该目录。4.3 React 18 支持与体验优化plugin-techdocs1.8.0增加了 React 18 支持若存在react-dom/client将使用新的createRootAPI9468a67b92。同时DocsTable的分页控件改为按需动态显示3605370af6并默认在 TechDocs 表中加入 kind 列df449a7a31。五、Scaffolderpublish:gitlabaction 能力大幅扩展plugin-scaffolder-backend1.18.0对publish:gitlabaction 进行了重要增强dea0aafda7新增三类属性settings透传 GitLab Project Create API 支持的通用项目设置branches创建额外分支并将其设为保护分支protectedprojectVariables设置项目级环境变量。同时原有属性repoVisibility与topics被标记为deprecated其能力已由settings覆盖。此外还有两项可用性改进当 GitLab namespace 找不到时输出有意义的错误信息f41099bb31以及为github:issues:label、publish:azure等 action 补充示例与测试7dd82cc07e、733ddf7130。六、CatalogOpenTelemetry 指标、处理器废弃与 stitching 铺垫plugin-catalog-backend1.14.0的主要变化集中在可观测性与内部架构OpenTelemetry 指标插桩78af9433c8为缺失的关键路径补充指标采集。仓库中的 plugins/catalog-backend/src/database/metrics.ts 展示了具体的实现模式——例如createEntitiesCountByKind同时注册 OpenTelemetry 可观测 Gauge 与旧的 Prometheus Gauge通过单飞缓存single-flight与 TTL默认 30 秒合并并发查询避免每次指标抓取都触发重型数据库查询LocationEntityProcessor标记为废弃7a2e2924c7该处理器早已不在内部使用继续保留甚至可能有害修复 eager delete 触发的关系重拼接问题348e8c1cdb被急切删除的实体未能正确触发与其有关联关系的实体重新拼接re-stitching延迟拼接deferred stitching的内部铺垫b97e9790f0为后续 #18062 的落地做准备。此外catalog-backend-module-github-org0.1.0新增catalogModuleGithubOrgEntityProvider支持从多个GitHub 组织摄取用户与团队c101e683d5plugin-catalog-backend-module-github0.4.4中的catalogModuleGithubOrgEntityProvider被移除需改为从新包导入AwsEksClusterProcessor支持 Entity 回调函数并在初始化 EKS 集群时传入 region5abc2fd4d6。七、Auth 与 Kubernetes模块化推进与新插件7.1 认证模块GCP IAPgcpIapAuthenticator.initialize()不再是async6f142d5356BREAKINGProxyAuthenticator.initialize()同样不再async6f142d5356BREAKING与 OAuth 的等价实现保持一致Microsoft provider迁移到新的独立模块包backstage/plugin-auth-backend-module-microsoft-provider0.1.02d8f7e82c1新增 Pinniped认证模块backstage/plugin-auth-backend-module-pinniped-provider0.1.0ae34255836修复持久化 scope 在登录时无法正确恢复、以及 OAuth refresh handler 响应中 cookie 持久化 scope 缺失的问题6c2b0793bf、8b8b1d23aeGitHub authenticator 修复了 OAuth scope 未正确持久化的问题5d32a58b5aOIDC refresh 时若 token endpoint 响应缺少 scope则回退使用请求的 scope9ff7935152。7.2 Kubernetes新增 Kubernetes cluster 插件95518765ee管理员可以直接在 Backstage 中查看 Kubernetes 集群新增plugin-kubernetes-node0.1.0cbb0e3c3f4承载 Kubernetes 后端插件的扩展点目前包含KubernetesObjectsProviderExtensionPointkubernetes-backend已改用该扩展点认证策略增强5dac12e435当提供Backstage-Kubernetes-Authorization-X-X请求头时Kubernetes API 会调用认证策略从而支持 pinniped 或自定义策略等需要额外步骤获取 k8s token 的场景KubernetesFetcher允许传入undefined的labelSelectorae943c3bb1BREAKING仅影响自定义ObjectProvider实现新增plugin-kubernetes-react、plugin-kubernetes-cluster、plugin-kubernetes-common0.7.0Kubernetes 插件按 ADR 11 进行重构2d8151061c暂无破坏性变化。八、其他值得关注的变化8.1 搜索查询长度限制可配置plugin-search-backend1.4.6为搜索查询设置了默认 100 字符的长度上限16be6f9473可通过配置文件覆盖search: maxTermLength: 1008.2 后端任务指标backend-tasks0.5.11为后台任务新增计数与直方图指标5db102bfdfbackend_tasks.task.runs.count任务运行总次数的 Counterbackend_tasks.task.runs.duration任务运行耗时的 Histogram两者均带result、taskId、scope标签便于细分。同时修复了使用HumanDuration定义的任务在应用启动时被立即触发的问题ddd76ac98d。8.3 配置加载器config-loader1.5.1新增watch选项a4617c422a可设为false禁用文件监听FileConfigSource在读取到空文件时会短暂延迟后重试773ea341d2避免 watch 模式下文件写入未完成时读到空内容的抖动。8.4 create-appE2E 测试切换到 Playwright、Docker 基础镜像更新Cypress → Playwright5eacd5d213create-app 模板的 E2E 测试改为基于 Playwright配套新增backstage/e2e-test-utils0.1.0f5b41b27a9Initial release用于在 monorepo 中自动发现带e2e-tests目录的包E2E 脚本从packages/app/package.json移入根package.json的yarn test:e2e非 CI 环境以开发模式运行若需要可在项目根创建包含playwright.config.ts的.eslintignoreDocker 基础镜像由node:18-bullseye-slim改为node:18-bookworm-slimb665f2ce65、04a3f65e15修复了 bullseye 上的镜像构建错误——需同步修改自有Dockerfile。8.5 前端核心体验修复core-app-api1.11.0的RouteResolver及useRouteRef对常见不安全字符进行URL 编码c9d9bfeca2AppRouter修复了app.baseUrl含basePath时signOutTargetUrl计算错误29e4d8b76b整个应用包裹Suspense支持在插件之外使用翻译acca17e91aTranslationApi修复了部分情况下语言变更未通知订阅者的问题f1b349cfbacore-componentsTabbedLayout点击当前激活 tab 也会触发导航4eab5cf901MissingAnnotationEmptyState可根据当前实体动态生成 YAML 示例d19a827ef1。8.6 Jenkins 与 HomeJenkins 插件前端 后端新增JobRunTable组件、新路由与getBuildJobsAPI可在 Actions 列点击图标进入 Job 运行列表页411896faf9Jenkins 后端新增对新后端系统的支持930ac236d8Home 插件新增 Top / Recently Visited 组件f997f771da。九、升级路线建议综合 v1.19.0 的变更升级时建议按以下优先级处理后端启动方式确认已迁移至新后端系统若仍在旧系统可临时设置LEGACY_BACKEND_START但应尽快迁移因为该标志在后续版本中会被废弃并移除见 packages/cli/CHANGELOG.md.icon.svg文件按上文示例迁移为.tsxSvgIcon实验性插件配置 API替换__experimentalReconfigure()/__experimentalConfigure()的使用改用国际化 API 或普通配置项声明式前端集成若使用 alpha API将at: id/input改为attachTo: { id, input }并按新createApp选项名迁移TechDocs 自定义 preparer实现shouldCleanPreparedDirectory方法Dockerfile将基础镜像更新为node:18-bookworm-slim。通过本文对照仓库源码如 packages/techdocs-cli/src/lib/mkdocsServer.ts、plugins/catalog-backend/src/database/metrics.ts你可以进一步深入验证每个变更的实际实现从而在升级与迁移过程中做到心中有数。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考