Backstage v1.28.0 升级指南代理认证强化、OAuth 作用域重构与 New Backend System 1.0 迁移准备【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage v1.28.0 是迈向 New Backend System 1.0 稳定版的关键版本集中体现了核心后端服务向backstage/backend-defaults的大迁移、代理插件默认启用 Backstage 认证、OAuth Provider 作用域管理重构以及外部路由默认绑定与静态配置化路由绑定等一系列能力。本文以仓库内的 docs/releases/v1.28.0-changelog.md 为主体结合 packages/ 与 plugins/ 下的源码实现系统梳理本版本的所有破坏性变更、弃用项与新特性并给出可落地的升级与配置方案帮助你在升级到 v1.28.0 时避免踩坑、平稳过渡。一、版本概览一次面向 New Backend System 1.0 的大搬家v1.28.0 最核心的工程主线是把核心后端服务的实现从backstage/backend-app-api与backstage/backend-common迁往backstage/backend-defaults并系统性地弃用旧后端系统legacy backend system的各类工具为 New Backend System 1.0 的稳定发布 扫清障碍。与之同步的还有几项必须留意的破坏性变更特别是代理后端proxy-backend默认要求认证这一安全强化。本版本涉及的关键包版本变化如下包版本级别核心变化backstage/backend-common0.23.0Minor核心服务迁出并弃用、TokenManager弃用、createServiceBuilder弃用backstage/backend-defaults0.3.0Minor承接核心服务工厂与实现新增 subpath 导出backstage/backend-test-utils0.4.0Minor新增TestCaches、mockCredentials.service支持访问限制backstage/integration1.12.0MinorGerritgitilesBaseUrl必填、GitHub 旧命名 API 移除、HarnessreadTreebackstage/plugin-proxy-backend0.5.0Minor默认要求 Backstage 认证破坏性backstage/plugin-auth-node0.4.14PatchOAuth 作用域管理重构scopes.persist/required/transformbackstage/plugin-catalog1.21.0Minor外部路由默认绑定、Scaffolder 新权限支持backstage/plugin-scaffolder1.21.0MinorSecretField取代ui:widget: passwordbackstage/plugin-search-backend-module-elasticsearch1.5.0Minor索引器删除陈旧索引破坏性backstage/plugin-kubernetes-backend/-common/-react0.18.0 / 0.8.0 / 0.4.0Minor切换至 autoscaling/v2 APIbackstage/plugin-notifications-backend0.3.0Minor支持按 processor 过滤通知二、核心服务迁移到backstage/backend-defaults改导入、别再用旧地址这是 v1.28.0 最重要的一次结构调整。变更日志明确backstage/backend-app-api中的核心服务工厂与实现已标记为弃用并迁往backstage/backend-defaults的 subpath 导出例如backstage/backend-defaults/scheduler——coreServices.scheduler的服务工厂与默认实现backstage/backend-defaults/auth、backstage/backend-defaults/httpAuth、backstage/backend-defaults/userInfo—— 对应的三大认证服务工厂原在backstage/backend-app-api中的authServiceFactory、httpAuthServiceFactory、userInfoServiceFactory已弃用backstage/backend-defaults/urlReader—— 原backstage/backend-common中的全部 URL reader 功能UrlReader、FetchUrlReader等迁移至此。同时backstage/backend-common0.23.0中以下内容被正式弃用最终弃用TokenManager请改用coreServices.auth、coreServices.httpAuth、coreServices.userInfo并参照 认证服务迁移指南isDatabaseConflictError已迁往backstage/backend-plugin-apiContainerRunner、DockerContainerRunner、KubernetesContainerRunner旧版createServiceBuilder工厂、ServiceBuilder类型、notFoundHandler、redactWintonLogLine、dropDatabase、getVoidLogger以及旧版错误/请求日志处理器类型ErrorHandlerOptions、RequestLoggingHandlerFactorybackend-tasks0.5.24的所有导出均被标记弃用统一指向backstage/backend-plugin-api与backstage/backend-defaults。迁移要点请逐一替换上述导入路径如果仍然在旧地址导入这些服务会持续收到弃用告警且这些地址会在后续版本移除。仓库中的 example-backend 与 example-backend-legacy如存在已在本版本同步更新依赖可作为迁移参照。三、破坏性变更一代理后端默认要求 Backstage 认证backstage/plugin-proxy-backend0.5.0带来了一项重要的安全默认值变更除非显式配置否则所有代理端点都会立即拒绝缺少有效 Backstage 用户或服务令牌的请求。这与 Backstage 其他后端开箱即用的行为保持一致目的是保护上游服务免受未授权访问。代理端点配置现在形如proxy: endpoints: /pagerduty: target: https://api.pagerduty.com credentials: require # NEW! headers: Authorization: Token token${PAGERDUTY_TOKEN}credentials有三个可选值值行为require调用方每次请求必须携带 Backstage 用户或服务凭据凭据不会转发给代理目标。这是新的默认值forward调用方必须携带凭据且这些凭据会转发给代理目标dangerously-allow-unauthenticated不要求 Backstage 凭据旧默认值。目标自身仍可做校验但代理不再拦截未授权调用方若同时配置allowedHeaders: [Authorization]则提供的 Backstage 令牌会被转发仓库中的实现plugins/proxy-backend/src/service/router.ts确认了这一逻辑默认credentialsPolicy require且仅接受上述三个候选值遇到其他值会抛出Unknown credentials policy ...错误。升级注意事项原先允许匿名访问的代理请求升级后可能开始收到401 Unauthorized如果你设置了backend.auth.dangerouslyDisableDefaultAuthPolicy: true本变更不生效代理会像所有端点都被设为dangerously-allow-unauthenticated一样工作仍需要匿名访问的端点请显式添加credentials: dangerously-allow-unauthenticated需要把调用方令牌透传给上游的端点请使用credentials: forward。相关测试见 plugins/proxy-backend/src/service/router.credentials.test.ts 与 plugins/proxy-backend/src/service/router.config.test.ts。四、破坏性变更二Gerrit 集成强制要求 Gitilesbackstage/integration1.12.0对 Gerrit 集成做出了两项收紧gitilesBaseUrl现在是必填项用于覆盖该要求的DISABLE_GERRIT_GITILES_REQUIREMENT环境变量已被移除backstage/backend-defaults0.3.0中GerritUrlReader构造函数的workdir参数被移除Gerrit 的readTree实现将只使用 Gitiles API不再支持通过 git clone 拉取仓库。仓库中的 Gerrit 集成配置解析packages/integration/src/gerrit/config.ts验证了gitilesBaseUrl在配置结构中的必填地位其测试覆盖可参见 packages/integration/src/gerrit/config.test.ts 与 packages/integration/src/gerrit/GerritIntegration.test.ts。升级动作检查你的app-config.yaml为所有 Gerrit 集成补上形如https://gerrit-review.example.com/gitiles的gitilesBaseUrl配置否则配置加载将失败。五、破坏性变更三Elasticsearch 索引器将删除陈旧索引backstage/plugin-search-backend-module-elasticsearch1.5.0中索引器现在会在完成索引后删除匹配自身模式的陈旧索引以防止陈旧索引导致分片耗尽。例如使用some-type-index__*模式的索引器会删除匹配该模式的历史索引。同时ElasticSearchClientWrapper的getAliases方法被弃用可能在未来的版本中移除。升级注意事项升级前请务必确认你的索引模式不会匹配到并非由 Backstage 管理、不应被删除的索引。该索引器原本就使用通配符模式在这些索引上移除别名本次只是把删除动作延伸到索引本身。六、OAuth 作用域管理重构统一为additionalScopesv1.28.0 统一了所有 OAuth 认证 Provider 的作用域配置方式核心变化集中在backstage/plugin-auth-node0.4.14createOAuthAuthenticator现在接受新的scopes选项集合scopes.persist—— 作用域是否需要持久化替代原shouldPersistScopesscopes.required—— 始终请求的必选作用域列表scopes.transform—— 在请求前转换作用域的函数createOAuthProviderFactory新增additionalScopes选项并会从 auth provider 配置中读取additionalScopes两者都用于追加始终请求的作用域。底层行为变化持久化作用域的 Provider现在授权与刷新流程都会将已授权作用域与请求作用域合并此前授权流程不包含已有作用域、刷新流程只包含已有作用域。同时各 Provider 模块统一了配置破坏性变更——移除scope/scopes配置项改用标准additionalScopes配置并各自设置了必选作用域始终存在Provider 模块必选作用域backstage/plugin-auth-backend-module-atlassian-provider0.2.0offline_access、read:jira-work、read:jira-userbackstage/plugin-auth-backend-module-oauth2-provider0.2.0无新增必选仅移除scope配置backstage/plugin-auth-backend-module-oidc-provider0.2.0openid、profile、emailbackstage/plugin-auth-backend-module-vmware-cloud-provider0.2.0openid、offline_accessbackstage/plugin-auth-backend-module-pinniped-provider0.1.13openid、pinniped:request-audience、username、offline_accessbackstage/plugin-auth-backend-module-bitbucket-provider0.1.2accountbackstage/plugin-auth-backend-module-github-provider0.1.16read:userbackstage/plugin-auth-backend-module-gitlab-provider0.1.16read_userbackstage/plugin-auth-backend-module-google-provider0.1.16openid、userinfo.email、userinfo.profilebackstage/plugin-auth-backend-module-okta-provider0.0.12openid、email、profile、offline_access且支持数组形式配置此外本版本将 OneLogin Provider 从auth-backend中独立为backstage/plugin-auth-backend-module-onelogin-provider0.1.0OIDC 模块还修复了当服务器未提供revocation_endpoint时不应调用 revoke 函数的问题。七、前端外部路由默认绑定 静态配置化路由绑定1. 外部路由默认目标defaultTargetbackstage/core-plugin-api1.9.3为createExternalRouteRef新增了defaultTarget选项实现见 packages/frontend-plugin-api/src/routing/ExternalRouteRef.ts允许按名称指定默认目标如catalog.catalogIndex当目标路由存在于应用中且没有显式路由绑定时会自动使用该默认目标。基于此机制多个插件在本版本添加了默认外部路由绑定backstage/plugin-catalog1.21.0createComponent→ Scaffolder 页面viewTechDoc→ TechDocs 实体文档页createFromTemplate→ Scaffolder 选中模板页backstage/plugin-scaffolder1.21.0registerComponent→ Catalog Import 页面viewTechDoc→ TechDocs 实体文档页backstage/plugin-api-docs0.11.6registerComponent默认绑定到 Catalog Import 页面backstage/plugin-catalog-graph0.4.6catalogEntity默认绑定到 Catalog 实体页面backstage/plugin-org0.6.26catalogIndex外部路由变为可选默认绑定到 Catalog 索引页。2. 静态配置化路由绑定backstage/core-app-api1.12.6支持通过静态配置app.routes.bindings配置路由绑定而不再局限于代码方式app: routes: bindings: catalog.createComponent: catalog-import.importPage配置键的格式为plugin-id.externalRouteNameexternalRouteName是createPlugin的externalRoutes对象中使用的键名值格式相同但名称取自插件的routes选项。上述配置等价于代码中的const app createApp({ // ... bindRoutes({ bind }) { bind(catalogPlugin.externalRoutes, { createComponent: catalogImportPlugin.routes.importPage, }); }, });八、Scaffolder用SecretField取代不安全的密码控件backstage/plugin-scaffolder1.21.0与backstage/plugin-scaffolder-react1.9.0弃用了ui:widget: password会显示不安全警告推荐改用内置的SecretFieldui:field: Secret它配合${{ secrets.xxx }}表达式使用apiVersion: backstage.io/v1alpha1 kind: Template metadata: ... spec: parameters: - title: collect some information schema: type: object properties: password: title: Password type: string - ui:widget: password ui:field: Secret steps: - id: collect-info name: Collect some information action: acme:do:something input: - password: ${{ parameters.password }} password: ${{ secrets.password }}同版本的其他 Scaffolder 变化还包括新增任务级权限scaffolder.task.create、scaffolder.task.cancel、scaffolder.task.read前端ContextMenu、ActionsPage、OngoingTask、TemplateCard组件已同步适配后端端点见 plugins/scaffolder-backendbackstage/plugin-scaffolder-backend-module-gitlab0.4.1新增gitlab:issue:edit与gitlab:pipeline:trigger两个 actionbackstage/plugin-scaffolder-backend-module-github0.3.0允许在createPullRequestaction 中留空作者信息并为githubPullRequest、githubWebhook增加 dry run 处理与测试EntityPicker改用entityPresentationApi展示实体debug:waitaction 的最大等待时间提升到 10 分钟RJSF 依赖统一升级到 5.18.4。九、认证与令牌插件间认证新方案与令牌载荷变化1. 基于静态密钥的插件间认证backstage/backend-app-api0.7.6新增了基于静态密钥的插件间认证方法适用于无法使用数据库做默认公钥签名方案参见 BEP-0003的只读服务节点等场景大多数用户仍应留在更安全、零配置的数据库签名方案上。使用openssl生成密钥对# 1. 使用 ES256 算法生成私钥 openssl ecparam -name prime256v1 -genkey -out private.ec.key # 2. 转换为 PKCS#8 格式 openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.ec.key -out private.key # 3. 提取公钥 openssl ec -inform PEM -outform PEM -pubout -in private.key -out public.key然后在app-config.yaml中配置backend: auth: keyStore: type: static static: keys: - publicKeyFile: /absolute/path/to/public.key privateKeyFile: /absolute/path/to/private.key keyId: some-custom-id2. 令牌载荷变化受限令牌不再包含ent字段受限用户令牌limited user tokens的载荷中不再包含ent字段所有权声明ownership claims改由 user info 服务获取。注意此变更前签发的受限令牌将失效用户可能需要清除浏览器 Cookie 以刷新认证令牌。3. 其他认证相关更新ExternalTokenHandler新增对 JWKS 令牌的支持外部访问服务令牌与服务主体service principals支持可选的accessRestrictions可将访问限制在特定插件或权限内backstage/backend-plugin-api0.6.19、backstage/backend-test-utils0.4.0的mockCredentials.service亦支持该选项backstage/backend-plugin-api0.6.19将TokenManagerService与IdentityService类型标记为弃用。十、New Backend System 清理去掉多余的函数调用括号backstage/backend-plugin-api0.6.19开始推进BackendFeature契约变更createBackendPlugin与createBackendModule现在实际返回BackendFeature而非() BackendFeature因此在向 backend 或测试 backend如startTestBackend添加插件/模块时应去掉尾部的()调用括号。短期内为非破坏性feature 类型带有返回自身的回调签名但该回调签名将在未来版本移除强烈建议现在就清理await startTestBackend({ features: [ eventsServiceFactory(), // service - stays unchanged - catalogModuleBitbucketCloudEntityProvider(), // module - remove parentheses catalogModuleBitbucketCloudEntityProvider,其他契约层面的清理BackendPluginConfig、BackendModuleConfig、ExtensionPointConfig分别更名为CreateBackendPluginOptions、CreateBackendModuleOptions、CreateExtensionPointOptionsSchedulerService声明及其依赖类型的带前缀版本从backstage/backend-tasks迁至backstage/backend-plugin-apiUrlReader相关类型全部加上UrlReaderService前缀重命名如ReadTreeOptions→UrlReaderServiceReadTreeOptions共 9 个类型。十一、Catalog 与 Kubernetes 等插件的功能更新Catalog 相关backstage/plugin-catalog-backend1.23.0在新后端系统中透传EventsService修复getLocationByEntity的 bugDefaultCatalogCollator确保同时索引name与titlebackstage/plugin-catalog-import0.12.0前端插件从identityApi迁移到fetchApi集成 Azure DevOps 作为 Catalog 导入源支持像 GitHub 一样向 Azure DevOps 仓库创建 Pull Requestbackstage/plugin-catalog-backend-module-ldap0.6.0LDAP Catalog 模块迁移到新后端系统backstage/plugin-catalog-backend-module-gitlab0.3.18修复GitlabOrgDiscoveryEntityProvider缺少orgEnabled配置时报错、以及 fallback 分支优先于 GitLab 默认分支的问题。Kubernetes 相关backstage/plugin-kubernetes-backend0.18.0、plugin-kubernetes-common0.8.0、plugin-kubernetes-react0.4.0全面切换到 Kubernetesautoscaling/v2API同时kubernetes-react与plugin-kubernetes、plugin-search一样完成了从identityApi到fetchApi的迁移。通知系统Notificationsbackstage/plugin-notifications-backend0.3.0与backstage/plugin-notifications-node0.2.0支持按 processor 过滤通知邮件模块backstage/plugin-notifications-backend-module-email0.1.0同步支持通知过滤器前端backstage/plugin-notifications0.2.2修复了标题计数器的性能问题。TechDocs 与搜索backstage/plugin-techdocs-node1.12.5TechdocsGenerator不再强制要求containerRunner选项即可在 Docker 中生成 TechDocs支持为 techdocs builder 定义自定义构建日志传输Harness Provider 实现了readTreebackstage/backend-common与backstage/integration从而支持 TechDocs 功能getRepoUrlFromLocationAnnotation增加对 Harness SCM 集成的检查backstage/plugin-search-backend1.5.10与search-backend-node1.2.24将启动拆分为 init 与 start 两个阶段确保初始化在启动前完成。十二、测试与开发工具链更新backstage/backend-test-utils0.4.0新增TestCaches用法与TestDatabases类似MockDirectoryOptions更名为CreateMockDirectoryOptionsmockCredentials.service支持访问限制backstage/cli0.26.7repo fix命令新增--publish标志用于校验并在可能时生成发布所需元数据打包发布时还会检查backstage.pluginId与backstage.pluginPackage(s)字段包构建目标提升为 ES2022backstage/cli-common0.1.14findPaths的 monorepo 根目录检查接受package.json中简写的workspaces配置backstage/create-app0.5.16TypeScript 升级到 5.4移除dockerode依赖新脚手架应用从侧边栏移除 Tech Radar 菜单项backstage/core-components0.14.8Gauge 组件新增decimalDigits属性控制小数位数SidebarSubmenu文字跟随主题色Status 组件新增图标。十三、升级清单与排障速查结合上述内容升级到 v1.28.0 时建议按以下顺序检查替换核心服务导入auth/httpAuth/userInfo/scheduler/urlReader等服务从backstage/backend-defaults/*导入不要再从backend-app-api、backend-common导入检查代理端点为需要匿名访问的代理端点显式配置credentials: dangerously-allow-unauthenticated否则会收到401补齐 Gerrit 配置为所有 Gerrit 集成配置gitilesBaseUrl确认 Elasticsearch 索引模式确保索引器模式不会误删非 Backstage 管理的索引迁移 OAuth 作用域配置将scope/scopes改为additionalScopes并留意各 Provider 新增的必选作用域清理后端 feature 调用括号去掉插件/模块后的()替换 Scaffolder 密码字段ui:widget: password→ui:field: Secret并在步骤输入中改用${{ secrets.xxx }}处理受限令牌失效如有需要提示用户清理浏览器 Cookie 以刷新令牌更新 Gerrit URL reader 依赖假设readTree仅走 Gitiles API不再支持 git clone。如果升级过程中需要精确匹配版本组合可以参考仓库内 packages/release-manifests 中维护的发布清单以及 docs/keeping-backstage-updated.md 了解版本升级的常规流程。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
