1. 项目概述为什么要在Linux上自建GitLab如果你是一名开发者、运维工程师或者是一个小团队的负责人你肯定对代码版本管理不陌生。Git是事实上的标准但GitHub、Gitee这类托管平台对于企业内网开发、代码资产私有化或者有严格合规要求的场景就显得不那么“趁手”了。这时候GitLab就进入了视野。它不仅仅是一个Git仓库管理器更是一个集成了CI/CD、项目管理、代码审查等功能的DevOps一体化平台。在Linux服务器上部署一套自己的GitLab意味着你拥有了一个完全自主可控、功能强大的代码协作中心。我见过不少团队一开始图省事用公共仓库或者简单的Git服务器但随着项目复杂度提升和团队规模扩大代码审查流程混乱、自动化部署缺失、权限管理粗放等问题就暴露出来了。回过头来再部署GitLab往往要经历一次痛苦的迁移。所以我的建议是如果你的项目有长期发展的打算或者团队成员超过3人尽早搭建自己的GitLab环境是性价比极高的投资。今天我就以一名多年运维和开发者的角度带你走一遍在Linux以Ubuntu 22.04 LTS为例上从零开始安装、配置GitLab的完整流程并分享那些官方文档里不会写的“踩坑”经验和调优技巧。2. 安装前的关键决策与准备工作在敲下第一条安装命令之前有几个关键的决策点需要想清楚。这直接决定了后续安装的顺利程度和系统的长期稳定性。盲目开始很可能中途遇到各种版本冲突、资源不足的问题导致推倒重来。2.1 硬件与系统需求评估GitLab对资源是有一定要求的尤其是当用户量和项目数增长后。官方给了一个最低配置但那真的只是“能跑起来”。CPU与内存这是最重要的部分。对于一个小团队10人以下的初期使用我建议至少分配2核CPU和4GB内存。注意这个4GB是空闲内存也就是说如果你的服务器总共只有4GB系统本身占用一部分后GitLab可能会因为内存不足而运行缓慢甚至崩溃。因此服务器总内存最好有8GB。如果用户更多或启用了大量CI/CD流水线请考虑8核16GB或更高配置。存储你需要考虑两部分存储。一是系统盘用于安装GitLab软件和操作系统二是数据盘用于存放仓库数据、CI/CD产物、容器镜像等。后者会随着时间快速增长。务必为/var/opt/gitlab目录GitLab默认数据目录准备充足的空间我建议单独挂载一块高性能的SSD数据盘容量至少100GB起步并做好监控和扩容计划。操作系统GitLab官方对主流Linux发行版都有很好的支持如Ubuntu、Debian、CentOS/RHEL等。我个人更推荐Ubuntu LTS版本如20.04 22.04因为其社区活跃软件包更新及时遇到问题也更容易搜索到解决方案。本文将以Ubuntu 22.04 LTS作为示范环境。注意切勿在配置过低的机器上安装否则你会被无尽的“502错误”和超时问题折磨。我曾经在一台1核2GB的测试机上安装打开页面都需要十几秒完全无法使用。2.2 安装方式选型包管理 vs Docker vs 源码这是第二个关键决策。主流安装方式有三种各有优劣Omnibus包安装推荐这是GitLab官方打包的一体化安装包包含了运行所需的所有服务Nginx, PostgreSQL, Redis, Sidekiq等。它的优点是部署极其简单升级方便官方维护所有组件版本经过兼容性测试。缺点是“全家桶”不够灵活会占用较多资源。Docker容器化安装使用Docker镜像运行隔离性好部署和迁移非常方便。适合熟悉Docker、追求环境一致性的团队。你需要自行管理数据卷、网络和容器生命周期。对于生产环境通常建议使用Docker Compose或Kubernetes来编排。源码编译安装最灵活也最复杂。你需要手动安装和配置每一个依赖Ruby, Go, PostgreSQL等。除非你有非常特殊的定制化需求或者是为了学习研究否则强烈不推荐用于生产环境。对于绝大多数场景尤其是初次部署和中小团队Omnibus包安装是最稳妥、最省心的选择。它能让你快速获得一个可用的生产级环境把精力集中在使用GitLab本身而不是折腾基础设施。因此本教程将围绕Omnibus包安装方式展开。2.3 网络与域名准备GitLab安装后需要通过浏览器访问。你需要一个域名或IP地址生产环境强烈建议绑定域名如gitlab.your-company.com这比直接使用IP地址更专业也方便后续配置HTTPS。如果只是内网测试可以使用服务器IP地址。防火墙配置确保服务器的防火墙如ufw或firewalld开放了以下端口80/tcp (HTTP)和443/tcp (HTTPS)用于Web访问。22/tcp (SSH)用于Git的SSH协议克隆和推送。可选其他端口如SMTP端口25, 465, 587用于邮件通知。解析记录将你准备好的域名A记录解析到你的服务器公网IP。如果是内网可以在团队成员的hosts文件里做映射。3. 分步详解Omnibus包安装流程好了理论准备完毕我们开始动手。以下操作假设你拥有一台全新的Ubuntu 22.04 LTS服务器并已通过SSH以root或具有sudo权限的用户登录。3.1 系统更新与依赖安装第一步永远是更新系统确保软件源和基础包是最新的这能避免很多因版本过旧导致的依赖问题。sudo apt update sudo apt upgrade -y安装一些必要的工具这些工具在后续的维护和问题排查中会用到。sudo apt install -y curl ca-certificates openssh-server postfix这里安装了curl用于下载、ca-certificates更新CA证书、openssh-serverGit SSH协议依赖和postfix邮件服务器用于发送通知。在安装postfix时会弹出配置窗口。对于大多数情况选择“Internet Site”然后系统会询问“System mail name”这里填写你的服务器域名如server.yourdomain.com或直接按回车使用系统主机名。如果你打算使用外部SMTP服务如腾讯企业邮、SendGrid这里可以选“Local only”甚至跳过postfix的安装后续在GitLab中配置。3.2 添加GitLab官方仓库并安装这是Omnibus安装的核心步骤通过添加官方源来安装能保证版本的纯净和后续升级的顺畅。信任GitLab的GPG密钥这是为了验证从GitLab仓库下载的软件包是否被篡改。curl -fsSL https://packages.gitlab.com/gitlab/gitlab-ce/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/gitlab-archive-keyring.gpg这个命令下载密钥并转换格式后存入系统密钥环。添加GitLab CE社区版仓库echo deb [signed-by/usr/share/keyrings/gitlab-archive-keyring.gpg] https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/ $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/gitlab_gitlab-ce.list命令中的$(lsb_release -cs)会自动获取你系统的代号如jammy for Ubuntu 22.04。这确保了添加的是对应你系统版本的仓库。刷新软件包列表并安装GitLabsudo apt update sudo apt install gitlab-ce执行apt install gitlab-ce时系统会开始下载并安装GitLab及其所有依赖。安装包大约几百MB下载速度取决于你的网络。安装过程会自动完成所有组件的初始配置。实操心得有时从 packages.gitlab.com 下载速度较慢。你可以考虑使用国内的镜像源例如清华大学开源软件镜像站。具体方法是修改上面的仓库地址。但请注意使用镜像源可能存在版本延迟生产环境建议优先使用官方源或确保镜像源足够及时。3.3 初始配置最关键的一步安装完成后GitLab并不会立即运行。我们需要编辑其主配置文件告诉它如何访问。编辑配置文件sudo vim /etc/gitlab/gitlab.rb这是GitLab唯一的配置文件所有组件Nginx, PostgreSQL等的设置都通过这个文件管理。打开后你会看到一个非常长的Ruby格式的配置文件。对于初次安装我们只需要修改最关键的一行external_url。配置外部访问地址 在文件中找到external_url这一行可以用/external_url搜索。默认可能是external_url http://gitlab.example.com。 将其修改为你的实际访问地址。例如使用IP地址external_url http://192.168.1.100使用域名推荐external_url http://gitlab.your-company.com使用HTTPSexternal_url https://gitlab.your-company.com配置HTTPS需要证书稍后详述这里我们先使用HTTP确保基础服务能通。稍后再配置HTTPS。让配置生效 保存并退出编辑器后执行以下命令。这个命令会根据/etc/gitlab/gitlab.rb的配置生成所有组件的实际配置文件并启动或重启服务。sudo gitlab-ctl reconfigure这是最重要的命令之一。reconfigure过程会持续几分钟屏幕上会滚动大量输出显示它在配置数据库、创建密钥、设置Nginx虚拟主机等。请耐心等待其完成直到出现类似“gitlab Reconfigured!”的提示。3.4 获取初始密码并登录reconfigure完成后GitLab服务就已经在运行了。它会在首次安装时为一个默认用户root生成一个随机密码。查看初始密码sudo cat /etc/gitlab/initial_root_password这个文件只会在首次reconfigure后的24小时内存在之后出于安全考虑会被自动删除。请立即复制下这个密码。登录Web界面 打开浏览器访问你刚才在external_url中设置的地址如http://192.168.1.100。 你会看到GitLab的登录界面。使用用户名root和刚才查到的密码登录。首次登录强制修改密码 成功登录后系统会强制要求你为root账户修改密码。请务必设置一个强度高且牢记的新密码。这个root账户是GitLab实例的超级管理员拥有所有权限。恭喜至此GitLab的核心安装和基础访问已经完成。你现在应该能看到GitLab的仪表盘了。但这只是开始要让其真正可用、好用还需要进行一系列关键配置。4. 生产环境必备配置详解一个“裸奔”的GitLab实例是不适合投入生产的。以下几个配置关乎安全性、可用性和用户体验。4.1 配置HTTPS使用Let‘s Encrypt免费证书在公网或内网敏感环境HTTP是极不安全的密码和代码传输都是明文。启用HTTPS是必须项。Omnibus GitLab内置了对Let‘s Encrypt免费证书的自动申请和续期支持配置非常简单。再次编辑主配置文件sudo vim /etc/gitlab/gitlab.rb修改相关配置项 找到并修改以下几行如果被注释取消注释#并修改值# 将external_url改为https协议 external_url https://gitlab.your-company.com # 启用Lets Encrypt letsencrypt[enable] true # 设置联系邮箱证书过期前会收到提醒 letsencrypt[contact_emails] [adminyour-company.com] # 自动续期 letsencrypt[auto_renew] true # 在reconfigure时自动获取证书首次 letsencrypt[auto_renew_hour] 0 letsencrypt[auto_renew_minute] 30 letsencrypt[auto_renew_day_of_month] */4应用配置sudo gitlab-ctl reconfigure这次reconfigure会花费更长时间因为GitLab会尝试与Let‘s Encrypt服务器通信验证你对域名gitlab.your-company.com的所有权通过HTTP-01挑战并自动获取和配置SSL证书。确保你的服务器80端口能在公网被访问否则验证会失败。验证 完成后再次用浏览器访问https://gitlab.your-company.com你应该能看到绿色的安全锁标志。注意事项Let‘s Encrypt证书有效期为90天上述配置启用了自动续期通过cron job通常无需手动干预。但务必确保contact_emails填写正确以便接收续期失败等通知。4.2 配置邮件服务器SMTPGitLab需要通过邮件发送注册确认、密码重置、流水线通知等。默认使用本机的sendmail或之前安装的postfix可能无法将邮件送达外部邮箱如QQ、163邮箱常被当作垃圾邮件。配置一个可靠的SMTP服务是必须的。以下以配置腾讯企业邮箱或其他第三方SMTP服务为例编辑主配置文件sudo vim /etc/gitlab/gitlab.rb搜索并配置SMTP设置 找到gitlab_rails[smtp_enable]和gitlab_rails[smtp_address]等配置区域修改如下具体参数需根据你的邮箱服务商调整gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.exmail.qq.com # 腾讯企业邮箱SMTP服务器 gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] gitlabyour-company.com # 发件邮箱 gitlab_rails[smtp_password] YourEmailPassword # 邮箱密码或授权码 gitlab_rails[smtp_domain] your-company.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] true # 使用SSL # 设置发件人信息 gitlab_rails[gitlab_email_from] gitlabyour-company.com gitlab_rails[gitlab_email_reply_to] noreplyyour-company.com重要对于腾讯、网易等邮箱smtp_password通常不是登录密码而是需要到邮箱设置中申请的授权码。应用配置并测试sudo gitlab-ctl reconfigure sudo gitlab-rails console # 进入GitLab Rails控制台在控制台中执行以下命令发送测试邮件Notify.test_email(your-personal-emailgmail.com, GitLab SMTP Test, Hello from GitLab!).deliver_now退出控制台输入exit检查你的个人邮箱是否收到测试邮件。4.3 性能调优与日常维护命令GitLab安装后了解一些基本的运维命令和调优点能让系统运行得更平稳。常用服务管理命令sudo gitlab-ctl start/stop/restart启动/停止/重启所有GitLab服务。sudo gitlab-ctl status查看所有组件的运行状态。sudo gitlab-ctl tail实时查看所有服务的日志。可以加服务名如sudo gitlab-ctl tail nginx或sudo gitlab-ctl tail postgresql。监控资源占用GitLab包含一个内置的监控端点。在Web界面以管理员身份登录访问“管理区域” - “监控” - “指标”可以查看服务器负载、内存、磁盘等状态。确保/var/opt/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 reconfigure和sudo gitlab-ctl restart。一个关键调优参数如果服务器内存较小如4GB你可能会发现GitLab运行一段时间后变得很慢。可以尝试调整UnicornGitLab的Web应用服务器新版已换为Puma的工作进程数减少内存压力。在/etc/gitlab/gitlab.rb中puma[worker_processes] 2 # 默认可能是CPU核数可适当调低修改后需要sudo gitlab-ctl reconfigure。5. 安装后常见问题与排查实录即使按照教程一步步来在实际环境中也可能遇到各种问题。这里记录几个我遇到的高频问题及其解决方法。5.1 访问出现“502 Whoops, GitLab is taking too much time to respond.”这是最常见的问题没有之一。根本原因通常是资源不足特别是内存或服务未完全启动。检查服务状态首先运行sudo gitlab-ctl status。查看是否有服务是down状态。常见的是puma或sidekiq启动失败。检查内存运行free -h。如果可用内存available很少Swap使用率很高说明内存不足。需要增加服务器内存或按照上一节调低worker数量。查看日志运行sudo gitlab-ctl tail puma或sudo gitlab-ctl tail gitlab-rails查看错误日志。常见的错误信息会指向具体原因如数据库连接失败、磁盘空间满等。给服务更多启动时间在低配机器上首次启动或reconfigure后服务需要较长时间初始化。可以等待2-5分钟再刷新页面。重启大法有时某个组件卡住了可以尝试sudo gitlab-ctl restart。5.2 Let‘s Encrypt证书申请失败在配置HTTPS的reconfigure阶段可能会在日志中看到ACME证书申请失败。检查域名解析和端口确保external_url中配置的域名已正确解析到服务器公网IP并且服务器的80端口在防火墙上是开放的。Let‘s Encrypt的HTTP-01挑战需要通过80端口访问你的服务器。检查是否已有证书如果之前配置过HTTPS可能残留了证书文件。可以尝试清理后重试sudo rm -rf /etc/gitlab/ssl/your-domain.com*然后再次sudo gitlab-ctl reconfigure。手动申请如果自动失败可以尝试使用GitLab内置工具手动申请sudo gitlab-ctl reconfigure sudo gitlab-ctl renew-le-certs5.3 邮件发送失败配置SMTP后测试邮件收不到。检查密码/授权码这是最容易出错的地方。确保smtp_password填写的是SMTP授权码而不是邮箱登录密码。检查SMTP服务器和端口不同邮箱服务商的SMTP地址和端口可能不同如SSL端口465 TLS端口587。确认配置无误。查看邮件日志sudo gitlab-ctl tail mailroom或sudo gitlab-rails console中测试发送时观察控制台输出通常会有详细的错误信息。服务器网络策略有些云服务器如阿里云、腾讯云的25端口默认被封禁。如果你的SMTP服务使用25端口需要联系云厂商解封或者改用支持465/587端口的服务。5.4 备份与恢复失败备份文件很大恢复时可能出错。确保版本一致恢复时目标GitLab的版本必须高于或等于创建备份时的版本。最好保持一致。检查磁盘空间恢复过程需要额外空间。确保/var/opt/gitlab所在磁盘有足够的空闲空间至少是备份文件大小的两倍。权限问题备份文件通常由git用户创建。确保你执行恢复命令时有权限读取备份文件。可以将备份文件拷贝到默认目录/var/opt/gitlab/backups/并确保属主是git:git(sudo chown git:git /var/opt/gitlab/backups/备份文件名.tar)。恢复前停止服务一定要按顺序先停止puma和sidekiq再进行恢复操作。安装和配置GitLab是一个系统工程涉及系统、网络、安全等多个方面。本教程涵盖了从规划到上线的核心路径和常见陷阱。记住做好备份是运维工作的铁律。当你熟悉了这些基本操作后就可以进一步探索GitLab强大的CI/CD、容器镜像库、安全扫描等高级功能了。