极狐GitLab 16 变更

此页面包含极狐GitLab 16 的次要版本和补丁版本的升级信息。确保您查看以下说明：

  • 您的安装类型。
  • 您当前版本和目标版本之间的所有版本。

有关升级极狐GitLab Helm Chart 的更多信息，请参阅 7.0 的发行说明。

从 15.11 升级时需要注意的问题

  • 从极狐GitLab 16 开始不支持 PostgreSQL 12。在升级到极狐GitLab 16.0 或更高版本之前，将 PostgreSQL 升级到至少 13.6 版本。
  • 如果您的极狐GitLab 实例首先升级到 15.11.0、15.11.1 或 15.11.2，则数据库架构不正确。在升级到 16.x 之前执行 解决方法。
  • 从 16.0 开始，极狐GitLab 私有化部署安装默认有两个数据库连接，而不是一个。此更改将 PostgreSQL 连接的数量加倍，使私有化部署版本的极狐GitLab 的行为类似于 GitLab.com，并且是为私有化部署版本的极狐GitLab 启用单独的 CI 功能数据库的步骤。在升级到 16.0 之前，请确定是否需要 增加 PostgreSQL 的最大连接数。
    • 此更改适用于使用 Linux 软件包（Omnibus）、极狐GitLab Helm chart、极狐GitLab Operator、极狐GitLab Docker 映像和自编译安装的方法。
    • 可以禁用第二个数据库连接。

  • 大多数安装可以跳过 16.0、16.1 和 16.2，因为升级路径的第一个必需步骤是 16.3。在所有情况下，您都应查看这些中间版本的说明。

    某些极狐GitLab 安装必须根据使用的功能和环境的大小停留在这些中间版本：

    如果您的实例受到影响并且您跳过这些步骤：

    • 升级可能需要数小时才能完成。
    • 实例在所有数据库更改完成之前生成 500 错误，然后需要重新启动 Puma 和 Sidekiq。
    • 对于 Linux 软件包安装，发生超时并且需要 手动解决方法以完成迁移。

  • 极狐GitLab 16.0 引入了关于强制限制项目大小的更改。在私有化部署中，如果您使用这些限制，达到限制的项目在推送到同一组中未受影响的 Git 仓库时会导致错误消息。错误通常涉及超出零字节的限制（limit of 0 B）。

    推送成功，但错误表明否则可能会导致自动化问题。

  • 通常，备份在有 PgBouncer 的环境中必须 通过设置以 GITLAB_BACKUP_ 为前缀的变量来绕过 PgBouncer。然而，由于一个已知问题，gitlab-backup 使用通过 PgBouncer 的常规数据库连接而不是在覆盖中定义的直接连接，并且数据库备份失败。解决方法是直接使用 pg_dump。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    15.11 全部 无
    16.0 全部 无
    16.1 全部 无
    16.2 全部 无
    16.3 全部 无
    16.4 全部 无
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.6 16.7.7
    16.8 16.8.0 - 16.8.3 16.8.4

Linux 软件包安装

  • 在升级到极狐GitLab 16 之前，必须更改 Gitaly 和 Praefect 配置结构。为避免数据丢失，首先重新配置 Praefect，作为新配置的一部分，禁用元数据验证。阅读更多：

  • 如果您重新配置 Gitaly 以将 Git 数据存储在除 /var/opt/gitlab/git-data/repositories 之外的位置，软件包中的极狐GitLab 16.0 及更高版本不会自动创建目录结构。

16.11.0

  • 在 JSON Web Token (ID token) 中添加了一个 groups_direct 字段。
    • 如果您使用极狐GitLab CI/CD ID 令牌与第三方服务进行身份验证，此更改可能导致 HTTP 头大小增加。代理服务器可能会拒绝请求，如果头过大。
    • 如果可能，增加接收系统上的头限制。
  • 在升级到极狐GitLab 16.11 后，某些拥有大型环境和数据库的用户在 Web UI 中加载源代码页面时会遇到超时。
    • 这些超时是由于流水线数据的慢速 PostgreSQL 查询引起的，从而超过了内部 60 秒超时。
    • 您仍然可以克隆 Git 仓库，其他仓库数据请求有效。

Linux 软件包安装

在极狐GitLab 16.11 中，除了以下情况，PostgreSQL 自动升级到 14.x：

  • 您正在使用 Patroni 运行数据库以实现高可用性。
  • 您的数据库节点是极狐GitLab Geo 配置的一部分。
  • 您已特别 选择退出 自动升级 PostgreSQL。
  • 您在 /etc/gitlab/gitlab.rb 中有 postgresql['version'] = 13。

容错和 Geo 安装支持手动升级到 PostgreSQL 14，参阅 在 HA/Geo 集群中部署的软件包 PostgreSQL。

Geo 安装

  • 由于在极狐GitLab 16.5 中引入并在 17.0 中修复的错误，极狐GitLab Pages 部署文件在次要 Geo 站点上被孤立。如果 Pages 部署本地存储，则这可能导致剩余存储为零，并随后在发生故障切换时导致数据丢失。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.7 16.7.8
    16.8 16.8.0 - 16.8.7 16.8.8
    16.9 16.9.0 - 16.9.8 16.9.9
    16.10 16.10.0 - 16.10.6 16.10.7
    16.11 16.11.0 - 16.11.3 16.11.4

  • 在极狐GitLab 16.11 到极狐GitLab 17.2 之间，缺少的 PostgreSQL 索引可能导致高 CPU 使用率、慢速作业工件验证进度以及慢速或超时的 Geo 指标状态更新。索引在极狐GitLab 17.3 中添加。要手动添加索引，请参阅 Geo Troubleshooting - High CPU usage on primary during job artifact verification。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.11 全部 无
    17.0 全部 无
    17.1 全部 无
    17.2 全部 无

  • 次要站点的 Geo 复制详细信息似乎为空，即使 Geo 复制正在工作。参阅 问题 468509。没有已知的解决方法。该错误在极狐GitLab 17.4 中修复。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.11 16.11.5 - 16.11.10 无
    17.0 全部 17.0.7
    17.1 全部 17.1.7
    17.2 全部 17.2.5
    17.3 全部 17.3.1

16.10.0

您可能在升级到极狐GitLab 16.10 或更高版本时遇到以下错误： 

PG::UndefinedColumn: ERROR:  column namespace_settings.delayed_project_removal does not exist

此错误可能发生在删除列的迁移在引用现已删除列的后续迁移之前运行时。计划在 16.11 中发布此错误的 修复。

解决问题的方法：

  1. 暂时重新创建该列。使用 gitlab-psql 或手动连接到数据库，运行： 

    ALTER TABLE namespace_settings ADD COLUMN delayed_project_removal BOOLEAN DEFAULT NULL;

  2. 应用待处理的迁移： 

    gitlab-ctl reconfigure

  3. 完成检查： 

    gitlab-ctl upgrade-check

  4. 删除该列。使用 gitlab-psql 或手动连接到数据库，运行： 

    ALTER TABLE namespace_settings DROP COLUMN delayed_project_removal;

Linux 软件包安装

极狐GitLab 16.10 的 Linux 软件包安装包括 Patroni 的新主要版本升级，从版本 2.1.0 到版本 3.0.1。

如果您正在使用启用 高可用性 (HA) （3000 用户或更多）的 参考架构，您正在使用 PostgreSQL 复制和故障切换用于 Linux 软件包安装，这使用 Patroni。

如果是这种情况，请阅读 具有停机的多节点升级 以了解如何升级您的多节点实例。

有关版本 2.1.0 和版本 3.0.1 之间引入的更改的更多信息，请参阅 Patroni 发行说明。

Geo 安装

  • 由于在极狐GitLab 16.5 中引入并在 17.0 中修复的错误，极狐GitLab Pages 部署文件在次要 Geo 站点上被孤立。如果 Pages 部署本地存储，则这可能导致剩余存储为零，并随后在发生故障切换时导致数据丢失。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.7 16.7.8
    16.8 16.8.0 - 16.8.7 16.8.8
    16.9 16.9.0 - 16.9.8 16.9.9
    16.10 16.10.0 - 16.10.6 16.10.7
    16.11 16.11.0 - 16.11.3 16.11.4

16.9.0

您可能在升级到极狐GitLab 16.9.0 时遇到以下错误： 

PG::UndefinedTable: ERROR:  relation "p_ci_pipeline_variables" does not exist

确保所有迁移完成并重新启动所有 Rails 和 Sidekiq 节点。

Geo 安装

  • 由于容器复制中的错误，配置错误的次要站点可能会将失败的容器复制标记为成功。随后验证将由于校验和不匹配而将容器标记为失败。解决方法是修复次要站点配置。 受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    全部 全部 16.10.2

  • 由于在极狐GitLab 16.5 中引入的错误，个人代码片段未被复制到次要 Geo 站点。这可能导致在 Geo 故障切换事件中丢失个人代码片段数据。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.5 全部 无
    16.6 全部 无
    16.7 全部 无
    16.8 16.8.0 - 16.8.3 16.8.4
    16.9 16.9.0 - 16.9.1 16.9.2

  • 您可能会体验到容器注册表图像子集的验证失败，因为主站点和次要站点之间的校验和不匹配。由于数据正确复制到次要站点，因此没有直接的数据丢失风险，但验证未成功。目前没有已知的解决方法。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.8 16.8.0 - 16.8.3 16.8.4
    16.9 16.9.0 - 16.9.1 16.9.2

  • 由于在极狐GitLab 16.5 中引入并在 17.0 中修复的错误，极狐GitLab Pages 部署文件在次要 Geo 站点上被孤立。如果 Pages 部署本地存储，则这可能导致剩余存储为零，并随后在发生故障切换时导致数据丢失。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.7 16.7.8
    16.8 16.8.0 - 16.8.7 16.8.8
    16.9 16.9.0 - 16.9.8 16.9.9
    16.10 16.10.0 - 16.10.6 16.10.7
    16.11 16.11.0 - 16.11.3 16.11.4

Linux 软件包安装

  • Sidekiq 的 min_concurrency 和 max_concurrency 选项在极狐GitLab 16.9.0 中被弃用，计划在极狐GitLab 17.0.0 中删除。在极狐GitLab 16.9.0 及更高版本中，为避免极狐GitLab 17.0.0 中的破坏性更改，请设置新的 concurrency 选项并删除 min_concurrency 和 max_concurrency 选项。

16.8.0

  • 在极狐GitLab 16.8.0 和 16.8.1 中，升级了 Sidekiq gem，并且新版本需要 Redis 6.2 或更高版本。如果您使用的是 Redis 6.0，请直接升级到 16.8.2，恢复与 Redis 6.0 的兼容性。
  • note您应该升级到 Redis 6.2 或更高版本，因为 Redis 6.0 不再受支持。

  • 通常，备份在有 PgBouncer 的环境中必须 通过设置以 GITLAB_BACKUP_ 为前缀的变量来绕过 PgBouncer。然而，由于一个已知问题，gitlab-backup 使用通过 PgBouncer 的常规数据库连接而不是在覆盖中定义的直接连接，并且数据库备份失败。解决方法是直接使用 pg_dump。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    15.11 全部 无
    16.0 全部 无
    16.1 全部 无
    16.2 全部 无
    16.3 全部 无
    16.4 全部 无
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.6 16.7.7
    16.8 16.8.0 - 16.8.3 16.8.4

Geo 安装

  • PostgreSQL 版本 14 是极狐GitLab 16.7 及更高版本新安装的默认版本。由于已知问题，现有的 Geo 次要站点无法升级到 PostgreSQL 版本 14。有关更多信息，请参阅 问题 7768。 所有 Geo 站点必须运行相同版本的 PostgreSQL。要在极狐GitLab 16.7 到 16.8.1 上添加新的 Geo 次要站点，您必须根据您的配置采取以下操作之一：

    • 要添加第一个 Geo 次要站点：在设置新的 Geo 次要站点之前，将主站点升级到 PostgreSQL 14。如果您的主站点已经运行 PostgreSQL 14，则无需特殊操作。
    • 要向已经具有一个或多个 Geo 次要站点的部署中添加新的 Geo 次要站点：
      • 如果所有现有站点都运行 PostgreSQL 13，请使用 固定的 PostgreSQL 版本 13 安装新的 Geo 次要站点。
      • 如果所有现有站点都运行 PostgreSQL 14：无需特殊操作。
      • 升级所有现有站点到极狐GitLab 16.8.2 或更高版本和 PostgreSQL 14，然后再将新的 Geo 次要站点添加到部署中。

  • 由于在极狐GitLab 16.5 中引入的错误，个人代码片段未被复制到次要 Geo 站点。这可能导致在 Geo 故障切换事件中丢失个人代码片段数据。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.5 全部 无
    16.6 全部 无
    16.7 全部 无
    16.8 16.8.0 - 16.8.3 16.8.4
    16.9 16.9.0 - 16.9.1 16.9.2

  • 您可能会体验到容器注册表图像子集的验证失败，因为主站点和次要站点之间的校验和不匹配。由于数据正确复制到次要站点，因此没有直接的数据丢失风险，但验证未成功。目前没有已知的解决方法。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.8 16.8.0 - 16.8.3 16.8.4
    16.9 16.9.0 - 16.9.1 16.9.2

  • 由于在极狐GitLab 16.5 中引入并在 17.0 中修复的错误，极狐GitLab Pages 部署文件在次要 Geo 站点上被孤立。如果 Pages 部署本地存储，则这可能导致剩余存储为零，并随后在发生故障切换时导致数据丢失。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.7 16.7.8
    16.8 16.8.0 - 16.8.7 16.8.8
    16.9 16.9.0 - 16.9.8 16.9.9
    16.10 16.10.0 - 16.10.6 16.10.7
    16.11 16.11.0 - 16.11.3 16.11.4

16.7.0

  • 极狐GitLab 16.7 是必需的升级停止。这确保了在极狐GitLab 16.7 及更早版本中引入的所有数据库更改已在所有私有化部署实例上实施。依赖更改可以在极狐GitLab 16.8 及更高版本中发布。

    • 如果您在升级路径中跳过 16.6，您可能会在升级到 16.7 后体验性能问题，因为您的实例正在处理极狐GitLab 16.6 版本的后台数据库迁移。 阅读更多关于 16.6.0 升级说明 中的 ci_builds 迁移。

  • 通常，备份在有 PgBouncer 的环境中必须 通过设置以 GITLAB_BACKUP_ 为前缀的变量来绕过 PgBouncer。然而，由于一个已知问题，gitlab-backup 使用通过 PgBouncer 的常规数据库连接而不是在覆盖中定义的直接连接，并且数据库备份失败。解决方法是直接使用 pg_dump。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    15.11 全部 无
    16.0 全部 无
    16.1 全部 无
    16.2 全部 无
    16.3 全部 无
    16.4 全部 无
    16.5 全部 无
    16.6 全部 无
    16.7 16.7.0 - 16.7.6 16.7.7
    16.8 16.8.0 - 16.8.3 16.8.4

Linux 软件包安装

特定信息适用于 Linux 软件包安装：

  • 从极狐GitLab 16.7 开始，PostgreSQL 14 是随 Linux 软件包安装的默认版本。在软件包升级期间，数据库不会升级到 PostgreSQL 14。 如果您想升级到 PostgreSQL 14，您必须手动进行。

    如果您想使用 PostgreSQL 13，您必须在 /etc/gitlab/gitlab.rb 中设置 postgresql['version'] = 13。

Geo 安装

  • PostgreSQL 版本 14 是极狐GitLab 16.7 及更高版本新安装的默认版本。由于已知问题，现有的 Geo 次要站点无法升级到 PostgreSQL 版本 14。 所有 Geo 站点必须运行相同版本的 PostgreSQL。要在极狐GitLab 16.7 到 16.8.1 上基于配置添加新的 Geo 次要站点，您必须采取以下操作之一：

    • 您正在添加第一个 Geo 次要站点：在设置新的 Geo 次要站点之前，将主站点升级到 PostgreSQL 14。如果您的主站点已经运行 PostgreSQL 14，则无需特殊操作。
    • 您正在向已经具有一个或多个 Geo 次要站点的部署中添加新的 Geo 次要站点：
      • 如果所有现有站点都运行 PostgreSQL 13：使用 固定的 PostgreSQL 版本 13 安装新的 Geo 次要站点。
      • 如果所有现有站点都运行 PostgreSQL 14：无需特殊操作。
      • 升级所有现有站点到极狐GitLab 16.8.2 或更高版本和 PostgreSQL 14，然后再将新的 Geo 次要站点添加到部署中。

  • 您可能会体验到项目子集的验证失败，因为主站点和次要站点之间的校验和不匹配。详细信息在此 问题 中进行了跟踪。由于数据正确复制到次要站点，因此没有数据丢失风险。用户从 Geo 次要站点克隆受影响的项目将始终被重定向到主站点。目前没有已知的解决方法。我们正在积极研究修复。

    受影响的版本：

    受影响的小版本 受影响的补丁版本 修复版本
    16.3 全部 无
    16.4 全部 无
    16.5 全部 无
    16.6 16.6.0 - 16.6.5 16.6.6
    16.7 16.7.0 - 16.7.3 16.7.4

  • 由于在极狐GitLab 16.5 中引入的错误，个人代码片段未被复制到次要 Geo 站点。这可能导致在 Geo 故障切换