尼斯特JS-TypeorM-AWS-连接器

无缝桥 TypeORM 与 AWS 参数存储和保密管理器,用于在 NestJS 中安全自动旋转的数据库连接

重点

• QQ 零认证代码库 — 在运行时解决 AWS SSM 参数存储和密件管理器中的所有数据库配置
• * 以健康检查、交易亲和以及最多一个退休人才库为基准自动进行核证轮换
• 明确排水超时、总体故障和包件中性生命周期事件导致关闭
• QQ Split-source架构——下级团队拥有主机/端口/机密,app团队拥有独家的池/出站/同步设置
• 使用扩展合格类型Script声明为 NestJS 12 和 TypeORM 1 构建 ES 模块,可从 CommonJS 装入 require(esm)

目录

• 说明
• 技术堆栈
• 特征
• 建筑
• 项目结构
• 先决条件
• 安装
• 使用量
• 移动到 3. 0
• 移动到 2. 0
• 路线图
• 财务问题
• 许可证
• 承认

说明

NestJS-TypeorM-AWS-连接器 是生产级的NestJS模块,可以消除AWS托管应用程序中管理数据库配置的痛苦. 而不是硬编码证书或拼接环境变量, 此连接器会解决您的整个类型ORM DataSourceOptions 从 AWS 系统管理器 财务报告和审定财务报表 AWS 保密管理器 ——具有内置的认证旋转.

在现代云土结构中,数据库证书定期被旋转,以达到安全合规. 传统方法在旋转时会断开连接,导致停机. 这个连接器避免破坏性的中跑 DataSource 通过先验证一个替换连接来拆卸,促进未来查询跑取者的新驱动器,并仅在现有查询跑取者排出后退出上一个池. 它最多允许一代人和一代人退休;以后间隔推迟而不是增加池数.

实际世界使用案例

• ECS 远门微服务:在远门上部署雀巢JS API,由AWS保密管理器以自动旋转政策管理证书——连接器不重新部署取取新鲜证书.
• 多种环境部署: 使用相同的密码库 dev, (中文(简体) ), staging,以及 production ——每个环境从命名空间SSM参数中解决自己的数据库配置.
• 欧罗拉 PostgreSQL / RDS MySQL:连接到管理中的AWS数据库,其中基础设施团队通过参数存储控制主机,端口和秘密引用,而应用程序团队只配置实体和行为.
• 遵约第一组织:满足SOC2和PCI-DSS的要求,从不在代码,环境文件或容器图像中存储证书.

连接器使用 分裂源模式: 基础设施自有参数(host, port, secret ID)活在犬类的 AWS 命名空间中,而应用程序自有的设置(集合大小,超时,同步行为)则活在您应用的命名空间中. Raw 值会让您绕过 SSM 完全用于本地开发 .

QQ 技术堆栈

* 特性

• ✨ AWS 参数存储集成 ——从结构化的SSM路径解析数据库主机,端口,名称,类型,并调整参数,同时提供分级命名空间支持
• ✨ AWS 秘密管理器集成 ——从保密管理器获取用户名/密码证书,并妥善处理缺失或错误的秘密
• ✨ 边界证书旋转 - 升级前验证替换人员,只允许现有人才库外加一个退休人才库
• ✨ 交易无穷 ——查询跑道员和与管理器相关的交易停留在交易开始的一代人身上
• ✨ 封锁 ——停止新作,等活生生的后辈,再将超时或关闭故障报告为一个汇总错误
• ✨ 旋转事件 - 报告推迟轮调、退休一代和排出时间,而无巢穴事件影响依赖
• ✨ 紧急恢复 ——连续3次自转失败后,自动回击恢复,而不会破坏性地撕毁直播 DataSource
• ✨ 连接健康验证 - 验证现有和新的连接 SELECT 1 旋转前后的询问
• ✨ 分割源配置模型 ——基础设施自有设置(主机,端口,秘密代号)使用犬形AWS命名空间;应用自有设置使用您的模块命名空间
• ✨ 原始值覆盖 ——通过提供直接价值,完全适用于任何领域——适合当地发展 host: '127.0.0.1'
• ✨ 等级查询解析 – 场级 SSM 查询 – Canonical 默认 – ssm lookup Defaults – Parameter Store ConfigModule 默认
• ✨ ES 模块构建 - 载有扩展合格类型Script声明和源图的船舶ES模块 require(esm)
• ✨ 边界错误模型 ——静态诊断只披露经验证的错误类型和可选的 SQLSTATE,同时保留原故障为 cause
• ✨ NestJS 12 和 TypeORM 1 - 同侪 @nestjs/common 财务报告和审定财务报表 @nestjs/core >=12.3.2 <13 财务报告和审定财务报表 typeorm >=1.1.2 <2
• ✨ 同步同步注册( A) - 使用 register() 静态配置或 registerAsync() 有工厂功能用于动态配置

建筑

系统架构

flowchart TD
    appModule[AppModule] --> paramStore[ParameterStoreConfigModule]
    appModule --> connectorModule[TypeOrmAwsConnectorModule]
    connectorModule --> connectorService[TypeOrmAwsConnectorService]
    connectorModule --> rotatorService[RotatorService]
    connectorModule --> scheduleModule[ScheduleModule]
    connectorService --> paramStoreService[ParameterStoreConfigService]
    connectorService --> configService[NestJS ConfigService]
    connectorService --> ssmParameterStore[AWS SSM Parameter Store]
    connectorService --> secretsManager[AWS Secrets Manager]
    rotatorService --> connectorService
    rotatorService --> dataSource[TypeORM DataSource]
    connectorModule --> typeOrmModule[TypeOrmModule.forRootAsync]

数据流动

sequenceDiagram
    participant App as NestJS App
    participant Connector as ConnectorService
    participant SSM as AWS Parameter Store
    participant SM as AWS Secrets Manager
    participant TypeORM as TypeORM DataSource
    participant Rotator as RotatorService

    App->>Connector: getTypeOrmOptions()
    Connector->>SSM: Resolve host, port, dbName, type
    SSM-->>Connector: Parameter values
    Connector->>SSM: Resolve secretId
    SSM-->>Connector: Secret ID
    Connector->>SM: GetSecretValue(secretId)
    SM-->>Connector: username + password
    Connector->>SSM: Resolve optional tuning params
    SSM-->>Connector: poolSize, timeouts, etc.
    Connector-->>App: DataSourceOptions
    App->>TypeORM: Initialize DataSource

    loop Every rotation interval
        Rotator->>TypeORM: Validate connection health
        Rotator->>Connector: getTypeOrmOptions()
        Connector->>SM: Fetch fresh credentials
        SM-->>Connector: New username + password
        Rotator->>TypeORM: Initialize replacement DataSource
        Rotator->>TypeORM: Verify with SELECT 1
        Rotator->>TypeORM: Promote replacement driver for future query runners
        Rotator->>TypeORM: Retire previous pool after active query runners drain
    end

项目结构

NestJS-TypeORM-AWS-Connector/
├── .github/
│   ├── workflows/
│   │   ├── mirror-docs-to-docviewer.yml
│   │   ├── mirror-to-codecommit.yml
│   │   ├── qodana-quality-scan.yml
│   │   ├── release.yml
│   │   ├── snyk-security-scan.yml
│   │   └── test.yml
│   └── dependabot.yml
├── docs/
│   ├── api-reference/
│   ├── getting-started/
│   └── guides/
├── scripts/
│   ├── test/
│   │   └── consumer-smoke.mjs
│   └── check-declaration-imports.cjs
├── src/
│   ├── modules/
│   │   └── typeorm-aws-connector/
│   ├── shared/
│   │   ├── constant/
│   │   ├── enum/
│   │   ├── interface/
│   │   ├── provider/
│   │   └── type/
│   └── index.ts
├── test/
│   ├── consumer/
│   └── typeorm-aws-connector/
├── CHANGELOG.md
├── commitlint.config.js
├── eslint.config.js
├── LICENSE
├── lint-staged.config.js
├── nest-cli.json
├── package-lock.json
├── package.json
├── prettier.config.js
├── README.md
├── release.config.js
├── rollup.config.js
├── tsconfig.build.json
└── tsconfig.json

· 先决条件

• 节点.js ^22.13.0 ||24.11.0
• npm >= 9.0.0
• @nestjs/common和 @nestjs/core ##12.3.2 <13
• @nestjs/config ###120.0.1 < 13
• 型号 : 1.1.2 < 2
• @elsikora/nestjs-aws-parameter-store-config ^3.0.0-dev.1 (3.0预放出和每平稳 3.x)
• @aws-sdk/client-sm @3.535.0 <4
• 配置 AWS 证书( IAM 角色、 环境变量或 AWS CLI 配置)

* 安装

这些源代码描述 Connector 3. ^3.0.0-0 选择一个 3.0 预放后稳定 3.x 释放.

# Install the connector and its peer dependencies
npm install @elsikora/nestjs-typeorm-aws-connector@^3.0.0-0 @elsikora/nestjs-aws-parameter-store-config@^3.0.0-0 @aws-sdk/client-ssm @nestjs/common@^12 @nestjs/core@^12 @nestjs/config@^12 @nestjs/typeorm@^12 typeorm@^1

连接器安装 @aws-sdk/client-secrets-manager 财务报告和审定财务报表 @nestjs/schedule 作为直接的依赖. @elsikora/nestjs-aws-parameter-store-config 财务报告和审定财务报表 @nestjs/config 是同位素: 连接器注入 ParameterStoreConfigService 财务报告和审定财务报表 ConfigService,因此它必须共享申请的两份副本.

验证安装

npm ls @elsikora/nestjs-typeorm-aws-connector @elsikora/nestjs-aws-parameter-store-config @nestjs/config typeorm

使用量

先决条件:登记参数存储配置模块

在使用连接器之前, 登记 ParameterStoreConfigModule 从 @elsikora/nestjs-aws-parameter-store-config登记 ConfigModule 作为全局: 连接符注入 ConfigService 在自己的模块内:

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { ENamespace, ParameterStoreConfigModule } from "@elsikora/nestjs-aws-parameter-store-config";

@Module({
    imports: [
        ConfigModule.forRoot({ isGlobal: true }),
        ParameterStoreConfigModule.registerAsync({
            imports: [ConfigModule],
            inject: [ConfigService],
            useFactory: (configService: ConfigService) => ({
                application: configService.getOrThrow<string>("APPLICATION"),
                config: { region: configService.getOrThrow<string>("AWS_REGION") },
                environment: configService.getOrThrow<string>("ENVIRONMENT"),
                instanceName: "my-api",
                namespace: ENamespace.AWS_ECS_FARGATE,
                shouldDecryptParameters: true,
            }),
        }),
    ],
})
export class AppModule {}

基本用途:静态登记

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { TypeOrmAwsConnectorModule, TypeOrmAwsConnectorService } from "@elsikora/nestjs-typeorm-aws-connector";
import { UserEntity } from "./entities/user.entity";

@Module({
    imports: [
        TypeOrmModule.forRootAsync({
            // Register the connector inside the TypeORM factory module so the factory can inject its service
            imports: [
                TypeOrmAwsConnectorModule.register({
                    entities: [UserEntity],
                    rotation: {
                        isEnabled: false,
                    },
                }),
            ],
            inject: [TypeOrmAwsConnectorService],
            useFactory: async (connectorService: TypeOrmAwsConnectorService) => connectorService.getTypeOrmOptions(),
        }),
    ],
})
export class DatabaseModule {}

连接器解决 DataSourceOptions· ; TypeOrmModule 仍为初始化直播的主人公 DataSource设置 rotation.isEnabled: false 用于一发或见 启用证书旋转 长期服务.

自定义 SSM 查询

覆盖参数存储中解决的具体字段 :

import { ENamespace } from "@elsikora/nestjs-aws-parameter-store-config";
import { TypeOrmAwsConnectorModule } from "@elsikora/nestjs-typeorm-aws-connector";

TypeOrmAwsConnectorModule.register({
    entities: [UserEntity],
    ssmLookupDefaults: {
        instanceName: "my-api",
        namespace: ENamespace.AWS_ECS_FARGATE,
    },
    ssmLookups: {
        secretId: {
            instanceName: "database",
            namespace: ENamespace.AWS_SECRETS_MANAGER,
            path: ["secret-id"],
        },
        host: {
            instanceName: "aurora-postgres",
            namespace: ENamespace.AWS_RDS,
            path: ["host"],
        },
        port: {
            instanceName: "aurora-postgres",
            namespace: ENamespace.AWS_RDS,
            path: ["port"],
        },
        rotationShutdownDrainTimeoutMs: {
            path: ["database", "rotation", "shutdown-drain-timeout-ms"],
        },
    },
});

地方发展:原始价值

完全通过AWS用于当地发展:

import { EDatabaseType } from "@elsikora/nestjs-typeorm-aws-connector";

TypeOrmAwsConnectorModule.register({
    entities: [UserEntity],
    host: "127.0.0.1",
    port: 5432,
    username: "local-user",
    password: "local-password",
    databaseName: "mydb",
    type: EDatabaseType.POSTGRES,
});

启用证书旋转

为长期服务启用自动证书旋转 :

import { Logger } from "@nestjs/common";
import { ETypeOrmAwsConnectorRotationEvent, TypeOrmAwsConnectorModule } from "@elsikora/nestjs-typeorm-aws-connector";

const rotationLogger = new Logger("DatabaseRotation");

TypeOrmAwsConnectorModule.register({
    entities: [UserEntity],
    rotation: {
        isEnabled: true,
        intervalMs: 3_600_000, // Rotate every hour
        shutdownDrainTimeoutMs: 15_000,
        onEvent: (event) => {
            switch (event.type) {
                case ETypeOrmAwsConnectorRotationEvent.DRAIN_TIMEOUT: {
                    rotationLogger.error("Database rotation drain timed out", event);
                    break;
                }
                case ETypeOrmAwsConnectorRotationEvent.GENERATION_RETIRED: {
                    rotationLogger.log("Database generation retired", event);
                    break;
                }
                case ETypeOrmAwsConnectorRotationEvent.ROTATION_DEFERRED: {
                    rotationLogger.warn("Database rotation deferred", event);
                    break;
                }
            }
        },
    },
});

当旋转被启用时, shutdownDrainTimeoutMs 必须是正整数。 直接或通过犬类SSM路径提供 typeorm/rotation/shutdown-drain-timeout-ms;连接器不创建关闭默认值.

轮调服务将:

1. 验证当前连接健康
2. 从 AWS 保密管理器获取新证书
3. 创建替换 DataSource 包含同步、迁移、跳出和扩展安装
4. 校验替换连接与 a SELECT 1 查询
5. 推动未来查询跑取器的替换驱动程序,而不破坏直播 DataSource
6. 将查询运行器和管理器约束的交易保留在创建时
7. 延后间隔,直到退休的一代 排出并关闭
8. 在连续3次失败后,试图通过同一限制旋转门进行紧急恢复

轮调期间最多存在两个数据库库:现代和退休一代。 重叠相隔会合而不是创建队列替换 .

onEvent 是一个可选的,包中性可观察性回调。 它能回来 void 或者说 Promise<void>;它的返回承诺是没有等待的,它的同步体应该保持小. 它不能自己写正确或数据库。 收听器故障仅作为已验证的错误类型加上可选的SQLSTATE进行记录,并与自转生命周期相隔离. 事件物体被冻结,没有证书.

连接器永久设置 TypeORM 查询记录到 false。外国故障信息、堆栈、 SQL、 参数、 驱动有效载荷、 证书、 查询坐标、 配置文件、 IP 地址和 URL 都从未被复制到连接器日志或包装信件中。 折叠错误将原始失败保留为 cause 用于明确的进程处理.

轮回用于长寿服务. 对于一发任务,迁移、诱饵或明确的CLI任务,保留 rotation.isEnabled 禁用,所以连接符不会注册背景间隔.

关闭寿命周期

在长期运行的应用程序中启用 Nest 关闭钩 SIGTERM 到达连接器 :

const app = await NestFactory.create(AppModule);

app.enableShutdownHooks();
await app.listen(3000);

关闭时, 连接器会取消间隔, 拒绝新的查询运行器, 等待到 shutdownDrainTimeoutMs 然后结束现在的、待定的和退休的几代人。 如果排出或关闭不能解决,它就会喷出 DRAIN_TIMEOUT进行最优的清理,并拒绝 AggregateError呼唤者和管弦乐者必须将关闭视为不干净.

排水和发电的关闭 都有一个限定的阶段, 所以主机终止预算必须超过大约 2 × shutdownDrainTimeoutMs 加上周围的巢穴关闭工程和运行保障.

在工厂进行同步登记

TypeOrmAwsConnectorModule.registerAsync({
    imports: [ConfigModule],
    inject: [ConfigService],
    useFactory: (configService: ConfigService) => {
        const isRotationEnabled = configService.get<boolean>("DB_ROTATION_ENABLED", false);

        return {
            entities: [UserEntity],
            rotation: {
                intervalMs: configService.get<number>("DB_ROTATION_INTERVAL", 3_600_000),
                isEnabled: isRotationEnabled,
                ...(isRotationEnabled
                    ? {
                            shutdownDrainTimeoutMs: configService.getOrThrow<number>("DB_ROTATION_SHUTDOWN_DRAIN_TIMEOUT"),
                        }
                    : {}),
            },
        };
    },
});

打开生的 shutdownDrainTimeoutMs 当启用的服务从参数存储器中解析时属性 ConfigService。 。 。 .

一个 App 中的多个数据库模块

在每个拥有特定TypeORM连接的Nest数据库模块内分别注册连接器. 连接器模块被限定为该模块注册,因此多个连接器实例可以在一个应用程序中安全地共存.

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { getDataSourceToken, TypeOrmModule } from "@nestjs/typeorm";
import { TypeOrmAwsConnectorModule, TypeOrmAwsConnectorService } from "@elsikora/nestjs-typeorm-aws-connector";
import { ProviderEntity } from "./entities/provider.entity";

@Module({
    imports: [
        TypeOrmModule.forRootAsync({
            imports: [
                TypeOrmAwsConnectorModule.registerAsync({
                    // Must match the name below so RotatorService binds to this DataSource
                    dataSourceToken: getDataSourceToken("provider"),
                    imports: [ConfigModule],
                    inject: [ConfigService],
                    useFactory: (configService: ConfigService) => ({
                        entities: [ProviderEntity],
                        poolSize: configService.get<number>("PROVIDER_DB_POOL_SIZE", 10),
                    }),
                }),
            ],
            inject: [TypeOrmAwsConnectorService],
            name: "provider",
            useFactory: async (connectorService: TypeOrmAwsConnectorService) => connectorService.getTypeOrmOptions(),
        }),
    ],
})
export class ProviderDatabaseModule {}

使用 dataSourceToken 当连接器的 RotatorService 应当绑定在命名的 TypeORM 上 DataSource 而不是默认的连接符 。 每个注册都拥有独立的间隔,生成状态,以及事件召回.

数值分辨率优先

对于每个配置字段,数值按此顺序解决:

1. 原始值覆盖 (直接以配置方式提供)
2. SSM 参数存储器搜索 (通过结构化查询)
3. 内建默认 (仅用于可选调制字段,如 poolSize, (中文(简体) ), connectionTimeoutMs(中文(简体) )

所需字段(host, (中文(简体) ), port, (中文(简体) ), databaseName, (中文(简体) ), type, (中文(简体) ), secretId如果无法解决,则丢出明显的错误。 当旋转解析为启用时, rotation.shutdownDrainTimeoutMs 还需要这样做。 明确 rotation 属性优先于其结构化的 SSM 搜索.

移动到 3. 0

3.0 将连接器移动到NestJS 12和TypeORM 1,并将它作为仅作为ES模块来运输. 配置 API, Canonical SSM 查询合同,自转生命周期和导出名称不改变.

1. 先升级节点.js,雀巢JS和TypeORM. 在NestJS 11或更久,TypeORM 0.3或Node.js 20上的应用停留在 2.x上.
2. 安装 @elsikora/nestjs-aws-parameter-store-config 页:1 @nestjs/config 应用程序中有12个;它们不再由连接器安装. npm ls 必须显示每个副本.
3. 只从软件包根导入 . dist/esm, (中文(简体) ), dist/cjs 编辑 require 出口条件已不复存在.

ES模块应用程序 以 moduleResolution 设置为 bundler, (中文(简体) ), node16 或者说 nodenext申报内容 .js 每个相对导入的扩展 . 普通JS应用程序 保留 require(),该节点服务通过 require(esm) 每个支持的释放。 类型脚本 module: commonjs 通过顶层查找类型 types 字段为 moduleResolution: node10 (文本 6 然后需要 "ignoreDeprecations": "6.0"),并通过 exports 无 moduleResolution,而TypeScript 6 的解析为 bundler。 。 。 . 创建本地ES模块 例如,Nest CLI SWC 建构器类型是相互导入的实体之间的关系 Relation<T>; 否则启动失败 ReferenceError: Cannot access '...' before initialization。 。 。 .

正在导入包装入中否 .env 文档,然后写到控制台。 CI检查了这一点,并运行了针对Postgres的无害环境管理、通用JS和SWC消费者应用软件,在包装的柏油球上:在每个同位素范围内发布最新版本,在Node.js22.13.0上发布每个同位素位于其射程下方的同位素.

见完整 移动到 3. 0 向导。 。 。 .

从 1.x 移动

连接器2.0有意去除无限制的旋转和只限出力的关闭合同. 允许旋转的现有应用程序必须增加正数 rotation.shutdownDrainTimeoutMs,允许 Nest 关闭连接用于进程信号,并决定如何浮出新的结构旋转事件.

见完整 移动到 2.0 向导 升级前.

* 路线图

问 题

许可证

这个项目的许可证根据 麻省理工学院。 。 。 .

承认

• 网点JS ——进步节点.js框架,使构建服务器侧应用程序成为欢乐
• 类型ORM ——以基于装饰器的实体定义对数据库层进行授权的ORM
• JavaScript v3 的 AWS SDK 软件 ——用于SSM和秘密管理器客户端操作的模块化 AWS SDK
• @elsikora/nestjs-aws-参数库配置 - 提供结构化查询基础的参数存储配置模块
• 语义释放 ——自动版本和换行日志生成
• 滚动 ——模块捆绑器为ES模块提供动力构建输出
• 由 QQ 创建 埃尔西科拉

回到顶部