| GitLab Docs

Help us learn about your current experience with the documentation. Take the survey.

---
stage: Gitlab Delivery
group: Self Managed
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
title: 升级自行编译的安装
---


      Tier: Free, Premium, Ultimate

      Offering: GitLab Self-Managed


升级自行编译的 GitLab 实例到更高版本。

如果您要从 GitLab Community Edition（社区版）升级到 GitLab Enterprise Edition（企业版），请参考
[从社区版升级到企业版](upgrading_from_ce_to_ee.md) 文档。

## 升级到新主版本号

主版本号可能引入向后不兼容的变更。您应先升级到当前主版本号的最新次版本号。
请遵循 [升级建议](../policy/maintenance.md#upgrade-recommendations) 确定最佳升级路径。

升级新主版本号前，请确保之前版本的后台迁移任务已完成。要查看 `background_migration` 队列的当前大小，
请参阅 [升级前检查后台迁移](background_migrations.md)。

## 升级自行编译的实例

升级自行编译的 GitLab 实例步骤如下：

1. 升级前检查不同 GitLab 版本的变更以确保兼容性：
   - [GitLab 17 变更](versions/gitlab_17_changes.md)
   - [GitLab 16 变更](versions/gitlab_16_changes.md)
   - [GitLab 15 变更](versions/gitlab_15_changes.md)
1. 检查 [后台迁移](background_migrations.md)。所有迁移必须在每次升级前完成。
1. [创建备份](#create-a-backup)。
1. [停止 GitLab](#stop-gitlab)。
1. [更新 Ruby](#update-ruby)。
1. [更新 Node.js](#update-nodejs)。
1. [更新 Go](#update-go)。
1. [更新 Git](#update-git)。
1. [更新 PostgreSQL](#update-postgresql)。
1. [更新 GitLab 代码库](#update-the-gitlab-codebase)。
1. [更新配置文件](#update-configuration-files)。
1. [安装依赖并运行迁移](#install-libraries-and-run-migrations)。
1. [更新 GitLab Shell](#update-gitlab-shell)。
1. [更新 GitLab Workhorse](#update-gitlab-workhorse)。
1. [更新 Gitaly](#update-gitaly)。
1. [更新 GitLab Pages](#update-gitlab-pages)。

升级完成后：

1. [启动 GitLab 和 NGINX](#start-gitlab-and-nginx)。
1. [检查 GitLab 状态](#check-gitlab-status)。

### 创建备份

前提条件：
- 确保 `rsync` 已安装。

执行备份：
```shell
cd /home/git/gitlab

sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production

停止 GitLab

# 使用 systemd 的系统
sudo systemctl stop gitlab.target

# 使用 SysV init 的系统
sudo service gitlab stop

更新 Ruby

GitLab 17.5 及更高版本仅支持 Ruby 3.2.x，必要时请升级。使用以下命令检查当前 Ruby 版本：

ruby -v

安装 Ruby。

更新 Node.js

要检查最低要求的 Node.js 版本，请参阅 Node.js 版本要求。

GitLab 还需要 Yarn >= v1.10.0 来管理 JavaScript 依赖。

更新 Yarn（Debian/Ubuntu）：

sudo apt-get remove yarn
npm install --global yarn

更多信息请访问 Yarn 官网。

更新 Go

要检查最低要求的 Go 版本，请参阅 Go 版本要求。

检查当前版本：

go version

下载并安装 Go（例如 64 位 Linux）：

# 删除旧版 Go 安装目录
sudo rm -rf /usr/local/go

curl --remote-name --location --progress-bar "https://go.dev/dl/go1.22.5.linux-amd64.tar.gz"
echo '904b924d435eaea086515bc63235b192ea441bd8c9b198c507e85009e6e4c7f0  go1.22.5.linux-amd64.tar.gz' | shasum -a256 -c - && \
  sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/
rm go1.22.5.linux-amd64.tar.gz

更新 Git

要检查是否满足最低 Git 版本要求，请参阅 Git 版本要求。

使用 Gitaly 提供的 Git 版本，该版本：

始终满足 GitLab 的版本要求。
可能包含正常运行所需的自定义补丁。

# 安装依赖
sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential

# 克隆 Gitaly 仓库
git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly

# 编译并安装 Git
cd /tmp/gitaly
sudo make git GIT_PREFIX=/usr/local

将 <X-Y-stable> 替换为与目标 GitLab 版本匹配的稳定分支名（例如安装 GitLab 16.7 时使用 16-7-stable）。

记得在 config/gitlab.yml 中设置 git -> bin_path 为 /usr/local/bin/git。

更新 PostgreSQL

最新版 GitLab 可能依赖比当前运行更新的 PostgreSQL 版本，且可能需要启用某些扩展。更多信息请参阅 PostgreSQL 要求。

GitLab 18.0 需要 PostgreSQL 16。

升级 PostgreSQL 请参考其官方文档。

更新 GitLab 代码库

更新 GitLab 代码库克隆：

获取仓库元数据：

cd /home/git/gitlab
sudo -u git -H git fetch --all --prune
sudo -u git -H git checkout -- Gemfile.lock db/structure.sql locale

切换到目标版本分支：

社区版：

cd /home/git/gitlab
sudo -u git -H git checkout <BRANCH>

企业版：

cd /home/git/gitlab
sudo -u git -H git checkout <BRANCH-ee>

更新配置文件

升级时需为新配置选项更新：

gitlab.yml
database.yml
NGINX（或 Apache）
SMTP
systemd
SysV

`gitlab.yml` 新配置

gitlab.yml 可能有新配置选项：

查看新增配置：

cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:config/gitlab.yml.example origin/BRANCH:config/gitlab.yml.example

手动将新配置添加到当前 gitlab.yml。

`database.yml` 新配置

database.yml 可能有新配置：

查看新增配置：

cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:config/database.yml.postgresql origin/BRANCH:config/database.yml.postgresql

手动将新配置添加到当前 database.yml。

NGINX 或 Apache 新配置

确保使用最新的 NGINX 配置变更：

cd /home/git/gitlab

# HTTPS 配置
git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab-ssl origin/BRANCH:lib/support/nginx/gitlab-ssl

# HTTP 配置
git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab origin/BRANCH:lib/support/nginx/gitlab

GitLab 不再自动设置 Strict-Transport-Security，需在 NGINX 配置中手动启用。

若使用 Apache，请参考更新的 Apache 模板。由于 Apache 不支持 Unix socket 后端，需通过 /etc/default/gitlab 让 GitLab Workhorse 监听 TCP 端口。

SMTP 配置

若使用 SMTP 发送邮件，请在 config/initializers/smtp_settings.rb 添加：

ActionMailer::Base.delivery_method = :smtp

示例请参考 smtp_settings.rb.sample。

配置 systemd 单元

检查 systemd 单元是否更新：

cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:lib/support/systemd origin/BRANCH:lib/support/systemd

复制文件：

sudo mkdir -p /usr/local/lib/systemd/system
sudo cp lib/support/systemd/* /usr/local/lib/systemd/system/
sudo systemctl daemon-reload

配置 SysV init 脚本

gitlab.default.example 可能有新配置：

查看新增配置：

cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:lib/support/init.d/gitlab.default.example origin/BRANCH:lib/support/init.d/gitlab.default.example

手动将新配置添加到当前 /etc/default/gitlab。

确保使用最新的 init 脚本：

cd /home/git/gitlab
sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab

若在 systemd 系统上仍使用 init 脚本（未切换到原生 systemd 单元），请运行：

sudo systemctl daemon-reload

安装依赖并运行迁移

确保安装了所需的 PostgreSQL 扩展。

安装依赖：

cd /home/git/gitlab

# 若安装或上次升级未执行过
sudo -u git -H bundle config set --local deployment 'true'
sudo -u git -H bundle config set --local without 'development test kerberos'

# 更新 gems
sudo -u git -H bundle install

# 可选：清理旧 gems
sudo -u git -H bundle clean

# 运行数据库迁移
sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production

# 更新 node 依赖并重新编译资源
sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production NODE_OPTIONS="--max_old_space_size=4096"

# 清理缓存
sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production

更新 GitLab Shell

cd /home/git/gitlab-shell

sudo -u git -H git fetch --all --tags --prune
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION)
sudo -u git -H make build

更新 GitLab Workhorse

安装并编译 GitLab Workhorse：

cd /home/git/gitlab
sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production

更新 Gitaly

必须先升级 Gitaly 服务器再升级应用服务器，防止应用服务器的 gRPC 客户端发送旧版 Gitaly 不支持的 RPC。

若 Gitaly 独立部署或使用 Gitaly Cluster (Praefect)，请参考零停机升级。

Gitaly 在构建过程中编译并嵌入 Git 二进制文件，需要额外依赖：

# 安装依赖
sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential

# 获取 Gitaly 源码并编译
cd /home/git/gitlab
sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production

更新 GitLab Pages

安装并编译 GitLab Pages：

cd /home/git/gitlab-pages

sudo -u git -H git fetch --all --tags --prune
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

启动 GitLab 和 NGINX

# 使用 systemd 的系统
sudo systemctl start gitlab.target
sudo systemctl restart nginx.service

# 使用 SysV init 的系统
sudo service gitlab start
sudo service nginx restart

检查 GitLab 状态

检查 GitLab 及环境配置：

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production

运行更全面的检查：

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production

所有项目均为绿色即表示升级成功！

故障排除

升级过程中遇到问题可尝试以下步骤：

回滚到上一版本

回滚必须遵循对应版本的升级指南（例如从 16.6 回滚到 16.5 时，按 16.4→16.5 的升级指南操作）。

回滚时：

不应执行数据库迁移指南（备份已回滚到旧版本）。
若运行过数据库迁移，回滚后必须恢复备份。代码版本必须与备份中的数据库模式版本兼容（旧模式在备份中）。

从备份恢复

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production

停止 GitLab

更新 Ruby

更新 Node.js

更新 Go

更新 Git

更新 PostgreSQL

更新 GitLab 代码库

更新配置文件

gitlab.yml 新配置

database.yml 新配置

NGINX 或 Apache 新配置

SMTP 配置

配置 systemd 单元

配置 SysV init 脚本

安装依赖并运行迁移

更新 GitLab Shell

更新 GitLab Workhorse

更新 Gitaly

更新 GitLab Pages

启动 GitLab 和 NGINX

检查 GitLab 状态

故障排除

回滚到上一版本

从备份恢复

`gitlab.yml` 新配置

`database.yml` 新配置