Backstage 后端启动连接优化解析:PostgreSQL 多插件共享数据库时如何复用数据库存在性检查

原创2026-09-08 21:33:401,714 阅读
文章标签:开发者门户前端后端插件系统代码生成文档研发协作云原生

Backstage 后端启动连接优化解析:PostgreSQL 多插件共享数据库时如何复用数据库存在性检查

本篇技术分析聚焦于 Backstage 仓库中 .changeset/quick-databases-share.md 所记录的一项 @backstage/backend-defaults patch 变更:当多个插件共享同一个 PostgreSQL 数据库时,通过复用数据库存在性检查来削减后端启动阶段的连接数量。读完本文,你将理解 Backstage 后端数据库初始化的完整链路、ensureExists / ensureSchemaExists / pluginDivisionMode 等配置项的实际作用,以及该优化在源码与测试中的具体实现,可直接用于排查或优化自建 Backstage 实例的 PostgreSQL 启动连接数。

一次 patch 变更背后的启动连接问题

changeset 文件 .changeset/quick-databases-share.md 中记录的变更内容非常简短:

'@backstage/backend-defaults': patch
Reduced PostgreSQL startup connections when multiple plugins share a database by reusing the database existence check.

对应到版本记录,packages/backend-defaults/CHANGELOG.md 中该变更以提交哈希 61449ae 被记录在同一 patch 版本中。要理解这条优化,需要先弄清 Backstage 后端为每个插件初始化 PostgreSQL 数据库时的完整流程。

Backstage 插件数据库初始化:从配置到连接的调用链

在 Backstage 的新后端系统中,数据库连接由 @backstage/backend-defaults 包中的 PgConnector(PostgreSQL 连接器)统一管理。核心入口是 postgres.ts 中的 getClient(pluginId) 方法:

async getClient(pluginId: string, _deps): Promise<Knex> {
  const pluginDbConfig = computePgPluginConfig(this.config, pluginId, this.prefix);

  if (pluginDbConfig.databaseName && pluginDbConfig.ensureExists) {
    try {
      await this.ensureDatabase(pluginDbConfig.databaseName);
    } catch (error) {
      throw new Error(
        `Failed to connect to the database to make sure that '${pluginDbConfig.databaseName}' exists, ${error}`,
      );
    }
  }
  // ... pluginDivisionMode === 'schema' 时还会执行 ensurePgSchema
  const client = createPgDatabaseClient(this.config, mergeDatabaseConfig(
    pluginDbConfig.knexConfig,
    pluginDbConfig.databaseClientOverrides,
  ));
  return client;
}

整个调用链可以概括为:

  1. computePgPluginConfig() 根据全局配置与插件级配置计算出该插件的数据库配置(客户端类型、连接串、databaseName、ensureExists 等);
  2. 若 ensureExists 为真,则先调用 ensureDatabase() 通过管理员连接确认(必要时创建)目标数据库;
  3. 最后用 createPgDatabaseClient() 为插件建立真正的业务连接。

ensureExists 的默认行为与配置层级

在 config.d.ts 中,ensureExists 的语义被明确定义为:"是否确保给定数据库存在(不存在则创建),未指定时默认为 true"。而 postgres.ts 中的解析逻辑表明,插件级配置会覆盖全局配置:

const baseEnsureExists = config.getOptionalBoolean('ensureExists') ?? true;
const ensureExists =
  config.getOptionalBoolean(`${pluginPath(pluginId)}.ensureExists`) ?? baseEnsureExists;

也就是说,只要没有显式关闭,每个插件在启动时都会先发起一次"数据库存在性检查"。

插件数据库的命名与两种划分模式

computePgPluginConfig 中关于 databaseName 的推导决定了检查的目标:

if (pluginDivisionMode === 'schema') {
  databaseName = connectionDatabaseName; // 使用共享库
} else {
  databaseName = connectionDatabaseName ?? `${prefix}${pluginId}`; // 默认 backstage_plugin_<插件ID>
}

pluginDivisionMode 支持两种取值(config.d.ts):

取值 含义 数据库名来源
database(默认) 每个插件拥有独立的数据库 未显式指定时自动生成为 backstage_plugin_<插件ID>(prefix 默认可覆盖)
schema 所有插件共享同一个数据库,各自拥有独立 schema 使用 base 连接中显式配置的 database,并将 searchPath 设置为插件 ID

注意 postgres.ts 中的关键约束:当 pluginDivisionMode 不是 schema 时,base 连接里的 database 字段会被 omit 掉——因为只有在 schema 模式下插件才可能共享一个显式指定的数据库。

优化前的痛点:每个插件各自发起一次存在性检查

在未优化的实现中,若多个插件配置了同一个 databaseName(典型场景是 pluginDivisionMode: 'schema' 下所有插件共享一个数据库,或插件级配置把 connection.database 指向同一个库),每个插件的 getClient() 都会独立执行一次完整的存在性检查流程:

  • 各自通过管理员连接查询 pg_database 系统表;
  • 各自执行 CREATE DATABASE(当库不存在时,由 ensurePgDatabase 触发,见 postgres.ts)。

这意味着后端启动时,数据库上的管理员连接数会随插件数量线性增长;如果插件并发初始化,还会出现对同一数据库的重复且相互竞争的存在性检查,产生不必要的连接建立与 DDL 操作。

优化核心:databaseEnsureCache 按数据库名复用检查结果

本次 patch 的改动集中在 PgConnector 中引入的一个成员:

private readonly databaseEnsureCache = new Map<string, Promise<void>>();

配合重写后的 ensureDatabase 方法:

private async ensureDatabase(databaseName: string): Promise<void> {
  let promise = this.databaseEnsureCache.get(databaseName);
  if (!promise) {
    promise = this.customEnsureDatabaseExists
      ? this.customEnsureDatabaseExists(this.config, databaseName)
      : retryPgAdminOperation(() =>
          ddlLimiter(() =>
            this.runAdminOperation(this.databaseAdminPool, admin =>
              ensurePgDatabase(admin, databaseName),
            ),
          ),
        );
    this.databaseEnsureCache.set(databaseName, promise);
  }

  try {
    await promise;
  } catch (error) {
    if (this.databaseEnsureCache.get(databaseName) === promise) {
      this.databaseEnsureCache.delete(databaseName);
    }
    throw error;
  }
}

这段实现的要点可以拆解为三点:

  1. 以数据库名为键缓存 Promise:同一数据库的检查只发起一次,后续插件直接 await 同一个 Promise。由于 Promise 天然支持多个等待者,并发初始化同一库的多个插件会共享同一次检查;
  2. 失败时从缓存中移除:若检查抛错,缓存中的 Promise 会被删除,这样后续插件会重新发起检查(而不是永远复用失败结果),并抛出带数据库名的清晰错误信息;
  3. 复用点位于 getClient 与 ensureDatabase 之间:getClient 每次调用仍会走 ensureDatabase(databaseName),但查询缓存命中后不再建立新的管理员连接。

配套机制:管理员连接池、DDL 串行化与失败重试

本次优化并非孤立改动,它与连接器内既有的三套机制配合,共同决定了启动阶段的连接行为:

PgAdminPool:单管理员客户端 + 空闲自动销毁

PgAdminPool 是一个针对管理员连接的轻量池:同一时刻只维护一个 Knex 客户端实例(this.client),所有检查操作复用它;操作结束后通过 scheduleIdleDestroy() 在空闲超过 adminPoolIdleTimeoutMillis(构造时传入,默认 10 秒)后自动销毁。这保证数据库存在性检查不再"用完即弃、检查一次连一次",而是长期复用单个管理连接。

同时,runAdminOperation 在操作失败时会调用 pool.invalidate() 主动销毁可能处于异常状态的客户端,避免复用脏连接。

ddlLimiter:DDL 全局串行化

文件顶部定义了 const ddlLimiter = limiterFactory(1);(postgres.ts),将所有 CREATE DATABASE / CREATE SCHEMA 等 DDL 操作限制为同一时刻最多一个。这避免了多个插件并发执行 DDL 时的锁竞争与死锁风险。

retryPgAdminOperation:3 次重试 + 100ms 退避

async function retryPgAdminOperation(operation) {
  const maxAttempts = 3;
  for (let attempt = 1; ; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (attempt >= maxAttempts) throw error;
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  }
}

源码注释指出,管理员连接池理论上不应出现连接获取超时,但为防御 knex 等依赖的潜在问题,初始设置阶段仍采用小超时 + 多次重试的策略(postgres.ts)。

测试验证:三种典型场景全部覆盖

该优化的行为在 postgres.test.ts 中有完整的测试佐证:

  • 共享检查测试:配置 plugin1 与 plugin2 指向同一个 shared 数据库,并发调用 getClient,断言 ensureDatabaseExists 只被调用 1 次——这正是本次优化的核心行为;
  • 失败重试测试:第一次检查失败后,plugin2 会重新发起检查(共调用 2 次),验证了失败缓存清理逻辑;
  • 管理员客户端共享测试:两个不同数据库的检查共享同一个 createAdminClient(调用 1 次、查询 2 次、最终销毁 1 次),证明 PgAdminPool 的复用生效;
  • 此外还有针对 schema 划分模式下管理员客户端复用的测试(postgres.test.ts),覆盖 CREATE SCHEMA IF NOT EXISTS ?? 的串行执行。

配置建议与适用前提

要最大化该优化带来的收益,结合上述机制可以从两个方向入手:

1. 让插件确实共享同一数据库名(优化生效的前提)。两种典型做法:

  • 使用 pluginDivisionMode: 'schema',所有插件共用 base 连接中指定的数据库;
  • 或多个插件在各自插件级配置中显式将 connection.database 指向同一个库(这正是测试用例所模拟的场景)。

2. 按需调整 ensureExists 行为。ensureExists 与 ensureSchemaExists 都支持全局与插件级两层配置(见 config.d.ts):

backend:
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: 5432
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      database: backstage_shared   # pluginDivisionMode: schema 时的共享库
    ensureExists: true             # 默认即 true;不存在则创建
    ensureSchemaExists: false      # 默认 false;pg + schema 模式下方可生效
    pluginDivisionMode: schema     # 可选 database | schema,默认 database
    plugin:
      catalog:
        ensureExists: true         # 插件级覆盖全局配置

适用前提说明:

  • 该优化位于 @backstage/backend-defaults(当前仓库中该包版本为 0.17.9-next.0 之前的 patch 系列,见 CHANGELOG.md),升级到包含提交 61449ae 的版本后自动生效,无需额外配置;
  • 相关能力(ensureExists / ensureSchemaExists / pluginDivisionMode)目前仅对 pg 客户端完整支持;MySQL 驱动仅支持 database 模式,配置其他模式会直接报错(见 mysql.ts);
  • 本地开发默认使用 SQLite(见 app-config.yaml),该优化主要影响生产环境的 PostgreSQL 部署。

小结

.changeset/quick-databases-share.md 这条看似一行字的 patch 记录,实际对应了 Backstage 后端数据库初始化链路中的一处务实优化:通过 databaseEnsureCache 按数据库名复用存在性检查的 Promise、借助 PgAdminPool 复用管理员连接并空闲回收、配合 ddlLimiter 串行化 DDL 与失败重试机制,将"多插件共享数据库"场景下的启动连接数从"每插件一查"收敛为"每库一查"。对于在 schema 划分模式下运行大量插件的生产环境,这能显著降低 PostgreSQL 在启动瞬间的连接峰值,也体现了 Backstage 后端系统在资源节俭上的持续演进。

登录后查看全文
backstage