Backstage v1.14.0 版本解读:ConfigSource 配置源体系、Catalog 命名空间过滤与 DevTools 插件

原创2026-09-12 18:49:301,969 阅读
文章标签:开发者门户前端后端插件系统代码生成文档研发协作云原生

Backstage v1.14.0 版本解读:ConfigSource 配置源体系、Catalog 命名空间过滤与 DevTools 插件

本文基于 Backstage 开源仓库 docs/releases/v1.14.0-changelog.md 整理,围绕 v1.14.0 的核心变更展开:新的 ConfigSource 配置源系统如何取代旧的 loadConfig,Catalog 页面新增的命名空间(namespace)过滤能力如何接入自定义页面,以及全新 DevTools 插件的引入方式;同时覆盖 theme 无障碍(WCAG)改进、Kubernetes AKS 认证、Scaffolder 权限元数据、repo-tools OpenAPI 子命令迁移等关键升级。读者阅后可掌握该版本的升级要点、破坏性变更清单以及对应源码级实现细节。

一、v1.14.0 版本概览

Backstage v1.14.0 是一次同时包含 Minor(新增能力)与 Patch(缺陷修复)变更的常规版本,涉及的核心包包括:

包名 版本 变更类型 核心内容
@backstage/config-loader 1.3.0 Minor 引入全新的 ConfigSource 配置源系统
@backstage/core-app-api 1.8.0 Minor 分析事件 navigate 携带路由参数;新增 FrontendHostDiscovery
@backstage/repo-tools 0.3.0 Minor OpenAPI 命令迁移到 schema openapi 子命令(破坏性)
@backstage/theme 0.3.0 Minor 浅色主题前景色与 running 状态色更新以满足 WCAG
@backstage/plugin-catalog / plugin-catalog-react 1.11.0 / 1.6.0 Minor Catalog 页面新增命名空间过滤与列
@backstage/plugin-devtools 系列 0.1.0 Minor 全新 DevTools 插件(前端、后端、公共类型包)
@backstage/plugin-kubernetes / -backend 0.9.0 / 0.11.0 Minor Pod 日志组件;AKS 认证支持;aws-sdk v2→v3
@backstage/plugin-scaffolder-backend 1.14.0 Minor 权限/规则元数据端点;catalog:fetch 支持默认 namespace/kind
@backstage/plugin-permission-node 0.7.8 Minor createPermissionIntegrationRouter 支持多种资源类型

完整的包级更新清单以仓库内 docs/releases/v1.14.0-changelog.md 为准。以下按主题深入展开。

二、ConfigSource:新一代配置源系统

2.1 背景:为什么需要取代 loadConfig

@backstage/config-loader@1.3.0 是本版本最值得关注的底层基础设施变更。它引入了一套全新的配置源(config source)系统来取代旧的 loadConfig 入口,核心动机是让配置来源可组合、可复用、可流式更新——例如从密钥提供方(secret providers)加载配置、按需订阅配置变化,而不再局限于"读文件 + 环境变量"的固定套路。

2.2 默认行为:一行代码加载配置

升级后的默认加载方式通过 ConfigSources 工具类完成:

const source = ConfigSources.default({
  argv: options?.argv,
  remote: options?.remote,
});
const config = await ConfigSources.toConfig(source);
  • ConfigSources.default(...) 会读取默认的 app-config.yaml 与 app-config.local.yaml,以及以 APP_CONFIG_ 为前缀的环境变量;如果传入 --config <path|url> 命令行参数,则会覆盖默认配置文件路径(URL 目标仅在提供 remote 选项时受支持)。
  • ConfigSources.toConfig(source) 将配置源转换为可关闭(closable)的 Config 实例;如果只需一次性读取,可以在拿到配置后立即调用 config.close()。

从源码 packages/config-loader/src/sources/ConfigSources.ts 可以看到 default 的实现:它先通过 defaultForTargets 构建"参数目标"来源,再叠加 EnvConfigSource,最后用 merge 合并为单一来源:

static default(options: ConfigSourcesDefaultOptions): ConfigSource {
  const argSource = this.defaultForTargets({
    ...options,
    targets: this.parseArgs(options.argv),
  });
  const envSource = EnvConfigSource.create({ env: options.env });
  return this.merge([argSource, envSource]);
}

2.3 接口定义与自定义来源

ConfigSource 接口极其精简,只有一个方法:

export interface ConfigSource {
  readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceIterator;
}

在仓库 packages/config-loader/src/sources/types.ts 中,其精确定义为返回异步生成器(AsyncGenerator<{ configs: ConfigSourceData<a href="https://link.gitcode.com/i/be08cde18d58f18277567b9120dbfc94" target="_blank">] }, void, void>)的 readConfigData 方法。由于是生成器,配置源天然支持"持续产出新的配置快照",ConfigSources.toConfig 内部会持续监听生成器的下一次产出并用新值刷新 ObservableConfigProxy(见 [ConfigSources.ts)。

官方推荐用 async generator 实现自定义来源,最简单的示例:

class MyConfigSource implements ConfigSource {
  async *readConfigData() {
    yield {
      config: [
        {
          context: 'example',
          data: { backend: { baseUrl: 'http://localhost' } },
        },
      ],
    };
  }
}

每条 yield 的数据形如 { context, data, path? }:context 用于标识该段配置的来源语境,data 是配置对象本体,path(可选)记录配置来自哪个文件。

2.4 内置来源与配置解析顺序

ConfigSources 还提供了 defaultForTargets、merge、parseArgs 等静态工具,分别负责:

  • parseArgs(argv):解析 --config 参数,自动区分本地路径(type: 'path')与 URL(type: 'url');
  • defaultForTargets(options):为指定目标创建 FileConfigSource 与 RemoteConfigSource 并合并。若无目标参数,则按顺序探测 app-config.yaml → app-config.<env>.yaml(由 BACKSTAGE_ENV 环境变量指定,逗号分隔)→ app-config.local.yaml → app-config.<env>.local.yaml;
  • merge(sources):将多个来源合并为一个(底层是 MergedConfigSource)。

另外,ConfigSourceData 继承自 AppConfig,其 SubstitutionFunc 支持配置值中的 ${MY_ENV_VAR} 环境变量替换语法(默认实现从环境读取并去除空白)。

2.5 SchemaLoader 新增 noUndeclaredProperties 与 CLI --strict

与配置系统配套的还有两项校验能力:

  • SchemaLoader 新增 noUndeclaredProperties 选项,可在校验配置时强制禁止未声明的额外键;
  • @backstage/cli@0.22.7 的 backstage-cli config:check 新增 --strict 选项,会暴露 schema 层面的错误,配合上述选项可实现严格的配置合规检查。

这一组合让"配置漂移"(意外新增或拼错的配置键)能在 CI 阶段被直接拦截。

三、Catalog:命名空间过滤与列

3.1 默认页面行为

@backstage/plugin-catalog@1.11.0 与 @backstage/plugin-catalog-react@1.6.0 同步引入了 entity namespace(实体命名空间)过滤器和列。默认的 Catalog 页面现在会展示命名空间过滤能力,便于在多个命名空间(如不同团队、环境或部署单元)之间快速切换视图。

3.2 自定义 CatalogPage 接入过滤器

如果你维护的是自定义 Catalog 页面,需要在过滤器区域加入 EntityNamespacePicker:

<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>
</CatalogFilterLayout>

EntityNamespacePicker 在源码 plugins/catalog-react/src/components/EntityNamespacePicker/EntityNamespacePicker.tsx 中基于 EntityAutocompletePicker 实现,内部以 name="namespace"、path="metadata.namespace" 作用于实体元数据,并用 EntityNamespaceFilter 完成过滤。它还接收 initiallySelectedNamespaces 属性用于预选命名空间。

3.3 自定义列时加入命名空间列

如果自定义了 CatalogTable 的列配置,需要通过 createNamespaceColumn() 工厂方法补充命名空间列:

createNamespaceColumn(): TableColumn<CatalogTableRow> {
  return {
    title: <EntityTableColumnTitle translationKey="namespace" />,
    field: 'entity.metadata.namespace',
    width: 'auto',
  };
}

该工厂位于 plugins/catalog/src/components/CatalogTable/columns.tsx,它把表格字段映射到 entity.metadata.namespace,与 createNameColumn、createSystemColumn、createOwnerColumn 等同属 columnFactories 集合(通过 CatalogTable.columns 字段暴露),保持列定义风格的统一。

四、DevTools 插件:全新引入的调试套件

v1.14.0 正式引入了 @backstage/plugin-devtools(前端)、@backstage/plugin-devtools-backend(后端)与 @backstage/plugin-devtools-common(公共类型)三个包,为开发者门户提供内置的调试与信息查看能力。

前端插件在 plugins/devtools/src/plugin.ts 中定义:

export const devToolsPlugin = createPlugin({
  id: 'devtools',
  apis: [
    createApiFactory({
      api: devToolsApiRef,
      deps: { discoveryApi: discoveryApiRef, fetchApi: fetchApiRef },
      factory: ({ discoveryApi, fetchApi }) =>
        new DevToolsClient({ discoveryApi, fetchApi }),
    }),
  ],
  routes: { root: rootRouteRef },
});

export const DevToolsPage = devToolsPlugin.provide(
  createRoutableExtension({
    name: 'DevToolsPage',
    component: () =>
      import('./components/DevToolsPage').then(m => m.DevToolsPage),
    mountPoint: rootRouteRef,
  }),
);

它通过 devToolsApiRef 暴露 DevToolsClient(依赖 discoveryApi 与 fetchApi 与后端通信),并以可路由扩展 DevToolsPage 挂载到应用路由。注意该插件还依赖 @backstage/plugin-permission-react 等权限相关包,属于可受权限策略约束的调试工具。接入示例应用中,前端(example-app)与后端(example-backend)均引入了对应依赖(见 changelog 中 example-app@0.2.83、example-backend@0.2.83 的依赖变更段)。

五、Theme 无障碍改进与核心组件修复

5.1 WCAG 对比度修正

@backstage/theme@0.3.0 更新了浅色主题的 primary foreground 与 running 状态指示色以满足 WCAG 标准:

  • 主前景色由 #2E77D0 调整为 #1F5493(更深的蓝色,提升与白色背景的对比度);
  • 同时修正了 Backstage Table 表头的无障碍样式(83b45f9df50)。

若你的应用自定义了主题色,建议参考新色值评估对比度;使用默认主题的应用无需额外操作。

5.2 core-components 相关的无障碍修复

@backstage/core-components@0.13.1 汇总了多项无障碍修复:

  • Table 表头样式无障碍问题;
  • 受控 select 输入在 Tab 导航及键盘 Enter/空格操作下的无障碍问题;
  • Edit Metadata Link 在屏幕阅读器下缺少"在新标签页打开"提示的问题;
  • 侧边栏(Sidebar)点击事件默认纳入分析采集(26cff1a5dfb)。

六、Kubernetes 插件:Pod 日志组件与 AKS 认证

6.1 前端:Pod 日志与重命名

@backstage/plugin-kubernetes@0.9.0 新增了 Pod 日志组件,同时包含两处破坏性变更:

  1. 自定义插件如果使用了 Kubernetes 插件 API 中的组件,需将 kubernetesProxyApi 加入插件 API 列表,例如:

    export const kubernetesPlugin = createPlugin({
      id: 'kubernetes',
      apis: [
        // ...
        createApiFactory({
          api: kubernetesProxyApiRef,
          deps: { kubernetesApi: kubernetesApiRef },
          factory: ({ kubernetesApi }) =>
            new KubernetesProxyClient({ kubernetesApi }),
        }),
      ],
    });
    
  2. KubernetesDrawer 更名为 KubernetesStructuredMetadataTableDrawer:

    // 旧写法
    import { KubernetesDrawer } from "@backstage/plugin-kubernetes"
    // 新写法
    import { KubernetesStructuredMetadataTableDrawer } from "@backstage/plugin-kubernetes"
    

    更名是为了支持除 StructuredMetadataTable 之外更丰富的抽屉内容。

6.2 后端:AKS 认证与 aws-sdk v3

@backstage/plugin-kubernetes-backend@0.11.0 支持通过 labelSelector 限定拉取 Pod 指标(大集群下显著减小响应体),并将 aws-sdk 客户端从 v2 升级到 v3:

  • AKS 支持:集群可配置 authProvider: aks,retrieveObjectsByServiceId 动作会使用请求体中的 auth.aks 值作为 bearer token 与 Kubernetes 鉴权(05f1d74539d);
  • 破坏性变更:AwsIamKubernetesAuthTranslator 不再暴露 awsGetCredentials、getBearerToken、getCredentials、validCredentials 方法且无替代品;
  • 修复了使用客户端侧认证提供方时 Kubernetes 代理端点请求总是返回 500 的问题(a341129b754)。

七、Scaffolder 与权限系统升级

7.1 Scaffolder 后端与通用包

  • plugin-scaffolder-backend@1.14.0:元数据端点现在能同时暴露 template 与 action 两种资源类型的权限和规则;catalog:fetch 动作新增 defaultNamespace 与 defaultKind 参数支持;同时将 vm2 最低版本提升至 3.9.18(安全修复);
  • plugin-scaffolder-common@1.3.0:除原有 scaffolderPermissions 外,新增 scaffolderTemplatePermissions 与 scaffolderActionPermissions 子集导出,按资源类型分组;模板新增 Markdown 文本 blob 输出支持(82e10a6939c);
  • plugin-scaffolder-react@1.4.0:同样获得 Markdown 文本输出能力,并优化了 scaffolder/next 的按钮体验(Create 按钮内边距、OngoingTask 的 Cancel/Start Over 按钮栏、ContextMenu 的显示/隐藏按钮栏选项)。

7.2 permission-node 多资源类型路由

@backstage/plugin-permission-node@0.7.8 的 createPermissionIntegrationRouter 现在接受多资源类型的权限与规则,例如:

createPermissionIntegrationRouter({
  resources: [
    {
      resourceType: 'resourceType-1',
      permissions: permissionsResourceType1,
      rules: rulesResourceType1,
    },
    {
      resourceType: 'resourceType-2',
      permissions: permissionsResourceType2,
      rules: rulesResourceType2,
    },
  ],
});

这意味着单个权限集成路由即可统一承载多个资源类型的授权规则。

八、OpenAPI 工具链:repo-tools 子命令迁移

@backstage/repo-tools@0.3.0 对 OpenAPI 相关命令做了破坏性重组,所有命令收敛到 schema openapi 子命令下:

# 旧命令
yarn backstage-repo-tools schema:openapi:verify
# 新命令
yarn backstage-repo-tools schema openapi verify

同时,生成的 OpenAPI 文件统一命名为 .generated.ts,并在文件头部追加警告注释,明确提示"请勿手工编辑"。受此影响:

  • @backstage/backend-openapi-utils@0.0.2 相应调整了 README 与生成输出扩展名,并改用包含行号引用的 permalink(fe16bd39e83);
  • @backstage/plugin-search-backend@1.3.1 与 @backstage/plugin-todo-backend@0.1.42 在本版本中接入 OpenAPI 3.0 规范,采用 schema-first 模式约束路由。

九、其他值得关注的变更

9.1 分析与认证

  • core-app-api@1.8.0:analytics 的 navigate 事件现在会把路由参数(route parameters)作为事件属性一并上报,便于按参数维度分析页面导航行为;
  • Azure auth provider:修复了同一资源下多 scope 获取访问令牌失败的问题(b645d70034a);
  • plugin-auth-backend@0.18.3:新增基于数据库的持久化会话存储(3ffcdac7d07),为会话提供了跨重启的持久能力。

9.2 Discovery 与集成

  • FrontendHostDiscovery(core-app-api)与 HostDiscovery(backend-common)新增,前者取代旧名称 SingleHostDiscovery(仅因命名弃用,功能等同),提供基于配置的 discovery 实现;
  • GitHub 多组织实体提供方:GithubMultiOrgEntityProvider 支持事件(events)驱动刷新,且传入自定义 teamTransformer 时会完整覆盖默认转换行为(破坏性);queryWithPaging 修复了超过 1000 个仓库的组织出现的 GitHub 次级限流问题(改为每秒一次请求);
  • GitLab:新增 gitlab:group:ensureExists scaffolder 动作,并修复 4 个 GitLab 动作的输入 schema 校验问题;修正了嵌套子分组 workspace 的场景;
  • AWS SQS 事件模块:允许配置 endpoint(便于配合 localstack 测试),并统一 @aws-sdk v3 版本;
  • badges-backend:改为从 TokenManager 获取令牌(而非解析请求头),从而支持关闭 authMiddleware 公开暴露 badges 端点,并内置默认关闭的端点混淆(obfuscation)保护;createRouter 现在必须传入 tokenManager、logger、identityApi(破坏性)。

9.3 其他插件修复

  • Org 插件:EntityMembersListCard 新增 showAggregateMembersToggle 属性,可在查看 Group 时切换"直接成员/聚合成员"展示:
    // 在 packages/app/src/components/catalog/EntityPage.tsx 中
    const groupPage = (
      // ...
      <EntityMembersListCard showAggregateMembersToggle />
      // ...
    );
    
  • Search:搜索页新增关闭按钮并优化输入框;<SearchBar/> 支持通过 InputProps 覆盖默认键;SearchPagination 在变更每页条数时自动重置游标;修复 URL 编码变化导致的 404;
  • Elasticsearch 搜索模块:升级 aws-sdk v3 并新增 OpenSearch Serverless 支持;
  • TechDocs:恢复 TechDocs 导航中尾随斜杠(trailing slash)的支持;
  • Jenkins:rebuild 改用 Jenkins API replay(支持带必填参数的任务),并在 CI/CD 表格操作列增加"在 Jenkins 查看构建"链接;
  • 其他:Azure DevOps 构建运行支持逗号分隔的多个构建拆分请求;Octopus Deploy 支持 space 前缀(如 Spaces-1/Projects-102);app-defaults 新增 kind:resource 系统图标(useApp().getSystemIcon('kind:resource'));tech-insights 支持自定义 check 描述渲染;@backstage/cli@0.22.7 弃用 React 16。

十、升级建议与破坏性变更清单

升级到 v1.14.0 前,请重点核对以下破坏性变更:

  1. repo-tools OpenAPI 命令迁移:schema:openapi:* 一律改为 schema openapi *;生成文件更名为 .generated.ts 并禁止手工编辑;
  2. badges-backend createRouter 签名:必须传入 tokenManager、logger、identityApi;
  3. Kubernetes 插件:KubernetesDrawer → KubernetesStructuredMetadataTableDrawer;使用其 API 组件需显式注册 kubernetesProxyApi;AwsIamKubernetesAuthTranslator 移除 4 个方法;
  4. AWS 目录提供方:AwsOrganizationCloudAccountProcessor.fromConfig 改为返回 Promise;
  5. GithubMultiOrgEntityProvider:自定义 teamTransformer 将完整覆盖默认行为;
  6. 搜索页 UI:移除了包裹 SearchBar 的 Material UI Paper,自定义应用需同步调整;
  7. React 16 弃用:@backstage/cli 开始标记 React 16 弃用,建议规划升级到 React 17/18。

其余功能(ConfigSource、命名空间过滤、DevTools、AKS、WCAG 配色等)均为向后兼容的新增能力,可平滑升级后按需启用。建议升级后在 CI 中启用 backstage-cli config:check --strict,提前暴露配置 schema 层面的不一致。

登录后查看全文
backstage