Backstage v1.14.0 版本解读:ConfigSource 配置源体系、Catalog 命名空间过滤与 DevTools 插件
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 日志组件,同时包含两处破坏性变更:
-
自定义插件如果使用了 Kubernetes 插件 API 中的组件,需将
kubernetesProxyApi加入插件 API 列表,例如:export const kubernetesPlugin = createPlugin({ id: 'kubernetes', apis: [ // ... createApiFactory({ api: kubernetesProxyApiRef, deps: { kubernetesApi: kubernetesApiRef }, factory: ({ kubernetesApi }) => new KubernetesProxyClient({ kubernetesApi }), }), ], }); -
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:ensureExistsscaffolder 动作,并修复 4 个 GitLab 动作的输入 schema 校验问题;修正了嵌套子分组 workspace 的场景; - AWS SQS 事件模块:允许配置 endpoint(便于配合 localstack 测试),并统一
@aws-sdkv3 版本; - 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 前,请重点核对以下破坏性变更:
- repo-tools OpenAPI 命令迁移:
schema:openapi:*一律改为schema openapi *;生成文件更名为.generated.ts并禁止手工编辑; - badges-backend
createRouter签名:必须传入tokenManager、logger、identityApi; - Kubernetes 插件:
KubernetesDrawer→KubernetesStructuredMetadataTableDrawer;使用其 API 组件需显式注册kubernetesProxyApi;AwsIamKubernetesAuthTranslator移除 4 个方法; - AWS 目录提供方:
AwsOrganizationCloudAccountProcessor.fromConfig改为返回 Promise; - GithubMultiOrgEntityProvider:自定义
teamTransformer将完整覆盖默认行为; - 搜索页 UI:移除了包裹 SearchBar 的 Material UI Paper,自定义应用需同步调整;
- React 16 弃用:
@backstage/cli开始标记 React 16 弃用,建议规划升级到 React 17/18。
其余功能(ConfigSource、命名空间过滤、DevTools、AKS、WCAG 配色等)均为向后兼容的新增能力,可平滑升级后按需启用。建议升级后在 CI 中启用 backstage-cli config:check --strict,提前暴露配置 schema 层面的不一致。