Backstage 插件数据库配置指南基于 DatabaseManager 的多库、多客户端持久化实战【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文是一份面向生产环境的 Backstage 数据库配置实战指南。文章围绕 Backstage 的DatabaseManager由backstage/backend-common/ 新版后端系统中的backstage/backend-defaults提供展开讲解如何在app-config.yaml中按插件粒度per plugin配置数据库客户端与连接信息覆盖 SQLite 内存库、PostgreSQL、自定义库名前缀、基础设施即代码IaC下的随机凭据、PostgreSQL 与 SQLite 混用等典型场景。读完本文你将掌握 Backstage 数据库的完整配置体系、底层实现原理以及数据库权限与迁移回滚等运维要点。Backstage 数据库管理的核心机制Backstage 的后端插件各自维护自己的数据库连接这一能力由DatabaseManager统一提供。它的设计要点如下按插件隔离每个插件通过插件 IDpluginId获得独立的数据库连接与库名互不干扰。默认自动建库未显式指定库名时Backstage 会自动为每个插件创建以backstage_plugin_为前缀的数据库例如auth插件对应backstage_plugin_auth、catalog插件对应backstage_plugin_catalog。基线与插件覆盖backend.database下定义全局默认客户端与连接backend.database.plugin.pluginId下定义插件级覆盖。同类型客户端会继承基线配置并做增量合并不同类型客户端则完全以插件配置为准。从源码看DatabaseManager.ts 中DatabaseManager.fromConfig读取backend.database配置块并注册了五种连接器Connectorpg: new PgConnector(databaseConfig, prefix, schemaPrefix), sqlite3: new Sqlite3Connector(databaseConfig), better-sqlite3: new Sqlite3Connector(databaseConfig), mysql: new MysqlConnector(databaseConfig, prefix), mysql2: new MysqlConnector(databaseConfig, prefix),其中prefix取自databaseConfig.getOptionalString(prefix)缺省值为backstage_plugin_schemaPrefix缺省为空字符串且仅允许字母、数字、下划线等安全字符。插件请求连接时forPlugin(pluginId)会通过getClientType解析出该插件实际使用的客户端类型——优先取plugin.pluginId.client否则回退到基线的client若连接器不存在则抛出Unsupported database client type ...错误。此外DatabaseManager会为每个插件缓存 Knex 客户端databaseCache并启动每 60 秒一次的保活循环执行select 1连接在应用关闭时通过rootLifecycle的 shutdown 钩子统一销毁。前置条件安装数据库驱动在使用前请确保backend包中安装了对应的数据库驱动。不同客户端需要不同的驱动包客户端类型驱动包安装命令PostgreSQLpgyarn --cwd packages/backend add pgSQLite 3better-sqlite3yarn --cwd packages/backend add better-sqlite3yarn --cwd packages/backend add pgyarn --cwd packages/backend add better-sqlite3从运维角度讲只需为实际使用的客户端安装驱动即可。如果你打算同时使用 PostgreSQL 和 SQLite两个驱动可以一起安装。注意仓库根目录的默认配置 app-config.yaml 使用client: better-sqlite3与connection: :memory:因此开箱即用的开发环境依赖better-sqlite3驱动。配置文件结构与覆盖规则数据库配置统一放在backend.database下插件级配置放在backend.database.plugin.pluginId下。例如catalog插件的pluginId就是catalog其专属配置块为plugin.catalog。覆盖规则与源码computePgPluginConfig的行为一致插件未指定client时沿用基线client此时插件连接配置与基线连接配置合并插件值优先。插件指定了与基线不同的client时插件连接配置原样使用不再继承基线的连接配置。数据库名的解析顺序以 PostgreSQL 为例见 postgres.ts若插件连接配置中显式给出connection.database则使用该名称否则使用自动生成名${prefix}${pluginId}即backstage_plugin_pluginId。其中prefix通过backend.database.prefix配置可满足多个部署共享同一个数据库实例/集群的场景。典型配置示例以下示例均来自官方指南原文可直接套用到你的app-config.yaml或等价的环境配置覆盖文件中。1. 最小化内存配置全插件使用 SQLite 内存库适用于测试或其他不需要持久化的场景backend: database: client: better-sqlite3 connection: :memory:这也是仓库根目录 app-config.yaml 中默认使用的数据库配置。从 sqlite3.ts 的源码可以看到SQLite 连接器会把字符串形式的connection规范化为{ filename: connection }对象并自动补上useNullAsDefault: true同时每个连接创建成功后都会执行PRAGMA foreign_keys ON以启用外键约束。在 watch 模式下通过backstage-cli package start启动内存库还会借助DevDataStore在热重载之间保存/恢复数据库状态。2. PostgreSQL全插件使用 PGauth插件自定义库名backend: database: client: pg connection: host: some.example-pg-instance.tld user: postgres password: password port: 5432 plugin: auth: connection: database: pg_auth_set_by_user基线连接中的host、user、password、port会被所有插件继承auth插件额外指定了database: pg_auth_set_by_user因此它不再使用自动生成的backstage_plugin_auth而catalog等其他插件仍使用backstage_plugin_catalog等自动库名。3. 自定义库名前缀当多个部署共享同一个数据库实例/集群时可以通过prefix让不同部署使用不同前缀的库名避免冲突backend: database: client: pg connection: host: some.example-pg-instance.tld user: postgres password: password port: 5432 prefix: example_prefix_此时auth、catalog插件将分别使用名为example_prefix_auth、example_prefix_catalog的数据库。4. 按插件配置连接适配 IaC 随机凭据与库名在 Terraform、AWS CloudFormation 等基础设施即代码IaC环境中数据库凭据可能随机生成也可能无权创建新库或无法控制库名。此时可以为每个插件单独配置完整连接信息backend: database: client: pg connection: postgresql://some.example-pg-instance.tld:5432 plugin: auth: connection: postgresql://fort:knoxsome.example-pg-instance.tld:5432/unwitting_fox_jumps catalog: connection: postgresql://bank:reservesome.example-pg-instance.tld:5432/shuffle_ransack_playback注意连接既支持对象形式host/user/password/port也支持postgresql://形式的连接字符串。源码中 getPgConnectionConfig 会借助pg-connection-string解析字符串形式的连接。5. PostgreSQL 与 SQLite 3 混用下面的配置中除auth插件使用better-sqlite3内存库外其余插件全部使用 PostgreSQL。由于auth的客户端类型与基线不同其连接配置被原样使用不会继承基线的 PostgreSQL 连接backend: database: client: pg connection: postgresql://foo:barsome.example-pg-instance.tld:5432 plugin: auth: client: better-sqlite3 connection: :memory:配置项速查来自 schema 定义结合 config.d.ts 的配置结构声明backend.database支持的关键字段如下字段类型/取值说明clientbetter-sqlite3 \| sqlite3 \| pg \| embedded-postgres默认数据库客户端connection字符串或对象基础连接配置支持普通连接以及type: azure、type: cloudsql、type: rds等云托管 PostgreSQL 特殊连接prefix字符串自动生成库名的前缀默认backstage_plugin_schemaPrefix字符串使用pluginDivisionMode: schema时 schema 名的前缀默认ensureExists布尔是否自动创建不存在的库默认trueensureSchemaExists布尔是否自动创建不存在的 schema默认false仅pgpluginDivisionMode: schema支持pluginDivisionModedatabase \| schema插件数据库划分方式默认database每插件一库schema表示在同一个库中为每个插件划分独立 schema仅pg支持role字符串PostgreSQL 中新建 schema 的归属角色knexConfig对象透传给 Knex 的任意配置如debug、asyncStackTraces插件级knexConfig会递归合并进基线skipMigrations布尔跳过数据库迁移支持插件级覆盖plugin.pluginId.*同上插件级覆盖client、connection、ensureExists、ensureSchemaExists、knexConfig、role、skipMigrations检查数据库自动建库与最小权限原则DatabaseManager会在插件首次获取连接时尝试创建不存在的数据库。以 PostgreSQL 为例postgres.ts 中的ensurePgDatabase会先查询pg_database判断库是否存在不存在时执行CREATE DATABASE管理操作通过独立的 admin 连接池串行执行DDL 并发限制为 1并带有最多 3 次、间隔 100ms 的重试。SQLite 连接器则会在使用磁盘存储时自动创建目录。因此需要注意如果基线凭据没有建库权限、你在plugin.pluginId下设置了独立凭据那么这些库必须预先手动创建好——服务启动后只能使用它们无法替你创建。由于 Backstage 需要查询数据库是否存在你需要为数据库用户授予列出/查看数据库的权限PostgreSQLGRANT SELECT ON pg_database TO some_user;MySQLGRANT SHOW DATABASES ON *.* TO some_user;除此之外还可以通过ensureExists: false显式关闭自动建库插件级可单独覆盖适合完全由 IaC 托管库生命周期的环境。进阶迁移回滚与进一步阅读数据库迁移由 Knex 驱动每个插件的迁移脚本存放在各自包的migrations目录中。当升级 Backstage 后需要降级时直接替换版本会导致迁移目录与数据库记录不一致出现 “The migration directory is corrupt” 错误此时应使用 Knex 手动回滚例如node_modules/.bin/knex migrate:status --connection postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD$POSTGRES_HOST/backstage_plugin_catalog --client pg --migrations-directory node_modules/backstage/plugin-catalog-backend/migrations/node_modules/.bin/knex migrate:down migration_id --connection postgresql://... --client pg --migrations-directory node_modules/backstage/plugin-catalog-backend/migrations/完整的回滚操作步骤参见 Manual Knex Rollback 指南其中也详细对比了migrate:down回滚单个迁移与migrate:rollback回滚最近一批迁移的适用场景。小结Backstage 的数据库体系以DatabaseManager为核心通过“基线配置 插件级覆盖”的双层结构覆盖了从开发期 SQLite 内存库到生产期多 PostgreSQL 集群、再到 IaC 托管数据库的全部持久化场景。理解backend.database.prefix、plugin.pluginId覆盖规则以及ensureExists/pluginDivisionMode等进阶字段就能在共享实例、随机凭据、多租户等复杂部署中游刃有余地完成数据库配置。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage 插件数据库配置指南：基于 DatabaseManager 的多库、多客户端持久化实战
Backstage 插件数据库配置指南基于 DatabaseManager 的多库、多客户端持久化实战【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文是一份面向生产环境的 Backstage 数据库配置实战指南。文章围绕 Backstage 的DatabaseManager由backstage/backend-common/ 新版后端系统中的backstage/backend-defaults提供展开讲解如何在app-config.yaml中按插件粒度per plugin配置数据库客户端与连接信息覆盖 SQLite 内存库、PostgreSQL、自定义库名前缀、基础设施即代码IaC下的随机凭据、PostgreSQL 与 SQLite 混用等典型场景。读完本文你将掌握 Backstage 数据库的完整配置体系、底层实现原理以及数据库权限与迁移回滚等运维要点。Backstage 数据库管理的核心机制Backstage 的后端插件各自维护自己的数据库连接这一能力由DatabaseManager统一提供。它的设计要点如下按插件隔离每个插件通过插件 IDpluginId获得独立的数据库连接与库名互不干扰。默认自动建库未显式指定库名时Backstage 会自动为每个插件创建以backstage_plugin_为前缀的数据库例如auth插件对应backstage_plugin_auth、catalog插件对应backstage_plugin_catalog。基线与插件覆盖backend.database下定义全局默认客户端与连接backend.database.plugin.pluginId下定义插件级覆盖。同类型客户端会继承基线配置并做增量合并不同类型客户端则完全以插件配置为准。从源码看DatabaseManager.ts 中DatabaseManager.fromConfig读取backend.database配置块并注册了五种连接器Connectorpg: new PgConnector(databaseConfig, prefix, schemaPrefix), sqlite3: new Sqlite3Connector(databaseConfig), better-sqlite3: new Sqlite3Connector(databaseConfig), mysql: new MysqlConnector(databaseConfig, prefix), mysql2: new MysqlConnector(databaseConfig, prefix),其中prefix取自databaseConfig.getOptionalString(prefix)缺省值为backstage_plugin_schemaPrefix缺省为空字符串且仅允许字母、数字、下划线等安全字符。插件请求连接时forPlugin(pluginId)会通过getClientType解析出该插件实际使用的客户端类型——优先取plugin.pluginId.client否则回退到基线的client若连接器不存在则抛出Unsupported database client type ...错误。此外DatabaseManager会为每个插件缓存 Knex 客户端databaseCache并启动每 60 秒一次的保活循环执行select 1连接在应用关闭时通过rootLifecycle的 shutdown 钩子统一销毁。前置条件安装数据库驱动在使用前请确保backend包中安装了对应的数据库驱动。不同客户端需要不同的驱动包客户端类型驱动包安装命令PostgreSQLpgyarn --cwd packages/backend add pgSQLite 3better-sqlite3yarn --cwd packages/backend add better-sqlite3yarn --cwd packages/backend add pgyarn --cwd packages/backend add better-sqlite3从运维角度讲只需为实际使用的客户端安装驱动即可。如果你打算同时使用 PostgreSQL 和 SQLite两个驱动可以一起安装。注意仓库根目录的默认配置 app-config.yaml 使用client: better-sqlite3与connection: :memory:因此开箱即用的开发环境依赖better-sqlite3驱动。配置文件结构与覆盖规则数据库配置统一放在backend.database下插件级配置放在backend.database.plugin.pluginId下。例如catalog插件的pluginId就是catalog其专属配置块为plugin.catalog。覆盖规则与源码computePgPluginConfig的行为一致插件未指定client时沿用基线client此时插件连接配置与基线连接配置合并插件值优先。插件指定了与基线不同的client时插件连接配置原样使用不再继承基线的连接配置。数据库名的解析顺序以 PostgreSQL 为例见 postgres.ts若插件连接配置中显式给出connection.database则使用该名称否则使用自动生成名${prefix}${pluginId}即backstage_plugin_pluginId。其中prefix通过backend.database.prefix配置可满足多个部署共享同一个数据库实例/集群的场景。典型配置示例以下示例均来自官方指南原文可直接套用到你的app-config.yaml或等价的环境配置覆盖文件中。1. 最小化内存配置全插件使用 SQLite 内存库适用于测试或其他不需要持久化的场景backend: database: client: better-sqlite3 connection: :memory:这也是仓库根目录 app-config.yaml 中默认使用的数据库配置。从 sqlite3.ts 的源码可以看到SQLite 连接器会把字符串形式的connection规范化为{ filename: connection }对象并自动补上useNullAsDefault: true同时每个连接创建成功后都会执行PRAGMA foreign_keys ON以启用外键约束。在 watch 模式下通过backstage-cli package start启动内存库还会借助DevDataStore在热重载之间保存/恢复数据库状态。2. PostgreSQL全插件使用 PGauth插件自定义库名backend: database: client: pg connection: host: some.example-pg-instance.tld user: postgres password: password port: 5432 plugin: auth: connection: database: pg_auth_set_by_user基线连接中的host、user、password、port会被所有插件继承auth插件额外指定了database: pg_auth_set_by_user因此它不再使用自动生成的backstage_plugin_auth而catalog等其他插件仍使用backstage_plugin_catalog等自动库名。3. 自定义库名前缀当多个部署共享同一个数据库实例/集群时可以通过prefix让不同部署使用不同前缀的库名避免冲突backend: database: client: pg connection: host: some.example-pg-instance.tld user: postgres password: password port: 5432 prefix: example_prefix_此时auth、catalog插件将分别使用名为example_prefix_auth、example_prefix_catalog的数据库。4. 按插件配置连接适配 IaC 随机凭据与库名在 Terraform、AWS CloudFormation 等基础设施即代码IaC环境中数据库凭据可能随机生成也可能无权创建新库或无法控制库名。此时可以为每个插件单独配置完整连接信息backend: database: client: pg connection: postgresql://some.example-pg-instance.tld:5432 plugin: auth: connection: postgresql://fort:knoxsome.example-pg-instance.tld:5432/unwitting_fox_jumps catalog: connection: postgresql://bank:reservesome.example-pg-instance.tld:5432/shuffle_ransack_playback注意连接既支持对象形式host/user/password/port也支持postgresql://形式的连接字符串。源码中 getPgConnectionConfig 会借助pg-connection-string解析字符串形式的连接。5. PostgreSQL 与 SQLite 3 混用下面的配置中除auth插件使用better-sqlite3内存库外其余插件全部使用 PostgreSQL。由于auth的客户端类型与基线不同其连接配置被原样使用不会继承基线的 PostgreSQL 连接backend: database: client: pg connection: postgresql://foo:barsome.example-pg-instance.tld:5432 plugin: auth: client: better-sqlite3 connection: :memory:配置项速查来自 schema 定义结合 config.d.ts 的配置结构声明backend.database支持的关键字段如下字段类型/取值说明clientbetter-sqlite3 \| sqlite3 \| pg \| embedded-postgres默认数据库客户端connection字符串或对象基础连接配置支持普通连接以及type: azure、type: cloudsql、type: rds等云托管 PostgreSQL 特殊连接prefix字符串自动生成库名的前缀默认backstage_plugin_schemaPrefix字符串使用pluginDivisionMode: schema时 schema 名的前缀默认ensureExists布尔是否自动创建不存在的库默认trueensureSchemaExists布尔是否自动创建不存在的 schema默认false仅pgpluginDivisionMode: schema支持pluginDivisionModedatabase \| schema插件数据库划分方式默认database每插件一库schema表示在同一个库中为每个插件划分独立 schema仅pg支持role字符串PostgreSQL 中新建 schema 的归属角色knexConfig对象透传给 Knex 的任意配置如debug、asyncStackTraces插件级knexConfig会递归合并进基线skipMigrations布尔跳过数据库迁移支持插件级覆盖plugin.pluginId.*同上插件级覆盖client、connection、ensureExists、ensureSchemaExists、knexConfig、role、skipMigrations检查数据库自动建库与最小权限原则DatabaseManager会在插件首次获取连接时尝试创建不存在的数据库。以 PostgreSQL 为例postgres.ts 中的ensurePgDatabase会先查询pg_database判断库是否存在不存在时执行CREATE DATABASE管理操作通过独立的 admin 连接池串行执行DDL 并发限制为 1并带有最多 3 次、间隔 100ms 的重试。SQLite 连接器则会在使用磁盘存储时自动创建目录。因此需要注意如果基线凭据没有建库权限、你在plugin.pluginId下设置了独立凭据那么这些库必须预先手动创建好——服务启动后只能使用它们无法替你创建。由于 Backstage 需要查询数据库是否存在你需要为数据库用户授予列出/查看数据库的权限PostgreSQLGRANT SELECT ON pg_database TO some_user;MySQLGRANT SHOW DATABASES ON *.* TO some_user;除此之外还可以通过ensureExists: false显式关闭自动建库插件级可单独覆盖适合完全由 IaC 托管库生命周期的环境。进阶迁移回滚与进一步阅读数据库迁移由 Knex 驱动每个插件的迁移脚本存放在各自包的migrations目录中。当升级 Backstage 后需要降级时直接替换版本会导致迁移目录与数据库记录不一致出现 “The migration directory is corrupt” 错误此时应使用 Knex 手动回滚例如node_modules/.bin/knex migrate:status --connection postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD$POSTGRES_HOST/backstage_plugin_catalog --client pg --migrations-directory node_modules/backstage/plugin-catalog-backend/migrations/node_modules/.bin/knex migrate:down migration_id --connection postgresql://... --client pg --migrations-directory node_modules/backstage/plugin-catalog-backend/migrations/完整的回滚操作步骤参见 Manual Knex Rollback 指南其中也详细对比了migrate:down回滚单个迁移与migrate:rollback回滚最近一批迁移的适用场景。小结Backstage 的数据库体系以DatabaseManager为核心通过“基线配置 插件级覆盖”的双层结构覆盖了从开发期 SQLite 内存库到生产期多 PostgreSQL 集群、再到 IaC 托管数据库的全部持久化场景。理解backend.database.prefix、plugin.pluginId覆盖规则以及ensureExists/pluginDivisionMode等进阶字段就能在共享实例、随机凭据、多租户等复杂部署中游刃有余地完成数据库配置。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考