让开源，少一点语言距离。
npm包中文文档

@aws-cdk/aws-s3-deployment

中文文档
1.204.0发布于 2023/06/20Apache-2.0TypeScriptCommonJS近 30 天下载 1.9万

用于向 S3 桶部署内容的构造

此软件包已被标记为弃用

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

中文使用文档
中文原文
文档目录13 节
  1. 支助来源
  2. 删除时保留
  3. 一般性建议
  4. 发泡
  5. 排除和包含过滤器
  6. 对象元数据
  7. 云纹无效
  8. 大小限制
  9. EFS 支持
  10. 有部署时间值的数据
  11. 页:1
  12. 发展
  13. 路线图

AWS S3 部署构造库

End-of-Support

AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.

关于如何移徙的更多信息,请参见: 移动到 AWS CDK v2 指南。 。 。 .

这个库允许充入带有.zip文件内容的 S3 桶 从其他 S3 桶或从本地磁盘.

以下示例定义了可公开访问的 S3 桶, 并带有网页托管功能 启用并输入磁盘上的本地目录.

const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', {
  websiteIndexDocument: 'index.html',
  publicReadAccess: true,
});

new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: websiteBucket,
  destinationKeyPrefix: 'web/static', // optional prefix in destination bucket
});

这是在引擎盖下发生的事情:

  1. 当部署此堆栈时( 要么通过 cdk deploy 或通过CI/CD) 本地目录中的内容 website-dist 目录将存档并上传 到一个中介资产桶。 如果不止一个来源,他们会 个人上传.
  2. 这个 BucketDeployment 构造自定义 CloudFormation 资源 类型 Custom::CDKBucketDeployment 输入模板。 源桶/钥匙 用于指向资产桶.
  3. 自定义资源下载 .zip 归档,取出并发行 aws s3 sync --delete 攻击目的地桶(在这种情况下) websiteBucket) (中文(简体) ). 如果有一个以上的来源,来源将是 在此步骤下下载并合并了部署前.

如果您在另一个构造中引用填充的桶,则取决于 文件已经存在, 请确定使用 deployment.deployedBucket这个 将确保在使用资源之前完成水桶部署 创建桶 :

declare const websiteBucket: s3.Bucket;

const deployment = new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket: websiteBucket,
});

new ConstructThatReadsFromTheBucket(this, 'Consumer', {
  // Use 'deployment.deployedBucket' instead of 'websiteBucket' here
  bucket: deployment.deployedBucket,
});

支助来源

用于桶部署的源类型有:

  • 本地 .zip 文件 : s3deploy.Source.asset('/path/to/local/file.zip')
  • 本地目录 : s3deploy.Source.asset('/path/to/local/directory')
  • 又一个桶: s3deploy.Source.bucket(bucket, zipObjectKey)
  • 字符串数据 : s3deploy.Source.data('object-key.txt', 'hello, world!') (支助) 部署时间值(中文(简体) )
  • JSON数据 : s3deploy.Source.jsonData('object-key.json', { json: 'object' }) (支助) 部署时间值(中文(简体) )

要从一个文件创建源, 您可以通过 AssetOptions 排除 除单一文件外的所有文件 :

  • 单一文件 : s3deploy.Source.asset('/path/to/local/directory', { exclude: ['**', '!onlyThisFile.txt'] })

重要性 这个 aws-s3-deployment 模块仅用于 来自可信来源的zip文件 。 由 CDK CLI 捆绑的目录( 通过使用 Source.asset() 在目录上)是安全的. 使用时 Source.asset() 或者说 Source.bucket() 引用已有的zip文件,确保您信任 文档中您正在引用 。 来自不信任来源的分页可能能够执行 此模块使用的 Lambda 函数中的任意代码,并使用其权限 在 S3 桶中读取或写入出乎意料的文件.

删除时保留

默认情况下, 目的地桶的内容会 没有 当 BucketDeployment 资源从堆栈中移除,或当目的地是 换了 您可以使用选项 retainOnDelete: false 要禁用这种行为, 在这种情况下,内容将被删除.

假设这一点有以下几个含义:

  • 逻辑标识更改

    更改逻辑编号 BucketDeployment 构造,不改变目的地 (例如由于重构,或有意改变ID) 将导致删除对象。 。 。 . 这是因为"云阵"将首先创建新的资源,不会影响, 之后删除旧资源,这将导致删除对象, 因为目的地没有改变 retainOnDelete 实值 false。 。 。 .

  • 目标变化

    当目标桶或前缀被更改时,上一个目标的所有文件都会 第一个 为: 删除后上传到新的目的地位置。 这可能涉及可用性 您的用户.

一般性建议

共享密钥

如果目标桶 没有 专为具体 BucketDeployment 构造(即由其他实体共享), 我们建议永远配置 destinationKeyPrefix 属性。 这将防止部署人员 不小心删除了它没有上传的数据.

专注的小桶

如果目标桶 实值 专门,跳过前缀配置可能是合理的, 在这种情况下,我们建议删除 retainOnDelete: false,转而配置 autoDeleteObjects 财产在目的地桶。 这将避免上述逻辑识别问题.

发泡

默认情况下, 来源中不存在的目标桶中的文件将被删除 当 BucketDeployment 创建或更新资源。 您可以使用选项 prune: false 无法禁用 ,在这种情况下,文件将不会被删除.

declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'DeployMeWithoutDeletingFilesOnDestination', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket,
  prune: false,
});

此选项也允许您 同一目的桶前缀的多桶布置, 每一个都有各自的特性。 例如,您可以设置不同的缓存控制头 基于文件扩展名 :

declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'BucketDeployment', {
  sources: [s3deploy.Source.asset('./website', { exclude: ['index.html'] })],
  destinationBucket,
  cacheControl: [s3deploy.CacheControl.fromString('max-age=31536000,public,immutable')],
  prune: false,
});

new s3deploy.BucketDeployment(this, 'HTMLBucketDeployment', {
  sources: [s3deploy.Source.asset('./website', { exclude: ['*', '!index.html'] })],
  destinationBucket,
  cacheControl: [s3deploy.CacheControl.fromString('max-age=0,no-cache,no-store,must-revalidate')],
  prune: false,
});

排除和包含过滤器

在部署中评价过滤器有两点:资产捆绑和实际部署。 如果您只是想在资产捆绑过程中排除文件, 您应该利用 exclude 财产 AssetOptions 定义源时:

declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'HTMLBucketDeployment', {
  sources: [s3deploy.Source.asset('./website', { exclude: ['*', '!index.html'] })],
  destinationBucket,
});

如果您想要指定在部署过程中使用的过滤器, 您可以使用 exclude 财务报告和审定财务报表 include 打开过滤器 BucketDeployment。如果排除,这些文件将不会被部署到目的地桶。 此外,如果文件在目的桶中已经存在,如果您正在使用 prune 选项 :

declare const destinationBucket: s3.Bucket;
new s3deploy.BucketDeployment(this, 'DeployButExcludeSpecificFiles', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket,
  exclude: ['*.txt'],
});

这些过滤器遵循的是AWS CLI所使用的相同格式. 详情见CLI文件 使用包含和排除过滤器。 。 。 .

对象元数据

您可以指定用于部署中所有对象的元数据. S3中元数据有2个类型:系统自定义元数据和用户自定义元数据. 系统定义的元数据有一个特殊的目的,例如缓存控制定义了保存一个对象缓存的时间. S3 不使用用户定义的元数据,密钥总是从 x-amz-meta- (此前缀会自动添加).

系统定义的元数据密钥包括以下内容:

  • 缓存控制( e)--cache-control 内 aws s3 sync(中文(简体) )
  • 内容分散( e)--content-disposition 内 aws s3 sync(中文(简体) )
  • 内容编码( e)--content-encoding 内 aws s3 sync(中文(简体) )
  • 内容 - 语言--content-language 内 aws s3 sync(中文(简体) )
  • 内容类型( e)--content-type 内 aws s3 sync(中文(简体) )
  • 期满--expires 内 aws s3 sync(中文(简体) )
  • x- amz- 存储级( )--storage-class 内 aws s3 sync(中文(简体) )
  • x-amz-website-再定向定位(--website-redirect 内 aws s3 sync(中文(简体) )
  • x-amz- server- side- 加密 (--sse 内 aws s3 sync(中文(简体) )
  • x-amz-server-side-加密-aws-kms-key-id (英语:--sse-kms-key-id 内 aws s3 sync(中文(简体) )
  • x-amz-server-side-加密-客户-算法(--sse-c-copy-source 内 aws s3 sync(中文(简体) )
  • x- amz- acl (帮助--acl 内 aws s3 sync(中文(简体) )

您可以在 S3 设置对象文档 财务报告和审定财务报表 aws s3 sync 文档。 。 。 .

const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', {
  websiteIndexDocument: 'index.html',
  publicReadAccess: true,
});

new s3deploy.BucketDeployment(this, 'DeployWebsite', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: websiteBucket,
  destinationKeyPrefix: 'web/static', // optional prefix in destination bucket
  metadata: { A: "1", b: "2" }, // user-defined metadata

  // system-defined metadata
  contentType: "text/html",
  contentLanguage: "en",
  storageClass: s3deploy.StorageClass.INTELLIGENT_TIERING,
  serverSideEncryption: s3deploy.ServerSideEncryption.AES_256,
  cacheControl: [
    s3deploy.CacheControl.setPublic(),
    s3deploy.CacheControl.maxAge(Duration.hours(1)),
  ],
  accessControl: s3.BucketAccessControl.BUCKET_OWNER_FULL_CONTROL,
});

云纹无效

您可以提供 CloudFront 分发和可选路径, 以在桶部署完成后无效 .

import * as cloudfront from '@aws-cdk/aws-cloudfront';
import * as origins from '@aws-cdk/aws-cloudfront-origins';

const bucket = new s3.Bucket(this, 'Destination');

// Handles buckets whether or not they are configured for website hosting.
const distribution = new cloudfront.Distribution(this, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) },
});

new s3deploy.BucketDeployment(this, 'DeployWithInvalidation', {
  sources: [s3deploy.Source.asset('./website-dist')],
  destinationBucket: bucket,
  distribution,
  distributionPaths: ['/images/*.png'],
});

大小限制

部署资源的默认内存限制为128MiB. 如果你需要的话 复制更大的文件,您可以使用 memoryLimit 用于增加 aWS Lambda 资源处理器大小.

部署资源的默认麻黄存储大小为512MiB. 狦 需要上传更大的文件,您可能达到此限制 。 你可以用这个 ephemeralStorageSize 用于增加 AWS Lambda 存储大小的配置 资源处理器.

注意: 您的堆栈中将新建 AWS Lambda 处理器, 用于每种组合 内存和存储大小.

EFS 支持

如果工作流程比默认的(512 MB)磁盘空间需要更多的磁盘空间,您可以附加一个 EFS 存储到下面 羊肉达功能. 启用 EFS 支持集 efs 财务报告和审定财务报表 vpc 巴克特部署的道具.

检查下方的样本使用情况 . 请注意,创建 VPC 内含可能导致堆栈删除失败. 为简洁起见,现将其列于下. 为了避免这种状况,您的网络在下方(VPC)保持单独堆放,并作为道具通过.

declare const destinationBucket: s3.Bucket;
declare const vpc: ec2.Vpc;

new s3deploy.BucketDeployment(this, 'DeployMeWithEfsStorage', {
  sources: [s3deploy.Source.asset(path.join(__dirname, 'my-website'))],
  destinationBucket,
  destinationKeyPrefix: 'efs/',
  useEfs: true,
  vpc,
  retainOnDelete: false,
});

有部署时间值的数据

内容转至 Source.data() 或者说 Source.jsonData() 可包含 只有在部署期间才能解决的参考文献.

例如:

import * as sns from '@aws-cdk/aws-sns';

declare const destinationBucket: s3.Bucket;
declare const topic: sns.Topic;

const appConfig = {
  topic_arn: topic.topicArn,
  base_url: 'https://my-endpoint',
};

new s3deploy.BucketDeployment(this, 'BucketDeployment', {
  sources: [s3deploy.Source.jsonData('config.json', appConfig)],
  destinationBucket,
});

数值在 topic.topicArn 是一个部署时间值。 只有解决 通过在生成的源文件中放置标记来进行部署,以及 以实际价值代替其部署到目的地.

页:1

  • 此库使用一个 AWS CloudFormation 自定义资源, 大约是 10MiB in 尺寸。 此资源的代码与此库相捆绑 .
  • AWS Lambda的执行时间限于15min. 这限制了数据的数量 它可以部署在桶 在这个暂停.
  • 当 BucketDeployment 从堆栈中取出,保留内容 在目的地桶内(952号) (中文(简体) ).
  • 使用时 s3deploy.Source.bucket() 以获取文件源 另一桶: 只有在密钥( 文件名) 时才会更新已部署的文件 更改源桶中的文件。 正在更改文件不会到位 足够好: 如果属性不运行, 自定义资源将不会运行 变化.
    • 如果使用资产(s3deploy.Source.asset()你不用担心 关于这一点:资产系统将确保如果文件有变化, 文件名称是独一无二的,部署将运行.

发展

自定义资源在 Python 3.7 中被执行,以便杠杆化 用于"aws s3同步"的 AWS CLI. 密码在下面 lib/lambda 财务报告和审定财务报表 单位测试正在进行中 test/lambda。 。 。 .

此软件包在构建时间需要 Python 3. 7 才能创建自定义 资源Lambda捆绑并测试. 还要靠几部剧本 所以 可能很难在Windows上发展.

路线图

  • 支持“蓝色/绿色”部署(954号(中文(简体) )

版本与发布记录

@aws-cdk/aws-s3-deployment 共发布 280 个版本，首次发布于 2018/10/19；过去 12 个月发布了 0 个版本。

版本发布日期距今
1.204.0latest2023/06/203 年前
1.203.02023/06/013 年前
1.202.02023/05/223 年前
1.201.02023/05/113 年前
1.200.02023/04/273 年前
1.199.02023/04/213 年前

关于 @aws-cdk/aws-s3-deployment 的常见问题

@aws-cdk/aws-s3-deployment 是什么？

用于向 S3 桶部署内容的构造注意：该包已被作者标记为弃用——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-s3-deployment？

在项目目录运行 npm install @aws-cdk/aws-s3-deployment，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-cloudfront（1.204.0）、@aws-cdk/aws-ec2（1.204.0）、@aws-cdk/aws-efs（1.204.0）、@aws-cdk/aws-iam（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-s3-assets（1.204.0）、@aws-cdk/core（1.204.0）、@aws-cdk/lambda-layer-awscli（1.204.0）、constructs（^3.3.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@aws-cdk/aws-s3-deployment 支持 TypeScript 吗？

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

@aws-cdk/aws-s3-deployment 支持 ESM 还是 CommonJS？

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

@aws-cdk/aws-s3-deployment 需要什么版本的 Node.js？

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

@aws-cdk/aws-s3-deployment 可以商用吗？

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

@aws-cdk/aws-s3-deployment 的下载量有多少？

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

@aws-cdk/aws-s3-deployment 还在维护吗？

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