GitLab在Debian上的数据迁移指南

GitLab在Debian上的数据迁移指南

一 迁移准备

• 核对版本一致性：在两台服务器上查看 GitLab 版本，确保迁移前后版本一致或兼容。命令：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION。若不一致，建议先在旧实例升级到目标版本再迁移。
• 规划停机窗口：为避免写入导致不一致，迁移时建议短暂停写（仅停止应用写入进程，必要时再停 Nginx）。
• 备份策略确认：默认备份不含仓库文件（对象存储）与容器镜像仓库（Registry），如使用对象存储或自建 Registry，需单独迁移并校验。
• 网络与权限：确保新服务器可访问旧服务器备份目录，备份文件属主为 git:git，目录权限为 0700。
• 配置梳理：记录旧实例的 external_url、HTTPS/证书、SMTP、LDAP/SSO、对象存储与 Registry 等关键配置，便于新实例还原。

二 备份旧实例

• 建议停写后备份：sudo gitlab-ctl stop unicorn & & sudo gitlab-ctl stop sidekiq（如需彻底一致，可再停 nginx：sudo gitlab-ctl stop nginx）。
• 创建备份：sudo gitlab-rake gitlab:backup:create。备份默认生成于 /var/opt/gitlab/backups，文件名形如 YYYY-MM-DD-HH-MM-SS_gitlab_backup.tar。
• 保留策略与路径：在 /etc/gitlab/gitlab.rb 中可配置备份保留时间与路径，例如：gitlab_rails[‘backup_path’] = ‘/var/opt/gitlab/backups’；gitlab_rails[‘backup_keep_time’] = 604800（7 天）。修改后执行 sudo gitlab-ctl reconfigure。
• 复制备份：将备份文件安全复制到新服务器同目录（/var/opt/gitlab/backups），并确保属主为 git:git。

三 在新服务器恢复

• 安装同版本 GitLab：在 Debian 上添加官方仓库并安装与旧实例一致的 GitLab 版本（CE/EE 保持一致）。示例：curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash，然后 sudo EXTERNAL_URL=“http://< 新地址或域名> ” apt-get install gitlab-ce。
• 还原配置：将旧实例的 /etc/gitlab/gitlab.rb 关键配置（external_url、HTTPS、SMTP、LDAP/SSO、对象存储、Registry 等）合并到新实例对应文件，注意仅迁移必要项，避免覆盖新环境差异。
• 执行恢复：建议停写后恢复。命令：sudo gitlab-ctl stop unicorn & & sudo gitlab-ctl stop sidekiq；然后 sudo gitlab-rake gitlab:backup:restore BACKUP=YYYY-MM-DD-HH-MM-SS（仅填时间戳部分，不含 _gitlab_backup.tar 后缀）。恢复过程中如有覆盖提示，输入 yes 确认。
• 启动与重载：sudo gitlab-ctl reconfigure & & sudo gitlab-ctl start。
• 版本不一致处理：若必须跨小版本迁移，优先在旧实例升级到目标版本后再备份与恢复。

四 迁移后验证与常见问题

• 功能与数据校验：登录 Web 检查项目、用户、权限、议题、合并请求、CI/CD 流水线、Runner是否正常；在本地执行 git clone/push 测试读写；抽样比对关键仓库对象数量与大小。
• 外部集成：验证 HTTPS/证书、SMTP 邮件、LDAP/SSO、对象存储（如 S3/MinIO）与 Registry 是否可用。
• 常见报错与修复：
  • 页面 500 且日志含 aes256_gcm_decrypt 解密失败：在 Rails 控制台清理相关加密 token 后重试。示例：
    • gitlab-rails console
    • UPDATE projects SET runners_token = null, runners_token_encrypted = null;
    • UPDATE namespaces SET runners_token = null, runners_token_encrypted = null;
    • UPDATE application_settings SET runners_registration_token_encrypted = null;
    • UPDATE application_settings SET encrypted_ci_jwt_signing_key = null;
    • UPDATE ci_runners SET token = null, token_encrypted = null;
      注：清理 runner 注册令牌后需在新实例重新注册 Runner。
  • 权限/属主问题：确保 /var/opt/gitlab/backups 及备份文件属主为 git:git，目录权限 0700。
  • 配置未生效：修改 gitlab.rb 后执行 sudo gitlab-ctl reconfigure。

五 只迁移部分项目的替代方案

• 若仅需迁移少量项目，可在新实例为每个项目新建空仓库，然后在本地使用镜像推送：
  • git clone --mirror < 旧仓库URL>
  • cd < 仓库目录>
  • git remote set-url origin < 新仓库URL>
  • git push --mirror
• 该方式不涉及数据库与配置迁移，适合选择性迁移或演练。

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