Help us learn about your current experience with the documentation. Take the survey.

GitLab 容器注册表故障排除

您必须以管理员身份登录 GitLab 才能排查 GitLab 容器注册表的大多数问题。

您可以在 GitLab 容器注册表管理文档中找到更多故障排除信息。

将 OCI 容器镜像迁移到 GitLab 容器注册表

将容器镜像迁移到 GitLab 注册表不受支持，但史诗任务提议改变这一行为。

您可以使用第三方工具迁移容器镜像。例如，skopeo 可以在各种存储机制之间复制容器镜像。您可以使用 skopeo 从容器注册表、容器存储后端、本地目录和本地 OCI-layout 目录复制到 GitLab 容器注册表。

Docker 连接错误

当组、项目或分支名称中包含特殊字符时，可能会发生 Docker 连接错误。特殊字符包括：

  • 开头的下划线。
  • 结尾的连字符或破折号。

要解决此错误，您可以更改组路径、项目路径或分支名称。

如果您使用 Docker Engine 17.11 或更早版本，可能会收到 404 Not Found 或 Unknown Manifest 错误消息。当前版本的 Docker Engine 使用 v2 API。

您的 GitLab 容器注册表中的镜像必须使用 Docker v2 API。有关如何将版本 1 镜像更新到版本 2 的信息，请参阅 Docker 文档。

推送清单列表时出现 Blob unknown to registry 错误

当推送 Docker 清单列表到 GitLab 容器注册表时，您可能会收到错误 manifest blob unknown: blob unknown to registry。此错误可能是由于多个具有不同架构的镜像分布在多个存储库中，而不是在同一个存储库中造成的。

例如，您可能有两个镜像，每个代表一种架构：

  • amd64 平台。
  • arm64v8 平台。

要使用这些镜像构建多架构镜像，您必须将它们推送到与多架构镜像相同的存储库中。

要解决 Blob unknown to registry 错误，请在单个镜像的标签名称中包含架构。例如，使用 mygroup/myapp:1.0.0-amd64 和 mygroup/myapp:1.0.0-arm64v8。然后您可以使用 mygroup/myapp:1.0.0 标记清单列表。

无法更改项目路径或传输项目

如果您尝试更改项目路径或将项目传输到新的命名空间，您可能会收到以下错误之一：

  • 项目无法传输，因为其容器注册表中存在标签。
  • 命名空间无法移动，因为至少有一个项目在容器注册表中有标签。

当项目在容器注册表中有镜像时，会发生此错误。您必须在更改路径或传输项目之前删除或移动这些镜像。

以下过程使用这些示例项目名称：

  • 当前项目：gitlab.example.com/org/build/sample_project/cr:v2.9.1。
  • 新项目：gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1。

  1. 在您的计算机上下载 Docker 镜像：

    docker login gitlab.example.com
docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1

    使用个人访问令牌或部署令牌来验证您的用户账户。

  2. 重命名镜像以匹配新项目名称：

    docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1

  3. 使用 UI 或 API 删除旧项目中的镜像。镜像排队和删除时可能会有延迟。

  4. 更改路径或传输项目：

    1. 在左侧边栏中，选择 Search or go to 并找到您的项目。
    2. 选择 Settings > General。
    3. 展开 Advanced 部分。
    4. 在 Change path 文本框中，编辑路径。
    5. 选择 Change path。

  5. 恢复镜像：

    docker push gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1

详细信息请参阅此 issue。

Failed to pull image 消息

当 CI/CD 作业无法从具有有限 CI/CD 作业令牌范围 的项目中拉取容器镜像时，您可能会收到 Failed to pull image 错误消息。

OCI manifest found, but accept header does not support OCI manifests 错误

如果您无法拉取镜像，注册表日志中可能有类似以下的错误：

manifest unknown: OCI manifest found, but accept header does not support OCI manifests

当客户端未提交正确的 Accept: application/vnd.oci.image.manifest.v1+json 标头时，会发生此错误。确保您的 Docker 客户端版本是最新的。如果您使用第三方工具，请确保它能够处理 OCI 清单。