GitLab Linux版本更新注意事项

GitLab Linux版本更新注意事项

一 升级前准备

• 核对当前与目标版本，严格按官方升级路径执行，避免跨多主版本直接升级；必要时先在测试环境演练。备份建议包含：应用数据备份、配置文件与密钥文件。生产环境建议安排维护窗口并提前通知用户。
• 备份与版本确认
  • 应用数据备份：GitLab 12.2+ 使用命令：gitlab-backup create；12.1 及更早使用：gitlab-rake gitlab:backup:create。备份默认目录可在 /etc/gitlab/gitlab.rb 的 backup_path 配置项查看。
  • 配置文件与密钥：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json 必须单独备份（恢复时同样需要）。
  • 当前版本确认：查看文件 /opt/gitlab/embedded/service/gitlab-rails/VERSION。
• 系统与时区
  • 确保系统时间与时区正确，避免证书校验、计划任务与迁移任务异常。
• 资源与依赖
  • 预留充足磁盘空间（备份与解压过程会临时占用），确保网络稳定（下载安装包/镜像）。
  • 按需准备系统依赖（如 policycoreutils、openssh-server、postfix 等），避免 reconfigure/启动阶段报错。

二 升级路径与数据库变更

• 严格遵循官方升级路径，逐版本升级（通常先升级到当前主版本的最新小版本，再进入下一主版本）。示例路径（仅示意，请以官方工具/文档为准）：
  • 11.4.3 → 11.11.8 → 12.0.12 → 12.1.17 → 12.10.14 → 13.0.14 → 13.1.11 → 13.8.8 → 13.12.15 → 14.0.12 → 14.3.6 → 14.9.5 → 14.10.5
  • 11.0.2 → 11.11.8 → 12.10.14 → 13.12.15 → 14.3.6 → 14.9.5 → 15.0.5 → 15.4.6 → 16.0.8 → 16.3.7 → 16.7.7 → 16.10.1 → 17.2.2
• 关键版本与动作提示
  • 13 → 14：可能涉及“哈希存储”转换，按提示完成存储与迁移相关步骤。
  • 14.0.12 → 14.3.6：需要升级数据库关系；部分环境还需关注 Redis 版本兼容。
  • 15.11.x → 16.0.x：需将内置 PostgreSQL 升级至 13（使用命令：gitlab-ctl pg-upgrade -V 13），升级前确认版本：/opt/gitlab/embedded/bin/postgres --version。
  • 16.11.x → 17.2.x：继续按官方路径执行，关注控制台与后台任务报错，必要时处理卡住的后台迁移任务。

三 升级操作要点

• 建议流程（Omnibus 包管理，适用于 Debian/Ubuntu/CentOS/RHEL）
  1. 备份：执行应用数据备份与配置/密钥备份。
  2. 停止写入组件：建议先停 unicorn/puma 与 sidekiq（避免备份与迁移不一致）。示例：gitlab-ctl stop unicorn && gitlab-ctl stop sidekiq（如环境使用 Puma，则停 puma）。
  3. 更新软件包：
     • Debian/Ubuntu：sudo apt update && sudo apt install gitlab-ce=（或下载 .deb 后 dpkg -i）。
     • CentOS/RHEL：sudo yum install gitlab-ce-.rpm 或 rpm -Uvh gitlab-ce-.rpm。
  4. 重新配置与启动：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。
  5. 验证：gitlab-rake gitlab:check 或访问管理界面确认版本与健康状态。
• 容器化部署（Docker）
  • 备份挂载卷数据（如 /srv/gitlab/config、/srv/gitlab/logs、/srv/gitlab/data），拉取目标版本镜像，使用原有卷重新启动新容器；升级后复核证书与配置。
• 可用性影响
  • 单节点升级期间通常不可用（可能出现 Deploy in progress 或 502），多节点可参考官方零停机方案执行滚动升级。

四 升级后验证与常见问题

• 验证清单
  • 版本核对：管理界面与 /opt/gitlab/embedded/service/gitlab-rails/VERSION。
  • 健康与任务：执行 gitlab-rake gitlab:check；在“管理 → 监控 → 后台任务”确认无卡死迁移/作业。
  • 数据一致性：抽查项目、仓库、LFS、CI 作业、Runner 注册与 Webhook 触发是否正常。
• 常见故障处理
  • 502/页面不可用：等待迁移完成或重启相关服务（如 gitlab-ctl restart sidekiq；必要时 systemctl restart gitlab-runsvdir）。
  • 数据库迁移问题：查看状态 gitlab-rake db:migrate:status，必要时执行 gitlab-rake db:migrate；如失败，回滚到升级前版本并恢复备份。
  • 权限/目录异常：如 /var/opt/gitlab/postgresql 权限问题，可临时修正（如 chmod 0755）后再执行迁移与重启。
  • 配置/进程占用：修改 gitlab.rb 后需 gitlab-ctl reconfigure；如遇 Chef/puma 占用，排查并终止相关进程后再执行。

五 回退与恢复

• 回退原则
  • 回退需要“撤销”升级带来的数据库变更，必须准备与目标版本完全一致（版本号与 CE/EE 类型一致）的数据库备份，最好有完整应用备份。
• Linux 包实例回退步骤
  1. 停止服务：gitlab-ctl stop puma && gitlab-ctl stop sidekiq。
  2. 卸载当前包：Debian/Ubuntu 使用 dpkg -r gitlab-ee/gitlab-ce；CentOS/RHEL 使用 yum remove gitlab-ee/gitlab-ce。
  3. 安装目标版本：如 apt install gitlab-ee=15.0.5-ee.0 或 yum install gitlab-ee-15.0.5-ee.0.el8（CE 替换为 gitlab-ce）。
  4. 重新配置：gitlab-ctl reconfigure。
  5. 恢复数据：使用回退目标版本的备份执行恢复（确保与备份时版本/类型完全一致）。
• Docker 回退要点
  • 指定早期版本镜像启动，恢复数据库备份；为减少覆盖，可使用 SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state 仅恢复数据库。
• 重要提醒
  • 回退会丢失升级后产生的数据/变更；仅在必要时执行，并优先选择“回到升级前最近一次备份点”。