Debian下GitLab数据库迁移指南

Debian下GitLab数据库迁移指南

一 迁移方式与前置准备

• 迁移方式选择
  • 整机迁移（推荐）：使用 Omnibus 内置备份工具打包仓库、数据库与附件，在新服务器同版本恢复，操作简洁、风险低。备份默认目录为 /var/opt/gitlab/backups。适用于绝大多数场景。
  • 仅数据库迁移：手动导出 PostgreSQL 数据并在新库导入，同时迁移配置与数据目录。适用于更换数据库实例或做架构调整，步骤更复杂、需严格一致性校验。
• 版本与一致性
  • 建议新旧实例 GitLab 版本完全一致（含小版本/补丁），避免结构差异导致恢复失败或数据不一致。
  • 检查版本：cat /opt/gitlab/embedded/service/gitlab-rails/VERSION。
• 备份工具与命令
  • GitLab 12.2+：使用 gitlab-backup create
  • GitLab 12.1 及更早：使用 gitlab-rake gitlab:backup:create
• 规划与网络
  • 预估停机时间，选择业务低峰；内网直连传输备份文件可显著提升速度并降低风险。

二 方案一 整机迁移步骤（内置备份恢复）

• 旧服务器备份
  • 建议先停止写入服务：sudo gitlab-ctl stop puma；sudo gitlab-ctl stop sidekiq
  • 创建备份：sudo gitlab-backup create（12.1 用：sudo gitlab-rake gitlab:backup:create）
  • 备份文件位于：/var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar
• 传输备份到新服务器
  • scp /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar user@new_ip:/var/opt/gitlab/backups/
• 新服务器恢复
  • 安装与旧服务器 同版本 GitLab（Debian 包管理安装）
  • 确认备份文件属主为 git:git：sudo chown git:git /var/opt/gitlab/backups/*
  • 停止写入服务：sudo gitlab-ctl stop puma；sudo gitlab-ctl stop sidekiq
  • 执行恢复（BACKUP 参数不带 “_gitlab_backup.tar” 后缀）：sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
  • 如为 13.1+ 且跨服务器，检查密钥可解密：sudo gitlab-rake gitlab:doctor:secrets
  • 重新配置并启动：sudo gitlab-ctl reconfigure；sudo gitlab-ctl start
• 验证
  • 登录 Web 检查项目、用户、权限；运行健康检查：sudo gitlab-rake gitlab:check SANITIZE=true
  • 可选完整性校验：sudo gitlab-rake gitlab:artifacts:check；sudo gitlab-rake gitlab:lfs:check；sudo gitlab-rake gitlab:uploads:check。

三 方案二 仅数据库迁移步骤（PostgreSQL）

• 旧库导出
  • 建议停机一致性导出：sudo gitlab-ctl stop puma；sudo gitlab-ctl stop sidekiq
  • 导出：sudo -u postgres pg_dump -d gitlabhq_production > gitlab-backup.sql
• 新库准备
  • 安装 PostgreSQL（Debian）：sudo apt-get update && sudo apt-get install -y postgresql postgresql-contrib
  • 创建库与用户（示例）：sudo -u postgres psql
    • CREATE DATABASE gitlabhq_production;
    • CREATE USER gitlab WITH PASSWORD ‘your_password’;
    • GRANT ALL PRIVILEGES ON DATABASE gitlabhq_production TO gitlab;
• 新库导入
  • psql gitlabhq_production < gitlab-backup.sql
• 配置与启动
  • 编辑 /etc/gitlab/gitlab.rb，确保数据库指向新库（示例）：
    • gitlab_rails[‘db_adapter’] = “postgresql”
    • gitlab_rails[‘db_host’] = “localhost”
    • gitlab_rails[‘db_port’] = 5432
    • gitlab_rails[‘db_username’] = “gitlab”
    • gitlab_rails[‘db_password’] = “your_password”
    • gitlab_rails[‘db_database’] = “gitlabhq_production”
  • 重新配置并启动：sudo gitlab-ctl reconfigure；sudo gitlab-ctl start
• 校验
  • 访问实例并检查关键功能；必要时运行 gitlab-rake 检查任务（如 artifacts、lfs、uploads）。

四 常见问题与注意事项

• 版本不一致
  • 不同版本的数据库结构可能不兼容，务必保持 同版本迁移；若需升级，先在原环境升级完成再迁移。
• secrets 与加密数据
  • 跨服务器恢复时，/etc/gitlab/gitlab-secrets.json 必须一致或在 13.1+ 用 gitlab-rake gitlab:doctor:secrets 验证可解密，否则可能导致 CI/CD 变量、Runner 注册、加密配置不可用。
• 备份与恢复命令差异
  • 12.2+ 使用 gitlab-backup；12.1 及更早 使用 gitlab-rake gitlab:backup:create/restore。恢复时 BACKUP 参数不带后缀名。
• 文件权限与目录
  • 备份文件与数据目录（如 /var/opt/gitlab/backups）属主应为 git:git，否则恢复可能失败。
• 停机窗口与回滚
  • 迁移前明确停机窗口与回滚方案；整机迁移回滚只需切回旧实例；仅数据库迁移回滚需保留旧库快照与备份。