Debian 上 GitLab 的迁移与升级策略
一、策略总览与版本路径
- 采用“先备份 → 再迁移/升级 → 验证”的闭环流程，优先使用 Omnibus 包与 APT 管理，避免跨大版本跳跃升级。
- 迁移优先选择“同版本全量备份恢复”，跨版本迁移需按官方升级路径逐步升级后再迁移，降低风险。
- 单节点升级期间会出现短暂不可用（浏览器显示 Deploy in progress 或出现 502），需安排维护窗口。
二、迁移策略与步骤
- 同版本迁移（推荐）
- 在旧实例创建备份：sudo gitlab-backup create（旧版可用 sudo gitlab-rake gitlab:backup:create），备份默认位于 /var/opt/gitlab/backups。
- 在新服务器安装与旧实例相同版本的 GitLab（添加官方仓库后执行 sudo apt-get install gitlab-ce）。
- 将备份文件复制到新服务器同目录（/var/opt/gitlab/backups）。
- 在新实例恢复：sudo gitlab-rake gitlab:backup:restore BACKUP=YYYY-MM-DD-HH-MM-SS。
- 对比并同步 /etc/gitlab/gitlab.rb（如 external_url、SSL、邮件、LDAP 等），执行 sudo gitlab-ctl reconfigure 与 sudo gitlab-ctl restart。
- 登录验证项目、用户、权限、Runner、Webhooks、CI 等是否正常。
- 跨版本迁移
- 先在旧实例按官方升级路径逐步升级到目标版本，再执行“同版本迁移”；或在新实例安装目标版本后恢复备份，再按需升级。
- 仅迁移部分项目（替代方案）
- 在新实例为每个项目新建空项目，使用 git clone --mirror 与 git push --mirror 逐仓库迁移（适合小规模或选择性迁移）。
三、就地升级步骤（Debian 11/12，Omnibus 包）
- 准备与检查
- 备份：sudo gitlab-backup create；确认版本：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION；查看升级路径工具并规划版本阶梯。
- 如为 Gitaly 集群，先升级 Gitaly 节点，避免 gRPC 不兼容。
- 执行升级
- 更新系统：sudo apt update && sudo apt upgrade；确保已添加 GitLab 官方仓库。
- 升级软件包：sudo apt-get install gitlab-ce（或指定版本：sudo apt install gitlab-ce=15.11.0-ce.0）。
- 重新配置与重启：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。
- 升级后验证
- 访问页面与后台检查版本与健康状态；必要时运行 sudo gitlab-rake gitlab:check SANITIZE=true。
- 如从旧版启用哈希存储，按需执行迁移：gitlab-rake gitlab:storage:migrate_to_hashed。
四、回滚与风险控制
- 回滚预案
- 保留旧实例与备份文件；若升级失败，使用备份在新实例或回滚到旧实例恢复。
- 升级前记录当前版本与配置基线（gitlab.rb、gitlab-secrets.json、/var/opt/gitlab 关键子目录清单）。
- 关键注意事项
- 单节点升级存在停机时间，请提前公告维护窗口。
- 大版本升级前确保后台迁移任务完成，避免数据损坏。
- 升级后检查 external_url、SSL/TLS、防火墙（80/443/22）、邮件与 Runner 注册是否受影响。
- 如从旧版迁移到启用哈希存储的版本，执行存储迁移任务以完成对象路径转换。
五、Docker 部署的迁移与升级要点
- 备份：docker exec -t gitlab-backup create；数据目录通常为 /srv/gitlab/data/backups。
- 升级：docker pull gitlab/gitlab-ce:latest，停止旧容器后使用相同卷与端口启动新容器（注意挂载 /etc/gitlab、/var/opt/gitlab、/var/log/gitlab）。
- 迁移：将备份文件放入数据卷的 backups 目录后，在容器内执行恢复命令；恢复后执行 reconfigure 并验证。