centos gitlab项目迁移技巧

CentOS 上 GitLab 项目迁移实用技巧

一 迁移方式速览与选择

• 全量迁移（推荐）：使用官方备份工具打包仓库、数据库与上传文件，在新实例同版本恢复，迁移前后一致性最好，适合整机或实例级切换。备份命令为：gitlab-rake gitlab:backup:create，恢复命令为：gitlab-rake gitlab:backup:restore BACKUP=时间戳。适合大多数场景。
• 仅项目迁移（选择性）：通过导出/导入项目（如导出为 .tar.gz 再导入）或使用 API/脚本批量迁移，适合只搬迁部分项目、跨实例合并或精简迁移。注意需单独处理附件、CI 变量、Runner 等。

二 全量迁移步骤（同版本，最稳）

• 版本与环境
  • 保持源与目标 GitLab 版本一致（如均为 15.0.0），避免跨版本恢复带来的不兼容。
  • 在新服务器安装对应 el7/el8 的安装包（CentOS 7 用 el7，Alibaba Cloud Linux 3 用 el8），安装依赖：yum install policycoreutils openssh-server postfix*，完成后执行 gitlab-ctl reconfigure。
• 备份关键文件与数据
  • 备份配置文件：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json（后者包含 DB 加密密钥，务必迁移）。
  • 备份数据：在源服务器执行 gitlab-rake gitlab:backup:create，默认目录 /var/opt/gitlab/backups。若目录权限异常，修正为 git:git 并 755。
• 传输与恢复
  • 将备份 tar 包与配置文件传到目标服务器同路径（如 /var/opt/gitlab/backups）。
  • 目标服务器停止写入服务：gitlab-ctl stop sidekiq；如为 13 以前停止 unicorn，13 及以后停止 puma。
  • 恢复数据：进入备份目录执行 gitlab-rake gitlab:backup:restore BACKUP=时间戳（文件名去掉 .tar 后缀的时间戳部分）。
• 启动与验证
  • 启动服务：gitlab-ctl start；访问页面检查项目、用户、Runner、LFS/附件是否正常。

三 仅迁移部分项目或跨实例合并

• 使用项目导出/导入
  • 在源项目“设置-导出”导出 .tar.gz，在目标实例“新建项目-导入”上传并导入；适合少量项目、跨实例合并。
• 批量迁移思路
  • 结合 GitLab API 遍历项目列表，逐一调用导出/导入；注意处理私有令牌、组成员、保护分支、Webhooks、CI/CD 变量、Runner 注册等差异。
• 附件与 LFS
  • 若使用对象存储（如 S3/OSS），确保目标实例可访问同一存储或迁移对象；本地存储需同步 /var/opt/gitlab/gitlab-rails/uploads 与 /var/opt/gitlab/gitlab-rails/shared 下相关目录。
• Runner 与 CI
  • 在新实例重新注册 Runner，复制 config.toml（注意并发、标签、镜像缓存等）；检查 .gitlab-ci.yml 中的服务镜像与依赖可达性。

四 常见问题与排错要点

• 版本不一致
  • 备份恢复强烈建议同版本；跨版本恢复可能失败或导致数据不一致。
• 权限与路径
  • 备份目录与文件属主应为 git:git，权限 755；恢复时报 Permission denied 时优先检查属主与目录权限。
• 服务未停导致恢复失败
  • 恢复前务必停止 sidekiq 与 puma/unicorn，避免写入冲突。
• 502/页面异常
  • 检查 external_url、端口占用、Nginx/SELinux/防火墙；必要时 gitlab-ctl tail 查看日志定位。
• SSH 克隆失败
  • 确认 external_url 中的协议与端口、Nginx/防火墙放行、以及客户端 known_hosts 更新。

五 自动化与最小化停机实践

• 备份策略
  • 自定义备份目录：在 /etc/gitlab/gitlab.rb 设置 gitlab_rails[‘backup_path’] = “/data/git-backup”，执行 gitlab-ctl reconfigure 生效。
  • 保留策略：设置 gitlab_rails[‘backup_keep_time’] = 604800（保留 7 天）；配合 crontab 定时执行备份脚本，降低人为遗漏风险。
• 最小化停机
  • 在低峰期操作：先停写入（Sidekiq/Puma），备份与传输并行，恢复完成后立即启动；必要时短暂维护窗口通知用户。
• 传输与校验
  • 使用 scp/rsync 校验文件大小与 sha256sum；大包建议断点续传或内网直传，减少窗口时间。

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