如何安装 GitLab – wiki基地

作者： /

GitLab 安装超详细指南：从准备到运行的每一步

引言：为什么选择自建 GitLab？

在软件开发和协作领域，版本控制系统是核心基础设施。GitLab 作为一款流行的基于 Git 的代码托管平台，集成了 CI/CD 流水线、问题跟踪、Wiki、代码评审等多种功能，提供了一个完整的DevOps平台。虽然 SaaS 版本的 GitLab (GitLab.com) 为许多团队提供了便利，但对于一些特定的需求，自建（Self-Managed）GitLab 实例具有不可替代的优势：

  1. 数据主权与安全性： 将敏感代码和数据保存在自己的服务器上，可以更好地控制数据的访问和保护，满足合规性要求。
  2. 定制化与集成： 可以根据自己的需求深度定制 GitLab 的配置，与内部的其他系统进行更紧密的集成。
  3. 性能控制： 可以根据团队规模和使用情况调整服务器资源，优化性能。
  4. 网络环境： 在内部网络中部署，可以减少对外部网络的依赖，提高访问速度和稳定性，尤其适合内网开发环境。
  5. 成本控制： 对于大型团队或长期使用而言，自建可能比订阅 SaaS 版本更具成本效益（尤其是在已经有基础设施的情况下）。

本篇文章将手把手教你如何详细安装和配置一个自建的 GitLab 实例。我们将重点介绍最常用和推荐的安装方式——使用 Omnibus 包进行安装，因为它包含了 GitLab 及其所有依赖（如 Nginx、PostgreSQL、Redis 等），大大简化了安装和管理过程。

无论你是系统管理员、运维工程师还是希望在自己的服务器上搭建 GitLab 的开发者，本文都将为你提供清晰、全面的指导。

准备工作：安装前的必需条件

在开始安装 GitLab 之前，你需要进行一系列的准备工作，确保你的服务器环境满足 GitLab 的最低要求。跳过这一步可能会导致安装失败或运行不稳定。

1. 硬件要求

GitLab 的硬件需求取决于你的用户数量、项目数量、CI/CD 任务量以及使用频率。以下是一些基本的指导：

  • CPU:
    • 最低配置 (<= 100 用户, 低并发): 至少 4 核 CPU。
    • 推荐配置 (<= 500 用户, 中等并发): 至少 8 核 CPU。
    • 更大型部署: 建议更多核心，并考虑分拆服务（如独立的 Gitaly 服务器）。
  • 内存 (RAM): 内存是影响 GitLab 性能最关键的因素之一。
    • 最低配置: 至少 8GB。请注意，8GB 只能勉强运行，尤其是在使用 CI/CD 或进行一些资源密集型操作时，很容易出现性能瓶颈甚至服务崩溃。
    • 推荐配置 (<= 100 用户): 至少 16GB。
    • 推荐配置 (<= 500 用户): 至少 32GB。
    • 注意: 这些是 GitLab 进程本身 消耗的内存。操作系统、其他服务（如果安装在同一台服务器上）也会占用内存。请留出足够的余量。
  • 磁盘空间:
    • 最低配置: 至少 50GB 可用空间。
    • 推荐配置: 至少 100GB 可用空间。
    • 考虑因素: 你的代码库大小、CI/CD 缓存、Docker 镜像（如果使用内置 Registry）、备份文件等都会占用大量磁盘空间。建议使用 SSD 硬盘以获得更好的性能，并预留充足的空间。
    • IOPS: 磁盘的读写速度（IOPS）对 GitLab 性能影响很大，尤其是对 Gitaly（处理 Git 请求的服务）和数据库。SSD 通常能提供远高于 HDD 的 IOPS。

总结硬件： 对于一个小型团队（几十人），16GB 内存 + 100GB SSD 是一个比较稳妥的起点。如果预算允许，总是建议配置更高的内存，它能显著提升 GitLab 的响应速度和稳定性。

2. 操作系统 (OS)

GitLab Omnibus 包支持多种 Linux 发行版。选择一个稳定、长期支持 (LTS) 的版本是明智的。常用的支持列表如下：

  • Ubuntu (LTS 版本如 20.04, 22.04)
  • Debian (稳定版本如 10, 11)
  • CentOS / RHEL / Rocky Linux / AlmaLinux (8 或更新版本)
  • openSUSE Leap

本教程将主要以 Ubuntu 22.04 LTS 作为示例进行详细讲解，但步骤对于其他基于 Debian 的系统（如 Debian）或基于 RHEL 的系统（如 CentOS/Rocky/AlmaLinux）也非常相似，只需替换包管理器命令（apt 替换为 yum 或 dnf）即可。

选择操作系统时，请确保它是 64 位系统。

3. 网络要求

为了让用户能够访问 GitLab，你需要确保服务器的网络配置正确，并且相关的端口在防火墙中是开放的。

  • SSH (端口 22): 用于 Git 推送/拉取（通过 SSH 协议）和服务器管理。必须开放。
  • HTTP (端口 80): 用于 HTTP 克隆和访问 GitLab Web 界面（如果未配置 HTTPS 或作为 HTTPS 的重定向）。必须开放。
  • HTTPS (端口 443): 用于 HTTPS 克隆和访问 GitLab Web 界面（强烈推荐使用 HTTPS）。如果使用 HTTPS，必须开放。

你可能还需要考虑：

  • SMTP (端口 25, 587, 或 465): 如果你需要配置 GitLab 发送邮件（如注册确认、通知等）。
  • 其他自定义端口: 如果你修改了 Nginx 或其他服务的默认端口。

确保你的服务器有静态 IP 地址，并且如果通过域名访问，DNS 记录已正确指向该 IP 地址。

4. 域名或静态 IP

用户将通过域名或静态 IP 地址访问你的 GitLab 实例。

  • 推荐使用域名: gitlab.yourcompany.com 这样的域名更友好，并且是配置 HTTPS 所必需的（大多数证书颁发机构要求使用域名）。
  • 如果使用静态 IP: 用户将通过 http://<服务器IP> 或 https://<服务器IP> 访问。但请注意，使用 IP 配置 HTTPS 需要自签名证书或内网 CA 颁发的证书，过程相对复杂且在浏览器中会显示安全警告。

确保你计划使用的域名或 IP 地址是可达的。

5. Sudo 权限

安装和配置过程需要root权限。确保你当前登录的用户拥有 sudo 权限。

6. 前置依赖（部分在安装过程中会安装）

Omnibus 包会安装大部分依赖，但通常建议提前安装或确保一些基础工具可用：

  • curl: 用于下载安装脚本或文件。
  • openssh-server: 如果你需要在服务器上进行 SSH 操作（几乎总是需要的）。
  • ca-certificates: 用于验证 SSL 证书。
  • postfix 或其他邮件传输代理 (MTA)：用于发送邮件。如果不需要邮件功能，可以跳过 Postfix，但安装过程中可能会提示或警告。建议安装 Postfix 并稍后配置或禁用。

准备好以上各项后，你就可以开始正式的安装流程了。

GitLab Omnibus 包安装步骤（以 Ubuntu 22.04 LTS 为例）

GitLab 官方提供了 Omnibus 包，这是最简单、最快速的安装方式。它将 GitLab 及其所有必要的组件（如 Web 服务器 Nginx、数据库 PostgreSQL、缓存 Redis 等）打包在一起，通过一个命令即可安装和配置。

步骤 1：更新系统

在安装任何新软件之前，更新你的系统软件包列表并升级已安装的软件包是一个好习惯。这可以确保你拥有最新的安全补丁和软件版本，避免潜在的兼容性问题。

bash
sudo apt update
sudo apt upgrade -y

对于基于 RHEL 的系统（CentOS/Rocky/AlmaLinux）：

bash
sudo yum update -y # 或者 sudo dnf update -y

步骤 2：安装必要的依赖

安装一些 GitLab Omnibus 包依赖的基础软件包。

bash
sudo apt install -y curl openssh-server ca-certificates postfix

  • curl: 用于下载 GitLab 仓库脚本。
  • openssh-server: 确保 SSH 服务已安装并运行，用于 Git 通过 SSH 协议进行推送/拉取。
  • ca-certificates: 包含用于验证 SSL 证书的根证书，保证与外部服务的安全通信。
  • postfix: 一个邮件传输代理 (MTA)，用于 GitLab 发送通知邮件等。如果你不需要邮件功能，可以跳过安装 Postfix，但在后续配置中需要禁用邮件发送功能。建议先安装。

在安装 postfix 时，可能会出现配置界面。通常选择 “Internet Site”，然后填写你的服务器域名或一个适当的主机名。如果暂时不确定，可以使用默认值或服务器的主机名，之后可以在 /etc/postfix/main.cf 中修改。

对于基于 RHEL 的系统：

bash
sudo yum install -y curl policycoreutils openssh-server postfix # 或者 sudo dnf install ...
sudo systemctl enable sshd
sudo systemctl start sshd
sudo systemctl enable postfix
sudo systemctl start postfix

注意：RHEL/CentOS/Rocky/AlmaLinux 系统上可能还需要调整 SELinux 策略。policycoreutils 包提供了相关工具。

步骤 3：添加 GitLab 仓库

GitLab 为不同的 Linux 发行版维护了软件包仓库。我们需要添加适合你的系统的仓库，以便使用标准的包管理器进行安装和更新。GitLab 提供了一个方便的脚本来完成这个任务。

访问 GitLab Package Repository 页面，找到你的操作系统和版本，然后复制其提供的脚本。或者，你可以使用以下通用脚本（它会检测你的系统并添加正确的仓库）：

bash
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

如果你想安装企业版 (EE)，请将 gitlab-ce 替换为 gitlab-ee：

bash
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

（CE 是社区版，免费；EE 是企业版，部分功能需要许可证，但基本安装流程相同，无许可证时运行的是 CE 功能子集）

这个脚本会下载仓库的签名密钥，添加到你的系统，并配置 APT 源列表。完成后，你会看到成功的消息。

对于基于 RHEL 的系统，脚本会有所不同，通常是：

“`bash
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash

或者 enterprise edition

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh | sudo bash

“`

步骤 4：安装 GitLab Omnibus 包

在添加了 GitLab 仓库后，你就可以使用包管理器安装 GitLab 主程序包了。在安装命令中，你需要通过 EXTERNAL_URL 环境变量指定你希望通过哪个 URL 访问 GitLab。

bash
sudo EXTERNAL_URL="http://gitlab.yourcompany.com" apt install gitlab-ce

请将 "http://gitlab.yourcompany.com" 替换为你实际计划使用的域名或 IP 地址。使用域名或 IP 地址作为 EXTERNAL_URL 是非常重要的，它会影响 GitLab 内部许多配置（如重定向、API 地址等）。 如果你打算后续配置 HTTPS，这里可以先使用 HTTP 地址，之后再修改配置文件。

如果你要安装企业版：

bash
sudo EXTERNAL_URL="http://gitlab.yourcompany.com" apt install gitlab-ee

安装过程会下载大量的软件包，可能需要一些时间，具体取决于你的网络速度。安装完成后，GitLab 的所有组件会被安装到 /opt/gitlab 目录下，配置文件位于 /etc/gitlab。

对于基于 RHEL 的系统，命令是：

“`bash
sudo EXTERNAL_URL=”http://gitlab.yourcompany.com” yum install gitlab-ce # 或者 dnf

或者 enterprise edition

sudo EXTERNAL_URL=”http://gitlab.yourcompany.com” yum install gitlab-ee # 或者 dnf

“`

步骤 5：配置和启动 GitLab

安装包完成后，GitLab 并不会立即完全配置好并运行。你需要运行 gitlab-ctl reconfigure 命令。这个命令是 GitLab Omnibus 包的核心管理命令之一，它会读取 /etc/gitlab/gitlab.rb 配置文件，然后根据配置自动化地设置和启动所有 GitLab 组件，包括：

  • 生成 Nginx 配置文件
  • 初始化或升级 PostgreSQL 数据库
  • 配置 Redis
  • 启动 Puma (Rails 应用服务器)
  • 启动 Sidekiq (异步任务处理器)
  • 启动 Gitaly (Git 仓库服务)
  • 启动其他相关服务

运行配置命令：

bash
sudo gitlab-ctl reconfigure

这个命令的执行时间可能会比较长（几分钟到十几分钟），具体取决于你的服务器性能。在执行过程中，你会看到各种服务的配置和启动输出。请耐心等待，直到命令执行完毕并显示成功信息。

如果过程中出现错误，请仔细阅读输出信息，通常会指出问题所在。常见的错误可能包括内存不足、磁盘空间不足、端口被占用等。

6. 验证安装

gitlab-ctl reconfigure 命令成功完成后，GitLab 的各个服务应该已经在后台运行了。你可以通过以下命令检查服务的状态：

bash
sudo gitlab-ctl status

你应该看到类似 run: gitaly: (pid ...) ..., run: nginx: (pid ...) ..., run: postgresql: (pid ...) ..., run: puma: (pid ...) ... 等输出，表示各个组件正在运行。

现在，打开你的 Web 浏览器，访问你在步骤 4 中设置的 EXTERNAL_URL 地址（例如 http://gitlab.yourcompany.com 或服务器的 IP 地址）。你应该能看到 GitLab 的登录页面。

7. 首次登录和设置 Root 密码

首次访问 GitLab 登录页面时，你需要设置 root 用户的初始密码。

在 GitLab 的较新版本中，root 用户的初始密码会被临时存储在一个文件中。使用以下命令查看：

bash
sudo cat /etc/gitlab/initial_root_password

复制显示的密码。注意，这个文件在第一次运行 gitlab-ctl reconfigure 后 24 小时会自动删除，或者在执行 gitlab-ctl reconfigure 后 60 分钟删除（取决于 GitLab 版本和配置）。如果在文件删除后才尝试登录，你需要重置 root 密码（后面会介绍）。

在 GitLab 登录页面，使用用户名 root 和刚刚获取的初始密码进行登录。

登录成功后，GitLab 会要求你立即修改 root 用户的密码。设置一个安全的新密码，并妥善保管。修改密码后，你会进入 GitLab 的主界面。

至此，你的 GitLab 实例已经成功安装并可以访问了。

安装后的重要配置和维护

成功安装 GitLab 只是第一步。为了让你的 GitLab 实例更健壮、更安全、更实用，还需要进行一些重要的配置和维护。

1. 配置 HTTPS (强烈推荐)

通过 HTTPS 访问 GitLab 可以加密用户与服务器之间的通信，保护敏感数据（如代码、凭据）。为 GitLab 配置 HTTPS 最常见的方式是使用 Let’s Encrypt 提供的免费 SSL 证书，GitLab Omnibus 包内置了对 Let’s Encrypt 的支持，配置非常简单。

前提条件：

  • 你的服务器必须可以通过公网（或内网，取决于你的需求）访问。
  • 你必须拥有一个域名，并且该域名已经正确地解析到你的 GitLab 服务器的 IP 地址。
  • 你的服务器必须开放端口 80 和 443，以便 Let’s Encrypt 进行域名验证和 HTTPS 访问。

配置步骤：

编辑 GitLab 主配置文件 /etc/gitlab/gitlab.rb：

bash
sudo nano /etc/gitlab/gitlab.rb

找到 external_url 配置项，将其修改为你的 HTTPS 地址：

ruby
external_url 'https://gitlab.yourcompany.com'

（将 gitlab.yourcompany.com 替换为你的实际域名）

然后，找到 Let’s Encrypt 相关的配置，启用自动获取证书：

“`ruby

Enable Let’s Encrypt

letsencrypt[‘enable’] = true

Specify the email address for notifications about expiring certificates

letsencrypt[‘contact_emails’] = [‘[email protected]’] # 替换为你的邮箱

Auto-renew certificates

letsencrypt[‘auto_renew’] = true

Run the renew process automatically

letsencrypt[‘auto_renew_hour’] = 10 # 设置一个小时
letsencrypt[‘auto_renew_minute’] = 30 # 设置一个分钟
letsencrypt[‘auto_renew_day_of_month’] = “*/5” # 每5天检查一次
“`

将 [email protected] 替换为你的电子邮件地址，以便接收证书过期通知。

保存并关闭文件。

运行 gitlab-ctl reconfigure 使配置生效：

bash
sudo gitlab-ctl reconfigure

reconfigure 过程会自动检测 external_url 中的 HTTPS 设置，尝试通过 Let’s Encrypt 获取证书，并配置 Nginx 使用这些证书。如果一切顺利，你应该能够通过 https://gitlab.yourcompany.com 访问 GitLab，并且浏览器会显示安全的连接。

如果 Let’s Encrypt 验证失败（通常是由于防火墙阻止了对端口 80 的访问，或者 DNS 配置不正确），请检查防火墙规则和域名解析，然后再次运行 gitlab-ctl reconfigure。

手动配置 SSL 证书：

如果你有其他来源的 SSL 证书（如购买的商业证书或内部 CA 颁发的证书），可以将证书文件和私钥文件放在服务器上（例如 /etc/gitlab/ssl/ 目录），然后在 /etc/gitlab/gitlab.rb 中配置：

“`ruby
external_url ‘https://gitlab.yourcompany.com’

nginx[‘ssl_certificate’] = “/etc/gitlab/ssl/gitlab.yourcompany.com.crt”
nginx[‘ssl_certificate_key’] = “/etc/gitlab/ssl/gitlab.yourcompany.com.key”
“`

然后运行 sudo gitlab-ctl reconfigure。

2. 配置邮件发送 (SMTP)

GitLab 需要发送各种通知邮件，例如新用户注册、密码重置、评论回复、CI/CD 状态变更等。配置 SMTP 服务是确保这些功能正常工作的关键。

编辑 /etc/gitlab/gitlab.rb 文件：

bash
sudo nano /etc/gitlab/gitlab.rb

找到 gitlab_rails['smtp_enable'] 相关的配置段，并根据你的 SMTP 服务提供商进行修改。以下是一个使用外部 SMTP 服务器的示例：

“`ruby
gitlab_rails[‘smtp_enable’] = true
gitlab_rails[‘smtp_address’] = “smtp.your-mailserver.com” # 替换为你的 SMTP 服务器地址
gitlab_rails[‘smtp_port’] = 587 # SMTP 端口，常用 25, 587, 465
gitlab_rails[‘smtp_user_name’] = “your-gitlab-smtp-user” # 替换为你的 SMTP 登录用户名
gitlab_rails[‘smtp_password’] = “your-gitlab-smtp-password” # 替换为你的 SMTP 登录密码
gitlab_rails[‘smtp_domain’] = “your-mailserver.com” # 替换为你的邮件服务器域名
gitlab_rails[‘smtp_authentication’] = “login” # 认证方式，常用 plain, login, cram_md5
gitlab_rails[‘smtp_enable_starttls_auto’] = true # 启用 STARTTLS 自动协商
gitlab_rails[‘smtp_tls’] = false # 如果使用端口 465 并要求 SSL/TLS，则设置为 true

可选：配置发件人地址

gitlab_rails[‘gitlab_email_from’] = ‘[email protected]’ # 替换为 GitLab 发送邮件的地址
gitlab_rails[‘gitlab_email_display_name’] = ‘GitLab’
“`

请根据你的实际 SMTP 服务器设置修改上述参数。

保存并关闭文件，然后再次运行 gitlab-ctl reconfigure：

bash
sudo gitlab-ctl reconfigure

配置完成后，你可以通过 GitLab 的 Rails 控制台测试邮件发送功能。

进入 Rails 控制台：

bash
sudo gitlab-rails console

在控制台中执行以下命令发送测试邮件：

ruby
Notify.test_email('[email protected]', 'Test email from GitLab', 'This is a test email from your GitLab instance.').deliver_now

将 '[email protected]' 替换为你接收测试邮件的地址。检查收件箱是否收到了邮件。

3. 配置备份策略

定期备份你的 GitLab 实例数据至关重要，以防硬件故障、数据损坏或误操作。GitLab Omnibus 包提供了一个内置的备份 Rake 任务。

要创建备份，只需运行：

bash
sudo gitlab-backup create SKIP=builds,artifacts,registry

SKIP 参数可以用来跳过备份大型数据（如 CI/CD 构建日志、制品、容器镜像仓库），加快备份速度，如果需要备份这些数据，请移除 SKIP 参数。

备份文件会生成在 /var/opt/gitlab/backups/ 目录下，文件名包含时间戳。

为了实现自动化备份，你可以配置一个 Cron 作业。编辑 Cron 表：

bash
sudo crontab -e

添加一行，例如每天凌晨 1 点执行备份：

cron
0 1 * * * sudo gitlab-backup create SKIP=builds,artifacts,registry

这会将备份文件保存在本地。强烈建议将备份文件定期传输到另一个存储位置（例如对象存储、另一台服务器）以实现真正的灾难恢复。 你可以在 Cron 脚本中添加 scp 或对象存储上传命令。

关于备份和恢复的更详细信息及其他配置选项，请查阅 GitLab 官方文档。

4. 监控 GitLab

GitLab Omnibus 包内置了 Prometheus 和 Grafana，可以用于监控 GitLab 自身的性能指标。默认情况下，这些监控服务可能已启用，并在特定端口上暴露数据。

你可以访问 http://your-gitlab-server:9168 (Prometheus Node Exporter) 和 http://your-gitlab-server:9090 (Prometheus) 查看原始监控数据。Grafana 通常运行在 http://your-gitlab-server:9168 上，并提供预设的仪表盘。

你可以通过修改 /etc/gitlab/gitlab.rb 中的相关配置（如 prometheus_monitoring['enable'], node_exporter['enable'], grafana['enable']）来控制这些服务的启用状态和端口。

定期检查监控数据，可以帮助你及时发现性能瓶颈或潜在问题。

5. 调整性能配置

如果你的 GitLab 实例在高负载下出现性能问题，你可能需要调整 /etc/gitlab/gitlab.rb 中关于 Unicorn/Puma (应用服务器) 和 Sidekiq (异步任务处理器) 的配置。

例如，增加 Puma worker 数量或 Sidekiq 并发数可以利用更多 CPU 核心，但会增加内存消耗。

“`ruby

Puma settings (adjust according to your server’s CPU cores and RAM)

unicorn[‘worker_processes’] = 4 # GitLab 14.0+ uses Puma by default

puma[‘worker_processes’] = 4 # 建议设置为 CPU 核心数或其两倍，但注意内存消耗
puma[‘per_worker_threads’] = 4 # 每个 worker 的线程数

Sidekiq settings (adjust according to your server’s RAM and disk I/O)

sidekiq[‘concurrency’] = 25 # Sidekiq 并发数，影响处理后台任务的速度
“`

修改这些配置后，需要运行 sudo gitlab-ctl reconfigure 使其生效。

重要提示： 在调整性能配置之前，强烈建议查阅 GitLab 官方文档中关于硬件要求和性能调优的部分，并逐步进行调整，同时监控系统资源使用情况。不恰当的配置可能导致服务不稳定或资源耗尽。

6. 安全设置

安装后应立即采取一些基础安全措施：

  • 更改 root 密码： 如果你还没有改，请立即修改初始 root 密码。
  • 禁用 root 账户的 Web 登录 (可选但推荐)： 创建一个新的管理员账户后，可以在管理界面禁用 root 用户通过 Web 界面登录，只保留 SSH 登录能力。
  • 启用双因素认证 (2FA)： 在管理界面为用户（特别是管理员）强制启用 2FA。
  • 配置防火墙： 确保只有必需的端口（22, 80, 443）对外开放，限制不必要的端口访问。
  • 定期更新： 保持 GitLab 版本最新，以获取最新的安全补丁和功能。

7. 创建用户和组

登录 GitLab 后，作为管理员，你可以在管理界面创建新用户、创建组、创建项目，并分配相应的权限。

其他安装方法简述

虽然 Omnibus 包是最简单、最推荐的安装方式，但 GitLab 也支持其他安装方法：

  • Docker 安装： 将 GitLab 运行在 Docker 容器中，提供了更好的隔离性、可移植性和易于部署。这需要你熟悉 Docker 的使用。GitLab 官方提供了 Docker 镜像。
  • Kubernetes (Helm Chart) 安装： 如果你有 Kubernetes 集群，可以使用 GitLab 官方提供的 Helm Chart 将 GitLab 部署到集群中，实现高可用和弹性伸缩。这适用于大型、对可用性要求高的部署。
  • 从源代码安装： 这是最灵活但也最复杂的方式，你需要手动安装所有依赖并编译 GitLab 源代码。通常只推荐给需要深度定制或开发的专家使用。

对于大多数用户和场景，使用 Omnibus 包或 Docker 是更明智的选择。本篇文章主要聚焦于 Omnibus 包，因为它提供了本地服务器上最完整的、一站式的解决方案。

常见问题与故障排除

在安装或运行 GitLab 过程中，可能会遇到一些问题。以下是一些常见问题及其排查方向：

  • gitlab-ctl reconfigure 失败：
    • 仔细阅读输出日志，错误信息通常会指示问题所在。
    • 检查服务器资源：CPU、内存、磁盘空间是否充足。内存不足是常见原因。
    • 检查 /etc/gitlab/gitlab.rb 配置文件是否有语法错误或配置错误。
    • 检查端口是否被占用：ss -tulnp | grep <port_number> 或 netstat -tulnp | grep <port_number>。
    • 检查文件权限。
  • 无法访问 GitLab Web 界面：
    • 检查服务器防火墙是否开放了 80 (HTTP) 和 443 (HTTPS) 端口。
    • 检查服务器内部防火墙（如 ufw, firewalld）是否开放了端口。
    • 检查 Nginx 服务是否正在运行：sudo gitlab-ctl status。
    • 查看 Nginx 访问日志和错误日志：sudo gitlab-ctl tail nginx。
    • 检查 DNS 解析是否正确指向服务器 IP。
    • 如果配置了 HTTPS，检查 SSL 证书是否有效，链是否完整。
  • Git Push/Pull (SSH) 失败：
    • 检查 SSH 服务是否正在运行：sudo systemctl status sshd。
    • 检查服务器防火墙是否开放了 22 端口。
    • 检查用户是否将 SSH 公钥添加到了 GitLab 的用户设置中。
    • 查看 GitLab Shell 的日志：sudo gitlab-ctl tail gitlab-shell。
  • Git Push/Pull (HTTPS) 失败：
    • 检查 Web 界面是否可以通过 HTTPS 正常访问。
    • 检查 SSL 证书是否有效，并且客户端信任该证书（尤其是自签名证书）。
    • 查看 GitLab Puma/Unicorn 日志：sudo gitlab-ctl tail puma 或 sudo gitlab-ctl tail unicorn。
  • 性能缓慢：
    • 检查服务器资源使用情况：top, htop, free -h, iostat。
    • 特别关注内存使用，如果 SWAP 空间被大量使用，说明内存不足。
    • 检查磁盘 I/O：iostat -xz 1。
    • 检查 GitLab 监控仪表盘，查看哪些服务是瓶颈。
    • 考虑调整 /etc/gitlab/gitlab.rb 中的性能参数（Puma workers, Sidekiq concurrency）。
  • 查看 GitLab 日志：
    • 使用 sudo gitlab-ctl tail 查看所有服务的实时日志。
    • 特定服务的日志文件位于 /var/log/gitlab/ 目录下，例如 /var/log/gitlab/nginx/, /var/log/gitlab/puma/, /var/log/gitlab/sidekiq/, /var/log/gitlab/gitaly/ 等。

遇到问题时，查阅 GitLab 官方文档是最好的方式，它提供了详细的故障排除指南和配置说明。

GitLab 升级

使用 Omnibus 包安装的 GitLab 升级非常简单。通常只需要更新系统的软件包列表并升级 gitlab-ce 或 gitlab-ee 包即可。

bash
sudo apt update
sudo apt upgrade -y gitlab-ce # 或者 gitlab-ee

对于基于 RHEL 的系统：

bash
sudo yum update -y gitlab-ce # 或者 gitlab-ee; 或者 dnf

包管理器会自动下载新版本的 GitLab 并执行升级脚本。升级完成后，gitlab-ctl reconfigure 命令会自动运行以应用任何配置变更和数据库迁移。

重要提示：

  • 在进行主要版本升级（例如从 15.x 升级到 16.x）之前，务必仔细阅读 GitLab 的官方升级指南，了解升级路径和注意事项。有时需要分阶段升级到中间版本。
  • 在升级前务必进行完整的备份！ 这是防止升级失败导致数据丢失的最后一道防线。
  • 大型升级可能需要较长时间，并且在升级过程中 GitLab 会停机。请选择合适的维护窗口进行升级。

总结

通过本文的详细步骤，你已经学会了如何使用最简单、最推荐的方式——GitLab Omnibus 包——在一台 Linux 服务器上安装和配置自己的 GitLab 实例。从前期的环境准备、详细的安装步骤，到安装后的 HTTPS 配置、邮件发送、备份策略、性能调优和安全加固，我们覆盖了搭建一个可用、稳定、安全的 GitLab 所需的大部分核心环节。

自建 GitLab 为你提供了代码和数据的完全控制权，让你能够根据团队的特定需求进行深度定制和集成。虽然它需要一定的服务器管理和维护投入，但对于满足数据安全、合规性或特定性能需求的团队而言，这是非常值得的。

记住，GitLab 是一个功能强大的平台，除了核心的代码托管外，还有丰富的 CI/CD、Registry、Wiki、Issue Board 等功能等待你去探索和利用，以提升你的团队协作和开发效率。

希望这篇详细的指南能够帮助你顺利地搭建起属于你自己的 GitLab！如果在安装或使用过程中遇到任何问题，请查阅 GitLab 官方文档或社区寻求帮助。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部