在 RHEL 上安装 GitLab

适用于：✅ RHEL 10, ✅ RHEL 9, ✅ RHEL 8 及其衍生版

I. 环境配置

1.1 开放相关端口

要打开所需的防火墙端口（80、443、22）并能够访问 GitLab：

1.启用并启动 OpenSSH 服务器守护进程：

1
sudo systemctl enable --now sshd

2.打开防火墙相关服务端口：

1
2
3
4
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-service=ssh
sudo systemctl reload firewalld

II. 安装 GitLab

2.1 在线安装

2.1.1 添加包存储库

1.安装所需软件包：

1
sudo dnf install -y curl

2.使用以下脚本添加 GitLab 仓库：

企业版

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

社区版

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

2.1.2 安装 GitLab

使用您系统的软件包管理器安装 GitLab。

企业版

1
sudo dnf install gitlab-ee

社区版

1
sudo dnf install gitlab-ce

2.2 离线安装

2.2.1 支持平台

GitLab 为不同平台提供 Linux 软件包，建议下载前查看不同平台官方最后支持的 GitLab 版本。

2.2.2 最新版本

如果你当前使用的平台未超过官方最后支持的 GitLab 版本，建议安装官方最新发布的版本。

2.2.3 下载离线包

从 GitLab 仓库筛选你计划安装的离线安装包并下载。

2.2.4 安装依赖

1.查看当前版本 GitLab 需要哪些依赖包👇

2.查看安装平台是否已经安装依赖包

1
dnf list installed <软件名>

3.安装依赖包

1
sudo dnf install -y perl-interpreter policycoreutils-python-utils

2.2.5 安装 GitLab

1
2
# 请将文件名替换为你实际下载的文件名
sudo dnf install gitlab-ee-18.x.x-ee.0.el8.x86_64.rpm

2.3 查看 GitLab 状态

1
systemctl status gitlab-runsvdir

III. 配置 GitLab

3.1 配置 URL

官方文档：Configuration options for Linux package installations | GitLab Docs

编辑 /etc/gitlab/gitlab.rb 文件，将 external_url 修改为您首选的 URL 。

1
external_url 'https://gitlab.example.com'

3.2 配置 SSL

3.2.1 启用 Let’s Encrypt 集成

官方文档：Configure SSL for a Linux package installation | GitLab Docs

中文文档：NGINX settings - GitLab Omnibus - GitLab 文档中心

3.2.2 手动配置 HTTPS

你可以通过 Certbot 或 acme.sh 申请 SSL 证书，本文不再赘述。

3.3 完整配置

本文使用 Nginx 反向代理 GitLab ，由于外部 Nginx 会处理 SSL，我们需要让内置 Nginx 只监听 HTTP 请求。

💡Tips：external_url 建议先配置为 GitLab 服务器 IP 访问，待测试完成后再修改为 HTTPS 域名访问。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# GitLab 对外访问地址（必须是公网域名）
external_url 'https://gitlab.example.com'

# 禁用 Let’s Encrypt 集成功能
letsencrypt['enable'] = false

################################################################################
## GitLab NGINX
##! Docs: https://docs.gitlab.com/omnibus/settings/nginx.html
################################################################################

# 告知 GitLab 它处于反向代理之后, 用于接收外部 Nginx 转发的流量
nginx['listen_port'] = 80
nginx['listen_https'] = false

# 允许 GitLab 接收代理头信息
nginx['proxy_set_headers'] = {
  "Host" => "$http_host_with_default",
  "X-Real-IP" => "$remote_addr",
  "X-Forwarded-For" => "$proxy_add_x_forwarded_for",
  "X-Forwarded-Proto" => "https",
  "Upgrade" => "$http_upgrade",
  "Connection" => "$connection_upgrade"
}

# 添加反向代理 IP（填写前置代理真实 IP）
nginx['real_ip_trusted_addresses'] = [ '172.16.18.11' ]
# 其他 real_ip 配置选项
nginx['real_ip_header'] = 'X-Forwarded-For'
nginx['real_ip_recursive'] = 'on'

################################################################################
## gitlab.yml configuration
##! Docs: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/gitlab.yml.md
################################################################################

## 强烈建议做好暴露 SSH 安全防护！！！

# 只有 SSH 域名和 Web 域名不一致时才需要修改这里
#gitlab_rails['gitlab_ssh_host'] = 'gitlab.example.com'

# 可信代理，确保能获取真实用户 IP（填写前置代理真实 IP）
gitlab_rails['trusted_proxies'] = ['172.16.18.11']

# SSH 对外展示端口（前置代理服务器端口）
gitlab_rails['gitlab_shell_ssh_port'] = 56343

📢注意：GitLab 会在每次重新配置时尝试更新任何 Let’s Encrypt 证书。若您计划使用自行手动创建的证书，必须禁用 Let’s Encrypt 集成功能，否则自动更新机制可能导致证书被覆盖。

3.3 应用配置

1
sudo gitlab-ctl reconfigure

3.4 检查服务状态

1
sudo gitlab-ctl status

💡Tips：systemctl 与 gitlab-ctl 的关系
在 GitLab 的架构中，systemctl 处于最高层级，而 gitlab-ctl 是它的“项目经理”。
systemctl：负责管理 GitLab 的“总开关”（即 runsvdir 守护进程）。如果这个总开关关了，GitLab 的所有子服务（Nginx, Redis, PostgreSQL 等）都会全部强制停止。
gitlab-ctl：这是 GitLab 自带的管理工具，它通过 runit 监控并管理内部的 20 多个子服务。

IV. Nginx 配置

📢注意：GitLab 服务器和 Nginx 服务器需在防火墙放行相关端口。如果是云服务器（如阿里云、腾讯云），除了系统内部防火墙，还需要在云平台的安全组/防火墙设置中放行相关端口。

4.1 配置 Web 代理

在 /etc/nginx/conf.d/gitlab.conf 中创建：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
upstream gitlab_web_upstream {
    # GitLab 服务器的内网 IP 和端口
    server 172.16.18.12:80;
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name gitlab.example.com;
    # 强制跳转 HTTPS
    return 301 https://$server_name$request_uri;
}

# HTTPS 代理
server {
    listen 443 ssl;
    server_name gitlab.example.com;

    # SSL 证书路径
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # 其它 SSL 配置
    ssl_session_timeout   60m;
    ssl_session_cache     shared:MozSSL:10m;
    ssl_protocols         TLSv1.2 TLSv1.3;
    ssl_ciphers           ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305;
    ssl_prefer_server_ciphers on;

    # 关键代理参数
    location / {
        # 后端 GitLab 服务器
        proxy_pass http://gitlab_web_upstream;

        # 与后端协议一致性
        proxy_set_header Host              $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 $scheme;

        # 支持 WebSocket 连接
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # 超时优化
        proxy_connect_timeout 60s;
        proxy_send_timeout    300s;
        proxy_read_timeout    300s;

        # 传输优化
        client_max_body_size 250m;
        proxy_buffering off;
    }
}

4.2 配置 SSH 代理

这是开启 SSH 转发的关键。编辑 Nginx 主配置文件 /etc/nginx/nginx.conf。注意：stream 块必须在 http 块之外。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
user nginx;
worker_processes auto;
# ... 其他配置 ...

http {
    # 这里是原本的 http 配置，包含上面的 include /etc/nginx/conf.d/*.conf;
    # 如果请求头中有 Upgrade，则设置 Connection 为 upgrade，否则为 close
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    # ... 其他配置 ...
}

# 添加以下 stream 块进行 TCP 转发
stream {
    upstream gitlab_ssh_upstream {
        # 转发到 GitLab 服务器的 SSH 端口
        server 172.16.18.12:22;
    }

    server {
        # 互联网访问的 SSH 端口
        listen 56343;
        proxy_pass gitlab_ssh_upstream;
        proxy_connect_timeout 60s;
        proxy_timeout 300s;
    }
}

4.3 测试并重启 Nginx

1
2
sudo nginx -t
sudo systemctl restart nginx

V. 初始登录

5.1 初始密码

GitLab 为 root 管理员账户生成随机密码和电子邮件地址，并将其存储在 /etc/gitlab/initial_root_password 文件中，保存时限为 24 小时。出于安全考虑，该文件将在 24 小时后自动删除。

1
sudo cat /etc/gitlab/initial_root_password

5.2 初始登录

安装 GitLab 后，请访问您设置的 URL，并使用以下凭据登录：

用户名：root
密码：请查看 /etc/gitlab/initial_root_password

📢注意：登录后，请修改您的密码和电子邮件地址。

5.3 重置密码

1.进入控制台。在 GitLab 服务器上执行以下命令：

1
sudo gitlab-rails console -e production

2.查找并重置管理员密码。进入控制台界面（出现 irb(main):001:0> 提示符）后，依次输入以下命令：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 1. 找到管理员账号（ID 通常为 1，或者按用户名 root 查找）
user = User.find_by_username('root')

# 2. 设置新密码（注意：密码至少需要 8 位字符）
user.password = 'YourNewStrongPassword123'

# 3. 确认新密码
user.password_confirmation = 'YourNewStrongPassword123'

# 4. 保存更改
user.save!

# 5. 退出控制台
exit

📢注意：在输入 user.save! 后，如果返回 true，说明修改成功；如果返回一堆报错，通常是因为密码太简单（不符合 GitLab 的复杂度要求）。

VI. 后续步骤

参考文档：Steps after installing GitLab | GitLab Docs

重点关注：Secure GitLab | GitLab Docs

6.1 关闭用户注册

选择本地部署 GitLab 一般都是仅供内部用户使用，当内部用户注册完成后，为了安全起见，建议关闭新用户注册通道。

登录后台依次进入：Admin Area -> Settings -> General -> Sign-up restrictions

❎（取消勾选）Sign-up enabled -> Save Changes

6.2 关闭遥测数据

登录后台依次进入：Admin Area -> Settings -> Metrics and profiling -> Usage statistics。

❎（取消勾选）Enable Service ping -> Save Changes

VII. 常见问题

7.1 HTTP 502

7.1.1 报错提示

7.1.2 解决方案

1.查看端口占用，Gitlab 默认使用以下两个端口：

前端网页端口：默认 80
后端服务端口：默认 8080

如果确认端口被占用，请检查并修改 /etc/gitlab/gitlab.rb

1
2
3
4
5
# 内部 Nginx 监听端口（给前置代理用的）
nginx['listen_port'] = 18080 

# 修改 Puma 的监听端口
puma['port'] = 18081

修改后执行：

1
2
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

2.检查服务状态，执行以下命令查看所有组件是否都在 run 状态：

1
sudo gitlab-ctl status

点关注：puma, gitaly, postgresql, redis。如果某个服务显示 down 或者 run 的时间（uptime）一直在重置（例如总是 0s 或 1s），说明它正在反复重启。

追踪实时日志（定位报错根源），这是最有效的方法。运行以下命令并刷新浏览器：

1
sudo gitlab-ctl tail puma

根据浏览器提示解决相关问题，如：

内存不足：如果看到 Out of memory 或 Worker timeout，说明服务器内存爆了。
权限问题：如果看到 Permission denied，可能是某些目录的权限在手动操作中被改动了。

7.2 422

7.2.1 报错提示

7.2.2 解决方案

首先按照官方配置文档检查你的配置，其次网络上有很多提到清除浏览器缓存或在无痕窗口中登录解决，都可以尝试。

作者这里的报错其实是犯了个低级错误，我在 external_url 里配置的是 https://git.example.com ，为了在本地测试我没有修改 HTTPS 域名访问，直接访问的是 GitLab 服务器 http://172.16.x.x ，GitLab 会认为这是一个不安全的跨站请求，从而拒绝登录。知道了原因，解决方案当然就是先临时修改为 IP 访问，测试完成后再修改为 HTTPS 域名访问。

📢注意：修改后执行 gitlab-ctl reconfigure ，测试完请改回 HTTPS 域名访问。

VIII. 参考文档

Installation methods | GitLab Docs

Offline GitLab | GitLab Docs

通过 Nginx 代理实现互联网访问…GitLab

I. 环境配置#

1.1 开放相关端口#

II. 安装 GitLab#

2.1 在线安装#

2.1.1 添加包存储库#

2.1.2 安装 GitLab#

2.2 离线安装#

2.2.1 支持平台#

2.2.2 最新版本#

2.2.3 下载离线包#

2.2.4 安装依赖#

2.2.5 安装 GitLab#

2.3 查看 GitLab 状态#

III. 配置 GitLab#

3.1 配置 URL#

3.2 配置 SSL#

3.2.1 启用 Let’s Encrypt 集成#

3.2.2 手动配置 HTTPS#

3.3 完整配置#

3.3 应用配置#

3.4 检查服务状态#

IV. Nginx 配置#

4.1 配置 Web 代理#

4.2 配置 SSH 代理#

4.3 测试并重启 Nginx#

V. 初始登录#

5.1 初始密码#

5.2 初始登录#

5.3 重置密码#

VI. 后续步骤#

6.1 关闭用户注册#

6.2 关闭遥测数据#

VII. 常见问题#

7.1 HTTP 502#

7.1.1 报错提示#

7.1.2 解决方案#

7.2 422#

7.2.1 报错提示#

7.2.2 解决方案#

VIII. 参考文档#