GitLab 16.9 升级至 19.5

记录一下这次跨3个大版本的 GitLab 升级，具体是从 16.9.3 升级至 19.5.3。

另外，16.9.3 是部署在 CentOS 7.6 服务器上的，从 GitLab 18 开始不支持这个版本的 CentOS，这次升级顺便把 CentOS 换成 Ubuntu。

在 CentOS 服务器上备份 GitLab

先从 16.9.3 升级至 16.11.10

下载 16.11.10

wget -c https://packages.gitlab.com/gitlab/gitlab-ce/el/7/x86_64/Packages/g/gitlab-ce-16.11.10-ce.0.el7.x86_64.rpm

安装 16.11.10

rpm -Uvh gitlab-ce-16.11.10-ce.0.el7.x86_64.rpm

创建阿里云云盘并挂载，用于保存备份文件

mkdir /gitlab-bak
mount /dev/vdb1 /gitlab-bak

复制 gitlab 配置文件到备份云盘

cd /etc/gitlab
cp -r gitlab-secrets.json gitlab.rb ssl /gitlab-bak

修改备份文件夹的权限

chown git:git /gitlab-bak

gitlab 配置文章 /etc/gitlab/gitlab.rb 中修改备份路径至备份云盘

gitlab_rails['backup_path'] = "/gitlab-bak"

gitlab-ctl reconfigure

备份 gitlab

gitlab-backup create

或者

gitlab-rake gitlab:backup:create

需要注意的地方：备份前不能用 gitlab-ctl stop 命令停止 gitlab 所有服务，不然备份时会出现下面的错误

ActiveRecord::DatabaseConnectionError: There is an issue connecting to your database with your username/password, username: gitlab.

备份完成后，会生成下面的备份文件

1793490040_2026_11_01_16.11.10_gitlab_backup.tar

在 Ubuntu 服务器上恢复 GitLab 备份

准备一台系统是 Ubuntu 22.04 的阿里云云服务器（注：GitLab 16.11.10 支持的最高版本 Ubuntu 是 22.04）。

安装 GitLab 16.11.10

curl --location "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh" | sudo bash
EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ce=16.11.10-ce.0

挂载备份云盘

mkdir /gitlab-bak
mount /dev/vdb1 /gitlab-bak

在配置文件中修改备份文件夹路径

gitlab_rails['backup_path'] = "/gitlab-bak"

gitlab-ctl reconfigure

修改 tar.rb

vi /opt/gitlab/embedded/service/gitlab-rails/gems/gitlab-backup-cli/lib/gitlab/backup/cli/utils/tar.rb

从 tar_args 中移除以下2个参数

--unlink-first
--recursive-unlink

不然会出现下面的错误，造成恢复失败

Backup::Error: Restore operation failed: tar: .: Cannot unlink: Invalid argument

停止 puma 与 sidekiq 服务

gitlab-ctl stop puma
gitlab-ctl stop sidekiq

修改备份文件夹权限

chown git:git /gitlab-bak

恢复备份，需要去掉备份文件名后缀 _gitlab_backup.tar

gitlab-backup restore BACKUP=1793490040_2026_11_01_16.11.10

或者

gitlab-rake gitlab:backup:restore BACKUP=1793484972_2026_11_01_16.11.10

恢复数据库出现下面的错误提示，这个不影响恢复，忽略即可

Restoring PostgreSQL database gitlabhq_production ... ERROR:  must be owner of extension pg_trgm
ERROR:  must be owner of extension btree_gist
ERROR:  must be owner of extension plpgsql
ERROR:  must be owner of extension plpgsql
ERROR:  must be owner of extension btree_gist
ERROR:  must be owner of extension pg_trgm

将备份云盘上的 gitlab 配置文件复制到新服务器

cp /gitlab-bak
cp -r gitlab-secrets.json gitlab.rb ssl /etc/gitlab

注：ssl 是保存证书文件的目录

恢复之前删除的 tar_args 参数值

--unlink-first
--recursive-unlink

如果自定义了 data 与 uploads 的路径，恢复为默认值

# git_data_dirs({ "default" => { "path" => "/gitlab-data/git-data/" } })
# gitlab_rails['uploads_directory'] = "/gitlab-data/uploads"

重新配置 gitlab

gitlab-ctl reconfigure

重启 gitlab

gitlab-ctl restart

恢复过程的截图

恢复成功后继续在 Ubuntu 服务器上完成后续升级。

按以下路径从 16.11.10 升级至 19.5.3

apt-get install gitlab-ce=17.1.8-ce.0
apt-get install gitlab-ce=17.3.7-ce.0
apt-get install gitlab-ce=17.5.5-ce.0
apt-get install gitlab-ce=17.8.7-ce.0
apt-get install gitlab-ce=17.11.7-ce.0
apt-get install gitlab-ce=18.2.8-ce.0
apt-get install gitlab-ce=18.5.7-ce.0
apt-get install gitlab-ce=18.8.11-ce.0
apt-get install gitlab-ce=19.2.10-ce.0
apt-get install gitlab-ce=19.5.3-ce.0

为了加快升级速度，下载 .deb 包用 dpkg 命令安装（下载地址）

wget -c https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/jammy/pool/main/g/gitlab-ce/gitlab-ce_17.5.5-ce.0_amd64.deb
dpkg -i gitlab-ce_17.5.5-ce.0_amd64.deb
wget -c https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/jammy/pool/main/g/gitlab-ce/gitlab-ce_17.8.7-ce.0_amd64.deb

这样可以一边升级，一边下载 GitLab 安装包。

升级至 17.8.7 后，gitlab-ctl reconfigure 过程中出现下面的错误

PG::CheckViolation: ERROR:  check constraint "check_83faf1f5e7" of relation "packages_dependencies" is violated by some row

启动数据库控制台

gitlab-rails dbconsole --database main

发现 142 个 packages 的 project_id 为 null

SELECT COUNT(*) FROM packages_dependencies WHERE project_id IS NULL;

删除这些包后问题解决

DELETE FROM packages_dependencies WHERE project_id IS NULL;

在 Ubuntu 服务器上依次进行10个版本的升级后，终于完成这次“三级跳”式的 GitLab 大升级。