Debian上GitLab的迁移策略

Debian 上 GitLab 迁移策略

一、策略总览与前置准备

• 迁移方式选型
  • 整体迁移（推荐）：使用官方备份工具打包数据库、仓库、上传等数据，在新服务器恢复，适合一次性完整切换，停机时间可控。备份默认路径为 /var/opt/gitlab/backups，备份命令为 gitlab-rake gitlab:backup:create。
  • 渐进式迁移：逐项目用 git push --mirror 到新实例，适合对停机敏感、分批切换的场景，但需自行处理用户、权限、Runner、Webhooks 等差异。
• 版本与一致性
  • 新旧实例的 GitLab 版本需保持一致（如 14.8.2、18.1.x），避免结构与加密字段不兼容导致恢复失败。
• 关键文件与目录
  • 备份包：默认 /var/opt/gitlab/backups/YYYY_MM_DD_HHMMSS_version_gitlab_backup.tar。
  • 机密与配置：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json（用于加密令牌、CI JWT 等，缺失会导致功能异常）。
• 资源与网络
  • 确保磁盘空间充足（备份包与解压后数据）、带宽与传输稳定性；迁移窗口内建议限制写入（只读或维护模式）。
• 回滚预案
  • 保留旧实例运行与备份；切换前记录 external_url、存储路径、SMTP、LDAP/SSO 等关键配置，便于快速回滚。

二、标准迁移流程（整体迁移）

1. 旧实例备份
   • 创建备份：执行 gitlab-rake gitlab:backup:create；备份文件位于 /var/opt/gitlab/backups/。
   • 单独备份机密与配置：复制 /etc/gitlab/gitlab.rb 与 /etc/gitlab/gitlab-secrets.json 到安全位置。
2. 新实例准备
   • 安装与旧实例同版本的 GitLab（CE/EE），可通过官方仓库或 .deb 包安装；首次配置执行 gitlab-ctl reconfigure。
   • 按需调整 /etc/gitlab/gitlab.rb（如 external_url、自定义数据目录等），再执行 gitlab-ctl reconfigure 使配置生效。
3. 传输备份与配置
   • 将备份 .tar 文件复制到新实例 /var/opt/gitlab/backups/；将 gitlab.rb 与 gitlab-secrets.json 复制到 /etc/gitlab/（覆盖前先备份新实例默认配置）。
4. 停止写入并恢复
   • 为减少一致性风险，建议停止相关服务：gitlab-ctl stop unicorn、gitlab-ctl stop sidekiq（必要时停 nginx）。
   • 执行恢复：BACKUP 参数填写备份文件名的时间戳前缀，例如 gitlab-rake gitlab:backup:restore BACKUP=1695041661_2023_09_18_15.1.3（不要包含 “_gitlab_backup.tar” 后缀）。
5. 启动与验证
   • 启动服务：gitlab-ctl start；访问 external_url 校验项目、用户、权限、CI/CD、Runner 注册等是否正常。

三、常见场景与差异处理

• 自定义数据目录或 Gitaly 存储路径
  • 若旧实例使用非默认路径（如 /var/gitlab），需在新实例 gitlab.rb 中以相同方式配置（例如设置 gitaly[‘configuration’][‘storage’][0][‘path’]），并确保目录权限与所有权一致，再执行 gitlab-ctl reconfigure 后恢复。
• 版本不一致或跨小版本
  • 恢复前务必将新实例升级/降级至与旧实例完全一致的版本；跨版本恢复易因结构或加密字段变化失败。
• 迁移后 Runner、Webhooks、第三方集成
  • Runner 需在新实例重新注册（旧 registration_token 不会跨实例复用）；检查 Webhooks、外部 CI、对象存储、LDAP/SSO、SMTP 等配置是否在新实例生效。
• 大对象与附件（LFS、上传）
  • 若使用对象存储（如 S3），确保新实例的 object_store 配置一致；若使用本地存储，需同步 /var/opt/gitlab/gitlab-rails/uploads 等目录（该目录默认不在备份包中，需单独迁移）。

四、验证与回滚

• 验证清单
  • 登录与权限：管理员与若干用户登录，校验项目可见性、成员与权限、SSH/HTTP 拉取推送。
  • 代码与 CI：克隆、提交、推送、创建 Merge Request、运行 Pipeline，检查 Artifacts/Runner 是否正常。
  • 安全与合规：检查 2FA、SSH 密钥、Deploy Keys、Protected Branches、审计日志。
  • 通知与集成：Webhooks、邮件通知、外部工单/仓库镜像。
• 回滚步骤
  • 若出现异常，切换 DNS/CNAME 或负载均衡回旧实例；必要时在新实例停止服务、恢复旧配置与数据库，确保业务连续性。

五、排错要点

• 恢复时报错或页面 500
  • 常见为加密令牌不一致或残留数据导致。可在 gitlab-rails console 清理相关 token（示例：将 projects.runners_token、namespaces.runners_token、application_settings.runners_registration_token_encrypted、application_settings.encrypted_ci_jwt_signing_key、ci_runners.token 置空），再重启服务重试。
• 备份包权限或所有权问题
  • 确保备份文件属主为 git:git，目录 /var/opt/gitlab/backups 权限正确，避免因权限导致恢复失败。
• 服务未完全停止导致恢复失败
  • 恢复前确认已停止 unicorn、sidekiq（必要时停 nginx），避免写入冲突。
• 版本不匹配
  • 恢复前核对 /opt/gitlab/embedded/service/gitlab-rails/VERSION，确保两端版本一致。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！