在运维的生涯中，没有什么比服务器即将到期却伴随着陈旧软件的安全漏洞geng让人头疼的了。这不仅仅是换个机器那么简单，尤其是当你的代码托管平台 GitLab 还停留在好几年前的版本时。想象一下旧服务器在个人账号下摇摇欲坠，而新的企业级 ECS Yi经就位，摆在面前的却是一道kan似不可逾越的鸿沟：如何将数以万计的代码记录、CI/CD 流水线配置以及无数的开发者权限，无损地搬运到新环境，并顺便修补那些让人夜不Neng寐的安全漏洞？

这不仅仅是一次数据迁移，geng是一场关于版本兼容性的“大手术”。hen多新手运维容易犯的一个致命错误就是试图一步登天——直接在新服务器上拉取Zui新的 GitLab 镜像，然后导入旧数据。结果往往是灾难性的：数据库结构彻底损坏，服务无法启动。别慌，今天我们就来拆解一套经过实战检验的“异机同版本迁移 -> 验证切流 -> Docker 镜像阶梯式升级”的完整方案，让你稳稳地完成这次壮举。

一、 核心原则：切勿跨越雷池一步登天

在动手之前，我们必须把一条铁律刻在脑子里：严禁直接修改镜像标签。GitLab 的数据库结构在不同大版本之间变化巨大，Ru果你试图从 9.x 直接跳到 15.x，恢复数据时你只会得到一堆报错。官方文档明确要求，必须遵循“必经停靠点”进行递进式升级。

我们的整体战略是“先同构，后升级”。也就是说新服务器上安装的 GitLab 版本，必须与旧服务器创建备份时的版本号完全一致。比如旧环境是 9.4.3，新环境也得先装 9.4.3，数据迁移成功后再一步步通过中间版本升级到Zui终目标。这听起来hen繁琐，但却是唯一安全可靠的路径。

背景与目标

假设我们的现状是这样的：旧服务器运行着较老的 GitLab 版本，存在Yi知安全漏洞，且服务器即将到期。新服务器Yi经准备就绪。我们的目标是：将旧服务器的 GitLab 完整迁移至新服务器，并升级到Zui新的安全版本。

二、 阶段一：旧环境的“冷冻”与备份

迁移的第一步，是确保旧环境的数据处于绝对静止的状态。Ru果在备份过程中还有人在提交代码，那么备份出来的数据将是不一致的，恢复后必然丢失Zui新的提交记录。

Step 1：停止用户数据写入

我们需要进入旧服务器的 GitLab 容器，停止处理 Web 请求的 Puma 服务和后台任务处理的 Sidekiq 服务。这相当于挂上了“暂停营业”的牌子。

# 进入旧容器并停止关键服务
docker exec -it <旧gitlab容器> gitlab-ctl stop puma
docker exec -it <旧gitlab容器> gitlab-ctl stop sidekiq
# 验证状态，确保它们Yi经停止
docker exec -it <旧gitlab容器> gitlab-ctl status

此时用户Yi经无法通过 Web 界面进行操作，SSH 推送也会被阻塞。这正是我们需要的“静默期”。

Step 2：触发全量备份

接下来利用官方提供的备份工具生成数据快照。这个过程可Neng需要一些时间，取决于你的仓库数量和 LFS 大文件的大小。

docker exec -t <旧容器名称或ID> gitlab-backup create

执行完毕后你会在容器的备份目录下kan到一个类似 1712345678_2026_01_01_16.10.0_gitlab_backup.tar 的文件。这就是我们的救命稻草。

Step 3：转移备份文件与核心秘钥

光有数据包还不够，GitLab 的安全依赖于 gitlab-secrets.json。Ru果只恢复数据而不恢复这个文件，用户将无法登录，两步验证也会失效。

我们需要将备份文件和配置文件从旧服务器搬运到新服务器。建议使用 scp 或 rsync。

# 示例：将备份文件和秘钥文件拷贝到新服务器的临时目录
scp /data/gitlab/data/backups/1712345678_2026_01_01_16.10.0_gitlab_backup.tar root@new-server:/tmp/
scp /data/gitlab/config/gitlab-secrets.json root@new-server:/tmp/

三、 阶段二：新环境的“重生”与恢复

现在舞台转移到了新服务器。我们要在这里搭建一个与旧版本完全一致的 GitLab 环境。

Step 4：准备宿主机环境

确保新服务器Yi经安装了 Docker 和 Docker Compose。然后创建数据挂载目录。为了保持一致性，建议目录结构与旧服务器保持一致，或者根据 docker-compose.yml 自定义。

mkdir -p /data/gitlab/config /data/gitlab/data /data/gitlab/logs

Step 5：编写 Docker Compose 配置

这是Zui关键的一步。请注意，image 的标签必须与旧服务器一致。假设旧版本是 gitlab/gitlab-ce:9.4.3-ce.0，那么新环境也必须用这个。

version: '3'
services:
  gitlab:
    image: 'gitlab/gitlab-ce:9.4.3-ce.0' # 注意：此处必须与源版本完全一致
    container_name: gitlab
    restart: always
    hostname: 'gitlab.example.com'
    ports:
      - '443:443'
      - '80:80'
      - '22:22'
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /data/gitlab/config:/etc/gitlab
      - /data/gitlab/logs:/var/log/gitlab
      - /data/gitlab/data:/var/opt/gitlab
    shm_size: '256m'

将之前拷贝过来的 gitlab-secrets.json 放置到新服务器的 /data/gitlab/config/ 目录下。同时将备份文件 .tar 放置到 /data/gitlab/data/backups/ 目录下。

别忘了修改备份文件的权限，否则 GitLab 容器内的用户可Neng无法读取它。

chmod 600 /data/gitlab/data/backups/1712345678_2026_01_01_16.10.0_gitlab_backup.tar

Step 6：启动新环境

拉取镜像并启动容器。第一次启动会初始化配置，可Neng需要几分钟。

docker-compose up -d

你Ke以通过 docker logs -f gitlab 来观察启动日志，直到kan到 gitlab Reconfigured! 之类的提示。

Step 7：执行恢复命令

容器运行正常后我们就Ke以把旧数据“灌”进去了。执行恢复命令时需要指定备份文件的时间戳前缀。

# 交互提示输入两次 yes 确认
docker exec -it gitlab gitlab-backup restore BACKUP=1712345678_2026_01_01_16.10.0

这个过程会重建数据库表。Ru果一切顺利，你会kan到一系列的 OK 提示。

Step 8：恢复完成与重启

恢复完成后为了确保所有配置生效，建议重启一下容器。

docker restart gitlab
# 执行一次全面检查
docker exec -it gitlab gitlab-rake gitlab:check SANITIZE=true
# Ru果修改了 gitlab.rb 配置，需要重载
docker exec -it gitlab gitlab-ctl reconfigure

四、 阶段三：阶梯式升级

此时新服务器上Yi经运行着和旧服务器一模一样的版本了数据也是Zui新的。接下来就是激动人心的升级环节。请记住不Neng直接跳到Zui新版。

官方升级路径规则要求必须在特定版本停留以完成数据库后台迁移。例如从 9.4.3 升级到 11.8.1，中间可Neng需要经过 10.0.x 和 11.0.x 等停靠点。你需要查阅官方的升级工具来确定具体的路线图。

假设我们的路线是：9.4.3 -> 10.0.x -> 11.0.x -> 11.8.1。

Step 9：修改镜像版本并重建容器

编辑 docker-compose.yml，将 image 标签修改为路线图中的下一个版本，比如 gitlab/gitlab-ce:10.0.0-ce.0。

    image: 'gitlab/gitlab-ce:10.0.0-ce.0' # 替换为下一个停靠点版本号

然后执行升级命令：

docker-compose pull
docker-compose up -d

Step 10：强制等待后台迁移任务完毕

这是升级中Zui关键的一步，也是Zui容易翻车的地方！

GitLab 升级不仅仅是替换二进制文件，还涉及到数据库 schema 的变geng。hen多时候，这些变geng是在后台异步进行的。Ru果你在后台任务还没跑完的时候就急着去升级下一个版本，数据库将会发生不可逆的损毁。

所以每次容器启动并kan起来正常后你必须耐心等待，并检查后台任务的状态。Ke以通过命令行检查：

# 检查普通后台迁移
docker exec -it gitlab gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
# 检查批处理后台迁移队列
docker exec -it gitlab gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'

只有当上述命令全部返回 0 时才代表当前版本的数据库迁移工作彻底完成了。Ru果返回非零值，那就喝杯咖啡，继续等。

当然你也Ke以通过 Web 界面以管理员登录：Admin Area -> Monitoring -> Background Migrations，查kan状态是否全部为 Finished。

Step 11：重复操作直到终点

确认当前版本稳定且后台任务清零后重复 Step 9 和 Step 10：修改 docker-compose.yml 到下一个停靠点，拉取镜像，启动，等待后台迁移完成。

就这样，像爬楼梯一样，一级一级地往上走，直到Zui终达到目标版本。

五、 阶段四：服务切换与验证

当新服务器上的 GitLab Yi经升级到Zui新版本，且运行了一段时间没有问题后我们就Ke以进行Zui后的切流了。

Step 12：初步测试

在修改 DNS 之前，先通过本地 hosts 文件指向新服务器 IP，进行全方位验收：

用户验证开发人员Neng否正常通过 Web 登录界面及终端 SSH 连接。

代码及 Runner 测试提交一段测试代码，观察 CI/CD 流水线是否正常触发，Docker Runner 是否兼容。

性Neng观察观察宿主机 CPU、内存利用率是否异常。

Step 13：修改 DNS

测试通过后修改域名解析，将域名解析指向新服务器 IP。此时全公司的流量就会切换到新环境了。

六、 应急预案：回滚策略

虽然我们Zuo了万全的准备，但墨菲定律告诉我们，凡事总有意外。在新环境运行初期，Ru果发现严重问题，我们需要有快速回滚的Neng力。

在异机迁移模式下回滚基本是零成本、零风险的。因为旧服务器虽然停止了写入，但数据和容器dou还在。

触发回滚的条件：新环境出现致命错误，无法在短时间内修复。

回滚步骤：

修改 DNS 或负载均衡配置，将域名重新解析回旧服务器 IP。

在旧服务器上，由于之前我们只是停止了 Puma 和 Sidekiq，容器其实还在。执行以下命令恢复服务：

docker exec -it <旧容器名称> gitlab-ctl start

业务即可无缝恢复至维护前的状态。后续你Ke以在新服务器上慢慢排查问题，而不必担心线上业务停摆。

GitLab 的迁移和升级确实是一项细致活，它考验的不仅是技术，geng是耐心。从旧服务器的“冷冻”，到新环境的“重生”，再到小心翼翼的“阶梯式攀爬”，每一步dou暗藏玄机。特别是那个关于“后台迁移任务”的等待，往往是hen多急于求成的运维人员容易忽略的细节。

通过本文介绍的这套“异机同版本迁移 + 阶梯升级”方案，我们不仅规避了直接跨版本升级带来的数据损毁风险，还通过保留旧环境作为回滚退路，确保了业务的高可用性。希望这篇指南Neng帮助你在面对服务器到期或版本升级时不再焦虑，从容应对。毕竟代码是公司的核心资产，守护好它们，是我们义不容辞的责任。

---