# @aws-cdk/aws-elasticache-alpha 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-elasticache-alpha/

版本：2\.275\.0-alpha\.0
npm 元数据更新时间：2026-10-26T19:19:07.102Z
中文译文更新时间：2026-11-07T13:56:57.703Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：781 kB，31 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20\.0\.0
- 运行依赖：0 个
- peer 依赖：constructs ^10\.5\.0，aws-cdk-lib ^2\.275\.0
- 首次发布：2025-09-29T14:03:20.068Z
- 最新版本发布：2026-10-26T19:19:06.572Z
- 近 30 天下载量：43948（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 64 个）

## 中文简介

用于 AWS 的 CDK 构建库: : elastiCache

## 安装

```sh
npm install @aws-cdk/aws-elasticache-alpha
```

也可以使用：`pnpm add @aws-cdk/aws-elasticache-alpha`、`yarn add @aws-cdk/aws-elasticache-alpha`、`bun add @aws-cdk/aws-elasticache-alpha`

## README

# ElastiCache CDK 构造库

* * *

![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)

> 本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 [语义版本](https://semver.org/) 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码.

* * *

本模块的构造用于 [亚马逊快递](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/WhatIs.html)。 。 。 .

-   这个 `ServerlessCache` 构造有利于创建和管理无服务器缓存.
-   这个 `User` 财务报告和审定财务报表 `UserGroup` 构造有利于创建和管理缓存用户.

## 无服务器缓存

Amazon ElastiCache Serverles是一个无服务器选项,根据应用程序流量模式自动缩放缓存容量. 您可以使用 `ServerlessCache` 构造 :

```ts
const vpc = new ec2.Vpc(this, 'VPC');
 
const cache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  vpc,
});
```

### 连接到无服务器缓存

要控制安全小组能访问无服务器缓存的人,请使用 `.connections` 属性.

无服务器缓存有一个默认端口 `6379`。 。 。 .

此示例允许 EC2 实例连接到无服务器缓存 :

```ts
declare const serverlessCache: elasticache.ServerlessCache;
declare const instance: ec2.Instance;
 
// allow the EC2 instance to connect to serverless cache on default port 6379
serverlessCache.connections.allowDefaultPortFrom(instance);
```

### 使用自定义引擎版本

这个名字 `CacheEngine` 财务报告和审定财务报表 `UserEngine` 固定成员覆盖现有版本 在最近CDK发布时。 如果 ElastiCache 发布新引擎 在添加为指定成员之前,请使用 `.of(...)` 工厂改为目标 它没有等待 CDK 更新 :

```ts
declare const vpc: ec2.Vpc;

new elasticache.ServerlessCache(this, 'ServerlessCache', {
  // Use any engine/version combination supported by ElastiCache:
  engine: elasticache.CacheEngine.of('valkey', '9'),
  vpc,
});
```

同样的模式适用于 `UserEngine.of(engineType)` 用于用户和用户组.

### 缓存使用限制

您可以在缓存数据存储和ECPU/second上配置使用限制,用于控制成本并确保可预测的性能.

**配置选项 :**

-   **最大限度**:确保您的缓存使用量不超过所配置的最大值
-   **最低限额**: 为连贯一致的业绩保留资源基线水平
-   **两者**: 定义您的缓存使用将运行的区域

关于更多的信息,见 [为管理费用设定比例限制](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Scaling.html#Pre-Scaling)。 。 。 .

```ts
declare const vpc: ec2.Vpc;
 
const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  vpc,
  cacheUsageLimits: {
    // cache data storage limits (GB)
    dataStorageMinimumSize: Size.gibibytes(2), // minimum: 1GB
    dataStorageMaximumSize: Size.gibibytes(3), // maximum: 5000GB
    // rate limits (ECPU/second)
    requestRateLimitMinimum: 1000, // minimum: 1000
    requestRateLimitMaximum: 10000, // maximum: 15000000
  },
});
```

### 备份和恢复

您可以启用无服务器缓存的自动备份 . 当自动备份被启用后,ElastiCache每天创建缓存的备份.

也可以在最方便的时候随时设置备用窗口. 如果您不指定备份窗口, ElastiCache 将自动指定一个 .

更多信息见 [安排自动备份](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/backups-automatic.html)。 。 。 .

要启用自动备份,请设置 `backupRetentionLimit` 属性。 您也可以通过设置指定快照创建时间 `backupTime` 属性 :

```ts
declare const vpc: ec2.Vpc;
 
const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  backup: {
    // enable automatic backups and set the retention period to 6 days
    backupRetentionLimit: 6,
    // set the backup window to 9:00 AM UTC
    backupTime: events.Schedule.cron({
      hour: '9',
      minute: '0',
    }),
  },
  vpc,
});
```

您可以通过设置创建最后备份 `backupNameBeforeDeletion` 属性.

```ts
declare const vpc: ec2.Vpc;
 
const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  backup: {
    // set a backup name before deleting a cache
    backupNameBeforeDeletion: "my-final-backup-name",
  },
  vpc,
});
```

通过将快照ARNs设置为 `backupArnsToRestore` 属性 :

```ts
declare const vpc: ec2.Vpc;
 
const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  backup: {
    // set the backup(s) to restore
    backupArnsToRestore: ['arn:aws:elasticache:us-east-1:123456789012:serverlesscachesnapshot:my-final-backup-name'],
  },
  vpc,
});
```

### 休息时加密

At-rest 加密总是对无服务器缓存启用. 有两个加密选项:

-   **默认**: 当无 `kmsKey` 指定(左起为 `undefined`),自动使用 AWS 拥有的 KMS 密钥
-   **客户管理密钥**:首先创建 KMS 密钥,然后通过 `kmsKey` 属性

### 休息时加密的客户管理密钥

ElastiCache支持对称的客户管理密钥(CMK)在休息时进行加密.

更多信息见 [使用 AWS KMS 的客户管理密钥](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/at-rest-encryption.html#using-customer-managed-keys-for-elasticache-security)。 。 。 .

要使用CMK, 请设置您的CMK 到 `kmsKey` 属性 :

```ts
import { Key } from 'aws-cdk-lib/aws-kms';
 
declare const kmsKey: Key;
declare const vpc: ec2.Vpc;
 
const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  serverlessCacheName: 'my-serverless-cache',
  vpc,
  // set Customer Managed Key
  kmsKey,
});
```

### 计量和监测

您可以使用 Cloud Watch Metrics 通过 `metric` 方法.

关于无服务器缓存计量的更多信息,见 [Valkey 和 Redis 开放源码软件的无服务器参数和事件](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/serverless-metrics-events-redis.html) 财务报告和审定财务报表 [无服务器参数和事件](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/serverless-metrics-events.memcached.html)。 。 。 .

```ts
declare const serverlessCache: elasticache.ServerlessCache;
 
// The 5 minutes average of the total number of successful read-only key lookups in the cache.
const cacheHits = serverlessCache.metricCacheHitCount();
 
// The 5 minutes average of the total number of bytes used by the data stored in the cache.
const bytesUsedForCache = serverlessCache.metricDataStored();
 
// The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
const elastiCacheProcessingUnits = serverlessCache.metricProcessingUnitsConsumed();
 
// Create an alarm for ECPUs.
elastiCacheProcessingUnits.createAlarm(this, 'ElastiCacheProcessingUnitsAlarm', {
  threshold: 50,
  evaluationPeriods: 1,
});
```

### 导入已存在的无服务器缓存

要导入已有的无服务器缓存, 请使用 `ServerlessCache.fromServerlessCacheAttributes` 方法 :

```ts
declare const securityGroup: ec2.SecurityGroup;
 
const importedServerlessCache = elasticache.ServerlessCache.fromServerlessCacheAttributes(this, 'ImportedServerlessCache', {
  serverlessCacheName: 'my-serverless-cache',
  securityGroups: [securityGroup],
});
```

## 用户和用户组

设置需要属性并创建 :

```ts
const newDefaultUser = new elasticache.NoPasswordUser(this, 'NoPasswordUser', {
  userId: 'default',
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
})
 
const userGroup = new elasticache.UserGroup(this, 'UserGroup', {
  users: [newDefaultUser],
});
```

### 非洲区域局

在 Valkey 7.2 及 上行 和 Redis OSS 6.0 上行,您可以使用一个功能,即基于角色的存取控制(RBAC). RBAC也是控制无服务器缓存访问的唯一方法.

RBAC允许您通过用户组控制缓存访问. 这些用户组被设计为组织访问缓存的一种方式.

更多信息见 [角色接入控制](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Clusters.RBAC.html)。 。 。 .

为使RBAC能够使用Valkey或Redis OSS进行ElastiCache,请采取以下步骤:

-   创建用户.
-   创建用户组并添加用户到用户组.
-   指定用户组为缓存 .

### 创建用户

首先,您需要通过使用 `IamUser`, (中文(简体) ), `PasswordUser` 或者说 `NoPasswordUser` 构造.

使用 RBAC 创建用户,并通过使用 `accessString` 属性.

更多信息见 [使用访问字符串指定权限](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Clusters.RBAC.html#Access-string)。 。 。 .

您可以通过使用 `IamUser` 构造 :

```ts
const user = new elasticache.IamUser(this, 'User', {
  // set user engine
  engine: elasticache.UserEngine.REDIS,
    
  // set user id
  userId: 'my-user',
 
  // set username
  userName: 'my-user',
 
  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
});
```

> 注:IAM启用的用户必须具有匹配的用户名和用户名. 更多信息见 [限制](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/auth-iam.html)。构造可以自动设置用户名,使其与用户代号相同.

如果您想要创建密码认证用户, 请使用 `PasswordUser` 构造 :

```ts
const user = new elasticache.PasswordUser(this, 'User', {
  // set user engine
  engine: elasticache.UserEngine.VALKEY,
  
  // set user id
  userId: 'my-user-id',  
    
  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
 
  // set username
  userName: 'my-user-name',
 
  // set up to two passwords
  passwords: [
    // "SecretIdForPassword" is the secret id for the password
    SecretValue.secretsManager('SecretIdForPassword'),
    // "AnotherSecretIdForPassword" is the secret id for the password
    SecretValue.secretsManager('AnotherSecretIdForPassword'),
  ],
});
```

您也可以通过使用 `NoPasswordUser` 构造 :

```ts
const user = new elasticache.NoPasswordUser(this, 'User', {
  // set user engine  
  engine: elasticache.UserEngine.REDIS, 
    
  // set user id
  userId: 'my-user-id',
 
  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
 
  // set username
  userName: 'my-user-name',
});
```

> 注: `NoPasswordUser` 只能用于 Redis 快取 .

### 默认用户

ElastiCache 自动创建默认用户,同时设置用户ID和用户名 `default`。该默认用户不能被修改或删除。 用户被创建为无密码认证用户.

这个用户旨在与之前的 Redis OSS 版本的默认行为相兼容,并且有一个访问字符串,允许它调用所有命令并访问所有密钥.

要在 CDK 中使用此自动创建的默认用户, 您可以使用 `NoPasswordUser.fromUserAttributes` 方法。 关于进口方法的更多信息,请参见: [导入现有用户组](https://npmcn.com/package/%40aws-cdk/aws-elasticache-alpha/#readme-import-an-existing-user-and-user-group) 节.

要将适当的访问控制添加到缓存中, 请设置 `accessString` 改为 `off -@all` 或用很强的口令.

要更改默认用户,请创建新的默认用户,用户名设置为 `default`。然后可以与原默认用户互换.

更多信息见 [用 Valkey 或 Redis OSS 将 RBAC 应用到缓存中](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Clusters.RBAC.html#rbac-using)。 。 。 .

如果你想创建新的默认用户, `userName` 必须是 `default` 财务报告和审定财务报表 `userId` 绝对不是 `default` 通过使用 `NoPasswordUser` 或者说 `PasswordUser`数字 :

```ts
// use the original `default` user by using import method
const defaultUser = elasticache.NoPasswordUser.fromUserAttributes(this, 'DefaultUser', {
  // userId and userName must be 'default'
  userId: 'default',
});
 
// create a new default user
const newDefaultUser = new elasticache.NoPasswordUser(this, 'NewDefaultUser', {
  // new default user id must not be 'default'
  userId: 'new-default',
  // new default username must be 'default'
  userName: 'default',
  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
});
```

> 注意: 您无法使用 `IamUser` 因为一个IAM启用的用户的用户名和用户ID不能不同.

### 添加用户到用户组

下一个,使用 `UserGroup` 构造以创建用户组并添加用户. 确保您包括原默认用户或新默认用户:

```ts
declare const newDefaultUser: elasticache.IUser;
declare const user: elasticache.IUser;
declare const anotherUser: elasticache.IUser;
 
const userGroup = new elasticache.UserGroup(this, 'UserGroup', {
  // add users including default user
  users: [newDefaultUser, user],
});
 
// you can also add a user by using addUser method
userGroup.addUser(anotherUser);
```

### 指定用户组

最后,指定一个用户组以缓存 :

```ts
declare const vpc: ec2.Vpc;
declare const userGroup: elasticache.UserGroup;
 
const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  serverlessCacheName: 'my-serverless-cache',
  vpc,
  // assign User Group
  userGroup,
});
 
```

### 授予IAM用户权限

如果你创建IAM用户, `"elasticache:Connect"` 必须允许对用户和缓存采取行动.

> 注:不需要任何密码用户或密码认证用户的许可.

更多信息见 [正在使用 IAM 认证](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/auth-iam.html)。 。 。 .

为了获得许可,您可以使用 `grantConnect` 方法输入 `IamUser` 财务报告和审定财务报表 `ServerlessCache` 构造 :

```ts
declare const user: elasticache.IamUser;
declare const serverlessCache: elasticache.ServerlessCache;
declare const role: iam.Role;
 
// grant "elasticache:Connect" action permissions to role
user.grantConnect(role);
serverlessCache.grants.connect(role);
```

### 导入现有用户组

您可以通过导入方法导入已有的用户组 :

```ts
const stack = new Stack();
 
const importedIamUser = elasticache.IamUser.fromUserId(this, 'ImportedIamUser', 'my-iam-user-id');
 
const importedPasswordUser = elasticache.PasswordUser.fromUserAttributes(stack, 'ImportedPasswordUser', {
  userId: 'my-password-user-id',
});
 
const importedNoPasswordUser = elasticache.NoPasswordUser.fromUserAttributes(stack, 'ImportedNoPasswordUser', {
  userId: 'my-no-password-user-id',
});
 
const importedUserGroup = elasticache.UserGroup.fromUserGroupAttributes(this, 'ImportedUserGroup', {
  userGroupName: 'my-user-group-name'
});
```

## 常见问题

### @aws-cdk/aws-elasticache-alpha 是什么？

用于 AWS 的 CDK 构建库: : elastiCache

### 如何安装 @aws-cdk/aws-elasticache-alpha？

在项目目录运行 npm install @aws-cdk/aws-elasticache-alpha，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.0）、aws-cdk-lib（^2\.275\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-elasticache-alpha 支持 TypeScript 吗？

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

### @aws-cdk/aws-elasticache-alpha 支持 ESM 还是 CommonJS？

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

### @aws-cdk/aws-elasticache-alpha 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-elasticache-alpha 可以商用吗？

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

### @aws-cdk/aws-elasticache-alpha 的下载量有多少？

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

### @aws-cdk/aws-elasticache-alpha 还在维护吗？

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