# @aws-cdk/aws-cloudtrail 中文文档

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

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:14:17.471Z
中文译文更新时间：2026-11-07T15:24:31.849Z
软件包许可：Apache-2\.0

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

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

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

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

- 包体积（解压后）：846 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：9 个
- peer 依赖：@aws-cdk/aws-events 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-kms 1\.204\.0，@aws-cdk/aws-lambda 1\.204\.0，@aws-cdk/aws-logs 1\.204\.0，@aws-cdk/aws-s3 1\.204\.0，@aws-cdk/aws-sns 1\.204\.0，@aws-cdk/core 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:30:08.996Z
- 最新版本发布：2023-06-19T21:07:15.389Z
- 近 30 天下载量：8835（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

AWS 的 CDK 构造库: CloudTrail

## 安装

```sh
npm install @aws-cdk/aws-cloudtrail
```

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

## README

# AWS 云轨构造库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

## 轨迹

AWS CloudTrail可以对您的AWS账户进行治理、合规以及业务和风险审计。 采取的行动 用户、角色或AWS服务在CloudTrail被记录为事件。 学多一点 [云轨 文档](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)。 。 。 .

这个 `Trail` 构造可以将事件作为日志文件持续发送到亚马逊 S3 桶。 学习更多关于 [创建 aWS 账户的轨迹](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)。 。 。 . 以下代码为您的账户创建了简单的 CloudTrail -

```ts
const trail = new cloudtrail.Trail(this, 'CloudTrail');
```

默认情况下, 这将创建一个 CloudTrail 会写入的新 S3 Bucket, 并选择一些其他合理默认 例如开展多区域和全球服务活动. 每个财产的缺省和如何推翻这些缺省都记录在 `TrailProps` 接口.

## 日志文件验证

为了验证CloudTrail的日志文件在CloudTrail交付后没有被修改,CloudTrail提供了一个 每个文件的数字签名 。 学习更多 [正在验证 CloudTrail 日志文件 诚信](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-log-file-validation-intro.html)。 。 。 .

启用于 `Trail` 默认构造,但可以通过设置关闭 `enableFileValidation` 改为 `false`。 。 。 .

```ts
const trail = new cloudtrail.Trail(this, 'CloudTrail', {
  enableFileValidation: false,
});
```

## 通知

亚马逊 SNS 通知可以配置在包含有有轨电车事件的新日志文件上交付到 S3. 学习更多 [配置 Amazon SNS 通知 云轨](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html)。 。 。 . 以下代码配置要通知的 SNS 主题 -

```ts
const topic = new sns.Topic(this, 'TrailTopic');
const trail = new cloudtrail.Trail(this, 'CloudTrail', {
  snsTopic: topic,
});
```

## 服务整合

除了向S3发送线索事件之外,它们还可以被配置为通知其他AWS服务-

### 亚马逊云表日志

CloudTrail 事件可以交付给 Cloud Watch Logs Log Group 。 默认情况下,将创建一个新的日志组,其中包含 默认保留设置。 以下代码允许发送 Cloud Watch 日志, 但指定特定保留 时长.

```ts
import * as logs from '@aws-cdk/aws-logs';

const trail = new cloudtrail.Trail(this, 'CloudTrail', {
  sendToCloudWatchLogs: true,
  cloudWatchLogsRetention: logs.RetentionDays.FOUR_MONTHS,
});
```

如果您想要使用一个特定的日志组来代替,此选项可以通过 `cloudwatchLogGroup`。 。 。 .

### 亚马逊事件Bridge

Amazon EventBridge 规则可以配置,以便在 CloudTrail 事件发生时使用 `Trail.onEvent()` API (英语). 使用可用的 API `aws-events`,可以过滤这些事件,使之与感兴趣的事件相匹配 特定服务、账户或时间范围。 见 [通过下列方式交付的活动 云轨](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/EventTypes.html#events-for-services-not-listed) 从 CloudTrail 了解更多事件结构.

以下代码从特定 AWS 账户中过滤 S 3 的事件并触发 lambda 函数 .

```ts
const myFunctionHandler = new lambda.Function(this, 'MyFunction', {
  code: lambda.Code.fromAsset('resource/myfunction'),
  runtime: lambda.Runtime.NODEJS_14_X,
  handler: 'index.handler',
});

const eventRule = cloudtrail.Trail.onEvent(this, 'MyCloudWatchEvent', {
  target: new targets.LambdaFunction(myFunctionHandler),
});

eventRule.addEventPattern({
  account: ['123456789012'],
  source: ['aws.s3'],
});
```

## 多区域和全球服务活动

默认a `Trail` 配置以将日志文件从多个区域发送到给定的单个 S3 桶 账户。 这在所有其他区域都造成了阴影痕迹(复制痕迹)。 学习更多关于 [怎么样 云轨区域行为](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-regional-and-global-services) 和关于 [`IsMultiRegion` 属性](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudtrail-trail.html#cfn-cloudtrail-trail-ismultiregiontrail)。 。 。 .

就大多数服务而言,事件记录在行动所在区域。 对于全球服务,如AWS IAM, AWS STS,亚马逊CloudFront, 第53路等,活动都会被送到包括全球服务的任何线索. 学多点 [关于全球服务活动](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-global-service-events)。 。 。 .

全球服务事件默认开启 `Trail` 在 CDK 中构造.

以下代码将无法为特定用户提供全球服务提供多区域线索和线索 `Trail` - 说吧

```ts
const trail = new cloudtrail.Trail(this, 'CloudTrail', {
  // ...
  isMultiRegionTrail: false,
  includeGlobalServiceEvents: false,
});
```

## 事件类型

**管理活动** 提供在您的 AWS 资源上执行的管理操作信息 账户。 这些也被称为控制飞机操作. 学习更多关于 [管理层 活动](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-events)。 。 。 .

默认a `Trail` 记录所有管理事件。 然而,它们可以被配置为要么关闭,要么只关闭 日志“ 读取” 或“ 写入” 事件 .

以下代码配置 `Trail` 只跟踪属于“读取”类型的管理事件.

```ts
const trail = new cloudtrail.Trail(this, 'CloudTrail', {
  // ...
  managementEvents: cloudtrail.ReadWriteType.READ_ONLY,
});
```

**数据事件** 提供关于在某一资源上或在一个资源中执行的资源业务的信息。 这些也是已知的 作为数据飞机操作。 学习更多关于 [数据 活动](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-concepts.html#cloudtrail-concepts-events)。 。 。 . 默认情况下,没有记录数据事件 `Trail`。 。 。 .

AWS CloudTrail支持亚马逊S3对象和AWS Lambda函数的数据事件记录.

这个 `logAllS3DataEvents()` API 配置线索以记录所有 S3 数据事件,同时 `addS3EventSelector()` API 可以 用于配置特定桶和特定对象前缀的 S3 数据事件的日志。 以下代码 配置 S3 数据事件的日志 `fooBucket` 对象前缀 `bar/`。 。 。 .

```ts
import * as s3 from '@aws-cdk/aws-s3';

const trail = new cloudtrail.Trail(this, 'MyAmazingCloudTrail');
declare const bucket: s3.Bucket;

// Adds an event selector to the bucket foo
trail.addS3EventSelector([{
  bucket,
  objectPrefix: 'bar/',
}]);
```

同样 `logAllLambdaDataEvents()` 配置记录所有 Lambda 数据事件的线索,同时 `addLambdaEventSelector()` API可用于配置特定Lambda函数的日志. 以下代码 为特定函数配置 Lambda 数据事件的日志.

```ts
const trail = new cloudtrail.Trail(this, 'MyAmazingCloudTrail');
const amazingFunction = new lambda.Function(this, 'AnAmazingFunction', {
  runtime: lambda.Runtime.NODEJS_14_X,
  handler: "hello.handler",
  code: lambda.Code.fromAsset("lambda"),
});

// Add an event selector to log data events for the provided Lambda functions.
trail.addLambdaEventSelector([ amazingFunction ]);
```

## 常见问题

### @aws-cdk/aws-cloudtrail 是什么？

AWS 的 CDK 构造库: CloudTrail注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-cloudtrail？

在项目目录运行 npm install @aws-cdk/aws-cloudtrail，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-events（1\.204\.0）、@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/aws-kms（1\.204\.0）、@aws-cdk/aws-lambda（1\.204\.0）、@aws-cdk/aws-logs（1\.204\.0）、@aws-cdk/aws-s3（1\.204\.0）、@aws-cdk/aws-sns（1\.204\.0）、@aws-cdk/core（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-cloudtrail 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。