升级 GitLab
所有等级
自我管理
升级 GitLab 是一个相对简单的过程，但根据您使用的安装方法、您的 GitLab 版本的旧版本、是否升级到主要版本等，复杂性可能会增加。
请务必阅读整个页面，因为它包含与每种升级方法相关的信息。
将 GitLab 升级到最新的可用补丁版本，例如13.8.8而不是13.8.0. 这包括您必须在升级路径上停留的版本，因为可能有与升级过程相关的问题的修复程序。
该维修策略文档 有关于升级，包括额外的信息：
- 如何解释 GitLab 产品版本控制。
- 关于要运行的版本的建议。
- 我们如何使用补丁和安全补丁版本。
- 当我们向后移植代码更改时。
根据安装方式升级
根据安装方式和你的 GitLab 版本，官方有多种更新 GitLab 的方式：
Linux 包（综合 GitLab）
该软件包升级指南 包含更新官方GitLab仓库安装了一个包所需的步骤。
当您想要更新到特定版本时，也有说明 。
从源安装
- 从源代码升级社区版和企业版 - 从源代码升级社区版和企业版的指南。
- 补丁版本指南包括补丁版本所需的步骤，例如 13.2.0 到 13.2.1，适用于社区版和企业版。
过去，我们使用单独的文档来进行升级说明，但此后我们转而使用单个文档。旧的升级指南仍然可以在 Git 存储库中找到：
使用 Docker 安装
GitLab 为社区版和企业版提供官方 Docker 镜像。它们基于 Omnibus 包，有关如何更新它们的说明位于单独的文档中。
使用 Helm 安装
GitLab 可以使用 Helm 部署到 Kubernetes 集群中。有关如何更新云原生部署的说明位于 单独的文档中。
使用 从图表版本到 GitLab 版本的版本映射来确定升级路径。
计划您的升级
请参阅指南以计划您的 GitLab 升级。
升级前检查后台迁移
在更新到较新版本之前，某些版本可能需要完成不同的迁移。
批量迁移是 GitLab 14.0 及更高版本中可用的迁移类型。后台迁移和批量迁移不一样，所以你应该在更新之前检查两者是否完整。
通过增加 可以处理队列中作业的Sidekiq 工作器的数量来减少完成这些迁移所需的时间 background_migration。
后台迁移
对于 Omnibus 安装：
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.pending'对于从源安装：
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.pending'批量后台迁移
GitLab 14.0 引入了批量后台迁移。
某些安装可能需要运行 GitLab 14.0 至少一天才能完成该升级引入的数据库更改。
检查批量后台迁移的状态
要检查批量后台迁移的状态：
Finished在升级 GitLab 之前，所有迁移都必须具有状态。
批量后台迁移的状态也可以直接在数据库中查询。
-
psql根据您的实例安装方法（例如，sudo gitlab-psql对于 Omnibus 安装）的说明登录提示。 - 在
psql会话中运行以下查询以查看有关未完成的批处理后台迁移的详细信息：
select job_class_name, table_name, column_name, job_arguments from batched_background_migrations where status <> 3;如果迁移未完成并且您尝试更新到更高版本，GitLab 会提示您错误：
Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':如果出现此错误，请检查批处理后台迁移选项以完成升级。
如果我的后台迁移卡住了怎么办？
以下操作可能会破坏您的 GitLab 性能。
重新执行这些命令是安全的，尤其是当您有 1000 多个可能会溢出运行时内存的待处理作业时。
用于综合安装
# Start the rails console
sudo gitlab-rails c
# Execute the following in the rails console
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }对于从源安装
# Start the rails console
sudo -u git -H bundle exec rails RAILS_ENV=production
# Execute the following in the rails console
scheduled_queue = Sidekiq::ScheduledSet.new
pending_job_classes = scheduled_queue.select { |job| job["class"] == "BackgroundMigrationWorker" }.map { |job| job["args"].first }.uniq
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }批量迁移（GitLab 14.0 及更新版本）：
请参阅对批处理后台迁移进行故障排除。
处理运行 CI/CD 管道和作业
如果在 GitLab Runner 处理作业时升级 GitLab 实例，则跟踪更新将失败。当 GitLab 重新上线时，跟踪更新应该会自我修复。但是，根据错误，GitLab Runner 会重试或最终终止作业处理。
至于工件，GitLab Runner 尝试上传它们 3 次，之后作业最终失败。
针对以上两种情况，建议升级前进行以下操作：
- 计划您的维护。
- 暂停你的跑步者。
- 等待所有作业完成。
- 升级 GitLab。
检查挂起的高级搜索迁移
此部分仅在您启用了Elasticsearch 集成时适用。
主要版本要求 在主要版本升级之前从当前版本中的最新次要版本完成所有高级搜索迁移。您可以通过运行以下命令来查找挂起的迁移：
用于综合安装
sudo gitlab-rake gitlab:elastic:list_pending_migrations对于从源安装
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations如果我的高级搜索迁移卡住了怎么办？
了解如何重试暂停的迁移。
无需停机即可升级
升级到新的主要版本
升级主要版本需要更多关注。向后不兼容的更改和迁移保留给主要版本。请仔细按照说明进行操作，因为我们无法保证主要版本之间的升级是无缝的。
需要按照以下升级步骤确保主版本升级成功：
- 升级到先前主要版本的最新次要版本。
- 升级到下一个主要版本 (
X.0.Z)。 - 升级到它的第一个次要版本 (
X.1.Z)。 - 继续升级到该主要版本的较新版本。
确定支持的升级路径。
在升级到新的主要版本之前，确保所有后台迁移都已完全完成也很重要。要查看background_migration队列的当前大小， 请在升级前检查后台迁移。
如果您已启用Elasticsearch 集成，请确保在当前版本中的最后一个次要版本中完成所有高级搜索迁移。 在继续进行主要版本升级之前，请务必 检查待处理的高级搜索迁移。
如果您的 GitLab 实例有任何关联的运行器，升级 GitLab Runner 以匹配升级到的 GitLab 次要版本非常重要。这是为了确保与 GitLab 版本的兼容性。
升级路径
一次升级跨多个 GitLab 版本只能通过接受停机时间来实现。以下示例假设升级时停机是可以接受的。如果您不想停机，请阅读如何零停机升级。
找到您的版本在下面的升级路径中的位置，并相应地升级 GitLab，同时参考 版本特定的升级说明：
8.11.Z-> 8.12.0-> 8.17.7-> 9.5.10-> 10.8.7-> 11.11.8-> 12.0.12-> 12.1.17-> 12.10.14-> 13.0.14-> 13.1.11-> 13.8.8->最新13.12.Z->最新14.0.Z->最新14.1.Z->最新14.Y.Z
下表虽然并非详尽无遗，但显示了支持的升级路径的一些示例。上述版本之间的附加步骤是可能的。我们只列出了最低限度的必要步骤。
目标版本 | 你的版本 | 支持的升级路径 | 笔记 |
|
|
| 需要三个中间版本： |
|
|
| 需要两个中间版本： |
|
|
| 需要四个中间版本： |
|
|
| 需要六个中间版本： |
|
|
| 需要三个中间版本： |
|
|
| 需要四个中间版本： |
|
|
| 需要五个中间版本： |
|
|
|
|
版本间升级
GitLab有两个版本：社区版是MIT许可，以及企业版，其基于社区版的顶部，包括额外的功能，主要是针对机构拥有超过100个用户。
您可以在下面找到一些帮助您更改 GitLab 版本的指南。
社区到企业版
以下指南仅适用于企业版订阅者。
如果您希望将 GitLab 安装从社区版升级到企业版，请根据安装方法按照以下指南进行操作：
- 源 CE 到 EE 更新指南- 步骤与版本升级非常相似：停止服务器，获取代码，更新新功能的配置文件，安装库并进行迁移，更新初始化脚本，启动应用程序并检查其地位。
- Omnibus CE 到 EE - 按照本指南将您的 Omnibus GitLab 社区版更新为企业版。
企业到社区版
如果您需要将企业版安装降级回社区版，您可以按照本指南使该过程尽可能顺利。
特定版本升级说明
每个月，GitLab 的主要、次要或补丁版本都会与发布帖子一起 发布。您应该阅读您传递的所有版本的发布帖子。在主要和次要发布帖子的末尾，有三个部分需要专门查找：
- 弃用
- 移除
- 升级的重要注意事项
这些包括：
- 作为升级的一部分需要执行的步骤。例如8.12 需要重新创建 Elasticsearch 索引。任何旧版本的 GitLab 升级到 8.12 或更高版本都需要这样做。
- 对我们支持的软件版本的更改，例如 在 GitLab 13 中停止支持 IE11。
除了本节中的说明外，您还应该根据您安装 GitLab 的方式检查特定于安装的升级说明：
以下与 Ruby 和 Git 版本相关的特定信息不适用于Omnibus 安装 和Helm Chart 部署。它们带有适当的 Ruby 和 Git 版本，并且没有使用 Ruby 和 Git 的系统二进制文件。使用这两种方法时无需安装 Ruby 或 Git。
14.5.0
- 当
make运行时，Gitaly版本是现在创建_build/bin的源目录的根目录下，并不再。如果您使用的是源代码安装，在你更新到这些二进制文件systemd单元文件 或init脚本由下面的文档。 - Workhorse 和 Gitaly 之间的连接
backchannel默认使用 Gitaly协议。如果您在 Workhorse 和 Gitaly 之间部署了 gRPC 代理，Workhorse 将无法再连接。作为解决方法，禁用临时workhorse_use_sidechannel 功能标志。如果您需要 Workhorse 和 Gitaly 之间的代理，请使用 TCP 代理。如果您对此更改有任何反馈，请转到此问题。 - 在 14.1 中，我们引入了后台迁移，它改变了我们存储合并请求差异提交的方式，以显着减少所需的存储量。在 14.5 中，我们引入了一组迁移，通过确保
merge_request_diff_commits完成表上的所有剩余作业来完成此过程。在大多数情况下，这些作业已经处理完毕，因此在升级到 14.5 期间不需要额外的时间。但如果还有剩余作业，部署可能需要额外几分钟才能完成。
所有合并请求差异提交将自动合并这些更改，并且没有额外的要求来执行升级。merge_request_diff_commits表中的现有数据保持解包状态，直到您运行VACUUM FULL merge_request_diff_commits. 但请注意，该VACUUM FULL操作会锁定并重写整个merge_request_diff_commits表，因此该操作需要一些时间才能完成，并且会阻止对该表的访问，直到该过程结束。我们建议您仅在 GitLab 未主动使用或在此过程中脱机时运行此命令。完成所需的时间取决于表的大小，可以使用select pg_size_pretty(pg_total_relation_size('merge_request_diff_commits'));.
有关更多信息，请参阅此问题。
14.4.0
- 需要 Git 2.33.x 及更高版本。我们建议您使用Gitaly 提供的 Git 版本。
- 请参阅GitLab 13.9 到 14.4 中的维护模式问题。
- 在 14.4.0 中默认启用数据库负载平衡后，我们发现了一个问题，即 如果与 PostgreSQL 的连接被切断，cron 作业将无法工作，因为 Sidekiq 会继续使用错误的连接。在重新启动 Sidekiq 之前，依赖定期运行的 cron 作业的 Geo 和其他功能不起作用。如果此问题影响到您，我们建议升级到 GitLab 14.4.3 及更高版本。
14.3.0
- 运行 14.0.0-14.0.4 的实例不应直接升级到 GitLab 14.2 或更高版本。
- 在从早期的 GitLab 14 版本升级到 14.3.Z 之前，确保批量后台迁移完成。
- 需要 Ruby 2.7.4。 有关如何继续操作，请参阅Ruby 安装说明。
- GitLab 14.3.0 包含部署后迁移，以解决下表列出的具有整数 PK的表的主键溢出风险：
如果迁移作为无停机部署的一部分执行，则存在由于锁定与应用程序逻辑冲突而导致锁定超时或死锁的失败风险。在每种情况下，这些迁移都可以安全地重新运行，直到成功：
# For Omnibus GitLab
sudo gitlab-rake db:migrate
# For source installations
sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production14.2.0
- 运行 14.0.0-14.0.4 的实例不应直接升级到 GitLab 14.2 或更高版本。
- 在从早期的 GitLab 14 版本升级到 14.2.Z 之前，确保批量后台迁移完成。
- GitLab 14.2.0 包含后台迁移，以解决下表列出的具有整数 PK的表的主键溢出风险：
- ci_build_needs
- ci_build_trace_chunks
- ci_builds_runner_session
- deployments
- geo_job_artifact_deleted_events
- push_event_payloads
ci_job_artifacts：
如果迁移作为无停机部署的一部分执行，则存在由于锁定与应用程序逻辑冲突而导致锁定超时或死锁的失败风险。在每种情况下，这些迁移都可以安全地重新运行，直到成功：
# For Omnibus GitLab
sudo gitlab-rake db:migrate
# For source installations
sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production14.1.0
- 运行 14.0.0 - 14.0.4 的实例不应直接升级到 GitLab 14.2 或更高版本， 但可以升级到 14.1.Z。
已经运行 14.0.5（或更高版本）的实例不需要在 14.1.Z 停止。14.1 包含在升级路径中，以实现与自我管理安装的最广泛兼容性，并确保 14.0.0-14.0.4 安装不会遇到批处理后台迁移问题。 - 请参阅GitLab 13.9 到 14.4 中的维护模式问题。
14.0.0
- 升级到 GitLab 14.0 所做的数据库更改可能需要数小时或数天才能在更大的 GitLab 实例上完成。这些批量后台迁移更新整个数据库表以减轻主键溢出，并且必须在升级到 GitLab 14.2 或更高版本之前完成。
- 由于其中一个问题
BatchedBackgroundMigrationWorkers是 不工作 的自我管理的情况下，修复被创造 ，需要更新到至少14.0.5。该修复程序也在14.1.0 中发布。
更新到 14.0.5 或更高版本的 14.0 补丁版本后， 需要先完成批量后台迁移， 然后才能更新到更高版本。
如果迁移未完成并且您尝试更新到更高版本，您将看到如下错误：
Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active':查看如何解决此错误。
- 在 GitLab 13.3中不推荐使用一些管道处理方法， 并且在 GitLab 14.0 中完全删除了此代码。如果您计划从GitLab 13.2 或更早版本直接升级 到 14.0（不受支持），则升级时不应运行任何管道，否则升级完成时管道可能会报告错误状态。您应该改为遵循受支持的升级路径。
- 已取消对 PostgreSQL 11 的支持。在更新到 GitLab 14.0 之前，请确保将您的数据库更新到版本 12。
- 请参阅GitLab 13.9 到 14.4 中的维护模式问题。
升级到更高版本的 14.Y
- 由于批量后台迁移，运行 14.0.0 - 14.0.4 的实例不应直接升级到 GitLab 14.2 或更高版本。
- 首先升级到：
- 14.0.5 或更高版本的 14.0.Z 补丁版本。
- 14.1.0 或更高版本的 14.1.Z 补丁版本。
- 批量后台迁移需要 在更新到更高版本之前完成，并且可能需要比平时更长的时间。
13.12.0
请参阅GitLab 13.9 到 14.4 中的维护模式问题。
13.11.0
- 需要 Git 2.31.x 及更高版本。我们建议您使用Gitaly 提供的 Git 版本。
- 请参阅GitLab 13.9 到 14.4 中的维护模式问题。
13.10.0
请参阅GitLab 13.9 到 14.4 中的维护模式问题。
13.9.0
- 在
sudo gitlab-rake db:migrate部署节点上运行最终命令之前，使用 PostgreSQL 控制台（或sudo gitlab-psql）执行以下查询以删除有问题的触发器：
drop trigger trigger_e40a6f1858e6 on application_settings;
drop trigger trigger_0d588df444c8 on application_settings;
drop trigger trigger_1572cbc9a15f on application_settings;
drop trigger trigger_22a39c5c25f3 on application_settings;- 运行最后的迁移：
sudo gitlab-rake db:migrate如果您已经sudo gitlab-rake db:migrate在部署节点上运行了最终命令并且遇到了列重命名问题，您会看到以下错误：
-- remove_column(:application_settings, :asset_proxy_whitelist)
rake aborted!
StandardError: An error has occurred, all later migrations canceled:
PG::DependentObjectsStillExist: ERROR: cannot drop column asset_proxy_whitelist of table application_settings because other objects depend on it
DETAIL: trigger trigger_0d588df444c8 on table application_settings depends on column asset_proxy_whitelist of table application_settings要解决此错误，请按照前面的步骤完成更新。本期提供了更多详细信息。
13.8.8
GitLab 13.8 包括后台迁移以解决重复服务记录的问题。如果存在重复的服务，则此后台迁移必须在唯一索引应用于服务表之前完成，这是在 GitLab 13.9中引入的。从 GitLab 13.8 及更早版本升级到更高版本必须包括对 GitLab 13.8.8 的中间升级，并且必须等到后台迁移完成才能继续。
如果仍然存在重复的服务，升级到 13.9.x 或更高版本会导致升级失败并显示以下错误：
PG::UniqueViolation: ERROR: could not create unique index "index_services_on_project_id_and_type_unique"
DETAIL: Key (project_id, type)=(NNN, ServiceName) is duplicated.13.6.0
需要 Ruby 2.7.2。GitLab 不是从 Ruby 2.6.6 或更旧版本开始的。
所需的 Git 版本是 Git v2.29 或更高版本。
13.4.0
GitLab 13.4.0 包括后台迁移，将遗留存储中的所有剩余存储库移动到散列存储。此迁移存在已知问题，已在 GitLab 13.5.4 及更高版本中修复。如果可能，请跳过 13.4.0 并升级到 13.5.4 或更高版本。请注意，迁移可能需要很长时间才能运行，具体取决于必须移动的存储库数量。在进一步升级之前，请务必检查所有后台迁移是否已完成。
13.3.0
推荐的 Git 版本是 Git v2.28。Git v2.24 所需的最低版本保持不变。
13.2.0
由于 Rails 中的重大更改可能导致授权问题，因此具有多个 Web 节点的 GitLab 安装必须先 升级到 13.1，然后才能升级到 13.2（及更高版本）。
GitLab 13.2.0修复了电子邮件验证绕过。升级后，如果您的某些用户在登录时意外遇到 404 或 422 错误，或者在使用命令行时出现“被阻止”消息，则他们的帐户可能未得到确认。在这种情况下，请让他们查看电子邮件以获取重新确认链接。有关更多信息，请参阅我们对电子邮件确认问题的讨论。
GitLab 13.2.0 依赖于btree_gistPostgreSQL的扩展。对于使用外部管理的 PostgreSQL 设置的安装，如果 GitLab 的数据库用户不是超级用户，请确保 在升级 GitLab 之前手动安装扩展。这对于使用 GitLab 管理的 PostgreSQL 数据库的安装来说不是必需的。
13.1.0
在 13.1.0 中，您必须升级到：
- 至少 Git v2.24（以前，所需的最低版本是 Git v2.22）。
- 推荐的 Git v2.26。
由于使用了新的--end-of-optionsGit 标志，否则会导致某些 RPC 中 Gitaly 服务出现内部错误。
此外，在 GitLab 13.1.0 中，Rails的版本从 6.0.3 升级到 6.0.3.1。Rails 升级包括对不向后兼容的 CSRF 令牌生成的更改 - 具有新 Rails 版本的 GitLab 服务器生成具有旧 Rails 版本的 GitLab 服务器无法识别的 CSRF 令牌 - 这可能导致非 GET 请求失败多节点 GitLab 安装。
因此，如果您使用多个 Rails 服务器并专门从 13.0 升级，则必须先将所有服务器升级到 13.1.Z，然后再升级到 13.2.0 或更高版本：
- 确保所有 GitLab Web 节点都运行 GitLab 13.1.Z。
- 启用
global_csrf_token功能标志以启用CSRF令牌生成的新方法：
Feature.enable(:global_csrf_token)- 只有这样，才能继续升级到更高版本的 GitLab。
12.2.0
在 12.2.0 中，我们启用了 Rails 的经过身份验证的 cookie 加密。旧会话会自动升级。
但是，不支持会话 cookie 降级。因此，升级到 12.2.0 后，任何降级都会导致所有会话无效并且用户注销。
12.1.0
如果您打算从 升级12.0.Z到12.10.Z，则需要在升级12.1.Z前执行中间升级到，12.10.Z以避免出现#215141 之类的问题。
12.0.0
在 12.0.0 中，我们进行了各种与数据库相关的更改。这些更改要求用户首先升级到最新的 11.11 补丁版本。升级到 11.11.Z 后，用户可以升级到 12.0.Z。否则可能会导致无法应用数据库迁移，从而导致应用程序错误。
还需要您升级到 12.0.Z，然后再移动到 12.Y 的更高版本。
示例 1：您当前使用的是 GitLab 11.11.8，这是 11.11.Z 的最新补丁版本。您可以像往常一样升级到 12.0.Z。
示例 2：您当前使用的是 GitLab 10.Y 版本。要升级，请先升级到最后一个 10.Y 版本 (10.8.7)，然后再升级到最后一个 11.Y 版本 (11.11.8)。升级到 11.11.8 后，您可以安全地升级到 12.0.Z。
GitLab 13.9 到 14.4 中的维护模式问题
当维护模式启动时，使用者无法与SSO，SAML，或LDAP登录。
在启用维护模式之前登录的用户将继续登录。如果启用维护模式的管理员丢失了他们的会话，那么他们将无法通过 UI 禁用维护模式。在这种情况下，您可以通过 API 或 Rails 控制台禁用维护模式。
此错误已在 GitLab 14.5.0 中修复，预计将向后移植到 GitLab 14.3 和 14.4。
各种各样的
- MySQL 到 PostgreSQL将指导您将数据库从 MySQL 迁移到 PostgreSQL。
- 升级失败后从备份中恢复
- 使用 Slony 升级 PostgreSQL，用于以最少的停机时间升级 PostgreSQL 数据库。
- 管理 PostgreSQL 扩展
