本页内容

• 准备工作
• 第 1 步 - 安装依赖项
• 第 2 步 - 修改系统 SSH 端口
• 第 3 步 - 安装 Docker 与 Docker Compose
• 第 4 步 - 配置 Docker 卷
• 第 5 步 - 使用 Docker Compose 安装 Gitlab
• 第 6 步 - 配置 Gitlab（访问 Gitlab、限制公开注册、配置 Gitlab 个人资料、修改 root 密码、修改用户名、禁用 Prometheus 指标并提升隐私）
• 第 7 步 - 创建你的第一个项目（添加 SSH 密钥、创建项目）
• 第 8 步 - 管理 Gitlab 容器
• 第 9 步 - 备份 Gitlab
• 第 10 步 - 恢复 Gitlab
• 第 11 步 - 升级 Gitlab
• 总结

• 访问 Gitlab
• 限制公开注册
• 配置 Gitlab 个人资料
• 修改 root 密码
• 修改用户名
• 禁用 Prometheus 指标并提升隐私

• 添加你的 SSH 密钥
• 创建项目

Gitlab Server 是云托管版 Gitlab 版本控制系统的开源版本。相比云托管，自建（self-hosting）代码仓库的优势在于你能完全掌控自己的代码。

本指南将介绍如何在 Debian 12 上通过 Docker 安装 Gitlab Server。Gitlab 提供两个版本——免费的社区版（Community edition）和付费的企业版（Enterprise edition）。我们将安装社区版；如果你需要更多功能，可以轻松升级到企业版。

本指南最初由 Navjot Singh 针对 Ubuntu 22.04 编写，现已修改并更新以适配 Debian 12。

准备工作

• 一台运行 Debian 12 的服务器。
• 一个指向该服务器的完全限定域名（FQDN），例如 gitlab.example.com。
• 你已以 root 用户身份登录。
• 所有软件包均已更新。

一台运行 Debian 12 的服务器。

一个指向该服务器的完全限定域名（FQDN），例如 gitlab.example.com。

apt update && apt upgrade

第 1 步 - 安装依赖项

在安装 Gitlab 之前，我们必须先安装本教程所需的某些软件包。

apt install ca-certificates curl openssh-server apt-transport-https gnupg lsb-release -y

其中部分软件包可能已在你的系统上预装。

第 2 步 - 修改系统 SSH 端口

Gitlab 会使用默认的 SSH 端口，这会与系统的 SSH 端口冲突。为了获得最佳效果，最好修改系统默认的 SSH 端口。

为此，请打开 /etc/ssh/sshd_config 文件进行编辑。

nano /etc/ssh/sshd_config

找到下面这行，去掉行首的井号（#）并将其值从 22 改为你选择的任意其他端口。在本教程中，我们将其改为 2425：

#Port 22

改为

 Port 2222

按 Ctrl + X 保存文件，并在提示时输入 Y。

重启 SSH 服务。

systemctl restart sshd

关闭当前的 SSH 会话，并使用新端口重新登录。

ssh username@<serverIP> -p 2222

第 3 步 - 安装 Docker 与 Docker Compose

添加 Docker 官方的 GPG 密钥。

curl -fsSL https://download.docker.com/linux/debian/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/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

更新系统软件源以包含 Docker 的软件源。

apt update

安装 Docker。

apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

本教程将使用 Docker Compose v2 插件，而非旧版的独立二进制文件。因此，运行命令已从 docker-compose 改为 docker compose，下文均以此为准。

Docker 以高权限运行，因此你经常需要使用 sudo 来执行命令。将你的 Linux 用户账户加入 docker 用户组是更好的做法。

usermod -aG docker ${USER}

${USER} 变量会自动获取当前登录的系统账户。如果你不是以想要赋予权限的用户登录，请将 ${USER} 替换为该用户名。

要使新的用户组成员身份生效，请注销服务器后重新登录，或运行以下命令。系统会提示你输入该用户的密码。

su - $(USER)

第 4 步 - 配置 Docker 卷

在安装之前，我们必须为 Gitlab 的数据和配置指定通过 Docker 卷进行访问的位置。

创建 Docker 卷目录。

mkdir -p /opt/gitlab/vol

切换到 /opt/gitlab 目录。

cd /opt/gitlab 

创建一个环境变量文件并打开进行编辑。

nano .env

粘贴以下代码以定义 $GITLAB_HOME 变量。

GITLAB_HOME=/opt/gitlab/vol

Gitlab 容器使用主机挂载卷来存储持久化数据。下表展示了 Gitlab 各目录在本地路径、容器路径及其各自用途之间的对应关系。

第 5 步 - 使用 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 在 Dockerhub 上的 Docker 镜像位置。
• 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 步所述，$GITLAB_HOME 现在可在 compose 文件中用于将相关目录挂载到容器上。
• shm_size 指容器使用的共享内存大小。默认情况下，Docker 会为共享内存目录（挂载于 /dev/shm）分配 64MB，这对于 Gitlab 容器生成的 Prometheus 指标来说可能不够。因此，至少 256MB 的共享内存可确保 Docker 平稳运行。你可以根据系统的内存容量调大该值。或者，安装后可在管理后台禁用 Prometheus 指标——我们将在下一步介绍。

启动 Gitlab Docker 容器。

docker compose up -d

整个过程需要几分钟才能完成。你可以通过 Docker 日志查看进度。

docker logs gitlab-howtoforge -f

按 Ctrl + C 退出日志监控。

你可以使用以下命令查看 Gitlab 容器的状态。

docker ps

Gitlab 会自动生成一个 root 密码，并保存在 initial_root_password 文件中。该文件位于 /srv/gitlab/config 目录下。运行以下命令即可查看 root 密码。

cat /opt/gitlab/vol/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.

复制该密码并保存，以便后续使用。至此所有准备工作已完成，我们可以开始进行配置。

第 6 步 - 配置 Gitlab

访问 Gitlab

在浏览器中打开地址 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（编辑个人资料）」选项。

你将进入个人资料设置页面，可以在其中填写你的姓名、电子邮件等个人信息。填写完成后点击「Update profile settings（更新个人资料设置）」。暂时不要返回首页，因为我们还有更多设置需要在此完成。

修改 root 密码

这是最重要的步骤之一。你应该立即修改默认的 root 密码。在早期版本中，Gitlab 会要求在安装过程中修改密码，而现在这一步骤已变为可选。要修改密码，请点击左侧边栏的「Password（密码）」菜单。

输入密码信息后点击「Save password（保存密码）」以使更改生效。此后你将被登出实例，需要重新登录。

修改用户名

你可以将默认的 Gitlab 用户名从 root 修改为你喜欢的任意名称。为此，请点击左侧边栏的「Account（账户）」菜单。

进入该页面后，输入新的用户名并点击「Update username（更新用户名）」按钮以完成修改。系统会再次提示你确认，再次点击「Update username」按钮即可确认更改。

你还应在此启用双因素认证（2FA），以提升账户安全性。

禁用 Prometheus 指标并提升隐私

在上一步中，我们提到应将共享内存大小增加到至少 256 MB，这主要是为了在磁盘上存储 Prometheus 指标相关的数据。如果你不使用该功能，应该将其禁用。该操作只能在安装完成后进行。要禁用它，请从菜单栏打开「Admin Panel（管理面板）」。

进入管理面板后，打开「Settings（设置）>> Metrics and profiling（指标与性能分析）」菜单选项。

在 Metrics 页面展开「Metrics - Prometheus」部分，取消勾选「Enable health and performance metrics endpoint（启用健康与性能指标端点）」选项，然后点击「Save changes（保存更改）」按钮使更改生效。

Gitlab 还会从每个安装实例收集使用情况信息。如果你重视隐私、不希望这样做，可在同一页面展开「Usage statistics（使用统计）」选项，并取消勾选「Enable Service Ping（启用服务探测）」。点击「Save changes」按钮使更改生效。

第 7 步 - 创建你的第一个项目

让我们尝试创建第一个项目并推送一次提交。

添加你的 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\\.ssh 目录。请将以下代码粘贴到文件末尾。

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 密钥）」菜单。

将 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 中的每个仓库都属于一个项目。一个项目包含仓库、问题跟踪器（issue tracker）、合并请求（merge requests）、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

在推送命令执行过程中，系统会再次提示你输入口令。

返回你的 Gitlab 项目页面，你将看到其中的 CHANGELOG 文件。恭喜！你已成功创建第一个项目并向其中提交了一个文件。

第 8 步 - 管理 Gitlab 容器

下面我们来看看如何使用简单的命令管理 Gitlab 容器。

如果你在任何时候想要停止容器，请在 Docker Compose 目录中执行以下命令。

$ docker compose down

要再次启动它们，请执行以下命令。

$ docker compose up -d

如果你想修改或新增 Gitlab 实例的某项设置，可以通过编辑 docker-compose.yml 文件中 GITLAB_OMNIBUS_CONFIG 变量下的内容来实现。修改完成后，你需要重启容器以使更改生效。请执行以下命令，以新配置更新容器。

$ docker compose down --remove-orphans
$ docker compose up -d

要重启容器，请执行以下命令。不过，下面的重启命令不会读取对 Docker Compose 文件所做的任何更改。

$ docker compose restart

进入容器 shell。

$ docker exec -it <container name> bash

第 9 步 - 备份 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.rb 文件；任何对 Gitlab 的修改都需要通过该变量来定义。所以，你同样需要备份 compose 文件。

你可以创建一个 cron 条目，定期备份你的 Gitlab 安装。

第 10 步 - 恢复 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

第 11 步 - 升级 Gitlab

要升级 Gitlab，第一步是如上一节所示先进行一次备份。

接下来，切换到 Gitlab 的 Docker Compose 目录。

$ cd ~/gitlab-docker

接下来，停止并移除现有容器，不过你的数据会被保留。

$ docker compose down --remove-orphans

拉取最新版本的 Gitlab Docker 镜像。

$ docker compose pull

再次启动容器。

$ docker compose up -d

该流程适用于 Gitlab 小版本之间的升级；但当你升级到大版本时，必须遵循额外的步骤并采取预防措施。在执行升级之前，你应该参考 Gitlab 的官方文档。

总结

本教程到此结束，你学习了如何在 Debian 12 服务器上通过 Docker 安装 Gitlab，还创建了你的第一个项目并从电脑提交了文件。如果你有任何问题，请在下方评论区留言。