适用于：✅ 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 安装到指定目录#
💡Tips：在 Rocky Linux 8 上通过 RPM 包（dnf install）安装 GitLab 时，由于其采用了 Omnibus 封装机制，官方并不支持像普通软件那样在安装时通过参数自定义安装路径。
GitLab 的 Omnibus 安装包强制遵循 Linux 标准目录结构。不过，你可以通过 “软链接（Symbolic Link）” 或 “修改配置文件” 的方式，将占用空间最大的数据目录转移到你指定的存储位置。
2.3.1 使用软链接#
如果你希望整个 GitLab（包括程序和数据）都“看起来”在另一个目录（例如 /path/gitlab），可以在安装前创建软链接。
1.准备目录：
1
2
3
4
| mkdir -p /path/gitlab/opt
mkdir -p /path/gitlab/data
mkdir -p /path/gitlab/etc
mkdir -p /path/gitlab/log
|
2.创建软链接，在执行 dnf install 之前，先建立链接，欺骗安装程序：
1
2
3
4
| ln -s /path/gitlab/opt /opt/gitlab
ln -s /path/gitlab/data /var/opt/gitlab
ln -s /path/gitlab/etc /etc/gitlab
ln -s /path/gitlab/log /var/log/gitlab
|
📌关键目录说明,在决定安装位置时，请参考以下目录的功能：
| 默认目录 | 用途 | 建议操作 |
|---|
/opt/gitlab | 程序文件（约 2GB+） | 若根分区小，建议用方法一软链接。 |
/var/opt/gitlab | 核心数据（仓库、数据库） | 空间占用最大，建议挂载大硬盘。 |
/etc/gitlab | 配置文件（含密钥） | 必须定期备份，体积很小。 |
/var/log/gitlab | 日志文件 | 随时间增长，建议定期清理或移走。 |
3.执行安装：
1
2
| # 请将文件名替换为你实际下载的文件名
sudo dnf install gitlab-ee-18.x.x-ee.0.el8.x86_64.rpm
|
此时，虽然程序认为它装在 /opt/gitlab，但物理文件实际存储在 /path/gitlab/opt。
2.3.2 修改配置文件#
如果你已经安装好了，或者只想把**最占空间的数据（仓库、数据库）**移走，而保留程序在默认位置，可以修改 gitlab.rb 。
1.修改配置文件，编辑 /etc/gitlab/gitlab.rb：
1
| sudo vi /etc/gitlab/gitlab.rb
|
2.修改关键路径参数，搜索并取消注释以下行，改为你的目标目录：
1
2
3
4
5
6
7
| # 修改 Git 仓库存储路径
git_data_dirs({
"default" => { "path" => "/data/gitlab-data" }
})
# 修改 PostgreSQL 数据库存储路径
postgresql['data_dir'] = "/data/gitlab-postgres"
|
3.生效配置：
1
| sudo gitlab-ctl reconfigure
|
2.4 查看 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.4 应用配置#
1
| sudo gitlab-ctl reconfigure
|
3.5 检查服务状态#
3.5.1 查看所有服务的概览状态#
输出解读：
run: 表示服务正常运行。
down: 表示服务已停止。
uptime: 显示服务已运行的时长（秒）。
PID: 显示该服务的进程 ID。
3.5.2 查看特定服务的状态#
如果你怀疑某个特定组件（例如数据库）有问题，可以只查看它的状态：
1
2
3
4
5
| # 查看 PostgreSQL 状态
sudo gitlab-ctl status postgresql
# 查看 Redis 状态
sudo gitlab-ctl status redis
|
3.5.3 使用 GitLab 检查工具#
如果你能进入系统但某些功能异常，可以使用 GitLab 的内部检查脚本。它会测试配置文件、数据库连接和文件权限等。
1
| sudo gitlab-rake gitlab:check
|
📢注意：这个命令运行时间较长，因为它会执行一系列深度检查。如果看到大量的 OK，说明系统配置基本正常。
3.5.4 实时查看运行日志#
如果 status 显示服务正在运行，但网页打不开，查看实时日志是排查问题的最佳手段：
1
2
3
4
5
| # 查看所有服务的实时日志 (Ctrl+C 退出)
sudo gitlab-ctl tail
# 只查看 Nginx 的访问日志
sudo gitlab-ctl tail nginx/gitlab_access.log
|
💡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，并使用以下凭据登录：
📢注意：登录后，请修改您的密码和电子邮件地址。
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. 卸载 GitLab#
7.1 停止 GitLab 服务#
在卸载软件包之前，先停止所有运行中的 GitLab 组件，以防止文件占用或卸载过程中出现异常。
7.2 使用 dnf 移除软件包#
使用 dnf 命令卸载主程序：
1
| sudo dnf remove gitlab-ee
|
7.3 清理残留的服务进程#
有时候卸载后仍会有残留的 runit 服务进程。建议检查并清理：
1
2
3
4
5
| # 确认是否还有 gitlab 相关的进程
ps -ef | grep gitlab
# 如果有残留，可以尝试强制停止
sudo gitlab-ctl terminate
|
7.4 删除数据和配置#
📢注意：此步骤会永久删除所有仓库、数据库和配置文件。执行前请确认已备份重要数据。
1
2
3
4
5
6
7
8
| # 删除配置文件
sudo rm -rf /etc/gitlab
# 删除数据目录（包括仓库、数据库等）
sudo rm -rf /var/opt/gitlab
# 删除日志文件
sudo rm -rf /var/log/gitlab
|
GitLab 有时会创建一些临时挂载点。如果发现无法删除目录，请检查挂载情况：
1
2
3
4
5
| # 查看是否有残留挂载
mount | grep gitlab
# 如果有，手动卸载
sudo umount /var/opt/gitlab/....
|
VIII. 常见问题#
8.1 HTTP 502 错误#
8.1.1 报错提示#
8.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 状态：
点关注：puma, gitaly, postgresql, redis。如果某个服务显示 down 或者 run 的时间（uptime）一直在重置（例如总是 0s 或 1s），说明它正在反复重启。
追踪实时日志（定位报错根源），这是最有效的方法。运行以下命令并刷新浏览器：
1
| sudo gitlab-ctl tail puma
|
根据浏览器提示解决相关问题，如：
8.2 422 错误#
8.2.1 报错提示#
8.2.2 解决方案#
首先按照官方配置文档
检查你的配置，其次网络上有很多提到清除浏览器缓存或在无痕窗口中登录解决，都可以尝试。
小凡这里的报错其实是犯了个低级错误，我在 external_url 里配置的是 https://git.example.com ，为了在本地测试我没有修改 HTTPS 域名访问，直接访问的是 GitLab 服务器 http://172.16.x.x ，GitLab 会认为这是一个不安全的跨站请求，从而拒绝登录。知道了原因，解决方案当然就是先临时修改为 IP 访问，测试完成后再修改为 HTTPS 域名访问。
📢注意：修改后执行 gitlab-ctl reconfigure ，测试完请改回 HTTPS 域名访问。
IX. 参考文档#
Installation methods | GitLab Docs
Offline GitLab | GitLab Docs
通过 Nginx 代理实现互联网访问…GitLab
