Linux GitLab迁移与升级指南

一、迁移前准备

1. 版本一致性确认

迁移前需确保新旧服务器GitLab版本完全一致（如旧服务器为14.6.0，新服务器需先安装14.6.0）。版本不一致会导致数据结构不兼容，引发恢复失败或功能异常。

2. 备份数据

使用GitLab自带工具备份所有关键数据（仓库、数据库、配置、CI/CD设置等）：

# 进入GitLab备份目录
cd /var/opt/gitlab/backups
# 创建全量备份（RAILS_ENV=production表示生产环境）
sudo gitlab-rake gitlab:backup:create RAILS_ENV=production

备份文件默认以时间戳_版本号_gitlab_backup.tar格式命名（如1725431200_2024_09_04_16.2.4_gitlab_backup.tar）。
额外备份配置文件（避免配置丢失）：

sudo cp /etc/gitlab/gitlab.rb /path/to/backup/  # 主配置文件
sudo cp /etc/gitlab/gitlab-secrets.json /path/to/backup/  # 敏感信息（如数据库密码、加密密钥）

3. 传输备份文件

将备份文件及配置文件复制到新服务器（使用scp命令，需输入新服务器密码）：

scp /var/opt/gitlab/backups/*.tar root@new_server_ip:/var/opt/gitlab/backups/
scp /path/to/backup/gitlab.rb root@new_server_ip:/etc/gitlab/
scp /path/to/backup/gitlab-secrets.json root@new_server_ip:/etc/gitlab/

二、迁移执行步骤

1. 新服务器安装相同版本GitLab

根据新服务器操作系统选择安装方式（以CentOS为例，使用YUM包管理器）：

# 添加GitLab官方仓库（以14.6.0为例）
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash
# 安装指定版本
sudo yum install -y gitlab-ce-14.6.0-ce.0.el7.x86_64

2. 恢复备份数据

（1）设置备份文件权限

确保新服务器备份目录权限正确（属主为git用户）：

cd /var/opt/gitlab/backups
sudo chown git:git *.tar  # 修改备份文件属主
sudo chmod 777 *.tar     # 临时开放权限（恢复后建议改回755）

（2）执行恢复命令

# 停止相关服务（避免数据冲突）
sudo gitlab-ctl stop unicorn
sudo gitlab-ctl stop sidekiq
# 恢复备份（BACKUP参数为备份文件名中的时间戳部分）
sudo gitlab-rake gitlab:backup:restore BACKUP=1725431200_2024_09_04_16.2.4
# 恢复过程中会提示确认，输入"yes"继续

（3）重启GitLab服务

sudo gitlab-ctl start  # 启动所有服务
sudo gitlab-ctl status # 检查服务状态（确保所有服务均为"run"）

3. 验证迁移结果

• Web界面检查：访问新服务器GitLab地址（如http://new_server_ip），使用原管理员账号（root）登录，确认项目、用户、CI/CD配置等是否完整。
• 命令行检查：通过Git克隆一个项目，验证代码仓库是否可正常访问：

  git clone http://new_server_ip/username/project.git
  

三、升级前准备

1. 查看当前版本

确认当前GitLab版本（用于确定升级路径）：

cat /opt/gitlab/embedded/service/gitlab-rails/VERSION  # RPM安装
# 或
cat /usr/lib/gitlab/embedded/service/gitlab-rails/VERSION  # Debian安装

2. 查阅官方升级路径

GitLab升级必须遵循逐步升级原则（不能跨大版本直接升级），避免数据损坏。例如：

• 从13.10.2升级到15.0.0，需依次经过：13.10.2 → 13.12.15 → 14.0.12 → 14.3.6 → 14.9.5 → 14.10.4 → 15.0.0。
• 官方升级路径查询：访问GitLab Upgrade Paths，输入当前版本获取详细步骤。

3. 备份数据

升级前必须备份所有数据（步骤同迁移备份），防止升级失败导致数据丢失。

四、升级执行步骤

1. 停止相关服务

升级前停止GitLab关键服务（避免数据冲突）：

sudo gitlab-ctl stop unicorn
sudo gitlab-ctl stop sidekiq
# 可选：停止Nginx（若使用自定义配置）
sudo gitlab-ctl stop nginx

2. 升级GitLab包

根据安装方式选择升级命令（以RPM包为例）：

# 下载新版本rpm包（以14.0.12为例）
wget https://packages.gitlab.com/gitlab/gitlab-ce/packages/el/7/gitlab-ce-14.0.12-ce.0.el7.x86_64.rpm
# 安装新版本（--nobest忽略依赖冲突，--skip-broken跳过损坏包）
sudo rpm -Uvh --nobest --skip-broken gitlab-ce-14.0.12-ce.0.el7.x86_64.rpm

3. 重新配置与重启

# 重新配置GitLab（应用新版本设置）
sudo gitlab-ctl reconfigure
# 重启所有服务
sudo gitlab-ctl restart
# 检查服务状态
sudo gitlab-ctl status

4. 验证升级结果

• 版本检查：再次查看版本号，确认已升级到目标版本：

  cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
  

• 功能测试：访问Web界面，创建项目、提交代码，验证核心功能是否正常。

五、常见问题处理

1. 哈希存储迁移失败

若从13.X直接升级到14.X，可能因传统存储未转换导致失败。需先执行哈希存储迁移：

sudo gitlab-rake gitlab:storage:migrate_to_hashed

2. glibc版本过高导致PostgreSQL问题

若升级系统glibc到2.28及以上，PostgreSQL可能无法正常启动。需手动备份并还原PostgreSQL数据：

# 备份PostgreSQL数据
sudo -u postgres pg_dumpall > /tmp/pg_backup.sql
# 卸载旧版本GitLab（保留数据目录）
sudo yum remove gitlab-ce
# 重新安装GitLab
sudo yum install gitlab-ce-新版本.rpm
# 恢复PostgreSQL数据
sudo -u postgres psql -f /tmp/pg_backup.sql

3. 邮箱验证问题（13.X及以上版本）

若内网环境无法使用SMTP，需通过控制台绕过邮箱验证：

# 进入GitLab控制台
sudo gitlab-rails console -e production
# 强制确认管理员账号（root）
admin = User.find_by_username("root")
admin.confirmed_at = Time.zone.now
admin.save!
# 强制确认所有未验证用户
User.where('LENGTH(confirmation_token) = 32').where(confirmed_at: nil).find_each { |u| u.confirmed_at = Time.now; u.save }
exit

六、注意事项

• 测试环境验证：生产环境升级前，务必在测试环境模拟整个流程，确保兼容性。
• 逐步升级：严格遵循官方升级路径，每次升级一个小版本，避免跨大版本直接升级。
• 监控服务状态：升级后持续监控GitLab服务（如gitlab-ctl status），及时处理异常。
• 备份保留：升级前后保留备份文件（至少7天），以便回滚。