Linux里GitLab更新有何技巧

Linux 上 GitLab 更新的实用技巧

一 升级前的规划与准备

• 明确安装方式：是 Omnibus 包、源码编译、Docker 还是 Kubernetes/Helm，不同方式升级路径与命令不同。优先选择升级到目标大版本下的最新补丁版（例如 13.8.8 而非 13.8.0），避免跨多个小版本带来的风险。升级前务必阅读该版本的版本特定变更说明。
• 规划升级路线：从 10.8 起官方强制执行强制升级路径，不允许跨多个主版本直接升级；应逐版本（或按官方推荐路径）升级，并在每个阶段停留足够时间让迁移完成。
• 检查后台迁移：升级到新版本前，确认后台迁移与（自 14.0 起的）批量后台迁移均已完成。可查询剩余任务数，必要时临时增加处理 background_migration 队列的 Sidekiq 并发以加速。
• 做好备份与回滚预案：备份 /etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json 与数据目录；准备好按官方步骤进行恢复的演练与空间。
• 维护窗口与通知：选择低峰时段，提前通知用户；如运行 CI/CD，评估升级对流水线与任务的影响（Runner 会重试或失败，产物最多重试 3 次）。

二 不同安装方式的关键步骤

• Omnibus 包（RPM/DEB）
  1. 备份：执行备份（如 gitlab-backup create 或旧版 gitlab-rake gitlab:backup:create），并备份配置文件与 secrets。
  2. 检查迁移：确认后台迁移与批量后台迁移均完成。
  3. 更新包：使用系统包管理器更新（如 apt/yum/dnf），或下载指定版本 .rpm/.deb 升级。
  4. 重新配置与重启：执行 gitlab-ctl reconfigure，必要时 gitlab-ctl restart。
  5. 验证：访问管理界面或执行健康检查确认版本与功能正常。
• 源码编译
  1. 切换到目标版本的 BRANCH（如 16-0-stable），确保文档与代码分支一致。
  2. 备份、停止服务（如 systemctl stop gitlab.target 或 SysV 的 service 停止）。
  3. 升级运行时依赖（如 Ruby ≥ 3.1.x、Yarn ≥ 1.10.0、合适的 Go 版本），再拉取并检出新版本代码。
  4. 执行数据库迁移（如 bundle exec rake db:migrate RAILS_ENV=production），然后启动服务。
• Docker
  1. 备份挂载卷中的 config/、logs/、data/。
  2. 拉取目标版本镜像（如 gitlab/gitlab-ce:tag）。
  3. 停止旧容器，使用相同卷与端口启动新容器（注意环境变量与卷映射一致）。
• Kubernetes（Helm）
  1. 对照 Chart 版本与 GitLab 版本映射确定升级路径。
  2. 备份 Kubernetes 资源与持久卷数据。
  3. 使用 Helm 升级（如 helm upgrade），按需调整 values 与资源限额。

三 迁移与回滚的要点

• 后台迁移未完成时切勿跨主版本：Omnibus 可用命令检查剩余后台迁移与批量迁移状态；若未完成，先扩容 Sidekiq 处理 background_migration 队列，待完成后再升级。
• 批量后台迁移卡住的处理：在 GitLab 14.0+ 可能需要先在 14.0 上运行至少一天以完成数据库变更；若界面提示某批量迁移未 finished，可在数据库中查询未完成项并排查。
• 常见“卡住”迁移的已知问题：如 13.6/14.2/14.4/14.5/14.8/14.9 等版本存在特定迁移在特定数据条件下可能长期 pending，需按对应版本的官方说明进行清理或补救。
• 回滚策略：升级失败或异常时，先恢复到升级前备份与原版本包；恢复命令示例（Omnibus）：gitlab-rake gitlab:backup:restore BACKUP=备份时间戳。恢复后执行 gitlab-ctl reconfigure 与重启。

四 版本路径与常见坑的规避

• 强制升级路径与“停一停”策略：从 10.8 起强制路径生效，禁止跨多主版本；建议主/次版本升级间隔不超过一周，给后台迁移留足时间。
• 必须停下的版本点：升级到某些版本可能需要手动干预或额外步骤（如 13.x 的若干变更），务必阅读版本说明并按指引操作。
• 升级顺序与补丁优先：优先升级到当前大版本的最新补丁版；跨主版本时遵循官方推荐路径逐级升级，避免一次性跨越多个主版本。
• 升级后健康检查：访问管理界面核查版本与健康状态，必要时运行 gitlab-rake gitlab:check（Omnibus 可用）确认系统状态。

五 自动化与最小化停机时间的建议

• 使用官方仓库进行就地升级，减少人为失误；为关键步骤编写脚本化流程（备份→检查→升级→验证→回滚）。
• 在维护窗口内操作，提前停止写入（如可短暂停止 unicorn/sidekiq），并在升级后第一时间完成 reconfigure/restart 与验证。
• 若需更高可用性，考虑在蓝绿/金丝雀环境验证新版本后再切换；对 Runner 与 CI/CD 提前告知与评估，允许任务自动重试与失败回退。