Backstage v1.18.0 发布解析新后端系统就绪、Kubernetes 认证策略重构与 TypeScript 5.0 升级指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 开源仓库中的官方发布说明 docs/releases/v1.18.0.md 编写并结合仓库内源码与配置对关键变更进行逐项解读。阅读本文后你将掌握 v1.18.0 中两个 BREAKING 变更Kubernetes 认证策略与 GitLab 组织发现的迁移方法、新后端系统New Backend System的生产可用现状与默认导出约定、backstage-cli fix新命令的用途以及围绕认证后端、国际化、Scaffolder 模板编辑器等 10 余项新特性的落地细节。v1.18.0 是 Backstage 发展历程中的一个重要里程碑官方在发布说明中正式宣布新后端系统已可用于生产环境同时引入了一批面向开发体验的改进——TypeScript 最低版本提升到 5.0、CLI 新增backstage-cli fix命令、认证后端支持通过模块安装 Provider并开启了实验性的 I18n 国际化支持。需要注意的是本次发布包含两个BREAKING破坏性变更Kubernetes 后端认证策略机制重构以及 GitLab 用户/组发现 Provider 必须显式声明扫描范围。下面按主题逐项展开。一、Kubernetes 后端认证策略重构BREAKING1. 变更内容发布说明明确指出集成方现在可以通过KubernetesBuilder上的addAuthStrategy方法注入自定义认证策略auth strategy。与此同时原有的setAuthTranslatorMap方法被移除其职责并入认证策略体系。从当前仓库源码看这一设计在新后端系统中体现为kubernetesAuthStrategyExtensionPoint扩展点plugins/kubernetes-backend/src/plugin.ts 中的AuthStrategy类实现了KubernetesAuthStrategyExtensionPoint接口其addAuthStrategy(key, authStrategy)方法将策略注册进一个Mapstring, AuthenticationStrategy且校验策略名中不允许包含连字符-随后在初始化时将authStrategyMap注入KubernetesRouter。这意味着每种 Kubernetes 集群访问方式如 serviceAccount、googleServiceAccount、awsRole 等对应一个独立的AuthenticationStrategy实现自定义认证方式时不再依赖翻译映射表auth translator map而是直接实现AuthenticationStrategy接口并注册多个策略共存时通过字符串 key 区分key 不能含-。2. 迁移指引若你此前依赖setAuthTranslatorMap定制认证逻辑需要改为实现AuthenticationStrategy接口接口定义位于backstage/plugin-kubernetes-node在初始化KubernetesBuilder时调用addAuthStrategy(key, strategy)注册从配置与代码中移除旧的setAuthTranslatorMap调用。可参考 KubernetesRouter.test.ts 中的测试用例了解策略注入后的调用方式。二、GitLab 用户/组发现必须限定作用范围BREAKING1. 变更内容如果你使用GitlabOrgDiscoveryEntityProvider从 GitLab 摄取用户User和组Group现在必须将扫描范围限定到某个具体组。不配置该值时后端将无法启动。发布说明给出的配置示例新增group字段catalog: providers: gitlab: yourProviderId: host: gitlab.com orgEnabled: true group: org/teams2. 源码层面的强制校验这一限制在源码中实现了硬校验GitlabOrgDiscoveryEntityProvider.ts 的fromConfig方法中有如下逻辑if (!providerConfig.group providerConfig.host gitlab.com) { throw new Error( Missing group value for GitlabOrgDiscoveryEntityProvider:${providerConfig.id}., ); }从该实现可以推断该强制校验目前针对host gitlab.comGitLab SaaS场景对于自托管self-managed实例未配置group时仍会走全量扫描分支调用listGroups/listUsersrefresh方法中根据isSelfManaged()与restrictUsersToGroup的组合分别决定扫描路径自托管 限定组时通过listDescendantGroups枚举子组并拉取组成员SaaS 场景则以group为根组枚举其子孙组shouldProcessGroup进一步用groupPattern与group前缀过滤保证只处理目标组范围内的实体Provider 还支持通过 events 订阅gitlab.group_create、gitlab.user_add_to_group等系统钩子事件做增量同步delta mutation。对自托管实例若希望继续全量发现用户/组可以不配置group但需要明确orgEnabled: true且无restrictUsersToGroup。若使用的是 GitLab.com则必须像上面那样显式提供group值。三、TypeScript 5.0 成为最低版本v1.18.0 起Backstage 的最低 TypeScript 版本提升至 v5.0。升级自己项目时需同步调整package.json中的 TypeScript 依赖{ devDependencies: { typescript: ^5.0.0 } }同时建议检查tsconfig.json中与 TS 5.0 相关的编译器选项如moduleResolution、verbatimModuleSyntax等是否符合新版本约束。由于仓库其余包均按此基线开发本地项目若低于 5.0 可能出现类型检查或构建失败。四、新后端系统New Backend System正式就绪1. 官方结论可以用于生产发布说明首次明确表态新后端系统已可用于生产环境使用。尽管仍有个别插件待迁移、细节待打磨但官方鼓励用户开始使用并提供了两条配套路径后端迁移指南docs/backend-system/building-backends/migrating按章节逐步迁移旧式后端legacyPlugin辅助函数用于在迁移过渡期安装那些尚未适配新系统的旧插件。在仓库中可找到大量基于createBackendPlugin/createBackendModule构建的新系统插件示例例如 kubernetesPlugin 与 authPluginlegacyPlugin相关类型定义于backstage/backend-plugin-api包中。2. 实验性的package start命令本地开发方面发布说明推荐尝试新的package start后端启动命令通过设置环境变量启用EXPERIMENTAL_BACKEND_START1 yarn start该模式相比传统方式有以下特点不再使用 Webpack改为基于模块加载器的 watch 模式启动更轻量仍能在重启间保留 SQLite 数据库状态且没有文件系统开销若进展顺利官方计划在下一个版本将其设为默认启动方式。五、新后端系统包默认导出约定1. 约定内容已迁移到新后端系统的插件与模块现在要求将自身实现作为包的默认导出default export。这一约定带来三个收益明确每个包的主入口便于自动发现特性feature discovery允许在代码中轻松写出动态导入dynamic import一行式。2. 迁移示例若你此前采用如下静态导入import { examplePlugin } from backstage/plugin-example-backend; backend.add(examplePlugin);升级后可能需要改为backend.add(import(backstage/plugin-example-backend));仓库中的实际范例可参考 catalog-backend-module-scaffolder-entity-model 的 index.ts它以export { catalogModuleScaffolderEntityModel as default } from ./module;形式提供默认导出其模块定义 module.ts 通过createBackendModule注册到 catalog 的catalogProcessingExtensionPoint。升级时请检查后端包中所有backstage/*插件/模块的导入语句逐一改为动态导入或新的默认导出引用。3. 自动特性发现默认导出约定同时支撑了特性自动发现机制packages/backend-defaults中的 discoveryFeatureLoader.ts 借助PackageDiscoveryService扫描当前package.json及其依赖从各包默认导出中自动收集后端特性并注册到实例从而省去手动backend.add(...)。六、yarn fix与sideEffects: falseCLI 新增了backstage-cli fix命令通常配置为yarn fix运行。它会扫描项目内所有包确保声明正确目前承担两项职责校验包导出package exports声明取代了旧的backstage-cli migrate package-exports命令确保前端包设置sideEffects: false该修复已应用到所有backstage/*包使前端构建可以获得更激进的 tree-shaking 优化产出更小的 bundle。项目根目录的 package.json 中即包含各包的 scripts 声明可将fix纳入日常开发流程yarn fix七、Auth 后端重大改进1. 新后端系统支持与 Provider 模块化backstage/plugin-auth-backend现已支持新后端系统并允许通过模块安装认证 Provider。作为配套重构构建自定义 Provider 所需的全部 API 从backstage/plugin-auth-node导出对有限数量的 Provider现在可以通过静态配置指定固定的 sign-in resolver登录身份解析器。从 authPlugin.ts 可见其新系统实现骨架插件注册authProvidersExtensionPoint扩展点各 Provider 模块通过registerProvider({ providerId, factory })注入工厂初始化时将所有 Provider 工厂合并后交给createRouter见 router.ts构建 HTTP 路由同时注册authOwnershipResolutionExtensionPoint支持自定义所有权解析。示例 Provider 模块可参考仓库中大量auth-backend-module-*包如plugins/auth-backend-module-github-provider、plugins/auth-backend-module-google-provider等。2. 会话过期判断改进所有认证 Provider 的会话过期检查得到增强现在同时考虑 Backstage 身份令牌identity token与 Provider 专属令牌如 OAuth access token / refresh token的过期时间二者任一过期都会触发会话失效判定避免出现身份令牌有效但第三方令牌已过期导致的静默失败。八、实验性 I18n 国际化支持前端系统新增一组实验性国际化 API支持将界面文案翻译为其他语言覆盖override默认消息。目前部分支持已落地到backstage/plugin-user-settings与backstage/plugin-adr两个插件详细用法见docs/plugins/internationalization文档。由于仍处于实验阶段接口可能随版本演进变化不建议在生产大规模依赖。九、前端声明式集成的实验性包为推进前端声明式集成frontend declarative integration目标本次新增两个包backstage/frontend-plugin-apibackstage/frontend-app-api发布说明强调这两个包仍高度实验性不应在正式项目中使用。它们承载未来前端插件系统的核心抽象当前仅供早期探索与贡献者试用。十、Scaffolder 模板编辑器支持下载 Dry-Run 结果模板编辑器template editor的 dry-run 结果视图中现在可以将 dry-run 生成的结果打包为 zip 存档下载。这意味着你在编辑模板参数、预览渲染结果后可以直接把生成的骨架归档保存或分发给他人便于本地验证模板逻辑。十一、Azure DevOps 多组织支持Azure DevOps 集成现在允许为不同组织配置独立的凭据。此前单一凭据配置只能覆盖一个组织升级后可在集成配置中按组织拆分例如integrations: azure: - host: dev.azure.com credentials: - organizations: - orgA clientId: ... clientSecret: ... - organizations: - orgB clientId: ... clientSecret: ...具体字段说明见docs/integrations/azure/locations/文档。这对于在多个 Azure DevOps 组织间维护不同服务主体service principal的团队尤其有用。十二、新包backstage/plugin-catalog-backend-module-scaffolder-entity-modelScaffolder 对 Catalog 的集成逻辑有了专门的新家。以下两项能力从 Scaffolder 后端插件包中迁移并弃用ScaffolderEntitiesProcessor处理 Scaffolder 特定实体模型如 Template 类型的 catalog 处理器对应的新后端系统模块catalogModuleScaffolderEntityModel。新的导入路径为// 处理器 import { ScaffolderEntitiesProcessor } from backstage/plugin-catalog-backend-module-scaffolder-entity-model; // 新后端系统模块默认导出 import catalogModuleScaffolderEntityModel from backstage/plugin-catalog-backend-module-scaffolder-entity-model;在仓库中该包的处理器实现位于 ScaffolderEntitiesProcessor.ts配套测试见 ScaffolderEntitiesProcessor.test.ts 与 module.test.ts。升级时请将原先从backstage/plugin-scaffolder-backend导入上述符号的代码改到新包。十三、进一步的 MySQL 兼容性工作本版本由 VMware 社区贡献者在核心与各插件中持续推进 MySQL 兼容性改进对应 PR #18921。具体包括数据库连接、查询语法、迁移脚本等层面的兼容性调整。如果你的 Backstage 以 MySQL 为后端存储升级后建议重点回归验证 Catalog、Auth、Scaffolder 等核心模块的数据库读写路径。十四、安全修复与升级建议安全修复v1.18.0不包含任何安全修复升级路径官方建议将项目持续更新到最新版本完整升级指南见docs/getting-started/keeping-backstage-updated。核心升级动作可归纳为① 将 TypeScript 升级到 v5.0② 依据上文处理两个 BREAKING 变更Kubernetes 认证策略、GitLabgroup必填③ 将已迁移插件的导入改为默认导出/动态导入④ 运行yarn fix修正包声明与sideEffects⑤ 可选以EXPERIMENTAL_BACKEND_START1体验新的后端启动模式。参考链接仓库内发布说明原文docs/releases/v1.18.0.mdKubernetes 新后端插件与认证策略扩展点plugins/kubernetes-backend/src/plugin.ts、KubernetesRouter.test.tsGitLab 组织发现 ProviderGitlabOrgDiscoveryEntityProvider.ts 及测试 GitlabOrgDiscoveryEntityProvider.test.tsAuth 新后端插件authPlugin.ts、router.tsScaffolder 实体模型新包index.ts、module.ts、ScaffolderEntitiesProcessor.ts特性自动发现加载器discoveryFeatureLoader.ts新后端系统架构文档docs/backend-system/architecture、docs/backend-system/building-backends【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考