GitLab Linux版本更新注意事项
小樊
42
2025-11-30 19:08:10
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）
- 备份：执行应用数据备份与配置/密钥备份。
- 停止写入组件：建议先停 unicorn/puma 与 sidekiq（避免备份与迁移不一致）。示例：gitlab-ctl stop unicorn && gitlab-ctl stop sidekiq（如环境使用 Puma，则停 puma）。
- 更新软件包：
- 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。
- 重新配置与启动：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。
- 验证：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 包实例回退步骤
- 停止服务：gitlab-ctl stop puma && gitlab-ctl stop sidekiq。
- 卸载当前包：Debian/Ubuntu 使用 dpkg -r gitlab-ee/gitlab-ce；CentOS/RHEL 使用 yum remove gitlab-ee/gitlab-ce。
- 安装目标版本：如 apt install gitlab-ee=15.0.5-ee.0 或 yum install gitlab-ee-15.0.5-ee.0.el8（CE 替换为 gitlab-ce）。
- 重新配置：gitlab-ctl reconfigure。
- 恢复数据：使用回退目标版本的备份执行恢复（确保与备份时版本/类型完全一致）。
- Docker 回退要点
- 指定早期版本镜像启动，恢复数据库备份；为减少覆盖，可使用 SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state 仅恢复数据库。
- 重要提醒
- 回退会丢失升级后产生的数据/变更；仅在必要时执行，并优先选择“回到升级前最近一次备份点”。
