很多人一开始接触GitLab都有个误区以为装好了GitLab就等于装好了Git或者说Git自带在这套服务里。实际完全不是这么回事。Git是一个分布式的版本控制工具跑在你本地或者任意一台服务器上的命令行工具GitLab是一个围绕Git搭建的Web协作平台提供仓库管理、合并请求、CI/CD这些能力。这两者一个是发动机一个是整车互相配合但不能互相替代。这篇文章我会围绕Linux环境下Git和GitLab的完整安装过程把每一步为什么要这样做、背后是什么逻辑、哪些坑我踩过全部摊开来讲。文中所有命令我都基于Ubuntu 22.04 LTS实测过CentOS / Rocky Linux的差异点我会单独标注。无论你是刚入行的后端开发者还是要给团队搭一套内部代码管理平台的运维这篇都能给你一个可以照着抄的作业。1. 先搞懂几个核心概念免得装完一脸懵1.1 Git和GitLab到底什么关系Git是一个命令行工具职责只有一个管理代码的版本历史。你在本地仓库里执行git init、git add、git commit所有操作都发生在本机不需要任何服务端。GitLab则是把Git仓库托管到一台中央服务器上让团队多个人可以拉取、推送、协作同时提供图形化界面、权限控制、代码审查流程。用个生活化的类比Git是你家里的个人账本GitLab是银行柜台。你可以在自家账本上记账账本不会消失但别人看不到你存进银行别人就能通过合规流程存取还有交易流水、对账单这些增值服务。所以安装顺序一定是先装Git再装GitLab——虽然GitLab安装包会自带一个精简的Git运行时用于内部操作但你在服务器上直接操作仓库时系统环境里的Git版本才是关键。1.2 版本选择GitLab CE vs EE以及安装方式GitLab有两个版本Community Edition社区版CE和Enterprise Edition企业版EE。CE免费功能上已经覆盖绝大多数中小团队需求像分支保护、合并请求审批、基础的CI/CD都有。EE多了LDAP高级映射、审计事件、多个K8s集群集成这类偏企业管理的能力普通团队基本用不上。安装方式主要有三种Omnibus包安装官方推荐的打包方式把Ruby、PostgreSQL、Redis、Nginx等所有组件打包成一个安装包一条命令装完运维最简单。源码安装理论上灵活实际是噩梦。依赖几十个组件版本还互相打架我试过一次就放弃了除非你有极强的定制需求否则别碰。Docker安装省事但数据卷映射、网络模式、升级时的数据迁移都有额外复杂度而且单机直接装Omnibus的性能更好。这篇教程选择的是Omnibus包安装这也是官方文档里最主推、社区案例最多的方案。后面涉及的所有路径、命令、配置文件格式都基于此。2. 环境准备装之前花10分钟省得后面折腾一天2.1 我推荐的服务器配置选型很多教程跳过环境规划直接给命令这是最坑人的。GitLab是全家桶服务PostgreSQL、Redis、Sidekiq、Puma这些进程全部常驻内存。我见过有人在1核1G的云服务器上硬装GitLab结果装完界面都打不开后台报OOM内存溢出错误查了半天不知道怎么回事。如果只是自己练手或个人使用建议至少2核4G内存。团队使用10人以上建议4核8G起步。Swap也建议开一下哪怕手动建一个4G的swap文件关键时刻能救命。磁盘方面SSD是硬性要求GitLab对IOPS很敏感机械盘在写仓库时会卡到怀疑人生。先检查系统信息free -h nproc cat /etc/os-release df -h2.2 系统镜像源更新与基础依赖安装任何东西之前先把系统的软件源更新到最新。腾讯云、阿里云这些国内服务器通常自带内部镜像源直接用就行。如果在海外服务器或者纯内网环境保持官方源也可以。sudo apt update sudo apt upgrade -yUbuntu系统下安装必要的基础工具链sudo apt install -y curl wget git vim ca-certificates perl openssl这些包里面最重要的是ca-certificates没有它后续访问HTTPS下载源会报证书错误这个坑我踩过不止一次。2.3 配置主机名与hosts解析GitLab安装时会以主机名作为默认访问地址。建议提前规划好对外访问的域名比如git.example.com。如果没有域名也可以直接用服务器的IP地址但后面配置HTTPS证书时会麻烦很多。修改主机名sudo hostnamectl set-hostname gitlab-server echo gitlab-server | sudo tee /etc/hostname同时确认/etc/hosts里有一条本机解析记录不然有些组件在启动时会因为解析不到主机名报错。echo 127.0.0.1 gitlab-server | sudo tee -a /etc/hosts这一步看起来不起眼实际价值很大GitLab内部的Gitaly、Puma等组件之间通信时都会走主机名解析如果hosts配置不对启动日志里会出现一堆“Connection refused”或者“Cannot resolve host”。3. 安装Git两种方式一个推荐一个备用3.1 方式一apt直接安装推荐大多数人用Ubuntu 22.04自带的软件源里Git版本大概是2.34对于绝大多数场景完全够用。安装命令sudo apt update sudo apt install -y git验证版本git --version git config --global init.defaultBranch main git config --global user.name 你的名字 git config --global user.email youexample.com这里特别提一下init.defaultBranch这个配置。Git默认的初始分支名是master但GitHub和GitLab新建仓库时普遍用main。改这个配置不是为了跟风而是为了少踩一个坑如果本地仓库默认分支是master而GitLab上新建项目默认分支是main第一次推送时就会出现“远端没有匹配分支”或需要手工设置上游的麻烦。提前统一分支名省掉这些沟通成本。3.2 方式二源码编译安装老版本系统的解决方案如果你的系统是CentOS 7或者更老的Ubuntu系统自带的Git版本可能停留在1.8或者2.0有些GitLab功能需要更高版本的Git客户端才能正常操作比如部分合并请求的底层命令依赖新版filter-branch。这时候建议自己编译安装最新版。先下载源码包以2.45.2为例实际版本可以到Git官网查当前最新版cd /tmp wget https://github.com/git/git/archive/refs/tags/v2.45.2.tar.gz tar -zxvf v2.45.2.tar.gz cd git-2.45.2编译前安装依赖sudo apt install -y make gcc libcurl4-openssl-dev libexpat1-dev gettext zlib1g-dev libssl-dev然后编译安装make prefix/usr/local all sudo make prefix/usr/local install验证是否生效hash -r git --version这里要留意一个细节源码编译安装的Git默认会装到/usr/local/bin而系统自带的旧版在/usr/bin。如果git --version显示还是老版本说明PATH里/usr/bin排在/usr/local/bin前面执行which git查看路径必要时把export PATH/usr/local/bin:$PATH写进/etc/profile。3.3 安装后立刻要做的三件事很多教程装完Git就急着装GitLab我建议先花两分钟把Git的全局配置弄利索尤其是如果你在服务器上不止一次地要把代码推到远端仓库的话这些配置能避免大量重复劳动。第一配置SSH密钥ssh-keygen -t ed25519 -C youexample.com一路回车生成默认密钥。然后把公钥加到GitLab的用户设置里后面装完GitLab会用到。第二配置autoCRLF相关的换行符行为。跨平台协作的项目里Windows和Linux的换行符差异一直很讨厌git config --global core.autocrlf input第三配置push默认行为git config --global push.default simple这个配置让git push只会推送当前分支到同名的远端分支避免误推所有分支。4. 安装GitLab CE一步一步走到能打开页面4.1 下载并配置GitLab软件源GitLab官方提供的是安装脚本但更可控的做法是自己添加软件源然后手动安装。以Ubuntu 22.04为例cd /tmp curl -LO https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh sudo bash script.deb.sh这个脚本做了两件事把GitLab的GPG公钥导入系统、在/etc/apt/sources.list.d/下创建gitlab_gitlab-ce.list文件。国内服务器如果下载慢可以把源地址里的packages.gitlab.com替换成国内镜像站的地址再把deb路径对应用上。软件源配置好之后更新索引并安装sudo apt update sudo apt install -y gitlab-ce安装包比较大大概600MB左右需要一点耐心。安装完成后会提示你下一步需要执行sudo gitlab-ctl reconfigure。4.2 修改external_url配置这一步是整个安装过程最关键的一步。GitLab安装完成后默认的访问地址是http://gitlab-server这个地址是准备阶段主机名的产物。如果要改成自己的域名或者服务器IP需要修改主配置文件sudo vim /etc/gitlab/gitlab.rb找到这行external_url http://gitlab.example.com改成你自己的地址external_url http://gitlab.example.com这里的协议头决定了GitLab内部Nginx是走HTTP还是HTTPS。如果你要配HTTPS这里直接写成https://gitlab.example.com然后再配证书GitLab会自动处理内部的TLS终止。修改完后执行重配置sudo gitlab-ctl reconfigurereconfigure这个过程会做很多事生成所有组件的配置文件、初始化数据库、启动所有服务。第一次跑需要3到5分钟后面每次改配置再跑就快多了。4.3 首次登录干掉默认的root密码GitLab首次启动时会为root用户生成一个临时密码存放位置sudo cat /etc/gitlab/initial_root_password如果这个文件不存在说明你的GitLab版本较新临时密码不会持久化写入文件需要通过另一个方式重置sudo gitlab-rails runner user User.find_by(username: root); user.password 新密码; user.password_confirmation 新密码; user.save!用浏览器访问配置好的external_url地址用root用户登录系统会强制要求修改密码。建议一登录就改因为GitLab的root账号等同于整个平台的管理员权限默认密码留在文件里总归不踏实。4.4 验证核心服务状态GitLab装好之后用这个命令查看所有组件状态sudo gitlab-ctl status正常情况下列表里会有run: postgresql、run: redis、run: gitaly、run: puma、run: sidekiq、run: nginx这些关键条目。如果某个组件显示down先看日志sudo gitlab-ctl tail这个命令会实时输出所有组件的日志排查问题时的第一利器。另外也建议顺手看看端口监听情况sudo ss -lntp | grep -E 80|443|8080|5432GitLab的Nginx默认监听80/443PostgreSQL监听5432仅限本机Puma监听8080Unicorn的默认端口新版用Puma目录不同但端口逻辑一样。5. 必做的安全加固与访问配置5.1 给GitLab配上HTTPSHTTP明文传输的密码简直就是裸奔。GitLab自带Nginx配HTTPS只需要三步。第一步把证书和私钥文件放到/etc/gitlab/ssl/目录下sudo mkdir -p /etc/gitlab/ssl sudo chmod 700 /etc/gitlab/ssl然后把证书文件命名为gitlab.example.com.crt私钥命名为gitlab.example.com.key。第二步修改/etc/gitlab/gitlab.rbexternal_url https://gitlab.example.com nginx[enable] true nginx[redirect_http_to_https] true第三步重新reconfiguresudo gitlab-ctl reconfigure这里我要特别提醒如果用的是自签名证书GitLab部分组件之间的内部通信也会校验证书可能需要在配置里额外设置letsencrypt[enable] false或者在客户端信任该证书。从生产角度建议直接用自动化平台签发的免费证书避免一堆自签名的“信任问题”。5.2 配置Nginx反向代理可选场景如果你的服务器上已经有一个Nginx在提供服务不想让GitLab独占80/443端口可以把GitLab的Nginx禁用用外部Nginx做反向代理。修改gitlab.rbnginx[enable] false然后在外部Nginx的配置文件里加上一段代理规则server { listen 80; server_name gitlab.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name gitlab.example.com; ssl_certificate /etc/ssl/gitlab.example.com.crt; ssl_certificate_key /etc/ssl/gitlab.example.com.key; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这个方案适合泛域名、多服务共存的架构。要注意的是GitLab的WebSocket用于实时日志和终端也需要相同的代理配置缺失会导致实时功能异常。5.3 邮件通知配置GitLab要有邮件通知功能注册验证、密码找回、合并请求提醒都靠它。以常见的SMTP服务为例修改gitlab.rbgitlab_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] 你的SMTP授权码 gitlab_rails[smtp_authentication] login gitlab_rails[smtp_tls] true这里强调一下“授权码”而非登录密码。现在主流的邮件服务商都要求用专用授权码登录SMTP用明文登录密码大概率报535错误。配置完成后用这个命令测试sudo gitlab-rails console在Rails控制台里执行Notify.test_email(receiverexample.com, Test Subject, Test Body).deliver_now能收到邮件就说明配置生效了。6. 日常运维备份、升级与迁移一次讲透6.1 用自带命令做备份GitLab的备份机制设计得比较完善备份内容包括数据库数据、Git仓库数据、附件文件、CI/CD配置。执行备份sudo gitlab-backup create备份文件默认存放在/var/opt/gitlab/backups/文件名类似1720000000_2024_07_07_16.8.0_gitlab_backup.tar。建议把/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json这两个配置文件单独备份缺了它们备份文件即使恢复了也用不了。这个坑我亲身经历过备份文件完好但secrets文件丢了所有仓库能恢复但Web端登录不了最后只能重置所有加密密钥等于重装。可以写一个cron任务定期备份0 2 * * * /usr/bin/gitlab-backup create /var/log/gitlab-backup.log 216.2 升级GitLab的完整流程GitLab升级有个铁律不能跨大版本直接跳只能逐版本升级。比如从16.0升到16.11再升到17.0。每升一次都要跑一次reconfigure和migratesudo apt update sudo apt install gitlab-ce sudo gitlab-ctl reconfigure sudo gitlab-ctl migrate升级前必须做一次备份备份后还要在测试环境先验证一遍恢复流程。生产环境升级前建议先停掉GitLab的写入sudo gitlab-ctl deploy-page up这条命令会展示一个维护页面防止用户在升级过程中提交数据。升级完成后取消维护页sudo gitlab-ctl deploy-page down还有一点升级GitLab CE版本时如果跨了大版本Gem和Node.js依赖可能不兼容表现为升级后页面白屏或500错误。此时到gitlab.rb里检查所有非默认配置多半是某个配置项已经废弃导致的。6.3 迁移到新服务器迁移场景在团队换了服务器或者云平台时很常见。迁移的核心思路是“版本完全一致配置文件完整迁移”步骤梳理如下在新服务器上安装相同版本的GitLab然后停掉新服务器的服务除了PostgreSQL和redis先停Nginx和Puma避免端口冲突sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq sudo gitlab-ctl stop nginx把旧服务器的备份文件和两个配置文件复制到新服务器对应目录scp /path/to/backup.tar usernew-server:/var/opt/gitlab/backups/ scp /etc/gitlab/gitlab.rb usernew-server:/etc/gitlab/ scp /etc/gitlab/gitlab-secrets.json usernew-server:/etc/gitlab/在新服务器上恢复备份sudo chmod 777 /var/opt/gitlab/backups/备份文件.tar sudo gitlab-backup restore BACKUP备份文件名不含.tar扩展名恢复完成后重新配置并启动所有服务sudo gitlab-ctl reconfigure sudo gitlab-ctl restart这里有个细节备份文件只有GitLab进程本身能读取手动恢复时需要调整文件权限为777恢复完再改回来否则可能出现“Permission denied”。7. 常见问题速查与实战解决以下问题都是我在不同服务器上真实遇到过的整理成速查表方便你排查时快速定位。现象可能原因排查命令与解决办法访问页面502Puma还没启动完成或内存不足sudo gitlab-ctl status、sudo gitlab-ctl tail puma等几分钟再刷新内存不足则加swap或升级配置页面503Nginx配置错误或reconfigure未执行检查/var/log/gitlab/nginx/error.log重新sudo gitlab-ctl reconfiguregit push时报403SSH密钥未添加到用户配置或IP白名单检查GitLab用户Settings里的SSH Keys本地用ssh -T gitgitlab.example.com测试git clone时报Permission denied公钥不匹配或本地用的是HTTP方式但密码错确认本地公钥是否已添加改用git开头地址克隆执行gitlab-rails时报Gem错误版本升级导致的依赖残留sudo gitlab-rake cache:clear必要时执行sudo gitlab-ctl clean数据库连接失败PostgreSQL未启动或数据目录损坏sudo gitlab-ctl status postgresql查看/var/log/gitlab/postgresql/日志修改external_url后页面商品图裂图片存储在别的主机名路径下修改配置后必须reconfigure如果之前域名变过需要迁移仓库路径定时备份文件越来越大备份没有清理机制在cron里加find /var/opt/gitlab/backups -mtime 7 -name *.tar -delete除了表格里的这些还有一个很隐蔽的问题服务器的系统时间不准会导致GitLab部分功能异常比如sidekiq里的定时任务不执行。排查时可以用date -R看一眼当前时间偏差超过几分钟就该配置NTP校正。8. 安装完成后把这些配置也顺手做了8.1 创建第一个项目并验证全链路安装配置全部完成后真正麻烦的是验证整条链路是否打通。新建一个项目从本机克隆、修改、推送、创建合并请求完整走一遍流程。新建项目后的HTTP克隆地址通常长这样http://gitlab.example.com/root/demo-project.git按GitLab提示的示例命令执行第一次推送git init git remote add origin http://gitlab.example.com/root/demo-project.git git add . git commit -m Initial commit git push -u origin main如果是SSH克隆地址则形如gitgitlab.example.com:root/demo-project.git。我第一次配完GitLab后HTTP方式推送中文文件名总是报编码警告后来发现是核心配置里core.quotepath默认关闭中文文件名在日志里显示成八进制转义。不耽误操作但看起来别扭可以改回来git config --global core.quotepath false8.2 给团队设置的用户管理策略GitLab装好只是开始团队真正用起来之后用户管理才是日常重点。推荐的做法是在Admin Area里关闭用户自助注册如果你只需要内部成员开启管理员审核新用户同时设置项目默认分支保护规则。在Admin Area → Settings → General把Sign-up restrictions里的Sign-up enabled关掉。这样可以避免服务器地址暴露后被人随便注册账号。项目层面的分支保护我习惯默认设置main分支禁止任何人直接推送所有代码必须通过Merge Request合入且至少需要一个人审批。这步做完团队里那种直接在main上改然后强推的坏习惯可以彻底杜绝。8.3 调整CI Runner如果有持续集成需求GitLab内置了强大的CI/CD功能但默认没有Runner流水线会一直卡在pending状态。安装Runner有两种路径一种是直接在服务器上装gitlab-runner二进制文件另一种是用Docker方式启动。单机上最省事的还是直接装Runnercurl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64 chmod x /usr/local/bin/gitlab-runner sudo useradd --comment GitLab Runner --create-home gitlab-runner --shell /bin/bash sudo gitlab-runner install --usergitlab-runner sudo gitlab-runner start注册Runner时需要的token在GitLab项目页面里找Settings → CI/CD → Runners。Runner注册时需要指定executor新手最容易踩的坑是选了shell executor后构建环境里什么都没装流水线第一步就报错。这个完全正常需要自己在Runner所在的服务器装好项目的构建依赖。9. 最后再分享几点实操体会GitLab这东西装一遍记忆深刻装三遍你就会发现大部分所谓“疑难杂症”其实都是同一个原因配置改完之后没有正确reconfigure或者升级时的顺序颠倒了。这是我踩过最多次的坑所以你在看任何教程时都要习惯把“reconfigure之后发生了什么”作为重点。我还有一个个人习惯每次修改gitlab.rb之前先cp一份备份到同目录再加时间戳后缀。比如cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak.20240707。别小看这个动作GitLab的配置文件里几百行Ruby语法一个引号写错就可能导致整个服务起不来有备份就随时能回退没有就只能靠记忆把改过的行一点点改回去。工具链路从Git到GitLab中间还牵扯到SSH、Nginx、PostgreSQL、Redis这些基础设施每一样单独拿出来都能写一篇长文。这篇教程最想帮你解决的问题是把“装起来”和“用好”之间那段谁都说不清的模糊地带趟平。如果你照着走完一遍本地能clone能pushWeb端能看到提交记录那这个平台就已经算正式跑起来了。后面的CI/CD流水线、代码质量检查、权限模型细化都可以在这个基础上慢慢加。版本管理工具永远是越用越理解而不是越学越会。