# @btc-embedded/cdk-extensions 中文文档

规范地址：https://npmcn.com/package/%40btc-embedded/cdk-extensions/

版本：0\.24\.7
npm 元数据更新时间：2026-10-26T10:56:16.295Z
中文译文更新时间：2026-11-08T19:19:58.249Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40btc-embedded/cdk-extensions
原文对照：https://npmcn.com/package/%40btc-embedded/cdk-extensions/?lang=original
项目主页：https://github.com/btc-embedded/cdk-extensions#readme
源码仓库：https://github.com/btc-embedded/cdk-extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.5 MB，436 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：constructs ^10\.5\.1，aws-cdk-lib ^2\.260\.0，cdk-monitoring-constructs ^9\.0\.0，@aws-cdk-containers/ecs-service-extensions \>=2\.0\.1-alpha\.535
- 首次发布：2024-12-13T08:47:18.370Z
- 最新版本发布：2026-10-26T10:56:16.081Z
- 近 30 天下载量：3630（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：134（近 12 个月 78 个）

## 中文简介

有用的 CDK 扩展和常见逻辑集合

## 安装

```sh
npm install @btc-embedded/cdk-extensions
```

也可以使用：`pnpm add @btc-embedded/cdk-extensions`、`yarn add @btc-embedded/cdk-extensions`、`bun add @btc-embedded/cdk-extensions`

## README

# BTC 嵌入式 CDK 扩展

# @btc-内嵌/cdk-扩展

以 TypeScript 构建云基础设施的可重复使用的 AWS CDK( Cloud Development Kit) 扩展和构造集合.

## 特征

-   **CDK 构造**:包括 API Gateway、应用程序负载平衡器、Cognitto、VPC、DocumentDB等的现成使用构件.
-   **ECS 服务扩展**:为高级集装箱管弦乐提供ECS服务扩展.
-   **公用事业**:用于堆栈参数、价值进口和配置分析的通用公用事业和辅助工具.
-   **模块扩展**:轻松地扩展AWS资源,具有伐木,OpenTeleometry,EFS,Cloud Map,自定义容器等特征.

## 安装

```sh
yarn install @btc-embedded/cdk-extensions
```

## 用法示例

### 基本用途

```typescript
import { ApiGateway } from "@btc-embedded/cdk-extensions";

// Use constructs and extensions in your CDK app
```

### 使用应用程序集来简化配置

对于引用一个基础平台堆栈的应用程序级别堆栈,使用 `ApplicationStack` 确保一致使用基站堆栈名称:

```typescript
import { ApplicationStack } from "@btc-embedded/cdk-extensions";

export class MyAppStack extends ApplicationStack {
  constructor(scope: Construct, id: string) {
    super(scope, id, {
      basePlatformStackName: "my-platform-stack",
      env: {
        account: "123456789012",
        region: "eu-central-1",
      },
    });

    // Constructs and extensions automatically resolve the platform stack name
    // No need to pass basePlatformStackName repeatedly
  }
}
```

### 部署

使用 `createApplicationApp` 用于配置驱动的部署:

```typescript
import {
  createApplicationApp,
  ApplicationStack,
} from "@btc-embedded/cdk-extensions";
import { z } from "zod";

const configSchema = z.object({
  env: z.object({ account: z.string(), region: z.string() }),
  basePlatformStackName: z.string(),
});

createApplicationApp({
  directory: "./config",
  schema: configSchema,
  createStack: (scope, config) => new MyAppStack(scope, "MyApp", config),
});
```

## CLI 命令

### catnip — 计算机辅助翻译部的云工具包

`catnip` 为CloudFormation、ECS和Cognito提供业务帮助.

全局选项( 适用于所有命令) :

-   `--region <region>` —— AWS 区域(默认为 `AWS_DEFAULT_REGION` 编号 : `AWS_REGION`(中文(简体) )
-   `--profile <profile>` — AWS 命名配置文件

#### 堆栈诊断

诊断失败 Cloud Formation 部署并显示ECS 失败上下文 .

用法 :

```bash
catnip stack-diagnose
catnip stack-diagnose --stack-name my-stack
catnip stack-diagnose --stage prod
catnip stack-diagnose --stack-name my-stack --tail 200 --tasks 10
```

选项 :

-   `--stack-name <name>` —— 堆栈到诊断( 可选的; 自动检测到最后一个失败的堆栈如果省略)
-   `--stage <name>` ——自动检测的相位过滤器(如果 `--stack-name` (已提供)
-   `--tail <n>` — 每个容器显示的对数行数( 默认: 100)
-   `--tasks <n>` - 最近停止检查的任务数目(默认:5)

#### 语录

流出运行 CloudFormation 堆栈中的 ECS 服务的活日志 .

用法 :

```bash
catnip ecs-logs --stack-name my-stack
catnip ecs-logs --stack-name my-stack --follow
catnip ecs-logs --stack-name my-stack --service api --tail 50
catnip ecs-logs --stack-name my-stack --output raw
catnip ecs-logs --stack-name my-stack --output pretty
```

选项 :

-   `--stack-name <name>` — CloudFormation 堆栈名( 需要)
-   `--tail <n>` ——每个容器显示历史线(默认:100)
-   `-f, --follow` 保持新日志活动的投票
-   `--service <name>` ——按名称过滤服务
-   `-o, --output <mode>` 输出模式 : `text`, (中文(简体) ), `raw`,或 `pretty` (默认:文本)

#### 音响

使用 CloudFormation 输出从堆栈获取 Cognito 令牌 .

用法 :

```bash
catnip oidc-token --stack-name my-stack
catnip oidc-token --stack-name my-stack --output json
```

选项 :

-   `--stack-name <name>` – 出口Cognito资源的堆栈(需要)
-   `--output <token|json>` ——只打印符号,或完全响应 JSON(默认: `token`(中文(简体) )
    -   `token` 输出为 `access_token`

#### pg- 隧道

打开安全会话管理器通向Aurora PostgreSQL并启动本地客户端.

用法 :

```bash
catnip pg-tunnel --stack-name my-stack
catnip pg-tunnel --stack-name my-stack --exec "psql"
catnip pg-tunnel --stack-name my-stack --database app
catnip pg-tunnel --stack-name my-stack --no-auto-launch
catnip pg-tunnel --stage prod
```

选项 :

-   `--stack-name <name>` – 部署Aurora集群的堆放地(通常是基站台堆放地;自动发现工作时可选)
-   `--stage <name>` – 堆栈自动发现时使用的相位过滤器
-   `--local-port <port>` 首选本地端口( 默认 : `5432`(中文(简体) )
-   `--database <name>` - 超过 `PGDATABASE` 用于启动的客户端/壳
-   `--exec <command>` ——隧道开通后运行的明确命令
-   `--no-auto-launch` 保持隧道连接,不发射客户端/壳
-   `--tunnel-instance-id <id>` —— 堆栈导出缺失时倒置 EC2 实例 ID

数据库选择行为 :

-   若为 `--database` 提供了该值
-   如果省略, `catnip` 从已部署的ECS服务任务定义推断出数据库名称(`POSTGRES_DATABASE`(中文(简体) )
-   如果准确地推断出一个数据库,则作为 `PGDATABASE`
-   如果推断出多个数据库,则用源堆栈/服务打印 `PGDATABASE` 未设置

先决条件:

-   `session-manager-plugin` 必须在 `PATH`

## 文档

-   [API 参考](https://npmcn.com/package/%40btc-embedded/cdk-extensions/API.md)

## 许可证

Apache-2.0 — BTC 嵌入式系统 AG

## 常见问题

### @btc-embedded/cdk-extensions 是什么？

有用的 CDK 扩展和常见逻辑集合

### 如何安装 @btc-embedded/cdk-extensions？

在项目目录运行 npm install @btc-embedded/cdk-extensions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.1）、aws-cdk-lib（^2\.260\.0）、cdk-monitoring-constructs（^9\.0\.0）、@aws-cdk-containers/ecs-service-extensions（\>=2\.0\.1-alpha\.535）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 catnip，可以用 npx catnip 直接运行。

### @btc-embedded/cdk-extensions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @btc-embedded/cdk-extensions 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @btc-embedded/cdk-extensions 可以商用吗？

@btc-embedded/cdk-extensions 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @btc-embedded/cdk-extensions 的下载量有多少？

根据 npm 官方下载统计，@btc-embedded/cdk-extensions 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,630 次，日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @btc-embedded/cdk-extensions 还在维护吗？

最新版本 0\.24\.7 发布于 2026/10/26（13 天前）；至今共发布 134 个版本，其中过去 12 个月发布了 78 个；首次发布于 2024/12/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。