GitLab在Debian上的数据迁移指南
小樊
42
2025-12-11 07:14:14
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
- 该方式不涉及数据库与配置迁移，适合选择性迁移或演练。
