Backstage v1.18.0 版本全解析新后端系统默认导出迁移、可声明式 Sign-in Resolver 与前端系统初亮相【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstagev1.18.0 是 Backstage 演进过程中承前启后的一个版本它既完成了新后端系统New Backend System插件默认导出的全面迁移又在认证模块中引入了可配置的 Sign-in Resolver 体系同时以frontend-app-api/frontend-plugin-api两个0.1.0包首次亮出了实验性的新前端系统。本文以 docs/releases/v1.18.0-changelog.md 为主线结合仓库源码深入拆解这些变更的配置写法、迁移步骤与底层实现帮助你判断升级路径并快速落地到自己的开发门户中。总览v1.18.0 的关键变更地图v1.18.0 涉及数十个包的版本更新核心主题可以归纳为四条主线新后端系统全面推进大量后端插件的导出从命名导出改为default导出配合backend.add(import(...))的新式加载方式同时backend-app-api增强了特性发现feature discovery能力并在启动时检测循环服务依赖。认证体系重构backstage/plugin-auth-node0.3.0引入 authenticator 模式createOAuthAuthenticator/createProxyAuthenticator并支持通过auth.providers.id.signIn.resolvers配置声明式 Sign-in Resolver。实验性新前端系统初亮相frontend-app-api与frontend-plugin-api首次发布0.1.0配合实验性 i18n 国际化支持。平台能力增强配置深度可见性deep visibility扩展、catalog.processingInterval可配置化、Azure DevOps 多组织凭据、backstage.io/techdocs-entity注解、MySQL 数据库支持铺开等。一、配置层readDurationFromConfig与深度可见性扩展1.1 新增readDurationFromConfig工具函数backstage/config1.1.0新增了readDurationFromConfig函数变更号62f448edb0b5用于从配置对象中读取时长duration类型的值。其实现位于 packages/config/src/readDurationFromConfig.ts。该函数支持三种输入格式ms风格字符串如1d、2 seconds由ms库解析ISO 8601 时长字符串如P2DT6H、PT1M以P开头时自动走 ISO 解析分支对象形式以复数单位为键如{ days: 2, hours: 6 }允许的单位包括years、months、weeks、days、hours、minutes、seconds、milliseconds见源码第 22-31 行的propsOfHumanDuration常量。函数签名支持可选的key参数用于从配置对象的子键读取import { readDurationFromConfig } from backstage/config; // 从 config 的 catalog.processingInterval 键读取 const interval readDurationFromConfig(config, { key: catalog.processingInterval });从源码实现看该函数不内置可选性若目标键不存在需要在调用前先用config.has(...)判断源码注释中明确说明。当解析失败时会抛出带明确路径与错误原因的InputError例如Invalid duration xxx in config at catalog.processingInterval。该工具在 v1.18.0 中被backend-tasks用于调度任务间隔与catalog-backend处理间隔采纳替代了原先分散在各处的时长解析逻辑。1.2 Deep Visibility 扩展到未覆盖 schema 的值backstage/config-loader1.5.0的一个重要行为变更9606ba0939e6深度可见性deep visibility现在也作用于没有被配置 schema 覆盖的值。此前只有在配置 schema 中显式声明了/** deepVisibility frontend */的键其可见性才会沿配置树向下传递且只覆盖 schema 中已声明的路径。现在只要某个父节点声明了 deep visibility其下的所有值无论是否在 schema 中定义都会继承该可见性。例如// plugins/a/config.schema.ts export interface Config { /** deepVisibility frontend */ a?: unknown; } // plugins/a/config.schema.ts export interface Config { a?: { b?: string; }; }变更后a下的所有值对前端可见而此前只有a和a/b两个精确路径可见。这意味着插件作者可以放心地把deepVisibility frontend标注在配置树的根节点上而无需为每一个子字段逐一声明。从源码看该继承逻辑位于 packages/config-loader/src/schema/compile.ts第 167-170 行如果自身没有定义 deepVisibility则继承父级的 deepVisibility同时第 87-91 行注释指出设计上禁止将deepVisibility设为backend以防止权限逃逸——可见性的合法传递方向是secret - backend - frontend。同文件collect.ts第 356 行也把deepVisibility列为合法 schema 标签之一。另外config-loader1.5.0还修复了配置无操作更新时仍通知订阅者的问题f9657b891b00减少前端无谓的重渲染。二、认证体系Authenticator 模式与声明式 Sign-in Resolverv1.18.0 在认证方面投入最大backstage/plugin-auth-node0.3.0与backstage/plugin-auth-backend0.19.0构成了新的认证插件开发范式。2.1 Authenticator 模式将认证集成与登录逻辑解耦变更8513cd7d00e3引入了一套新的认证提供方auth provider构建体系核心思想是创建 authenticator认证器再基于它组合出 provider。初始提供两种类型createOAuthAuthenticatorcreateOAuthRouteHandlerscreateOAuthProviderFactoryOAuth 流程createProxyAuthenticatorcreateProxyAuthRouteHandlerscreateProxyAuthProviderFactory代理认证流程。这套模式的关键收益是登录逻辑sign-in logic与认证集成逻辑分离同一类型的 provider 可以完全复用同一套登录解析逻辑同时天然适配新后端系统。此外原先backstage/plugin-auth-backend内部基于 passport 策略实现 provider 的辅助函数也以公开 APIPassportHelpers与PassportOAuthAuthenticatorHelper的形式开放。2.2 声明式 Sign-in Resolver从写代码到写配置新引入的 provider factory 支持通过配置键resolvers声明式地配置 Sign-in Resolver按顺序取第一个成功解析出身份的 resolverauth: providers: google: development: clientId: ${AUTH_GOOGLE_CLIENT_ID} clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET} signIn: resolvers: - resolver: emailMatchingUserEntityAnnotation - resolver: emailLocalPartMatchingUserEntityName这些可配置 resolver 由createSignInResolverFactory工厂函数创建其实现位于 plugins/auth-node/src/sign-in/createSignInResolverFactory.ts。从源码看该工厂接受一个可选的optionsSchema基于 zod 定义这个 schema同时用于配置驱动与代码驱动的参数校验若未提供optionsSchema工厂不接受任何选项传入选项会抛出InputError若提供则调用时先经optionsSchema.parse(...)校验失败时抛出带详细校验错误的InputError。这意味着插件作者定义的每个 resolver 既可以像上面那样在 YAML 中按名字引用也可以带上自己的参数例如- resolver: myResolver\n options: {...}前后端配置体验一致。2.3 新增的 Provider 模块与内置 Provider 管理v1.18.0 将认证 provider 拆分为独立模块均为0.1.0新包新模块提供的 Providerbackstage/plugin-auth-backend-module-github-providerGitHub23af27f5ce79backstage/plugin-auth-backend-module-gitlab-providerGitLab080cc7794700backstage/plugin-auth-backend-module-google-providerGoogle8513cd7d00e3backstage/plugin-auth-backend-module-gcp-iap-providerGCP IAP8513cd7d00e3backstage/plugin-auth-backend-module-oauth2-providerOAuth2101cf1d13b04backstage/plugin-auth-backend0.19.0相应地新增了authPlugin导出面向新后端系统该插件不再内置任何 auth provider必须通过安装上述模块来添加例如从backstage/plugin-auth-backend-module-google-provider引入authModuleGoogleProvider。同时新增createRouter的disableDefaultProviderFactories选项可禁用内置的 provider 工厂GitLab provider 也已迁移到独立模块实现。另一个值得注意的配置项是auth.identityTokenAlgorithm生成 Backstage token 时使用的签名算法现在可以通过该配置自定义。2.4 OAuth 会话过期处理与身份响应字段backstage/core-app-api1.10.0修复了两个与 OAuth 会话建模相关的 bug18619f793c94OAuth2Session类型中expiresAt与backstageIdentity现在是可选字段因为实际场景中它们确实可能缺失所有 OAuth provider 共用的OAuth类现在会同时考量 Backstage 身份与上游身份提供方两者的会话过期时间任一即将过期即触发刷新。配套地BackstageIdentityResponse新增可选的expiresAt字段core-plugin-api1.6.0auth-node的BackstageIdentityResponse则新增可选expiresInSeconds字段prepareBackstageIdentityResponse工具函数会从 token 中读取过期时间并写入响应。这套字段的补齐正是前文双会话刷新策略的底层支撑。三、新后端系统默认导出迁移与加载方式升级3.1 统一的默认导出迁移Breaking Changev1.18.0 中以下后端插件/模块的新后端系统导出统一迁移为default导出变更71114ac50e02涉及 adr、airbrake、auth-backend、azure-devops、badges、bazaar、catalog-backend、devtools、entity-feedback、events-backend、kafka、kubernetes、lighthouse、linguist、periskop、permission-backend、proxy、scaffolder-backend、search-backend、todo、user-settings 等// 迁移前命名导出 import { examplePlugin } from backstage/plugin-example-backend; backend.add(examplePlugin); // 迁移后默认导出 动态 import backend.add(import(backstage/plugin-example-backend));配合backstage/backend-app-api0.5.3的新能力3b30b179cb38backend.add(import(my-plugin))的包导入安装方式正式可用。这也意味着升级到 v1.18.0 时所有使用新后端系统加载插件的地方都应改为默认导出形式。3.2 Feature Discovery 与依赖检查强化backend-app-api0.5.3在一系列 patch 中完善了新后端系统的运行时行为特性发现增强154632d8753b/37a20c7f14aa启动时可发现额外的 service factory且支持对后端包特性发现做 include / exclude 配置alpha 模块也纳入发现范围默认导出限定cb7fc410ed99实验性的特性发现只考虑包的 default 导出package.json中仍需backstage字段扩展点按 ID 跟踪3fc64b9e2f8f扩展点extension points改为通过 ID 而非引用跟踪以支持包重复的场景循环依赖检测b219d097b3f4后端启动时若检测到循环服务依赖会直接失败避免运行期出现难以排查的初始化死循环。backend-plugin-api0.6.3还从类型层面保证了 root 作用域服务不能依赖插件作用域服务ba4506076e2d并把 service factory 标记为可安装的 feature factory474b792d6a43。3.3 后端测试工具同步升级backend-test-utils0.2.3引入了ServiceFactoryTester58cb5e5cea7b专门用于测试 service factory 的新工具模块导入安装支持202e52c5e361startTestBackend({ features: [import(my-plugin)] })mockService扩展9fb3b5373c45为生命周期等服务提供 mock 变体如mockServices.lifecycle.mock()返回的 mock 实现自带factory属性可传入部分实现覆盖特定方法。四、前端新前端系统与实验性 i18n4.1frontend-app-api与frontend-plugin-api首次发布backstage/frontend-app-api0.1.0与backstage/frontend-plugin-api0.1.0均为首次发布628ca7e458e4。其中frontend-plugin-api依赖core-plugin-api1.6.0frontend-app-api则依赖 GraphiQL 插件、core-components0.13.5等。仓库中的example-app-next与app-next-example-plugin两个示例应用已接入这两个包可视为新前端系统的实验样板。graphiql插件也同步提供了/alpha下的实验性导出cf950c3b6eab并支持使用 FetchApib2fbeed5403b。4.2 实验性国际化i18n支持core-app-api、core-plugin-api、plugin-user-settings、plugin-adr等多个包引入了实验性国际化支持6e30769cc627。同时test-utils1.4.3新增/alpha导出MockTranslationApi用于在测试中模拟翻译 APIb5fbddc15dca并支持 React Testing Library 13 / React 18通过render*方法暴露legacyRoot选项见9ceb6195275a。如果你计划在自己的插件中接入多语言v1.18.0 提供了最早的基础设施雏形。五、Catalog处理间隔可配置与 GitLab 组限定5.1catalog.processingInterval配置项backstage/plugin-catalog-backend1.13.0允许在 app-config 中配置实体处理间隔62f448edb0b5实现位于 plugins/catalog-backend/src/service/CatalogBuilder.tscatalog: processingInterval: { minutes: 3 } # 也支持 3m 或 PT3M 等 readDurationFromConfig 支持的格式从源码第 776-794 行可以看到实际解析逻辑读取键catalog.processingInterval若未配置则使用默认值若显式配置为false则禁用处理否则调用readDurationFromConfig解析为时长对象这正是第一节新工具函数的第一个落地场景。5.2 其它 Catalog 相关变更backstage.io/techdocs-entity注解e44f45ac4515同时作用于plugin-catalog与plugin-techdocs允许一个实体引用另一个实体的 TechDocs例如backstage.io/techdocs-entity: system:default/example。典型场景是同一仓库中的前端与后端共享一份文档把 TechDocs 构建在System实体下再让成员实体通过注解引用从而避免重复构建、避免 TechDocs 页面堆满重复内容。该注解同时影响 TechDocs 按钮与 TechDocs 选项卡。GitLab.com 组限定3d73bafd85c9BreakingGitlabOrgDiscoveryEntityProvider现在要求必须配置group参数否则后端启动失败catalog: providers: gitlab: yourProviderId: host: gitlab.com orgEnabled: true group: org/teamsScaffolder 实体模型独立成模块d5313ede3529ScaffolderEntitiesProcessor被标记弃用应改从新的backstage/plugin-catalog-backend-module-scaffolder-entity-model导入alpha 导出catalogModuleTemplateKind也迁移至该包并更名为catalogModuleScaffolderEntityModel。处理循环改为迭代实现1fd2109739c1catalog 处理循环的任务流水线从递归改为迭代降低深层实体图的栈溢出风险另外修复了实体查询limit参数、order参数识别、fullTextFilterFields校验等 OpenAPI/查询问题。六、集成层Azure DevOps 多组织凭据与 Kubernetes 认证策略6.1 Azure DevOpscredentials取代单凭据配置backstage/integration1.7.0新增AzureDevOpsCredentialsProvider5f1a92b9f19f支持为不同的 Azure DevOpsServer组织配置各自的凭据同时弃用AzureIntegrationConfig.credential与AzureIntegrationConfig.token改为credentialsintegrations: azure: - host: dev.azure.com credentials: - organizations: - my-org - my-other-org clientId: ${AZURE_CLIENT_ID} clientSecret: ${AZURE_CLIENT_SECRET} tenantId: ${AZURE_TENANT_ID} - organizations: - yet-another-org personalAccessToken: ${PERSONAL_ACCESS_TOKEN}plugin-scaffolder-backend、backend-common、catalog-backend-module-azure均切换到DefaultAzureDevOpsCredentialsProvider获取凭据。另外catalog-backend-module-azure在提交新 location 到 catalog 前会先去重 Azure 搜索结果044b4f2fb1e3并提升AzureDevOpsEntityProvider结果一致性94f96508491d。6.2 KubernetesAuthenticationStrategy取代AuthTranslatorbackstage/plugin-kubernetes-backend0.12.00ad36158d980让集成者可以通过KubernetesBuilder的addAuthStrategy方法带入自定义认证策略。BreakingsetAuthTranslatorMap方法与整个KubernetesAuthTranslator接口被移除替换为更聚焦的AuthenticationStrategy概念。前端plugin-kubernetes与plugin-kubernetes-common同步放宽了retrieveObjectsByServiceId请求体auth字段的类型允许任意 JSON 对象便于集成者编写自定义认证策略。此外还修复了caFile配置下代理端点请求失败的问题024b2b66a332、为集群资源补充 AWS 注解ccf00accb408以及修复自定义资源 kind 显示为undefined的问题47ea122590f5。七、Scaffolder、Search 与 TechDocs 的实用增强7.1 ScaffolderDry Run 结果页支持 .zip 下载0119c326394a模板预演dry run结果现在可以打包下载方便在本地检查生成内容。parseEntityRef过滤器增强b5f239b50bcf现在接受两个参数可提供默认的 kind 与 namespace 值与catalog-model中parseEntityRef的行为对齐。Action 示例补齐a4989552d828/ded27b83ead2/f3c0b95e3ef1为publish:github、publish:gitlab、publish:bitbucket、github:actions:dispatch等 action 增加了示例定义便于模板作者参照。run:yeoman支持 dry-run4fa1c74cbadcscaffolder-backend-module-yeoman。RJSF 升级b16c341ced45scaffolder 前端及 home 插件将rjsf/*依赖统一升级到 5.13.0。7.2 Search默认查询参数可配置plugin-search与plugin-search-react1.7.0支持通过 app-config 为 SearchPage 配置首次加载/重置时的默认查询参数b78f570f44d3search: query: pageLimit: 50pageLimit的合法取值为10、25、50、100。plugin-search-react还优化了只在配置存在时才用默认设置初始化搜索上下文45f8a95e1068。此外search-backend-module-pg新增indexerBatchSize选项控制批量索引的大小并增加调试日志输出批次内实体列表4ccf9204bc95。7.3 TechDocsAzurite 支持5985d458ee30作用于plugin-techdocs-backend与plugin-techdocs-node新增techdocs.publisher.azureBlobStorage.connectionString配置项便于本地使用 Azurite 模拟 Azure Blob 存储Publisher 类型扩展60af8017dd84techdocs.publisher.type补充googleGcs、awsS3、azureBlobStorage、openStackSwift等取值默认 mkdocs 插件10a86bd4ae12同时作用于techdocs/cli1.5.0TechDocs CLI 与后端支持通过可选配置/CLI 选项指定默认的 mkdocs 插件Lightbox 缩放图标86c19906fe4bplugin-techdocs-module-addons-contrib文档内图片在 lightbox 中可缩放查看。八、CLI 与工程化repo fix与sideEffects优化backstage/cli0.22.13带来多项工程化改进repo fix命令3494c502aba7自动修复所有包中可自动修复的问题初始能力包括修复包的导出声明以及把所有非打包前端包标记为side-effect free。标记sideEffects: false可以显著减小 Webpack 打包体积——这也是 v1.18.0 中大量前端包出现406b786a2a2cMark package as being free of side effects变更的原因。create-app0.5.5同步在根package.json中新增fix: backstage-cli repo fix脚本test: backstage-cli repo test, test:all: backstage-cli repo test --coverage, fix: backstage-cli repo fix, lint: backstage-cli repo lint --since origin/master,--inspect监听地址可配置04eabd21bee4例如--inspect0.0.0.0:9229方便在容器/远程环境下调试实验性后端启动命令的 ESM loader4d5eeec52d80与前端包发现支持f36113ca2305new命令支持创建纯后端模块278d9326eb40后端插件/模块支持dev/index入口71d4368ae5cc移除了实验性的package fix命令cd7331587eb3其能力由backstage/eslint-plugin的no-undeclared-imports规则替代。create-app0.5.5还默认切到 TypeScript 5.2a4c08241ad92并修复了后端模板为使用任务调度器的插件重复创建连接池的问题——若你的后端packages/backend/src/index.ts仍在使用旧写法需按下述方式更新// in packages/backend/src/index.ts - const taskScheduler TaskScheduler.fromConfig(config); const taskScheduler TaskScheduler.fromConfig(config, { databaseManager });九、其它值得关注的变化MySQL 支持铺开cfc3ca6ce060bazaar、catalog-backend、scaffolder-backend、tech-insights-backend、code-coverage-backend、app-backend、linguist-backend 等多个后端包完成 MySQL 适配为多数据库部署铺路自动登出组件AutoLogout9b74166d11a1core-components0.13.5提供基于用户非活跃时间的可选自动登出机制详见 docs/auth/autologout.mdPermissionspermissionModuleAllowAllPolicy从permission-backend移入新的backstage/plugin-permission-backend-module-allow-all-policy0.1.084ad6fccd4d5/5f7b2153526bDevTools 资源利用率展示12e644aa4eefDevTools 插件及后端开始展示资源利用情况Vault secrets engine 覆盖858a18800870可在 catalog 实体级别通过注解vault.io/secrets-engine覆盖 Vault secret engineTable 加载指示器47782f4bfa5bcore-components的 Table 组件新增 loading 状态StructuredMetadataTablenull 值修复0c9907645aab元数据含null时不再崩溃后端代理配置错误提示02ba0a2efd2a代理路由未正确配置时的报错会带上路由名便于定位version:bump重复项处理4af4defcc114重复包名改为记录日志而非抛错。十、升级建议与注意事项综合 v1.18.0 的变更升级时建议按以下顺序排查后端插件导出迁移所有新后端系统用法改为backend.add(import(backstage/plugin-xxx))默认导出形式这是本版本最普遍、最需要动手的 Breaking Change。认证配置若使用auth-backend的内置 provider评估是否迁移到disableDefaultProviderFactories 独立 provider 模块的组合将signIn逻辑迁移到声明式resolvers配置以获得可配置、可复用的登录解析能力。GitLab 目录集成使用GitlabOrgDiscoveryEntityProvidergitlab.com必须补上group配置否则后端无法启动。Azure DevOpstoken/credential已弃用切换为credentials多组织配置。Kubernetes若自定义过认证翻译器需按AuthenticationStrategy重写。数据库接入 MySQL 的插件增多多数据库部署的兼容面扩大。构建优化运行yarn fixbackstage-cli repo fix让所有前端包获得sideEffects: false标记以获得更优的 Webpack 打包结果。新前端系统frontend-plugin-api/frontend-app-api与 i18n 基础设施在此版本仍属实验阶段生产环境接入前建议关注后续版本的稳定性承诺与迁移文档。参考路径速查变更原文docs/releases/v1.18.0-changelog.mdreadDurationFromConfig实现packages/config/src/readDurationFromConfig.ts配置 schema 深度可见性继承packages/config-loader/src/schema/compile.tsSign-in Resolver 工厂plugins/auth-node/src/sign-in/createSignInResolverFactory.ts公共 Sign-in Resolverplugins/auth-node/src/sign-in/commonSignInResolvers.tsCatalog 处理间隔解析plugins/catalog-backend/src/service/CatalogBuilder.ts认证相关文档docs/auth/index.md 与 docs/auth/add-auth-provider.md【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考