{{< details >}}

  1. Tier: 基础版, 专业版, 旗舰版
  2. Offering: 私有化部署

{{< /details >}}

{{< history >}}

  1. 引入于极狐GitLab 16.4，作为私有化部署的 beta 功能。
  2. 在极狐GitLab 17.3 中 GA。

{{< /history >}}

元数据数据库为容器容器镜像仓库提供了若干增强功能，以提升性能并添加新功能。

默认情况下，容器容器镜像仓库使用对象存储来持久化与容器镜像相关的元数据。这种存储元数据的方法限制了数据访问的效率，特别是跨多个镜像的数据，例如列出标签时。通过使用数据库存储这些数据，可以实现许多新功能，包括在线垃圾回收，它可以在零停机时间自动删除旧数据。

此数据库与容器镜像仓库已经使用的对象存储协同工作，但不替代对象存储。在执行元数据导入到元数据数据库后，您必须继续维护对象存储解决方案。

对于 Helm Charts 安装，请参阅 Helm Charts 文档中的管理容器容器镜像仓库元数据数据库。

增强功能

元数据数据库架构支持性能改进、错误修复和新功能，这些功能在对象存储元数据架构中不可用。这些增强功能包括：

  1. 自动在线垃圾回收
  2. 仓库、项目和群组的存储使用情况可见性
  3. 镜像签名
  4. 移动和重命名仓库
  5. 受保护标签
  6. 清理策略 的性能改进，支持成功清理大型仓库
  7. 列出仓库标签的性能改进
  8. 追踪和显示标签发布时间戳（请参阅议题 290949）
  9. 按名称之外的其他属性排序仓库标签

由于对象存储元数据架构的技术限制，新功能仅在元数据数据库版本中实现。非安全漏洞修复可能仅限于元数据数据库版本。

已知限制

  1. 现有容器镜像仓库的元数据导入需要一段只读时间。
  2. Geo 功能有限。
  3. 升级版本时必须手动运行容器镜像仓库常规架构和部署后数据库迁移。
  4. 在多节点 Linux 软件包环境中，不能保证容器镜像仓库升级期间零停机时间。

元数据数据库功能支持

您可以从现有容器镜像仓库导入元数据到元数据数据库，并使用在线垃圾回收。

一些启用了数据库的功能仅为 JihuLab.com 启用，并且容器镜像仓库数据库的自动数据库配置不可用。

为 Linux 软件包安装启用元数据数据库

先决条件：

  1. 极狐GitLab 17.3 或更高版本。
  2. PostgreSQL 数据库版本 12 或更高版本。必须可以从容器镜像仓库节点访问。

按照与您的情况匹配的说明进行操作：

  1. 新安装或首次启用容器容器镜像仓库。
  2. 将现有容器镜像元数据导入到元数据数据库：
    • 一步导入。仅推荐用于相对较小的容器镜像仓库或没有避免停机的要求。
    • 三步导入。推荐用于较大的容器容器镜像仓库。

开始之前

  1. 所有数据库连接值都是占位符。在完成任何步骤之前，您必须创建、验证您能够连接到并管理一个新的 PostgreSQL 数据库以供容器镜像仓库使用。
  2. 启用数据库后，您必须继续使用它。数据库现在是容器镜像仓库元数据的来源，在此之后禁用它会导致容器镜像仓库在数据库处于活动状态期间写入的所有镜像丢失可见性。
  3. 在导入步骤完成后，切勿运行离线垃圾回收。该命令与使用元数据数据库的容器镜像仓库不兼容，可能会删除与标记镜像相关的数据。
  4. 验证您没有自动离线垃圾回收。
  5. 您可以先减少容器镜像仓库的存储以加快流程。
  6. 尽可能备份您的容器容器镜像仓库数据。

新安装

要启用数据库：

  1. 编辑 /etc/gitlab/gitlab.rb，添加您的数据库连接详细信息，但从 禁用 元数据数据库开始：

    registry['database'] = {
  'enabled' => false,
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}
  2. 保存文件并重新配置极狐GitLab。
  3. 应用数据库迁移。

  4. 通过编辑 /etc/gitlab/gitlab.rb 并设置 enabled 为 true 来启用数据库：

    registry['database'] = {
  'enabled' => true,
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}
  5. 保存文件并重新配置极狐GitLab。

现有容器镜像仓库

您可以一步或三步导入现有容器容器镜像仓库元数据。影响导入持续时间的一些因素：

  1. 您现有容器镜像仓库数据的大小。
  2. 您的 PostgreSQL 实例的规格。
  3. 正在运行的容器镜像仓库实例数量。
  4. 容器镜像仓库、PostgreSQL 和您配置的对象存储之间的网络延迟。

{{< alert type=”note” >}}

元数据导入仅针对标记的镜像。未标记和未引用的清单，以及仅由它们引用的层，将被留下并变得不可访问。未标记的镜像从未通过极狐GitLab UI 或 API 可见，但它们可能会在后端变成“悬空”并被留下。在导入到新容器镜像仓库后，所有镜像默认情况下都受持续的在线垃圾回收影响，删除任何未标记和未引用的清单和层，这些清单和层保留超过 24 小时。

{{< /alert >}}

根据您的容器镜像仓库安装选择一步或三步方法。

一步导入

{{< alert type=”warning” >}}

导入期间，容器镜像仓库必须关闭或保持在 read-only 模式。仅在导入期间不需要写入容器镜像仓库且容器镜像仓库包含相对较少的数据时选择此方法。

{{< /alert >}}

  1. 将 database 部分添加到您的 /etc/gitlab/gitlab.rb 文件，但从 禁用 元数据数据库开始：

    registry['database'] = {
  'enabled' => false, # 必须为 false！
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

  2. 确保容器镜像仓库设置为 read-only 模式。

    编辑您的 /etc/gitlab/gitlab.rb 并将 maintenance 部分添加到 registry['storage'] 配置中。例如，对于使用 gs://my-company-container-registry 存储桶的 gcs 支持的容器镜像仓库，配置可能是：

    ## 对象存储 - 容器容器镜像仓库
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # 必须设置为 true。
    }
  }
}
  3. 保存文件并重新配置极狐GitLab。
  4. 应用数据库迁移（如果您尚未这样做）。

  5. 运行以下命令：

    sudo gitlab-ctl registry-database import

  6. 如果命令成功完成，容器镜像仓库现在已完全导入。您现在可以启用数据库，在配置中关闭只读模式，并启动容器镜像仓库服务：

    registry['database'] = {
  'enabled' => true, # 现在必须启用！
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

## 对象存储 - 容器容器镜像仓库
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => false
    }
  }
}
  7. 保存文件并重新配置极狐GitLab。

现在您可以使用元数据数据库进行所有操作！

三步导入

按照本指南导入您现有的容器容器镜像仓库元数据。此过程推荐用于较大的元数据集或在完成导入时尽量减少停机时间。

{{< alert type=”note” >}}

用户报告了在速度为 2 到 4 TB 每小时的情况下完成步骤一导入。在较慢速度下，超过 100TB 数据的容器镜像仓库可能需要超过 48 小时。

{{< /alert >}}

预导入仓库（步骤一）

对于较大的实例，此命令可能需要数小时到数天才能完成，具体取决于容器镜像仓库的大小。在完成步骤一期间，您可以继续正常使用容器镜像仓库。

{{< alert type=”warning” >}}

尚无法重新启动导入，因此重要的是让导入运行完成。如果您必须停止操作，您必须重新启动此步骤。

{{< /alert >}}

  1. 将 database 部分添加到您的 /etc/gitlab/gitlab.rb 文件，但从 禁用 元数据数据库开始：

    registry['database'] = {
  'enabled' => false, # 必须为 false！
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}
  2. 保存文件并重新配置极狐GitLab。
  3. 应用数据库迁移（如果您尚未这样做）。

  4. 运行第一步以开始导入：

    sudo gitlab-ctl registry-database import --step-one

{{< alert type=”note” >}}

您应该尽快安排以下步骤，以减少停机时间。理想情况下，步骤一完成后不超过一周。步骤一和步骤二之间写入容器镜像仓库的新数据，会导致步骤二需要更多时间。

{{< /alert >}}

导入所有仓库数据（步骤二）

此步骤需要关闭容器镜像仓库或设置为 read-only 模式。允许足够的时间进行停机以执行步骤二。

  1. 确保容器镜像仓库设置为 read-only 模式。

    编辑您的 /etc/gitlab/gitlab.rb 并将 maintenance 部分添加到 registry['storage'] 配置中。例如，对于使用 gs://my-company-container-registry 存储桶的 gcs 支持的容器镜像仓库，配置可能是：

    ## 对象存储 - 容器容器镜像仓库
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # 必须设置为 true。
    }
  }
}
  2. 保存文件并重新配置极狐GitLab。

  3. 运行步骤二导入：

    sudo gitlab-ctl registry-database import --step-two

  4. 如果命令成功完成，所有镜像现在已完全导入。您现在可以启用数据库，在配置中关闭只读模式，并启动容器镜像仓库服务：

    registry['database'] = {
  'enabled' => true, # 必须设置为 true！
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

## 对象存储 - 容器容器镜像仓库
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # 此部分可以删除。
    'readonly' => {
      'enabled' => false
    }
  }
}
  5. 保存文件并重新配置极狐GitLab。

现在您可以使用元数据数据库进行所有操作！

导入剩余数据（步骤三）

即使容器镜像仓库现在完全使用数据库作为其元数据，它尚未访问任何潜在未使用的层 blob，阻止这些 blob 被在线垃圾回收器删除。

要完成此过程，请运行迁移的最后一步：

sudo gitlab-ctl registry-database import --step-three

命令成功退出后，容器镜像仓库元数据现在已完全导入到数据库。

导入后

导入后大约需要 48 小时才能看到您的容器镜像仓库存储减少。这是在线垃圾回收的正常和预期部分，因为此延迟确保在线垃圾回收不会干扰镜像推送。查看监控在线垃圾回收部分以了解如何监控在线垃圾回收器的进度和健康状态。

数据库迁移

容器容器镜像仓库支持两种类型的迁移：

  1. 常规架构迁移：必须在部署新应用程序代码之前运行的数据库结构更改，也称为部署前迁移。这些应该很快（不超过几分钟）以避免部署延迟。

  2. 部署后迁移：可以在应用程序运行时进行的数据库结构更改。用于较长的操作，例如在大表上创建索引，以避免启动延迟和延长的升级停机时间。

默认情况下，容器镜像仓库同时应用常规架构和部署后迁移。为了减少升级期间的停机时间，您可以跳过部署后迁移并在应用程序启动后手动应用它们。

应用数据库迁移

要在应用程序启动前应用常规架构和部署后迁移：

  1. 运行数据库迁移：

    sudo gitlab-ctl registry-database migrate up

要跳过部署后迁移：

  1. 仅运行常规架构迁移：

    sudo gitlab-ctl registry-database migrate up --skip-post-deployment

    作为 --skip-post-deployment 标志的替代方案，您还可以将 SKIP_POST_DEPLOYMENT_MIGRATIONS 环境变量设置为 true：

    SKIP_POST_DEPLOYMENT_MIGRATIONS=true sudo gitlab-ctl registry-database migrate up

  2. 启动应用程序后，应用任何待处理的部署后迁移：

    sudo gitlab-ctl registry-database migrate up

{{< alert type=”note” >}}

migrate up 命令提供了一些额外的标志，可以用于控制迁移的应用方式。运行 sudo gitlab-ctl registry-database migrate up --help 查看详细信息。

{{< /alert >}}

在线垃圾回收监控

导入过程后的初始在线垃圾回收运行根据导入的镜像数量在持续时间上有所不同。在此期间，您应监控在线垃圾回收的效率和健康状况。

监控数据库性能

完成导入后，预计数据库会经历一段高负载期，因为垃圾回收队列排空。此高负载是由于在线垃圾回收器处理排队任务时大量单独的数据库调用造成的。

定期检查 PostgreSQL 和容器镜像仓库日志以查找任何错误或警告。在容器镜像仓库日志中，尤其要关注 component=registry.gc.* 过滤的日志。

跟踪指标

使用监控工具如 Prometheus 和 Grafana 来可视化和跟踪垃圾回收指标，重点关注前缀为 registry_gc_* 的指标。这些指标包括标记为删除的对象数量、成功删除的对象数量、运行间隔和持续时间。请参阅启用容器镜像仓库调试服务器以了解如何启用 Prometheus。

队列监控

通过计算 gc_blob_review_queue 和 gc_manifest_review_queue 表中的行数来检查队列的大小。初始情况下，较大的队列是预期的，行数与导入的 blob 和清单数量成比例。队列应随着时间的推移减少，表明垃圾回收正在成功审查作业。

SELECT COUNT(*) FROM gc_blob_review_queue;
SELECT COUNT(*) FROM gc_manifest_review_queue;

解释队列大小：

  1. 队列缩小：表明垃圾回收正在成功处理任务。
  2. 接近零的 gc_manifest_review_queue：标记为潜在删除的镜像已被审查并被分类为仍在使用或已删除。

  3. 过期任务：通过运行以下查询检查过期的 GC 任务：

    SELECT COUNT(*) FROM gc_blob_review_queue WHERE review_after < NOW();
SELECT COUNT(*) FROM gc_manifest_review_queue WHERE review_after < NOW();

    大量过期任务表示问题。只要队列大小随着时间的推移减少，过期任务数量接近零，大队列大小并不令人担忧。大量过期任务应立即检查日志。

检查 GC 日志中的消息，指示 blob 仍在使用，例如 msg=the blob is not dangling，这意味着它们不会被删除。

调整 blobs 间隔

如果您的 gc_blob_review_queue 大小较大，并且希望增加垃圾回收 blob 或清单工作运行之间的频率，请将您的间隔配置从默认值（5s）更新为 1s：

registry['gc'] = {
  'blobs' => {
    'interval' => '1s'
  },
  'manifests' => {
    'interval' => '1s'
  }
}

导入负载清除后，您应该对这些设置进行长期调优，以避免对数据库和容器镜像仓库实例的不必要的 CPU 负载。您可以逐渐增加间隔以达到性能和资源使用的平衡。

验证数据一致性

要确保导入后数据的一致性，请使用 crane validate 工具。此工具检查容器容器镜像仓库中的所有镜像层和清单是否可访问并正确链接。通过运行 crane validate，您可以确认容器镜像仓库中的镜像是完整和可访问的，确保导入成功。

审查清理策略

如果您的大多数镜像都是标记的，垃圾回收不会显著减少存储空间，因为它只删除未标记的镜像。

实施清理策略以删除不需要的标签，这最终导致通过垃圾回收删除镜像并恢复存储空间。

使用元数据数据库备份

{{< alert type=”note” >}}

如果您为容器容器镜像仓库元数据配置了自己的数据库，则必须手动管理备份。gitlab-backup 不会备份元数据数据库。

{{< /alert >}}

启用元数据数据库时，备份必须同时捕获容器镜像仓库使用的对象存储，如之前一样，还必须捕获数据库。对象存储和数据库的备份应协调进行，以尽可能接近捕获容器镜像仓库的状态。要恢复容器镜像仓库，您必须同时应用两个备份。

降级容器镜像仓库

在导入完成后将容器镜像仓库降级到之前的版本，您必须恢复到所需版本的备份以进行降级。

使用 Geo 的数据库架构

使用极狐GitLab Geo 和容器容器镜像仓库时，您必须为每个站点配置单独的数据库和对象存储堆栈。对容器容器镜像仓库的 Geo 复制使用从容器镜像仓库通知生成的事件，而不是数据库复制。

先决条件

每个 Geo 站点需要一个单独的、特定于站点的：

  1. 用于容器容器镜像仓库数据库的 PostgreSQL 实例。
  2. 用于容器容器镜像仓库的对象存储实例。
  3. 配置为使用这些特定于站点资源的容器容器镜像仓库。

此图展示了数据流和基本架构：

flowchart TB subgraph "Primary site" P_Rails[GitLab Rails] P_Reg[Container registry] P_RegDB[(Registry database)] P_Obj[(Object storage)] P_Reg --> P_RegDB P_RegDB --> P_Obj end subgraph "Secondary site" S_Rails[GitLab Rails] S_Reg[Container registry] S_RegDB[(Registry database)] S_Obj[(Object storage)] S_Reg --> S_RegDB S_RegDB --> S_Obj end P_Reg -- "Notifications" --> P_Rails P_Rails -- "Events" --> S_Rails S_Rails --> S_Reg classDef primary fill:#d1f7c4 classDef secondary fill:#b8d4ff class P_Rails,P_Reg,P_MainDB,P_RegDB,P_Obj primary class S_Rails,S_Reg,S_MainDB,S_RegDB,S_Obj secondary

在每个站点使用单独的数据库实例，因为：

  1. 主极狐GitLab 数据库以只读方式复制到辅助站点。
  2. 此复制无法选择性地禁用容器镜像仓库数据库。
  3. 容器容器镜像仓库需要在两个站点的数据库上具有写访问权限。
  4. 同质设置确保 Geo 站点之间的最大一致性。

恢复到对象存储元数据

在完成元数据导入后，您可以将容器镜像仓库恢复为使用对象存储元数据。

{{< alert type=”warning” >}}

当您恢复到对象存储元数据时，在导入完成和恢复操作之间添加或删除的任何容器镜像、标签或仓库都不可用。

{{< /alert >}}

要恢复到对象存储元数据：

  1. 恢复在迁移之前拍摄的备份。

  2. 将以下配置添加到您的 /etc/gitlab/gitlab.rb 文件：

    registry['database'] = {
  'enabled' => false,
}
  3. 保存文件并重新配置极狐GitLab。

故障排除

错误：存在待处理的数据库迁移

如果容器镜像仓库已更新并存在待处理的架构迁移，容器镜像仓库将无法启动并显示以下错误消息：

FATA[0000] configuring application: there are pending database migrations, use the 'registry database migrate' CLI command to check and apply them

要解决此问题，请按照步骤应用数据库迁移。

错误：离线垃圾回收不再可能

如果容器镜像仓库使用元数据数据库并尝试运行离线垃圾回收，则容器镜像仓库将失败并显示以下错误消息：

ERRO[0000] this filesystem is managed by the metadata database, and offline garbage collection is no longer possible, if you are not using the database anymore, remove the file at the lock_path in this log message lock_path=/docker/registry/lockfiles/database-in-use

您必须：

  1. 停止使用离线垃圾回收。
  2. 如果您不再使用元数据数据库，请删除错误消息中显示的 lock_path 处的锁定文件。例如，删除 /docker/registry/lockfiles/database-in-use 文件。

错误：无法在只读事务中执行 <STATEMENT>

容器镜像仓库可能会在应用数据库迁移时失败，并显示以下错误消息：

err="ERROR: cannot execute CREATE TABLE in a read-only transaction (SQLSTATE 25006)"

此外，如果尝试运行在线垃圾回收，容器镜像仓库可能会失败，并显示以下错误消息：

error="processing task: fetching next GC blob task: scanning GC blob task: ERROR: cannot execute SELECT FOR UPDATE in a read-only transaction (SQLSTATE 25006)"

您必须通过检查 PostgreSQL 控制台中的 default_transaction_read_only 和 transaction_read_only 的值来验证只读事务是否被禁用。例如：

# SHOW default_transaction_read_only;
 default_transaction_read_only
 -------------------------------
 on
(1 row)

# SHOW transaction_read_only;
 transaction_read_only
 -----------------------
 on
(1 row)

如果这些值中的任何一个设置为 on，您必须禁用它：

  1. 编辑您的 postgresql.conf 并设置以下值：

    default_transaction_read_only=off
  2. 重新启动您的 Postgres 服务器以应用这些设置。
  3. 尝试重新应用数据库迁移，如果适用。
  4. 重新启动容器镜像仓库 sudo gitlab-ctl restart registry。

错误：无法在标签表中有条目时导入所有仓库

如果您尝试导入现有容器镜像仓库元数据并遇到以下错误：

ERRO[0000] cannot import all repositories while the tags table has entries, you must truncate the table manually before retrying,
see https://docs.gitlab.com/ee/administration/packages/container_registry_metadata_database.html#troubleshooting
common_blobs=true dry_run=false error="tags table is not empty"

此错误发生在容器镜像仓库数据库的 tags 表中存在现有条目时，这可能发生在您：

  1. 尝试进行一步导入并遇到错误。
  2. 尝试进行三步导入过程并遇到错误。
  3. 故意停止导入过程。
  4. 在以上任何情况后尝试再次运行导入。
  5. 在错误的配置文件上运行导入。

要解决此问题，您必须删除 tags 表中的现有条目。您必须在您的 PostgreSQL 实例上手动截断表：

  1. 编辑 /etc/gitlab/gitlab.rb 并确保元数据数据库被 禁用：

    registry['database'] = {
  'enabled' => false,
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # 默认值，但如果您的数据库实例端口不同，请设置为该端口。
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # 请参阅 PostgreSQL 文档以获取更多信息 https://www.postgresql.org/docs/current/libpq-ssl.html。
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}
  2. 使用 PostgreSQL 客户端连接到您的容器镜像仓库数据库。

  3. 截断 tags 表以删除所有现有条目：

    TRUNCATE TABLE tags RESTART IDENTITY CASCADE;
  4. 截断 tags 表后，尝试再次运行导入过程。

错误：database-in-use 锁文件存在

如果您尝试导入现有容器镜像仓库元数据并遇到以下错误：

|  [0s] step two: import tags failed to import metadata: importing all repositories: 1 error occurred:
    * could not restore lockfiles: database-in-use lockfile exists

此错误意味着您之前已导入容器镜像仓库并完成导入所有仓库数据（步骤二），database-in-use 存在于容器镜像仓库文件系统中。如果遇到此问题，则不应再次运行导入器。

如果您必须继续，您必须手动从文件系统中删除 database-in-use 锁文件。文件位于 /path/to/rootdirectory/docker/registry/lockfiles/database-in-use。

错误：预导入所有仓库：AccessDenied:

当导入现有容器镜像仓库并使用 AWS S3 作为存储后端时，您可能会收到 AccessDenied 错误：

/opt/gitlab/embedded/bin/registry database import --step-one /var/opt/gitlab/registry/config.yml
  [0s] step one: import manifests
  [0s] step one: import manifests failed to import metadata: pre importing all repositories: AccessDenied: Access Denied

确保执行命令的用户具有正确的权限范围。

由于元数据管理问题导致容器镜像仓库无法启动

容器镜像仓库可能无法启动并出现以下错误之一：

错误：容器镜像仓库文件系统元数据正在使用，请在启用数据库之前导入数据

此错误发生在您的配置中启用了数据库 registry['database'] = { 'enabled' => true} 但尚未导入现有容器镜像仓库元数据到元数据数据库时。

错误：容器镜像仓库元数据数据库正在使用，请启用数据库

此错误发生在您已完成导入现有容器镜像仓库元数据到元数据数据库，但未在您的配置中启用数据库时。

检查或创建锁文件的问题

如果您遇到以下任何错误：

  • could not check if filesystem metadata is locked
  • could not check if database metadata is locked
  • failed to mark filesystem for database only usage
  • failed to mark filesystem only usage

容器镜像仓库无法访问配置的 rootdirectory。如果您之前有一个正常工作的容器镜像仓库，此错误不太可能发生。检查错误日志以查找任何配置问题。

删除标签后存储使用量未减少

默认情况下，在线垃圾收集器将在删除所有关联标签后 48 小时才开始删除未引用的层。此延迟确保垃圾收集器不会干扰长时间运行或中断的镜像推送，因为层在被容器镜像仓库关联到镜像和标签之前被推送到容器镜像仓库中。