• 选项
• 配置指南
  • 整合对象存储配置
    • 常用参数
  • 连接设置
    • S3 兼容的连接设置
    • Oracle Cloud S3 连接设置
    • Google Cloud Storage (GCS)
      • Google 示例（合并形式）
      • 带有 ADC 的 Google 示例（合并形式）
    • Azure Blob storage
      • Azure 示例（合并形式）
  • 特定于对象的配置
    • 有选择地禁用对象存储
  • 迁移到对象存储
  • 过渡到合并形式
  • 特定于存储的配置
  • 文件系统存储的其他替代方案
• 警告、限制和已知问题
  • 极狐GitLab 备份中不包含对象
  • 使用单独的桶
  • S3 API 兼容性问题
  • 代理下载
  • ETag 不匹配
  • 使用 Amazon 实例配置文件
    • 加密的 S3 存储桶
      • 服务器端加密 headers
    • IAM 权限
  • 多线程复制
• 将对象迁移到不同的对象存储提供程序

对象存储

极狐GitLab 支持使用对象存储服务来保存多种类型的数据。 建议在 NFS 上使用它，并且通常在较大的设置中更好，因为对象存储通常具有更高的性能、可靠性和可扩展性。

选项

极狐GitLab 已在多家对象存储提供商上经过供应商和客户的测试：

• Amazon S3
• Google Cloud Storage
• Digital Ocean Spaces
• Oracle Cloud Infrastructure
• OpenStack Swift (S3 compatible mode)
• Azure Blob storage
• 来自各种存储供应商的本地硬件和设备，其列表尚未正式确定。
• MinIO。我们的 Helm Chart 文档中有部署指南。

配置指南

极狐GitLab 中有两种指定对象存储配置的方法：

• 合并形式：所有支持的对象类型共享一个凭证。
• 存储特定形式：每个对象定义自己的对象存储连接和配置。

有关差异以及从一种形式过渡到另一种形式的更多信息，请参阅过渡到合并形式。

如果您当前正在本地存储数据，请参阅迁移到对象存储，了解迁移详细信息。

整合对象存储配置

使用整合的对象存储配置有很多优点：

• 它可以简化您的极狐GitLab 配置，因为连接详细信息在对象类型之间共享。
• 它允许使用加密的 S3 存储桶。
• 它使用正确的 Content-MD5 header 将文件上传到 S3。

由于必须启用直接上传模式，因此只能使用以下提供程序：

• Amazon S3-compatible providers
• Google Cloud Storage
• Azure Blob storage

使用整合对象存储时，会自动启用直接上传。不支持后台上传。对于特定于存储的配置，直接上传可能会成为默认设置，因为它不需要共享文件夹。

合并对象存储配置不能用于备份或 Mattermost。请参阅完整列表。但是，备份可以单独配置服务器端加密。

启用整合对象存储可为所有对象类型启用对象存储。如果未指定所有存储桶，sudo gitlab-ctl reconfigure 可能会失败并出现如下错误：

Object storage for <object type> must have a bucket specified

如果您想为特定对象类型使用本地存储，您可以选择性地禁用对象存储。

通过为具有多个存储桶的对象存储指定单个凭据，可以将大多数类型的对象（例如 CI 产物、LFS 文件、上传附件等）保存在对象存储中。

当合并形式为：

• 与 S3 兼容的对象存储一起使用，Workhorse 使用其内部 S3 客户端上传文件。
• 不与 S3 兼容的对象存储一起使用，Workhorse 回退到使用预签名 URL。

有关详细信息，请参阅 ETag 不匹配错误部分。

Omnibus 安装实例：

1. 编辑 /etc/gitlab/gitlab.rb 并添加以下行，替换您想要的值：

    # Consolidated object storage configuration
    gitlab_rails['object_store']['enabled'] = true
    gitlab_rails['object_store']['proxy_download'] = true
    gitlab_rails['object_store']['connection'] = {
      'provider' => 'AWS',
      'region' => '<eu-central-1>',
      'aws_access_key_id' => '<AWS_ACCESS_KEY_ID>',
      'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
    }
    # OPTIONAL: The following lines are only needed if server side encryption is required
    gitlab_rails['object_store']['storage_options'] = {
      'server_side_encryption' => '<AES256 or aws:kms>',
      'server_side_encryption_kms_key_id' => '<arn:aws:kms:xxx>'
    }
    gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<artifacts>'
    gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = '<external-diffs>'
    gitlab_rails['object_store']['objects']['lfs']['bucket'] = '<lfs-objects>'
    gitlab_rails['object_store']['objects']['uploads']['bucket'] = '<uploads>'
    gitlab_rails['object_store']['objects']['packages']['bucket'] = '<packages>'
    gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = '<dependency-proxy>'
    gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>'
    gitlab_rails['object_store']['objects']['pages']['bucket'] = '<pages>'
   

   如果您使用 AWS IAM 配置文件，请省略 AWS 访问密钥和秘密访问密钥/值对。例如：

   gitlab_rails['object_store']['connection'] = {
     'provider' => 'AWS',
     'region' => '<eu-central-1>',
     'use_iam_profile' => true
   }
   

2. 保存文件并重新配置极狐GitLab，使更改生效。

源安装实例：

1. 编辑 /home/git/gitlab/config/gitlab.yml 并添加或修改以下行：

   object_store:
     enabled: true
     proxy_download: true
     connection:
       provider: AWS
       aws_access_key_id: <AWS_ACCESS_KEY_ID>
       aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
       region: <eu-central-1>
     storage_options:
       server_side_encryption: <AES256 or aws:kms>
       server_side_encryption_key_kms_id: <arn:aws:kms:xxx>
     objects:
       artifacts:
         bucket: <artifacts>
       external_diffs:
         bucket: <external-diffs>
       lfs:
         bucket: <lfs-objects>
       uploads:
         bucket: <uploads>
       packages:
         bucket: <packages>
       dependency_proxy:
         bucket: <dependency_proxy>
       terraform_state:
         bucket: <terraform>
       pages:
         bucket: <pages>
   

2. 编辑 /home/git/gitlab-workhorse/config.toml 并添加或修改以下行：

   [object_storage]
     provider = "AWS"
   
   [object_storage.s3]
     aws_access_key_id = "<AWS_ACCESS_KEY_ID>"
     aws_secret_access_key = "<AWS_SECRET_ACCESS_KEY>"
   

3. 保存文件并重启极狐GitLab，使更改生效。

常用参数

在统一配置中，object_store 部分定义了一组通用参数。这里我们使用源安装中的 YAML，因为它更容易看到继承：

    object_store:
      enabled: true
      proxy_download: true
      connection:
        provider: AWS
        aws_access_key_id: <AWS_ACCESS_KEY_ID>
        aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
      objects:
        ...

Omnibus 配置直接映射到此：

gitlab_rails['object_store']['enabled'] = true
gitlab_rails['object_store']['proxy_download'] = true
gitlab_rails['object_store']['connection'] = {
  'provider' => 'AWS',
  'aws_access_key_id' => '<AWS_ACCESS_KEY_ID',
  'aws_secret_access_key' => '<AWS_SECRET_ACCESS_KEY>'
}

连接设置

统一配置表单和存储特定配置表单都必须配置连接。以下部分描述了可以在 connection 设置中使用的参数。

S3 兼容的连接设置

连接设置与 fog-aws 提供的设置相匹配：

Oracle Cloud S3 连接设置

Oracle Cloud S3 必须确保使用以下设置：

如果 enable_signature_v4_streaming 设置为 true，您可能会看到 production.log 中的以下错误：

STREAMING-AWS4-HMAC-SHA256-PAYLOAD is not supported

Google Cloud Storage (GCS)

以下是 GCS 的有效连接参数：

极狐GitLab 读取 google_json_key_location 的值，然后是 google_json_key_string，最后是 google_application_default。它使用以上具有值的设置中的第一个。

服务帐户必须有权访问存储桶。在 Google 的 Cloud Storage 身份验证文档中了解更多信息。

Google 示例（合并形式）

对于 Omnibus 安装实例，这是 connection 设置的示例：

gitlab_rails['object_store']['connection'] = {
  'provider' => 'Google',
  'google_project' => '<GOOGLE PROJECT>',
  'google_json_key_location' => '<FILENAME>'
}

带有 ADC 的 Google 示例（合并形式）

引入于 13.6 版本。

Google Cloud 应用程序默认凭据 (ADC) 通常与极狐GitLab 一起使用，使用默认服务帐户，消除了为实例提供凭据的需要。例如：

gitlab_rails['object_store']['connection'] = {
  'provider' => 'Google',
  'google_project' => '<GOOGLE PROJECT>',
  'google_application_default' => true
}

如果您使用 ADC，请确保：

• 您使用的服务帐户具有 iam.serviceAccounts.signBlob 权限。通常这是通过将 Service Account Token Creator 角色授予服务帐户来完成的。

• 您的虚拟机具有访问 Google Cloud API 的正确访问范围。如果机器没有正确的范围，错误日志可能会显示：

  Google::Apis::ClientError (insufficientPermissions: Request had insufficient authentication scopes.)
  

Azure Blob storage

引入于 13.4 版本。

尽管 Azure 使用 container 一词来表示 blob 的集合，但极狐GitLab 将 bucket 一词标准化。请务必在 bucket 设置中配置 Azure 容器名称。

Azure Blob 存储只能与合并形式一起使用，因为一组凭据用于访问多个容器。不支持存储特定形式。有关更多详细信息，请参阅如何转换为合并形式。

以下是 Azure 的有效连接参数。阅读 Azure Blob 存储文档，了解更多信息。

Azure 示例（合并形式）

对于 Omnibus 安装示例，以下是 connection 设置的示例：

gitlab_rails['object_store']['connection'] = {
  'provider' => 'AzureRM',
  'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>',
  'azure_storage_access_key' => '<AZURE STORAGE ACCESS KEY>',
  'azure_storage_domain' => '<AZURE STORAGE DOMAIN>'
}

Azure Workhorse 设置（仅限源安装）

对于源安装，Workhorse 还需要配置 Azure 凭据。在 Omnibus 安装中不需要，因为 Workhorse 设置是从以前的设置中填充的。

1. 编辑 /home/git/gitlab-workhorse/config.toml 并添加或修改以下行：

   [object_storage]
     provider = "AzureRM"
   
   [object_storage.azurerm]
     azure_storage_account_name = "<AZURE STORAGE ACCOUNT NAME>"
     azure_storage_access_key = "<AZURE STORAGE ACCESS KEY>"
   

如果您使用的是自定义 Azure 存储域，则必须在 Workhorse 配置中设置 azure_storage_domain。此信息在 Rails 和 Workhorse 之间的 API 调用中交换。

特定于对象的配置

以下 YAML 显示了 object_store 部分如何定义特定于对象的配置块以及如何覆盖 enabled 和 proxy_download 标志。bucket 是每种类型中唯一必需的参数：

  object_store:
      connection:
        ...
      objects:
        artifacts:
          bucket: artifacts
          proxy_download: false
        external_diffs:
          bucket: external-diffs
        lfs:
          bucket: lfs-objects
        uploads:
          bucket: uploads
        packages:
          bucket: packages
        dependency_proxy:
          enabled: false
          bucket: dependency_proxy
        terraform_state:
          bucket: terraform
        pages:
          bucket: pages

映射到以下 Omnibus 配置：

gitlab_rails['object_store']['objects']['artifacts']['bucket'] = 'artifacts'
gitlab_rails['object_store']['objects']['artifacts']['proxy_download'] = false
gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'external-diffs'
gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'lfs-objects'
gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'uploads'
gitlab_rails['object_store']['objects']['packages']['bucket'] = 'packages'
gitlab_rails['object_store']['objects']['dependency_proxy']['enabled'] = false
gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'dependency-proxy'
gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'terraform-state'
gitlab_rails['object_store']['objects']['pages']['bucket'] = 'pages'

以下是可以使用的有效 objects 列表：

在每个对象类型中，可以定义三个参数：

有选择地禁用对象存储

如上所示，可以通过将 enabled 标志设置为 false 来禁用特定类型的对象存储。例如，要禁用 CI 产物的对象存储：

gitlab_rails['object_store']['objects']['artifacts']['enabled'] = false

如果该功能完全禁用，则不需要存储桶。例如，使用此设置禁用 CI 产物，则不需要存储桶：

gitlab_rails['artifacts_enabled'] = false

迁移到对象存储

要将现有本地数据迁移到对象存储，请参阅以下指南：

• 作业产物，包括存档的作业日志
• LFS 对象
• 上传文件
• 合并请求差异
• 软件包（可选功能）
• 依赖代理
• Terraform 状态文件
• Pages 内容

过渡到合并形式

在 13.2 版本之前：

• 所有类型的对象（例如 CI/CD 产物、LFS 文件、上传附件等）的对象存储配置必须独立配置。
• 必须为每种类型复制对象存储连接参数，例如密码和端点 URL。

例如，Omnibus 安装实例可能具有以下配置：

# Original object storage configuration
gitlab_rails['artifacts_object_store_enabled'] = true
gitlab_rails['artifacts_object_store_direct_upload'] = true
gitlab_rails['artifacts_object_store_proxy_download'] = true
gitlab_rails['artifacts_object_store_remote_directory'] = 'artifacts'
gitlab_rails['artifacts_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }
gitlab_rails['uploads_object_store_enabled'] = true
gitlab_rails['uploads_object_store_direct_upload'] = true
gitlab_rails['uploads_object_store_proxy_download'] = true
gitlab_rails['uploads_object_store_remote_directory'] = 'uploads'
gitlab_rails['uploads_object_store_connection'] = { 'provider' => 'AWS', 'aws_access_key_id' => 'access_key', 'aws_secret_access_key' => 'secret' }

尽管这样提供了灵活性，因为它使极狐GitLab 可以跨不同的云提供商存储对象，但它也产生了额外的复杂性和不必要的冗余。由于极狐GitLab Rails 和 Workhorse 组件都需要访问对象存储，因此合并的形式避免了过多的凭据重复。

如果原始表单中的所有行都被省略，则仅使用合并的对象存储配置。要移动到合并形式，请删除原始配置（例如，artifacts_object_store_enabled 或 uploads_object_store_connection）。

特定于存储的配置

对于在 13.1 及更早版本中配置对象存储，或合并配置形式不支持的存储类型，请参阅以下指南：

文件系统存储的其他替代方案

如果您正在横向扩展您的极狐GitLab 实例，或添加容错和冗余，您可能正在考虑删除对块或网络文件系统的依赖关系。 请参阅以下附加指南：

1. 确保 git 用户主目录在本地磁盘上。
2. 配置 SSH 密钥的数据库查找，消除对共享 authorized_keys 文件的需要。
3. 防止作业日志使用本地磁盘。
4. 禁用 Pages 本地存储。

警告、限制和已知问题

极狐GitLab 备份中不包含对象

如我们的备份文档中所述，极狐GitLab 备份中不包含对象。您可以改为使用对象存储提供程序启用备份。

使用单独的桶

极狐GitLab 推荐为每种数据类型使用单独的存储桶。这确保了极狐GitLab 存储的各种类型的数据之间没有冲突。有计划在未来启用单个存储桶。

使用 Omnibus 和源安装，可以将单个真实存储桶拆分为多个虚拟存储桶。如果您的对象存储桶名为 my-gitlab-objects，您可以将上传配置为进入 my-gitlab-objects/uploads，将产物配置为 my-gitlab-objects/artifacts 等。应用程序的行为就像这些是单独的存储桶一样。请注意，存储桶前缀的使用可能无法与 Helm 备份一起正常工作。

基于 Helm 的安装需要单独的存储桶来处理备份恢复。

S3 API 兼容性问题

并非所有 S3 提供程序都与极狐GitLab 使用的 Fog 库完全兼容。production.log 中的错误：

411 Length Required

代理下载

客户端可以通过接收预先签名的限时 URL 或通过极狐GitLab 将数据从对象存储代理到客户端来下载对象存储中的文件。 直接从对象存储下载文件有助于减少极狐GitLab 需要处理的出口流量。

当文件存储在本地块存储或 NFS 上时，极狐GitLab 必须充当代理。 这不是对象存储的默认行为。

proxy_download 设置控制此行为：默认值通常为 false。 在每个用例的文档中验证这一点。如果您希望极狐GitLab 代理文件，请将其设置为 true。

当不代理文件时，极狐GitLab 会返回一个 HTTP 302 重定向，并带有一个预签名的、有时间限制的对象存储 URL。 这可能会导致以下一些问题：

• 如果极狐GitLab 使用非安全 HTTP 访问对象存储，客户端可能会生成 https->http 降级错误并拒绝处理重定向。对此的解决方案是极狐GitLab 使用 HTTPS。例如，LFS 会生成以下错误：

   LFS: lfsapi/client: refusing insecure redirect, https->http
  

• 客户端需要信任颁发对象存储证书的证书颁发机构，否则可能会返回常见的 TLS 错误，例如：

   x509: certificate signed by unknown authority
  

• 客户端需要对对象存储进行网络访问。网络防火墙可能会阻止访问。如果没有进行此访问，可能导致的错误包括：

   Received status code 403 from server: Forbidden
  

软件包仓库文档中特别提到了获取 403 Forbidden 响应，这是某些构建工具工作方式的副作用。

此外，在短时间内，用户可以与其他人共享预先签名的、有时间限制的对象存储 URL，而无需进行身份验证。此外，对象存储提供商和客户端之间可能会产生带宽费用。

ETag 不匹配

使用默认的极狐GitLab 设置，一些对象存储后端（例如 MinIO 和阿里巴巴）可能会产生 ETag mismatch 错误。

如果您在 Amazon Web Services S3 中看到此 ETag 不匹配错误，这可能是由于您的存储桶上的加密设置。要解决此问题，您有两种选择：

• 使用合并对象配置。
• 使用 Amazon 实例配置文件。

建议 MinIO 使用第一个选项。否则，MinIO 的解决方法是在服务器上使用 --compat 参数。

在未启用整合对象存储配置或实例配置文件的情况下，极狐GitLab Workhorse 使用未为其计算 Content-MD5 HTTP header 的预签名 URL 将文件上传到 S3。为确保数据没有损坏，Workhorse 检查发送数据的 MD5 哈希是否等于从 S3 服务器返回的 ETag header。启用加密后，情况并非如此，这会导致 Workhorse 在上传期间报告 ETag mismatch 错误。

借助整合的对象配置和实例配置文件，Workhorse 拥有 S3 凭据，因此它可以计算 Content-MD5 header，消除了比较从 S3 服务器返回的 ETag header 的需要。

不支持使用 GCS 的 Cloud Key Management Service (KMS) 加密存储桶，这会导致 ETag 不匹配错误。

使用 Amazon 实例配置文件

可以将极狐GitLab 配置为使用 IAM 角色来设置 Amazon 实例配置文件，而不是在对象存储配置中提供 AWS 访问和密钥。 使用此功能时，极狐GitLab 会在每次访问 S3 存储桶时获取临时凭证，因此配置中不需要硬编码值。

加密的 S3 存储桶

当使用实例配置文件或整合对象配置进行配置时，极狐GitLab Workhorse 会将文件正确上传到具有默认启用 SSE-S3 或 SSE-KMS 加密的 S3 存储桶。不支持客户主密钥 (CMK) 和 SSE-C 加密，因为这需要在每个请求中发送加密密钥。

服务器端加密 headers

引入于 13.3 版本。

在 S3 存储桶上设置默认加密是启用加密的最简单方法，但您可能需要设置存储桶策略以确保仅上传加密对象。为此，您必须将极狐GitLab 配置为在 storage_options 配置部分中发送正确的加密 headers：

与默认加密的情况一样，这些选项仅在启用 Workhorse S3 客户端时有效。必须满足以下两个条件之一：

• use_iam_profile 在连接设置中为 true。
• 合并对象存储设置正在使用中。

ETag 不匹配错误如果在未启用 Workhorse S3 客户端的情况下使用服务器端加密 headers，则会发生。

IAM 权限

要设置实例配置文件：

1. 创建具有必要权限的 Amazon 身份访问和管理 (IAM) 角色。以下示例是名为 test-bucket 的 S3 存储桶的角色：

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:DeleteObject"
               ],
               "Resource": "arn:aws:s3:::test-bucket/*"
           }
       ]
   }
   

2. 附加此角色到托管您的极狐GitLab 实例的 EC2 实例。
3. 通过 use_iam_profile 配置选项配置极狐GitLab 以使用它。

多线程复制

极狐GitLab 使用 S3 Upload Part Copy API 来加速桶内文件的复制。Ceph S3 Kraken 11.0.2 之前不支持这一点，并且在上传过程中复制文件时返回 404 错误。

可以使用 :s3_multithreaded_uploads 功能标志禁用该功能。要禁用该功能，请让具有 Rails 控制台访问权限的极狐GitLab 管理员运行以下命令：

Feature.disable(:s3_multithreaded_uploads)

将对象迁移到不同的对象存储提供程序

您可能需要将对象存储中的极狐GitLab 数据迁移到不同的对象存储提供程序。以下步骤向您展示如何使用 Rclone 执行此操作。

这些步骤假设您正在移动 uploads 存储桶，但相同的过程适用于其他存储桶。

先决条件：

• 选择要运行 Rclone 的计算机。根据您要迁移的数据量，Rclone 可能需要运行很长时间，因此您应该避免使用可以省电的笔记本电脑或台式电脑。你可以使用极狐GitLab 服务器来运行 Rclone。

1. 安装 Rclone。

2. 通过运行以下命令配置 Rclone：

   rclone config
   

   配置过程是交互式的。 添加至少两个“远端”：一个用于您的数据当前所在的对象存储提供程序（old），另一个用于您要移动到的提供程序（new）。

3. 验证是否可以读取旧数据。以下示例引用了 uploads 存储桶，但您的存储桶可能有不同的名称：

   rclone ls old:uploads | head
   

   这应该打印当前存储在您的 uploads 存储桶中的对象的部分列表。如果您收到错误，或者列表为空，请返回并使用 rclone config 更新您的 Rclone 配置。

4. 执行初始复制。对于此步骤，您不需要使极狐GitLab 服务器脱机。

   rclone sync -P old:uploads new:uploads
   

5. 首次同步完成后，使用新对象存储提供商的 Web UI 或命令行界面验证新存储桶中是否有对象。如果没有，或者在运行 rclone sync 时遇到错误，请检查您的 Rclone 配置并重试。

从旧位置到新位置至少完成一次成功的 Rclone 复制后，安排维护并让极狐GitLab 服务器脱机。在维护窗口期间，您必须做两件事：

1. 执行最终的 rclone sync 运行，知道您的用户无法添加新对象，因此您不会在旧存储桶中留下任何对象。
2. 更新极狐GitLab 服务器的对象存储配置以使用新的提供程序进行“上传”。