从零到实战：企业级 GitLab 备份与迁移全流程指南

手动复制 GitLab 的数据目录听起来简单，但在实际操作中极易导致权限、数据库版本或数据不一致等问题，从而让整个系统崩溃。本指南将介绍 为什么要迁移、如何备份、如何恢复，并给出常见问题和自动化方案，确保你的数据万无一失。

一、为什么要迁移 GitLab？

迁移 GitLab 通常出于以下原因：

资源不足：随着仓库数量和数据量的增长，原有服务器磁盘或内存不足。
环境变更：从测试环境迁移到正式生产环境，以获得更高的稳定性和安全性。
架构优化：将 GitLab 部署方式从物理机迁移到 Docker 容器，或迁移到分布式架构。
灾难恢复：通过备份恢复 GitLab，避免因硬件故障、黑客攻击或误删导致的数据丢失。

二、在新服务器上搭建一个干净的 GitLab 环境

迁移数据前，你需要准备好一个 版本一致 的新 GitLab 环境。

使用 Docker Compose 快速搭建

创建并编辑 docker-compose.yml：

version: '3.6'
services:
  web:
    # 版本最好先固定，备份恢复会触发版本问题，需要保持一致
    image: gitlab/gitlab-ce:18.2.4-ce.0
    container_name: gitlab
    restart: always
    hostname: 172.19.23.27
    ports:
      - "8080:80"
      - "8443:443"
      - "2222:22"
    volumes:
      - ./config:/etc/gitlab
      - ./logs:/var/log/gitlab
      - ./data:/var/opt/gitlab

启动 GitLab：

docker-compose up -d

确保 GitLab 版本和旧环境一致，否则恢复可能失败。

三、GitLab 备份机制详解

GitLab 官方提供了内置的 gitlab-backup 工具，它可以完整打包 Git 仓库、数据库和上传文件。

1. 备份内容包含哪些？

仓库数据：代码、提交历史、Wiki
数据库：用户、权限、Issue、Merge Request
上传文件：头像、附件、CI/CD artifacts
配置文件：gitlab.rb 和 gitlab-secrets.json

以上都可以通过gitlab自带的备份完成，您无需担心文件从哪儿来

2. 创建备份

进入源服务器（待迁移服务） GitLab 容器，执行备份：

docker exec -it gitlab bash
gitlab-backup create

此命令会在 /var/opt/gitlab/backups/ 生成一个带时间戳的 .tar 文件，例如 1725860456_2025_09_09_gitlab_backup.tar。

gitlab-migrate-1

根据我们docker-compose的映射关系，此时的备份 /var/opt/gitlab/backups/ 实际上会对应到我们docker compose目录的data/backups，将里面的tar备份文件取出，放到新服务器的data上。

四、将备份文件迁移到新服务器

这里不再赘述传输过程，无论是ftp还是scp等操作均可，将其放置到含有docker的机器上保持与源主机一致的目录结构。

五、在新服务器上恢复备份

进入新 GitLab 容器：

docker exec -it gitlab bash

恢复备份：

gitlab-backup restore BACKUP=1725860456

数为备份文件的时间戳前缀，例如 1725860456。新版本的gitlab基本会带上时间戳_年月日_版本号，所以这里最好输入完整，并且不需要带入tar等后缀，gitlab的backup会自动查询并完成备份的恢复

六、在新服务器设置定时备份

设置定时任务：进入定时任务面板并添加定时任务：

crontab -e
0 2 * * * docker exec -t gitlab gitlab-backup create

此时将会在每天的2点设置备份

设置保存天数

version: '3.6'
services:
  web:
    # 版本最好先固定，备份恢复会触发版本问题，需要保持一致
    image: gitlab/gitlab-ce:18.2.4-ce.0
    container_name: gitlab
    restart: always
    environment:
      # 保留最近 7 天的备份文件
      - BACKUP_KEEP_TIME=604800 
    hostname: 172.19.23.27
    ports:
      - "8080:80"
      - "8443:443"
      - "2222:22"
    volumes:
      - ./config:/etc/gitlab
      - ./logs:/var/log/gitlab
      - ./data:/var/opt/gitlab

设置environment变量，告诉gitlab日志只保留7天，可以显著的避免备份过多过大的问题占用磁盘空间。

七、git设置新的地址

因为是完整备份，所有的ssh密钥等都是可以用的，此时要连接新的地址来推送代码

git remote set-url origin ssh://git@127.0.0.1:2222/liujie/pig-ui.git

这里切换为你的地址即可，再发送测试出现如下即可完成沟通并推送：

ssh -T git@127.0.0.1 -p 2222
Welcome to GitLab, @LayFz!

八、常见问题与避坑指南

版本不一致：备份只能恢复到同版本 GitLab，升级需先恢复，再逐步升级。
磁盘不足：备份和恢复时都需要足够的磁盘空间。
权限错误：确保 /var/opt/gitlab/backups 目录属主为 git:git。

九、总结

GitLab 的 gitlab-backup 工具是官方推荐的迁移方式，安全可靠。
迁移分三步：在旧服务器备份 → 传输备份文件 → 在新服务器恢复。
自动化备份和异地存储是企业级最佳实践。
定期验证备份可恢复性，才能真正做到高可用和灾难恢复。