从 16.11 升级时需要注意的议题
- Linux 软件包安装
- 不过期的访问令牌
从 17.1 及更早版本升级时需要注意的议题
从 17.3 升级时需要注意的议题
17.7.0
- OpenSSL 3 升级
17.5.0
17.4.0
17.3.0
- Geo 安装 17.3.0
17.2.1
- Geo 安装 17.2.1
17.1.0
- Geo 安装 17.1.0
17.0.0
- Geo 安装 17.0.0

极狐 GitLab 17 变更

本页包含极狐GitLab 17 的小版本和补丁版本的升级信息。确保您查看以下说明：

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

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

从 16.11 升级时需要注意的议题

在升级到极狐GitLab 17.0 之前，您应该迁移到新的 Runner 注册流程。
在极狐GitLab 16.0 中，我们引入了一个新的 Runner 创建流程，使用 Runner 认证令牌来注册 Runners。旧的使用注册令牌的流程现在在极狐GitLab 17.0 中默认被禁用，并将在极狐GitLab 18.0 中被移除。如果仍然使用注册令牌，升级到极狐GitLab 17.0 将导致 Runner 注册失败。
Gitaly 存储不能再共享相同的路径，如下例所示：
```
gitaly['configuration'] = {
  storage: [
    {
       name: 'default',
       path: '/var/opt/gitlab/git-data/repositories',
    },
    {
       name: 'duplicate-path',
       path: '/var/opt/gitlab/git-data/repositories',
    },
  ],
}
```
在此示例中，必须删除或重新定位 duplicate-path 存储到新路径。如果您有多个 Gitaly 节点，必须确保在该节点的 gitlab.rb 文件中只列出对应的存储。
如果从节点的 gitlab.rb 文件中删除了存储，则与其关联的任何项目必须在极狐GitLab 数据库中更新其存储。您可以使用 Rails 控制台更新其存储。例如：
```
$ sudo gitlab-rails console
Project.where(repository_storage: 'duplicate-path').update_all(repository_storage: 'default')
```
从极狐GitLab 16.x 直接升级到极狐GitLab 17.1.0 或 17.1.1 时的迁移失败。
由于极狐GitLab 17.1.0 和 17.1.1 中的一个错误，后台作业未能正确完成，因此直接升级到极狐GitLab 17.1.0 和 17.1.1 时可能会失败。升级迁移期间的错误如下所示：
```
main: == [advisory_lock_connection] object_id: 55460, pg_backend_pid: 8714
main: == 20240531173207 ValidateNotNullCheckConstraintOnEpicsIssueId: migrating =====
main: -- execute("SET statement_timeout TO 0")
main:    -> 0.0004s
main: -- execute("ALTER TABLE epics VALIDATE CONSTRAINT check_450724d1bb;")
main: -- execute("RESET statement_timeout")
main: == [advisory_lock_connection] object_id: 55460, pg_backend_pid: 8714
STDERR:
```
此问题是因为极狐GitLab 17.0 中引入的后台迁移未完成。要升级，您可以：
- 升级到极狐GitLab 17.0，并等待所有后台迁移完成。
- 升级到极狐GitLab 17.1，然后手动执行后台作业和迁移，运行以下命令：
```
sudo gitlab-rake gitlab:background_migrations:finalize[BackfillEpicBasicFieldsToWorkItemRecord,epics,id,'[null]']
```
现在，您应该能够在极狐GitLab 17.1 中完成迁移并完成升级。此错误已在极狐GitLab 17.1.2 中修复，从极狐GitLab 16.x 直接升级到 17.1.2 不会导致这些问题。

Linux 软件包安装

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

已删除 PostgreSQL 13 的二进制文件。
在升级之前，您必须确保您的安装正在使用 PostgreSQL 14。
不再为 Ubuntu 18.04 构建软件包
确保您的操作系统已升级到 Ubuntu 20.04 或更高版本，然后再尝试升级极狐GitLab。

不过期的访问令牌

没有到期日期的访问令牌是无限期有效的，如果访问令牌被泄露，这会成为一个安全风险。

当您升级到极狐GitLab 16.0 及更高版本时，任何没有到期日期的个人、项目或组访问令牌会自动设置一个从升级日期起一年后到期的日期。

在应用此自动到期日期之前，您应该执行以下操作以减少中断：

有关更多信息，请参阅：

弃用和移除文档。
弃用议题。

从 17.1 及更早版本升级时需要注意的议题

如果客户使用极狐GitLab Duo 并升级到极狐GitLab 17.2.3 或更早版本，他们必须执行以下两个操作：
- 重新同步他们的许可证。
- 升级后重启服务器。
如果客户使用极狐GitLab Duo 并升级到极狐GitLab 17.2.4 或更高版本，他们必须执行以下两个操作之一：
- 重新同步他们的许可证。
- 等待下一次计划的许可证同步，通常每 24 小时进行一次。

客户升级到极狐GitLab 17.2.4 或更高版本后，这些步骤对于未来的升级不再需要。

从 17.3 升级时需要注意的议题

从极狐GitLab 17.3 升级时的迁移失败。

从 17.3 升级到 17.4 时，可能会遇到错误。在迁移过程中，您可能会看到如下所示的错误消息：

main: == [advisory_lock_connection] object_id: 127900, pg_backend_pid: 76263
main: == 20240812040748 AddUniqueConstraintToRemoteDevelopmentAgentConfigs: migrating
main: -- transaction_open?(nil)
main:    -> 0.0000s
main: -- view_exists?(:postgres_partitions)
main:    -> 0.0181s
main: -- index_exists?(:remote_development_agent_configs, :cluster_agent_id, {:name=>"index_remote_development_agent_configs_on_unique_agent_id", :unique=>true, :algorithm=>:concurrently})
main:    -> 0.0026s
main: -- execute("SET statement_timeout TO 0")
main:    -> 0.0004s
main: -- add_index(:remote_development_agent_configs, :cluster_agent_id, {:name=>"index_remote_development_agent_configs_on_unique_agent_id", :unique=>true, :algorithm=>:concurrently})
main: -- execute("RESET statement_timeout")
main:    -> 0.0002s
main: == [advisory_lock_connection] object_id: 127900, pg_backend_pid: 76263
rake aborted!
StandardError: An error has occurred, all later migrations canceled:

PG::UniqueViolation: ERROR:  could not create unique index "index_remote_development_agent_configs_on_unique_agent_id"
DETAIL:  Key (cluster_agent_id)=(1000141) is duplicated.

此错误是因为迁移在 remote_development_agent_configs 表的 cluster_agent_id 列上添加了唯一约束，但仍然存在重复条目。先前的迁移应当删除这些重复项，但在极少数情况下，新的重复项可能会在两次迁移之间插入。

要安全地解决此问题，请按照以下步骤操作：

打开运行迁移的 Rails 控制台。
将下面的脚本复制并粘贴到控制台中并执行。
重新运行迁移，应该可以成功完成。

 # Get the IDs to keep for each cluster_agent_id; if there are duplicates, only the row with the latest updated_at will be kept.
 latest_ids = ::RemoteDevelopment::RemoteDevelopmentAgentConfig.select("DISTINCT ON (cluster_agent_id) id")
   .order("cluster_agent_id, updated_at DESC")
   .map(&:id)

 # Get the list of remote_development_agent_configs to be removed.
 agent_configs_to_remove = ::RemoteDevelopment::RemoteDevelopmentAgentConfig.where.not(id: latest_ids)

 # Delete all duplicated agent_configs.
 agent_configs_to_remove.delete_all

17.7.0

OpenSSL 3 升级

在升级到极狐GitLab 17.7 之前，使用 OpenSSL 3 指南来识别和评估您的外部集成的兼容性。

Linux 软件包将 OpenSSL 从 v1.1.1w 升级到 v3.0.0。
云原生极狐GitLab (CNG) 已在极狐GitLab 16.7.0 中升级到 OpenSSL 3。如果您使用的是云原生极狐GitLab，无需执行任何操作。但是，请注意云原生混合安装使用 Linux 软件包进行有状态组件（如 Gitaly）的管理。对于这些组件，您需要验证使用的 TLS 版本、密码和证书是否符合以下讨论的安全级别更改。

随着 OpenSSL 3 的升级：

极狐GitLab 要求所有传入和传出的 TLS 连接使用 TLS 1.2 或更高版本。
TLS/SSL 证书必须具有至少 112 位的安全性。RSA、DSA 和 DH 密钥短于 2048 位，以及 ECC 密钥短于 224 位被禁止。

较旧的服务（如 LDAP 和 Webhook 服务器）可能仍使用 TLS 1.1。然而，TLS 1.0 和 1.1 已达到生命周期结束，不再被视为安全。极狐GitLab 将无法连接使用 TLS 1.0 或 1.1 的服务，并返回 no protocols available 错误消息。

此外，OpenSSL 3 将默认安全级别从级别 1 提升至 2，将安全位数从 80 提升至 112。因此，使用短于 2048 位的 RSA 和 DSA 密钥以及短于 224 位的 ECC 密钥签名的证书被禁止。

极狐GitLab 将无法连接使用签名不足的证书的服务，并返回 certificate key too weak 错误消息。有关更多信息，请参阅证书要求。

所有与 Linux 软件包一起提供的组件均与 OpenSSL 3 兼容。因此，您只需验证不属于极狐GitLab 软件包且为“外部”的服务和集成。

SSH 密钥不受此升级的影响。OpenSSL 设置的是 TLS 的安全要求，而不是 SSH。OpenSSH 和 gitlab-sshd 有其自己的加密算法配置设置。

请查看极狐GitLab 文档中有关保护您的安装的说明以获取更多详细信息。

17.5.0

OpenSSL 3 升级已推迟至极狐GitLab 17.7.0。

现在使用 AWS SDK v2 for Go 而不是 MinIO 客户端处理极狐GitLab Runner 分布式缓存的 S3 对象存储访问。您可以通过设置 FF_USE_LEGACY_S3_CACHE_ADAPTER 极狐GitLab Runner 功能标志为 true 来重新启用 MinIO 客户端。

17.4.0

从极狐GitLab 17.4 开始，新的极狐GitLab 安装在 ID 列方面具有不同的数据库架构。
- 所有以前的整数（32 位）ID 列（例如像 id、%_id、%_ids 这样的列）现在创建为 bigint（64 位）。
- 现有安装将在以后的版本中迁移从 32 位到 64 位整数，当数据库迁移交付执行此更改时。
- 如果您正在构建新的极狐GitLab 环境以测试升级，请安装极狐GitLab 17.3 或更早版本，以获得与现有环境相同的整数类型。然后您可以升级到更高版本，以运行与现有环境相同的数据库迁移。如果您是从备份中恢复到新环境中，则无需这样做，因为数据库恢复会删除现有的数据库架构定义，并使用作为备份一部分存储的定义。
Gitaly 需要 Git 2.46.0 及更高版本。对于从源代码安装，您应该使用 Gitaly 提供的 Git 版本。
Workhorse 中的 S3 对象存储上传现在默认使用 AWS SDK v2 for Go处理。如果您在 S3 对象存储上传中遇到问题，可以通过禁用 workhorse_use_aws_sdk_v2 功能标志降级到 v1。
当您升级到极狐GitLab 17.4 时，会为 Web IDE 生成一个 OAuth 应用程序。如果您的极狐GitLab 服务器的外部 URL 配置在 GitLab.rb 文件中包含大写字母，Web IDE 可能无法加载。要解决此问题，请参阅更新 OAuth 回调 URL。

17.3.0

Gitaly 需要 Git 2.45.0 及更高版本。对于从源代码安装，您应该使用 Gitaly 提供的 Git 版本。

Geo 安装 17.3.0

次要站点的 Geo 复制详细信息页面似乎是空的，即使 Geo 复制正在工作。没有已知的解决方法。该错误在极狐GitLab 17.4 中修复。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 16.11.5 - 16.11.10 None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
17.3 All 17.3.1

受影响的小版本	受影响的补丁版本	修复于
16.11	16.11.5 - 16.11.10	None
17.0	All	17.0.7
17.1	All	17.1.7
17.2	All	17.2.5
17.3	All	17.3.1

17.2.1

升级到极狐GitLab 17.2.1 可能会因为数据库中的未知序列而失败。此问题已在极狐GitLab 17.2.2 中修复。

升级到极狐GitLab 17.2.1 可能会失败并出现错误：

PG::DependentObjectsStillExist: ERROR: cannot drop desired object(s) because other objects depend on them

此数据库序列所有权问题已在极狐GitLab 17.2.1 中修复。然而，如果 17.2.0 中的迁移未完成，但由于格式错误的 JSON 文件，Linux 软件包阻止了升级到 17.2.1 或更高版本，您可能会遇到此问题。例如，您可能会看到此错误：

Malformed configuration JSON file found at /opt/gitlab/embedded/nodes/gitlab.example.com.json.
This usually happens when your last run of `gitlab-ctl reconfigure` didn't complete successfully.
This file is used to check if any of the unsupported configurations are enabled,
and hence require a working reconfigure before upgrading.
Please run `sudo gitlab-ctl reconfigure` to fix it and try again.

当前的解决方法是：

删除 /opt/gitlab/embedded/nodes 中的 JSON 文件：
```
rm /opt/gitlab/embedded/nodes/*.json
```
升级到极狐GitLab 17.2.1 或更高版本。

Geo 安装 17.2.1

在极狐GitLab 16.11 到极狐GitLab 17.2 中，缺少的 PostgreSQL 索引可能导致高 CPU 使用率、作业工件验证进度缓慢以及 Geo 指标状态更新缓慢或超时。该索引已在极狐GitLab 17.3 中添加。要手动添加索引，请参阅 Geo 故障排除 - 在作业工件验证期间主服务器上的高 CPU 使用率。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 All None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
次要站点的 Geo 复制详细信息页面似乎是空的，即使 Geo 复制正在工作。没有已知的解决方法。该错误在极狐GitLab 17.4 中修复。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 16.11.5 - 16.11.10 None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
17.3 All 17.3.1

受影响的小版本	受影响的补丁版本	修复于
16.11	All	None
17.0	All	17.0.7
17.1	All	17.1.7
17.2	All	17.2.5

受影响的小版本	受影响的补丁版本	修复于
16.11	16.11.5 - 16.11.10	None
17.0	All	17.0.7
17.1	All	17.1.7
17.2	All	17.2.5
17.3	All	17.3.1

17.1.0

具有不受信任的 extern_uid 的 Bitbucket 身份被删除。
默认的changelog模板生成的链接为完整的 URL，而不是极狐GitLab 特定的引用。
Gitaly 需要 Git 2.44.0 及更高版本。对于自编译安装，您应该使用 Gitaly 提供的 Git 版本。
升级到极狐GitLab 17.1.0 或 17.1.1 或极狐GitLab 17.0 中未完成的后台迁移可能会导致迁移运行失败。这是由于一个错误。

Geo 安装 17.1.0

在极狐GitLab 16.11 到极狐GitLab 17.2 中，缺少的 PostgreSQL 索引可能导致高 CPU 使用率、作业工件验证进度缓慢以及 Geo 指标状态更新缓慢或超时。该索引已在极狐GitLab 17.3 中添加。要手动添加索引，请参阅 Geo 故障排除 - 在作业工件验证期间主服务器上的高 CPU 使用率。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 All None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
次要站点的 Geo 复制详细信息页面似乎是空的，即使 Geo 复制正在工作。没有已知的解决方法。该错误在极狐GitLab 17.4 中修复。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 16.11.5 - 16.11.10 None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
17.3 All 17.3.1

受影响的小版本	受影响的补丁版本	修复于
16.11	All	None
17.0	All	17.0.7
17.1	All	17.1.7
17.2	All	17.2.5

受影响的小版本	受影响的补丁版本	修复于
16.11	16.11.5 - 16.11.10	None
17.0	All	17.0.7
17.1	All	17.1.7
17.2	All	17.2.5
17.3	All	17.3.1

17.0.0

Geo 安装 17.0.0

在极狐GitLab 16.11 到极狐GitLab 17.2 中，缺少的 PostgreSQL 索引可能导致高 CPU 使用率、作业工件验证进度缓慢以及 Geo 指标状态更新缓慢或超时。该索引已在极狐GitLab 17.3 中添加。要手动添加索引，请参阅 Geo 故障排除 - 在作业工件验证期间主服务器上的高 CPU 使用率。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 All None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
次要站点的 Geo 复制详细信息页面似乎是空的，即使 Geo 复制正在工作。没有已知的解决方法。该错误在极狐GitLab 17.4 中修复。
受影响的版本：

受影响的小版本受影响的补丁版本修复于

16.11 16.11.5 - 16.11.10 None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
17.3 All 17.3.1