Debian上GitLab版本升级指南

一、升级前准备工作

1. 备份数据（必做）

升级前必须备份所有关键数据，包括仓库、配置文件和数据库，防止升级失败导致数据丢失。常用命令：
sudo gitlab-rake gitlab:backup:create
此命令会创建包含所有项目和配置的备份文件，默认存储在/var/opt/gitlab/backups目录。

2. 检查系统兼容性

• 确保Debian系统版本与目标GitLab版本兼容（如GitLab 16.x要求Debian 11/12）；
• 更新系统包至最新状态：
  sudo apt-get update && sudo apt-get upgrade -y；
• 验证依赖项是否满足（如curl、openssh-server、ca-certificates、postfix），若缺失可通过sudo apt-get install <package-name>安装。

二、使用APT包管理器升级（推荐）

适用于通过GitLab官方仓库安装的实例，步骤简单且易回滚。

1. 更新APT包列表

sudo apt update
确保系统获取到GitLab官方仓库的最新版本信息。

2. 升级GitLab

• 升级到最新稳定版：
  sudo apt install gitlab-ce（社区版）或sudo apt install gitlab-ee（企业版）；
• 升级到特定版本（如16.3.0）：
  先通过sudo apt policy gitlab-ce查看可用版本，再执行：
  sudo apt install gitlab-ce=<version>。

3. 重新配置与重启

• 重新配置GitLab以应用新版本设置：
  sudo gitlab-ctl reconfigure；
• 重启服务使变更生效：
  sudo gitlab-ctl restart（12.5及以上版本推荐）或sudo systemctl restart gitlab-runsvdir。

4. 验证升级

• 查看GitLab版本信息：
  sudo gitlab-rake gitlab:env:info；
• 访问Web界面（如http://your-server-ip），登录后确认版本号显示正确。

三、手动下载安装包升级

适用于未使用APT仓库或需要自定义安装的场景。

1. 备份数据

同步骤一，确保数据安全。

2. 卸载旧版本（可选但建议）

避免版本冲突，卸载现有GitLab组件：
sudo apt purge gitlab-ce gitlab-ci-multi-runner gitlab-rails gitlab-shell；
删除残留数据和配置目录：
sudo rm -rf /var/opt/gitlab /etc/gitlab。

3. 下载最新安装包

访问GitLab官方下载页面（https://about.gitlab.com/downloads/），选择Debian对应版本（如.deb格式），使用wget下载：
wget https://packages.gitlab.com/gitlab/gitlab-ce/<version>/gitlab-ce_<version>_amd64.deb（替换<version>为目标版本号）。

4. 安装与配置

• 安装下载的.deb包：
  sudo dpkg -i gitlab-ce_<version>_amd64.deb；
• 自动解决依赖问题：
  sudo apt install -f；
• 重新配置GitLab：
  sudo gitlab-ctl reconfigure。

5. 启动与验证

• 启动GitLab服务：
  sudo gitlab-ctl start；
• 验证步骤同APT升级。

四、Docker部署升级

适用于通过Docker容器运行的GitLab实例。

1. 备份数据

通过Docker卷或绑定挂载备份数据目录（如/srv/gitlab/data）。

2. 拉取最新镜像

docker pull gitlab/gitlab-ce:latest（社区版）或docker pull gitlab/gitlab-ee:latest（企业版）。

3. 停止并替换容器

• 停止旧容器：
  docker stop gitlab；
• 删除旧容器（保留数据卷）：
  docker rm gitlab；
• 启动新容器，挂载原数据卷：
  docker run --detach --name gitlab --hostname your-domain.com --publish 443:443 --publish 80:80 --publish 22:22 --volume /srv/gitlab/config:/etc/gitlab --volume /srv/gitlab/logs:/var/log/gitlab --volume /srv/gitlab/data:/var/opt/gitlab gitlab/gitlab-ce:latest。

4. 验证升级

访问Web界面确认版本信息，或进入容器查看：
docker exec -it gitlab grep "VERSION" /etc/gitlab/gitlab.rb。

五、升级注意事项

1. 停机时间

单节点实例升级期间用户无法访问，建议选择低峰期并提前通知。

2. Gitaly服务器升级

若使用独立Gitaly服务器，需先升级Gitaly至与GitLab应用服务器兼容的版本，再升级GitLab。

3. 配置文件检查

升级后检查/etc/gitlab/gitlab.rb中的配置（如external_url），确保与新版本要求一致。

4. 常见问题处理

• 哈希存储迁移：若从旧版本升级到启用哈希存储的新版本，需运行：
  sudo gitlab-rake gitlab:storage:migrate_to_hashed；
• glibc问题：若升级操作系统glibc至2.28及以上，需备份并还原PostgreSQL数据，避免兼容性问题。