Amazon S3 与 S3 兼容存储
TeamCity 配备了 Amazon S3 Artifact Storage 插件,允许在 Amazon S3 桶中以及与 S3 兼容的桶中存储构建工件,比如 MinIO,Backblaze B2 等等。 S3 兼容存储可以在 AWS 和非 AWS 环境中托管。
导航至 Administration | <Your_Project> 页面并切换至 Artifacts Storage 标签页。
如果您希望您的新存储对所有 TeamCity 项目可用,打开 <Root project> 的设置。
如果您的新存储只应用于此项目及其子项目,那么可以编辑一个特定的项目。
内置的 TeamCity 工件存储默认显示并标记为活动状态。 点击 添加新储存 按钮以创建新的存储空间。
指定自定义存储名称,如有需要,还可以指定其内部使用的 ID。
将 Type 字段设置为 "AWS S3"。
选择一个现有的 AWS Connection,TeamCity 应使用它来访问您的 Amazon 资源。 如果没有合适的 AWS 连接存在,请点击 "+" 图标来添加一个。
tip
您无法使用归属于父项目且其 适用于子项目 设置已禁用的 AWS Connections。
然而,如果父项目已使用非共享连接配置了 S3 存储,那么这个存储仍可供子项目使用。
被选中的 AWS 连接使用的用户凭证(或者它扮演的 IAM 角色)应该具有以下权限以访问 S3 桶:
ListAllMyBuckets
获取存储桶位置
获取对象
ListBucket
PutObject
删除对象
获取加速配置
(如果启用了 Transfer Acceleration)
tip
在之前的 TeamCity 版本中,Artifacts 存储对话框允许您明确指定连接设置:访问密钥凭证,用户 IAM 角色,以及 TeamCity 是否应在 AWS 的默认位置查找凭证(默认提供商链设置)。
从2023.11版本开始,这些设置仅适用于 AWS Connections。 如果您正在从 TeamCity 的更早版本迁移,且您现有的 AWS S3 存储使用了这些设置中的任何一个,请点击 转换为 AWS 连接 链接。 此操作将 AWS 相关设置转移至新的 AWS 连接,并将此新连接选为您存储的源连接。
TeamCity 使用选定的 AWS 连接来获取可用的 S3 桶的列表。 打开 Bucket 下拉菜单,从列表中选择特定项目。
(可选)如果您想要为所有 TeamCity 项目使用相同的 S3 桶,并配置基于前缀的权限,请指定 path prefix。
Amazon S3 存储桶支持两种加速文件上传和下载的选项:
AWS CloudFront—— 这是一个内容分发网络(CDN),允许 TeamCity 使用低延迟的 CloudFront 服务器进行附件的传输。
传输加速—— 这是一个针对存储桶级别设计的功能,旨在优化全球到集中式 S3 存储桶的传输速度。 它可以实现您的客户端与 S3 桶之间长距离、快速、便捷且安全的文件传输。
如果您的存储桶已配置为使用 Transfer Acceleration 或 CloudFront,请在 传输加速 部分下选择相应的选项。 否则,如果您希望 TeamCity 以常规模式传输文件,请选择 None 类型。
note
选择 AWS CloudFront 选项需要设置额外的字段。 参阅此部分以获取更多信息:通过 CloudFront 传输工件。
note
使用 Transfer Acceleration 将应用以下限制:
虚拟主机寻址始终处于开启状态。 不支持路径式请求。
您的 S3 桶必须启用 Transfer Acceleration。
桶 的名称中不能含有点(.)。
AWS Connection 访问您的存储桶所使用的用户凭证或 IAM 角色必须包含
获取加速配置
权限。
为了优化大文件到存储的 上传 ,您可以启用 多部分上传。 为了实现这一点,请勾选 自定义阈值和部分大小 的设置,并设置多部分上传阈值。 允许的最小值是
5MB
。 支持的后缀名:KB
、MB
、GB
、TB
。 如果您将此字段留空,所有大于8 MB(8MB
是默认值)的文件将自动启动多部分上传。另外,您可以配置每个上传文件部分的最大允许大小。 最小值为
5MB
。 如果留空,TeamCity 将使用8MB
作为默认值。tip
我们建议您配置一个 bucket 生命周期策略 来防止多部分上传不完整。
取消选中 强制虚拟主机寻址 选项,以关闭 相应功能(默认启用)。 目前,TeamCity 支持托管式和路径式的请求。 请注意,自2020年9月以来,Amazon 停止支持路径样式访问新的存储桶。
note
如果您的存储使用了 Transfer Acceleration,则无法禁用此设置。
勾选 上传后验证文件完整性,允许 TeamCity 对上传的文件进行额外的 检查。 如果完整性验证失败,TeamCity将在构建日志中写入相应的消息。
点击 Save 以保存您的新存储并返回至可用存储的列表。
note
如果您的构建代理部署在代理服务器后面,您还必须在构建代理上配置代理设置。 请查看 使用代理进行出站构建代理连接。
当查看项目可用的存储列表时,点击设为活动开始为该项目的所有新构建使用对应的存储。 has N usages 链接允许您查看哪些构建使用了此存储来上传他们的构建工件。

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

Amazon S3 存储类别允许您根据存储的期望性能,以及数据的可用性和弹性进行精细调整。
有两种方式可以启用所需的存储类:
在 TeamCity 端。 当向 S3 桶上传工件时,TeamCity 会在其
x-amz-storage-class
请求中添加PUT
头。 标头值取决于 TeamCity 中相应的存储设置(例如,x-amz-storage-class: INTELLIGENT_TIERING
)。 这种模式在 AWS方面不需要任何额外的设置。虽然目前我们还不支持这种方法,但我们希望在未来的发布周期中实现这个功能。 赞成并评论这个 YouTrack 工单以支持该功能并分享您的反馈:TW-79992。
在 AWS 端。 在此模式下,TeamCity以规定的方式上传工件,预设的生命周期规则在工件上传后应用所需的存储类别。 要设置此规则,请按照以下步骤操作:
打开所需的 S3 存储,然后切换到 管理 标签。
点击 创建生命周期规则。
在 生命周期规则操作 部分下找到并检查 在存储类之间移动对象的当前版本。
选择所需的存储类别和上传与转换日期之间的延迟。 将 对象创建后的天数 设置为 "0" ,以便在 TeamCity 上传它们后立即过渡您的工件。
tip
TeamCity 不支持存档存储类,因为它们的文件不可立即获取,需要进行额外的解压/预热操作才能取回。
启用存储的工件的附加规则。 例如,您可以勾选 到期当前版本的对象 来标记之前上传的工件为已过期,以及 永久删除非当前版本的对象 来定期清理您的存储空间。
指定规则范围,以选择其应用于整个存储还是仅应用于符合所需过滤器的那些工件。
在页面底部复查您的规则。 它可能如下所示:
点击 创建规则 保存您的生命周期规则。
请参阅以下 AWS 帮助文章以获取更多信息:使用 Amazon S3 存储类别。
Amazon CloudFront 是一个内容分发网络,提供低延迟和高传输速度。 启用其对 S3 存储的支持将允许 TeamCity 通过最近的 CloudFront 服务器传输构建工件。 如果您的 S3 存储桶位于与您的 TeamCity 基础设施不同的区域,这可能会大大加快工件的上传/下载速度,并减少费用。
tip
如果您使用位于与目标 S3 桶相同区域的 EC2 构建代理,这些代理将直接与桶进行通信,省略 CloudFront。
TeamCity 可以为您设置 CloudFront 集成,或者您可以手动设置所有设置。
CloudFront 集成需要进行配置:
一个 OAI 用户
两个 CloudFront distributions,一个用于上传和下载工件。
一个 受信任的密钥组
一个 SSH-2 RSA 密钥对(公钥 + 私钥)以 PEM 格式存储
当您将存储类型切换到 AWS CloudFront 时,将出现四个新的设置。
另外,您可以点击 图标,让 TeamCity 自动配置所有四个设置。
为了使 Cloudfront 设置正常工作,TeamCity 需要以下权限:
cloudfront:ListDistributions
cloudfront:ListKeyGroups
cloudfront:ListPublicKeys
TeamCity 可以自动配置设置。 这涉及到:
生成密钥对并上传公钥到 CloudFront。
在 CloudFront 中创建新的密钥组。
创建两个新的分布,具体如下:
使用所有边缘位置价格类别。
一个新的 Origin Access Identity 可以访问当前的存储桶。
定义的默认行为
将新策略添加到 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>"
}
]
}
出于安全原因,我们建议配置两个单独的分发,用于上传和下载工件。 对于每个分发版:
生成一对 SSH-2 RSA 密钥格式 的密钥对。
将密钥对中的公钥上传到 CloudFront。
在 CloudFront 中添加一个新的密钥组,并将创建的公钥添加到此组中。
创建一个新的缓存策略,将 缓存键设置 | 查询字符串 设置为 全部。
如果您使用的是私有存储桶,请创建一个新的 OAI 用户。
创建一个分发并将您的密钥组附加到它上:
确保选择与在 TeamCity 中指定的相同的 S3 桶。
允许的 HTTP 方法用于上传工件
GET
,头部
,选项
,PUT
,POST
,PATCH
,DELETE
;用于下载GET
,头部
,选项
限制观看者访问:是
受信任的授权类型:受信任的密钥组
缓存键和源请求:缓存策略和源请求策略
对于私有存储桶,启用 use OAI 选项并使用以下设置配置 OAI:
Bucket 策略: 不,我将更新 Bucket 策略
对于公共桶,禁用 阻止公共访问 选项。
为您的 S3 桶添加新策略。 参见 策略示例。
当配置后,分发应该自动出现在 下载分发 和 上传分发 的下拉菜单中。
选择目标 CloudFront 分发。
在 Public key 中,选择与此分发相关联的公钥。
点击 Upload private key... 按钮上传配对中的私钥。
保存存储设置。
通过 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>/*"
}
以下示例说明了如何将 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
}
}
// ...
}
tip
为了快速获取应用于检索所需存储桶的 AWS Connection 的 ID, 请导航至所需的 Administration | <Your_Project> | Connections 页面。
TeamCity 服务器自带一个 命令行工具,用于将构建工件从一个存储转移到另一个存储。 您可以在 Project Settings | Artifacts Storage 页面上下载此工具。

当前,该工具支持以下迁移路径:
从本地目录到 Amazon S3 存储桶,反之亦然
从一个 Amazon S3 桶到另一个
我们也在努力支持其他云存储选项。
了解更多:制品迁移工具。
感谢您的反馈!