CentOS上GitLab的版本更新技巧

CentOS 上 GitLab 版本更新技巧

一 升级前的准备与规划

• 备份关键资产：执行应用数据备份与配置/密钥备份，确保可回滚与快速恢复。
  • 应用数据：sudo gitlab-rake gitlab:backup:create（默认归档至 /var/opt/gitlab/backups）
  • 配置与密钥：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json
• 确认现状与目标：
  • 当前版本：sudo gitlab-rake gitlab:env:info
  • 目标版本与升级路线：使用官方 Upgrade Path 工具规划路径，避免跨多版本直接升级。
• 系统与仓库准备：
  • 系统补丁：sudo yum update
  • 导入仓库密钥：sudo rpm --import https://packages.gitlab.com/gpg.key
  • 如未配置仓库，可导入官方 RPM 脚本仓库后使用 yum 安装/升级。

二 正确的升级路线与关键检查

• 路线原则：遵循“逐级升级”，先到当前大版本的最高补丁，再进入下一大版本；例如从 11.0.2 升级到 17.2.2 需经过多个中间版本节点，不可一步跨越。
• 单节点与多节点差异：
  • 单节点：升级期间通常不可用（可能出现 Deploy in progress 或 502），选择低峰时段执行。
  • 多节点：可按官方指引执行“零停机升级”（不同角色滚动升级）。
• 数据库与组件前置检查（跨版本常见拦路虎）：
  • 13 → 14：需完成“哈希存储”转换（hashed storage migration）。
  • 14.0.12 → 14.3.6：涉及数据库关系与 Redis 版本升级，任一缺失都会导致失败。
  • 15.11 → 16.x：需将内置 PostgreSQL 升级至 13；16.11 → 17.x：需升级至 14（使用 gitlab-ctl pg-upgrade -V <目标版本>）。
  • 每次升级后建议执行：sudo gitlab-rake db:migrate:status 与 sudo gitlab-rake db:migrate，确保迁移完成；必要时 gitlab-ctl reconfigure && gitlab-ctl restart。

三 标准升级步骤与常用命令

• 停止写路径服务（减少备份与升级不一致风险）：
  • sudo gitlab-ctl stop puma（或 unicorn）
  • sudo gitlab-ctl stop sidekiq
  • 可选：sudo gitlab-ctl stop nginx
• 执行升级（Omnibus RPM 场景）：
  • 方式 A（仓库优先）：sudo EXTERNAL_URL="https://gitlab.example.com" yum update gitlab-ce
  • 方式 B（离线 RPM）：sudo rpm -Uvh gitlab-ce-<version>.rpm
• 重新配置与启动：
  • sudo gitlab-ctl reconfigure
  • sudo gitlab-ctl restart
• 验证结果：
  • 版本：sudo gitlab-rake gitlab:env:info
  • 健康：sudo gitlab-rake gitlab:check
  • 访问管理界面确认版本号与功能可用性。

四 回滚与应急

• 回滚前提：必须拥有与“目标回退版本+相同版本与发行版（CE/EE）”一致的数据库备份（最好包含完整应用备份），否则无法安全回退数据库迁移。
• 回滚步骤（RPM 场景）：
  • 停止服务：sudo gitlab-ctl stop puma && sudo gitlab-ctl stop sidekiq
  • 卸载当前包：sudo yum remove gitlab-ee（CE 则为 gitlab-ce）
  • 安装目标版本：sudo yum install gitlab-ee-<version>-ee.0.el<osver>（CE 将 ee 替换为 ce）
  • 重新配置：sudo gitlab-ctl reconfigure
  • 恢复数据：使用升级前同版本的备份执行恢复（确保与回退版本一致）。

五 实用技巧与排错清单

• 升级前先在测试环境演练，验证升级路径与耗时，降低生产风险。
• 升级窗口与可用性：单节点升级会短暂不可用，提前公告并选择低峰时段；多节点按官方零停机方案执行。
• 升级后若见 500 或后台任务卡住：
  • 查看迁移状态：sudo gitlab-rake db:migrate:status
  • 执行迁移：sudo gitlab-rake db:migrate
  • 必要时：gitlab-ctl reconfigure && gitlab-ctl restart，并在管理后台“监控 → 后台任务”清理卡住任务。
• 权限与目录问题（经验项）：如遇权限报错，检查如 /var/opt/gitlab/postgresql 等目录权限，必要时修正后重启相关服务。
• 小版本与大版本策略：小版本可快速跟随仓库更新；跨大版本务必按“逐级升级”与“必要的前置任务（如 PG/Redis/存储转换）”执行。