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，否则恢复可能失败。
停机窗口与回滚
- 迁移前明确停机窗口与回滚方案；整机迁移回滚只需切回旧实例；仅数据库迁移回滚需保留旧库快照与备份。

最新问答