本教程适用于以下操作系统版本
- Ubuntu 22.04 (Jammy Jellyfish)
- Ubuntu 20.04 (Focal Fossa)
- Ubuntu 18.04 (Bionic Beaver)
本页内容
- 先决条件
- 第 1 步 - 配置防火墙
- 第 2 步 - 安装依赖
- 第 3 步 - 更改系统 SSH 端口
- 第 4 步 - 安装 Docker 和 Docker Compose
- 第 5 步 - 设置 Docker 卷
- 第 6 步 - 使用 Docker Compose 安装 Gitlab
- 第 7 步 - 配置 Gitlab 访问 Gitlab 限制公开注册 配置 Gitlab 个人资料 修改 Root 密码 修改用户名 禁用 Prometheus 指标并提升隐私
- 第 8 步 - 创建你的第一个项目 添加 SSH 密钥 创建项目
- 第 9 步 - 管理 Gitlab 容器
- 第 10 步 - 备份 Gitlab
- 第 11 步 - 恢复 Gitlab
- 第 12 步 - 升级 Gitlab
- 结语
- 访问 Gitlab
- 限制公开注册
- 配置 Gitlab 个人资料
- 修改 Root 密码
- 修改用户名
- 禁用 Prometheus 指标并提升隐私
- 添加 SSH 密钥
- 创建项目
Gitlab Server 是云托管 Gitlab 版本控制系统的开源版本。与云托管相比,自托管代码仓库的优势在于可以完全掌控自己的代码。
本指南将教你如何在 Ubuntu 22.04 服务器上使用 Docker 安装 Gitlab Server。Gitlab Server 提供两个版本——免费的 Community edition 和付费的 Enterprise edition。我们将安装 Community edition。如果你需要更多功能,可以轻松升级到 Enterprise edition。
先决条件
- 一台运行 Ubuntu 22.04 的服务器。
- 一个具有 sudo 权限的非 root 用户。
- 已启用并运行 Uncomplicated Firewall(UFW)。
- 一个指向该服务器的完全限定域名 (FQDN),例如 gitlab.example.com。
- 系统已全部更新。$ sudo apt update && sudo apt upgrade
一台运行 Ubuntu 22.04 的服务器。
一个具有 sudo 权限的非 root 用户。
已启用并运行 Uncomplicated Firewall(UFW)。
一个指向该服务器的完全限定域名 (FQDN),例如 gitlab.example.com。
系统已全部更新。
$ sudo apt update && sudo apt upgrade
第 1 步 - 配置防火墙
安装任何软件包之前,第一步是配置防火墙以允许 HTTP 和 HTTPS 连接。
检查防火墙状态。
$ sudo ufw status
你应看到类似下面的输出。
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
放行 HTTP 和 HTTPS 端口。
$ sudo ufw allow http
$ sudo ufw allow https
开放 587 端口用于通过 SMTP 接收邮件。你的 SMTP 邮件服务可能使用不同的端口。
$ sudo ufw allow http
$ sudo ufw allow 587
再次检查状态以确认。
$ sudo ufw status
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
80/tcp ALLOW Anywhere
443 ALLOW Anywhere
587 ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
80/tcp (v6) ALLOW Anywhere (v6)
443 (v6) ALLOW Anywhere (v6)
587 (v6) ALLOW Anywhere (v6)
第 2 步 - 安装依赖
在安装 Gitlab 之前,我们需要安装本教程过程中会用到的一些软件包。
$ sudo apt install ca-certificates curl openssh-server apt-transport-https gnupg lsb-release -y
其中部分软件包可能已预装在你的系统上。
第 3 步 - 更改系统 SSH 端口
Gitlab 使用默认的 SSH 端口,这会与系统的 SSH 端口冲突。为达到最佳效果,最好更改系统的默认端口。
为此,打开 /etc/ssh/sshd_config 文件进行编辑。
$ sudo nano /etc/ssh/sshd_config
找到下面这一行,去掉前面的井号(#),并把值从 22 改为你选择的任意其他值。本教程中我们选择 2425,即将
#Port 22
改为
Port 2425
按 Ctrl + X,并在提示时输入 Y 来保存文件。
重启 SSH 服务。
$ sudo systemctl restart sshd
在防火墙中开放 2425 端口。
$ sudo ufw allow 2425
关闭当前的 SSH 会话,并使用新端口重新登录。
$ ssh username@<serverIP> -p 2425
第 4 步 - 安装 Docker 和 Docker Compose
添加 Docker 官方 GPG 密钥。
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg
运行以下命令添加 Docker 仓库。
$ echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
更新系统以纳入 Docker 仓库。
$ sudo apt update
安装 Docker。
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
本教程将使用 Docker Compose v2 插件,而非旧版的独立二进制文件。因此,运行它的命令已从 docker-compose 变为 docker compose,本文中也据此体现。
Docker 以提权方式运行,因此你需要频繁使用 sudo 来执行命令。更好的做法是把你的 Linux 用户账户加入 docker 用户组。
$ sudo usermod -aG docker ${USER}
${USER} 变量会获取当前登录的系统账户。如果当前登录的账户不是你想授予权限的用户,请把 ${USER} 替换为该用户名。
要使新的组成员身份生效,请退出服务器后重新登录,或使用以下命令。系统会提示输入该用户的密码。
$ su - $(USER)
第 5 步 - 设置 Docker 卷
在继续安装之前,我们需要设定 Gitlab 数据与配置的位置,以便通过 Docker 卷访问。
创建 Docker 卷目录。
$ sudo mkdir /srv/gitlab -p
为 Docker compose 文件创建一个目录。
$ mkdir ~/gitlab-docker
切换到该目录。
$ cd ~/gitlab-docker
创建一个环境变量文件并打开编辑。
$ nano .env
粘贴以下代码来定义 $GITLAB_HOME 变量。
GITLAB_HOME=/srv/gitlab
Gitlab 容器使用主机挂载卷来存储持久化数据。下表展示了 Gitlab 各目录在主机上的本地位置与容器内位置之间的映射关系及各自用途。
第 6 步 - 使用 Docker Compose 安装 Gitlab
确保你位于 Gitlab 的 Docker compose 目录中。
创建并打开 Docker compose 配置文件进行编辑。
$ nano docker-compose.yml
在其中粘贴以下代码。
version: '3.6'
services:
web:
image: 'gitlab/gitlab-ee:latest'
container_name: 'gitlab-howtoforge'
restart: always
hostname: 'gitlab.example.com'
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'https://gitlab.example.com'
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "email-smtp.us-west-2.amazonaws.com"
gitlab_rails['smtp_user_name'] = "SESUsername"
gitlab_rails['smtp_password'] = "SESKey"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['gitlab_email_from'] = '
[email protected]
'
gitlab_rails['gitlab_email_reply_to'] = '
[email protected]
'
# Add any other gitlab.rb configuration here, each on its own line
ports:
- '80:80'
- '443:443'
- '22:22'
- '587:587'
volumes:
- '$GITLAB_HOME/config:/etc/gitlab'
- '$GITLAB_HOME/logs:/var/log/gitlab'
- '$GITLAB_HOME/data:/var/opt/gitlab'
shm_size: '256m'
我们来看一下文件中定义的所有选项。
- image 指向 Gitlab 的 Docker 镜像在 Dockerhub 上的位置。
- container_name 用于为 Docker 容器指定一个标签,以便在 Docker 网络内引用该容器时使用。
- restart 为容器指定重启策略。将其设为 always 表示容器一旦退出就会自动重启。
- hostname 定义容器的内部主机名,在本例中即安装 Gitlab 的 URL。
- environment 提供 GITLAB_OMNIBUS_CONFIG 变量,可用于填入任意 Gitlab 配置项。
- external_url 指向安装 Gitlab 的域名。使用 https 协议可确保自动安装 Let's Encrypt SSL 证书。
- SMTP 详细信息——我们加入了 SMTP 详细信息,以便 Gitlab 实例能够发送重要邮件和通知。本教程中使用 Amazon 的 SES 服务,不过你也可以选用任意服务。可查阅 Gitlab 文档中关于 SMTP 邮件服务的说明来了解如何配置。
- ports 让容器向主机发布端口或端口范围。由于 Gitlab 需要 22(SSH)、80(HTTP)、443(HTTPS) 和 587(SMTP) 端口,这些端口都已向系统暴露。如果希望 Gitlab 在服务器上使用非标准端口(可能是因为该端口不可用),需要先写主机端口再写容器端口。例如,由于服务器已占用 SSH(22) 端口,可以让 Gitlab 通过另一个端口(比如 3333)使用 SSH,此时需把上述文件中的 22:22 改为 3333:22。此外还需要在上面的 GITLAB_OMNIBUS_CONFIG 下添加一行 gitlab_rails['gitlab_shell_ssh_port'] = 3333。
- volume 定义服务器上用于存储持久化数据的目录。按照第 5 步的定义,现在可以在 compose 文件中使用 $GITLAB_HOME 来挂载容器上的相关目录。
- shm_size 指容器使用的共享内存。默认情况下,Docker 为共享内存目录(挂载于 /dev/shm)分配 64MB,这对于 Gitlab 容器生成的 Prometheus 指标来说可能不够用。因此,至少 256MB 的共享内存可保证 Docker 平稳运行。你可以根据系统 RAM 大小适当调高该值。另一种做法是在安装完成后从管理区域禁用 Prometheus 指标,我们将在下一步探讨这一点。
启动 Gitlab Docker 容器。
$ docker compose up -d
该过程需要几分钟才能完成。你可以通过 Docker 日志跟踪进度。
$ docker logs gitlab-howtoforge -f
按 Ctrl + C 退出日志监控。
你可以使用以下命令检查 Gitlab 容器的状态。
$ docker ps
从 Gitlab 14.0 开始,系统会自动生成 root 密码并将其保存在 initiall_root_password 文件中。该文件位于 /srv/gitlab/config 目录下。运行以下命令查看 root 密码。
$ sudo cat /srv/gitlab/config/initial_root_password
你会看到类似的输出。
# WARNING: This value is valid only in the following conditions
# 1. If provided manually (either via `GITLAB_ROOT_PASSWORD` environment variable or via `gitlab_rails['initial_root_password']` setting in `gitlab.rb`, it was provided before database was seeded for the first time (usually, the first reconfigure run).
# 2. Password hasn't been changed manually, either via UI or via command line.
#
# If the password shown here doesn't work, you must reset the admin password following https://docs.gitlab.com/ee/security/reset_user_password.html#reset-your-root-password.
Password: Hz3t7Etn18wB6VAfBWyDlYbN2VQdMCO0xIIENfDHcFo=
# NOTE: This file will be automatically deleted in the first reconfigure run after 24 hours.
复制该密码并保存备用。现在一切就绪,可以开始配置了。
第 7 步 - 配置 Gitlab
访问 Gitlab
在浏览器中打开 URL https://gitlab.example.com,会看到如下登录界面。

以 root 作为用户名,并输入上一步获得的密码,登录 Gitlab 仪表板。登录后会进入如下仪表板界面。

如你所见,Gitlab 已经创建了一个用于监控该实例的项目。
限制公开注册
默认情况下任何人都可以创建账户并获得访问权限。如果不需要,可以将其关闭。所幸该设置会以弹窗形式显示在仪表板上。点击 Turn off 按钮即可限制 Gitlab 实例的公开注册,随后会跳转到如下设置页面。

取消勾选 Sign-up enabled 选项以限制注册。点击 Save changes 按钮应用该设置。
如果仪表板上没有出现该弹窗,可以点击 Menu 按钮,从那里进入 Admin 面板来访问设置页面。

进入管理面板后,将鼠标悬停在左侧边栏的 Settings 选项上,点击 General 子菜单,即可进入 Sign-up restrictions 面板。

配置 Gitlab 个人资料
默认个人资料相当单调,没有任何可展示的内容。要修改它,点击左上角的用户图标打开下拉菜单,选择 Edit profile 选项。

随后会进入 Profile settings 页面,你可以在此添加姓名、电子邮箱及其他个人信息。完成后点击 Update profile settings。暂时不要返回首页,因为这里还有更多内容需要配置。

修改 Root 密码
这是最重要的步骤之一。你应立即修改默认的 root 密码。在早期版本中,Gitlab 要求在安装过程中修改密码,但现在已改为可选。要修改密码,点击左侧边栏的 Password 菜单。

填写密码信息后点击 Save password 完成修改。你会被登出实例,需要重新登录。
修改用户名
你可以把默认的 Gitlab 用户名 root 改为任意名称。为此,点击左侧边栏的 Account 菜单。

进入页面后,输入新用户名并点击 Update username 按钮完成修改。系统会再次提示确认,再次点击 Update username 按钮以确认更改。
你还应在此启用双因素认证,以提升账户安全性。
禁用 Prometheus 指标并提升隐私
在上一步中,我们讨论了增大 droplet 的共享内存并至少保持 256 MB,这主要是为了在磁盘上存储 Prometheus 指标相关的数据。如果你不使用该功能,就应将其禁用,且只能在安装完成后操作。要禁用它,请从菜单栏打开 Admin Panel。
进入 Admin 面板后,打开 Settings >> Metrics and profiling 菜单选项。

在 Metrics 页面上,展开 Metrics - Prometheus 部分,取消勾选 Enable health and performance metrics endpoint 选项。点击 Save changes 按钮使更改生效。

Gitlab 还会从每个安装实例收集使用信息。如果你重视隐私、不希望如此,可在同一页面展开 Usage statistics 选项并取消勾选 Enable Service Ping 选项。点击 Save changes 按钮使更改生效。

第 8 步 - 创建你的第一个项目
我们来尝试创建第一个项目并推送一次提交。
添加 SSH 密钥
在继续之前,我们应先添加 SSH 密钥,这样无需使用密码即可与安装实例交互。如果你已有 SSH 密钥,可跳过下面的命令;如果没有,可用以下命令创建。
$ ssh-keygen -t ed25519 -C "gitlab.example.com"
该命令适用于 macOS、Linux 以及 Windows 上的 Git Bash/WSL。接受默认设置并输入一个强密码短语。我们是在 Windows Powershell 终端中创建 SSH 密钥。
Generating public/private rsa key pair.
Generating public/private ed25519 key pair.
Enter file in which to save the key (C:\Users\<username>/.ssh/id_ed25519):
Enter same passphrase again:
Your identification has been saved in C:\Users\<username>/.ssh/id_ed25519.
Your public key has been saved in C:\Users\<username>/.ssh/id_ed25519.pub.
SHA256:CI3Ja1LSTN+j4LQnDYkAoP+DvZB8SWrD26zDyUBRbUY gitlab.example.com
+--[ED25519 256]--+
|* ..+E |
|. + / o o |
| o = B o . |
|. o B = S |
|.o X + |
| +X.* |
| .=B o |
+----[SHA256]-----+
把私钥身份添加到 SSH 认证代理。如果你使用 Windows,请确保 OpenSSH Authentication Agent 服务正在运行;如果使用 Linux 或 macOS,请运行以下命令。
$ eval $(ssh-agent -s)
添加密钥。
$ ssh-add C:\Users\<username>/.ssh/id_ed25519
在 Linux 和 macOS 上,命令变为
$ ssh-add ~/.ssh/id_ed25519
系统会提示输入密码短语,输入后密钥即被添加。
接下来,需要把这些设置保存到 ~/.ssh/config 文件。在 Windows 上,该文件位于 C:\Users\
Host gitlab.example.com
PreferredAuthentications publickey
IdentityFile ~/.ssh/id_ed25519
在该文件中,路径名在所有操作系统上保持一致。保存文件。
接下来,需要把公钥复制到 Gitlab 账户中。可通过以下命令显示公钥,这里的路径名同样适用于所有操作系统。
$ cat ~/.ssh/id_ed25519.pub
你会看到类似的输出。
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAml2KPhmGkdMWv7jksLKO13u3g1zI9CumKDQSpv7lYh gitlab.example.com
在 Gitlab 中打开个人资料设置,从左侧边栏选择 SSH Keys 菜单。

把 SSH 密钥粘贴到提供的输入框中,点击 Add Key 继续。

接下来,需要测试 SSH 连接是否正常工作。在你的电脑终端运行以下命令。
$ ssh -T
[email protected]
你会看到类似的输出。首先系统会询问是否把该 SSH 密钥加入系统的 Known hosts 列表,输入 yes 继续。随后会收到一条警告,提示 Gitlab 实例的 SSH 密钥与服务器 IP 的密钥不一致,并再次询问是否继续,同样输入 yes。最后会显示一条成功消息,确认你已连接到 Gitlab 实例。
The authenticity of host 'gitlab.example.com (192.0.2.0)' can't be established.
ECDSA key fingerprint is SHA256:g5mOqAY2A3lhXW0flnLGdSU7RrDnbRFKVJCquAhLXqk.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.
Warning: the ECDSA host key for 'gitlab.example.com' differs from the key for the IP address '192.0.2.0'
Are you sure you want to continue connecting (yes/no)? yes
Offending key for IP in C:\Users\navjo/.ssh/known_hosts:7
Welcome to GitLab, @navjot!
现在可以继续创建第一个仓库并进行若干次提交了。
创建项目
Gitlab 中的每个仓库都隶属于一个项目。项目包含仓库、问题跟踪、合并请求、wiki、持续集成与持续交付 (CI/CD) 流水线,以及许多其他功能。
要创建第一个仓库,点击主页上的 New project 按钮。

随后会进入 New Project 页面,其中提供了多种创建新项目的方式。

选择 Create blank project 选项继续。在下一页输入项目名称,在 Project URL 选项的下拉菜单中选择你的用户名,设置项目 slug。可按需要填写项目描述并调整项目可见性,还可以用 README 文件初始化仓库。

完成后点击 Create project。你会进入仓库页面,其中只有一个空白的 README.md 文件。

仓库已就绪,我们尝试从命令行添加一个变更日志。在你的电脑上输入以下命令创建 CHANGELOG 文件并推送回仓库。请确保电脑上已安装 Git。
第一步是克隆仓库,可使用 SSH 或 HTTPS。这里使用 SSH 克隆,系统会要求输入密码短语。
$ git clone
[email protected]
:user/howtoforge-test.git
输入其余命令以创建并推送 CHANGELOG 文件。
$ cd howtoforge-test
$ touch CHANGELOG # Or create the file in your editor and enter a project description
$ git add CHANGELOG
$ git commit -m "add Changelog"
$ git push -u origin main
执行 push 命令时会再次提示输入密码短语。
返回 Gitlab 项目页面,就能看到其中的 CHANGELOG 文件。恭喜!你已成功创建第一个项目并向其提交了一个文件。

第 9 步 - 管理 Gitlab 容器
我们来看看如何用简单的命令管理 Gitlab 容器。
如果任何时候想停止容器,可在 Docker compose 目录中执行以下命令。
$ docker compose down
要再次启动它们,执行以下命令。
$ docker compose up -d
如果想修改或新增 Gitlab 实例的设置,可在 GITLAB_OMNIBUS_CONFIG 变量下编辑 docker-compose.yml 文件。修改完成后需要重启容器使更改生效。执行以下命令以用新配置更新容器。
$ docker compose down --remove-orphans
$ docker compose up -d
要重启容器,执行以下命令。不过该重启命令不会读取对 Docker compose 文件所做的任何更改。
$ docker compose restart
进入容器 shell。
$ docker exec -it <container name> bash
第 10 步 - 备份 Gitlab
备份 Gitlab 只需一条命令即可完成。
$ docker exec -t gitlab-howtoforge gitlab-backup create
备份文件保存在 /srv/gitlab/data/backups 目录中。该备份不包含 gitlab-secrets.json 配置文件,此文件位于 /srv/gitlab/config 目录,因此需要单独备份。另有一个配置文件 gitlab.rb 包含 Gitlab 实例的全部设置,但本例中我们在 compose 文件里使用了 GITLAB_OMNIBUS_CONFIG 变量,因此 Gitlab 并不使用该文件。对 Gitlab 做任何修改都需要通过该变量定义,所以 compose 文件也需要一并备份。
你可以创建一条 cron 任务来定期备份 Gitlab 安装实例。
第 11 步 - 恢复 Gitlab
要恢复 Gitlab,你需要在另一台系统上有一个可正常运行的 Gitlab 安装实例,还需复制配置目录并覆盖现有安装的配置。
恢复 Gitlab 需要执行多条命令。首先,需要停止与数据库相连的进程。
$ docker exec -it <name of container> gitlab-ctl stop puma
$ docker exec -it <name of container> gitlab-ctl stop sidekiq
把
继续之前请确认这些进程已停止。
$ docker exec -it <name of container> gitlab-ctl status
把备份文件复制到 /srv/gitlab/data/backups 目录;若该目录不存在,请先创建。
运行恢复命令。需要把文件名中的 _gitlab_backup.tar 部分从命令里去掉。
$ docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
复制 gitlab-secrets.json 文件并覆盖新服务器 /srv/gitlab/config 目录中的现有文件。同时把已备份 compose 文件中的所有 Gitlab 设置复制到新容器上的对应文件。
重启 Gitlab 容器。不能直接使用 docker compose restart 命令,因为它不会读取我们需要的、对 compose 文件所做的任何更改。
$ docker compose down --remove-orphans
$ docker compose up -d
检查 Gitlab。
$ docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true
第 12 步 - 升级 Gitlab
升级 Gitlab 的第一步是按上一步所示进行备份。
接着切换到 Gitlab 的 Docker compose 目录。
$ cd ~/gitlab-docker
接着停止并移除现有容器,不过数据会保留。
$ docker compose down --remove-orphans
拉取 Gitlab Docker 镜像的最新版本。
$ docker compose pull
再次启动容器。
$ docker compose up -d
该流程适用于 Gitlab 次版本之间的升级,但升级到主版本时需要遵循额外步骤并做好防范。执行升级前请参考 Gitlab 官方文档。
结语
本教程到此结束,你已学会如何在 Ubuntu 22.04 服务器上使用 Docker 安装 Gitlab,还创建了第一个项目并从电脑向其提交了一个文件。如有任何问题,请在下方评论区留言。