Amazon S3 与 S3 兼容存储

TeamCity 配备了 Amazon S3 Artifact Storage 插件，允许在 Amazon S3 桶中以及与 S3 兼容的桶中存储构建工件，比如 MinIO， Backblaze B2 等等。 S3 兼容存储可以在 AWS 和非 AWS 环境中托管。

创建并设置新的 AWS S3 存储

导航至 Administration | <Your_Project> 页面并切换至 Artifacts Storage 标签页。
- 如果您希望您的新存储对所有 TeamCity 项目可用，打开 <Root project> 的设置。
- 如果您的新存储只应用于此项目及其子项目，那么可以编辑一个特定的项目。
内置的 TeamCity 工件存储默认显示并标记为活动状态。点击 添加新储存 按钮以创建新的存储空间。
指定自定义存储名称，如有需要，还可以指定其内部使用的 ID。
将类型字段设置为 "AWS S3"。
选择一个现有的 AWS Connection ，TeamCity 应使用它来访问您的 Amazon 资源。如果没有合适的 AWS 连接存在，请点击 "+" 图标来添加一个。
您不能使用属于父项目且其可用于子项目设置被禁用的 AWS 连接。
然而，如果父项目已使用非共享连接配置了 S3 存储，那么这个存储仍可供子项目使用。
被选中的 AWS 连接使用的用户凭证（或者它扮演的 IAM 角色）应该具有以下权限以访问 S3 桶：
- ListAllMyBuckets
- 获取存储桶位置
- 获取对象
- ListBucket
- PutObject
- 删除对象
- 获取加速配置 （如果启用了 Transfer Acceleration）
在以前的 TeamCity 版本中，构建工件存储对话框允许您明确指定连接设置：访问密钥凭据、用户 IAM 角色，以及 TeamCity 是否应在默认 AWS 位置中查找凭据（默认提供程序链设置）。
从2023.11版本开始，这些设置仅适用于 AWS Connections。如果您从旧版本的 TeamCity 迁移，并且现有的 AWS S3 存储使用了这些设置中的任何一个，请点击转换为 AWS 连接链接。此操作将 AWS 相关设置转移至新的 AWS 连接，并将此新连接选为您存储的源连接。
TeamCity 使用选定的 AWS 连接来获取可用的 S3 桶的列表。打开存储桶下拉菜单，从列表中选择一个特定项。

（可选）如果您想要为所有 TeamCity 项目使用相同的 S3 桶，并配置基于前缀的权限，请指定 path prefix。
Amazon S3 存储桶支持两种加速文件上传和下载的选项：
- AWS CloudFront—— 这是一个内容分发网络（CDN），允许 TeamCity 使用低延迟的 CloudFront 服务器进行附件的传输。
- Transfer Acceleration——一种桶级功能，旨在优化从世界各地到集中式 S3 存储桶的传输速度。它可以实现您的客户端与 S3 桶之间长距离、快速、便捷且安全的文件传输。
如果您的存储桶配置为使用 Transfer Acceleration 或 CloudFront，请在加速传输部分下选择相应的选项。否则，如果您希望 TeamCity 以常规模式传输文件，请选择无类型。
选择 AWS CloudFront 选项需要设置其他字段。参阅此部分以获取更多信息：通过 CloudFront 传输工件。
使用 Transfer Acceleration 将应用以下限制：
- 虚拟主机寻址始终处于开启状态。不支持路径式请求。
- 您的 S3 桶必须启用 Transfer Acceleration。
- 桶的名称中不能含有点（.）。
- AWS Connection 访问您的存储桶所使用的用户凭证或 IAM 角色必须包含 获取加速配置 权限。

为了优化大文件到存储的上传，您可以启用多部分上传。为了实现这一点，请勾选 自定义阈值和部分大小 的设置，并设置多部分上传阈值。允许的最小值是 5MB。支持的后缀名： KB、 MB、 GB、 TB。如果您将此字段留空，则会自动为所有大于 8 MB 的文件启动分段上传（8MB 是默认值）。
此外，您可以配置每个上传文件部分的最大允许大小。最小值为 5MB。如果留空，TeamCity 将使用 8MB 作为默认值。
我们建议您配置一个 bucket 生命周期策略来防止多部分上传不完整。

取消选中 强制虚拟主机寻址 选项，以关闭相应功能（默认启用）。目前，TeamCity 支持托管式和路径式的请求。请注意，自2020年9月以来， Amazon 停止支持路径样式访问新的存储桶。
如果您的存储使用了 Transfer Acceleration ，则无法禁用此设置。
勾选 上传后验证文件完整性 ，允许 TeamCity 对上传的文件进行额外的检查。如果完整性验证失败，TeamCity将在构建日志中写入相应的消息。
点击 Save 以保存您的新存储并返回至可用存储的列表。

当查看项目可用的存储列表时，点击 设为活动开始为该项目的所有新构建使用对应的存储。 has N usages 链接允许您查看哪些构建使用了此存储来上传他们的构建工件。

创建并设置新的 S3 兼容存储

导航至 Administration | <Your_Project> 页面并切换至 Artifacts Storage 标签页。
- 如果您希望您的新存储对所有 TeamCity 项目可用，打开 <Root project> 的设置。
- 如果您的新存储只应用于此项目及其子项目，那么可以编辑一个特定的项目。
内置的 TeamCity 工件存储默认显示并标记为活动状态。点击 添加新储存 按钮以创建新的存储空间。
指定自定义存储名称，如有需要，还可以指定其内部使用的 ID。
将类型字段设置为 "Custom S3"。
指定访问密钥 ID 和密钥访问密钥值。请参阅您的 S3 兼容存储供应商的文档，了解如何发布访问密钥的信息。
指定 TeamCity 应使用的存储端点以访问您的存储桶。
（可选）如果您想要为所有 TeamCity 项目使用相同的 S3 桶，并配置基于前缀的权限，请指定 path prefix。
为了优化大文件到存储的上传，您可以启用多部分上传。为了实现这一点，请勾选 自定义阈值和部分大小 的设置，并设置多部分上传阈值。允许的最小值是 5MB。支持的后缀名： KB、 MB、 GB、 TB。如果您将此字段留空，则会自动为所有大于 8 MB 的文件启动分段上传（8MB 是默认值）。
此外，您可以配置每个上传文件部分的最大允许大小。最小值为 5MB。如果留空，TeamCity 将使用 8MB 作为默认值。
取消选中 强制虚拟主机寻址 选项，以关闭相应功能（默认启用）。目前，TeamCity 支持托管式和路径式的请求。请注意，自2020年9月以来， Amazon 停止支持路径样式访问新的存储桶。
勾选 上传后验证文件完整性 ，允许 TeamCity 对上传的文件进行额外的检查。如果完整性验证失败，TeamCity将在构建日志中写入相应的消息。
点击 Save 以保存您的新存储并返回至可用存储的列表。

S3 存储类

Amazon S3 存储类别允许您根据存储的期望性能，以及数据的可用性和弹性进行精细调整。

有两种方式可以启用所需的存储类：

在 TeamCity 端. 当向 S3 桶上传工件时，TeamCity 会在其 x-amz-storage-class 请求中添加 PUT 头。标头值取决于 TeamCity 中相应的存储设置（例如， x-amz-storage-class: INTELLIGENT_TIERING）。这种模式在 AWS方面不需要任何额外的设置。
虽然目前我们还不支持这种方法，但我们希望在未来的发布周期中实现这个功能。赞成并评论这个 YouTrack 工单以支持该功能并分享您的反馈： TW-79992。
在 AWS 端. 在此模式下，TeamCity以规定的方式上传工件，预设的生命周期规则在工件上传后应用所需的存储类别。要设置此规则，请按照以下步骤操作：
1. 打开所需的 S3 存储并切换到管理层选项卡。
2. 点击创建生命周期规则。
3. 在生命周期规则操作部分下检查在存储类别之间移动对象的当前版本。
4. 选择所需的存储类别和上传与转换日期之间的延迟。将对象创建后的天数设置为 "0"，以便在 TeamCity 上传工件后立即转换它们。
  TeamCity 不支持存档存储类，因为它们的文件不可立即获取，需要进行额外的解压/预热操作才能取回。
5. 启用存储的工件的附加规则。例如，您可以检查使对象的当前版本过期以将先前上传的工件标记为已过期，并检查永久删除对象的非当前版本以定期清理您的存储。
6. 指定规则范围，以选择其应用于整个存储还是仅应用于符合所需过滤器的那些工件。
7. 在页面底部复查您的规则。它可能看起来如下：
8. 点击创建规则以保存您的生命周期规则。

请参阅以下 AWS 帮助文章以获取更多信息：使用 Amazon S3 存储类别。

通过 CloudFront 传输工件

Amazon CloudFront 是一个内容分发网络，提供低延迟和高传输速度。启用其对 S3 存储的支持将允许 TeamCity 通过最近的 CloudFront 服务器传输构建工件。如果您的 S3 存储桶位于与您的 TeamCity 基础设施不同的区域，这可能会大大加快工件的上传/下载速度，并减少费用。

前提条件

TeamCity 可以为您设置 CloudFront 集成，或者您可以手动设置所有设置。

CloudFront 集成需要进行配置：

一个 OAI 用户
两个 CloudFront distributions ，一个用于上传和下载工件。
一个受信任的密钥组
一个 SSH-2 RSA 密钥对（公钥 + 私钥）以 PEM 格式存储

CloudFront 设置

当您将存储类型切换为 AWS CloudFront 时，会出现四个新设置。

使用下载分发和上传分发下拉菜单选择手动创建的分发。
公钥字段和上传私钥... 按钮允许您指定相应的密钥。

另外，您可以点击图标，让 TeamCity 自动配置所有四个设置。

为了使 Cloudfront 设置正常工作，TeamCity 需要以下权限：

cloudfront:ListDistributions
cloudfront:ListKeyGroups
cloudfront:ListPublicKeys

自动 CloudFront 设置

TeamCity 可以自动配置设置。这涉及到：

生成密钥对并上传公钥到 CloudFront。
在 CloudFront 中创建新的密钥组。
创建两个新的分布，具体如下：
- 使用所有边缘位置价格类别。
- 一个新的 Origin Access Identity 可以访问当前的存储桶。
- 定义的默认行为
  - 允许的用于上传工件的 HTTP 方法： GET、 头部、 选项、 PUT、 POST、 PATCH、 DELETE ；用于下载的： GET、 头部、 选项；
  - 一个新的密钥组具有查看者访问权；
  - 一种自定义的缓存策略，允许传递所有查询字符串。
将新策略添加到 S3 桶中，以允许新分发访问它。请查看 policy example。

自动设置需要授予 Teamcity 额外的权限：

cloudfront:CreateDistribution
cloudfront:CreateKeyGroup
cloudfront:CreatePublicKey
cloudfront:CreateOriginRequestPolicy
cloudfront:CreateCloudFrontOriginAccessIdentity
cloudfront:CreateCachePolicy
cloudfront:DeleteKeyGroup
cloudfront:DeletePublicKey
cloudfront:ListCloudFrontOriginAccessIdentities
cloudfront:ListCachePolicies
cloudfront:ListOriginRequestPolicies
cloudfront:GetDistribution
cloudfront:GetPublicKey
s3:GetBucketPolicy
s3:PutBucketPolicy

示例策略提供所有必要的权限：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "1",
            "Effect": "Allow",
            "Action": [
                "cloudfront:CreatePublicKey",
                "cloudfront:CreateOriginRequestPolicy",
                "cloudfront:ListCloudFrontOriginAccessIdentities",
                "cloudfront:DeleteKeyGroup",
                "cloudfront:GetPublicKey",
                "cloudfront:ListCachePolicies",
                "cloudfront:CreateDistribution",
                "cloudfront:ListOriginRequestPolicies",
                "cloudfront:DeletePublicKey",
                "cloudfront:CreateCloudFrontOriginAccessIdentity",
                "cloudfront:CreateKeyGroup",
                "cloudfront:CreateCachePolicy",
                "cloudfront:GetDistribution",
                "cloudfront:ListPublicKeys",
                "s3:ListAllMyBuckets",
                "cloudfront:ListKeyGroups",
                "cloudfront:ListDistributions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "2",
            "Effect": "Allow",
            "Action": [
                "s3:PutBucketPolicy",
                "s3:GetBucketPolicy"
            ],
            "Resource": "arn:aws:s3:::<YOUR_BUCKET_NAME>"
        }
    ]
}


    

手动设置 CloudFront

出于安全原因，我们建议配置两个单独的分发，用于上传和下载工件。对于每个分发版：

生成一对 SSH-2 RSA 密钥格式的密钥对。
将密钥对中的公钥上传到 CloudFront。
在 CloudFront 中添加一个新的密钥组，并将创建的公钥添加到此组中。
创建一个新的缓存策略，并将缓存键设置 | 查询字符串设置为 All。
如果您使用的是私有存储桶，请创建一个新的 OAI 用户。
创建一个分发并将您的密钥组附加到它上：
- 确保选择与在 TeamCity 中指定的相同的 S3 桶。
- 允许的 HTTP 方法用于上传工件 GET、 头部、 选项、 PUT、 POST、 PATCH、 DELETE ；用于下载 GET、 头部、 选项。
- 限制查看者访问：是
- 受信任的授权类型：受信任的密钥组
- 缓存键和源请求：缓存策略和源请求策略
- 对于私有存储桶，启用 use OAI 选项并使用以下设置配置 OAI：
  - 存储桶策略：否，我将更新存储桶策略
- 对于公共存储桶，请禁用阻止公共访问选项。
为您的 S3 桶添加新策略。参见策略示例。

当配置后，分发应该自动出现在下载分发和上传分发的下拉菜单中。

选择目标 CloudFront 分发。
在 Public key 中，选择与此分发相关联的公钥。
点击 Upload private key... 按钮上传配对中的私钥。
保存存储设置。

S3 策略示例

通过 OAI 访问私有存储桶：

{
"Sid": "1",
"Effect": "Allow",
"Principal": {
      "AWS": "arn:aws:iam::cloudfront:user/CloudFront Origin Access Identity <OAI ID"
  },
  "Action": [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject"
  ],
  "Resource": "arn:aws:s3:::<S3 bucket name/*"
}

    

访问公共桶时：

{
"Sid": "PublicRead",
"Effect": "Allow",
"Principal": "*",
  "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion"
    ],
  "Resource": "arn:aws:s3::<BUCKET_NAME>/*"
}

    

Kotlin DSL

以下示例说明了如何将 S3 桶添加为项目工件的自定义存储，并将此存储设置为主存储（默认）。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.projectFeatures.activeStorage
import jetbrains.buildServer.configs.kotlin.projectFeatures.s3Storage

project {
    // ...
    features {
        activeStorage {
            id = "PROJECT_EXT_37"
            activeStorageID = "PROJECT_EXT_4"
        }
        s3Storage {
            id = "PROJECT_EXT_4"
            awsEnvironment = default {
                awsRegionName = "eu-west-1"
            }
            connectionId = "AwsPrimary"
            storageName = "S3 Transfer Acceleration"
            bucketName = "dk-s3ta"
            enableTransferAcceleration = true
            forceVirtualHostAddressing = true
            verifyIntegrityAfterUpload = true
        }
    }
    // ...
}

  

迁移构件至不同的存储

TeamCity 服务器自带一个命令行工具，用于将构建工件从一个存储转移到另一个存储。您可以在项目设置 | 构件存储页面下载此工具。

当前，该工具支持以下迁移路径：

从本地目录到 Amazon S3 存储桶，反之亦然
从一个 Amazon S3 桶到另一个

我们也在努力支持其他云存储选项。

了解更多：制品迁移工具。

最后修改日期： 2025年 9月 3日