从零自建GitLab私有代码仓库：安装、配置与踩坑指南

先说个事。我见过不下十个人公司代码量涨到一定程度之后开始纠结要不要自己搭一套GitLab。用GitHub吧私有仓库要收费代码放在别人服务器上有些场景也不踏实用码云这类轻量仓库又总觉得在代码评审、分支保护这些环节上差点意思。GitLab 恰恰卡在这个位置社区版免费、能装在任意一台 Linux 服务器上、仓库加CI/CD全都有还支持私有化部署。这篇我就把从零开始装 GitLab 的完整过程包括我自己踩过的坑一次性写清楚。不管你是刚接触Linux的开发者还是公司里被拉去搭内部代码仓库的运维照着这个流程走基本不会卡壳。1. 为什么要自建GitLab仓库1.1 什么情况下适合自己装一套GitLab先说结论如果你满足下面任一条件自建GitLab就很值得。团队需要一套私有代码仓库但不想把代码放到外部平台。公司需要代码评审Merge Request、分支保护、Issue 追踪这些协作功能。局域网内开发希望代码不走公网速度更快、更可控。后续要上CI/CD希望仓库和流水线在同一个平台里完成。反过来如果只是一个人写点脚本、存几份代码备份那GitLab确实是杀鸡用牛刀了Gitea、Gogs这类几百MB的极简Git服务更合适。GitLab全家桶装完动辄占用几个GB内存一个人用纯属浪费。我团队以前就是先用的Gitea后来人多了发现代码评审没地方做、权限控制太弱才迁到GitLab。这个迁移过程倒是简单Git本身的兼容性特别好换平台基本等于改一下origin地址不过这属于后话后面我会提。1.2 硬件评估内存就是GitLab的命门GitLab是出了名的吃内存这一点没人能反驳。官方给的推荐配置是4GB内存起步但根据我自己在不同机器上的测试这个说法有点保守了。内存大小实际体验适用场景1GB - 2GB能装上但运行极不稳定频繁502一push代码就假死不推荐演示环境都够呛4GB可以稳定跑起来同时在线5人左右操作略卡小型团队勉强能用8GB体验顺畅20人以内日常开发没有压力大多数中小企业首选16GB及以上跑得飞起还能顺带跑几个GitLab Runner做CI/CD团队规模大或流水线需求重的场景除了内存CPU至少2核起磁盘强烈建议SSD。别觉得仓库就几个GBGit的每次操作都在和磁盘IO打交道机械硬盘在GitLab里跑起来会让你怀疑人生。还有一点容易被忽略系统盘和仓库数据盘最好分开。默认情况下GitLab数据全放在 /var/opt/gitlab 下如果系统盘只有20GB仓库大了很快就会被撑爆。有条件就加一块独立数据盘或者至少在装完系统后把数据目录迁移到大分区上。1.3 版本选型CE和EE怎么选GitLab分为社区版CECommunity Edition和企业版EEEnterprise Edition。CE完全免费EE试用期过后需要付费。很多人一看到“企业版”就以为功能更强其实对于绝大部分小团队来说CE已经覆盖了99%的日常需求仓库托管、Merge Request、Issue、Wiki、CI/CD基础能力CE全都包含。EE多出来的主要是LDAP group同步、先进审计事件、多集群Kubernetes管理等企业级功能。如果只是内部代码托管完全没必要为这些功能买单。另外提一句安装时千万别去网上找什么“破解版”“开心版”GitLab本身社区版够用而且这类非官方安装包很容易被植入后门代码仓库这东西出了问题泄露的可是公司全部源码安全问题开不得玩笑。还有系统选择上的建议。CentOS 7已经停止维护了新装环境就别再用了。当前阶段我推荐Ubuntu 22.04 LTS、Debian 12或者Rocky Linux 9这三类系统对GitLab的兼容性都很好社区的踩坑资料也最全。2. 安装前的环境准备2.1 系统更新与依赖安装不管安装什么服务我习惯第一步先把系统软件源刷新一遍能避免很多莫名其妙的依赖问题。以Ubuntu 22.04为例sudo apt update sudo apt upgrade -y然后安装GitLab依赖的基础包sudo apt install -y curl openssh-server ca-certificates这里有个可选组件是postfix也就是邮件服务。GitLab默认用它来发送注册邮件、密码找回邮件、仓库变更通知。如果你们公司已经有企业邮箱可以在GitLab里直接配置SMTP就不需要装postfix如果暂时不打算配邮件也可以在安装时跳过后续再补都是可以的。我实际装的时候第一次傻乎乎跟着官方文档全部装上结果虚拟机上postfix服务一直起不来还拖慢了启动时间。后来才知道用SMTP方式完全没必要装postfix这块属于文档里“默认不装也行”的选项。2.2 域名、IP和端口规划这一步特别重要很多人上来就装装完才发现地址不对又折腾重来。GitLab安装时需要指定一个“外部访问地址”也就是external_url这个地址一旦设置后面改起来虽然不难但会牵扯一堆配置同步能避免尽量避免。你需要提前想清楚两件事。第一用IP访问还是域名访问。如果只在公司内网用直接写IP就行比如 http://192.168.1.100。如果有域名并且想配置HTTPS证书那这里就写 https://git.example.com。GitLab默认会占用80端口HTTP和443端口HTTPS如果服务器上已经跑了Nginx、Apache或者其他Web服务需要提前把端口让出来或者在GitLab配置里把访问端口改掉。第二SSH端口规划。GitLab的SSH服务默认使用22端口用于git clone和git push操作。如果服务器上的22端口已经被你日常运维用的SSH占了通常都占了那就需要给GitLab指定一个新的SSH端口比如2222。这一步很多人都会忽略装完才发现clone代码走不了SSH只能用HTTP。2.3 安装方式选型Omnibus包 vs Docker镜像GitLab官方推荐的安装方式有两种Omnibus一体化包和Docker镜像。另外还有一种源码编译安装费时费力且升级痛苦这里就不推荐了。对比项Omnibus包Docker容器安装复杂度较低一个包搞定中等需理解容器概念配置方式集中在 /etc/gitlab/gitlab.rb环境变量或挂载配置文件升级难度一条命令直接升拉新镜像重建容器数据迁移直接打包备份目录挂载卷注意别搞丢资源占用相对较少略高一点点适用场景大多数生产环境首选已有Docker体系追求环境隔离我的建议是如果你对Linux有一定了解直接用Omnibus包这是GitLab官方的主要支持路径网上所有教程基本也都是基于这种方式写的出了问题好排查。如果你本身就在用Docker管理一堆服务那用Docker方式也不错迁移方便。下面我先把Omnibus方式讲透Docker方式单独在第四章讲。3. 完整安装过程Omnibus包方式3.1 配置软件源GitLab官方软件源在 packages.gitlab.com国内直接下载速度经常只有几十KB每秒一个几百MB的包要下几个小时。这里推荐把软件源切换成清华Tuna镜像速度快且稳定这是国内装GitLab最常用的操作。以Ubuntu 22.04代号jammy为例先把GitLab CE的镜像源写进aptecho deb https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/gitlab-ce.list然后导入GitLab官方GPG密钥让系统信任这个源curl -fsSL https://packages.gitlab.com/gitlab/gitlab-ce/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/gitlab_gitlab-ce-archive-keyring.gpg更新一下软件源缓存sudo apt update如果你用的不是Ubuntu 22.04需要把源地址里的 jammy 替换成你自己系统的代号。Rocky Linux / AlmaLinux 用户则使用对应的清华源地址格式上换成yum仓库配置即可核心思路是一样的。3.2 执行安装并设置访问地址软件源配置完成后安装GitLab CE就一条命令sudo apt install -y gitlab-ce安装过程会自动把GitLab的各个组件部署好包括Nginx、PostgreSQL、Redis、Puma等整个过程大概几分钟取决于网络和机器性能。安装完成后GitLab会提示你修改配置文件。打开 /etc/gitlab/gitlab.rbsudo vim /etc/gitlab/gitlab.rb找到这一行改成你规划好的外部访问地址external_url http://192.168.1.100如果你提前规划好了SSH端口也在这里一并设置gitlab_rails[gitlab_shell_ssh_port] 2222保存退出后执行重配置命令sudo gitlab-ctl reconfigure这里要插一句reconfigure是GitLab最常用也最重要的命令。它会根据 gitlab.rb 里的配置重新生成所有组件的配置文件启动服务并做一次全面的健康检查。整个执行过程会有大量输出最后出现类似 gitlab Reconfigured! 的提示就表示成功了。配置完成后检查一下各组件的运行状态sudo gitlab-ctl status正常情况下run: postgresql、run: redis、run: puma、run: sidekiq 等都是绿色的running状态。3.3 安装后的目录结构和验证方法GitLab装好后你不需要知道每个组件具体怎么运行但至少要清楚三个关键目录/etc/gitlab配置文件目录gitlab.rb就在里面改配置就改这里。/var/opt/gitlab数据目录仓库数据、数据库文件、备份文件都在这下面。/var/log/gitlab日志目录排查问题全靠它。验证安装是否成功直接在浏览器里访问你设置的external_url地址。第一次访问会进入GitLab的初始配置页面要求你设置root管理员密码。设置完成后用root账号和刚设置的密码登录就进入GitLab主页面了。这里有个坑提醒一下如果你的服务器是云主机记得在安全组或者防火墙里放行80端口或者你自定义的HTTP端口不然外网访问不了这个问题经常让人误以为安装失败了。3.4 内存紧张时的经济型配置装好后如果你发现GitLab运行缓慢或者只有4GB内存可以通过修改 gitlab.rb 来裁剪掉一些不必要的组件。以降低Puma worker数量为例puma[worker_processes] 2 puma[min_threads] 4 puma[max_threads] 8减小PostgreSQL占用的共享内存postgresql[shared_buffers] 256MB关闭Prometheus监控小团队其实用不上prometheus_monitoring[enable] false改完记得重新执行sudo gitlab-ctl reconfigure这一套组合拳打下来GitLab在4GB内存的机器上稳定运行基本没问题。不过我要说实话这只是“能用”想获得非常好的体验内存还是8GB起步比较好。GitLab官方文档里有一句话我很认同它默认安装的组件是为企业级场景准备的在小机器上要主动做减法。4. Docker方式安装GitLab4.1 一条命令完成容器部署如果你已经是Docker玩家用容器方式部署GitLab会特别顺手。首先准备一个数据目录export GITLAB_HOME/srv/gitlab sudo mkdir -p $GITLAB_HOME然后运行容器sudo docker run --detach \ --hostname git.example.com \ --publish 443:443 --publish 80:80 --publish 2222:22 \ --name gitlab \ --restart always \ --volume $GITLAB_HOME/config:/etc/gitlab \ --volume $GITLAB_HOME/logs:/var/log/gitlab \ --volume $GITLAB_HOME/data:/var/opt/gitlab \ --shm-size 256m \ gitlab/gitlab-ce:latest这里有几个参数要解释一下--hostname容器内GitLab识别的主机名需要和外部访问域名一致。--publish端口映射把宿主机的80、443、2222分别映射到容器的对应端口。需要注意容器内部SSH服务默认还是22这里把宿主机的2222映射到了容器的22相当于对外暴露了一个SSH端口2222。--volume数据卷挂载把配置、日志、数据都放到宿主机目录这样即使容器不小心删了数据也不会丢。--shm-size给共享内存设置256MB这个参数可以避免PostgreSQL在容器里因为/dev/shm空间不足而崩溃。--restart always服务器重启后容器自动拉起省心。容器起来后进入容器修改配置sudo docker exec -it gitlab /bin/bash后续操作就和Omnibus方式一样了改 /etc/gitlab/gitlab.rb然后执行 gitlab-ctl reconfigure。4.2 Docker版的数据备份与升级Docker的优势在于环境隔离和部署标准化但数据安全千万不要忽视。备份方式很简单sudo docker exec -t gitlab gitlab-backup create备份文件会生成在挂载的 /srv/gitlab/data/backups 目录下。升级时先拉取新版本镜像再停掉旧容器用同样的参数重新创建新容器sudo docker pull gitlab/gitlab-ce:latest sudo docker stop gitlab sudo docker rm gitlab sudo docker run --detach \ --hostname git.example.com \ --publish 443:443 --publish 80:80 --publish 2222:22 \ --name gitlab \ --restart always \ --volume $GITLAB_HOME/config:/etc/gitlab \ --volume $GITLAB_HOME/logs:/var/log/gitlab \ --volume $GITLAB_HOME/data:/var/opt/gitlab \ --shm-size 256m \ gitlab/gitlab-ce:latest容器启动完成后配置和数据会因为挂载卷的存在全部保留升级基本无感。我实际用Docker部署过一次升级体验确实比Omnibus还要省事唯一要注意的就是别把挂载卷搞错了那里面装的是你公司的全部代码。5. 初始化配置与管理操作5.1 首次登录和修改root密码GitLab装好后第一步肯定是登录管理后台。由于刚才装的时候已经设置了root初始密码直接用它登录即可。但有一种情况需要注意如果你在 gitlab.rb 里配置了下面这一项那root密码就会用配置里指定的初始密码gitlab_rails[initial_root_password] 你的初始密码如果没有预先设置也可以直接修改GitLab后台的登录页面地址通过手动方式把root密码改掉。具体做法是进入服务器执行sudo gitlab-rails runner user User.find_by(username: root); user.password 新的密码; user.password_confirmation 新的密码; user.save!这种修改方式比在网页端找回密码更直接特别适合忘记初始密码的情况。5.2 配置SSH密钥SSH密钥是Git用户日常使用频率最高的功能配置不好很影响体验。首先在本地电脑生成密钥ssh-keygen -t ed25519 -C your_emailexample.com一路回车就能生成公钥文件默认在 ~/.ssh/id_ed25519.pub。查看内容cat ~/.ssh/id_ed25519.pub复制输出登录GitLab网页端点击右上角头像选择 Edit profile进入左侧SSH Keys菜单把公钥粘贴进去保存。然后本地测试连通性ssh -T git192.168.1.100如果出现 Welcome to GitLab, username! 就说明配置成功了。注意如果你把GitLab的SSH端口改成了2222那在clone和push时不能直接用默认配置需要手动改一下 ~/.ssh/configHost gitlab HostName 192.168.1.100 Port 2222 User git这样后面就可以直接用 git clone gitgitlab:group/project.git 这种方式拉代码不用每次手动指定端口舒服很多。5.3 关闭注册和加密通信GitLab默认开放注册功能任何访问到你服务器的人都能自己注册账号。如果这是公司内部的仓库建议立刻关闭不然等运维后台被一堆垃圾账号淹没的时候再清理就麻烦了。在 gitlab.rb 中加一行gitlab_rails[gitlab_signup_enabled] false重新执行sudo gitlab-ctl reconfigure从此注册按钮就消失了只有管理员能主动创建用户。关于HTTPS如果你有域名和有效的SSL证书建议配置上代码在公网传输时更安全。不过内网环境通过IP访问时通常直接HTTP就行这一项可以根据你的实际场景来选择不是必须项。5.4 开启SMTP邮件通知这一项可以加速代码评审的效率因为GitLab的很多操作比如有人你、指派给你MR都要靠邮件通知来驱动。如果装了postfix但没配好反而会产生大量退信日志建议直接走SMTP。以常见的企业邮箱为例在 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_enable_starttls_auto] true gitlab_rails[smtp_tls] true配置完记得 reconfigure然后在后台的用户设置里给自己发一封测试邮件能收到就说明没问题。6. 仓库创建与日常使用6.1 创建项目并推送代码安装和配置搞定后重点就回到日常使用了。GitLab的项目组织和GitHub类似先有命名空间用户或Group然后在命名空间里创建项目。建议团队内部先创建一个Group比如叫 dev然后成员都加入这个Group项目统一建在Group下面。这样做的好处是权限可以统一管理以后不管是加人还是调整权限都在Group这一层操作省心很多。在网页端创建好项目后本地推送代码的命令完全和GitHub一致git init git remote add origin git192.168.1.100:dev/jiaocheng.git git add . git commit -m init project git push -u origin master如果你用的是HTTP方式推送时GitLab会要求输入用户名和密码。这里有个细节要注意GitLab从13版本开始HTTP推送不支持账号密码直接认证需要使用Personal Access Token。在用户设置里生成一个token然后把它当密码用这算是很多新手比较容易卡壳的地方。6.2 用户权限与分支保护GitLab的权限模型分五个级别Guest访客、Reporter报告者、Developer开发者、Maintainer维护者、Owner所有者。日常开发里绝大多数成员给Developer就够用了Maintainer只给小组长或核心成员Owner只有这个项目的创建者才需要。分支保护是GitLab做得好的一个点。新建的GitLab项目master或main分支默认就是受保护状态普通Developer不能直接push必须通过Merge Request由Maintainer审核后才能合并。这个机制能强制团队走代码评审流程对代码质量提升真的立竿见影。如果你们团队规模小平时就几个人碰代码觉得审核流程太麻烦也可以在 项目设置 - 仓库 - 受保护分支 里临时把保护去掉。但说实话我建议还是保留代码评审这个习惯养成以后线上事故都能少很多。7. 常见问题与排查技巧7.1 502 Bad Gateway这是GitLab新手遇到最多的状况没有之一。现象是浏览器能打开GitLab的登录页但提交操作时页面刷不出来或者直接显示502。502的本质是Nginx已经启动但后面的Puma或者旧版本的Unicorn没有正常响应。大概率是内存不足。用下面的命令看组件状态sudo gitlab-ctl status你会发现 puma 是 down 的。再看日志sudo gitlab-ctl tail puma如果日志里有内存分配失败的报错基本可以确定是内存不够了。解决办法参考第三章的“经济型配置”把Puma的worker调低关闭Prometheus或者直接加内存。还有一种可能是端口被占用了Puma默认端口是8080如果服务器上已经跑了Tomcat或者其他服务占用了8080Puma也起不来。这种情况检查一下就行ss -lntp | grep 80807.2 端口冲突和防火墙导致无法访问装完GitLab后如果网页打不开先排除端口问题。在服务器本地执行curl -I http://127.0.0.1如果本地能返回响应说明GitLab本身没问题问题一定出在防火墙或安全组。Ubuntu上的防火墙操作sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw reload云服务器的话还要去云控制台检查安全组的入方向规则把80端口打开。这个问题我帮人排查过很多次本地curl一切正常外网就是打不开最后基本都是安全组的问题。7.3 SSH连接失败的各种情况SSH连不上GitLab常见的报错有三种。第一种ssh: connect to host 192.168.1.100 port 22: Connection refused要么是服务端SSH端口不对要么是防火墙没放行。如果你改了GitLab的SSH端口一定要记得在防火墙和安全组里同时放行这个新端口。第二种Permission denied (publickey,keyboard-interactive)说明SSH连接是通的但服务器不认你的密钥。先检查公钥是否添加到了GitLab后台再检查你本地用的密钥路径是不是默认的 ~/.ssh/id_*。第三种The authenticity of host ... cant be established.这是第一次连接时的指纹确认提示输入yes回车即可不用慌。7.4 磁盘空间不足与日志膨胀GitLab跑久了日志文件和数据库会慢慢把磁盘吃掉。尤其是 /var/log/gitlab 和 /var/opt/gitlab/git-data 这两个目录前者是日志后者是仓库数据。查看磁盘占用sudo du -sh /var/log/gitlab/* | sort -rh | head -10GitLab本身有logrotate机制但如果你发现某个日志文件特别大可以手动清一下注意不要直接删除日志文件本身用下面的方式截断它sudo truncate -s 0 /var/log/gitlab/nginx/gitlab_access.log还有一个大坑是仓库回收站GitLab删除项目后不会立即清理磁盘数据而是在后台异步清理需要定期执行sudo gitlab-rake gitlab:cleanup:repos另外建议给数据目录挂一块大容量磁盘这样即使日志出了问题也不至于把系统盘塞满导致整个服务器挂掉。7.5 备份与恢复GitLab的备份机制很成熟一定要利用起来。备份所有仓库和数据库sudo gitlab-backup create备份文件会生成在 /var/opt/gitlab/backups 目录下按时间戳命名。恢复备份前先停止相关服务防止数据写入sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq然后执行恢复sudo gitlab-backup restore BACKUP备份文件的时间戳恢复完成后启动所有服务sudo gitlab-ctl start这里划重点备份和恢复的GitLab版本最好一致跨大版本恢复容易出问题。所以升级GitLab前一定要先备份万一升级失败还能退回原版本。我个人的习惯是在crontab里加一条定时备份任务每天凌晨自动备份一次保留最近7天的备份文件0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON1有这层保障至少不用担心仓库数据莫名其妙丢了。为了让你查找方便我把上面这些问题整理成了速查表现象可能原因优先排查方式502 Bad Gateway内存不足或Puma没起来gitlab-ctl status查看puma状态网页无法访问防火墙或安全组没放行服务器本地curl测试SSH连接被拒SSH端口不对或防火墙拦截ss -lntp 查看监听端口SSH公钥认证失败公钥未添加或密钥路径不对检查后台SSH Keys设置磁盘被占满日志膨胀或仓库回收站未清理du -sh 查看各目录占用push代码报权限错误分支受保护或token未配置检查分支保护设置8. 收尾给新手的几条实操建议最后再分享几个我装过那么多次GitLab之后的个人体会。第一第一次安装之前把你规划的 external_url 和 SSH 端口写在纸上打开配置文件直接填进去然后 reconfigure。这个动作能避免九成“装完改配置”的返工。第二如果没有特殊需求直接装社区版不要碰乱七八糟的二次开发版和所谓企业版破解包。GitLab社区版本身已经很重了没必要再给自己埋雷。第三版本升级前一定、一定、一定先备份。GitLab的版本升级有时候涉及到数据库结构变更如果跨版本太多官方会让你先升级到中间版本再继续跳版本升级是很多人升级失败的主要原因。第四装好之后顺手开一个项目把团队的编码规范或者新人入职文档放进去让大家先熟悉GitLab的MR流程。很多人装完GitLab就用它存代码其实代码评审、Issue管理、CI/CD这些功能才是它真正的价值所在。一开始就把这些用起来团队协作的效率提升是非常明显的。如果你准备继续深入下一步建议了解GitLab Runner把CI/CD流水线搭起来让提交代码后自动构建、自动部署。这一块配合本文搭建的GitLab正好能拼出整套DevOps基础设施。到时候你会发现之前折腾的这台服务器可不只是一个代码仓库那么简单了。