Backstage v1.26.0 发布详解安全默认的 Auth 架构落地、应用后端公开入口与后端系统关键变更【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南围绕 Backstage v1.26.0 官方发布说明展开深度剖析本次版本中落地并完成的 BEP-0003 Auth 架构演进用户身份证明uip声明、零配置插件签名密钥、OBO 令牌与外部访问静态令牌、app-backend实验性公开应用入口、新后端系统的模块加载与服务初始化变更、OpenAPI 工具链新增的 lint 与 fuzz 命令以及事件系统、Catalog 错误事件、Kubernetes 代理等配套改动。读者读完可掌握 v1.26.0 的核心能力变化、升级路径与源码级实现原理。一、版本概览与升级总览Backstage v1.26.0 是继 v1.25.0 之后的一次重要功能版本核心主题是安全默认secure by defaultBEP-0003Auth 架构演进见仓库内 beps/0003-auth-architecture-evolution/README.md中关于后端安全的主要部分在本版本全部落地。此外本次发布还涉及应用后端app-backend、新后端系统New Backend System、认证模块迁移、OpenAPI 工具链、事件系统与 Catalog 错误事件等多个方面。与以往版本一样官方强烈建议将你的 Backstage 项目保持在此最新版本之上。详细的升级指引可参考仓库文档 docs/getting-started/keeping-backstage-updated.md。本版本不包含任何安全修复Security Fixes属于纯粹的功能与架构演进版本。值得注意的是本次发布涉及若干BREAKING破坏性变更主要集中在新后端系统相关包如backstage/backend-app-api0.7.0与 Kubernetes 后端插件下文将逐一说明。二、Auth 改进BEP-0003 全面落地后端安全默认化v1.26.0 最核心的亮点是 BEP-0003Auth 架构演进的主要部分全部就位从后端需要自行加保护转变为后端默认受保护。BEP 全文可在仓库 beps/0003-auth-architecture-evolution/README.md 查阅其设计要点包括引入新的AuthService与HttpAuthService接口、默认访问控制策略Default Auth Policy、受限用户令牌Limited User Token、以及基于 On-Behalf-OfOBO的服务间通信。v1.26.0 将这些设计从提案变为实现。2.1 用户令牌新增uip身份证明声明由auth后端签发的用户令牌Backstage user token现在包含一个新的uipuser identity proof用户身份证明声明。该声明是一段独立的身份证明用于 Cookie、service on-behalf-of 令牌等有限的用户识别场景无需传递真实用户令牌及其完整授权能力。从源码实现看uip声明由 plugins/auth-backend/src/identity/issueUserToken.ts 中的createUserIdentityClaim()生成它仅以sub、iat、exp三个字段构造 payload并用与用户令牌相同的签名密钥生成一段JWS 签名片段而非完整的 JWT从而大幅压缩嵌入主令牌的体积// plugins/auth-backend/src/identity/issueUserToken.ts节选 const uip await createUserIdentityClaim({ header: { typ: tokenTypes.limitedUser.typParam, alg: key.alg, kid: key.kid, }, payload: { sub, iat, exp }, key: signingKey, }); const claims: BackstageTokenPayload { ...additionalClaims, iss: issuer, sub, ent, aud, iat, exp, uip, // 新增的用户身份证明声明 };同时签发逻辑对令牌体积设置了MAX_TOKEN_LENGTH 32768的硬性上限约 500 个实体引用的余量超过即抛出明确错误防止因 ownership 声明或自定义声明过大导致令牌膨胀。这一机制也呼应了 BEP-0003 中将用户令牌中的所有权信息分离出去的设计目标——完整的所有权信息ent声明将逐步迁移到由auth-backend提供的/v1/userinfo端点该端点在本版本已有bf4d71a提交的初始实现可解析并返回用户令牌中的sub与ent声明。2.2 插件间认证零配置公钥签名 OBO 令牌插件到插件plugin-to-plugin的认证在本版本被正式限定作用域properly scoped并基于一套零配置zero-configuration公钥签名方案每个插件现在可以生成自己的签名密钥用于令牌签发生成的公钥存储在插件数据库中公钥通过新端点/.backstage/auth/v1/jwks.json对外暴露见backstage/backend-app-api的 changelog 说明AuthService新增getPluginRequestToken方法可签发作用域受限的令牌使目标插件能够识别请求来自哪个插件借助前述uip身份证明机制新增on-behalf-ofOBO令牌用于在上游请求中安全携带用户身份。OBO 令牌的核心实现位于 packages/backend-defaults/src/entrypoints/auth/DefaultAuthService.ts 的getPluginRequestTokencase user: { const { token } internalForward; const onBehalfOf await this.userTokenHandler.createLimitedUserToken(token); return this.pluginTokenHandler.issueToken({ pluginId: this.pluginId, targetPluginId, onBehalfOf: { limitedUserToken: onBehalfOf.token, expiresAt: onBehalfOf.expiresAt, }, }); }可以看到当一个用户请求需要转发给上游插件时当前插件会先把用户的真实令牌转换为受限用户令牌createLimitedUserToken再将其封装进面向targetPluginId的插件令牌中。这样 OBO 令牌的受众audience被限定为目标插件无法被滥用于其他后端插件目标插件既能识别最近的调用方subject也能按原始调用者的身份应用权限。BEP 文档中的两张时序图token-sequence-cookie.drawio.svg与token-sequence-obo.drawio.svg分别描述了 Cookie 令牌流与 OBO 令牌流的完整交互。基于同一身份证明机制TechDocs 等需要暴露 Cookie 端点的插件现在会签发插件私有作用域的 Cookie从而杜绝同域共部署的其他插件被恶意复用 Cookie的滥用场景。2.3 外部调用方backend.auth.externalAccess静态令牌从外部调用方请求你的后端插件service-to-service auth在本版本变得更加简单新增了一个配置段backend.auth.externalAccess在传统的 legacy 服务令牌之外支持配置静态令牌static tokens。该系统被设计为可扩展的——未来可以继续添加更多认证方法。其底层实现位于 packages/backend-defaults/src/entrypoints/auth/external/ExternalAuthTokenHandler.ts默认注册了三种令牌处理器static、legacy、jwks并支持通过externalTokenHandlersServiceRefmultiton service ref注册自定义处理器const defaultHandlers: Recordstring, ExternalTokenHandlerunknown { static: staticTokenHandler, legacy: legacyTokenHandler, jwks: jwksTokenHandler, };配置解析逻辑支持accessRestrictions访问限制字段用于将外部令牌的访问限定到特定插件、特定权限名或权限动作create/read/update/delete详见 packages/backend-defaults/src/entrypoints/auth/external/helpers.ts 中的readAccessRestrictionsFromConfig()。一个典型的externalAccess配置如下backend: auth: externalAccess: - type: static options: token: ${MY_STATIC_TOKEN} subject: external:my-service # 该令牌代表的服务主体 accessRestrictions: - plugin: catalog # 仅允许访问 catalog 插件 permission: catalog-entity-read - plugin: scaffolder permissionAttribute: action: [read, create]同时旧的backend.auth.keys配置仍会被读取用于兼容 legacy 服务令牌但会输出弃用警告日志The backend.auth.keys config has been replaced by backend.auth.externalAccess。另外ServerTokenManager现在也会读取新的backend.auth.externalAccess设置见backstage/backend-common0.21.7的变更00fca28。2.4 升级注意事项多后端部署的更新顺序与数据库依赖多后端部署更新顺序如果你的 Backstage 部署拆分为 3 个或更多独立后端必须先更新出站调用最少的核心后端。新的自动化插件服务认证虽然使用特性检测feature detection来确定认证方式但只能处理一跳single hop。实践中这意味着如果使用了 permission backend 插件应先更新 permission backend 实例再更新 catalog。数据库依赖插件服务认证系统使用插件数据库存储非对称密钥。因此任何需要向其他插件发起请求的插件现在都必须拥有数据库并且需要在 JWKS 端点上接受入站 HTTP 请求。对大多数采用默认配置的部署而言无需任何操作默认设置会按需自动创建逻辑数据库但如果你使用的是自定义或锁定的数据库设置则可能需要为插件创建额外的数据库。2.5 新增 Auth 模块Cloudflare Access、Azure Easy Auth、Bitbucket更多认证提供方被迁移为独立的后端模块实现从而支持新后端系统。本版本新增的模块包括Cloudflare Access拆分为独立模块backstage/plugin-auth-backend-module-cloudflare-access-providerv0.1.0PR #24287 之前的 c26218d 提交原 Cloudflare Access 类型被标记为弃用Azure Easy Auth新模块backstage/plugin-auth-backend-module-azure-easyauth-providerv0.1.0。注意破坏性变更默认 provider ID 从easyAuth改为azureEasyAuth切换模块后需要同步更新 app config 以及前端ProxiedSignInPage的providerpropBitbucket新模块backstage/plugin-auth-backend-module-bitbucket-providerv0.1.0将 Bitbucket auth provider 迁移到独立模块包。这三个模块对应的源码目录均可在仓库 plugins 下找到plugins/auth-backend-module-cloudflare-access-provider/、plugins/auth-backend-module-azure-easyauth-provider/、plugins/auth-backend-module-bitbucket-provider/。三、App Backend实验性公开应用入口public entry pointapp-backend插件现在能够保护主应用包main application bundle只向未认证用户提供有限的公开包public bundle。启用方式在你的 app 包中添加一个src/index-public-experimental.tsx入口点该入口点仅在生产构建中使用。这仍然是一个实验性功能。与该特性配套的变更包括backstage/plugin-auth-react0.1.0移除了CookieAuthRefreshProvider与useCookieAuthRefresh的path选项BREAKING新增CookieAuthRedirect组件用于在使用app-backend的独立公开入口时将公开包重定向到受保护包backstage/core-app-api1.12.4与backstage/frontend-app-api0.6.4应用现在能感知自己是否由app-backend以公开包 受保护包分离模式提供处于受保护模式时应用会持续刷新会话 Cookie并在用户登出时清除 Cookiebackstage/plugin-app-backend在启用公开入口并与新 auth 服务配合时实现基于 Cookie 的认证并在缓存存储中跟踪资源命名空间。四、新后端系统New Backend System关键变更4.1 模块仅在关联插件存在时加载BREAKINGbackstage/backend-app-api0.7.0模块modules不再被加载除非其扩展的插件plugin存在。这是本版本新后端系统最重要的行为变更直接影响依赖注入与启动行为。与之配套backstage/backend-test-utils0.3.7的startTestBackend会在提供了模块但没有父插件时自动添加占位插件placeholder plugins保证测试环境的正常启动。4.2createServiceFactory新增initialization选项服务工厂新增初始化选项initialization允许服务创建者覆盖服务的初始化时机懒加载 lazy 或 饿加载 eager。默认策略保持与当前行为一致插件作用域plugin scoped服务默认懒加载根作用域root scoped服务默认饿加载。该选项同时被加入到backstage/backend-plugin-api0.6.17的类型定义中。4.3/api/:pluginId路径保留BREAKING/api/:pluginId路径现在保留给插件流量专用不再允许在 http router 服务中将其配置为其他用途。具体而言见backstage/backend-app-apichangelog 的10327fb变更httpRouterServiceFactory的getPath选项被弃用更一般地插件 API 路径被限定为/api/:pluginId/形式指向/api/*但不匹配任何已注册插件的请求不再由 index router 处理而是返回 404。4.4 全插件 LoggerService 迁移本次发布在全仓库范围内完成了将所有插件从旧 Winston logger 迁移到LoggerService的大扫除变更PR #24224由 drodil 贡献。对大多数用户透明但旧后端系统的部分用户会注意到差异需要移除 winston 兼容包装器winston compatibility wrapper。受影响的包包括backstage/backend-tasks0.5.22、backstage/plugin-kubernetes-backend0.17.0BREAKING、backstage/plugin-tech-insights-node0.6.0BREAKING、backstage/plugin-badges-backend0.4.0、backstage/plugin-adr-backend等。五、OpenAPI 工具链新 lint 规则与 fuzz 模糊测试backstage/repo-tools0.8.0为 OpenAPI 工具链新增两项能力5.1allowReservedlint 规则repo schema openapi lint命令新增一条 lint 规则强制所有 URL 参数设置allowReserved: true。原因默认的 URL 编码过于严格例如不允许将作为空格的编码。修复方式是为参数补充allowReserved: true/v1/todos: get: operationId: ListTodos # ... parameters: - name: entity in: query allowReserved: true schema: type: string该规则的实现位于 packages/repo-tools/src/commands/repo/schema/openapi/lint.ts错误信息为Query parameters must specify allowReserved (true or false)。5.2 新增 fuzz 模糊测试命令新增两个 fuzz 命令用于对插件进行模糊测试fuzzing通过自动生成符合 schema 的输入帮助发现应用代码中的 bug# 对单个包进行 OpenAPI fuzz backstage-cli package schema openapi fuzz # 对仓库中声明了 fuzz 脚本的所有包进行 fuzz仅测试相对指定 ref 有变更的包 backstage-cli repo schema openapi fuzz命令注册位于 packages/repo-tools/src/commands/index.tsrepo schema openapi fuzz与package schema openapi fuzzrepo级命令会筛选package.json中声明了fuzz脚本的包并执行yarn fuzz见 packages/repo-tools/src/commands/repo/schema/openapi/fuzz.ts。底层依赖 Schemathesis 测试库。六、事件系统改进与新后端系统的接入6.1 eventsServiceRef 取代 EventBroker / EventSubscriber在新后端系统中事件系统应改为通过依赖导出的eventsServiceRef访问而非旧的EventBroker和EventSubscriber模式。因此仍然使用旧后端系统的用户会注意到 GitHub catalog providers 的构造方式发生了一些变化详见backstage/plugin-catalog-backend-module-github0.6.0的 BREAKING 变更GithubOrgEntityProvider.onEvent变为私有GithubOrgEntityProvider.supportsEventTopics被移除GithubMultiOrgEntityProvider.fromConfig的eventBroker选项被移除supportsEventTopics同样移除受影响用户请将EventsService实例作为events选项传入这些 provider。6.2 Catalog 错误事件Catalog Error EventsCatalog 中的实体处理错误entity processing errors过去被发送到本地 logger这在生产环境中往往造成大量日志噪音且难以排查。本版本改为发送到事件系统events system。如果你希望保留原有的日志行为可以订阅该 topic实现PR #23022由 punkle 贡献。七、Kubernetes 代理破坏性变更backstage/plugin-kubernetes-backend0.17.0中KubernetesProxy现在要求向其构造函数传入DiscoveryService如果你仍在使用旧后端系统。这是本版本的一个明确 BREAKING 变更变更号6c19c14。该版本同时完成了 Winston logger 到LoggerService的替换5dd8177BREAKING并修复了BackstageCredentials转发、代理 handler 缺失 header 处理、credentials为undefined时崩溃等问题。八、其他值得关注的变更除上述主题外v1.26.0 还包含以下要点详见完整 changelog docs/releases/v1.26.0-changelog.md配置加载器backstage/config-loader1.8.0默认环境变量替换函数现在会裁剪替换值两端的空白字符避免环境变量误含空白引发的 bug若依赖旧行为可自行覆盖substitutionFuncConfigSources.default({ substitutionFunc: async name process.env[name], });同时新增了对环境变量的参数替换支持。集成层backstage/integration1.10.0新增 AWS CodeCommit URL Reader/Integration。Catalog 插件backstage/plugin-catalog1.19.0EntitySwitch路由函数新增isApiType()AboutCard新增create something similar按钮若实体带backstage.io/source-template注解则链接到对应 scaffolder 模板。通知系统notifications-backendURL 查询参数由minimal_severity改为minimumSeverity通知页面支持对多条选中的通知批量触发Save或Mark as readprocessor 函数更名为preProcess/postProcess并新增processOptions处理能力。搜索backstage/plugin-search-backend-module-elasticsearch1.4.0使用新后端系统时Elasticsearch provider仅在存在search.elasticsearch配置段时才被添加。CLIbackstage/cli0.26.3新增versions:migrate命令帮助将包迁移到新的backstage-community命名空间默认 linter 设置中加入 deprecation 插件默认关闭。九、升级路径与后续行动清单基于以上变更v1.26.0 的升级行动清单可归纳为保持项目更新参考 docs/getting-started/keeping-backstage-updated.md 中的升级指引将依赖升级到 v1.26.0 对应版本。多后端部署按出站调用最少优先的顺序更新后端先 permission backend再 catalog确认插件具备数据库且 JWKS 端点可达。旧后端系统用户移除 winston 兼容包装器将 GitHub org provider 的eventBroker选项替换为events为KubernetesProxy构造函数补充DiscoveryService。新后端系统用户确认模块加载行为变更模块仅在插件存在时加载如需自定义服务初始化时机使用createServiceFactory的initialization选项。认证配置如需开放外部调用配置backend.auth.externalAccessstatic/legacy/jwks accessRestrictions如需整体关闭内置保护可配置backend.dangerouslyDisableServiceAuth: true详见 BEP 文档。OpenAPI 使用者为所有 URL 参数补充allowReserved: true以通过新 lint 规则并可尝试新的 fuzz 命令进行 schema 驱动的模糊测试。总而言之v1.26.0 标志着 Backstage 认证体系从可选加固走向安全默认的转折点用户身份证明、插件签名密钥、OBO 令牌与外部访问配置共同构成了更清晰、更可扩展的安全边界而新后端系统的模块加载与服务初始化变更则进一步夯实了后端架构的稳定性。对于正在升级或规划多后端部署的团队本文列出的破坏性变更与升级顺序将是落地过程中最值得关注的部分。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage v1.26.0 发布详解安全默认的 Auth 架构落地、应用后端公开入口与后端系统关键变更【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南围绕 Backstage v1.26.0 官方发布说明展开深度剖析本次版本中落地并完成的 BEP-0003 Auth 架构演进用户身份证明uip声明、零配置插件签名密钥、OBO 令牌与外部访问静态令牌、app-backend实验性公开应用入口、新后端系统的模块加载与服务初始化变更、OpenAPI 工具链新增的 lint 与 fuzz 命令以及事件系统、Catalog 错误事件、Kubernetes 代理等配套改动。读者读完可掌握 v1.26.0 的核心能力变化、升级路径与源码级实现原理。一、版本概览与升级总览Backstage v1.26.0 是继 v1.25.0 之后的一次重要功能版本核心主题是安全默认secure by defaultBEP-0003Auth 架构演进见仓库内 beps/0003-auth-architecture-evolution/README.md中关于后端安全的主要部分在本版本全部落地。此外本次发布还涉及应用后端app-backend、新后端系统New Backend System、认证模块迁移、OpenAPI 工具链、事件系统与 Catalog 错误事件等多个方面。与以往版本一样官方强烈建议将你的 Backstage 项目保持在此最新版本之上。详细的升级指引可参考仓库文档 docs/getting-started/keeping-backstage-updated.md。本版本不包含任何安全修复Security Fixes属于纯粹的功能与架构演进版本。值得注意的是本次发布涉及若干BREAKING破坏性变更主要集中在新后端系统相关包如backstage/backend-app-api0.7.0与 Kubernetes 后端插件下文将逐一说明。二、Auth 改进BEP-0003 全面落地后端安全默认化v1.26.0 最核心的亮点是 BEP-0003Auth 架构演进的主要部分全部就位从后端需要自行加保护转变为后端默认受保护。BEP 全文可在仓库 beps/0003-auth-architecture-evolution/README.md 查阅其设计要点包括引入新的AuthService与HttpAuthService接口、默认访问控制策略Default Auth Policy、受限用户令牌Limited User Token、以及基于 On-Behalf-OfOBO的服务间通信。v1.26.0 将这些设计从提案变为实现。2.1 用户令牌新增uip身份证明声明由auth后端签发的用户令牌Backstage user token现在包含一个新的uipuser identity proof用户身份证明声明。该声明是一段独立的身份证明用于 Cookie、service on-behalf-of 令牌等有限的用户识别场景无需传递真实用户令牌及其完整授权能力。从源码实现看uip声明由 plugins/auth-backend/src/identity/issueUserToken.ts 中的createUserIdentityClaim()生成它仅以sub、iat、exp三个字段构造 payload并用与用户令牌相同的签名密钥生成一段JWS 签名片段而非完整的 JWT从而大幅压缩嵌入主令牌的体积// plugins/auth-backend/src/identity/issueUserToken.ts节选 const uip await createUserIdentityClaim({ header: { typ: tokenTypes.limitedUser.typParam, alg: key.alg, kid: key.kid, }, payload: { sub, iat, exp }, key: signingKey, }); const claims: BackstageTokenPayload { ...additionalClaims, iss: issuer, sub, ent, aud, iat, exp, uip, // 新增的用户身份证明声明 };同时签发逻辑对令牌体积设置了MAX_TOKEN_LENGTH 32768的硬性上限约 500 个实体引用的余量超过即抛出明确错误防止因 ownership 声明或自定义声明过大导致令牌膨胀。这一机制也呼应了 BEP-0003 中将用户令牌中的所有权信息分离出去的设计目标——完整的所有权信息ent声明将逐步迁移到由auth-backend提供的/v1/userinfo端点该端点在本版本已有bf4d71a提交的初始实现可解析并返回用户令牌中的sub与ent声明。2.2 插件间认证零配置公钥签名 OBO 令牌插件到插件plugin-to-plugin的认证在本版本被正式限定作用域properly scoped并基于一套零配置zero-configuration公钥签名方案每个插件现在可以生成自己的签名密钥用于令牌签发生成的公钥存储在插件数据库中公钥通过新端点/.backstage/auth/v1/jwks.json对外暴露见backstage/backend-app-api的 changelog 说明AuthService新增getPluginRequestToken方法可签发作用域受限的令牌使目标插件能够识别请求来自哪个插件借助前述uip身份证明机制新增on-behalf-ofOBO令牌用于在上游请求中安全携带用户身份。OBO 令牌的核心实现位于 packages/backend-defaults/src/entrypoints/auth/DefaultAuthService.ts 的getPluginRequestTokencase user: { const { token } internalForward; const onBehalfOf await this.userTokenHandler.createLimitedUserToken(token); return this.pluginTokenHandler.issueToken({ pluginId: this.pluginId, targetPluginId, onBehalfOf: { limitedUserToken: onBehalfOf.token, expiresAt: onBehalfOf.expiresAt, }, }); }可以看到当一个用户请求需要转发给上游插件时当前插件会先把用户的真实令牌转换为受限用户令牌createLimitedUserToken再将其封装进面向targetPluginId的插件令牌中。这样 OBO 令牌的受众audience被限定为目标插件无法被滥用于其他后端插件目标插件既能识别最近的调用方subject也能按原始调用者的身份应用权限。BEP 文档中的两张时序图token-sequence-cookie.drawio.svg与token-sequence-obo.drawio.svg分别描述了 Cookie 令牌流与 OBO 令牌流的完整交互。基于同一身份证明机制TechDocs 等需要暴露 Cookie 端点的插件现在会签发插件私有作用域的 Cookie从而杜绝同域共部署的其他插件被恶意复用 Cookie的滥用场景。2.3 外部调用方backend.auth.externalAccess静态令牌从外部调用方请求你的后端插件service-to-service auth在本版本变得更加简单新增了一个配置段backend.auth.externalAccess在传统的 legacy 服务令牌之外支持配置静态令牌static tokens。该系统被设计为可扩展的——未来可以继续添加更多认证方法。其底层实现位于 packages/backend-defaults/src/entrypoints/auth/external/ExternalAuthTokenHandler.ts默认注册了三种令牌处理器static、legacy、jwks并支持通过externalTokenHandlersServiceRefmultiton service ref注册自定义处理器const defaultHandlers: Recordstring, ExternalTokenHandlerunknown { static: staticTokenHandler, legacy: legacyTokenHandler, jwks: jwksTokenHandler, };配置解析逻辑支持accessRestrictions访问限制字段用于将外部令牌的访问限定到特定插件、特定权限名或权限动作create/read/update/delete详见 packages/backend-defaults/src/entrypoints/auth/external/helpers.ts 中的readAccessRestrictionsFromConfig()。一个典型的externalAccess配置如下backend: auth: externalAccess: - type: static options: token: ${MY_STATIC_TOKEN} subject: external:my-service # 该令牌代表的服务主体 accessRestrictions: - plugin: catalog # 仅允许访问 catalog 插件 permission: catalog-entity-read - plugin: scaffolder permissionAttribute: action: [read, create]同时旧的backend.auth.keys配置仍会被读取用于兼容 legacy 服务令牌但会输出弃用警告日志The backend.auth.keys config has been replaced by backend.auth.externalAccess。另外ServerTokenManager现在也会读取新的backend.auth.externalAccess设置见backstage/backend-common0.21.7的变更00fca28。2.4 升级注意事项多后端部署的更新顺序与数据库依赖多后端部署更新顺序如果你的 Backstage 部署拆分为 3 个或更多独立后端必须先更新出站调用最少的核心后端。新的自动化插件服务认证虽然使用特性检测feature detection来确定认证方式但只能处理一跳single hop。实践中这意味着如果使用了 permission backend 插件应先更新 permission backend 实例再更新 catalog。数据库依赖插件服务认证系统使用插件数据库存储非对称密钥。因此任何需要向其他插件发起请求的插件现在都必须拥有数据库并且需要在 JWKS 端点上接受入站 HTTP 请求。对大多数采用默认配置的部署而言无需任何操作默认设置会按需自动创建逻辑数据库但如果你使用的是自定义或锁定的数据库设置则可能需要为插件创建额外的数据库。2.5 新增 Auth 模块Cloudflare Access、Azure Easy Auth、Bitbucket更多认证提供方被迁移为独立的后端模块实现从而支持新后端系统。本版本新增的模块包括Cloudflare Access拆分为独立模块backstage/plugin-auth-backend-module-cloudflare-access-providerv0.1.0PR #24287 之前的 c26218d 提交原 Cloudflare Access 类型被标记为弃用Azure Easy Auth新模块backstage/plugin-auth-backend-module-azure-easyauth-providerv0.1.0。注意破坏性变更默认 provider ID 从easyAuth改为azureEasyAuth切换模块后需要同步更新 app config 以及前端ProxiedSignInPage的providerpropBitbucket新模块backstage/plugin-auth-backend-module-bitbucket-providerv0.1.0将 Bitbucket auth provider 迁移到独立模块包。这三个模块对应的源码目录均可在仓库 plugins 下找到plugins/auth-backend-module-cloudflare-access-provider/、plugins/auth-backend-module-azure-easyauth-provider/、plugins/auth-backend-module-bitbucket-provider/。三、App Backend实验性公开应用入口public entry pointapp-backend插件现在能够保护主应用包main application bundle只向未认证用户提供有限的公开包public bundle。启用方式在你的 app 包中添加一个src/index-public-experimental.tsx入口点该入口点仅在生产构建中使用。这仍然是一个实验性功能。与该特性配套的变更包括backstage/plugin-auth-react0.1.0移除了CookieAuthRefreshProvider与useCookieAuthRefresh的path选项BREAKING新增CookieAuthRedirect组件用于在使用app-backend的独立公开入口时将公开包重定向到受保护包backstage/core-app-api1.12.4与backstage/frontend-app-api0.6.4应用现在能感知自己是否由app-backend以公开包 受保护包分离模式提供处于受保护模式时应用会持续刷新会话 Cookie并在用户登出时清除 Cookiebackstage/plugin-app-backend在启用公开入口并与新 auth 服务配合时实现基于 Cookie 的认证并在缓存存储中跟踪资源命名空间。四、新后端系统New Backend System关键变更4.1 模块仅在关联插件存在时加载BREAKINGbackstage/backend-app-api0.7.0模块modules不再被加载除非其扩展的插件plugin存在。这是本版本新后端系统最重要的行为变更直接影响依赖注入与启动行为。与之配套backstage/backend-test-utils0.3.7的startTestBackend会在提供了模块但没有父插件时自动添加占位插件placeholder plugins保证测试环境的正常启动。4.2createServiceFactory新增initialization选项服务工厂新增初始化选项initialization允许服务创建者覆盖服务的初始化时机懒加载 lazy 或 饿加载 eager。默认策略保持与当前行为一致插件作用域plugin scoped服务默认懒加载根作用域root scoped服务默认饿加载。该选项同时被加入到backstage/backend-plugin-api0.6.17的类型定义中。4.3/api/:pluginId路径保留BREAKING/api/:pluginId路径现在保留给插件流量专用不再允许在 http router 服务中将其配置为其他用途。具体而言见backstage/backend-app-apichangelog 的10327fb变更httpRouterServiceFactory的getPath选项被弃用更一般地插件 API 路径被限定为/api/:pluginId/形式指向/api/*但不匹配任何已注册插件的请求不再由 index router 处理而是返回 404。4.4 全插件 LoggerService 迁移本次发布在全仓库范围内完成了将所有插件从旧 Winston logger 迁移到LoggerService的大扫除变更PR #24224由 drodil 贡献。对大多数用户透明但旧后端系统的部分用户会注意到差异需要移除 winston 兼容包装器winston compatibility wrapper。受影响的包包括backstage/backend-tasks0.5.22、backstage/plugin-kubernetes-backend0.17.0BREAKING、backstage/plugin-tech-insights-node0.6.0BREAKING、backstage/plugin-badges-backend0.4.0、backstage/plugin-adr-backend等。五、OpenAPI 工具链新 lint 规则与 fuzz 模糊测试backstage/repo-tools0.8.0为 OpenAPI 工具链新增两项能力5.1allowReservedlint 规则repo schema openapi lint命令新增一条 lint 规则强制所有 URL 参数设置allowReserved: true。原因默认的 URL 编码过于严格例如不允许将作为空格的编码。修复方式是为参数补充allowReserved: true/v1/todos: get: operationId: ListTodos # ... parameters: - name: entity in: query allowReserved: true schema: type: string该规则的实现位于 packages/repo-tools/src/commands/repo/schema/openapi/lint.ts错误信息为Query parameters must specify allowReserved (true or false)。5.2 新增 fuzz 模糊测试命令新增两个 fuzz 命令用于对插件进行模糊测试fuzzing通过自动生成符合 schema 的输入帮助发现应用代码中的 bug# 对单个包进行 OpenAPI fuzz backstage-cli package schema openapi fuzz # 对仓库中声明了 fuzz 脚本的所有包进行 fuzz仅测试相对指定 ref 有变更的包 backstage-cli repo schema openapi fuzz命令注册位于 packages/repo-tools/src/commands/index.tsrepo schema openapi fuzz与package schema openapi fuzzrepo级命令会筛选package.json中声明了fuzz脚本的包并执行yarn fuzz见 packages/repo-tools/src/commands/repo/schema/openapi/fuzz.ts。底层依赖 Schemathesis 测试库。六、事件系统改进与新后端系统的接入6.1 eventsServiceRef 取代 EventBroker / EventSubscriber在新后端系统中事件系统应改为通过依赖导出的eventsServiceRef访问而非旧的EventBroker和EventSubscriber模式。因此仍然使用旧后端系统的用户会注意到 GitHub catalog providers 的构造方式发生了一些变化详见backstage/plugin-catalog-backend-module-github0.6.0的 BREAKING 变更GithubOrgEntityProvider.onEvent变为私有GithubOrgEntityProvider.supportsEventTopics被移除GithubMultiOrgEntityProvider.fromConfig的eventBroker选项被移除supportsEventTopics同样移除受影响用户请将EventsService实例作为events选项传入这些 provider。6.2 Catalog 错误事件Catalog Error EventsCatalog 中的实体处理错误entity processing errors过去被发送到本地 logger这在生产环境中往往造成大量日志噪音且难以排查。本版本改为发送到事件系统events system。如果你希望保留原有的日志行为可以订阅该 topic实现PR #23022由 punkle 贡献。七、Kubernetes 代理破坏性变更backstage/plugin-kubernetes-backend0.17.0中KubernetesProxy现在要求向其构造函数传入DiscoveryService如果你仍在使用旧后端系统。这是本版本的一个明确 BREAKING 变更变更号6c19c14。该版本同时完成了 Winston logger 到LoggerService的替换5dd8177BREAKING并修复了BackstageCredentials转发、代理 handler 缺失 header 处理、credentials为undefined时崩溃等问题。八、其他值得关注的变更除上述主题外v1.26.0 还包含以下要点详见完整 changelog docs/releases/v1.26.0-changelog.md配置加载器backstage/config-loader1.8.0默认环境变量替换函数现在会裁剪替换值两端的空白字符避免环境变量误含空白引发的 bug若依赖旧行为可自行覆盖substitutionFuncConfigSources.default({ substitutionFunc: async name process.env[name], });同时新增了对环境变量的参数替换支持。集成层backstage/integration1.10.0新增 AWS CodeCommit URL Reader/Integration。Catalog 插件backstage/plugin-catalog1.19.0EntitySwitch路由函数新增isApiType()AboutCard新增create something similar按钮若实体带backstage.io/source-template注解则链接到对应 scaffolder 模板。通知系统notifications-backendURL 查询参数由minimal_severity改为minimumSeverity通知页面支持对多条选中的通知批量触发Save或Mark as readprocessor 函数更名为preProcess/postProcess并新增processOptions处理能力。搜索backstage/plugin-search-backend-module-elasticsearch1.4.0使用新后端系统时Elasticsearch provider仅在存在search.elasticsearch配置段时才被添加。CLIbackstage/cli0.26.3新增versions:migrate命令帮助将包迁移到新的backstage-community命名空间默认 linter 设置中加入 deprecation 插件默认关闭。九、升级路径与后续行动清单基于以上变更v1.26.0 的升级行动清单可归纳为保持项目更新参考 docs/getting-started/keeping-backstage-updated.md 中的升级指引将依赖升级到 v1.26.0 对应版本。多后端部署按出站调用最少优先的顺序更新后端先 permission backend再 catalog确认插件具备数据库且 JWKS 端点可达。旧后端系统用户移除 winston 兼容包装器将 GitHub org provider 的eventBroker选项替换为events为KubernetesProxy构造函数补充DiscoveryService。新后端系统用户确认模块加载行为变更模块仅在插件存在时加载如需自定义服务初始化时机使用createServiceFactory的initialization选项。认证配置如需开放外部调用配置backend.auth.externalAccessstatic/legacy/jwks accessRestrictions如需整体关闭内置保护可配置backend.dangerouslyDisableServiceAuth: true详见 BEP 文档。OpenAPI 使用者为所有 URL 参数补充allowReserved: true以通过新 lint 规则并可尝试新的 fuzz 命令进行 schema 驱动的模糊测试。总而言之v1.26.0 标志着 Backstage 认证体系从可选加固走向安全默认的转折点用户身份证明、插件签名密钥、OBO 令牌与外部访问配置共同构成了更清晰、更可扩展的安全边界而新后端系统的模块加载与服务初始化变更则进一步夯实了后端架构的稳定性。对于正在升级或规划多后端部署的团队本文列出的破坏性变更与升级顺序将是落地过程中最值得关注的部分。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
