Debian环境下迁移GitLab的可选方案与选择建议
- 整实例备份与恢复：使用 Omnibus 包提供的备份工具（如 gitlab-backup create 或 gitlab-rake gitlab:backup:create）打包数据库、仓库、附件、CI/CD 产物等，在新实例上恢复。适合一次性整机迁移，要求GitLab 版本与类型（CE/EE）完全一致。支持从 v14.9 起的增量仓库备份。备份默认不含配置文件与密钥，需单独迁移。适合生产环境的标准做法。
- 项目级导出/导入：在源项目“Settings → Advanced → Export project”导出 .tar.gz，在目标实例“New project → Import project → GitLab export”导入。适合少量项目或跨实例选择性迁移；版本需兼容（一般仅支持相邻小版本），且不会导出诸如Webhooks、CI/CD 变量、Runner 注册信息、容器镜像等内容。
- rsync 直拷仓库数据：停机后用 rsync 同步 /var/opt/gitlab/git-data/repositories 等目录至新服务器，再在新实例恢复/重建元数据。适合仅代码与仓库的快速迁移或作为整实例迁移的补充。
- 导入裸仓库 rake 任务：使用 gitlab-rake gitlab:import:repo_by_url 等将裸仓库导入到指定命名空间。适合从非 GitLab 源或手工维护的仓库批量导入；注意所有权与命名空间映射及 hashed storage 的兼容性。
- 第三方迁移工具 Congregate：GitLab 官方专业服务工具，支持从多源 SCM/CI 系统迁移到 GitLab（自托管或 GitLab.com），适合大规模、多项目、跨平台迁移与自动化编排。
整实例备份与恢复步骤（Debian Omnibus 推荐）
- 版本与兼容性
- 确保新旧实例的 GitLab 版本与类型（CE/EE）一致；备份恢复不支持跨版本或跨类型。
- 旧实例备份
- 创建备份：sudo gitlab-backup create（或 sudo gitlab-rake gitlab:backup:create）。备份默认位于 /var/opt/gitlab/backups，文件名含时间戳_版本号。
- 单独备份配置与密钥：sudo cp /etc/gitlab/gitlab.rb /your/backup/path/；sudo cp /etc/gitlab/gitlab-secrets.json /your/backup/path/；如有 HTTPS，同步证书目录。
- 新实例准备
- 在 Debian 上添加 GitLab APT 源并安装相同版本：curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash；sudo EXTERNAL_URL=“https://your-domain” apt-get install gitlab-ce；sudo gitlab-ctl reconfigure。
- 传输备份与配置
- scp 备份包至新实例：/var/opt/gitlab/backups/；同步 gitlab.rb 与 gitlab-secrets.json 至 /etc/gitlab/。
- 恢复
- 为一致性，先停止应用与任务：sudo gitlab-ctl stop unicorn；sudo gitlab-ctl stop sidekiq。
- 执行恢复（BACKUP= 为文件名前缀时间戳）：sudo gitlab-rake gitlab:backup:restore BACKUP=1717411200。
- 恢复后执行：sudo gitlab-ctl reconfigure；sudo gitlab-ctl start。
- 验证
- 登录 Web，检查用户、项目、权限、CI/CD、LFS、Pages、Packages等是否正常；克隆测试仓库验证读写。
项目级导出与导入步骤（选择性迁移）
- 源实例导出
- 进入项目 → Settings → Advanced → Export project，等待生成并下载 .tar.gz 包。
- 目标实例导入
- New project → Import project → GitLab export，上传归档并设置项目名称与命名空间。
- 重要限制
- 版本兼容：通常仅支持相邻小版本导入；跨大版本可能失败。
- 不包含：Webhooks、CI/CD 变量与触发器、Runner 信息、容器/包镜像、构建产物与追踪等。
- 安全：导出包含敏感信息，传输与存储需加密与最小权限。
其他方法与场景化建议
- rsync 直拷仓库数据
- 适用：仅需迁移代码仓库或作为整实例迁移的补充；对对象存储场景需额外处理。
- 要点：停机后执行 rsync 同步仓库数据目录至新实例相同路径；在新实例完成恢复/重建元数据与权限。
- 导入裸仓库 rake 任务
- 适用：从非 GitLab 源或已有裸仓库批量导入；注意项目所有者与命名空间的映射。
- 限制：导入后所有者可能变为首个管理员；hashed storage 环境下部分仓库可能被跳过，需提前评估。
- 第三方工具 Congregate
- 适用：大规模、多项目、跨平台迁移（如 GitHub/GitLab.com/其他 SCM 到 GitLab 自托管或 GitLab.com）。
- 特性：支持用户/组/项目、权限、CI、议题/合并请求等迁移的自动化编排与回滚；建议先在测试环境验证迁移清单与映射策略。
关键注意事项与最佳实践
- 版本与类型一致性
- 整实例备份恢复要求完全相同的 GitLab 版本与 CE/EE 类型；项目导出/导入需满足相邻小版本兼容。
- 密钥与配置
- 必须迁移 /etc/gitlab/gitlab-secrets.json（含 2FA、CI/CD 变量加密密钥等）；建议同步 gitlab.rb 与证书，避免恢复后认证/集成异常。
- 对象存储与增量
- 备份工具默认面向本地存储；使用对象存储时需按官方指引处理或转换为文件存储再备份。
- 自 v14.9 起支持增量仓库备份（INCREMENTAL=yes），适合频繁备份与迁移窗口较短的场景。
- 权限与所有权
- 确保备份与数据目录属主为 git:git；导入裸仓库时注意命名空间与所有者映射策略。
- 验证与回滚
- 迁移后在测试环境验证推送/拉取、MR、流水线、LFS/Packages/Pages等关键功能；保留旧实例只读或快照一段时间，确认无误再切换与清理。