GitLab Linux版本升级需要注意什么

GitLab Linux 版本升级注意事项

一 升级前准备

• 确认安装方式与当前版本：使用命令查看版本与运行环境，例如查看版本文件 /opt/gitlab/embedded/service/gitlab-rails/VERSION，或执行 sudo gitlab-rake gitlab:env:info。同时确认是 Omnibus RPM/DEB 还是源码/容器部署，不同方式升级步骤不同。
• 规划升级路径：严格遵循官方的升级路径，不可跨多个主版本直接升级。应先升级到当前主版本的最新小版本，再进入下一主版本；可用官方升级路径工具或文档核对。
• 完整备份：先做应用数据备份 sudo gitlab-rake gitlab:backup:create（默认目录 /var/opt/gitlab/backups），再备份配置与密钥 /etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json。注意：备份只能恢复到与其创建时完全相同的版本与类型（CE/EE）。
• 系统与健康检查：在目标版本上先跑 sudo gitlab-rake gitlab:check，提前处理告警；确保磁盘空间、I/O、内存充足；生产环境建议先在测试环境演练全流程。
• 维护窗口与可用性：单节点升级期间服务会不可用（可能出现 Deploy in progress 或 502）；多节点如需不停机，按官方指引执行零停机升级。

二 升级路径与版本门槛

• 逐版本升级：每次只升到路径中的下一版本，完成迁移与检查后再继续，避免一次性跨度过大导致回滚困难。
• 大版本门槛示例：从 13.x → 14.x 需要完成哈希存储迁移；从 14.0.12 → 14.3.6 需完成数据库关系升级；从 15.11.x → 16.0.x 与 16.11.x → 17.x 需要按官方步骤升级内置 PostgreSQL（如先到 13，再到 14），否则升级会失败。
• 配置项变更：如 13.12.15 → 14.0.12 起默认不再使用 Unicorn，需改用 Puma，并在 /etc/gitlab/gitlab.rb 中调整；旧配置直接沿用可能报错。
• 后台迁移收尾：部分版本升级后需执行后台迁移收尾任务，例如以 13.12.15 → 14.0.12 为起点的多个 gitlab:background_migrations:finalize 任务，确保大字段转换完成后再继续后续升级或业务切换。

三 升级中操作要点

• 包管理与安装：Omnibus 包用包管理器升级（RPM：rpm -Uvh gitlab-ce-.rpm；DEB：dpkg -i gitlab-ce__ce.deb），或 apt/yum 直接升级；安装后务必执行 sudo gitlab-ctl reconfigure 使配置生效。
• 服务启停策略：可在升级前短暂停止部分写服务（如 unicorn/sidekiq/puma）以减少备份与迁移时的数据变动，但不要全关导致健康检查失败；升级完成后执行 gitlab-ctl restart 恢复服务。
• 数据库迁移：每次升级后检查并执行 sudo gitlab-rake db:migrate（必要时先看 db:migrate:status），待所有迁移为 up 再进行下一版本升级。
• 版本核对与回滚预案：通过 /opt/gitlab/embedded/service/gitlab-rails/VERSION 或管理界面确认版本；若某版本失败，使用之前的备份在同级版本上恢复，再按路径重试。

四 升级后验证与常见问题

• 可用性验证：访问页面确认版本号与功能正常；出现 502 多为服务未完全就绪，稍候片刻；持续 500 需查看日志与迁移状态。
• 健康检查与后台任务：执行 sudo gitlab-rake gitlab:check；在管理后台查看后台任务，清理停滞任务，避免影响后续迁移与页面可用性。
• 配置与密钥：确认 /etc/gitlab/gitlab.rb 与 gitlab-secrets.json 正确无误；若曾注释或调整 Puma/Unicorn 等参数，按需恢复并重新 reconfigure。
• 数据库与存储：再次确认 db:migrate:status 均为 up；如涉及 PostgreSQL 大版本升级，按官方步骤完成并校验版本（例如 /opt/gitlab/embedded/bin/postgres --version）。

五 不同安装方式与系统要点

• RPM 系（如 CentOS/RHEL）：优先用 yum/dnf 或下载 RPM 本地升级；注意系统依赖与防火墙策略，升级窗口内可限制访问以降低风险。
• DEB 系（如 Debian/Ubuntu）：使用 apt 或 dpkg 升级，完成后执行 gitlab-ctl reconfigure；如用 Docker 运行，需基于卷/绑定挂载做好数据与配置备份，拉取新镜像后以原有数据卷重启新容器。