GitLab Container Registry administration · Gitlab 中文文檔

# GitLab Container Registry administration > 原文：[https://docs.gitlab.com/ee/administration/packages/container_registry.html](https://docs.gitlab.com/ee/administration/packages/container_registry.html) * [Enable the Container Registry](#enable-the-container-registry) * [Container Registry domain configuration](#container-registry-domain-configuration) * [Configure Container Registry under an existing GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain) * [Configure Container Registry under its own domain](#configure-container-registry-under-its-own-domain) * [Disable Container Registry site-wide](#disable-container-registry-site-wide) * [Disable Container Registry for new projects site-wide](#disable-container-registry-for-new-projects-site-wide) * [Configure storage for the Container Registry](#configure-storage-for-the-container-registry) * [Use filesystem](#use-filesystem) * [Use object storage](#use-object-storage) * [Migrate to object storage without downtime](#migrate-to-object-storage-without-downtime) * [Disable redirect for storage driver](#disable-redirect-for-storage-driver) * [Storage limitations](#storage-limitations) * [Change the registry’s internal port](#change-the-registrys-internal-port) * [Disable Container Registry per project](#disable-container-registry-per-project) * [Use an external container registry with GitLab as an auth endpoint](#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint) * [Configure Container Registry notifications](#configure-container-registry-notifications) * [Container Registry garbage collection](#container-registry-garbage-collection) * [Understanding the content-addressable layers](#understanding-the-content-addressable-layers) * [Recycling unused tags](#recycling-unused-tags) * [Removing unused layers not referenced by manifests](#removing-unused-layers-not-referenced-by-manifests) * [Performing garbage collection without downtime](#performing-garbage-collection-without-downtime) * [Running the garbage collection on schedule](#running-the-garbage-collection-on-schedule) * [Troubleshooting](#troubleshooting) * [Using self-signed certificates with Container Registry](#using-self-signed-certificates-with-container-registry) * [`unauthorized: authentication required` when pushing large images](#unauthorized-authentication-required-when-pushing-large-images) * [AWS S3 with the GitLab registry error when pushing large images](#aws-s3-with-the-gitlab-registry-error-when-pushing-large-images) * [Supporting older Docker clients](#supporting-older-docker-clients) * [Docker connection error](#docker-connection-error) * [Image push errors](#image-push-errors) * [Enable the Registry debug server](#enable-the-registry-debug-server) * [Advanced Troubleshooting](#advanced-troubleshooting) * [Unexpected 403 error during push](#unexpected-403-error-during-push) * [mitmproxy](#mitmproxy) * [Running the Docker daemon with a proxy](#running-the-docker-daemon-with-a-proxy) * [Running the Docker client](#running-the-docker-client) # GitLab Container Registry administration[](#gitlab-container-registry-administration "Permalink") Version history * 在 GitLab 8.8 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) . * 在 GitLab 8.9 中添加了對 Container Registry manifest `v1`支持，以支持 1.10 之前的 Docker 版本. **注意：**本文檔是管理員指南. 要了解如何使用 GitLab 容器注冊表，請參閱[用戶文檔](../../user/packages/container_registry/index.html) . 通過將容器注冊表集成到 GitLab 中，每個項目都可以擁有自己的空間來存儲其 Docker 映像. 您可以在[https://docs.docker.com/registry/introduction/上](https://s0docs0docker0com.icopy.site/registry/introduction/)了解有關 Docker 注冊表的更多信息. ## Enable the Container Registry[](#enable-the-container-registry "Permalink") **所有裝置 GitLab** 如果您使用 Omnibus 安裝包安裝了 GitLab，則默認情況下容器注冊表可能可用或可能不可用. 如果出現以下情況，容器注冊表將自動啟用，并在您的 GitLab 域上的端口 5050 上可用： * 您正在使用內置的[Let's Encrypt 集成](https://docs.gitlab.com/omnibus/settings/ssl.html) ，并且 * 您使用的是 GitLab 12.5 或更高版本. 否則，不會啟用容器注冊表. 要啟用它： * 您可以為您的[GitLab 域](#configure-container-registry-under-an-existing-gitlab-domain)配置它，或者 * 您可以為[其他域](#configure-container-registry-under-its-own-domain)配置它. **注意：**默認情況下，容器注冊表在 HTTPS 下工作. 您可以使用 HTTP，但不建議使用 HTTP，它不在本文檔的討論范圍之內. 如果要實現此目的，請閱讀[不安全的注冊表文檔](https://s0docs0docker0com.icopy.site/registry/insecure/) . **從源安裝** 如果您從源代碼安裝了 GitLab： 1. 您將必須自己[安裝注冊表](https://s0docs0docker0com.icopy.site/registry/deploying/) . 2. 安裝完成后，您必須在`gitlab.yml`中配置注冊表的設置才能啟用它. 3. 使用在[`lib/support/nginx/registry-ssl`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/nginx/registry-ssl)下找到的示例 NGINX 配置文件，并對其進行編輯以匹配`host` ， `port`和 TLS 證書路徑. `gitlab.yml`的內容是： ``` registry: enabled: true host: registry.gitlab.example.com port: 5005 api_url: http://localhost:5000/ key: config/registry.key path: shared/registry issuer: gitlab-issuer ``` where: | Parameter | Description | | --- | --- | | `enabled` | `true` `false` . 在 GitLab 中啟用注冊表. 默認情況下為`false` . | | `host` | 注冊表將在其下運行的主機 URL，并且用戶將可以使用該 URL. | | `port` | 外部注冊表域將在其上偵聽的端口. | | `api_url` | The internal API URL under which the Registry is exposed to. It defaults to `http://localhost:5000`. | | `key` | 私鑰位置是一對 Registry 的`rootcertbundle` . 閱讀[令牌身份驗證配置文檔](https://s0docs0docker0com.icopy.site/registry/configuration/) . | | `path` | 該目錄應與 Registry 的`rootdirectory`指定的目錄相同. 閱讀[存儲配置文檔](https://s0docs0docker0com.icopy.site/registry/configuration/) . GitLab 用戶，Web 服務器用戶和注冊表用戶必須可讀此路徑. 在[＃configure-container-for-container-registry 中](#configure-storage-for-the-container-registry)了解更多信息. | | `issuer` | This should be the same value as configured in Registry’s `issuer`. Read the [token auth configuration documentation](https://s0docs0docker0com.icopy.site/registry/configuration/). | **注意：**如果從源代碼安裝，則 GitLab 不會隨附注冊表初始化文件. 因此，如果您修改注冊表， [重新啟動 GitLab](../restart_gitlab.html#installations-from-source)將不會重新啟動注冊表. 閱讀有關如何實現這一目標的上游文檔. **絕對**要確保您的[注冊表配置](https://s0docs0docker0com.icopy.site/registry/configuration/)將`container_registry`作為服務，并將`https://gitlab.example.com/jwt/auth`作為領域： ``` auth: token: realm: https://gitlab.example.com/jwt/auth service: container_registry issuer: gitlab-issuer rootcertbundle: /root/certs/certbundle ``` **注意：**如果未設置`auth` ，則用戶無需身份驗證即可拉取 Docker 映像. ## Container Registry domain configuration[](#container-registry-domain-configuration "Permalink") There are two ways you can configure the Registry’s external domain. Either: * [使用現有的 GitLab 域](#configure-container-registry-under-an-existing-gitlab-domain) ，在這種情況下，注冊表將不得不偵聽端口并重用 GitLab 的 TLS 證書， * [將完全獨立的域](#configure-container-registry-under-its-own-domain)與該[域](#configure-container-registry-under-its-own-domain)的新 TLS 證書一起使用. 由于容器注冊表需要 TLS 證書，所以最終歸結為獲得新證書的難易程度或代價. 在首次配置 Container Registry 之前，請考慮到這一點. ### Configure Container Registry under an existing GitLab domain[](#configure-container-registry-under-an-existing-gitlab-domain "Permalink") 如果將注冊表配置為使用現有的 GitLab 域，則可以在端口上公開注冊表，以便可以重復使用現有的 GitLab TLS 證書. 假設 GitLab 域是`https://gitlab.example.com` ，注冊表暴露給外界的端口是`5050` ，如果您正在使用 Omnibus GitLab，則需要在`gitlab.rb`或`gitlab.yml`進行設置或分別從源代碼安裝 GitLab. **注意：**請小心選擇與注冊表偵聽的端口不同的端口（默認為`5000` ），否則您將遇到沖突. **所有裝置 GitLab** 1. 您的`/etc/gitlab/gitlab.rb`應該包含注冊表 URL 以及 GitLab 使用的現有 TLS 證書和密鑰的路徑： ``` registry_external_url 'https://gitlab.example.com:5050' ``` 請注意， `registry_external_url`如何在現有 GitLab URL 下的 HTTPS 上偵聽，但在其他端口上. 如果您的 TLS 證書不在`/etc/gitlab/ssl/gitlab.example.com.crt`并且密鑰不在`/etc/gitlab/ssl/gitlab.example.com.key`取消注釋以下行： ``` registry_nginx['ssl_certificate'] = "/path/to/certificate.pem" registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key" ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. 3. 驗證使用： ``` openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:5050 > cacert.pem ``` **注意：**如果您的證書提供者提供了 CA Bundle 證書，則將它們附加到 TLS 證書文件中. **從源安裝** 1. 打開`/home/git/gitlab/config/gitlab.yml` ，找到`registry`項，并使用以下設置進行配置： ``` registry: enabled: true host: gitlab.example.com port: 5050 ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. 3. 還要在 NGINX 中進行相關更改（域，端口，TLS 證書路徑）. 用戶現在應該可以使用以下命令使用其 GitLab 憑據登錄到 Container Registry： ``` docker login gitlab.example.com:5050 ``` ### Configure Container Registry under its own domain[](#configure-container-registry-under-its-own-domain "Permalink") 如果將注冊表配置為使用其自己的域，則將需要該特定域的 TLS 證書（例如， `registry.example.com` ），或者如果托管在現有 GitLab 域的子域（例如， `registry.example.com` ）下，則可能需要通配符證書`registry.gitlab.example.com` ）. **注意：**除手動生成的 SSL 證書（在此處說明）外， [Omnibus 安裝](https://docs.gitlab.com/omnibus/settings/ssl.html)還[支持](https://docs.gitlab.com/omnibus/settings/ssl.html)由 Let's Encrypt 自動生成的證書. 假設您希望在`https://registry.gitlab.example.com`上訪問容器注冊表. **所有裝置 GitLab** 1. 將您的 TLS 證書和密鑰放在`/etc/gitlab/ssl/registry.gitlab.example.com.crt`和`/etc/gitlab/ssl/registry.gitlab.example.com.key` ，并確保它們具有正確的權限： ``` chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.* ``` 2. TLS 證書到位后，使用以下命令編輯`/etc/gitlab/gitlab.rb` ： ``` registry_external_url 'https://registry.gitlab.example.com' ``` 請注意， `registry_external_url`如何在 HTTPS 上進行偵聽. 3. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. 如果您具有[通配符證書](https://en.wikipedia.org/wiki/Wildcard_certificate) ，則除了 URL 外，還需要指定證書的路徑，在這種情況下，/ `/etc/gitlab/gitlab.rb`將如下所示： ``` registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem" registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" ``` **從源安裝** 1. 打開`/home/git/gitlab/config/gitlab.yml` ，找到`registry`項，并使用以下設置進行配置： ``` registry: enabled: true host: registry.gitlab.example.com ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. 3. 還要在 NGINX 中進行相關更改（域，端口，TLS 證書路徑）. 用戶現在應該能夠使用其 GitLab 憑據登錄到 Container Registry： ``` docker login registry.gitlab.example.com ``` ## Disable Container Registry site-wide[](#disable-container-registry-site-wide "Permalink") **注意：**按照以下步驟在 Rails GitLab 應用程序中禁用注冊表，不會刪除任何現有的 Docker 映像. 這由注冊表應用程序本身處理. **所有的 GitLab** 1. 打開`/etc/gitlab/gitlab.rb`并將`registry['enable']`為`false` ： ``` registry['enable'] = false ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 1. 打開`/home/git/gitlab/config/gitlab.yml` ，找到`registry`項并將其設置`enabled`以`false` ： ``` registry: enabled: false ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ## Disable Container Registry for new projects site-wide[](#disable-container-registry-for-new-projects-site-wide "Permalink") 如果啟用了容器注冊表，那么它將在所有新項目中可用. 要禁用此功能并使項目的所有者自行啟用容器注冊表，請按照以下步驟操作. **所有裝置 GitLab** 1. 編輯`/etc/gitlab/gitlab.rb`并添加以下行： ``` gitlab_rails['gitlab_default_projects_features_container_registry'] = false ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 1. 打開`/home/git/gitlab/config/gitlab.yml` ，找到`default_projects_features`條目并進行配置，以便`container_registry`設置為`false` ： ``` ## Default project features settings default_projects_features: issues: true merge_requests: true wiki: true snippets: false builds: true container_registry: false ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ## Configure storage for the Container Registry[](#configure-storage-for-the-container-registry "Permalink") 您可以通過配置存儲驅動程序來將 Container Registry 配置為使用各種存儲后端. 默認情況下，GitLab 容器注冊表配置為使用[文件系統驅動程序](#use-filesystem)配置. 支持的不同驅動程序是： | Driver | Description | | --- | --- | | filesystem | 使用本地文件系統上的路徑 | | Azure | Microsoft Azure Blob 存儲 | | gcs | 谷歌云存儲 | | s3 | Amazon Simple Storage Service. 確保使用正確的[S3 權限范圍](https://s0docs0docker0com.icopy.site/registry/storage-drivers/s3/)配置存儲桶. | | swift | OpenStack Swift 對象存儲 | | oss | 阿里云 OSS | 在[Docker Registry 文檔中](https://s0docs0docker0com.icopy.site/registry/configuration/)閱讀有關單個驅動程序配置選項的更多信息. ### Use filesystem[](#use-filesystem "Permalink") 如果要將圖像存儲在文件系統上，則可以更改 Container Registry 的存儲路徑，請按照以下步驟操作. 此路徑可用于： * 運行容器注冊表守護程序的用戶. * 運行 GitLab 的用戶. **警告：**您應該確認所有的 GitLab，注冊表和 Web 服務器用戶都可以訪問該目錄. **所有裝置 GitLab** 在 Omnibus 中存儲圖像的默認位置是`/var/opt/gitlab/gitlab-rails/shared/registry` . 要更改它： 1. Edit `/etc/gitlab/gitlab.rb`: ``` gitlab_rails['registry_path'] = "/path/to/registry/storage" ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 在源安裝中存儲映像的默認位置是`/home/git/gitlab/shared/registry` . 要更改它： 1. 打開`/home/git/gitlab/config/gitlab.yml` ，找到`registry`項并更改`path`設置： ``` registry: path: shared/registry ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ### Use object storage[](#use-object-storage "Permalink") 如果要將圖像存儲在對象存儲中，則可以更改 Container Registry 的存儲驅動程序. [Read more about using object storage with GitLab](../object_storage.html). **警告：** GitLab 不會備份未存儲在文件系統上的 Docker 映像. 請記住，如果需要，請與您的對象存儲提供程序一起啟用備份.**注：** `regionendpoint`配置 S3 兼容的服務，如 MinIO 時才需要. 它采用一個 URL，例如`http://127.0.0.1:9000` . **所有裝置 GitLab** 在 Omnibus 中配置`s3`存儲驅動程序： 1. Edit `/etc/gitlab/gitlab.rb`: ``` registry['storage'] = { 's3' => { 'accesskey' => 's3-access-key', 'secretkey' => 's3-secret-key-for-access-key', 'bucket' => 'your-s3-bucket', 'region' => 'your-s3-region', 'regionendpoint' => 'your-s3-regionendpoint' } } ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **注意：** `your-s3-bucket`應該僅是存在的存儲桶的名稱，并且不能包含子目錄. **從源安裝** 存儲驅動程序的配置在[部署 Docker 注冊表](https://s0docs0docker0com.icopy.site/registry/deploying/)時創建的注冊表配置 YML 文件中完成. `s3`存儲驅動程序示例： ``` storage: s3: accesskey: 's3-access-key' secretkey: 's3-secret-key-for-access-key' bucket: 'your-s3-bucket' region: 'your-s3-region' regionendpoint: 'your-s3-regionendpoint' cache: blobdescriptor: inmemory delete: enabled: true ``` **注意：** `your-s3-bucket`應該僅是存在的存儲桶的名稱，并且不能包含子目錄. #### Migrate to object storage without downtime[](#migrate-to-object-storage-without-downtime "Permalink") 若要在不停止 Container Registry 的情況下遷移存儲，請將 Container Registry 設置為只讀模式. 在大型實例上，這可能需要將 Container Registry 置于只讀模式一段時間. 在此期間，您可以從 Container Registry 中拉出，但不能推送. 1. 可選：要減少要遷移的數據量，請運行[垃圾收集工具，而無需停機](#performing-garbage-collection-without-downtime) . 2. 例如，使用 AWS CLI [`cp`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/cp.html)或[`sync`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/sync.html)命令將初始數據復制到 S3 存儲桶. 確保將`docker`文件夾保留為存儲桶中的頂級文件夾. ``` aws s3 sync registry s3://mybucket ``` 3. 為了使更改生效， [請將 Container Registry 設置為`read-only`模式，](#performing-garbage-collection-without-downtime)然后[重新配置 GitLab](../restart_gitlab.html#omnibus-gitlab-reconfigure) . 4. 將自初始數據加載以來的所有更改同步到 S3 存儲桶，并刪除目標存儲桶中存在但源文件中不存在的文件： ``` aws s3 sync registry s3://mybucket --delete ``` **危險：** `--delete`標志將刪除存在于目標而不是在源文件中. 確保不交換源和目標，否則您將刪除注冊表中的所有數據. 5. 將注冊表配置為使用 S3 存儲桶進行存儲. 6. For the changes to take effect, set the Registry back to `read-write` mode and [reconfigure GitLab](../restart_gitlab.html#omnibus-gitlab-reconfigure). ### Disable redirect for storage driver[](#disable-redirect-for-storage-driver "Permalink") 默認情況下，訪問配置了遠程后端的注冊表的用戶將重定向到存儲驅動程序的默認后端. 例如，可以使用`s3`存儲驅動程序配置注冊表，該驅動程序將請求重定向到遠程 S3 存儲桶以減輕 GitLab 服務器上的負載. 但是，對于通常無法訪問公共服務器的內部主機使用的注冊表，此行為是不希望的. 要禁用重定向和[代理下載](../object_storage.html#proxy-download) ，請按如下所示將`disable`標志設置為 true. 這使得所有流量始終通過注冊表服務. 這樣可以提高安全性（由于無法公開訪問存儲后端，從而減少了表面攻擊），但性能卻較差（所有流量都通過服務重定向）. **所有裝置 GitLab** 1. Edit `/etc/gitlab/gitlab.rb`: ``` registry['storage'] = { 's3' => { 'accesskey' => 's3-access-key', 'secretkey' => 's3-secret-key-for-access-key', 'bucket' => 'your-s3-bucket', 'region' => 'your-s3-region', 'regionendpoint' => 'your-s3-regionendpoint' }, 'redirect' => { 'disable' => true } } ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 1. 將`redirect`標志添加到您的注冊表配置 YML 文件中： ``` storage: s3: accesskey: 'AKIAKIAKI' secretkey: 'secret123' bucket: 'gitlab-registry-bucket-AKIAKIAKI' region: 'your-s3-region' regionendpoint: 'your-s3-regionendpoint' redirect: disable: true cache: blobdescriptor: inmemory delete: enabled: true ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ### Storage limitations[](#storage-limitations "Permalink") 當前，沒有存儲限制，這意味著用戶可以上傳無限數量的任意大小的 Docker 映像. 此設置將在以后的版本中進行配置. ## Change the registry’s internal port[](#change-the-registrys-internal-port "Permalink") **注意：**請勿將此與 GitLab 本身用于向世界展示注冊表的端口混淆. 默認情況下，Registry Server 在端口`5000`上的 localhost 上偵聽，這是 Registry Server 應接受其連接的地址. 在下面的示例中，我們將注冊表的端口設置為`5001` . **所有的 GitLab** 1. 打開`/etc/gitlab/gitlab.rb`并設置`registry['registry_http_addr']` ： ``` registry['registry_http_addr'] = "localhost:5001" ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 1. 打開您的注冊表服務器的配置文件，然后編輯[`http:addr`](https://s0docs0docker0com.icopy.site/registry/configuration/)值： ``` http addr: localhost:5001 ``` 2. 保存文件并重新啟動注冊表服務器. ## Disable Container Registry per project[](#disable-container-registry-per-project "Permalink") 如果在您的 GitLab 實例中啟用了注冊表，但是您的項目不需要它，則可以從項目的設置中禁用它. 閱讀有關如何實現此目的的用戶指南. ## Use an external container registry with GitLab as an auth endpoint[](#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint "Permalink") **注意：**在使用外部容器注冊表時，與容器注冊表相關聯的某些功能可能不可用或存在[固有風險](./../../user/packages/container_registry/index.html#use-with-external-container-registries) **所有的 GitLab** 您可以將 GitLab 用作具有外部容器注冊表的身份驗證端點. 1. 打開`/etc/gitlab/gitlab.rb`并設置必要的配置： ``` gitlab_rails['registry_enabled'] = true gitlab_rails['registry_api_url'] = "http://localhost:5000" gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" ``` **注意：**啟用 GitLab 的 Container Registry 功能和身份驗證端點需要`gitlab_rails['registry_enabled'] = true` . 即使啟用了它，也不會啟動 GitLab 捆綁的 Container Registry 服務. 2. 證書密鑰對是 GitLab 和外部容器注冊表進行安全通信所必需的. 您將需要創建一個證書密鑰對，使用公共證書配置外部容器注冊表，并使用私鑰配置 GitLab. 為此，將以下內容添加到`/etc/gitlab/gitlab.rb` ： ``` # registry['internal_key'] should contain the contents of the custom key # file. Line breaks in the key file should be marked using `\n` character # Example: registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n" # Optionally define a custom file for Omnibus GitLab to write the contents # of registry['internal_key'] to. gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key" ``` **注意：**每次執行重新配置時，都會使用`internal_key`指定的內容填充`registry_key_path`指定的文件. 如果未指定文件，則 Omnibus GitLab 會將其默認設置為`/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key`并將其填充. 3. 要更改在 GitLab 容器注冊表頁面中顯示的容器注冊表 URL，請設置以下配置： ``` gitlab_rails['registry_host'] = "registry.gitlab.example.com" gitlab_rails['registry_port'] = "5005" ``` 4. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 1. 打開`/home/git/gitlab/config/gitlab.yml` ，然后在`registry`下編輯配置設置： ``` ## Container Registry registry: enabled: true host: "registry.gitlab.example.com" port: "5005" api_url: "http://localhost:5000" path: /var/opt/gitlab/gitlab-rails/shared/registry key: /var/opt/gitlab/gitlab-rails/certificate.key issuer: omnibus-gitlab-issuer ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ## Configure Container Registry notifications[](#configure-container-registry-notifications "Permalink") 您可以將 Container Registry 配置為發送 Webhook 通知，以響應注冊表中發生的事件. 在[Docker Registry 通知文檔中](https://s0docs0docker0com.icopy.site/registry/notifications/)閱讀有關 Container Registry 通知配置選項的更多信息. **注意：**可以為 Container Registry 配置多個端點. **所有裝置 GitLab** 要在 Omnibus 中配置通知端點： 1. Edit `/etc/gitlab/gitlab.rb`: ``` registry['notifications'] = [ { 'name' => 'test_endpoint', 'url' => 'https://gitlab.example.com/notify', 'timeout' => '500ms', 'threshold' => 5, 'backoff' => '1s', 'headers' => { "Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"] } } ] ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **從源安裝** 在[部署 Docker 注冊表](https://s0docs0docker0com.icopy.site/registry/deploying/)時創建的注冊表配置 YML 文件中完成了通知端點的配置. Example: ``` notifications: endpoints: - name: alistener disabled: false url: https://my.listener.com/event headers: <http.Header> timeout: 500 threshold: 5 backoff: 1000 ``` ## Container Registry garbage collection[](#container-registry-garbage-collection "Permalink") **注意：**僅當您通過 Omnibus 軟件包或[云本機圖表](https://docs.gitlab.com/charts/charts/registry/)安裝了 GitLab 時，垃圾收集工具才可用.**危險：**通過運行內置的垃圾收集命令，將導致 Container Registry 停機. 如果在其他實例之一仍在寫入注冊表存儲的環境中的某個實例上運行此命令，則將刪除引用的清單. 為避免這種情況，請確保在繼續[操作](#performing-garbage-collection-without-downtime)之前將注冊表設置為[只讀模式](#performing-garbage-collection-without-downtime) . 容器注冊表可以使用大量的磁盤空間. 為了清除一些未使用的層，注冊表包括一個垃圾收集命令. GitLab 提供了一組 API 來操作 Container Registry 并協助刪除未使用標簽的過程. 當前，這是使用 API??公開的，但是將來，這些控件將被遷移到 GitLab 接口. 項目維護者可以根據自己的標準定期[刪除大量的 Container Registry 標簽](../../api/container_registry.html#delete-registry-repository-tags-in-bulk) ，但是，這本身并不會回收數據，它只會使清單和圖像斑點之間的鏈接斷開. 要在整個 GitLab 實例中回收 Container Registry 數據，可以使用`gitlab-ctl`提供的內置命令. ### Understanding the content-addressable layers[](#understanding-the-content-addressable-layers "Permalink") 請考慮以下示例，該示例是您首先構建映像的地方： ``` # This builds a image with content of sha256:111111 docker build -t my.registry.com/my.group/my.project:latest . docker push my.registry.com/my.group/my.project:latest ``` 現在，您要使用新版本覆蓋`:latest` ： ``` # This builds a image with content of sha256:222222 docker build -t my.registry.com/my.group/my.project:latest . docker push my.registry.com/my.group/my.project:latest ``` 現在， `:latest`標記指向`sha256:222222` . 但是，由于注冊表的體系結構，即使不再通過`:latest`標記也可以直接訪問圖像`my.registry.com/my.group/my.project@sha256:111111` ，仍可以訪問此數據. ### Recycling unused tags[](#recycling-unused-tags "Permalink") > 在所有 GitLab 8.12 中[引入](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/987) . 在運行內置命令之前，需要注意一些注意事項： * 內置命令將在啟動垃圾收集之前停止注冊表. * 垃圾收集命令需要一些時間才能完成，具體取決于存在的數據量. * 如果更改了注冊表配置文件的位置，則需要指定其路徑. * After the garbage collection is done, the registry should start up automatically. 如果未更改配置文件的默認位置，請運行： ``` sudo gitlab-ctl registry-garbage-collect ``` 該命令將花費一些時間來完成，具體取決于您存儲的層數. 如果更改了 Container Registry `config.yml`的位置： ``` sudo gitlab-ctl registry-garbage-collect /path/to/config.yml ``` 您也可以[刪除所有未引用的清單](#removing-unused-layers-not-referenced-by-manifests) ，盡管這是一種更具破壞性的操作，您應該首先了解其含義. ### Removing unused layers not referenced by manifests[](#removing-unused-layers-not-referenced-by-manifests "Permalink") > 在所有 GitLab 11.10 中[引入](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3097) . **危險：**這是破壞性的操作. GitLab 容器注冊表遵循與 Docker Distribution 相同的默認工作流程：保留所有層，即使是未直接引用的層也允許使用上下文可尋址標識符訪問所有內容. 但是，在大多數工作流程中，如果注冊表標記未直接引用舊層，則您不必在意這些舊層. `registry-garbage-collect`命令支持`-m`開關，以允許您刪除所有不能通過`tag`直接訪問的未引用清單和層： ``` sudo gitlab-ctl registry-garbage-collect -m ``` 由于這是更具破壞性的操作，因此默認情況下將禁用此行為. 您可能期望這種操作方式，但是在執行此操作之前，請確保已備份所有注冊表數據. ### Performing garbage collection without downtime[](#performing-garbage-collection-without-downtime "Permalink") 在 GitLab 8.8 中[引入](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/764) . 通過將其置于只讀模式并且不使用內置命令，可以在不停止 Container Registry 的情況下執行垃圾回收. 在大型實例中，這可能需要 Container Registry 處于只讀模式一段時間. 在這段時間中，您將能夠從 Container Registry 中拉出，但不能進行推送. **注意：**默認情況下， [注冊表存儲路徑](#configure-storage-for-the-container-registry)為`/var/opt/gitlab/gitlab-rails/shared/registry` . 要啟用只讀模式： 1. 在`/etc/gitlab/gitlab.rb` ，指定只讀模式： ``` registry['storage'] = { 'filesystem' => { 'rootdirectory' => "<your_registry_storage_path>" }, 'maintenance' => { 'readonly' => { 'enabled' => true } } } ``` 2. 保存并重新配置 GitLab： ``` sudo gitlab-ctl reconfigure ``` 這會將 Container Registry 設置為只讀模式. 3. 接下來，觸發垃圾收集命令之一： ``` # Recycling unused tags sudo /opt/gitlab/embedded/bin/registry garbage-collect /var/opt/gitlab/registry/config.yml # Removing unused layers not referenced by manifests sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml ``` 這將開始垃圾收集，這可能需要一些時間才能完成. 4. 完成后，在`/etc/gitlab/gitlab.rb`更改回讀寫模式： ``` registry['storage'] = { 'filesystem' => { 'rootdirectory' => "<your_registry_storage_path>" }, 'maintenance' => { 'readonly' => { 'enabled' => false } } } ``` 5. 保存并重新配置 GitLab： ``` sudo gitlab-ctl reconfigure ``` ### Running the garbage collection on schedule[](#running-the-garbage-collection-on-schedule "Permalink") 理想情況下，您希望在不使用注冊表的情況下每周定期運行注冊表的垃圾回收. 最簡單的方法是添加一個新的 crontab 作業，該作業將每周定期運行一次. 在`/etc/cron.d/registry-garbage-collect`下創建一個文件： ``` SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # Run every Sunday at 04:05am 5 4 * * 0 root gitlab-ctl registry-garbage-collect ``` ## Troubleshooting[](#troubleshooting "Permalink") 在深入探討以下部分之前，請先進行一些基本的故障排除： 1. 檢查并確保 Docker 客戶端和 GitLab 服務器上的系統時鐘已同步（例如，通過 NTP）. 2. 如果使用的是 S3 支持的注冊表，請仔細檢查 IAM 權限和 S3 憑據（包括區域）是否正確. 有關更多詳細信息，請參閱[示例 IAM 策略](https://s0docs0docker0com.icopy.site/registry/storage-drivers/s3/) . 3. 檢查注冊表日志（例如`/var/log/gitlab/registry/current` ）和 GitLab 生產日志中的錯誤（例如`/var/log/gitlab/gitlab-rails/production.log` ）. 您也許可以在那里找到線索. ### Using self-signed certificates with Container Registry[](#using-self-signed-certificates-with-container-registry "Permalink") 如果您在容器注冊表中使用自簽名證書，則在 CI 作業期間可能會遇到如下問題： ``` Error response from daemon: Get registry.example.com/v1/users/: x509: certificate signed by unknown authority ``` 運行該命令的 Docker 守護程序需要由公認的 CA 簽名的證書，因此會出現上述錯誤. 雖然 GitLab 不使用自簽名的證書與集裝箱注冊表支持開箱即用，它可以使其工作的[指示多克爾守護信任自簽名證書](https://s0docs0docker0com.icopy.site/registry/insecure/) ，安裝多克爾守護進程，并設置`privileged = false`的跑步者的`config.toml` . 設置`privileged = true`優先于 Docker 守護程序： ``` [runners.docker] image = "ruby:2.6" privileged = false volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] ``` 有關此的其他信息： [發行 18239](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18239) . ### `unauthorized: authentication required` when pushing large images[](#unauthorized-authentication-required-when-pushing-large-images "Permalink") 錯誤示例： ``` docker push gitlab.example.com/myproject/docs:latest The push refers to a repository [gitlab.example.com/myproject/docs] 630816f32edb: Preparing 530d5553aec8: Preparing ... 4b0bab9ff599: Waiting d1c800db26c7: Waiting 42755cf4ee95: Waiting unauthorized: authentication required ``` GitLab 的注冊表默認令牌有效期為 5 分鐘. 當推送較大的圖像或推送時間超過 5 分鐘的圖像時，用戶可能會遇到此錯誤. 管理員可以在**管理區域>設置> CI / CD>容器注冊表>授權令牌持續時間（分鐘）中增加令牌持續時間** . ### AWS S3 with the GitLab registry error when pushing large images[](#aws-s3-with-the-gitlab-registry-error-when-pushing-large-images "Permalink") 將 AWS S3 與 GitLab 注冊表一起使用時，推送大圖像時可能會發生錯誤. 在注冊表日志中查找以下錯誤： ``` level=error msg="response completed with error" err.code=unknown err.detail="unexpected EOF" err.message="unknown error" ``` 要解決該錯誤，請在注冊表配置中指定一個`chunksize`值. 從`25000000` （25MB）到`50000000` （50MB）之間的值開始. **對于所有安裝** 1. Edit `/etc/gitlab/gitlab.rb`: ``` registry['storage'] = { 's3' => { 'accesskey' => 'AKIAKIAKI', 'secretkey' => 'secret123', 'bucket' => 'gitlab-registry-bucket-AKIAKIAKI', 'chunksize' => 25000000 } } ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **對于源安裝** 1. Edit `config/gitlab.yml`: ``` storage: s3: accesskey: 'AKIAKIAKI' secretkey: 'secret123' bucket: 'gitlab-registry-bucket-AKIAKIAKI' chunksize: 25000000 ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ### Supporting older Docker clients[](#supporting-older-docker-clients "Permalink") 從 GitLab 11.9 開始，我們開始提供 Docker 容器注冊表的 2.7.1 版本，默認情況下會禁用 schema1 清單. 如果您仍在使用較舊的 Docker 客戶端（1.9 或更早版本），則在推送映像時可能會遇到錯誤. 有關更多詳細信息，請參見[omn??ibus-4145](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4145) . 您可以添加配置選項以實現向后兼容. **對于所有安裝** 1. Edit `/etc/gitlab/gitlab.rb`: ``` registry['compatibility_schema1_enabled'] = true ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **對于源安裝** 1. 編輯[部署注冊表](https://s0docs0docker0com.icopy.site/registry/deploying/)時創建的 YML 配置文件. 添加以下代碼段： ``` compatibility: schema1: enabled: true ``` 2. 重新啟動注冊表以使更改生效. ### Docker connection error[](#docker-connection-error "Permalink") 當組，項目或分支名??稱中包含特殊字符時，可能會發生 Docker 連接錯誤. 特殊字符可以包括： * Leading underscore * 尾隨連字符/破折號 * 雙連字符/破折號為了解決這個問題，您可以[更改組路徑](../../user/group/index.html#changing-a-groups-path) ， [更改項目路徑](../../user/project/settings/index.html#renaming-a-repository)或更改分支名稱. 另一種選擇是創建一個[推送規則，](../../push_rules/push_rules.html)以防止在實例級別上發生這種情況. ### Image push errors[](#image-push-errors "Permalink") 當遇到錯誤或"重試"循環以嘗試推送映像但`docker login`正常時，NGINX 將標頭轉發到注冊表可能存在問題. 推薦的默認 NGINX 配置應該可以解決此問題，但是它可能發生在將 SSL 卸載到第三方反向代理的自定義設置中. 在[Docker 項目](https://github.com/docker/distribution/issues/970)問題中討論了此問題，一個簡單的解決方案是在注冊表中啟用相對 URL. **對于所有安裝** 1. Edit `/etc/gitlab/gitlab.rb`: ``` registry['env'] = { "REGISTRY_HTTP_RELATIVEURLS" => true } ``` 2. 保存文件并[重新配置 GitLab，](../restart_gitlab.html#omnibus-gitlab-reconfigure)以使更改生效. **對于源安裝** 1. 編輯[部署注冊表](https://s0docs0docker0com.icopy.site/registry/deploying/)時創建的 YML 配置文件. 添加以下代碼段： ``` http: relativeurls: true ``` 2. 保存文件并[重新啟動 GitLab，](../restart_gitlab.html#installations-from-source)以使更改生效. ### Enable the Registry debug server[](#enable-the-registry-debug-server "Permalink") 可以通過在`gitlab.rb`配置中設置注冊表調試地址來啟用可選的調試服務器. ``` registry['debug_addr'] = "localhost:5001" ``` 添加設置后， [重新配置 GitLab](../restart_gitlab.html#omnibus-gitlab-reconfigure)以應用更改. 使用 curl 來請求調試服務器的調試輸出： ``` curl localhost:5001/debug/health curl localhost:5001/debug/vars ``` ### Advanced Troubleshooting[](#advanced-troubleshooting "Permalink") **注意：**以下部分僅建議專家使用. 有時，不清楚什么地方出了問題，您可能需要更深入地研究 Docker 客戶端與 Registry 之間的通信，以找出問題所在. 過去我們將使用一個具體示例來說明如何診斷 S3 設置中的問題. #### Unexpected 403 error during push[](#unexpected-403-error-during-push "Permalink") 用戶試圖啟用 S3 支持的注冊表. `docker login`步驟很好. 但是，推送圖像時，輸出顯示： ``` The push refers to a repository [s3-testing.myregistry.com:5050/root/docker-test/docker-image] dc5e59c14160: Pushing [==================================================>] 14.85 kB 03c20c1a019a: Pushing [==================================================>] 2.048 kB a08f14ef632e: Pushing [==================================================>] 2.048 kB 228950524c88: Pushing 2.048 kB 6a8ecde4cc03: Pushing [==> ] 9.901 MB/205.7 MB 5f70bf18a086: Pushing 1.024 kB 737f40e80b7f: Waiting 82b57dbc5385: Waiting 19429b698a22: Waiting 9436069b92a3: Waiting error parsing HTTP 403 response body: unexpected end of JSON input: "" ``` 這個錯誤是模棱兩可的，因為尚不清楚 403 是來自 GitLab Rails 應用程序，Docker Registry 還是其他東西. 在這種情況下，由于我們知道自成功登錄以來，我們可能需要查看客戶端與注冊表之間的通信. [此處描述](https://s0docs0docker0com.icopy.site/registry/spec/api/)了 Docker 客戶端和 Registry 之間的 REST API. 通常，人們只會使用 Wireshark 或 tcpdump 捕獲流量并查看問題出在哪里. 但是，由于 Docker 客戶端和服務器之間的所有通信都是通過 HTTPS 完成的，因此即使您知道私鑰，也很難快速解密流量. 我們該怎么辦呢？一種方法是通過設置[不安全的注冊表](https://s0docs0docker0com.icopy.site/registry/insecure/)來禁用 HTTPS. 這可能會引入安全漏洞，僅建議用于本地測試. 如果您有生產系統并且不能或不想這樣做，則可以采用另一種方法：使用 mitmproxy，它代表中間代理. #### mitmproxy[](#mitmproxy "Permalink") [mitmproxy](https://mitmproxy.org/)允許您在客戶端和服務器之間放置代理以檢查所有流量. 一種麻煩是您的系統需要信任 mitmproxy SSL 證書才能起作用. 以下安裝說明假定您正在運行 Ubuntu： 1. [Install mitmproxy](https://docs.mitmproxy.org/stable/overview-installation/). 2. 運行`mitmproxy --port 9000`生成其證書. 輸入`CTRL` - `C`退出. 3. 將證書從`~/.mitmproxy`安裝到您的系統中： ``` sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt sudo update-ca-certificates ``` 如果成功，輸出應表明已添加證書： ``` Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done. Running hooks in /etc/ca-certificates/update.d....done. ``` 要驗證證書是否正確安裝，請運行： ``` mitmproxy --port 9000 ``` 這將在端口`9000`上運行 mitmproxy. 在另一個窗口中，運行： ``` curl --proxy http://localhost:9000 https://httpbin.org/status/200 ``` 如果一切設置正確，您將在 mitmproxy 窗口上看到信息，并且 curl 命令沒有錯誤. #### Running the Docker daemon with a proxy[](#running-the-docker-daemon-with-a-proxy "Permalink") 為了使 Docker 通過代理連接，您必須使用適當的環境變量啟動 Docker 守護程序. 最簡單的方法是關閉 Docker（例如`sudo initctl stop docker` ），然后手動運行 Docker. 以超級用戶身份運行： ``` export HTTP_PROXY="http://localhost:9000" export HTTPS_PROXY="https://localhost:9000" docker daemon --debug ``` 這將啟動 Docker 守護程序并通過 mitmproxy 代理所有連接. #### Running the Docker client[](#running-the-docker-client "Permalink") 現在我們已經運行了 mitmproxy 和 Docker，我們可以嘗試登錄并推送容器映像. 您可能需要以 root 身份運行才能執行此操作. 例如： ``` docker login s3-testing.myregistry.com:5050 docker push s3-testing.myregistry.com:5050/root/docker-test/docker-image ``` In the example above, we see the following trace on the mitmproxy window: [![mitmproxy output from Docker](https://img.kancloud.cn/b5/79/b579801cd82c175efcdc16f40940468b_1409x615.png)](img/mitmproxy-docker.png) 上圖顯示： * 初始的 PUT 請求可以順利通過 201 狀態代碼. * 201 將客戶端重定向到 S3 存儲桶. * 向 AWS 存儲桶的 HEAD 請求報告了 403 未經授權. 這是什么意思？這強烈表明 S3 用戶沒有[執行 HEAD 請求](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)的正確[權限](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) . 解決方案： [再次](https://s0docs0docker0com.icopy.site/registry/storage-drivers/s3/)檢查[IAM 權限](https://s0docs0docker0com.icopy.site/registry/storage-drivers/s3/) . 設置正確的權限后，錯誤將消失.