极狐GitLab 容器镜像仓库管理

借助极狐GitLab 容器镜像仓库，每个项目都可以拥有自己的空间来存储 Docker 镜像。

有关 Distribution Registry 的更多详情：

• 配置
• 存储驱动
• 部署 registry 服务器

本文档是管理员指南。要了解如何使用极狐GitLab 容器镜像仓库，请参阅用户文档。

启用容器镜像仓库#

启用容器镜像仓库的流程取决于你所使用的安装类型。

Linux 安装包安装#

如果你使用 Linux 安装包安装了极狐GitLab，容器镜像仓库可能默认可用，也可能不可用。

若你使用内置的 Let's Encrypt 集成，容器镜像仓库会自动启用并在你的极狐GitLab 域名端口 5050 上可用。

否则，容器镜像仓库默认不启用。要启用它：

• 你可以为其配置极狐GitLab 域名，或者
• 你可以为其配置不同的域名。

容器镜像仓库默认通过 HTTPS 工作。你也可以使用 HTTP，但不推荐且超出了本文档范围。

Helm Charts 安装#

对于 Helm Charts 安装，请参阅 Helm Charts 文档中的使用容器镜像仓库。

自行编译安装#

如果你自行编译安装了极狐GitLab：

1. 你必须使用与你所安装极狐GitLab 版本对应的镜像来部署 registry（例如：registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab）
2. 安装完成后，要启用它，你必须在 gitlab.yml 中配置 Registry 的设置。
3. 使用 lib/support/nginx/registry-ssl 下的 NGINX 配置文件示例，并对其进行编辑以匹配 host、port 和 TLS 证书路径。

gitlab.yml 的内容如下：

yaml
1registry:
2  enabled: true
3  host: <registry.gitlab.example.com>
4  port: <5005>
5  api_url: <http://localhost:5000/>
6  key: <config/registry.key>
7  path: <shared/registry>
8  issuer: <gitlab-issuer>

其中：

如果你从源代码安装极狐GitLab，则不会随附 Registry 初始化文件。 因此，如果你修改其设置，重启极狐GitLab 不会重启 Registry。请阅读上游文档了解如何实现。

至少，请确保你的 Registry 配置中将 container_registry 作为服务，并将 https://gitlab.example.com/jwt/auth 作为 realm：

yaml
1auth:
2  token:
3    realm: <https://gitlab.example.com/jwt/auth>
4    service: container_registry
5    issuer: gitlab-issuer
6    rootcertbundle: /root/certs/certbundle

容器镜像仓库域名配置#

你可以通过以下任一方式配置 Registry 的外部域名：

• 使用现有的极狐GitLab 域名。Registry 在一个端口上监听，并复用极狐GitLab 的 TLS 证书。
• 使用一个完全独立的域名，并为该域名配置新的 TLS 证书。

由于容器镜像仓库需要一个 TLS 证书，成本可能是一个需要考虑的因素。

在首次配置容器镜像仓库之前，请考虑这一点。

在现有极狐GitLab 域名下配置容器镜像仓库#

如果容器镜像仓库配置为使用现有的极狐GitLab 域名，你可以将容器镜像仓库暴露在一个端口上。这样，你可以复用现有的极狐GitLab TLS 证书。

如果极狐GitLab 域名是 https://gitlab.example.com，对外端口是 5050，要配置容器镜像仓库：

• 如果你使用的是 Linux 安装包，请编辑 gitlab.rb。
• 如果你使用的是自行编译安装，请编辑 gitlab.yml。

请确保你选择的端口与 Registry 监听的端口（默认为 5000）不同，否则会发生冲突。

ruby
registry_external_url '<https://registry-gitlab.example.com>'
registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678

用户现在应该可以使用他们的极狐GitLab 凭据登录容器镜像仓库：

shell
docker login <gitlab.example.com:5050>

在自己的域名下配置容器镜像仓库#

当 Registry 配置为使用其自己的域名时，你需要为该特定域（例如 registry.example.com）申请一个 TLS 证书。如果托管在你现有极狐GitLab 域名的子域下，你可能需要一个通配符证书。例如，*.gitlab.example.com 是一个匹配 registry.gitlab.example.com 的通配符，并且与 *.example.com 不同。

除了手动生成的 SSL 证书（在此处解释）外，Linux 安装包也支持通过 Let's Encrypt 自动生成的证书。

假设你希望容器镜像仓库可以通过 https://registry.gitlab.example.com 访问。

ruby
registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"

用户现在应该可以使用他们的极狐GitLab 凭据登录容器镜像仓库：

shell
docker login <registry.gitlab.example.com>

配置自签名证书#

如果你想在容器镜像仓库中使用自签名证书，你必须配置 Docker 守护进程信任自签名证书：

1. 指导 Docker 守护程序使用自签名证书。这些步骤因你的操作系统而异。

2. 在极狐GitLab Runner config.toml 文件中，挂载 Docker 守护进程并设置 privileged = false：

   toml
     [runners.docker]
       image = "ruby:2.6"
       privileged = false
       volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]

   设置 privileged = true 会优先于 Docker 守护进程的配置。

3. 重启 Docker。

站点范围内禁用容器镜像仓库#

按照以下步骤禁用 Registry 时，你不会删除任何现有的 Docker 镜像。Docker 镜像的删除由 Registry 应用程序本身处理。

站点范围内为新项目禁用容器镜像仓库#

如果容器镜像仓库已启用，那么它对所有新项目都应该是可用的。要禁用此功能，并让项目所有者自行启用容器镜像仓库，请按照以下步骤操作。

增加令牌持续时间#

在极狐GitLab 中，容器镜像仓库的令牌每五分钟过期一次。要增加令牌持续时间：

1. 在右上角，选择 管理员。
2. 在左侧边栏中，选择 设置 > CI/CD。
3. 展开 容器镜像仓库。
4. 对于 认证令牌持续时间（分钟），更新该值。
5. 选择 保存更改。

容器镜像仓库功能标志#

容器镜像仓库功能标志是控制容器镜像仓库中实验性或过渡性功能的环境变量开关。

与极狐GitLab 应用功能标志不同，容器镜像仓库功能标志：

• 通过 Registry 特定的环境变量进行管理
• 在容器镜像仓库代码库中定义
• 需要重新配置 Registry 才能更改

配置容器镜像仓库功能标志#

下表列出了活跃的容器镜像仓库功能标志：

要配置容器镜像仓库功能标志，请按照你的平台说明操作。

ruby
registry['env'] = {
  '<REGISTRY_FF_FEATURE_NAME>' => 'true' # 或者 'false' 禁用
}

shell
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart registry

yaml
registry:
  extraEnv:
    <REGISTRY_FF_FEATURE_NAME>: "true"  # 或者 "false" 禁用

shell
helm upgrade gitlab gitlab/gitlab -f values.yaml

ruby
registry['env'] = {
  '<REGISTRY_FF_FEATURE_NAME>' => 'true'
}

配置容器镜像仓库的存储#

你可以通过配置存储驱动来配置容器镜像仓库使用各种存储后端。默认情况下，极狐GitLab 容器镜像仓库配置为使用文件系统驱动的配置。

对于支持对象版本控制的存储后端，你可以使用对象版本控制来保留、检索和恢复存储桶中每个对象的非当前版本。但是，这可能会导致更高的存储使用量和成本。由于 Registry 的运作方式，镜像上传首先存储在临时路径中，然后传输到最终位置。对于包括 S3 和 GCS 在内的对象存储后端，这种传输是通过复制后删除来实现的。启用对象版本控制后，这些已删除的临时上传产物将作为非当前版本保留，从而增加了存储桶的大小。为了确保非当前版本在给定时间后被删除，你应该与你的存储提供商配置对象生命周期策略。

支持的不同驱动程序如下：

尽管大多数 S3 兼容服务应该可以与容器镜像仓库一起使用，但我们只保证对 AWS S3 的支持。因为我们无法断言第三方 S3 实现的正确性，所以我们可以调试问题，但除非问题可针对 AWS S3 存储桶复现，否则我们无法修补 Registry。

使用文件系统#

如果你想将镜像存储在文件系统上，你可以更改容器镜像仓库的存储路径，请按照以下步骤操作。

此路径应可供以下用户访问：

• 运行容器镜像仓库守护进程的用户。
• 运行极狐GitLab 的用户。

所有极狐GitLab、Registry 和 Web 服务器用户都必须有权访问此目录。

使用对象存储#

如果你想将容器镜像仓库镜像存储在对象存储而不是本地文件系统中，你可以配置一个受支持的存储驱动。

有关更多信息，请参阅对象存储。

为 Linux 安装包配置对象存储#

要为你的容器镜像仓库配置对象存储：

1. 选择你要使用的存储驱动。
2. 使用适当的配置编辑 /etc/gitlab/gitlab.rb。
3. 保存文件并重新配置极狐GitLab 以使更改生效。

ruby
1# 已弃用：将在极狐GitLab 19.0 中移除
2registry['storage'] = {
3  's3' => {
4    'accesskey' => '<s3-access-key>',
5    'secretkey' => '<s3-secret-key-for-access-key>',
6    'bucket' => '<your-s3-bucket>',
7    'region' => '<your-s3-region>',
8    'regionendpoint' => '<your-s3-regionendpoint>'
9  }
10}

ruby
1# 测试版：s3_v2 驱动
2registry['storage'] = {
3  's3_v2' => {
4    'accesskey' => '<s3-access-key>',
5    'secretkey' => '<s3-secret-key-for-access-key>',
6    'bucket' => '<your-s3-bucket>',
7    'region' => '<your-s3-region>',
8    'regionendpoint' => '<your-s3-regionendpoint>'
9  }
10}

ruby
1registry['storage'] = {
2  's3_v2' => {
3    'accesskey' => '<s3-access-key>',
4    'secretkey' => '<s3-secret-key-for-access-key>',
5    'bucket' => '<your-s3-bucket>',
6    'region' => '<your-s3-region>',
7    'regionendpoint' => '<your-s3-regionendpoint>',
8    'checksum_disabled' => true
9  }
10}

ruby
1registry['storage'] = {
2  's3_v2' => {  # 测试版驱动
3    'accesskey' => '<s3-access-key>',
4    'secretkey' => '<s3-secret-key-for-access-key>',
5    'bucket' => '<your-s3-bucket>',
6    'region' => '<your-s3-region>',
7    'regionendpoint' => '<your-s3-vpc-endpoint>',
8    'pathstyle' => false
9  }
10}

ruby
1registry['storage'] = {
2  's3' => {
3    'accesskey' => '<s3-access-key>',
4    'secretkey' => '<s3-secret-key-for-access-key>',
5    'bucket' => '<your-s3-bucket>',
6    'region' => '<your-s3-region>',
7    'regionendpoint' => '<your-s3-regionendpoint>',
8    'maxrequestspersecond' => 100
9  }
10}

ruby
1# 已弃用：将在 GitLab 19.0 中移除
2registry['storage'] = {
3  'azure' => {
4    'accountname' => '<your_storage_account_name>',
5    'accountkey' => '<base64_encoded_account_key>',
6    'container' => '<container_name>'
7  }
8}

ruby
1# Beta 版：azure_v2 驱动
2registry['storage'] = {
3  'azure_v2' => {
4    'credentials_type' => '<client_secret>',
5    'tenant_id' => '<your_tenant_id>',
6    'client_id' => '<your_client_id>',
7    'secret' => '<your_secret>',
8    'container' => '<your_container>',
9    'accountname' => '<your_account_name>'
10  }
11}

ruby
1registry['storage'] = {
2  'gcs' => {
3    'bucket' => '<your_bucket_name>',
4    'keyfile' => '<path/to/keyfile>',
5    # 如果存储桶与镜像仓库之外的其他应用共享，请取消以下注释：
6    # 'rootdirectory' => '/gcs/object/name/prefix'
7  }
8}

自编译安装#

存储驱动的配置在部署 Docker Registry 时创建的 registry 配置 YAML 文件中完成。

s3 存储驱动示例：

yaml
1storage:
2  s3:
3    accesskey: '<s3-access-key>'                # 如果使用 IAM 角色则不需要
4    secretkey: '<s3-secret-key-for-access-key>' # 如果使用 IAM 角色则不需要
5    bucket: '<your-s3-bucket>'
6    region: '<your-s3-region>'
7    regionendpoint: '<your-s3-regionendpoint>'
8  cache:
9    blobdescriptor: inmemory
10  delete:
11    enabled: true

<your-s3-bucket> 应为现有存储桶的名称，且不能包含子目录。

不停机迁移至对象存储#

要在不停用容器镜像仓库的情况下迁移存储，请将容器镜像仓库设置为只读模式。对于大型实例，这可能要求容器镜像仓库在较长时间内处于只读模式。在此期间， 您可以从容器镜像仓库拉取镜像，但不能推送。

1. 可选。为减少需要迁移的数据量，请运行不停机垃圾回收工具。

2. 此示例使用 aws CLI。如果您之前未配置过 CLI，请运行 sudo aws configure 配置您的凭证。 由于非管理员用户可能无法访问容器镜像仓库文件夹， 请确保使用 sudo。要检查您的凭证配置，请运行 ls 列出 所有存储桶。

   shell
   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 ls

   如果您使用 AWS 作为后端，则不需要 --endpoint-url 选项。

3. 将初始数据复制到您的 S3 存储桶，例如使用 aws CLI 的 cp 或 sync 命令。确保将 docker 文件夹作为存储桶内的顶层文件夹。

   shell
   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 sync registry s3://mybucket

   如果数据量很大，您可以通过运行并行同步操作 来提高性能。

4. 要执行最终数据同步， 将容器镜像仓库置于 read-only 模式并 重新配置极狐GitLab。

5. 将初始数据加载之后发生的任何变更同步到 S3 存储桶，并删除目标存储桶中存在但源中不存在的文件：

   shell
   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 sync registry s3://mybucket --delete --dryrun

   确认命令按预期执行后，移除 --dryrun 标志并运行该命令。

6. 通过检查以下两个命令返回的文件数，验证所有容器镜像仓库文件已上传到对象存储：

   shell
   sudo find registry -type f | wc -l

   shell
   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 ls s3://<mybucket> --recursive | wc -l

   这些命令的输出结果应一致，_uploads 目录及其子目录中的内容除外。

7. 配置您的 registry 使用 S3 存储桶进行存储。

8. 为使更改生效，将 Registry 设置回 read-write 模式并重新配置极狐GitLab。

迁移至 Azure 对象存储#

ruby
1registry['storage'] = {
2  'azure' => {
3    'accountname' => '<your_storage_account_name>',
4    'accountkey' => '<base64_encoded_account_key>',
5    'container' => '<container_name>',
6    'trimlegacyrootprefix' => true
7  }
8}

yaml
1storage:
2  azure:
3    accountname: <your_storage_account_name>
4    accountkey: <base64_encoded_account_key>
5    container: <container_name>
6    trimlegacyrootprefix: true

默认情况下，Azure 存储驱动使用 core.windows.net realm。您可以在 azure 部分为 realm 设置其他值（例如，Azure 政府云可使用 core.usgovcloudapi.net）。

禁用存储驱动的重定向#

默认情况下，访问配置了远程后端的 registry 的用户会被重定向到存储驱动的默认后端。例如，registry 可以使用 s3 存储驱动进行配置，这会将对远程 S3 存储桶的请求重定向，以减轻极狐GitLab 服务器的负载。

但是，对于通常无法访问公共服务器的内部主机所使用的 registry 来说，这种行为不受欢迎。要禁用重定向并代理下载，请将 disable 标志设置为 true，如下所示。这使得所有流量始终通过 Registry 服务。这样可以提高安全性（减少攻击面，因为存储后端未公开访问），但性能会降低（所有流量都通过该服务重定向）。

加密的 S3 存储桶#

您可以将 AWS KMS 服务端加密与已默认启用 SSE-S3 或 SSE-KMS 加密的 S3 存储桶一起使用。 不支持客户主密钥 (CMK) 和 SSE-C 加密，因为这需要在每个请求中发送加密密钥。

对于 SSE-S3，您必须在 registry 设置中启用 encrypt 选项。具体实现方式取决于您的极狐GitLab 安装方式。请按照与您安装方式匹配的说明操作。

存储限制#

没有存储限制，这意味着用户可以上传任意数量、任意大小的 Docker 镜像。此设置应在未来版本中可配置。

更改镜像仓库的内部端口#

默认情况下，Registry 服务器在 localhost 上的端口 5000 上进行监听， 这是 Registry 服务器应接受连接的地址。 在以下示例中，我们将 Registry 的端口设置为 5010。

按项目禁用容器镜像仓库#

如果您的极狐GitLab 实例启用了 Registry，但您的项目不需要它， 您可以从项目设置中禁用它。

使用外部容器镜像仓库并将 GitLab 作为认证端点#

如果您使用外部容器镜像仓库，某些与容器镜像仓库相关的功能可能不可用或存在固有风险。

为实现集成，外部 registry 必须配置为使用 JSON Web 令牌与极狐GitLab 进行认证。外部 registry 的运行时配置必须包含以下条目：

yaml
1auth:
2  token:
3    realm: https://<gitlab.example.com>/jwt/auth
4    service: container_registry
5    issuer: gitlab-issuer
6    rootcertbundle: /root/certs/certbundle

没有这些条目，registry 登录将无法通过极狐GitLab 认证。 极狐GitLab 也无法识别项目层次结构下的 嵌套镜像名称， 例如 registry.example.com/group/project/image-name:tag 或 registry.example.com/group/project/my/image-name:tag，而只能识别 registry.example.com/group/project:tag。

Linux 软件包安装#

您可以将极狐GitLab 用作外部容器镜像仓库的认证端点。

1. 打开 /etc/gitlab/gitlab.rb 并设置必要的配置：

   ruby
   gitlab_rails['registry_enabled'] = true
   gitlab_rails['registry_api_url'] = "https://<external_registry_host>:5000"
   gitlab_rails['registry_issuer'] = "gitlab-issuer"

   • gitlab_rails['registry_enabled'] = true 用于启用极狐GitLab 容器镜像仓库功能和认证端点。即使启用此选项，极狐GitLab 捆绑的容器镜像仓库服务也不会启动。
   • gitlab_rails['registry_api_url'] = "http://<external_registry_host>:5000" 必须更改为与 Registry 安装主机匹配的地址。 如果外部 registry 配置为使用 TLS，还必须指定 https。

2. 极狐GitLab 和外部容器镜像仓库之间需要证书密钥对才能安全通信。您需要创建一个证书密钥对， 将公共证书（rootcertbundle）配置给外部容器镜像仓库，将私钥配置给极狐GitLab。 为此，请将以下内容添加到 /etc/gitlab/gitlab.rb：

   ruby
   1# registry['internal_key'] 应包含自定义密钥文件的内容。
   2# 密钥文件中的换行应使用 `\n` 字符表示
   3# 示例：
   4registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
   5
   6# 可选地，定义一个自定义文件，供 Linux 软件包安装将 registry['internal_key'] 的内容写入。
   7gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"

   每次执行重新配置时，registry_key_path 指定的文件将被填充 internal_key 指定的内容。如果未指定文件，Linux 软件包安装将默认使用 /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key 并填充其内容。

3. 要更改极狐GitLab 容器镜像仓库页面中显示的容器镜像仓库 URL，请设置以下配置：

   ruby
   gitlab_rails['registry_host'] = "<registry.gitlab.example.com>"
   gitlab_rails['registry_port'] = "5005"

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

自编译安装#

1. 打开 /home/git/gitlab/config/gitlab.yml，在 registry 部分下编辑配置设置：

   yaml
   1## 容器镜像仓库
   2
   3registry:
   4  enabled: true
   5  host: "<registry.gitlab.example.com>"
   6  port: "5005"
   7  api_url: "https://<external_registry_host>:5000"
   8  path: /var/lib/registry
   9  key: </path/to/keyfile>
   10  issuer: gitlab-issuer

   了解更多 关于这些参数的含义。

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

配置容器镜像仓库通知#

您可以配置容器镜像仓库，使其在仓库中发生事件时发送 Webhook 通知。

更多关于容器镜像仓库通知配置选项的信息，请参阅 Docker Registry 通知文档。

您可以为容器镜像仓库配置多个端点。

yaml
1notifications:
2  endpoints:
3    - name: <alistener>
4      disabled: false
5      url: https://<my.listener.com>/event
6      headers: <http.Header>
7      timeout: 500
8      threshold: 5 # 已弃用：请改用 `maxretries`
9      maxretries: 5
10      backoff: 1000

运行清理策略#

前提条件：

• 如果您使用分布式架构，且容器镜像仓库运行在与 Sidekiq 不同的节点上，请按照配置外部 Sidekiq 时的容器镜像仓库中的步骤操作。

在创建清理策略后，您可以立即运行它来减少容器镜像仓库存储空间。您无需等待计划清理。

要减少特定项目使用的容器镜像仓库磁盘空间，管理员可以：

1. 按项目检查磁盘空间使用情况 以识别需要清理的项目。
2. 使用极狐GitLab Rails 控制台运行清理策略以删除镜像标签。
3. 执行垃圾回收 以删除未引用的层和未标记的清单。

按项目查看 Registry 磁盘空间使用情况#

要查看每个项目使用的磁盘空间，请在 极狐GitLab Rails 控制台中运行以下命令：

ruby
1projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]]
2# 您需要指定要检查的项目。可以通过任何方式获取这些项目。
3projects = Project.last(100)
4
5registry_metadata_database = ContainerRegistry::GitlabApiClient.supports_gitlab_api?
6
7if registry_metadata_database
8  projects.each do |project|
9    size = project.container_repositories_size
10    if size > 0
11      projects_and_size << [project.project_id, project.creator&.id, size, project.full_path]
12    end
13  end
14else
15  projects.each do |project|
16    project_layers = {}
17
18    project.container_repositories.each do |repository|
19      repository.tags.each do |tag|
20        tag.layers.each do |layer|
21          project_layers[layer.digest] ||= layer.size
22        end
23      end
24    end
25
26    total_size = project_layers.values.compact.sum
27    if total_size > 0
28      projects_and_size << [project.project_id, project.creator&.id, total_size, project.full_path]
29    end
30  end
31end
32
33# 以逗号分隔的形式输出
34projects_and_size.each do |ps|
35   puts "%s,%s,%s,%s" % ps
36end

要通过运行清理策略来删除镜像标签，请在 极狐GitLab Rails 控制台中运行以下命令：

ruby
1# 需要清理其容器镜像仓库的项目的数字 ID
2P = <project_id>
3
4# 具有项目开发者、维护者或所有者角色用户的数字 ID
5U = <user_id>
6
7# 获取所需的详细信息/对象
8user    = User.find_by_id(U)
9project = Project.find_by_id(P)
10policy  = ContainerExpirationPolicy.find_by(project_id: P)
11
12# 遍历每个容器仓库
13project.container_repositories.find_each do |repo|
14  puts repo.attributes
15
16  # 启动标签清理
17  puts Projects::ContainerRepository::CleanupTagsService.new(container_repository: repo, current_user: user, params: policy.attributes.except("created_at", "updated_at")).execute
18end

您也可以按计划运行清理。

要在实例范围内为所有项目启用清理策略，您需要找出所有具有容器镜像仓库但清理策略未启用的项目：

ruby