GitLab 迁移

一、迁移前准备1.版本一致性要求关键⚠️新旧服务器 GitLab 版本必须完全一致包括小版本号否则备份无法恢复。bash# 查询当前 GitLab 版本 cat /opt/gitlab/embedded/service/gitlab-rails/VERSION # 或 gitlab-rake gitlab:env:info | grep GitLab information2.迁移方式选择方式适用场景优点缺点官方备份恢复推荐常规迁移简单、官方支持需版本一致rsync全量迁移升级同步迁移快速需停机Docker卷迁移Docker部署直接复制数据卷需停容器数据库仓库分离大型实例灵活操作复杂二、官方备份恢复方式推荐【旧服务器】第一步备份配置文件必做备份不含配置bash# 备份密钥文件secrets存储加密密钥 cp /etc/gitlab/gitlab-secrets.json /backup/gitlab-secrets.json # 备份主配置文件 cp /etc/gitlab/gitlab.rb /backup/gitlab.rb # 备份 SSL 证书如有 cp -r /etc/gitlab/ssl /backup/ssl # 打包整个 /etc/gitlab 目录最稳妥 tar -czvf /backup/gitlab-etc-$(date %F).tar.gz /etc/gitlab【旧服务器】第二步停止写入服务保证数据一致bash# 停止 Puma/Unicorn 和 Sidekiq其他服务保留备份需要 gitlab-ctl stop puma gitlab-ctl stop sidekiq # 确认状态 gitlab-ctl status【旧服务器】第三步执行备份bash# 执行备份命令较慢取决于仓库大小 gitlab-backup create # 老版本命令gitlab-rake gitlab:backup:create # 可选参数跳过部分内容减小备份体积 gitlab-backup create SKIPartifacts,uploads STRATEGYcopy # 备份默认存放位置 ls -lh /var/opt/gitlab/backups/ # 生成文件名示例1715592345_2026_05_13_16.11.5_gitlab_backup.tar【旧服务器】第四步传输到新服务器bash# 方式一scp scp /var/opt/gitlab/backups/1715592345_2026_05_13_16.11.5_gitlab_backup.tar \ rootnewserver:/var/opt/gitlab/backups/ # 方式二rsync推荐支持断点续传 rsync -avP --progress \ /var/opt/gitlab/backups/*.tar \ /backup/gitlab-etc-*.tar.gz \ /backup/gitlab-secrets.json \ rootnewserver:/tmp/gitlab-migrate/【新服务器】第五步安装相同版本的 GitLabbash# CentOS/RHEL —— 指定版本安装 yum install -y gitlab-ce-16.11.5-ce.0.el7 # Ubuntu/Debian —— 指定版本安装 apt-get install -y gitlab-ce16.11.5-ce.0 # Docker 方式 —— 指定镜像 tag docker pull gitlab/gitlab-ce:16.11.5-ce.0【新服务器】第六步恢复配置文件bash# 恢复 secrets 和 gitlab.rb务必在 reconfigure 前 cp /tmp/gitlab-migrate/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json cp /tmp/gitlab-migrate/gitlab.rb /etc/gitlab/gitlab.rb # 如需修改域名 IP vi /etc/gitlab/gitlab.rb # 修改external_url http://newserver.example.com # 应用配置 gitlab-ctl reconfigure gitlab-ctl restart【新服务器】第七步恢复数据bash# 放置备份文件到备份目录 mv /tmp/gitlab-migrate/*_gitlab_backup.tar /var/opt/gitlab/backups/ # 修改备份文件权限必须 git 用户可读写 chown git:git /var/opt/gitlab/backups/*_gitlab_backup.tar chmod 600 /var/opt/gitlab/backups/*_gitlab_backup.tar # 停止写入服务 gitlab-ctl stop puma gitlab-ctl stop sidekiq gitlab-ctl status # 执行恢复BACKUP 参数只传时间戳部分不含 _gitlab_backup.tar gitlab-backup restore BACKUP1715592345_2026_05_13_16.11.5 # 过程中会两次询问是否覆盖输入 yes 确认【新服务器】第八步重启并验证bash# 重新配置并启动 gitlab-ctl reconfigure gitlab-ctl restart # 健康检查 gitlab-rake gitlab:check SANITIZEtrue gitlab-rake gitlab:doctor:secrets # 查看服务状态 gitlab-ctl status三、Docker部署GitLab 迁移方式1. 旧容器数据导出bash# 查看当前容器挂载路径 docker inspect gitlab | grep -A 5 Mounts # 标准挂载目录官方镜像默认 # /etc/gitlab - 配置 # /var/log/gitlab - 日志 # /var/opt/gitlab - 数据 # 停容器避免数据写入 docker stop gitlab # 打包数据 tar -czvf /backup/gitlab-config.tar.gz /srv/gitlab/config tar -czvf /backup/gitlab-data.tar.gz /srv/gitlab/data tar -czvf /backup/gitlab-logs.tar.gz /srv/gitlab/logs2.传输到新服务器bashrsync -avP /backup/gitlab-*.tar.gz rootnewserver:/tmp/3.新服务器解压并启动bash# 解压 mkdir -p /srv/gitlab cd /srv/gitlab tar -xzvf /tmp/gitlab-config.tar.gz -C / tar -xzvf /tmp/gitlab-data.tar.gz -C / tar -xzvf /tmp/gitlab-logs.tar.gz -C / # docker-compose.yaml 示例 cat docker-compose.yaml EOF version: 3.8 services: gitlab: image: gitlab/gitlab-ce:16.11.5-ce.0 # 版本必须和旧环境一致 container_name: gitlab restart: always hostname: gitlab.example.com environment: GITLAB_OMNIBUS_CONFIG: | external_url http://gitlab.example.com gitlab_rails[time_zone] Asia/Shanghai ports: - 80:80 - 443:443 - 22:22 volumes: - /srv/gitlab/config:/etc/gitlab - /srv/gitlab/logs:/var/log/gitlab - /srv/gitlab/data:/var/opt/gitlab shm_size: 256m EOF docker-compose up -d # 观察启动日志 docker logs -f gitlab四、rsync 全量迁移方式同版本快速迁移bash# 【旧服务器】停止 GitLab gitlab-ctl stop # 【新服务器】安装相同版本 GitLab 但不启动 yum install -y gitlab-ce-16.11.5-ce.0.el7 # 初次配置完成后立即停止 gitlab-ctl stop # 【旧服务器】全量同步数据 rsync -avP --delete /etc/gitlab/ rootnewserver:/etc/gitlab/ rsync -avP --delete /var/opt/gitlab/ rootnewserver:/var/opt/gitlab/ rsync -avP --delete /var/log/gitlab/ rootnewserver:/var/log/gitlab/ # 【新服务器】重新配置并启动 gitlab-ctl reconfigure gitlab-ctl start gitlab-ctl status五、迁移后必做校验项bash# 1. 健康检查 gitlab-rake gitlab:check SANITIZEtrue # 2. 密钥完整性最重要 gitlab-rake gitlab:doctor:secrets # 若报错 Failed to decrypt说明 gitlab-secrets.json 未正确迁移 # 3. 仓库完整性检查 gitlab-rake gitlab:git:fsck # 4. 后台任务状态 gitlab-rake gitlab:sidekiq:check # 5. 检查 Git LFS、CI Runner 可用性 gitlab-rake gitlab:lfs:checkWeb层面验证清单管理员能正常登录/admin项目列表、仓库代码可访问Issues、MR、Wiki 正常CI/CD Pipeline 历史正常Runner 重新注册或修改地址Webhook 目标地址是否需更新SSH Keygit clone gitnewserver:xx/xx.git能拉取代码邮件 SMTP 通知能送达六、客户端切换与收尾1.修改客户端 Git仓库远程地址bash# 方式一修改 remote url git remote set-url origin gitnewserver:group/project.git # 方式二DNS 平滑切换推荐 # 保持域名不变仅修改 DNS 解析到新服务器 IP客户端无感知2.SSH known_hosts 清理bash# 客户端删除旧 HostKey 避免告警 ssh-keygen -R oldserver ssh-keygen -R newserver # 强制重新信任3.旧服务器处理bash# 观察 1-2 周无异常后保留最后一次备份再下线 gitlab-ctl stop # 最后一份冷备份 tar -czvf /backup/gitlab-final-$(date %F).tar.gz /etc/gitlab /var/opt/gitlab七、迁移流程图graph TD A[开始迁移] -- B[确认新旧版本一致] B -- C[旧服务器停止 pumasidekiq] C -- D[旧服务器gitlab-backup create] D -- E[旧服务器备份 /etc/gitlab 和 gitlab-secrets.json] E -- F[传输备份文件到新服务器 (rsync/scp)] F -- G[新服务器安装相同版本 GitLab] G -- H[新服务器恢复 gitlab.rb 和 secrets.json] H -- I[新服务器gitlab-ctl reconfigure] I -- J[新服务器gitlab-backup restore] J -- K[新服务器reconfigure restart] K -- L[执行 gitlab-rake check 检查] L -- M{校验通过?} M --|否| N[排查 secrets / 权限 / 版本] N -- J M --|是| O[DNS/客户端切换] O -- P[观察1-2周] P -- Q[旧服务器冷备份后下线]八、常见坑与解决方案问题原因解决方案Failed to decryptgitlab-secrets.json未迁移从旧机复制该文件后reconfigurebackup restore报版本不匹配GitLab 版本不一致新机安装完全相同版本恢复后CI Runner离线Runner Token加密失效Admin→Runners 重新注册仓库 500 错误文件权限 git:git丢失chown -R git:git /var/opt/gitlab/git-data2FA全部失效secrets 未迁移同上必须迁移 secrets.json备份文件过大artifacts/uploads体积大备份时SKIPartifacts单独rsync邮件无法发送SMTP 地址/网络变化修改gitlab.rb中smtp 配置Docker 容器启不来shm_size不足增加shm_size: 256m九、最佳实践建议先做演练在测试环境完整走一遍流程估算停机时间。最小停机窗口选择业务低峰期凌晨停机一般 1–4 小时。双跑过渡旧服务器保留只读访问 1 周新服务器提供写入。备份 3-2-1 原则3 份副本、2 种介质、1 份异地。版本升级单独做迁移 升级分两步先迁移同版本再按官方路径升级。GitLab 升级路径跨大版本必须遵循官方升级路径。自动化脚本将 backup → rsync → restore 写成脚本可复用。