gitlab安装升级及迁移

发表于 更新于 分类于 ， ， 阅读次数： 本文字数： 8k 阅读时长 ≈ 7 分钟

1. gitlab简介

GitLab 是一个用于仓库管理系统的开源项目，使用Git作为代码管理工具，并在此基础上搭建起来的Web服务。
GitLab是由GitLabInc.开发，使用MIT许可证的基于网络的Git仓库管理工具，且具有wiki和issue跟踪功能。使用Git作为代码管理工具，并在此基础上搭建起来的web服务。
GitLab由乌克兰程序员DmitriyZaporozhets和ValerySizov开发，它使用Ruby语言写成。后来，一些部分用Go语言重写。截止2018年5月，该公司约有290名团队成员，以及2000多名开源贡献者。GitLab被IBM，Sony，JülichResearchCenter，NASA，Alibaba，Invincea，O’ReillyMedia，Leibniz-Rechenzentrum(LRZ)，CERN，SpaceX等组织使用。

2. 安装环境介绍

服务器的操作系统为CentOS Linux release 7.9.2009
包管理工具yum.
这里安装的是gitlab企业版，本教程可以作为社区版安装的参考资料，社区版安装稍有不同，在了解社区版的差异后，安装步骤稍作调整．

3. gitlab 安装

gitlab的安装方式有很多种，比如docker镜像安装，Helm charts安装，源代码安装，GET(GitLab Environment Toolkit)安装, 本文主要讲述使用ceontos或redhat系列中通过yum安装使用rpm包安装．安装前需要对yum和rpm命令有一定的了解．

4. 系统要求

空闲硬盘空间：　2.5G+
CPU: 4core+ (4核最多支持500用户，8核最多支持1000用户)
内存：4GB+

4.1. 安装准备工作

  • 更新yum源
    这里采用南京大学镜像(主要处于下载速度考虑)，如果你访问外网的速度够快, 可以考虑使用官方镜像．
    将下面一段代码拷贝到/etc/yum.repos.d, 命名为gitlab_gitlab-ee.repo, 当然你也可以根据自己的喜好命名，只要文件后缀为.repo即可，符合yum源文件命名规范即可

    1
    2
    3
    4
    5
    [gitlab_gitlab-ee]
     name=Gitlab EE Repository
     baseurl=https://mirrors.nju.edu.cn/gitlab-ee/yum/el$releasever/
     gpgcheck=0
     enabled=1

  • 更新yum缓存，以便快速查询，确保缓存中有最新安装包信息

    1
    yum makecache

4.2. 开始安装gitlab

  • 开始安装前可以使用yum命令查看有哪些可用的版本，以及当前最新版本是哪个．

    1
    yum list gitlab-ee --showduplicates | sort -r

    通过以上命令，确定当前列表中包含最新版本，如果列表中最新版本不是最新的，可能需要执行yum makecache 更新缓存，或者yum源本身就不包含最新版本，那么要考虑更换yum源．如果要安装指定版本，需要确保需要安装的版本包含在列表中．

  • 安装最新版本的方法

    1
    yum install -y gitlab-ee

  • 安装特定版本的方法
    以centos7为例, 后面的版本号x.y.z-ee.0.el7根据实际情况进行替换．

    1
    yum install -y gitlab-ee-x.y.z-ee.0.el7

  • 配置gitlab
    安装完成后执行以下命令gitlab将会自动帮我们完成一些必要的配置，切记如果你手动完成一些配置后不要重复执行以下命令，否则手动配置的参数会被清除，严重时会导致用户访问时出现http 500错误．

    修改external_url
    编辑文件/etc/gitlab/gitlab.rb

    1
    2
    3
    #replace gitlab.example.com with your domain or your ip
    # for instance external_url 'http://192.168.1.100'
    external_url 'your_domain'
    1
    gitlab-ctl reconfigure

  • 启动gitlab

    gitlab默认运行在80端口
    需要检查防火墙状态, 如何防火墙已开启, 需要放行80端口

    1
    2
    3
    4
    5
    6
    # 检查防火墙是否开启
    sudo firewall-cmd --state

    # 如果开启, 需放行80端口
    sudo firewall-cmd --add-port=80/tcp --permanent
    sudo firewall-cmd --reload

    如果一切顺利，我们就可以启动gitlab了，启动命令为

    1
    gitlab-ctl start

    启动成功后, 可以使用浏览器访问gitlab web页面，默认端口是80, 所以可以打开http://your_server_address访问．

    如果没有设置密码，系统将为root用户生成一个随机密码，该随机密码可以在/etc/gitlab/initial_root_password文件中找到．
    建议修改该随机密码，方式为

    1
    gitlab-rake "gitlab:password:reset[root]"

    参数说明: 命令中的root即为root用户，该命令也可以用来为其他用户设置密码．

    关于gitlab的高级配置，可以参考gitlab的官网

    如果要配置gitlab ci/cd还需要安装gitlab-runner, gitlab-runner的安装和配置可以参考我的博客gitlab-runner安装与配置, 更多关于gitlab的文章请访问gitlab合集

    这里补充几点如何启动，关闭，查看gitlab状态的命令，方便troubleshooting
    关闭gitlab

    1
    gitlab-ctl stop

    重启gitlab

    1
    gitlab-ctl restart

    查看gitlab状态

    1
    gitlab-ctl status

    查看gitlab滚动日志

    1
    gitlab-ctl tail

    想了解更多命令，可以查看帮助

    1
    gitlab-ctl --help

    命令行查看gitlab版本

    1
    cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

    查看日志文件

    日志文件位于/var/log/gitlab下, 日志是按照服务分类存放

    Gitlab 日志文件位于 /var/log/gitlab/gitlab-rails/production.log

5. gitlab升级

Gitlab的更新速度还是挺快的, 每隔一个月就会发布一个release. 如果要使用一些新特性或修补一些安全漏洞, 掌握升级技巧是必不可少的. 这里个人建议收藏文档, 原文在文章末尾有链接地址, 以备升级时使用, 知道系统是如何安装的, 又该如何升级. 原文实时更新, 踩过的坑都会记录下来.

更多关于Gitlab的release政策, 请参考gitlab官方文档GitLab release and maintenance policy

5.1. 升级前备份

  • 备份数据
1
gitlab-rake gitlab:backup:create
  • 备份敏感数据

手动备份两个具有敏感数据的文件

1
2
3
4
cp  /etc/gitlab/gitlab.rb  /var/opt/gitlab/backups
# and
cp  /etc/gitlab/gitlab-secrets.json  /var/opt/gitlab/backups

说明：

  • 备份被保存在/var/opt/gitlab/backups目录下
  • 备份文件名格式如下: 例如1665044212_2022_10_06_14.4.1-ee_gitlab_backup.tar, 命名规则为:备份编号+日期+gitlab版本号+后缀
  • 备份恢复的原则是对应版本的备份文件只能使用对应版本的gitlab程序进行恢复
  • 跨版本恢复备份文件会出现恢复失败或未知错误
  • 如果要在高版本中使用低版本的备份文件
    • 方法一: 在另一台机中 安装低版本gitlab 将低版本的备份程序采用低版本的gitlab恢复后再将低版本的gitlab升级到高版本, 再使用高版本的gitlab制作备份文件

5.2. 开启yum缓存

  • gitlab的每个安装包都接近1G大小，gitlab升级过程中可能需要反复恢复重试，如果不开启yum缓存，即每次执行yum install无论成功与否，安装包都会被清理掉，下次重试即使是相同的版本也会去服务器上重新下载，会特别慢，而且消耗服务器带宽，如果触发了镜像服务器的限流机制，升级可能会无法进行下去.

  • 强烈建议开启yum缓存，等升级完成后再关闭缓存并手动清理 /var/cache/yum/x86_64/7/gitlab_gitlab-ee下的缓存．

  • 开启yum 缓存步骤如下: 修改/etc/yum.conf, 将keepcache设置为1, 默认为0.
    这样当再次重试相同版本时就可以使用-C 参数使用缓存(详细使用方法参考”开始升级章节”)，而不必去镜像服务器上重新下载．

/etc/yum.conf

1
2
3
4
5
6
7
8
9
10
11

[main]
cachedir=/var/cache/yum/$basearch/$releasever
keepcache=1　# 开启缓存, 1表示开启缓存, 0表示关闭缓存
debuglevel=2
logfile=/var/log/yum.log
exactarch=1
obsoletes=1
gpgcheck=1
plugins=0

5.3. 开始升级

  • 升级前需要了解升级路径，gitlab不能一次性从低版本升级到最新版，需要升级到必要的中间版本，然后一步步升级到最新版本．主要涉及到版本之间的数据的迁移(data migration)工作，所以必须经过其中关键的版本升级，才能顺利完成数据更新操作．
    升级路径可以参考官网 - Upgrade paths, 这里简要列举路径如下

8.11.Z -> 8.12.0 -> 8.17.7 -> 9.0.13 -> 9.5.10 -> 10.0.7 -> 10.8.7-> 11.0.6 -> 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 -> 15.0.5 -> 15.1.6 (for GitLab instances with multiple web nodes) -> 15.4.6 -> 15.11.13 ->
(only instances with lots of users or large pipeline variables history) > 16.1 (instances with NPM packages in their package registry) > 16.2.x (only instances with large pipeline variables history) > 16.3 > latest 16.Y.Z.

  • 首先确定gitlab版本信息, 然后再选择合适的升级路径
    1
    2
    3
    4
    5
    6
    7
    gitlab-rake gitlab:env:info

    # 例如
    GitLab information
    Version:        14.4.1-ee
    Revision:       abc23a14bac

gitlab-rake中Rake并不是单词Rake的意思, 它实际上是Ruby Make的简写形式, 是ruby种类似make的一种程序. 使用Rake可以做一些通用的管理和运维任务.

  • 升级前关闭gitlab的部分服务

    1
    2
    3
    4
    5
      
    gitlab-ctl stop unicorn
    gitlab-ctl stop sidekiq
    gitlab-ctl stop nginx

  • 升级命令

    升级命令和安装命令是一样的, 将x.y.z-ee.0.el7替换成关键中间版本

    1
    yum update -y -C gitlab-ee-x.y.z-ee.0.el7

    -C 参数使用缓存, 详细解释参考”开启yum缓存”

    升级完成后，
    需要重新运行配置,否则启动会失败

    1
    gitlab-ctl reconfigure

    如果有手动配置，需要重做一遍．

    需要启动gitlab,等待数据迁移任务完成，然后再备份，再次进行下一个版本的升级．

    如果遇到严重问题，需要回退到上一个版本，导入备份，解决问题后继续往后升级，所以备份数据很重要．

    备份恢复命令如下：
    其中636041545_2021_11_04_12.10.14为备份文件的名字，不包含文件名后缀．

    1
    gitlab-rake gitlab:backup:restore BACKUP=1636041545_2021_11_04_12.10.14

  • 每个版本升级完成后，要启动gitlab等待数据迁移完成
    查看数据迁移任务，有两种查看方式，可以通过web界面查看，也可以通过命令行来查看．

    • web界面查看方式
      查看迁移任务的状态，打开web界面:
      在页面顶部, 选择 Menu > Admin.
      在页面左侧边栏，选择Monitoring > Background Migrations.

    • 命令行查看方式

      1
      gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'

6. gitlab迁移

  • 有时我们需要将gitlab迁移到新的性能更好的服务器．怎么进行迁移呢？当然方法很多，这里介绍其中的一种方式，即通过先备份，然后在新的服务器上进行还原操作．

  • 说明: gitlab还原有一点需要注意，那就是备份文件只能是在与创建备份的gitlab版本相同的gitlab上才能恢复，备份文件的后八位即是创建该备份的gitlab的版本，该版本只能在这种版本下进行还原．

6.1. 备份数据

1
gitlab-rake gitlab:backup:create
  • 备份文件默认(如果没有修改默认配置的情况下)保存在/var/opt/gitlab/backups目录下面．

6.2. 在新服务器上安装gitlab

  • 可以参考本文的安装部分进行安装

6.3. 还原备份

  • 将备份文件拷贝到新服务器的/var/opt/gitlab/backups目录下，执行恢复命令．备份文件参数，根据自己的实际情况进行修改．

    首先要将旧服务器上的两个文件/etc/gitlab/gitlab.rb,/etc/gitlab/gitlab-secrets.json拷贝到新服务器, 否则后续会发现一些奇怪的问题.

    并将/etc/gitlab/gitlab.rb 的external_url设置为正确的url

    然后执行gitlab-ctl reconfigure

    1
    gitlab-rake gitlab:backup:restore BACKUP=1636041545_2021_11_04_12.10.14

    如果还原失败, 请先参考问题排查章节, 再在到网上查找解决办法.

7. 如何彻底卸载gitlab?

  • 警告: 注意标题上彻底二字，在你不清楚卸载意味着会发生什么的时候，请不要执行以下任何步骤．

7.1. 卸载前备份

  • 卸载前执行一次备份，备份存放位置为/var/opt/gitlab/backups, 因为后续该目录也会被清除，所以请将备份拷贝到一个安全的位置，因为后续动作可能会永久的删除数据，以便后续发生问题或反悔的时候，可以从备份恢复数据．

  • 备份数据

    1
    gitlab-rake gitlab:backup:create

  • 备份敏感数据

    手动备份两个具有敏感数据的文件

    1
    2
    3
    4
    cp  /etc/gitlab/gitlab.rb  /var/opt/gitlab/backups
    # and
    cp  /etc/gitlab/gitlab-secrets.json  /var/opt/gitlab/backups

7.2. 执行卸载

  • 关闭gitlab

    1
    2
    3
    4
    #关闭gtilab
    gitlab-ctl stop
    #查看gitlab状态，确保已经关闭
    gitlab-ctl status

  • 卸载应用程序

    1
    rpm -e gitlab-ee

  • 删除数据残留
    首先确认有哪些数据残留

    1
    find / -name gitlab

    如果都是期望被删除的，那么开始执行删除操作，再次提醒将备份拷贝一份到安全位置．

    1
    2
    3
    4
    # 首先使用find命令查看一下有哪些数据残留
    find / -name gitlab 
    # 确定以上文件可以删除后使用删除命令进行删除
    find / -name gitlab | xargs rm -rf

8. 问题排查

  • 问题 1:

    从一台机迁移到另外一台机时报如下错错误

    1
    2
    3
    4
    5
    6

    Restoring PostgreSQL database gitlabhq_production ... ERROR:  must be owner of extension pg_trgm
    ERROR:  must be owner of extension btree_gist
    ERROR:  must be owner of extension btree_gist
    ERROR:  must be owner of extension pg_trgm

    解决办法:

    修改postgresql配置, 能从本地连接到postgresql

    1
    2
    3
    4
    5
    6
    $ vim /var/opt/gitlab/postgresql/data/postgresql.conf
    listen_addresses = '*'
    # 最下面新增两行
    $ vim /var/opt/gitlab/postgresql/data/pg_hba.conf
    local   all         all                               trust
    host    all         all                               127.0.0.1/32 trust

    重启gitlab使得配置生效

    1
    2
    3

    gitlab-ctl restart

    修改gitlab账号为超级用户

    1
    2
    3
    4
    5
    6
    7
    8
    $ su - gitlab-psql
    $ /opt/gitlab/embedded/bin/psql -h 127.0.0.1 gitlabhq_production
    psql (9.2.8)
    Type "help" for help.

    gitlabhq_production=# ALTER USER gitlab WITH SUPERUSER;
    ALTER ROLE
    gitlabhq_production=# \q

    修改完gitlab用户权限后, 记得将postgresql的配置文件改回去

    1. 保证安全性, 防止误操作
    2. 以免后续安装postgresql数据库是参数端口冲突

    参考文档: https://www.jianshu.com/p/09a2b0c25ecd

  • 问题 2:

    解决Gitlab迁移后，项目的 CI/ CD页面报500错误

    原因是: gitlab默认的备份机制，是不会备份gitlab.rb和gitlab-secrets.json文件的,
    如果这两文件还存在则将其拷贝到新的服务器, 如果不存在则将secrets 清除重设
    参考: https://www.jianshu.com/p/c46aa8c8539c

9. 关联阅读

gitlab安装升级及迁移

使用gitlab issue board的四种方式

GitLab集成PlantUML

gitlab-runner安装与配置

fedora上安装gitlab-runner安装与配置

macOS上安装gitlab-runner安装与配置

ubuntu上安装gitlab-runner安装与配置

windows上安装gitlab-runner

gitlab CICD基础