企业官网建设流程全解析

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 修复与令人兴奋的新增能力。总体来看，本次版本围绕以下主线展开：

以下各节将逐项展开说明。

BREAKING：OpenAPI 工具命令重组与.generated.ts生成物

命令统一收敛到schema openapi子命令

v1.14.0 对@backstage/repo-tools（0.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-utils（0.0.2）也同步调整了 README，并对参数嵌套 schema 的解析做了修正，改为引用中央 schema。

对于维护者而言，升级时需要：

1. 将 CI 中所有schema:openapi:*旧命令改为schema openapi *新语法；
2. 重新生成客户端/服务端文件，确认.generated.ts文件被纳入忽略/区分规则；
3. 清理对旧文件名的 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-backend（0.11.0）在本版本也有一批重要更新：

• 新增authProvider: aks：集群配置为authProvider: aks时，retrieveObjectsByServiceId动作会从 Azure 获取 AKS 访问令牌，并在请求体中通过auth.aks以 bearer token 形式认证（changelog commit05f1d74539d/c7bad1005ba）；
• Pod 指标支持labelSelector限制：允许按标签选择器拉取 Pod 指标，显著缩小大规模集群下的响应体积（commitf4114f02d49）；
• 修复代理端点 500 错误：客户端侧鉴权配置的集群在代理请求时此前总会失败的问题已修复（commita341129b754）。

DEPRECATION：React 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-devtools（0.1.0），由 @awanlin 贡献。它把关于 Backstage 安装实例的有用信息直接呈现在前端，帮助排障、审计与理解安装现状。该插件被视为未来更多运维（ops）类功能的基础。

根据插件官方文档 plugins/devtools/README.md，DevTools 开箱即带两个标签页，另有若干可选标签页：

Info 标签页的版本报告机制

Info 标签页中"Backstage 版本"的准确展示依赖一个前提：运行实例根目录必须存在backstage.json文件。发布说明与插件文档都特别提示，若使用 Docker 部署，需要修改 Dockerfile 确保该文件被复制进镜像的WORKDIR：

WORKDIR /app # This switches many Node.js dependencies to production mode. ENV NODE_ENV=production # Then copy the rest of the backend bundle, along with any other files we might want (including backstage.json). COPY --chown=node: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 path="info" title="Info"> <InfoContent /> </DevToolsLayout.Route> <DevToolsLayout.Route path="config" title="Config"> <ConfigContent /> </DevToolsLayout.Route> <DevToolsLayout.Route path="external-dependencies" title="External Dependencies" > <ExternalDependenciesContent /> </DevToolsLayout.Route> </DevToolsLayout> ); }; export const customDevToolsPage = <DevToolsPage />;

随后在 packages/app/src/App.tsx 中引入并将路由挂载到/devtools路径下。后端部分则需先安装并配置@backstage/plugin-devtools-backend（0.1.0），其实现位于 plugins/devtools-backend。

底层迁移：AWS SDK v3 与AwsIamKubernetesAuthTranslator

v1.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-elasticsearch（1.3.0）在此次升级中同时获得了OpenSearch Serverless 支持（commit3d72bdb41c7），AWS 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()); }

从该实现可以推断两点实践要点：

1. 会话表需自行管理：creatabletable: false表示后端不会自动建表，升级时需确保数据库中已存在 express-session 所需的会话表（可参考connect-session-knex的 schema）；
2. HTTPS 环境自动启用安全 Cookie：cookie.secure会根据authUrl是否以https开头自动设置，生产环境务必使用 HTTPS 访问 auth 服务。

其他 Auth 修复

@backstage/plugin-auth-backend（0.18.3）同时修复了部分请求错误的抛出方式（commit7c116bcac7f），@backstage/core-app-api（1.8.0）修复了 Azure auth provider 对单资源多 scope 获取访问令牌的 Bug（commitb645d70034a）。此外，HostDiscovery作为新名称被引入，用于取代因命名原因被弃用的SingleHostDiscovery（backend-common 0.18.5，commit42d817e76ab）。

软件模板：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 明确定义了该结构：

• text：Markdown text blobs列表，即模板产出的文本数据；
• 每个文本项包含title（用户友好的显示名）、icon（UI 图标键）、content（"The text blob to display in the UI, rendered as Markdown"，即以 Markdown 渲染的文本内容），以及可选的if条件——当条件求值为false/undefined/null/""/0/[]时，该文本被排除。

schema 中的示例为"**hey** _I'm_ Markdown"，说明 content 中可以使用 Markdown 语法（加粗、斜体等）。

前端渲染链路

从前端实现看，scaffolder-react的 DefaultTemplateOutputs.tsx 负责渲染任务输出：它会从output.text中选出标有default的文本项（无 default 时取第一项）进行展示，文本渲染组件使用@backstage/core-components中的MarkdownContent。整套链路验证了"模板产出 Markdown → 任务输出 → UI 以 Markdown 渲染"的闭环。

权限元数据完善

配套地，@backstage/plugin-scaffolder-common（1.3.0）现在额外导出scaffolderTemplatePermissions与scaffolderActionPermissions（按资源类型拆分的权限子集，commit67115f532b8），scaffolder-backend（1.14.0）的元数据端点也正确暴露两类资源类型的权限与规则，便于权限策略按需引用。

Scaffolder 其他改进

• catalog:fetch动作支持defaultNamespace与defaultKind参数（commita73b3c0b097）；
• scaffolder/next的按钮 UX 优化：Stepper 中 "Create" 按钮增加内边距，OngoingTask组件新增包含 "Cancel" 与 "Start Over" 的按钮栏（commitad1a1429de4）；
• @backstage/plugin-scaffolder-backend-module-gitlab（0.2.0）新增gitlab:group:ensureExists动作，并修复多个 gitlab 动作的输入 schema 校验问题。

配置加载体系重构：ConfigSource 可扩展模型

从loadConfig到ConfigSource

v1.14.0 最重要的架构级改动之一：@backstage/config-loader（1.3.0）引入了一套全新的config source（配置源）体系来取代旧的loadConfig（changelog 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的完整语义：

1. 命令行参数解析（parseArgs）：通过--config <path|url>传入的配置目标会被解析为path或url类型（ConfigSources.ts）；
2. 默认文件回退（defaultForTargets）：未显式指定目标时，按app-config.yaml→app-config.${env}.yaml（env 来自BACKSTAGE_ENV环境变量，逗号分隔）→app-config.local.yaml→app-config.${env}.local.yaml的顺序加载文件（ConfigSources.ts）；
3. 环境变量源：EnvConfigSource读取以APP_CONFIG_前缀的环境变量；
4. 合并与观测：通过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.ts）；
• SchemaLoader新增noUndeclaredProperties选项，可在校验配置时强制禁止未声明的键（changelog commit473db605a4f）；
• backstage-cli config:check新增--strict选项，可让 schema 错误直接暴露（@backstage/cli0.22.7）；
• 后端应用的configServiceFactory已切换为使用ConfigSources加载配置（backend-app-api 0.4.3，commitcf13b482f9e）。

Catalog：namespace 过滤、性能优化与周边修复

新增实体 namespace 过滤与列

@backstage/plugin-catalog（1.11.0）与@backstage/plugin-catalog-react（1.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> </CatalogFilterLayout>

EntityNamespacePicker的实现位于 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-github（0.3.0）为GithubMultiOrgEntityProvider实现事件支持；破坏性变更：传入自定义teamTransformer时将完全覆盖默认转换行为；同时修复了 GitHub 组织超过 1000 个仓库时queryWithPaging触发二级限流的问题（改为每秒一个请求，commit78bb674a713）；
• @backstage/plugin-catalog-backend-module-aws（0.2.0）中AwsOrganizationCloudAccountProcessor.fromConfig现在返回 Promise 而非实例（BREAKING）；
• @backstage/app-defaults（1.3.1）新增 resource 实体的系统图标，可通过useApp().getSystemIcon('kind:resource')获取。

安全修复：Scaffolder 依赖的 vm2 漏洞（CVE-2023-32314）

v1.14.0 通过自动化安全流程修复了 Scaffolder 插件所依赖的vm2包中的一个安全漏洞（CVE-2023-32314）。官方给出的处理方式很务实：

修复版本的vm2已经包含在 Scaffolder 插件所需的版本范围内，因此采纳者可以在不升级 Backstage 的前提下，通过常规安全流程单独升级vm2依赖来修复该漏洞。

从 changelog 可以看到，@backstage/plugin-scaffolder-backend（1.14.0）在补丁版本中两次提升vm2的最低版本要求：先到 3.9.17，再到 3.9.18（commitsd20c87966a4、1a48b84901c）。升级 Backstage 到 v1.14.0 同样会将其纳入依赖范围。

升级路径与建议

官方建议所有 Backstage 项目尽快升级到最新版本。结合本节内容，升级到 v1.14.0 的完整检查清单如下：

1. 升级依赖：以yarn backstage-cli versions:bump（或等价方式）将@backstage/*包统一提升到 v1.14.0 对应版本，重点核对 changelog 中列出的所有包版本（见下文速查表）；
2. 处理 OpenAPI 命令迁移：将 CI/本地脚本中的schema:openapi:*命令改为schema openapi *，重新生成客户端与服务端文件；
3. 处理 Kubernetes 插件变更：自定义插件若引用了KubernetesDrawer，改为KubernetesStructuredMetadataTableDrawer；若使用代理相关能力，将kubernetesProxyApi加入插件 API 列表；
4. 检查 AWS 鉴权代码：移除对AwsIamKubernetesAuthTranslator已删除四个方法的调用；
5. React 版本核对：确认应用不依赖 React 16 的 API，尽早升级到 17+ 以消除 CLI 警告；
6. Auth 会话存储：为使用 session 的 provider 准备数据库会话表，配置auth.session.secret；
7. 验证配置加载：如使用了--config远程 URL，需确认开启了remote选项；如配置校验依赖严格模式，可启用config:check --strict；
8. 处理安全项：确保vm2不低于 3.9.18；
9. 可选采用新能力：接入 DevTools 插件、为模板增加 Markdown 输出、启用 Catalog namespace 过滤等。

主要包版本速查表（v1.14.0）

总结

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