如何迁移Debian GitLab

迁移 Debian 上的 GitLab 通常有两种常见场景：
1️⃣ 同机或跨机迁移（保留数据）
2️⃣ 升级迁移（Debian / GitLab 版本变化）

下面以 官方 Omnibus GitLab 为例，给你一套最稳妥、生产可用的迁移方案。

一、迁移前准备

1. 确认 GitLab 安装方式

dpkg -l | grep gitlab

✅ gitlab-ee 或 gitlab-ce → Omnibus 安装（推荐）
❌ 源码安装 → 迁移方式不同（不建议）

2. 查看版本（非常重要）

gitlab-rake gitlab:env:info

或

cat /opt/gitlab/version-manifest.txt

✅ 强烈建议：目标服务器 GitLab 版本 ≥ 源服务器

二、完整迁移流程（推荐 ✅）

✅ 方案：备份 + 恢复（官方推荐）

三、在源服务器（旧 Debian）操作

1. 创建完整备份

gitlab-rake gitlab:backup:create

备份文件位置：

/var/opt/gitlab/backups/

文件名类似：

1234567890_2026_01_21_gitlab_backup.tar

2. 记录关键配置

/etc/gitlab/gitlab.rb
/etc/gitlab/gitlab-secrets.json

⚠️ 必须一起迁移，否则：

CI/CD 变量失效
Runner 无法注册
2FA / OAuth 失效

3. 拷贝文件到新服务器

scp /var/opt/gitlab/backups/*.tar root@new-server:/var/opt/gitlab/backups/
scp /etc/gitlab/gitlab.rb root@new-server:/etc/gitlab/
scp /etc/gitlab/gitlab-secrets.json root@new-server:/etc/gitlab/

四、在新 Debian 服务器操作

1. 安装相同版本 GitLab（关键）

添加官方源

curl -fsSL https://packages.gitlab.com/gpg.key | gpg --dearmor > /usr/share/keyrings/gitlab.gpg

echo "deb [signed-by=/usr/share/keyrings/gitlab.gpg] https://packages.gitlab.com/gitlab/gitlab-ce/debian $(lsb_release -cs) main" \
> /etc/apt/sources.list.d/gitlab.list

安装指定版本（示例）

apt update
apt install gitlab-ce=16.7.2-ce.0

版本号必须和旧服务器一致（或更高但兼容）

2. 恢复配置文件

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

gitlab-ctl reconfigure

3. 恢复备份

gitlab-ctl stop puma
gitlab-ctl stop sidekiq

gitlab-rake gitlab:backup:restore BACKUP=1234567890

只写时间戳，不要 .tar

恢复完成后：

gitlab-ctl restart

五、验证迁移是否成功

gitlab-rake gitlab:check SANITIZE=true

浏览器访问：

http://新服务器IP

✅ 仓库
✅ 用户
✅ CI/CD
✅ Runner

六、Runner 迁移（如有）

方式 1：重新注册（推荐）

gitlab-runner register

方式 2：拷贝 Runner 配置

/etc/gitlab-runner/config.toml

七、常见问题

❌ 版本不一致

必须先升级旧 GitLab，再迁移

❌ 502 错误

gitlab-ctl status
gitlab-ctl restart

检查端口冲突（80 / 443 / 22）

❌ 数据库版本不匹配

gitlab-rake db:migrate

八、最小停机迁移方案（高级）

使用 GitLab 主从（Geo）
或 rsync + 短时间停服务

九、总结（推荐顺序）

✅ 备份 → 同版本安装 → 恢复 → 验证

如果你愿意，可以告诉我：

Debian 版本（10 / 11 / 12）
GitLab 版本
是否跨云 / 跨机房
是否包含大量 CI/CD 数据

我可以给你 定制迁移方案 + 命令清单 ✅