Ubuntu 上升级 GitLab 的完整步骤
一 升级前准备
- 确认当前版本与仓库源：查看已安装版本（如访问 /help 页面，或执行命令查看），并确认使用的是 gitlab-ce（社区版）/gitlab-ee（企业版）/gitlab-jh（极狐版） 的 APT 源。示例：
apt policy gitlab-ce 或 apt policy gitlab-jh。
- 核对升级路径：GitLab 升级需遵循官方升级路径，不能跨越大版本。使用官方升级路径工具选择你的起始版本与目标版本，按提示逐跳升级。
- 全量备份：先备份数据与配置，默认备份目录为 /var/opt/gitlab/backups/。命令：
sudo gitlab-rake gitlab:backup:create。如后续需要恢复：sudo gitlab-rake gitlab:backup:restore BACKUP=备份时间戳。
- 检查内置数据库版本：若从 17.x 升级到 18.0.x，内置 PostgreSQL 需为 16.x。检查命令：
sudo gitlab-ctl pg-upgrade -V 或在 psql 中 SELECT version();。不满足需先升级数据库再升 GitLab。
- 维护窗口与通知：升级期间会重启服务，建议安排停机窗口并提前通知用户。
二 标准升级步骤（同系列小版本或按路径的相邻版本）
- 更新软件索引：
sudo apt update
- 执行升级：
- 社区版：
sudo apt install gitlab-ce
- 企业版：
sudo apt install gitlab-ee
- 极狐版：
sudo apt install gitlab-jh
- 重新配置并重启：
sudo gitlab-ctl reconfigure，随后可用 sudo gitlab-ctl restart 或 sudo systemctl status gitlab-ee/gitlab-ce/gitlab-jh 检查状态。
- 验证版本：访问 /help 页面或查看文件 /opt/gitlab/embedded/service/gitlab-rails/VERSION。
- 回滚预案：若升级异常，先恢复最近备份，再按备份对应的版本回装并恢复。
三 跨大版本升级要点（示例 17 → 18）
- 路径先行：使用官方升级路径工具确认可从 17.10 直达 18.0.1，若工具提示需经停（如先到 17.11.z），务必按提示执行。
- 数据库先行：升级到 18.0 前，内置 PostgreSQL 必须 16.x。若当前为 14.x/15.x，需先在同主版本内升级到 16.x：
- 升级 GitLab 到提示的过渡版本（如 17.11.z）：
sudo apt install gitlab-jh=17.11.2-jh.0
- 升级内置数据库：
sudo gitlab-ctl pg-upgrade（按交互选择目标版本，通常选 16）
- 确认数据库版本：
sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -c "SELECT version();"
- 完成数据库升级后再升级到 18.0.1：
sudo apt install gitlab-jh。
- 如遇到预安装脚本错误（dpkg 报错），多半与数据库版本不符有关，按上一步先升数据库再重试。
四 常见问题与排查
- 升级报错 dpkg: error processing archive … pre-installation script returned error exit status 1：多与内置 PostgreSQL 版本不满足目标版本要求有关。先在同主版本内升级数据库（
gitlab-ctl pg-upgrade），再重试 GitLab 升级。
- 页面无法访问或功能异常：检查服务状态
sudo gitlab-ctl status，查看日志 sudo gitlab-ctl tail，确认 /etc/gitlab/gitlab.rb 配置无语法错误后执行 sudo gitlab-ctl reconfigure。
- 备份与恢复：默认备份不含所有内容（例如某些附件/仓库数据），务必定期全量备份并演练恢复流程；恢复时指定时间戳：
sudo gitlab-rake gitlab:backup:restore BACKUP=时间戳。
- 升级耗时较长或内存不足：Omnibus 包在升级时会执行数据库迁移与重建操作，建议在至少 4GB 内存 的环境下执行，并预留足够时间。