Backstage v1.14.0 版本发布解读：OpenAPI 工具重构、DevTools 新插件与配置加载体系升级

Backstage v1.14.0 版本发布解读OpenAPI 工具重构、DevTools 新插件与配置加载体系升级【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章围绕 Backstage 开源仓库中的官方发布说明 docs/releases/v1.14.0.md 及其配套的 docs/releases/v1.14.0-changelog.md 展开逐项解读 v1.14.0 的核心亮点、破坏性变更与升级路径并结合仓库源码验证各特性的实际实现帮助维护者在升级或集成时快速定位影响面、规避坑点。v1.14.0 是 Backstage 在软件目录Catalog、软件模板Scaffolder、认证Auth与基础设施工具链上的一次重要迭代官方 OpenAPI 工具命令全面重组、Kubernetes 插件首次支持 Pod 日志查看、全新的 DevTools 运维插件上线、配置加载体系重构为可扩展的 ConfigSource 模型同时为 React 18 的过渡正式弃用 React 16。本文将从发布说明出发深入对应源码路径为读者提供一份既有官方解读、又有实现证据的升级参考。版本总览一次安全修复与多项能力升级根据发布说明v1.14.0 包含一项重要的安全修复、大量 Bug 修复与令人兴奋的新增能力。总体来看本次版本围绕以下主线展开类型内容影响对象BREAKINGOpenAPI 工具命令重组为schema openapi子命令生成文件改为.generated.ts使用 repo-tools 生成 API 客户端/服务端的开发者BREAKINGKubernetes 插件新增 Pod 日志查看相关接口调整依赖kubernetesProxyApi、KubernetesDrawer的自定义插件DEPRECATION正式弃用 React 16 支持仍停留在 React 16 的应用新插件DevTools面向集成者的运维信息面板插件集成与排障人员底层迁移AWS 相关特性迁移到 AWS SDK v3使用 AWS IAM 鉴权的 Kubernetes 集群架构升级Auth 后端会话持久化到数据库配置加载重构为 ConfigSource 体系多实例部署的 Auth 后端、配置管理功能增强软件模板支持 Markdown 输出Catalog 增加 namespace 过滤软件模板作者、Catalog 使用者性能优化Catalog 数据库热点操作精简大规模 Catalog 部署安全修复Scaffolder 依赖的vm2漏洞CVE-2023-32314Scaffolder 插件使用者以下各节将逐项展开说明。BREAKINGOpenAPI 工具命令重组与.generated.ts生成物命令统一收敛到schema openapi子命令v1.14.0 对backstage/repo-tools0.3.0中的 OpenAPI 相关命令做了破坏性重组所有命令被归入schema openapi子命令之下便于后续扩展与维护。发布说明中给出的迁移示例为# 旧命令v1.14.0 之前 yarn backstage-repo-tools schema:openapi:verify # 新命令v1.14.0 起 yarn backstage-repo-tools schema openapi verify从当前仓库源码 packages/repo-tools/src/commands/index.ts 可以印证这一分组结构openApiCommand下注册了generate生成客户端或服务端桩代码、validate校验 OpenAPI 3.x 文档合法性、fuzz基于随机数据对服务端进行模糊测试、diff对比 API 变更四个子命令且generate命令支持--client-package、--server、--client-additional-properties、--watch等选项。仓库级命令repo schema openapi则提供validate、lint、fuzz、diff等批量操作见 index.ts其中旧命令verify已被移除调用时会直接报错并提示改用repo schema openapi validate。生成文件改为.generated.ts并增加警告头第二个破坏性变更与生成产物有关生成的 OpenAPI 客户端/服务端文件现在使用.generated.ts扩展名并在文件顶部附带警告头明确提示该文件由工具生成、不应手工编辑。这一改动对应 changelog 中 commit27956d78671的目的在于让 lint 规则、代码审查流程可以更容易地将生成文件与手写代码区分开避免误改。配套的backstage/backend-openapi-utils0.0.2也同步调整了 README并对参数嵌套 schema 的解析做了修正改为引用中央 schema。对于维护者而言升级时需要将 CI 中所有schema:openapi:*旧命令改为schema openapi *新语法重新生成客户端/服务端文件确认.generated.ts文件被纳入忽略/区分规则清理对旧文件名的 import 引用。Kubernetes 插件Pod 日志查看器与接口破坏性变更新能力Pod 日志查看v1.14.0 为 Kubernetes 插件带来了展示 Pod 日志的能力对应 changelog commit280ec10c18e。这一功能使运维人员可以直接在 Backstage 的 Kubernetes 页面上查看工作负载 Pod 的运行日志而无需切换到 kubectl 或第三方控制台。同时插件在展示资源 YAML 时不再显示 Kubernetes 的 managedFields使视图更加简洁commita160e02c3d7。破坏性变更一kubernetesProxyApi需加入插件 API 列表由于新增了日志查看能力Kubernetes 插件的 API 结构发生了变化kubernetesProxyApi现在需要被显式地添加到插件自身的 API 列表中。对于基于 Kubernetes 插件组件构建自定义插件的开发者需要按如下方式补充export const kubernetesPlugin createPlugin({ id: kubernetes, apis: [ // ... createApiFactory({ api: kubernetesProxyApiRef, deps: { kubernetesApi: kubernetesApiRef, }, factory: ({ kubernetesApi }) new KubernetesProxyClient({ kubernetesApi, }), }), ], });破坏性变更二KubernetesDrawer更名为KubernetesStructuredMetadataTableDrawer组件KubernetesDrawer被重命名为KubernetesStructuredMetadataTableDrawer——因为抽屉现在不止承载StructuredMetadataTable一种内容例如还承载日志视图旧名称已无法准确表达其职责。迁移方式为// 旧写法 import { KubernetesDrawer } from backstage/plugin-kubernetes; // 新写法 import { KubernetesStructuredMetadataTableDrawer } from backstage/plugin-kubernetes;后端配套改进AKS 鉴权与性能优化与前端日志查看配套backstage/plugin-kubernetes-backend0.11.0在本版本也有一批重要更新新增authProvider: aks集群配置为authProvider: aks时retrieveObjectsByServiceId动作会从 Azure 获取 AKS 访问令牌并在请求体中通过auth.aks以 bearer token 形式认证changelog commit05f1d74539d/c7bad1005baPod 指标支持labelSelector限制允许按标签选择器拉取 Pod 指标显著缩小大规模集群下的响应体积commitf4114f02d49修复代理端点 500 错误客户端侧鉴权配置的集群在代理请求时此前总会失败的问题已修复commita341129b754。DEPRECATIONReact 16 正式弃用为推进 React 18 的过渡Backstage 在 v1.14.0 中正式弃用对 React 16 的支持changelog 中backstage/cli0.22.7 的 commitd548886872d即包含 Deprecated the use of React 16。发布说明明确指出当前没有任何东西会立刻损坏但如果你仍停留在 React 16运行backstage-cli命令时会出现友好的警告信息引导你尽快升级到 React 17。这是典型的提前预警式弃用策略——先让所有依赖方知道方向再在后续版本中逐步收紧约束。升级建议将应用的 React 依赖从 16.x 提升至 17.x若环境允许可一步到位到 18并同步升级types/react与react-dom随后运行yarn install与backstage-cli versions:check确认依赖树一致。新插件DevTools——面向集成者的运维信息面板插件定位与开箱能力v1.14.0 引入了一个面向集成者integrator而非终端用户的新插件backstage/plugin-devtools0.1.0由 awanlin 贡献。它把关于 Backstage 安装实例的有用信息直接呈现在前端帮助排障、审计与理解安装现状。该插件被视为未来更多运维ops类功能的基础。根据插件官方文档 plugins/devtools/README.mdDevTools 开箱即带两个标签页另有若干可选标签页标签页功能Info展示当前运行实例的操作系统、Node.js 版本、Backstage 版本及各包版本Config展示当前实例正在使用的配置基于各插件声明的 schema对标记为secret可见性的配置进行脱敏Scheduled Tasks可选查看并触发定时任务External Dependencies可选展示外部依赖的可达性状态Catalog Unprocessed Entities可选展示 Catalog 中未处理实体Info 标签页的版本报告机制Info 标签页中Backstage 版本的准确展示依赖一个前提运行实例根目录必须存在backstage.json文件。发布说明与插件文档都特别提示若使用 Docker 部署需要修改 Dockerfile 确保该文件被复制进镜像的WORKDIRWORKDIR /app # This switches many Node.js dependencies to production mode. ENV NODE_ENVproduction # Then copy the rest of the backend bundle, along with any other files we might want (including backstage.json). COPY --chownnode:node ... backstage.json ./安全提示Config 标签页的脱敏依赖 schema 声明Config 标签页能够脱敏凭据依赖的是各插件在配置 schema 中将敏感属性visibility声明为secret。若插件未正确声明则密钥会以明文展示。插件文档强烈建议启用权限框架并对 DevTools 应用合适的权限策略以限制谁可以查看配置信息。安装与自定义标签页安装前端包# From your Backstage root directory yarn --cwd packages/app add backstage/plugin-devtools安装后插件可通过默认特性发现feature discovery自动接入应用。如需自定义标签页组合可以在packages/app/src/components/devtools/CustomDevToolsPage.tsx中通过DevToolsLayout自由编排import { ConfigContent, ExternalDependenciesContent, InfoContent, } from backstage/plugin-devtools; import { DevToolsLayout } from backstage/plugin-devtools; export const DevToolsPage () { return ( DevToolsLayout DevToolsLayout.Route pathinfo titleInfo InfoContent / /DevToolsLayout.Route DevToolsLayout.Route pathconfig titleConfig ConfigContent / /DevToolsLayout.Route DevToolsLayout.Route pathexternal-dependencies titleExternal Dependencies ExternalDependenciesContent / /DevToolsLayout.Route /DevToolsLayout ); }; export const customDevToolsPage DevToolsPage /;随后在 packages/app/src/App.tsx 中引入并将路由挂载到/devtools路径下。后端部分则需先安装并配置backstage/plugin-devtools-backend0.1.0其实现位于 plugins/devtools-backend。底层迁移AWS SDK v3 与AwsIamKubernetesAuthTranslatorv1.14.0 在底层将 AWS 相关特性迁移到AWS SDK v3客户端体系涉及backstage/plugin-kubernetes-backend、backstage/plugin-search-backend-module-elasticsearch、backstage/integration-aws-node、backstage/plugin-events-backend-module-aws-sqs等多个包见 changelog 中多处Standardize aws-sdk v3 versions记录。多数场景下这应当在雷达之下工作行为与之前一致但官方仍建议遇到异常时及时反馈。该迁移伴随一处次要接口破坏AwsIamKubernetesAuthTranslator类移除了awsGetCredentials、getBearerToken、getCredentials、validCredentials四个方法changelog commit890988341e9且没有替代方法。发布说明指出该类的使用面主要局限在包内部对外部使用方影响有限但若你的自定义代码直接调用了上述方法升级前必须移除相关逻辑。此外backstage/plugin-search-backend-module-elasticsearch1.3.0在此次升级中同时获得了OpenSearch Serverless 支持commit3d72bdb41c7AWS Elasticsearch/OpenSearch 集成路径更完整。Auth 后端会话持久化到数据库从内存会话到数据库会话对于使用 session 存储的认证提供方v1.14.0 将原本保存在本地内存中的会话迁移到了auth 后端数据库中。这带来的直接收益是多实例横向扩展的 auth 后端之间可以共享会话状态会话处理不再受单实例内存的局限。从源码 plugins/auth-backend/src/service/router.ts 可以看到具体实现当配置中存在auth.session.secret时后端启用 cookie 解析与 express-session 中间件并使用connectSessionKnex提供的KnexSessionStore将会话写入数据库const secret config.getOptionalString(auth.session.secret); if (secret) { router.use(cookieParser(secret)); const enforceCookieSSL authUrl.startsWith(https); const KnexSessionStore connectSessionKnex(session); router.use( session({ secret, saveUninitialized: false, resave: false, cookie: { secure: enforceCookieSSL ? auto : false }, store: new KnexSessionStore({ createtable: false, knex: await database.get(), }), }), ); router.use(passport.initialize()); router.use(passport.session()); }从该实现可以推断两点实践要点会话表需自行管理creatabletable: false表示后端不会自动建表升级时需确保数据库中已存在 express-session 所需的会话表可参考connect-session-knex的 schemaHTTPS 环境自动启用安全 Cookiecookie.secure会根据authUrl是否以https开头自动设置生产环境务必使用 HTTPS 访问 auth 服务。其他 Auth 修复backstage/plugin-auth-backend0.18.3同时修复了部分请求错误的抛出方式commit7c116bcac7fbackstage/core-app-api1.8.0修复了 Azure auth provider 对单资源多 scope 获取访问令牌的 Bugcommitb645d70034a。此外HostDiscovery作为新名称被引入用于取代因命名原因被弃用的SingleHostDiscoverybackend-common 0.18.5commit42d817e76ab。软件模板Markdown 输出支持在模板 outputs 中输出 Markdown 文本v1.14.0 允许软件模板Software Template在任务运行完成后于scaffolder/next的outputs 部分输出 Markdown 内容从而向终端用户呈现更丰富的结果信息changelog commit82e10a6939c由 voximity 贡献。模板输出结构中的 Markdown 文本由text字段承载。当前仓库的模板 schema plugins/scaffolder-common/src/Template.v1beta3.schema.json 明确定义了该结构textMarkdown text blobs列表即模板产出的文本数据每个文本项包含title用户友好的显示名、iconUI 图标键、contentThe text blob to display in the UI, rendered as Markdown即以 Markdown 渲染的文本内容以及可选的if条件——当条件求值为false/undefined/null//0/[]时该文本被排除。schema 中的示例为**hey** _Im_ Markdown说明 content 中可以使用 Markdown 语法加粗、斜体等。前端渲染链路从前端实现看scaffolder-react的 DefaultTemplateOutputs.tsx 负责渲染任务输出它会从output.text中选出标有default的文本项无 default 时取第一项进行展示文本渲染组件使用backstage/core-components中的MarkdownContent。整套链路验证了模板产出 Markdown → 任务输出 → UI 以 Markdown 渲染的闭环。权限元数据完善配套地backstage/plugin-scaffolder-common1.3.0现在额外导出scaffolderTemplatePermissions与scaffolderActionPermissions按资源类型拆分的权限子集commit67115f532b8scaffolder-backend1.14.0的元数据端点也正确暴露两类资源类型的权限与规则便于权限策略按需引用。Scaffolder 其他改进catalog:fetch动作支持defaultNamespace与defaultKind参数commita73b3c0b097scaffolder/next的按钮 UX 优化Stepper 中 Create 按钮增加内边距OngoingTask组件新增包含 Cancel 与 Start Over 的按钮栏commitad1a1429de4backstage/plugin-scaffolder-backend-module-gitlab0.2.0新增gitlab:group:ensureExists动作并修复多个 gitlab 动作的输入 schema 校验问题。配置加载体系重构ConfigSource 可扩展模型从loadConfig到ConfigSourcev1.14.0 最重要的架构级改动之一backstage/config-loader1.3.0引入了一套全新的config source配置源体系来取代旧的loadConfigchangelog commit201206132da。新体系更灵活可以更方便地创建和复用新的配置来源——例如从密钥托管服务secret providers加载配置。新体系由ConfigSource接口与ConfigSources工具类构成。接口定义为export interface ConfigSource { readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceIterator; }最佳实践是使用异步迭代器实现自己的配置源class MyConfigSource implements ConfigSource { async *readConfigData() { yield { config: [ { context: example, data: { backend: { baseUrl: http://localhost } }, }, ], }; } }默认配置源的组装逻辑使用默认行为加载配置对应官方 changelog 示例const source ConfigSources.default({ argv: options?.argv, remote: options?.remote, }); const config await ConfigSources.toConfig(source);当前仓库实现 packages/config-loader/src/sources/ConfigSources.ts 展示了ConfigSources.default的完整语义命令行参数解析parseArgs通过--config path|url传入的配置目标会被解析为path或url类型ConfigSources.ts默认文件回退defaultForTargets未显式指定目标时按app-config.yaml→app-config.${env}.yamlenv 来自BACKSTAGE_ENV环境变量逗号分隔→app-config.local.yaml→app-config.${env}.local.yaml的顺序加载文件ConfigSources.ts环境变量源EnvConfigSource读取以APP_CONFIG_前缀的环境变量合并与观测通过MergedConfigSource合并所有源toConfig返回一个可close()的可观测配置对象ObservableConfigProxy支持配置热更新ConfigSources.ts。URL 配置源需要显式开启源码中当目标看起来像 URL 但未传入remote选项时会直接抛出错误Config argument ... looks like a URL but remote configuration is not enabled。因此若要从远程 URL 加载配置必须传递remote: { reloadInterval }选项。配套改进ConfigSources.default支持watch文件监听、rootDir、allowMissingDefaultConfig允许默认 app-config.yaml 缺失、substitutionFunc自定义${MY_ENV_VAR}替换逻辑等选项ConfigSources.tsSchemaLoader新增noUndeclaredProperties选项可在校验配置时强制禁止未声明的键changelog commit473db605a4fbackstage-cli config:check新增--strict选项可让 schema 错误直接暴露backstage/cli0.22.7后端应用的configServiceFactory已切换为使用ConfigSources加载配置backend-app-api 0.4.3commitcf13b482f9e。Catalognamespace 过滤、性能优化与周边修复新增实体 namespace 过滤与列backstage/plugin-catalog1.11.0与backstage/plugin-catalog-react1.6.0为默认 Catalog 页面新增了实体 namespace 过滤器与列changelog commit2258dcae970。如果你使用自定义 Catalog 页面可按如下方式接入CatalogFilterLayout CatalogFilterLayout.Filters EntityTypePicker / UserListPicker initialFilter{initiallySelectedFilter} / EntityTagPicker / {/* if you want namespace picker */} EntityNamespacePicker / /CatalogFilterLayout.Filters CatalogFilterLayout.Content CatalogTable columns{columns} actions{actions} / /CatalogFilterLayout.Content /CatalogFilterLayoutEntityNamespacePicker的实现位于 plugins/catalog-react/src/components/EntityNamespacePicker/EntityNamespacePicker.tsx它基于EntityAutocompletePicker构建并通过EntityNamespaceFilter接入过滤链路。若你自定义了CatalogTable的列配置可通过createNamespaceColumn()工厂方法追加 namespace 列实现见 plugins/catalog/src/components/CatalogTable/columns.tsx列字段映射到entity.metadata.namespace。Catalog 数据库性能优化发布说明指出维护团队定位到了 Catalog 数据库操作中的若干热点并进行了精简预期体现为更低的 CPU 与 IOPS 占用。对于运行大规模 Catalog 的部署升级后应关注数据库侧指标的变化。其他 Catalog 生态更新backstage/plugin-catalog-backend-module-github0.3.0为GithubMultiOrgEntityProvider实现事件支持破坏性变更传入自定义teamTransformer时将完全覆盖默认转换行为同时修复了 GitHub 组织超过 1000 个仓库时queryWithPaging触发二级限流的问题改为每秒一个请求commit78bb674a713backstage/plugin-catalog-backend-module-aws0.2.0中AwsOrganizationCloudAccountProcessor.fromConfig现在返回 Promise 而非实例BREAKINGbackstage/app-defaults1.3.1新增 resource 实体的系统图标可通过useApp().getSystemIcon(kind:resource)获取。安全修复Scaffolder 依赖的 vm2 漏洞CVE-2023-32314v1.14.0 通过自动化安全流程修复了 Scaffolder 插件所依赖的vm2包中的一个安全漏洞CVE-2023-32314。官方给出的处理方式很务实修复版本的vm2已经包含在 Scaffolder 插件所需的版本范围内因此采纳者可以在不升级 Backstage 的前提下通过常规安全流程单独升级vm2依赖来修复该漏洞。从 changelog 可以看到backstage/plugin-scaffolder-backend1.14.0在补丁版本中两次提升vm2的最低版本要求先到 3.9.17再到 3.9.18commitsd20c87966a4、1a48b84901c。升级 Backstage 到 v1.14.0 同样会将其纳入依赖范围。升级路径与建议官方建议所有 Backstage 项目尽快升级到最新版本。结合本节内容升级到 v1.14.0 的完整检查清单如下升级依赖以yarn backstage-cli versions:bump或等价方式将backstage/*包统一提升到 v1.14.0 对应版本重点核对 changelog 中列出的所有包版本见下文速查表处理 OpenAPI 命令迁移将 CI/本地脚本中的schema:openapi:*命令改为schema openapi *重新生成客户端与服务端文件处理 Kubernetes 插件变更自定义插件若引用了KubernetesDrawer改为KubernetesStructuredMetadataTableDrawer若使用代理相关能力将kubernetesProxyApi加入插件 API 列表检查 AWS 鉴权代码移除对AwsIamKubernetesAuthTranslator已删除四个方法的调用React 版本核对确认应用不依赖 React 16 的 API尽早升级到 17 以消除 CLI 警告Auth 会话存储为使用 session 的 provider 准备数据库会话表配置auth.session.secret验证配置加载如使用了--config远程 URL需确认开启了remote选项如配置校验依赖严格模式可启用config:check --strict处理安全项确保vm2不低于 3.9.18可选采用新能力接入 DevTools 插件、为模板增加 Markdown 输出、启用 Catalog namespace 过滤等。主要包版本速查表v1.14.0包版本关键变化backstage/config-loader1.3.0引入 ConfigSource 体系替代 loadConfigbackstage/repo-tools0.3.0BREAKINGschema openapi子命令、.generated.tsbackstage/theme0.3.0亮色主题主色调整以符合 WCAGbackstage/plugin-catalog1.11.0namespace 过滤与列backstage/plugin-catalog-react1.6.0EntityNamespacePickerbackstage/plugin-devtools0.1.0新插件前端backstage/plugin-devtools-backend0.1.0新插件后端backstage/plugin-kubernetes0.9.0Pod 日志BREAKING接口调整backstage/plugin-kubernetes-backend0.11.0AWS SDK v3AKS 支持labelSelector 指标backstage/plugin-scaffolder-backend1.14.0vm2 ≥3.9.18权限元数据catalog:fetch 增强backstage/plugin-scaffolder-common1.3.0Markdown 输出权限子集导出backstage/plugin-scaffolder-react1.4.0Markdown 输出渲染按钮 UXbackstage/plugin-auth-backend0.18.3持久化会话存储backstage/plugin-search-react1.6.0搜索输入框增强backstage/plugin-search-backend-module-elasticsearch1.3.0AWS SDK v3OpenSearch Serverlessbackstage/core-app-api1.8.0navigate 事件携带路由参数Azure 多 scope 修复backstage/cli0.22.7React 16 弃用警告config:check --strict总结v1.14.0 是 Backstage 在工具链规范化与运行时架构现代化两条线上同步推进的版本OpenAPI 命令重组与.generated.ts标记让生成代码的管理更规范ConfigSource 体系为配置加载打开了插件化扩展的窗口Auth 会话入数据库为多实例部署扫清了障碍DevTools 插件则为集成者提供了全新的运维视角。与此同时React 16 弃用与 AWS SDK v3 迁移属于提前布局类变更短期影响有限但长期必须跟进。建议按上文检查清单逐步升级并持续关注后续版本中 ConfigSource、前端系统与新后端系统相关能力的演进。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考