Sign in

Gitlab 跨主版本升级指南

Gitlab 跨主版本升级指南
CC（知识共享许可协议）: BY（署名）-NC（非商业性）-SA（相同方式共享）

本文为对自己的 Gitlab 实例从 v13 版本升级到 v18 版本的过程的记录笔记。

1️⃣ 升级前准备

务必进行备份，以防升级失败

执行备份

# 创建备份（注意修改 -it 后面的 gitlab 为你的编排命名）
docker compose exec -it gitlab gitlab-rake gitlab:backup:create

# 备份只有数据，还需要额外拷贝配置与密钥文件（注意修改你对应的文件和目录）
# 密钥文件会影响 2FA 登录的 OTP 生成
docker compose cp gitlab:/etc/gitlab/gitlab.rb ./data/backups/gitlab.rb
docker compose cp gitlab:/etc/gitlab/gitlab-secrets.json ./data/backups/gitlab-secrets.json

备份文件将会输出在 /var/opt/gitlab/backups 中（使用 Docker 容器部署时），当需要恢复备份时，也需要备份文件位于这个目录中。

并且推荐跨主版本升级时，每个主版本都要备份一次。

恢复备份

恢复备份前需要确保当前 gitlab 容器运行的版本与备份文件一致，即文件名 1750378735_2025_06_20_13.11.3_gitlab_backup.tar 中 13.11.3 这个部分。

# 以下命令注意修改 -it 后面的 gitlab 为你的编排命名
# 恢复备份前，需要停止 puma、sidekiq 等连接数据库的进程
docker compose exec -it gitlab gitlab-ctl stop puma
docker compose exec -it gitlab gitlab-ctl stop sidekiq

# 验证服务是否已停止，应输出
# down: puma: ...
# down: sidekiq: ...
docker compose exec -it gitlab gitlab-ctl status | grep -E 'puma|sidekiq'

# 恢复备份
# BACKUP 为要恢复的备份文件。只需要备份文件名的前部分，不需要整个文件名（去除 _gitlab_backup.tar）
docker compose exec -it gitlab gitlab-rake gitlab:backup:restore BACKUP=1750378735_2025_06_20_13.11.3

# 恢复配置与密钥（注意修改你对应的文件和目录）
docker compose cp ./data/backups/gitlab.rb gitlab:/etc/gitlab/gitlab.rb
docker compose cp ./data/backups/gitlab-secrets.json gitlab:/etc/gitlab/gitlab-secrets.json

# 恢复完成后重启容器，确保状态干净
docker compose restart gitlab

确保没有后台 Migration（自 v14 版本起）

当队列和失败都为0时，才能进行下一步升级。详见官方文档 Check the status of batched background migrations

注意磁盘空间

跨主版本升级时会拉取运行很多子版本镜像，注意磁盘空间，随时清理旧版本镜像。

# 检查磁盘空间
df -h

# 如果你的服务器上没有其他服务，只运行 Gitlab 则可以通过此命令清理停止的容器、不使用的镜像、构建缓存等。
# 否则，请谨慎清理。
docker system prune --all

错误码

Gitlab 502

可以显示 Gitlab Logo 时且携带 502 错误码，通常表示服务未启动完成，多等一段时间再刷新。

Gitlab 500

可以显示 Gitlab Logo 时且携带 500 错误码，大概率表示升级失败，需要回滚恢复重新操作。

Other 500/502

如果你通过 Nginx 反向代理，不显示 Gitlab Logo 直接输出 500/502 则表示 Gitlab 服务还没有启动。如果特别长时间的 500/502 则大概率配置或数据错误，Gitlab 无法启动。

2️⃣ 升级方式

Gitlab 升级需要严格遵循升级路径，大体上是每个子版本都需要，确保所有的库 migration 代码执行。可使用工具 Upgrade Path Tool 查询升级路径。

由于我使用的是 Docker Compose 部署的官方镜像，所以我的升级只需要修改配置文件的 版本号（gitlab/gitlab-ce:<版本号>-ce.0），再 docker compose down && docker compose up -d 重启即可。

如希望不停机升级，路径节点需要包含更多的子版本，详见官方文档 Zero Downtime Upgrades

3️⃣ 例外情况

所有升级时例外情况（非简单按路径更换版本号，需要额外操作）都在 Upgrade Path Tool 中各个版本上有详细说明。建议仔细阅读，尤其关注 Before upgrading 前后交代的步骤。

由于我使用的是官方的 gitlab/gitlab-ce 镜像，内集成了数据库，所以后续例外操作我不再关注数据库版本升级的指示。

💡 v13 → v14

迁移存储库

v14 版本起，全面启用哈希存储，如果从 v13.x 版本直接升级到 v14.x版本，且其中的传统存储未进行转换的话，将会升级失败，有如下提示：

Legacy storage is no longer supported. Please migrate your data to hashed storage.
Check https://docs.gitlab.com/ee/administration/raketasks/storage.html#migrate-to-hashed-storage for details.

需要在 v13 的最后一个版本，将传统存储转换为哈希存储：

# 进入容器交互
docker compose exec -it gitlab bash

# 存储库迁移
gitlab-rake gitlab:storage:migrate_to_hashed

# 验证存储库迁移
# 该命令输出的数量应和 /admin 页面中的项目数量总数一致
gitlab-rake gitlab:storage:hashed_projects


# 如果全部迁移成功以下两条命令应该为 0
gitlab-rake gitlab:storage:legacy_projects
gitlab-rake gitlab:storage:legacy_attachments

迁移 Web 服务器

v14 版本将从 unicorn 全面转为使用 puma web server，如果你的 gitlab.rb 文件中针对 unicorn 进行了自定义配置，需要根据官方文档的转换规则调整配置。Switch from unicorn to puma

💡 v14 → v15

需要移除 gitlab.rb 中所有已废除的配置，详见归档文档：https://archives.docs.gitlab.com/15.1/ee/update/removals.html

根据 AI 的总结，大概有这些（谨慎辨别）：

  • background_upload
  • gitlab_rails['lfs_object_store （包括 direct 和 background）
  • omniauth["kerberos"] 或相关 Kerberos 配置
  • gitlab_rails['pat_expiration']、gitlab_rails['ssh_expiration']
  • 任何与 repository audit events 相关的配置项

💡 v15.7.9 → v15.11.13

没看到更新说明上有额外指示，但直接升级报错：gitlab_rails['smtp_tls'] and gitlab_rails['smtp_enable_starttls_auto'] are mutually exclusive. Set one of them to false. SMTP providers usually use port 465 for TLS and port 587 for STARTTLS.

我注释掉了 smtp_enable_starttls_auto 升级成功