Backstage v1.38.0-next.0 变更日志深度解读Scaffolder 扩展 API、Redis 缓存透传与动作幂等化【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库 v1.38.0-next.0-changelog 编写系统梳理本次里程碑版本在缓存服务、Scaffolder 模板扩展、目录Catalog表格过滤、OIDC 认证超时配置、CLI 工具链等方向的全部实质性变更并结合仓库源码逐项佐证实现原理。读完本文你将清楚了解每个变更的适用场景、配置方式与底层机制可直接据此评估和规划自己的 Backstage 实例升级。版本概览一次面向开发门户质量与可扩展性的集中更新v1.38.0-next.0是 Backstage 进入 1.38 版本线后的首个预发布next版本整体属于一次功能与质量并重的更新。本次共涉及数十个backstage/*包的版本变更其中包含Minor Changes功能级变更的核心包包括backstage/backend-defaults0.9.0-next.0允许将 Redis 客户端与集群选项透传给 Cache 核心服务commit01edf6ebackstage/cli0.32.0-next.0将clean、pre/postpack、fix命令内部重构为独立模块commitc7254aebackstage/plugin-catalog1.29.0-next.0目录表格支持基于 system 列的过滤commit9454ef9backstage/plugin-scaffolder1.30.0-next.0与backstage/plugin-scaffolder-react1.15.0-next.0新增从 scaffolder-backend 获取模板扩展信息template extensions的 APIcommit5890016backstage/plugin-scaffolder-backend1.32.0-next.0新增 template-extensions scaffolder 服务端点commit75e4db4并完善内置过滤器的类型校验commit497d47a其余大量包为 Patch Changes缺陷修复与内部优化其中不乏安全修复如module-federation/enhanced升级以修复 GHSA-593f-38f6-jp5m、Scaffolder 多个动作的幂等化改造以及多项影响面较大的行为修复下文逐一展开。缓存核心服务Redis 客户端与集群选项完整透传本次版本对backstage/backend-defaults的缓存能力做了一次关键增强Cache 核心服务现在允许将 Redis 客户端选项和集群选项完整透传给底层存储客户端。此前用户只能通过简单的backend.cache.connection字符串URL配置 Redis 连接现在可以获得接近keyv/redis全量能力的配置面。从源码看缓存管理的核心实现在 CacheManager.tsCacheManager.fromConfig读取backend.cache.store支持redis、valkey、memcache、memory、infinispan五种存储未配置时默认回退到memoryparseRedisOptionsCacheManager.ts从backend.cache.redis配置段读取client与cluster两大部分createRedisStoreFactoryCacheManager.ts在创建KeyvRedis实例时会将解析后的client选项作为第二参数传入并在检测到cluster.rootNodes配置时改用createCluster(...)创建集群连接同时始终挂载error处理器以避免错误导致进程退出。客户端选项client配置项类型说明client.namespacestring键命名空间前缀最终会与插件 ID 拼接形成完整 namespaceconstructNamespaceclient.keyPrefixSeparatorstring命名空间与插件 ID 之间的分隔符默认:client.clearBatchSizenumber批量清理键时的每批数量client.useUnlinkboolean是否使用UNLINK异步删除替代DELclient.noNamespaceAffectsAllboolean无命名空间时是否影响全部键集群选项cluster配置项类型说明cluster.rootNodesarray根节点列表只要存在该键即进入集群模式缺失时回退到非集群模式并输出告警日志cluster.defaultsobject集群默认行为选项可被connection对象中除url外的其余字段合并覆盖见 CacheManager.tscluster.minimizeConnectionsboolean是否最小化连接数cluster.useReplicasboolean是否启用副本读取cluster.maxCommandRedirectionsnumber最大命令重定向次数一个典型的 Redis 集群缓存配置示例如下backend: cache: store: redis connection: url: redis://localhost:6379 pingInterval: 10000 redis: client: namespace: my-namespace keyPrefixSeparator: : clearBatchSize: 100 useUnlink: true cluster: rootNodes: - url: redis://node1:6379 - url: redis://node2:6379 minimizeConnections: true useReplicas: false maxCommandRedirections: 5需要注意的是backend.cache.connection的对象形式仅支持在store: redis时使用源码中对此有显式校验字符串 URL 形式则适用于所有远程存储。另外backend.cache.useRedisSets配置键已废弃且不再有任何效果——底层keyv/redis与keyv/valkey库已不支持 redis sets配置该键只会输出一条弃用告警见 CacheManager.ts。Scaffolder 模板扩展从后端到前端的完整 API 链路本次版本在 Scaffolder软件模板生态上新增了一条完整的能力链路模板扩展信息template extensions的检索 API覆盖后端服务端点、前端调用 API 与类型校验三个层面。后端template-extensions 服务端点backstage/plugin-scaffolder-backend1.32.0-next.0新增了 template-extensions scaffolder 服务端点commit75e4db4。从 router.ts 可以看到服务内部将两类扩展统一封装const templateExtensions { additionalTemplateFilters: convertFiltersToRecord(additionalTemplateFilters), additionalTemplateGlobals: convertGlobalsToRecord(additionalTemplateGlobals), };即模板扩展由**自定义模板过滤器filters与自定义模板全局函数globals**两部分组成它们会被注入到任务执行 WorkerTaskWorker.create与 Dry RunnercreateDryRunner中供模板渲染时调用。该端点使前端或外部系统可以查询当前实例注册了哪些可用的模板扩展。前端模板扩展信息检索 APIbackstage/plugin-scaffolder1.30.0-next.0与backstage/plugin-scaffolder-react1.15.0-next.0同步新增了从前端检索这些模板扩展信息的 APIcommit5890016方便在 Scaffolder UI 中展示或校验模板可用的过滤器与全局函数。类型校验内置过滤器文档化与 zod 校验backstage/plugin-scaffolder-node0.8.1-next.0与backstage/plugin-scaffolder-backend中commit497d47a对内部内置过滤器进行了文档化便于模板作者了解开箱可用的能力确保在使用createTemplateFilter与createTemplateGlobalFunction时其类型会通过zodschema 进行校验避免将类型不正确的过滤器/全局函数注册进模板执行环境。这对模板开发者意味着自定义过滤器与全局函数的注册将获得更强的类型安全保障错误会提前暴露而非在模板渲染期才失败。Scaffolder 动作幂等化重复执行不再产生副作用幂等化idempotency是本次版本在 Scaffolder 动作层最重要的主题。多个高频发布类动作被改造为可安全重复执行动作所属模块commitpublish:githubscaffolder-backend-module-github0be1a1egithub:actions:dispatchscaffolder-backend-module-githuba833f0fgithub:autolinks:createscaffolder-backend-module-github1af427agithub:branch-protection:createscaffolder-backend-module-github180ea6epublish:azurescaffolder-backend-module-azure2bd41cepublish:bitbucketscaffolder-backend-module-bitbucketadfceeepublish:bitbucketCloudscaffolder-backend-module-bitbucket-cloud5266f1cnotification:sendscaffolder-backend-module-notifications25a7675sentry:project:createscaffolder-backend-module-sentrydcda66a幂等化的价值在于当任务因超时、网络抖动或 Worker 重启等原因被重试时重复执行发布/通知/创建动作不会产生重复仓库、重复分支保护规则、重复通知或重复项目等副作用这与仓库中关于任务幂等性的设计理念参见 BEP 0004scaffolder 任务幂等性一脉相承也与taskTimeoutJanitor定期清理陈旧任务的机制见 router.ts形成配合——任务超时被回收后重新执行的动作可以安全重放。Catalog 目录system 列过滤与分页修复表格支持基于 system 列的过滤backstage/plugin-catalog1.29.0-next.0新增了在目录表格中基于 system 列进行过滤的能力commit9454ef9。在默认表格列定义 defaultCatalogTableColumnsFunc.tsx 中可以看到case system的分支处理这意味着 system 列已纳入表格的过滤维度体系与 owner、lifecycle 等既有列保持一致便于按系统维度快速筛检实体。目录 React 生态修复backstage/plugin-catalog-react1.16.1-next.0包含两项值得关注的修复分页重置修复commit221ddbauseEntityList在更新过滤器时偏移分页offset pagination会正确重置避免用户切换过滤条件后停留在旧页码默认实体内容组扩展commit186d016alpha 版defaultEntityContentGroups中新增operation内容组。其他目录相关修复backstage/plugin-catalog-unprocessed-entities0.2.16-next.0删除未处理实体前新增确认弹窗commitba88bfa修复 FailedEntities 组件中convertTimeToLocalTimezone对 ISO 8601 日期字符串的解析与时区转换commit2479827backstage/plugin-catalog-backend-module-github0.7.12-next.0在缺失处补充了validateLocationsExist配置定义commit16648efbackstage/plugin-catalog-backend-module-gitlab0.6.5-next.0新增按成员资格membership与主题topics过滤仓库的能力commita568cdabackstage/plugin-catalog-backend-module-incremental-ingestion0.6.5-next.0修复文档中误导性的位置注解示例commit27d1031。认证OIDC Provider 支持自定义超时backstage/plugin-auth-backend-module-oidc-provider0.4.2-next.0新增了OIDC Provider 的自定义超时设置commit7495edf。官方 changelog 给出的配置示例如下auth: oidc: production: clientId: ${AUTH_GOOGLE_CLIENT_ID} clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET} timeout: seconds: 30从源码 authenticator.ts 可以确认其实现机制当配置中存在timeout键时通过readDurationFromConfig将其读取为时长支持seconds、minutes、hours等字段转换为毫秒后注入 OIDC 客户端的自定义 HTTP 选项提供器未配置时则使用默认超时。在配套测试 authenticator.test.ts 中覆盖了三种场景未配置超时时使用默认值10000ms配置timeout: { seconds: 30 }时HTTP 超时精确生效为30000ms传入非法超时配置如直接给数字而非时长对象时能优雅降级处理而不崩溃。这一能力对网络状况复杂、OIDC 发现端点响应较慢的部署环境尤其有用可避免因默认超时过短导致的登录失败。CLI 工具链命令模块化、安全补丁与两项行为修复backstage/cli0.32.0-next.0本次包含一次内部结构调整与多项修复命令模块化commitc7254aeclean、pre/postpack、fix命令被迁移到各自独立的模块中属于纯内部重构对用户命令用法无影响但有利于后续维护与按需加载安全修复commit4ea76f7升级module-federation/enhanced至^0.9.0修复安全公告 GHSA-593f-38f6-jp5m。涉及 Module Federation 的实例应优先升级repo lint修复commit87a5cb4修复使用--max-warnings选项时repo lint命令失败的问题start命令修复commitd83f3f4修复start命令对多个--require标志处理不正确的问题现在所有指定的模块都会被正确加载。此修复对需要在启动前预加载如注入运行时钩子、加载环境变量多个模块的场景有直接影响。其他值得关注的修复与改进CanonUI 基础库backstage/canon0.2.1-next.0包含三项改进Menu 组件样式更新commit6af7b16为锚点标签anchor tags添加全局 CSS resetcommit513477fIcon 组件在找不到对应名称时返回null而非空 SVGcommit05a5003避免产生空白占位图标的怪异渲染。TechDocsbackstage/plugin-techdocs-node1.13.2-next.0commit304a422AWS 文件检索逻辑从“存入 buffer 数组”改为“通过 stream pipe 直接响应”显著改善大文件场景下的内存效率。对于使用 AWS S3 存储 TechDocs 静态文件的实例这一改动可降低后端内存峰值配套的backstage/plugin-techdocs-backend2.0.1-next.0、backstage/plugin-search-backend-module-techdocs0.4.1-next.0均基于该改动同步升级。前端生态backstage/plugin-scaffolder-react1.15.0-next.0模板卡片新增查看模板实体详情template entity detail的按钮commit6ed42b7模板作者与使用者可更便捷地从模板列表跳转到实体详情页backstage/plugin-home-react0.1.25-next.0commit2e4cb15修复未指定标题时内容分隔线自动隐藏的问题。后端生态backstage/plugin-devops、backstage/plugin-events、backstage/plugin-notifications、backstage/plugin-org、backstage/plugin-search、backstage/plugin-signals、backstage/plugin-user-settings等插件及其后端模块均在本版本中同步升级依赖保持与backend-defaults0.9.0-next.0等核心包的兼容性示例应用example-app、example-backend、example-backend-legacy、e2e-test等仓库内部工作区也随版本同步更新可作为升级后的行为参照。升级建议与注意事项安全优先如果实例使用 Module Federationmodule-federation/enhanced应优先升级backstage/cli以纳入 GHSA-593f-38f6-jp5m 的修复Scaffolder 用户本次大量动作github、azure、bitbucket、notifications、sentry 相关已幂等化升级后重试任务的行为会更安全新增的 template-extensions 端点与前端 API 可用来构建模板能力检视工具Redis 缓存用户如需细粒度控制可迁移到backend.cache.redis.client.*/cluster.*配置结构同时注意backend.cache.useRedisSets已废弃应及时清理OIDC 登录异常场景若登录流程受网络延迟影响可借助auth.oidc.*.timeout配置调整超时TechDocs AWS 存储内存效率提升是透明行为无需额外配置但值得在升级后观察内存指标确认收益。建议升级时使用官方 Upgrade Helper 工具核对依赖版本矩阵当前文档对应to1.38.0-next.0。完整的版本变更明细与包级依赖关系可查阅 v1.38.0-next.0-changelog如需要了解 Backstage 版本策略与升级节奏可参考 版本策略文档 与 保持 Backstage 更新。总结v1.38.0-next.0是一次典型的“功能增强 质量加固”版本Scaffolder 侧完成了模板扩展 API 全链路与发布动作幂等化为模板体系的自动化与可靠性打下基础缓存侧获得了 Redis 客户端/集群选项的完整透传能力OIDC 超时配置为认证链路的稳定性提供了新手段CLI 与 Canon、TechDocs 的修复则持续改善日常开发与运行体验。对于计划升级的团队建议重点验证 Scaffolder 模板与动作行为、Redis 缓存配置兼容性并结合上文列出的源码位置深入核对细节。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考