CentOS9 GitLab 完整配置全流程

一、前言

GitLab 是一款开源的代码托管与 DevOps 协作平台，本文基于 CentOS 7/CentOS 8 系统，采用 YUM 离线 / 国内镜像源 方式，从零到一完成 GitLab 安装、基础配置、端口修改、邮件通知、性能优化、备份恢复、防火墙放行、常见报错解决等全流程，适合个人搭建、企业内部代码仓库部署。

环境说明

• 系统：CentOS 7.9 / CentOS 8.x
• 安装方式：YUM（国内清华镜像，下载速度快）
• GitLab 版本：GitLab CE 社区版（最新稳定版）
• 硬件最低要求：2 核 4G（1 核 2G 极易卡顿、启动失败）
• 本文所有命令均为 root 权限执行

二、前期环境准备（必做）

2.1 关闭防火墙 / 放行端口（二选一）

生产建议放行端口，不直接关闭防火墙。

bash

运行

# 1. 查看防火墙状态
systemctl status firewalld

# 方式一：临时关闭（测试环境）
systemctl stop firewalld
systemctl disable firewalld

# 方式二：放行 GitLab 端口（生产推荐，默认80，自定义端口自行替换）
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
# 若修改端口为 8080，执行：firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload
firewall-cmd --list-ports

2.2 安装依赖包

GitLab 依赖 ssh、邮件服务、policycoreutils 等组件：

bash

运行

yum install -y curl policycoreutils-python openssh-server openssh-clients postfix cronie

2.3 启动 SSH & Postfix 服务

bash

运行

# 开机自启+启动 ssh
systemctl enable sshd && systemctl start sshd

# 邮件服务（用于仓库通知、找回密码）
systemctl enable postfix && systemctl start postfix

三、配置国内 YUM 源（解决官网下载慢）

默认官方源网络较差，推荐使用清华大学 GitLab 镜像源。

3.1 创建 GitLab YUM 源文件

bash

运行

vim /etc/yum.repos.d/gitlab-ce.repo

写入以下内容：

ini

[gitlab-ce]
name=Gitlab CE Repository
baseurl=https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/yum/el$releasever/
gpgcheck=0
enabled=1

• el$releasever：自动适配 CentOS 7/8
• gpgcheck=0：关闭密钥校验，避免证书报错

3.2 刷新 YUM 缓存

bash

运行

yum clean all
yum makecache

四、安装 GitLab CE 社区版

4.1 执行安装

bash

运行

# 安装最新稳定版
yum install -y gitlab-ce

安装过程约 3~10 分钟，耐心等待，出现 Complete! 代表安装完成。

4.2 查看 GitLab 版本

bash

运行

gitlab-ctl version

五、GitLab 核心配置（gitlab.rb 主配置）

GitLab 所有自定义配置集中在 /etc/gitlab/gitlab.rb，修改配置后必须执行 gitlab-ctl reconfigure 生效。

5.1 编辑主配置文件

bash

运行

vim /etc/gitlab/gitlab.rb

5.2 配置外部访问地址（必改）

找到 external_url，取消注释并修改为服务器公网 IP / 域名 + 端口。

ruby

# 默认端口 80
external_url 'http://192.168.1.100'

# 自定义端口（例如 8080），后续 Nginx 会自动监听该端口
# external_url 'http://192.168.1.100:8080'

注意：external_url 决定浏览器访问地址，端口修改后防火墙必须同步放行。

5.3 自定义 Nginx 端口（可选，默认 80）

如果服务器 80 端口被 Nginx、Apache 占用，必须修改：

ruby

# 取消注释，修改端口
nginx['listen_port'] = 8080

5.4 配置邮件通知（找回密码、MR 通知，推荐）

以 QQ 邮箱 SMTP 为例（163、企业邮箱配置逻辑一致）：

ruby

# 开启 SMTP
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.qq.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "你的QQ邮箱@qq.com"
# QQ 邮箱授权码（非登录密码，QQ邮箱→设置→账户→开启SMTP获取）
gitlab_rails['smtp_password'] = "邮箱授权码"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = true
# 发件人邮箱
gitlab_rails['gitlab_email_from'] = '你的QQ邮箱@qq.com'

5.5 性能优化（低配服务器必做）

1 核 2G/2 核 4G 服务器默认配置极易卡顿，添加以下优化参数：

ruby

# Unicorn 进程优化（CPU核数+1，最高不超过4）
unicorn['worker_processes'] = 2
unicorn['worker_timeout'] = 60

# PostgreSQL 数据库优化（降低内存占用）
postgresql['shared_buffers'] = "256MB"

# 关闭无用监控组件（减少资源消耗）
prometheus['enable'] = false
alertmanager['enable'] = false
node_exporter['enable'] = false
redis_exporter['enable'] = false

六、重载配置并启动 GitLab（关键步骤）

6.1 使所有配置生效

bash

运行

gitlab-ctl reconfigure

该命令会自动初始化数据库、启动所有组件，首次执行耗时较长，不要中断。

6.2 常用服务命令

bash

运行

启动所有服务 gitlab-ctl start # 停止所有服务 gitlab-ctl stop # 重启所有服务 gitlab-ctl restart # 查看所有组件状态 gitlab-ctl status # 查看实时日志（排错必备） gitlab-ctl tail

7.1 访问地址

浏览器输入：http://你的服务器IP:端口（默认 80 可省略端口）

八、GitLab 备份与恢复（生产必备）

8.1 手动备份

备份文件默认存放路径：/var/opt/gitlab/backups

bash

运行

# 执行备份
gitlab-rake gitlab:backup:create

8.2 配置自动定时备份

1. 修改 gitlab.rb 指定备份路径与保留时间

ruby

# 自定义备份目录
gitlab_rails['backup_path'] = "/mnt/gitlab_backup"
# 备份保留 7 天（单位：秒）
gitlab_rails['backup_keep_time'] = 604800

重载配置：gitlab-ctl reconfigure

1. 配置 crontab 定时任务

bash

运行

crontab -e

添加（每天凌晨 2 点自动备份）：

bash

运行

0 2 * * * /usr/bin/gitlab-rake gitlab:backup:create >> /var/log/gitlab_backup.log 2>&1

8.3 备份恢复（故障回滚）

bash

运行

# 1. 停止 GitLab 数据服务
gitlab-ctl stop puma
gitlab-ctl stop sidekiq

# 2. 执行恢复（替换为你的备份文件名）
gitlab-rake gitlab:backup:restore BACKUP=备份文件名

# 3. 重启服务
gitlab-ctl restart

九、常见报错 & 避坑指南

9.1 访问页面 502 错误

• 原因：内存不足、Unicorn 启动失败
• 解决：升级服务器内存至 2 核 4G ，或降低 unicorn['worker_processes'] = 1，重启 GitLab。

9.2 gitlab-ctl reconfigure 卡住不动

• 原因：磁盘空间不足、yum 源异常
• 解决：清理磁盘，重新执行 yum makecache，再次重载配置。

9.3 初始密码文件不存在

• 原因：已执行过 reconfigure 超过 24 小时
• 解决：重置 root 密码

bash

运行

gitlab-rails console -e production
# 依次执行
user = User.where(username: 'root').first
user.password = '新密码'
user.save!
exit

9.4 端口被占用

• 现象：Nginx 启动失败
• 解决：修改 gitlab.rb 中 nginx['listen_port'] 为未占用端口，并放行防火墙。

十、GitLab 日常使用基础操作

10.1 创建项目

1. 登录账号 → New project
2. 填写项目名称、描述、可见级别（私有 / 公开）
3. 创建完成后，获取仓库 SSH/HTTPS 地址。

10.2 Git 本地关联远程仓库

bash

运行

# 本地初始化
git init
# 关联远程仓库
git remote add origin 仓库地址
# 提交代码
git add .
git commit -m "first commit"
git push -u origin main

十一、总结

1. 优先使用国内清华 YUM 源，解决下载慢问题；
2. external_url 是访问核心，端口修改必须同步放行防火墙；
3. 低配服务器必须做性能优化，否则频繁 502、卡顿；
4. 生产环境务必关闭匿名注册 + 配置定时备份；
5. 所有配置修改后，必须执行 gitlab-ctl reconfigure 生效。