CentOS 7安装GitLab CE完全指南：从环境准备到高频故障排查

你手里有没有一台吃灰的CentOS 7服务器如果有我强烈建议给它装一套GitLab CE社区版。团队内部搭建代码托管、CI/CD和文档库这应该是成本最低、最容易上手的方案之一。GitLab CE自带代码仓库、Issues、Merge Request、CI/CD以及Wiki不用像其他轻量方案那样反复折腾插件也比自己裸写Git服务器省心太多。我在CentOS 7环境上反复装过很多次也踩过不少坑这篇就把“从零到能日常使用”的关键点一次性说透。在开始之前还是要提醒一句CentOS 7本身已经进入维护末期如果你是新项目建议评估是否直接上更新的发行版。但内网存量服务器的情况千奇百怪很多团队仍然跑在CentOS 7上。这篇安装经验仍然有参考价值。1. 安装GitLab前先想清楚这三件事1.1 系统版本、内存与磁盘规划装之前先确认你的系统确实是CentOS 7的最小安装不是CentOS 8也不是别人做过裁剪的“精简镜像”。很多人装到一半发现依赖对不上就是因为系统本身不干净。先用这条命令看一眼cat /etc/redhat-release free -h df -h看到CentOS Linux release 7.x再继续。内存和磁盘是决定GitLab能不能正常跑起来的关键。GitLab官方给的最低内存要求是4GB低于这个数虽然能装上但执行 reconfigure 的时候非常容易内存耗尽进程被系统杀掉最后页面打不开或者一直502。我给一个比较实际的参考表配置项最低要求建议配置内存4GB8GB及以上CPU2核4核及以上磁盘20GB可用空间50GB以上SSD更好Swap无4GB以上磁盘这块要特别留意。GitLab默认把仓库数据、数据库、备份文件都放在/var/opt/gitlab如果系统盘只有30GB可能用两三个月就满了。建议安装前先单独分一个数据盘比如挂载到/data后面再通过配置把GitLab的数据目录迁过去。如果你手头只有2GB内存的机器也不是不能用但一定要先加Swap。很多人在小内存机器上装失败其实不是GitLab的问题是Swap没配。这里先给一个创建4GB Swap的命令后面第5章还会再展开sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab1.2 域名、端口与external_url的选择external_url是/etc/gitlab/gitlab.rb里最核心的参数它决定了GitLab对外暴露的地址也决定了项目克隆地址、Webhook回调地址、邮件里的链接显示成什么。所以这个值必须从安装第一天就想清楚不建议随手填一个。如果只是在公司内网局域网使用最稳妥的做法是填服务器的IP比如external_url http://192.168.1.100这样同事在浏览器里访问http://192.168.1.100就能打开GitLab克隆项目时也会自动生成正确的IP地址。如果你有内部域名也可以填http://git.example.com但要保证DNS能解析到这台服务器。端口选择也很重要。GitLab自带Nginx默认监听80端口。如果这台机器上已经跑了Apache、Nginx或者其他Web服务80端口大概率冲突。这种情况下不要强行停掉现有服务更优雅的做法是让GitLab换一个端口比如external_url http://192.168.1.100:8081如果以后要启用HTTPSexternal_url要写成https://git.example.com并配置证书。这里要特别注意从HTTP换到HTTPS或者换域名都要重新执行gitlab-ctl reconfigure否则Nginx监听和生成链接都不会生效。1.3 防火墙与SELinux对安装的影响CentOS 7默认开着 firewalldSELinux也是 enforcing 状态。这两个东西在安装过程中一般不会报错但装完以后外部访问不了十有八九是它们挡的。防火墙处理比较简单内网场景直接放行HTTP/HTTPS服务sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --reload如果是自定义端口比如8081要单独放行sudo firewall-cmd --permanent --add-port8081/tcp sudo firewall-cmd --reloadSELinux稍微隐蔽一点。GitLab自带的Nginx在SELinux的管控范围内如果不开httpd_can_network_connect这个布尔值Nginx即使启动成功也连接不上后端的Unix Socket表现出来就是浏览器一直502。正确做法是放行它sudo setsebool -P httpd_can_network_connect 1-P参数表示持久化重启服务器后依然生效。不建议一上来就把SELinux关闭那样虽然省事但会破坏安全基线后续审计也不好交代。先尝试放行布尔值绝大多数场景都够用了。2. 在CentOS 7上安装GitLab CE的完整步骤2.1 安装依赖组件在敲安装命令前先把系统依赖补齐。GitLab依赖curl、policycoreutils、openssh-server、openssh-clients和postfix其中policycoreutils用于管理SELinux策略postfix用于发通知邮件。CentOS 7最小化安装很可能缺这些包直接执行sudo yum install -y curl policycoreutils policycoreutils-python openssh-server openssh-clients postfix sudo systemctl enable --now postfixpostfix这里很容易踩坑。很多CentOS 7的/etc/hosts里没有配好主机名解析postfix启动时会报Name or service not known导致邮件组件起不来。如果遇到这种情况检查一下/etc/hosts把当前服务器的IP和主机名对应关系加进去再启动postfix192.168.1.100 gitlab-server如果只是内网测试暂时不需要邮件通知postfix起不来不影响GitLab本身。但后面配置SMTP邮件时还要用这块能力不如现在就解决掉。2.2 配置GitLab CE的Yum源GitLab CE默认不在CentOS 7的系统源里需要先添加一个yum源。官方源网络不稳定我习惯用国内镜像源加速。创建/etc/yum.repos.d/gitlab-ce.repo内容如下注意把mirrors.example.com替换成你实际使用的镜像域名sudo tee /etc/yum.repos.d/gitlab-ce.repo EOF [gitlab-ce] namegitlab-ce baseurlhttps://mirrors.example.com/gitlab-ce/yum/el7/ gpgcheck1 gpgkeyhttps://mirrors.example.com/gitlab-ce/yum/gpg.key enabled1 EOF写完后刷新缓存顺便验证源能否正常访问sudo yum clean all sudo yum makecache如果这里的URL写错了或者镜像还没同步完执行yum makecache会直接报404。这时候不要急先检查baseurl末尾的/是否存在再确认镜像仓库的目录结构是yum/el7还是el7不同镜像站的路径略有差异。如果服务器完全在内网隔离环境没法访问外网镜像那就提前准备好rpm安装包。比如下载gitlab-ce-16.x.x-ce.0.el7.x86_64.rpm文件然后上传到服务器用本地方式安装sudo yum localinstall ./gitlab-ce-16.x.x-ce.0.el7.x86_64.rpm用yum localinstall比直接rpm -ivh更好因为yum会自动解决依赖问题。这也是为什么前面先装依赖包的原因。2.3 执行安装与版本锁定源配好之后正式安装就只剩一条命令了sudo yum install -y gitlab-ceGitLab CE的安装包体积比较大一般有几百MB具体大小取决于版本耐心等着就行。安装脚本执行完以后终端会提示你还没有运行gitlab-ctl reconfigure不用急先做配置再执行。如果想安装指定版本避免被yum拉到最新版可以这样指定sudo yum install -y gitlab-ce-16.x.x-ce.0.el7.x86_64生产环境我非常建议锁定版本。CentOS 7的系统源里GitLab CE如果直接跑yum update有可能被升级到不再支持el7的新版本升级后 reconfigure 大概率报错甚至直接起不来。锁版本其实很简单CentOS 7下用yum-versionlocksudo yum install -y yum-versionlock sudo yum versionlock add gitlab-ce以后有明确的升级需求时再用sudo yum versionlock delete gitlab-ce解锁。我见过太多人因为手滑执行了yum update把GitLab升到不兼容版本最后只能降级重装项目数据虽然还在但折腾成本非常高。3. GitLab核心配置与参数调整3.1 external_url填错了会怎样安装完成后第一件正事就是编辑/etc/gitlab/gitlab.rbsudo vim /etc/gitlab/gitlab.rb搜external_url这一项默认是被注释掉的示例值。改成你自己的实际访问地址比如external_url http://192.168.1.100填错会怎样我见过有人图省事填了http://localhost结果自己本机访问一切正常同事从别的电脑登录以后页面上所有项目克隆地址都变成localhost点哪里都连不上。这个值不是只给Nginx用的它会被写进GitLab生成的各种链接里包括API地址、Webhook回调、SSH克隆地址和通知邮件里的链接。如果你访问GitLab时在页面右上角看到“当前地址与配置不一致”之类的提示多半就是这个参数没对齐。从HTTP改成HTTPS也一样改完必须重新执行 reconfigure否则后端数据里的地址还是旧的。3.2 调整数据存储与备份目录GitLab默认把数据放在/var/opt/gitlab包括Git仓库、PostgreSQL数据库文件、上传文件、备份文件等。如果系统盘空间不够可以考虑把数据目录独立出来。比如我习惯把数据放到/data/git-datagit_data_dirs({ default { path /data/git-data } })备份目录也可以单独指定gitlab_rails[backup_path] /data/gitlab-backups改完之后先创建目录再执行 reconfiguresudo mkdir -p /data/git-data /data/gitlab-backups sudo chown -R git:git /data/git-data sudo chown -R git:git /data/gitlab-backups sudo gitlab-ctl reconfigure这个权限特别容易漏。如果不给git用户目录权限reconfigure 不会立刻报错但后续在网页上新建项目、推送代码时会出现权限拒绝或仓库创建失败日志里会有Permission denied。所以目录权限一定要在 reconfigure 之前处理掉。3.3 合理设置内存与Worker线程GitLab由多个子组件组成Nginx、PostgreSQL、Redis、Puma、Sidekiq、Prometheus等。默认配置其实是为了服务器资源充足的情况准备的。如果你的内存只有4GB我建议做下面这些调整。打开/etc/gitlab/gitlab.rb找到对应配置改成puma[worker_processes] 2 puma[min_threads] 1 puma[max_threads] 4 postgresql[shared_buffers] 256MB prometheus_monitoring[enable] falseprometheus_monitoring这一项很关键。GitLab内置监控组件会跑很多额外的Ruby进程在低配机器上纯属浪费直接关掉能省不少内存。worker_processes设为2基本够一个小团队使用CPU核数更多时可以适当调大。线程数同理不用照抄大厂的模板。改完执行sudo gitlab-ctl reconfigure执行完之后用free -h看内存变化。如果还是很高检查Swap是否已开启。低配机器上 reconfigure 本身就是一个吃内存的操作所以不要在服务器已经跑了很多业务进程的时候去跑它尽量在刚装完、负载比较低的时候做。3.4 SMTP邮件通知配置GitLab离开邮件通知基本是残废的用户注册、密码找回、Issue变更提醒全部要走邮件。默认配置下GitLab用本机postfix直接发信但很多云服务器会封25端口公网邮件也容易被拒。最省事的办法是配置一个SMTP中继。在/etc/gitlab/gitlab.rb里添加类似下面这段配置具体参数按你实际使用的邮件服务商来填gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.example.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] gitlabexample.com gitlab_rails[smtp_password] 你的密码 gitlab_rails[smtp_domain] example.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_tls] true如果邮件服务商使用的是587端口把smtp_tls改成smtp_starttls_auto相关参数。执行 reconfigure 后可以在GitLab后台的“管理区域→监控→邮件”页面测试发送。也可以在命令行验证sudo gitlab-rails console Notify.test_email(收件人example.com, 测试邮件, 内容).deliver_now密码里如果包含特殊字符比如、#Ruby字符串引号里的转义要小心。我习惯把密码放在单引号里避免被YAML解析出错。别问我是怎么知道的问就是曾经因为密码里有#导致配置文件被注释掉一半邮件模块直接起不来。4. 初始化、登录与日常运维操作4.1 reconfigure的触发时机gitlab-ctl reconfigure是GitLab最核心的命令之一很多人误以为它只是“初始化用的”其实它的作用是让系统读取/etc/gitlab/gitlab.rb里的配置重新生成本地配置并重启受影响的组件。以下场景都必须执行安装完成后第一次初始化修改external_url修改数据目录、备份目录调整Puma、PostgreSQL等组件参数修改SMTP配置执行过程中可能持续几分钟会执行数据库迁移和配置渲染。如果中途报错终端会输出摘要常见的是端口占用、目录权限不对、内存不足。不用慌先看报错末尾的提示处理后重新执行一次。这里特别提醒有人改完gitlab.rb后不执行 reconfigure然后抱怨“为什么页面没变化”。GitLab不是傻瓜式热加载配置文件改完必须触发一次重跑这不是bug是设计如此。日常运维里改完配置忘执行 reconfigure 的概率比我预想的高得多。4.2 首次登录与安全设置reconfigure 完成后浏览器访问你填的external_url第一次会打开设置root密码的页面。实际上GitLab安装时会临时生成一个初始密码文件路径是/etc/gitlab/initial_root_password里面记录了root账户的临时密码。如果你错过了临时文件或者密码文件已经过期删除可以直接用控制台重置root密码sudo gitlab-rails console user User.find_by_username(root) user.password 新密码 user.password_confirmation 新密码 user.save!刚装好的GitLab默认允许任何人注册账号。即使是内网环境我也建议立刻关闭公开注册否则任何人都能来注册一个账号代码仓库安全就无从谈起了。关闭方式有两种一是网页后台的管理员设置里取消“注册开启”二是在gitlab.rb加一行gitlab_rails[gitlab_signup_enabled] false再 reconfigure。除此之外root账号建议开启两步验证代码仓库是公司核心资产就算不暴露公网也别在这上面偷懒。4.3 常用运维命令与备份恢复日常运维其实不需要记太多命令把下面这些用熟就够了命令作用sudo gitlab-ctl status查看各组件运行状态sudo gitlab-ctl stop/start/restart启停GitLab全部组件sudo gitlab-ctl tail查看所有日志sudo gitlab-ctl tail puma只看Puma日志sudo gitlab-rake gitlab:env:info查看版本和配置信息sudo gitlab-backup create创建完整备份sudo gitlab-backup restore BACKUP时间戳恢复指定备份备份这块我多说几句。新版GitLab统一使用gitlab-backup create老版本用的是gitlab-rake gitlab:backup:create如果你查到老资料注意区分。备份文件会生成在backup_path目录下命名类似1735689600_2025_01_01_gitlab_backup.tar。恢复备份前必须停掉两个写入相关的服务sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq sudo gitlab-backup restore BACKUP1735689600_2025_01_01恢复完成后重启所有服务。如果不先停 Puma 和 Sidekiq数据库和文件可能处于写入状态恢复出来很可能是损坏的。我建议在 crontab 里加一条定时备份0 2 * * * /usr/bin/gitlab-backup create 2 /var/log/gitlab-backup.log find /data/gitlab-backups -name *_gitlab_backup.tar -mtime 7 -delete每天凌晨2点备份保留最近7份这样既不会占用太多磁盘又能防止仓库数据因为误删或机器故障彻底消失。5. 安装和运行中的高频问题排查5.1 yum源拉取失败或速度极慢症状是执行yum install gitlab-ce时一直卡在下载或者报404、找不到repo。这种情况先看两个地方yum repolist | grep gitlab curl -I https://mirrors.example.com/gitlab-ce/yum/el7/如果repolist里没有gitlab-ce说明源配置没生效检查/etc/yum.repos.d/gitlab-ce.repo是否存在、内容是否有语法错误。如果 curl 返回404看baseurl路径和镜像站的实际目录结构是否一致。镜像站同步有时候比官方源晚一两天刚发布的新版本可能在镜像源上还找不到。这时候要么等同步要么直接用官方源的rpm包离线安装。离线安装我推荐sudo yum localinstall ./gitlab-ce-*.rpm它比rpm -ivh更智能会自动处理依赖。安装前记得先yum clean all yum makecache清理掉旧的repo缓存防止缓存了错误的元数据。5.2 低配服务器安装卡住或无法启动症状是在小内存机器上执行 reconfigure 时终端提示Killed或者gitlab-ctl status看到 puma、postgresql 反复重启。基本可以断定是内存不够。先把Swap加上给系统一个缓冲空间sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile然后把/etc/fstab里加一行持久化配置否则重启后Swap就没了/swapfile none swap sw 0 0内存极度紧张时可以临时把Puma的worker降到1同时关闭Prometheus监控减轻内存负担。但说实话如果只有2GB内存即使装上GitLab也只适合几个人偶尔用人数一多还是会卡。真要让GitLab顺畅跑起来内存至少加到4GB这是硬条件。5.3 80端口被占用、Nginx冲突怎么处理如果在 reconfigure 时看到类似nginx: [emerg] bind() to 0.0.0.0:80 failed的日志说明80端口已经被占用。先查端口占用情况sudo netstat -tlnp | grep :80如果确认是系统里的Nginx或Apache占了80而你又不需要它们直接停掉并禁用sudo systemctl stop nginx sudo systemctl disable nginx如果这些Web服务是其他业务在用的不能停就给GitLab换个端口external_url http://192.168.1.100:8081 nginx[listen_port] 8081改完执行 reconfigure。这里要注意GitLab自带的Nginx监听的是0.0.0.0修改端口后要保持external_url里的端口和listen_port一致否则访问时会出现地址带端口但实际监听另一个端口的乌龙。5.4 页面一直502或504的排查路径502代表Nginx已经启动但连接不上后面的Puma/Unicorn服务504代表Puma处理请求超时。这两个都是GitLab内部服务没有正常工作的信号。排查顺序很重要。第一步看整体状态sudo gitlab-ctl status确认 postgresql、redis、puma、sidekiq 都是run。如果有组件是down或者不断重启继续看日志sudo gitlab-ctl tail puma常见原因有三个内存不足导致Puma被杀、磁盘满导致PostgreSQL无法写入、Unix Socket文件权限异常。处理时先看内存和磁盘free -h df -h如果是权限问题可以试着重置目录属主再重启Pumasudo chown -R git:git /var/opt/gitlab sudo gitlab-ctl restart puma刚执行完 reconfigure 的那几分钟内出现短暂502不算异常等组件全部拉起来再刷新页面即可。如果持续502就要按上面的路径认真排查了。5.5 防火墙、SELinux导致外部访问不了如果本机curl http://192.168.1.100能正常返回页面但其他电脑访问超时基本可以断定是被防火墙或SELinux挡了。先按防火墙排查sudo firewall-cmd --list-all如果没有放行HTTP/HTTPS执行sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --reload自定义端口就单独放行对应端口。如果是云服务器还要去云控制台的安全组里确认入方向规则没有挡住端口。安全组和操作系统防火墙是两层缺一个都进不来。防火墙没问题再看SELinuxgetenforce如果是Enforcing放行Nginx的网络连接sudo setsebool -P httpd_can_network_connect 1如果提示找不到setsebool命令说明缺少policycoreutils-python用yum补装即可。个人经验是遇到外部访问不了的问题按“云安全组→本机防火墙→SELinux→GitLab服务状态”这个顺序排查绝大多数情况下十分钟内能定位。不要一上来就怀疑GitLab坏了其实它往往很无辜。