对象存储

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

选项

极狐GitLab 与 Fog 紧密集成,因此您可以参考它的文档,查看哪些存储服务可以与极狐GitLab 集成。

具体来说,极狐GitLab 已在多家对象存储提供商上经过供应商和客户的测试:

配置指南

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

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

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

整合对象存储配置

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

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

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

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

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

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

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

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

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

当合并形式为:

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

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

使用 AWS S3

以下示例使用 AWS S3 为所有支持的服务启用对象存储:

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'] = 'gitlab-artifacts'
     gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
     gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
     gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
     gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
     gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
     gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
     gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
     gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
    

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

     gitlab_rails['object_store']['connection'] = {
       'provider' => 'AWS',
       'region' => 'eu-central-1',
       'use_iam_profile' => true
     }
    
  2. 保存文件并重新配置极狐GitLab,使更改生效。

    sudo gitlab-ctl reconfigure
    

Kubernetes

  1. 将以下内容放入名为 object_storage.yaml 的文件中,用作 Kubernetes Secret

    provider: AWS
    region: us-east-1
    aws_access_key_id: <AWS_ACCESS_KEY_ID>
    aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
    

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

    provider: AWS
    region: us-east-1
    use_iam_profile: true
    
  2. 创建 Kubernetes Secret:

    kubectl create secret generic -n <namespace> gitlab-object-storage --from-file=connection=object_storage.yaml
    
  3. 导出 Helm 值:

    helm get values gitlab > gitlab_values.yaml
    
  4. 编辑 gitlab_values.yaml

    global:
      appConfig:
        object_store:
          enabled: false
          proxy_download: true
          storage_options: {}
            # server_side_encryption:
            # server_side_encryption_kms_key_id
          connection:
            secret: gitlab-object-storage
        lfs:
          enabled: true
          proxy_download: true
          bucket: gitlab-lfs
          connection: {}
            # secret:
            # key:
        artifacts:
          enabled: true
          proxy_download: true
          bucket: gitlab-artifacts
          connection: {}
            # secret:
            # key:
        uploads:
          enabled: true
          proxy_download: true
          bucket: gitlab-uploads
          connection: {}
            # secret:
            # key:
        packages:
          enabled: true
          proxy_download: true
          bucket: gitlab-packages
          connection: {}
        externalDiffs:
          enabled: true
          when:
          proxy_download: true
          bucket: gitlab-mr-diffs
          connection: {}
        terraformState:
          enabled: true
          bucket: gitlab-terraform-state
          connection: {}
        ciSecureFiles:
          enabled: true
          bucket: gitlab-ci-secure-files
          connection: {}
        dependencyProxy:
          enabled: true
          proxy_download: true
          bucket: gitlab-dependency-proxy
          connection: {}
    
  5. 保存文件并应用新值:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    

Docker

  1. 编辑 docker-compose.yml

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            # 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'] = 'gitlab-artifacts'
            gitlab_rails['object_store']['objects']['external_diffs']['bucket'] = 'gitlab-mr-diffs'
            gitlab_rails['object_store']['objects']['lfs']['bucket'] = 'gitlab-lfs'
            gitlab_rails['object_store']['objects']['uploads']['bucket'] = 'gitlab-uploads'
            gitlab_rails['object_store']['objects']['packages']['bucket'] = 'gitlab-packages'
            gitlab_rails['object_store']['objects']['dependency_proxy']['bucket'] = 'gitlab-dependency-proxy'
            gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = 'gitlab-terraform-state'
            gitlab_rails['object_store']['objects']['ci_secure_files']['bucket'] = 'gitlab-ci-secure-files'
            gitlab_rails['object_store']['objects']['pages']['bucket'] = 'gitlab-pages'
    

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

    gitlab_rails['object_store']['connection'] = {
      'provider' => 'AWS',
      'region' => 'eu-central-1',
      'use_iam_profile' => true
    }
    
  2. 保存文件并重启极狐GitLab:

    docker compose up -d
    

源安装

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

    production: &base
      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: gitlab-artifacts
          external_diffs:
            bucket: gitlab-mr-diffs
          lfs:
            bucket: gitlab-lfs
          uploads:
            bucket: gitlab-uploads
          packages:
            bucket: gitlab-packages
          dependency_proxy:
            bucket: gitlab-dependency-proxy
          terraform_state:
            bucket: gitlab-terraform-state
          ci_secure_files:
            bucket: gitlab-ci-secure-files
          pages:
            bucket: gitlab-pages
    

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

    connection:
      provider: AWS
      region: eu-central-1
      use_iam_profile: true
    
  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>"
    

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

    [object_storage.s3]
      use_iam_profile = true
    
  3. 保存文件并重启极狐GitLab,使更改生效。

    # For systems running systemd
    sudo systemctl restart gitlab.target
    
    # For systems running SysV init
    sudo service gitlab restart
    

常用参数

在统一配置中,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>'
}
设置 描述
enabled 启用或禁用对象存储。
proxy_download 设置为 true启用代理所有提供的文件。选项允许减少出口流量,因为这允许客户端直接从远程存储下载而不是代理所有数据。
connection 下面描述了各种连接选项
storage_options 保存新对象时使用的选项,例如服务器端加密。在 13.3 版本中引入。
objects 特定于对象的配置

连接设置

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

S3 兼容的连接设置

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

设置 描述 默认值
provider 对于兼容的主机,始终使用 AWSAWS
aws_access_key_id AWS 凭证,或兼容的凭证。  
aws_secret_access_key AWS 凭证,或兼容的凭证。  
aws_signature_version 要使用的 AWS 签名版本。24 是有效选项。Digital Ocean Spaces 和其他提供商可能需要 24
enable_signature_v4_streaming 设置为 true 以启用具有 AWS v4 签名 的 HTTP 分块传输。Oracle Cloud S3 需要将其设为 falsetrue
region AWS 区域。  
host 已废弃:使用 endpoint 代替。不使用 AWS 时的 S3 兼容主机。例如,localhoststorage.example.com。假定为 HTTPS 和端口 443。 s3.amazonaws.com
endpoint 可在配置 S3 兼容服务时使用,例如 MinIO,方法是输入 URL,例如 http://127.0.0.1:9000。这优先于 host。始终使用 endpoint 作为统一形式。 (可选)
path_style 设置为 true 以使用 host/bucket_name/object 样式路径而不是 bucket_name.host/object。设置为 true 来使用 MinIO。对于 AWS S3,保留为 falsefalse
use_iam_profile 设置为 true 以使用 IAM 配置文件而不是访问密钥。 false
aws_credentials_refresh_threshold_seconds 在 IAM 中使用临时凭证时设置自动刷新阈值15

Oracle Cloud S3 连接设置

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

设置
enable_signature_v4_streaming false
path_style true

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

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

Google Cloud Storage (GCS)

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

设置 描述 示例
provider Provider 名称。 Google
google_project GCP 项目名称。 gcp-project-12345
google_json_key_location JSON 密钥路径。 /path/to/gcp-project-12345-abcde.json
google_application_default 设置为 true 以使用 Google Cloud Application Default Credentials 来查找服务帐户凭据。  
google_json_key_string JSON key 字符串。 { "type": "service_account", "project_id": "example-project-382839", ... }
google_application_default 设置为 true 以使用 Google Cloud Application Default Credentials,找到服务帐户凭据。  

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

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

note不支持使用 Cloud Key Management Service (KMS) 的存储桶加密,这将导致 ETag 不匹配错误
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,请确保:

Azure Blob storage

引入于 13.4 版本。

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

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

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

设置 描述 示例
provider Provider 名称。 AzureRM
azure_storage_account_name 用于访问存储的 Azure Blob 存储帐户的名称。 azuretest
azure_storage_access_key 用于访问容器的存储帐户访问密钥。通常是一个以 base64 编码的 secret 512 位加密密钥。 czV2OHkvQj9FKEgrTWJRZVRoV21ZcTN0Nnc5eiRDJkYpSkBOY1JmVWpYbjJy\nNHU3eCFBJUQqRy1LYVBkU2dWaw==\n
azure_storage_domain 用于连接 Azure Blob 存储 API 的域名(可选)。默认为 blob.core.windows.net。如果您使用的是 Azure 中国、Azure 德国或其他一些自定义 Azure 域,请设置此选项。 blob.core.windows.net
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 部分如何定义特定于对象的配置块以及如何覆盖 enabledproxy_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 列表:

类型 描述
artifacts CI 产物
external_diffs 合并请求差异
uploads 用户上传文件
lfs Git 大文件存储对象
packages 项目包(例如,PyPI、Maven 或 NuGet)
dependency_proxy 依赖代理
terraform_state Terraform 状态文件
pages Pages

在每个对象类型中,可以定义三个参数:

设置 是否必需 描述
bucket Yes 对象存储的桶名。
enabled No 覆盖公共参数。
proxy_download No 覆盖公共参数。

有选择地禁用对象存储

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

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

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

gitlab_rails['artifacts_enabled'] = false

迁移到对象存储

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

过渡到合并形式

在 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_enableduploads_object_store_connection)。

特定于存储的配置

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

对象存储类型 是否受合并配置支持?
备份 No
作业产物,包括存档的作业日志 Yes
LFS 对象 Yes
上传文件 Yes
Container Registry (optional feature) No
合并请求差异 Yes
Mattermost No
软件包(可选功能) Yes
依赖代理(可选功能) Yes
自动缩放 runner 缓存 (可选以提高性能) No
Terraform 状态文件 Yes
Pages 内容 Yes
caution不支持将加密 S3 存储桶与非合并配置一起使用。 如果您使用它,您可能会开始收到 ETag 不匹配错误

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

如果您正在横向扩展您的极狐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 不匹配错误,这可能是由于您的存储桶上的加密设置。要解决此问题,您有两种选择:

建议 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:

设置 描述
server_side_encryption 加密模式(AES256aws:kms)。
server_side_encryption_kms_key_id Amazon 资源名称。只有在 server_side_encryption 中使用 aws:kms 时才需要。请参阅有关使用 KMS 加密的 Amazon 文档

与默认加密的情况一样,这些选项仅在启用 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 服务器的对象存储配置以使用新的提供程序进行“上传”。