GitLab迁移完整版：CentOS原生→Ubuntu Docker Compose（数据零丢失，附故障排查）


本文详细讲解如何将CentOS服务器上的原生GitLab-ce，完整迁移到Ubuntu服务器的Docker Compose部署版本，核心保障数据零丢失，步骤清晰可直接复刻，适合运维工程师、服务器管理员实操参考。

一、整体迁移思路

核心原则：先完整备份CentOS上的GitLab数据/配置 → 迁移到Ubuntu服务器 → 基于Docker Compose部署GitLab → 恢复备份验证数据

关键注意点：GitLab版本尽量一致（避免跨大版本恢复兼容问题）、核心配置文件（gitlab-secrets.json）必须备份、权限与目录挂载正确。

二、步骤1：CentOS服务器 - 完整备份GitLab数据与配置

2.1 停止GitLab服务（避免备份时数据写入）


# 停止所有GitLab服务
gitlab-ctl stop
# 验证服务状态（确保全部停止，输出均为down状态）
gitlab-ctl status

2.2 执行GitLab数据备份

GitLab原生备份命令会打包所有仓库、数据库、用户、CI配置等，备份文件默认存放在/var/opt/gitlab/backups/。


# 执行备份（生成的文件格式：[时间戳]_gitlab_backup.tar）
gitlab-backup create
# 示例输出：Backup created in /var/opt/gitlab/backups/1704421234_2026_01_05_16.8.1_gitlab_backup.tar
# 记住这个时间戳，后续恢复需要用到

2.3 备份核心配置文件（至关重要）

gitlab.rb 是GitLab主配置文件，gitlab-secrets.json 包含加密密钥（丢失则无法恢复密码/CI变量等加密数据）：


# 创建临时备份目录，统一存放迁移文件
mkdir -p /tmp/gitlab_migrate
# 复制核心配置文件
cp /etc/gitlab/gitlab.rb /tmp/gitlab_migrate/
cp /etc/gitlab/gitlab-secrets.json /tmp/gitlab_migrate/
# 可选：如果自定义过GitLab的SSH密钥，一并备份
cp -r /var/opt/gitlab/.ssh /tmp/gitlab_migrate/

2.4 验证备份完整性


# 检查备份数据文件（确保tar文件存在且大小合理，避免空备份）
ls -lh /var/opt/gitlab/backups/
# 检查配置文件（确保3个文件/目录存在）
ls -lh /tmp/gitlab_migrate/

2.5 （可选）临时启动GitLab（如需继续使用）


gitlab-ctl start

三、步骤2：迁移备份文件到Ubuntu服务器

使用 scp 命令直接复制CentOS的备份文件到Ubuntu（简单直接，无需额外安装工具）。

2.1 在CentOS执行迁移命令（替换参数）


# 替换说明：
# [timestamp] → 备份文件的时间戳（如1704421234_2026_01_05_16.8.1）
# ubuntu_ip → Ubuntu服务器的IP/域名（如192.168.1.100）
# ubuntu_user → Ubuntu的登录用户（如root）
# 1. 迁移备份数据文件
scp /var/opt/gitlab/backups/[timestamp]_gitlab_backup.tar ubuntu_user@ubuntu_ip:/tmp/gitlab_migrate/
# 2. 迁移配置文件
scp /tmp/gitlab_migrate/gitlab.rb ubuntu_user@ubuntu_ip:/tmp/gitlab_migrate/
scp /tmp/gitlab_migrate/gitlab-secrets.json ubuntu_user@ubuntu_ip:/tmp/gitlab_migrate/
scp -r /tmp/gitlab_migrate/.ssh ubuntu_user@ubuntu_ip:/tmp/gitlab_migrate/  # 可选（自定义SSH密钥）

scp -r /tmp/gitlab_migrate/.ssh ubuntu_user@ubuntu_ip:/tmp/gitlab_migrate/  # 可选（自定义SSH密钥）

2.2 在Ubuntu验证迁移文件

登录Ubuntu服务器后，检查文件是否迁移成功：


ls -lh /tmp/gitlab_migrate/
# 正常输出应包含：[timestamp]_gitlab_backup.tar、gitlab.rb、gitlab-secrets.json

四、步骤3：Ubuntu服务器 - 系统初始化与依赖安装

3.1 更新系统并安装基础依赖


# 更新Ubuntu包索引
apt update && apt upgrade -y
# 安装Docker所需基础依赖
apt install -y ca-certificates curl gnupg lsb-release wget

3.2 关闭/禁用防火墙（可选，或按需开放端口）

迁移过程中临时关闭防火墙，避免端口拦截；后续可按需开放指定端口：


# 临时关闭ufw防火墙
ufw disable
# 关闭SELinux（Ubuntu默认无，如有则执行）
setenforce 0 && sed -i 's/^SELINUX=.*/SELINUX=disabled/' /etc/selinux/config

五、步骤4：Ubuntu安装Docker & Docker Compose

4.1 安装Docker Engine


# 1. 添加Docker官方GPG密钥
mkdir -p /etc/apt/trusted.gpg.d
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg
# 2. 添加Docker软件源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/trusted.gpg.d/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
# 3. 安装Docker
apt update && apt install -y docker-ce docker-ce-cli containerd.io
# 4. 启动Docker并设置开机自启
systemctl start docker
systemctl enable docker
# 5. 验证Docker安装（输出版本即成功）
docker --version

docker --version

4.2 安装Docker Compose（v2推荐）


# 1. 下载Docker Compose二进制文件（版本可替换为最新，查看地址：https://github.com/docker/compose/releases）
curl -SL https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
# 2. 添加执行权限
chmod +x /usr/local/bin/docker-compose
# 3. 建立软链接（让系统全局识别docker-compose命令）
ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
# 4. 验证安装（输出版本即成功）
docker-compose --version

六、步骤5：Ubuntu配置Docker Compose部署GitLab

5.1 创建GitLab持久化目录（核心）

Docker版GitLab需要挂载宿主机目录来持久化数据，目录权限需匹配容器内git用户（UID=998），否则容器无法读写数据：


# 创建目录结构（config：配置文件，data：核心数据，logs：日志，backups：备份文件）
mkdir -p /opt/gitlab/{config,data,logs,backups}
# 修改权限（关键！必须执行，否则容器启动失败）
chown -R 998:998 /opt/gitlab/
chmod -R 755 /opt/gitlab/

chmod -R 755 /opt/gitlab/

5.2 迁移配置文件到持久化目录


# 复制备份的配置文件到GitLab的config目录
cp /tmp/gitlab_migrate/gitlab.rb /opt/gitlab/config/
cp /tmp/gitlab_migrate/gitlab-secrets.json /opt/gitlab/config/
cp -r /tmp/gitlab_migrate/.ssh /opt/gitlab/config/  # 可选（自定义SSH密钥）
# 编辑gitlab.rb适配Docker环境（必须修改，否则无法正常使用）
vi /opt/gitlab/config/gitlab.rb

必须修改的配置项（按实际场景调整，示例仅供参考）：


# 1. 外部访问地址（替换为Ubuntu服务器IP/域名，如http://192.168.1.100）
external_url 'http://192.168.1.100'
# 2. 备份目录（容器内路径，对应宿主机/opt/gitlab/backups）
gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"
gitlab_rails['manage_backup_path'] = true
# 3. SSH端口（宿主机22端口默认被SSH占用，映射到2222，此处需与docker-compose一致）
gitlab_rails['gitlab_shell_ssh_port'] = 2222
# 4. 禁用内置PostgreSQL/Redis的自动升级（避免恢复时冲突）
gitlab_rails['auto_migrate'] = false
# 5. 内存优化（如果服务器内存<4GB，添加以下配置，减少资源占用）
puma['worker_processes'] = 2
sidekiq['max_concurrency'] = 10

5.3 迁移备份数据到backups目录


# 复制CentOS的备份文件到GitLab备份目录
cp /tmp/gitlab_migrate/[timestamp]_gitlab_backup.tar /opt/gitlab/backups/
# 修正备份文件权限（匹配容器内git用户，否则无法恢复）
chown 998:998 /opt/gitlab/backups/[timestamp]_gitlab_backup.tar

5.4 编写Docker Compose配置文件

在 /opt/gitlab/ 目录下创建 docker-compose.yml 文件：


cd /opt/gitlab/
vi docker-compose.yml

配置内容（版本匹配+端口映射，关键：镜像版本与CentOS的GitLab一致）：


version: '3.8'
services:
  gitlab:
    # 镜像版本必须与CentOS的GitLab一致（示例：16.8.1-ce.0，需自行替换）
 # 查看CentOS GitLab版本命令：gitlab-rake gitlab:env:info
    image: gitlab/gitlab-ce:16.8.1-ce.0
    container_name: gitlab
    restart: always  # 开机自启
    hostname: '192.168.1.100'  # 与external_url一致
    environment:
      # 时区配置（避免日志时间错乱）
      TZ: 'Asia/Shanghai'
      # 覆盖gitlab.rb的临时配置（与上述gitlab.rb一致即可）
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://192.168.1.100'
    ports:
      # 端口映射：宿主机端口:容器端口（80=HTTP，443=HTTPS，2222=SSH）
      - "80:80"
      - "443:443"
      - "2222:22"
    volumes:
      # 持久化目录挂载（宿主机:容器内，关键：目录路径必须与5.1一致）
      - /opt/gitlab/config:/etc/gitlab
      - /opt/gitlab/data:/var/opt/gitlab
      - /opt/gitlab/logs:/var/log/gitlab
      - /opt/gitlab/backups:/var/opt/gitlab/backups
    # 共享内存配置（至少256M，否则GitLab启动失败）
    shm_size: '256m'
    # 资源限制（可选，根据服务器配置调整，避免占用过多资源）
    deploy:
      resources:
        limits:
          memory: 4G

七、步骤6：启动GitLab并恢复备份

6.1 启动GitLab容器


cd /opt/gitlab/
# 后台启动容器（首次启动需要5-10分钟初始化，耐心等待）
docker-compose up -d
# 查看启动日志（确认无报错，出现"GitLab is up and running"即初始化完成）
docker-compose logs -f gitlab

docker-compose logs -f gitlab

6.2 进入GitLab容器恢复备份


# 1. 进入GitLab容器内部
docker exec -it gitlab /bin/bash
# 2. 执行恢复命令（替换[timestamp]为备份文件的时间戳，如1704421234_2026_01_05_16.8.1）
gitlab-backup restore BACKUP=[timestamp]
# 3. 输入yes确认恢复（出现提示：Do you want to continue (yes/no)? → 输入yes）

# 3. 输入yes确认恢复（出现提示：Do you want to continue (yes/no)? → 输入yes）

6.3 重新配置并重启GitLab


# 容器内执行：重新加载GitLab配置
gitlab-ctl reconfigure
# 重启GitLab服务（确保配置生效）
gitlab-ctl restart
# 退出容器
exit

# 退出容器

exit

八、步骤7：验证数据与服务

7.1 访问GitLab Web界面

浏览器访问 http://Ubuntu_IP（如http://192.168.1.100），使用CentOS上的GitLab账号密码登录，验证以下内容：

  • 项目列表、代码仓库是否完整；

  • 用户、组、权限配置是否正常；

  • CI/CD配置、Issue、Merge Request是否存在；

  • 个人设置、密码是否可正常使用。

7.2 测试SSH克隆/推送（关键验证）

因映射了SSH端口2222，克隆地址格式需指定端口：


git clone git@Ubuntu_IP:2222/用户名/项目名.git
# 测试推送代码：修改本地文件后git push，确认能正常提交

7.3 验证备份功能

迁移完成后，验证新环境的备份功能是否正常：


# 在Ubuntu宿主机执行，生成新备份
docker exec -it gitlab gitlab-backup create
# 查看新备份文件（确认生成成功）
ls -lh /opt/gitlab/backups/

ls -lh /opt/gitlab/backups/

九、关键注意事项（避坑必看）

  1. 版本一致性：Docker版GitLab版本必须 ≥ CentOS版，建议完全一致，否则会出现数据库兼容问题。查看CentOS版本命令：gitlab-rake gitlab:env:info。

  2. 端口冲突：Ubuntu宿主机22端口默认被SSH占用，需将GitLab的SSH映射到2222，并在gitlab.rb中配置gitlab_rails['gitlab_shell_ssh_port'] = 2222。

  3. 防火墙开放：如需启用ufw防火墙，需开放对应端口：


ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 2222/tcp
ufw reload

  1. 数据备份策略：迁移完成后，定期备份 /opt/gitlab 目录（尤其是config和backups），避免数据丢失。

  2. 内存要求：GitLab至少需要4GB内存，否则会启动失败或卡顿，可在gitlab.rb中调整puma/sidekiq进程数优化内存占用。

  3. 日志清理：定期清理GitLab容器日志，避免磁盘占满：


# 备份日志
docker logs gitlab --tail 1000 > /opt/gitlab/logs/gitlab_container.log
# 实时查看日志
docker logs -f gitlab

docker logs -f gitlab

十、故障排查（常见问题解决）

1.容器启动失败：查看日志 docker-compose logs gitlab，常见原因：内存不足（增加服务器内存或优化配置）、端口被占用（更换映射端口）、目录权限错误（重新执行chown -R 998:998 /opt/gitlab/）。

  1. 备份恢复失败：确认3点：① 备份文件权限为998:998；② GitLab版本匹配；③ 执行gitlab-ctl reconfigure后重试恢复。

  2. SSH克隆失败：检查2点：① 容器内SSH服务状态 docker exec gitlab gitlab-ctl status sshd（确保up）；② 端口映射正确（docker-compose中2222:22，gitlab.rb中配置对应端口）。

  3. Web界面无法访问：检查防火墙是否开放80端口、容器是否正常运行（docker ps | grep gitlab）、external_url配置是否正确。

总结

通过以上步骤，可将CentOS服务器上的原生GitLab完整迁移到Ubuntu的Docker Compose环境，核心是完整备份配置与数据、保证版本一致、正确配置目录挂载与权限。迁移完成后，建议先验证所有核心功能，再停止CentOS上的GitLab服务，确保业务平滑切换。

CSDN话题标签

#GitLab #Docker #Docker Compose #服务器迁移 #CentOS #Ubuntu #运维实操 #数据备份

原创内容，转载请注明出处。如有问题，欢迎评论区交流～

# gitlab # centos # ubuntu
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

四天蒸发近2000亿，宇树科技股价近乎“腰斩”；苹果举办库克告别派对：9月1日正式卸任CEO；Anthropic两款新Claude模型曝光 | 极客头条

avatar AI编程社区
cover

Claude Code反超GitHub Copilot登顶第一、90%程序员已用上Agent，最新AI编码调查报告来了

avatar AI编程社区
cover

如何用好 Claude Code 写后端代码

avatar AI编程社区