项目管理 之六 详解 Gitlab 本地部署全过程、Gitlab Pages、企业版 PATCH
Gitlab 官方推荐用户安装企业版,因为在不购买许可证时,安装的 Gitlab-ee 就是运行为 Gitlab-ce 版本(付费功能自动隐藏)
gitlab-ee 和 gitlab-ce
需要注意,Gitlab 分为 SaaS 和 Self-Managed 两种版本,其中,SaaS 即 gitlab.com 这个在线版本(这个其实就是官方的 Self-Managed 版本,不过有一些额外的功能);Self-Managed 就是指的我们自己本地部署的版本(本地部署也有额外的功能)。
Gitlab 官网目前提供了 Enterprise Edition 和 Community Edition 两种 Self-Managed 版本,分别对应 linux 系统的软件包 gitlab-ee 和 gitlab-ce。看名字就知道,gitlab-ee 是收费的功能更加丰富的版本。Self-Managed 版本根据用户付费情况的不同,又分为了 Starter、Premiun、Ultimate 三种 PLAN,可以在 https://about.gitlab.com/pricing/feature-comparison/ 查看区别。
Gitlab 官方推荐用户安装企业版,因为在不购买许可证时,安装的 Gitlab-ee 就是运行为 Gitlab-ce 版本(付费功能自动隐藏),方便用户随时升级到企业版。毫无疑问,必须得选择安装 Gitlab-ee 啊!目前最新版是 15.4.0,下面是部署好的后台效果图:
安装
安装方法有很多种,甚至可以选择最原始的从源代码进行安装。针对 Linux 系统 Gitlab 官方提供了很多现成的软件包,安装简单高效,可以在 https://about.gitlab.com/install/ 查看支持的 Linux 发行版。我使用的是 Ubuntu 20.04 LTS 系统(目前,Gitlab 支持 Ubuntu 18.04 LTS 和 Ubuntu 20.04 LTS。Ubuntu 22.04 LTS 版官方正在处理中)。
-
安装依赖工具
sudo apt-get install -y curl openssh-server ca-certificates tzdata perl
。这个没啥可说的,一个命令等待安装完成即可。 -
安装邮件服务器
sudo apt-get install -y postfix
,用来在用户注册之后自动给用户发送一封注册邮件。最新版安装后不用任何配置默认就可以使用。注意如果系统中安装了 mta 框架,则需要卸载(执行上述命令会自动卸载)。
注意,也可以选择其他邮件服务器,等后面安装了 Gitlab 之后再进行配置。Gitlab 也支持配置公共邮箱系统(例如,@gmail.com
、@163.com
),如果直接选择使用公共邮箱系统,则可以不用安装 postfix 等,跳过此步骤即可。安装详情见独立博文 https://itexp.blog.csdn.net/article/details/127105430
-
添加 Gitlab 仓库源:
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash
,这样就可以直接使用apt
来安装 Gitlab 了。
-
直接使用命令
sudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ee
安装 Gitlab。命令执行后,就开始下载 Gitlab 软件包,下载之后,会自动解压(安装目录/opt/gitlab
)解压过程比较长,耐心等待。
初次安装,解压完成之后,会自动进行一系列的配置。整个配置过程时间比较长,耐心等待即可。如果运气好,没有产生错误,我这里就遇到了错误(只要上面没有填写有效的域名,肯定会出错。详见错误处理章节)!- 如果重装,貌似不会自动执行配置,手动执行
sudo gitlab-ctl reconfigure
即可。在此之前,是无法访问的! - 如果重装,数据库等组件是依旧会存在的,所以,重装后的用户账户、仓库等会恢复之前的!
- 命令中的
EXTERNAL_URL="https://gitlab.example.com"
是用于指定安装后 Gitlab 的访问地址。也可以不指定,安装完成后再进行修改,详见配置章节。Gitlab 会根据其中的 https 来决定配置。
- 如果重装,貌似不会自动执行配置,手动执行
-
修改网络访问相关的配置,多数情况下都需要修改防火墙,以下是一些 Ubuntu 防火墙常用命令
sudo ufw status
: 查看防火墙状态sudo ufw enable
: 打开防火墙sudo ufw disable
: 关闭防火墙sudo ufw allow 22/tcp
: 允许所有的外部 IP 访问本机的 22/tcp (ssh)端口sudo ufw allow 9092
: 允许所有的外部 IP 访问本机的自定义 9092 端口sudo ufw delete allow 9092
: 禁用 9092 端口sudo ufw allow from 192.168.1.10
: 允许此IP访问所有的本机端口,即添加到了允许访问列表sudo ufw delete allow from 192.168.1.10
: 从允许访问列表中删除,即禁止此 ip 进行访问
错误处理
我最开安装的时候,最新版是 15.3.3 版本,安装过程出现了如下第一个错误。安装完后,Gitlab 就发布了最新的 15.4.0 ,果断直接升级到了最新版。升级会覆盖 /opt/gitlab
下的文件,配置文件一般不会变动。
-
在安装过程中报错
Error executing action create on resource 'acme_certificate[staging]
。这个问题是不能正常处理 Let’s Encrypt 的 SSL 证书导致的(根据官网说明,在安装时,指定了https
的 URL 后,安装就会自动识别并进行 HTTPS 相关(Let’s Encrypt)配置)。
由于我这里是使用的局域网的 IP,是无法获取到 SSL 证书的。实际此错误并不影响使用 Gitlab。当然我们可以通过编辑 Gitlab 文件sudo nano /opt/gitlab/embedded/cookbooks/letsencrypt/resources/certificate.rb
来屏蔽掉错误提示(如上图所示)。别忘了执行sudo gitlab-ctl reconfigure
重新配置 Gitlab 即可。如果后续升级了 Gitlab,会导致修改被还原,需要再次进行修改
-
默认用户登陆后不能正常显示头像。这个问题是由于 Gitlab 默认使用的头像服务器 gravatar 被墙了(Gitlab 根据用户邮箱自动从 gravatar 获取头像)。可以通过修改 Gitlab 文件
sudo nano /var/opt/gitlab/gitlab-rails/etc/gitlab.yml
中的配置来解决(当然也可以在个人资料里上传本地头像)。修改后gitlab-ctl restart
即可。
注意,如果后续升级了 Gitlab,会导致修改被还原,需要再次进行修改
配置
安装过程的后半段,大部分时间 Gitlab 都在自动执行各种配置。配置文件主要就是 /etc/gitlab/gitlab.rb
,我们可以手动更改。需要注意的是,更改该文件之后,必须重新执行 sudo gitlab-ctl reconfigure
以使修改生效。
我这里仅仅是介绍一些安装之后必须要进行的配置,全部 Gitlab 配置项是相当多的,可自行查看 /etc/gitlab/gitlab.rb
文件,官网 https://docs.gitlab.com/ee/ 也有比较详细的文档可供参考。
Gitlab URL
在上面安装时,指定的域名为 https://gitlab.example.com
,由于我是纯内网使用,这里直接修改为服务器 IP 地址。使用命令 sudo nano /etc/gitlab/gitlab.rb
编辑 external_url
配置项就可以修改访问 Gitlab 的 URL。
- 官方文档:https://docs.gitlab.com/omnibus/settings/configuration.html#configure-the-external-url-for-gitlab
- 官方建议也把 Markdown cache 清理掉。
HTTP 重定向
默认情况下,安装之后只能使用 https 进行访问,如果需要使用 http 访问,则可以通过需要修改 sudo nano /etc/gitlab/gitlab.rb
中的相关配置,开启 http 重定向到 https 来实现。
管理员密码
在默认情况下,Gitlab 会自动创建一个 root 用户,密码将随机生成并存储在 /etc/gitlab/initial_root_password
中。这个密码文件将在 24 小时后自动删除。登录后记得修改密码。也可以直接在服务器上重置密码:
# 登录到 gitlab 控制台
sudo gitlab-rails console -e production
# 选择用户
user=User.where(id:1).first
# 重置密码,保存退出
user.password='12345678'
user.password_confirmation='12345678'
user.save!
exit
在安装时,可以在安装命令 sudo GITLAB_ROOT_PASSWORD="<strongpassword>" EXTERNAL_URL="http://gitlab.example.com" apt install gitlab-ee
中显示指定 root 用户的密码。
PATCH
安装完 Gitlab-ee 之后,默认是运行为 Gitlab-ce 版本,收费功能自动隐藏了。简单进行 PATCH 一下就可以使用完整的 Gitlab-ee 功能。注意,我这里仅仅是为了验证功能,请务必尊重版权,到官网购买订阅。
-
安装
sudo apt install ruby
。注意,必须是 2.3 及以上版本。 -
sudo gem install gitlab-license
-
使用命令
sudo nano license.rb
新建一个 Keygen 源码文件,然后输入以下内容(注意,根据需要修改其中的license.xx
字段的内容)require "openssl" require "gitlab/license" key_pair = OpenSSL::PKey::RSA.generate(2048) File.open("license_key", "w") { |f| f.write(key_pair.to_pem) } public_key = key_pair.public_key File.open("license_key.pub", "w") { |f| f.write(public_key.to_pem) } private_key = OpenSSL::PKey::RSA.new File.read("license_key") Gitlab::License.encryption_key = private_key license = Gitlab::License.new license.licensee = { # 注册信息 "Name" => "none", "Company" => "none", "Email" => "example@test.com", } license.starts_at = Date.new(2020, 1, 1) # 开始时间 license.expires_at = Date.new(2050, 1, 1) # 结束时间 license.notify_admins_at = Date.new(2049, 12, 1) license.notify_users_at = Date.new(2049, 12, 1) license.block_changes_at = Date.new(2050, 1, 1) license.restrictions = { active_user_count: 10000, } puts "License:" puts license data = license.export puts "Exported license:" puts data File.open("GitLabBV.gitlab-license", "w") { |f| f.write(data) } public_key = OpenSSL::PKey::RSA.new File.read("license_key.pub") Gitlab::License.encryption_key = public_key data = File.read("GitLabBV.gitlab-license") $license = Gitlab::License.import(data) puts "Imported license:" puts $license unless $license raise "The license is invalid." end if $license.restricted?(:active_user_count) active_user_count = 10000 if active_user_count > $license.restrictions[:active_user_count] raise "The active user count exceeds the allowed amount!" end end if $license.notify_admins? puts "The license is due to expire on #{$license.expires_at}." end if $license.notify_users? puts "The license is due to expire on #{$license.expires_at}." end module Gitlab class GitAccess def check(cmd, changes = nil) if $license.block_changes? return build_status_object(false, "License expired") end end end end puts "This instance of GitLab Enterprise Edition is licensed to:" $license.licensee.each do |key, value| puts "#{key}: #{value}" end if $license.expired? puts "The license expired on #{$license.expires_at}" elsif $license.will_expire? puts "The license will expire on #{$license.expires_at}" else puts "The license will never expire." end
-
执行命令
ruby license.rb
会生成GitLabBV.gitlab-license
、license_key.pub
、license_key
这三个文件。其中的GitLabBV.gitlab-license
就是许可证。
-
使用
license_key.pub
替换/opt/gitlab/embedded/service/gitlab-rails/.license_encryption_key.pub
。替换命令:sudo mv license_key.pub /opt/gitlab/embedded/service/gitlab-rails/.license_encryption_key.pub
。这俩都是文本文件,也可以打开直接替换内容。
如果后续升级了 Gitlab,会导致/opt/gitlab/embedded/service/gitlab-rails/.license_encryption_key.pub
被还原,因此需要重新执行该步骤(之前导入过的许可证不用再次导入)! -
使用命令
sudo gitlab-ctl restart
重启 Gitlab,否则在导入许可证时会提示许可证无效,而无法导入我们上面生成的许可证。 -
以 Gitlab 创建的 root 用户登陆本地安装的 Gitlab,然后将
GitLabBV.gitlab-license
导入到 Gitlab 中。这一步需要注意,不同的 Gitlab 版本,导入位置不一样。- 早期版:直接浏览器访问
http://你的 IP/admin/license
,页面上有导入按钮 - 14.x:Menu ➔ Admin ➔ Subscription ➔ 许可证上传
- 15.x:Menu ➔ Admin ➔ Settings ➔ General ➔ Add License ➔ Expand ➔ 选择我们的
GitLabBV.gitlab-license
然后上传
成功导入之后就可以在订阅中看到激活信息了。详细说明见 Gitlab 官方文档:https://你的 IP/help/user/admin_area/license_file.md
注意,在导入时可能报 502 错误,多试几次吧,会有奇迹!
- 早期版:直接浏览器访问
-
更改 Gitlab 版本。激活后默认订阅版本的是
Starter
,这里我们修改为无限版。执行命令sudo nano /opt/gitlab/embedded/service/gitlab-rails/ee/app/models/license.rb
,然后修改如下部分的内容:
保存后,执行命令sudo gitlab-ctl restart
重启 Gitlab,再次查看如下:
使用
使用命令 sudo gitlab-ctl status
可以查看 Gitlab 的运行情况状态。Gitlab 正常运行后,就可以直接在浏览器中访问 Gitlab 了。注意,默认情况下,由于没有有效的 SSL 证书, https 访问时浏览器会报 Not Secure!
后续就是 Gitlab 的使用了。唯一需要注意的就是,管理员会比普通用户多个菜单项,其中可以对 Gitlab 进行配置。想要完整体验 Gitlab,还需要管理员进行一些列 Gitlab 内部的配置。
例如,在默认情况下,新用户注册后必须要管理员审批后才可以进行登陆。在 Gitlab 管理后台,管理员可以在以下页面中关闭必须要管理员同意的设置(去掉选定即可)。
GitLab Runner
GitLab Runner 是一个开源项目,用于运行您的作业并将结果发送回 GitLab,主要作用是用于监视相关项目的变动,然后可以自动拉取对应的分支进行自动构建,测试,和部署。它与 GitLab CI 一起使用,GitLab CI 是 GitLab 随附的开源持续集成服务,用于协调作业。
- GitLab Runner 的三种类型
- shared:运行整个平台(gitlab)的项目的作业
- group:运行特定 group下的所有项目的作业
- specific:运行指定的 Project 的作业
- GitLab Runner 两种状态
- locked:无法运行项目作业
- paused:不会运行作业
GitLab Runner 的安装主要就是两种方式,第一个是 Gitlab 官方提提供了针对不同 Linux 发行版的软件仓库源,把仓库源添加到 Ubuntu 中,就可以使用 apt 安装了;第二种就是手动下载二进制文件,使用 dpkg
来安装。
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner
- Ubuntu 自己的软件仓库中也有 GitLab Runner,但是版本比较旧了,不建议使用!
- 官方文档 https://docs.gitlab.com/runner/install/linux-repository.html
安装好了 GitLab Runner 以后,需要将 Runner 注册到部署的 Gitlab 上,这样 Gitlab 才能知道有多少管理的 Runner,同时 Runner 也能根据 CI/CD 里的配置(具体什么配置会在.gitlab-ci.yaml文件里讲到)来选择自己对应的任务去执行。
注意,如果重装或者说迁移了 Gitlab,则该页面会报 500 错误,Gitlab 提供了如下文档 Back up and restore GitLab,其中包含直接从数据库中重置各种数据。如果使用了无效,也可以直接使用如下的解决方法如下
# 时间比较长,耐心等待
sudo gitlab-rails console
# 输入如下内容会打印很多东西(注意该操作不能使用 SSH 远程处理,会导致后续无法继续输入)
> ApplicationSetting.first.delete
# 再输入如下内容会打印下面的 => nill
> ApplicationSetting.first
=> nill
# 退出
exit
管理员可以在后台部署一个共享的 Runner,供整个 Gitlab 用户使用。直接登陆管理员账号,如下,Gitlab 已经为我们准备好了相关命令。然而,当我执行如下的命令时,收到了如下的错误。搜了一下,有人说是英文 Go 1.15 版本开始废弃 CommonName,因此推荐使用 SAN 证书。
那我们就重新创建 SSL 证书。Gitlab 使用的 SSL 证书就位于 /etc/gitlab/ssl
目录下,那就直接使用 OpenSSL 重新生成一个使用了 SAN 字段的 SSL 证书。具体方法不多说,直接来个 bash 脚本。
cd /etc/gitlab/ssl
sudo nano ssl.sh
,然后填写以下内容
关于 CA 证书的签发详细过程,可以参考我的另一篇博文 Network 之九 对称加密、非对称加密、HASH、CA 证书签发及使用流程#!/bin/bash # Generate the openssl configuration files. echo "创建openssl.cnf------------------->" cat > openssl.cnf << EOF [req] distinguished_name = req_distinguished_name req_extensions = v3_req [req_distinguished_name] countryName = Country Name (2 letter code) countryName_default = CN stateOrProvinceName = State or Province Name (full name) stateOrProvinceName_default = SD localityName = Locality Name (eg, city) localityName_default = JN organizationalUnitName = Organizational Unit Name (eg, section) organizationalUnitName_default = ZCS commonName = ZCS commonName_default = ZCS commonName_max = 64 [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:TRUE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectAltName = @alt_names [alt_names] IP.1 = 192.168.200.33 IP.2 = 127.0.0.1 EOF echo "创建 v3.ext------------------->" cat > v3.ext << EOF authorityKeyIdentifier=keyid,issuer basicConstraints=CA:FALSE keyUsage=digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment subjectAltName=@alt_names [alt_names] IP.1 = 192.168.200.33 IP.2 = 127.0.0.1 EOF echo "创建 CA 根证书------------------------->" echo "创建私钥 ca.key" openssl genrsa -out ca.key 2048 echo "创建 CA 证书 ca.crt" openssl req -new -x509 -days 3650 -key ca.key -out ca.crt echo "生成服务器证书----------------->" echo "创建私钥 192.168.200.33.key" openssl genrsa -out 192.168.200.33.key 2048 echo "创建服务器证书请求文件 192.168.200.33.csr" openssl req -new -key 192.168.200.33.key -out 192.168.200.33.csr -config openssl.cnf echo "创建服务器证书 192.168.200.33.crt" openssl x509 -days 3650 -req -sha256 -extfile v3.ext -CA ca.crt -CAkey ca.key -CAcreateserial -in 192.168.200.33.csr -out 192.168.200.33.crt echo "创建pem------------------------>" cat 192.168.200.33.crt 192.168.200.33.key > 192.168.200.33.pem
sudo chmod u+x ssl.sh
sudo ./ssl.sh
sudo gitlab-ctl restart
。必须重启 Gitlab,否则上面的修改不生效!
然而,重新运行 sudo gitlab-runner register --url https://192.168.200.33/ --registration-token iDJ7UJLyxobQuynTewTz
依旧没有啥卵用。。。又经过一番 Google,最终找到了如下方法(必须手动指定证书):
sudo gitlab-runner register \
--non-interactive \
--tls-ca-file=/etc/gitlab/ssl/192.168.200.33.crt \
--url "https://192.168.200.33/" \
--registration-token "qJyTS7_oPer8PJKYP_2h" \
--executor "shell" \
--description "t340-runner" \
--tag-list "t340-runner" \
--run-untagged \
--locked="false"
执行以上命令之后,在 Runner 界面就可以看到我们的配置了。注意,其中的各个参数(主要是 --executor
和 --tag-list
)的详细说明,参见官网即可。
Gitlab-runner 的仓库中有人提问了这个问题 https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28841,有人说可以直接使用 Gitlab 的 API: curl --request POST -k "https://192.168.200.33//api/v4/runners" --form "token=iDJ7UJLyxobQuynTewTz" --form "description=shared-runner" --form "tag_list=shared-runner"
。经过我验证,这样也是不行的!
Gitlab Pages
在默认安装后,Gitlab Pages 是没有启用的。因此,首先需要通过 sudo nano /etc/gitlab/gitlab.rb
修改配置项启用 Gitlab Pages(修改内容如下所示)。修改之后, 需要使用 sudo gitlab-ctl reconfigure
,以使修改生效。
这里的 pages_external_url
,配置的是 Pages 使用的域名。如果你没有域名,就先随便写个主机名什么的。之后我们可能通过配置 Nginx 来解决。注意,我这里试验的是直接写 IP 导致无法正常访问 Gitlab!
访问 Pages 页面
在默认配置下,Gitlab Pages 的访问时 http://gitlab用户名.域名/工程名
,但是局域网下,只有 IP,没有域名,这就导致了无法正常访问 Gitlab Pages 页面。目前唯一可行的解决方法就是修改 Gitlab 内置到的 NGINX。
- Pages部署目录:
/var/opt/gitlab/gitlab-rails/shared/pages
- 内置的 Nginx 目录:
/var/opt/gitlab/nginx
。直接修改其中的conf/gitlab-pages.conf
会引起权限问题,只能以 root 用户去修改!还有一种变通方法,Gitlab 的配置支持自定义这个配置文件的路径。- 切换 root 用户,然后
cp /var/opt/gitlab/nginx/conf/gitlab-pages.conf /etc/gitlab/gitlab-pages.conf
,然后nano /etc/gitlab/gitlab-pages.conf
,编辑内容如下:
修改之后,# This file is managed by gitlab-ctl. Manual changes will be # erased! To change the contents below, edit /etc/gitlab/gitlab.rb # and run `sudo gitlab-ctl reconfigure`. ## Lines starting with two hashes (##) are comments with information. ## Lines starting with one hash (#) are configuration parameters that can be uncommented. ## ################################### ## configuration ## ################################### server { listen *:8000; server_name ~^(?<group>.*)\.192\.168\.200\.33$; server_tokens off; ## Don't show the nginx version number, a security best practice ## Disable symlink traversal disable_symlinks on; ## Real IP Module Config ## http://nginx.org/en/docs/http/ngx_http_realip_module.html ## HSTS Config ## https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/ add_header Strict-Transport-Security "max-age=63072000"; ## Individual nginx logs for this GitLab vhost access_log /var/log/gitlab/nginx/gitlab_pages_access.log gitlab_access; error_log /var/log/gitlab/nginx/gitlab_pages_error.log error; # Pass everything to pages daemon location / { # proxy_set_header Host $http_host; # proxy_set_header X-Real-IP $remote_addr; # proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # proxy_set_header X-Forwarded-Proto http; # Prevent NGINX from caching pages in response to the pages `Cache-Control` # header. # # Browsers already respect this directive and Pages can handle the request # volume without help from NGINX. # # If this changes in the future, ensure `proxy_cache_key` is set to a value # like `$scheme$host$request_uri`, as the default value does not take the # Pages hostname into account, leading to incorrect responses being served. # # See https://gitlab.com/gitlab-org/gitlab-pages/issues/73 # proxy_cache off; # proxy_pass http://localhost:8090; # 这里指向 Gitlab Pages 的部署路径 root /var/opt/gitlab/gitlab-rails/shared/pages; index index.html; } # Define custom error pages error_page 403 /403.html; error_page 404 /404.html; }
gitlab-ctl restart nginx
重启 Nginx,此时就可以退出 Root 权限了 sudo nano /etc/gitlab/gitlab.rb
,修改如下内容nginx['custom_nginx_config'] = "include /etc/gitlab/gitlab-pages.conf;"
,然后sudo gitlab-ctl reconfigure
- 然后就可以使用
http://上面配置的 pages_external_url/gitlab帐号/工程名/public/
- 切换 root 用户,然后
参考
- https://about.gitlab.com/install/#ubuntu
- https://www.rubydoc.info/gems/gitlab-license/1.0.0/file/README.md
- https://gitlab.com/gitlab-org/gitlab/-/issues/38255
- https://linuxhint.com/install-gitlab-ubuntu-22-04/
- http://www.javashuo.com/article/p-gcxxgulc-ht.html
- https://blog.csdn.net/weixin_43939952/article/details/120850782
- https://gitlab.com/gitlab-org/gitlab/-/issues/14263
开放原子开发者工作坊旨在鼓励更多人参与开源活动,与志同道合的开发者们相互交流开发经验、分享开发心得、获取前沿技术趋势。工作坊有多种形式的开发者活动,如meetup、训练营等,主打技术交流,干货满满,真诚地邀请各位开发者共同参与!
更多推荐
所有评论(0)