1. 为什么选择自建 GitLab 而不是直接用托管服务很多团队在起步阶段会直接使用公有托管平台来管理代码省事、零维护这没什么问题。但当团队规模超过十人、项目数量超过二十个之后一系列现实问题就会浮出水面CI/CD 的并发任务需要排队、私有镜像仓库需要额外付费、代码审查流程想自定义却受限于平台规则、敏感项目的代码不想放在别人的服务器上。这些痛点叠加在一起自建 GitLab 就成了一个绕不开的选项。GitLab 社区版CE是开源免费的功能覆盖了代码托管、代码审查、Issue 跟踪、CI/CD 流水线、容器镜像仓库、制品库、Wiki 等一整套研发协作链路。说白了它不只是一个 Git 仓库而是一个完整的 DevOps 平台。你把它部署在自己的服务器上数据完全自主可控想怎么配置就怎么配置想接什么 Webhook 就接什么 Webhook没有任何平台方的限制。但自建也有代价。GitLab 是一个相当“重”的应用它对内存、CPU、磁盘 I/O 都有不低的要求。我见过不少人兴冲冲地在一台 2GB 内存的入门级云主机上装 GitLab结果要么装到一半卡死要么装完之后页面加载要等十几秒推送代码动不动就超时。所以在动手之前先把硬件资源这件事想清楚比什么都重要。这篇文章面向的是有一定 Linux 基础、准备在自己的服务器上部署 GitLab 的开发和运维人员。我会从资源规划开始一步步讲到安装、配置、调优、备份和常见故障处理把我在多次部署中踩过的坑和总结的经验都摊开来讲。即使你之前没接触过 GitLab 的部署跟着走一遍也能跑通。2. 部署前的资源规划与系统准备2.1 硬件配置的最低门槛与推荐配置GitLab 官方文档给出的最低要求是 2 核 CPU、4GB 内存但这是“能跑起来”的底线不是“能用得舒服”的标准。根据我的实际经验不同规模的团队应该参考以下配置使用规模CPU内存磁盘说明个人学习/测试2 核4GB50GB SSD勉强可用CI 任务基本跑不动5-10 人小团队4 核8GB100GB SSD日常使用流畅轻度 CI10-30 人团队8 核16GB200GB SSD推荐配置CI 并发无压力30 人以上16 核32GB500GB SSD建议考虑多节点架构这里有一个关键点内存比 CPU 更重要。GitLab 内部集成了 PostgreSQL、Redis、Puma、Sidekiq、Nginx 等多个组件光是这些基础服务空跑就要吃掉 3-4GB 内存。如果内存不足系统会频繁使用 Swap导致整个平台的响应速度急剧下降。磁盘方面一定要用 SSD机械硬盘的随机读写性能会让 Git 操作变得非常痛苦。注意如果你打算启用 GitLab 内置的容器镜像仓库功能磁盘空间要额外预留。镜像层是出了名的占空间一个中等规模团队用半年几十 GB 就没了。2.2 操作系统的选择与基础环境配置GitLab 官方支持的 Linux 发行版主要包括 Ubuntu 20.04/22.04、Debian 11/12、CentOS 7/8 等。我个人更推荐 Ubuntu 22.04 LTS原因是它的软件源更新及时、社区支持好、遇到问题容易搜到解决方案。CentOS 7 虽然稳定但已经停止维护新部署不建议再用。系统装好之后先做几件基础的事情。第一更新系统包并安装必要的工具sudo apt update sudo apt upgrade -y sudo apt install -y curl openssh-server ca-certificates postfix其中 postfix 是用于邮件发送的GitLab 需要它来发送通知邮件。安装过程中会弹出一个配置界面选择“Internet Site”即可域名部分填你的服务器域名或 IP。第二配置防火墙。GitLab 需要开放以下端口sudo ufw allow 80/tcp # HTTP sudo ufw allow 443/tcp # HTTPS sudo ufw allow 22/tcp # SSH如果你修改了 GitLab 的 SSH 端口后面会讲记得把对应的端口也放开。第三设置服务器的主机名。这一步很多人会忽略但它直接影响 GitLab 生成的仓库地址sudo hostnamectl set-hostname gitlab.example.com然后在/etc/hosts中添加一条记录把主机名指向本机 IP127.0.0.1 gitlab.example.com这样做的好处是GitLab 在初始化时会自动使用这个主机名作为外部访问地址省去后续手动修改配置的麻烦。2.3 域名与 HTTPS 证书的提前准备如果你打算通过域名访问 GitLab 并启用 HTTPS强烈建议这么做需要提前准备好两样东西一个解析到服务器 IP 的域名以及一个有效的 TLS 证书。证书的获取方式有很多种最省事的是使用 Lets Encrypt 的免费证书。GitLab 内置了 Lets Encrypt 的自动申请和续期功能只需要在配置文件中填入域名和邮箱即可。但要注意Lets Encrypt 的验证需要你的服务器 80 端口对外可访问而且域名必须正确解析。如果你在内网环境部署没法用 Lets Encrypt那就需要自己准备证书文件或者先用 HTTP 跑起来后续再补上 HTTPS。我个人的建议是无论如何都要上 HTTPS。GitLab 的登录凭证、代码传输、API 调用都涉及敏感信息纯 HTTP 环境下这些数据是明文传输的风险很大。而且现在很多浏览器对 HTTP 站点会标记“不安全”影响使用体验。3. 安装方式的选择与实操过程3.1 三种主流安装方式的对比GitLab 的安装方式主要有三种Omnibus 包安装、Docker 容器安装、源码编译安装。这三种方式各有优劣适合不同的场景。安装方式优点缺点适用场景Omnibus 包官方支持、组件集成度高、升级方便灵活性稍差、依赖系统环境生产环境首选Docker 容器环境隔离、迁移方便、版本切换快数据持久化需额外配置、性能略有损耗测试环境、快速验证源码编译最大灵活性、可深度定制极其复杂、维护成本高特殊定制需求对于绝大多数场景我推荐使用 Omnibus 包安装。它把 GitLab 需要的所有组件PostgreSQL、Redis、Nginx 等都打包在一起通过一个配置文件就能统一管理升级时也只需要执行一条命令。Docker 方式虽然看起来更“现代”但在生产环境中数据卷的管理、网络配置、性能调优都会带来额外的复杂度不太适合对稳定性要求高的场景。3.2 使用 Omnibus 包安装 GitLab CE确认系统环境准备好之后就可以开始安装了。首先添加 GitLab 的官方软件源curl -fsSL https://packages.gitlab.com/gitlab/gitlab-ce/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/gitlab_gitlab-ce-archive-keyring.gpg echo deb [signed-by/usr/share/keyrings/gitlab_gitlab-ce-archive-keyring.gpg] https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/gitlab_gitlab-ce.list sudo apt update然后安装 GitLab CEsudo apt install -y gitlab-ce安装完成后GitLab 会自动进行首次配置。这个过程可能需要几分钟取决于服务器性能。安装脚本会输出一段提示信息告诉你如何访问 GitLab 以及初始密码存放在哪里。如果你需要指定安装某个版本可以用apt install gitlab-ce16.5.0-ce.0这样的格式。在生产环境中我强烈建议锁定版本号不要盲目追新。新版本可能引入不兼容的变更导致升级后服务异常。3.3 首次配置与初始化安装完成后需要编辑 GitLab 的主配置文件/etc/gitlab/gitlab.rb。这个文件是 Ruby 语法的里面包含了所有可配置项但大部分都被注释掉了。你只需要修改需要变更的部分。最核心的配置项是external_url它决定了 GitLab 的访问地址external_url https://gitlab.example.com如果你暂时没有域名和证书可以先用 HTTPexternal_url http://192.168.1.100修改完配置文件后执行重新配置命令让改动生效sudo gitlab-ctl reconfigure这个命令会重新读取配置文件重新生成各个组件的配置并重启相关服务。第一次执行可能需要 3-5 分钟耐心等待即可。配置完成后通过浏览器访问你设置的地址。首次访问会要求你设置 root 用户的密码。如果你错过了这个页面也可以通过命令行来重置sudo gitlab-rails console进入控制台后执行以下 Ruby 代码来重置密码user User.where(id: 1).first user.password 你的新密码 user.password_confirmation 你的新密码 user.save! exit注意密码至少要 8 位且不能是常见弱密码。GitLab 有密码复杂度校验太简单的密码会保存失败。4. 关键配置项的调优与安全加固4.1 邮件通知服务的配置GitLab 默认使用系统的 sendmail 来发送邮件但在实际使用中这种方式很容易被邮件服务商拒收或者直接进垃圾箱。更可靠的做法是配置一个 SMTP 服务来发送邮件。在/etc/gitlab/gitlab.rb中添加以下配置gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.example.com gitlab_rails[smtp_port] 587 gitlab_rails[smtp_user_name] gitlabexample.com gitlab_rails[smtp_password] your_smtp_password gitlab_rails[smtp_domain] example.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] false gitlab_rails[gitlab_email_from] gitlabexample.com gitlab_rails[gitlab_email_display_name] GitLab 通知配置完成后同样需要执行sudo gitlab-ctl reconfigure。然后可以通过以下命令测试邮件是否正常发送sudo gitlab-rails console在控制台中执行Notify.test_email(testexample.com, 测试邮件, 这是一封测试邮件).deliver_now如果对方能收到邮件说明配置成功。如果没有收到检查垃圾箱并查看/var/log/gitlab/gitlab-rails/production.log中的错误信息。4.2 SSH 端口的调整与优化GitLab 默认使用 22 端口作为 SSH 端口但这往往和系统本身的 SSH 服务冲突。有两种解决方案一是修改系统 SSH 的端口二是修改 GitLab 的 SSH 端口。我倾向于后者因为系统 SSH 的端口改动可能影响其他管理工具。在/etc/gitlab/gitlab.rb中修改gitlab_rails[gitlab_shell_ssh_port] 2222同时确保/etc/ssh/sshd_config中 GitLab 使用的 git 用户能够正常登录。然后重新配置 GitLab并在防火墙中开放 2222 端口。这样配置之后GitLab 仓库页面上显示的 SSH 克隆地址会自动带上 2222 端口用户不需要手动修改。4.3 资源限制与性能调优GitLab 的各个组件都支持通过配置文件调整资源占用。对于内存有限的服务器以下几个参数值得关注# 调整 Puma 工作进程数默认为 CPU 核心数 puma[worker_processes] 2 # 调整 Sidekiq 并发数默认为 20 sidekiq[max_concurrency] 10 # 调整 PostgreSQL 共享缓冲区默认为 256MB postgresql[shared_buffers] 512MB # 调整 Redis 最大内存 redis[maxmemory] 512mb redis[maxmemory_policy] allkeys-lru这些参数的调整需要根据服务器的实际资源来定。原则是不要让单个组件吃掉过多内存导致其他组件被 OOM Killer 杀掉。如果你不确定怎么调可以先保持默认观察一段时间的内存使用情况再做调整。另外GitLab 内置了 Prometheus 监控组件会额外消耗 200-300MB 内存。如果服务器资源紧张可以关掉它prometheus_monitoring[enable] false4.4 安全加固的几个关键点部署完成后有几项安全措施必须做。第一关闭公开注册。在 Admin Area 的 Settings 中找到 Sign-up restrictions取消“Sign-up enabled”的勾选。这样只有管理员才能创建新用户避免陌生人注册进来。第二启用双因素认证。在 Admin Area 的 Settings 中找到 Account and limit settings勾选“Enforce two-factor authentication”。对于存放核心代码的平台来说这一步非常有必要。第三配置备份策略。GitLab 自带备份命令可以备份数据库、仓库、上传文件等所有数据sudo gitlab-backup create备份文件默认存放在/var/opt/gitlab/backups/目录下。建议配置一个定时任务每天凌晨自动备份并将备份文件同步到远程存储。同时一定要把/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json也纳入备份范围这两个文件包含了加密密钥丢失后备份数据将无法恢复。5. 部署后常见故障的排查思路5.1 502 错误的几种典型原因502 Bad Gateway 是 GitLab 部署后最常见的问题之一。它的本质是 Nginx 无法连接到后端的 Puma 服务。造成这种情况的原因通常有以下几种第一种Puma 服务还没启动完成。GitLab 首次配置后各个服务的启动顺序有先后Puma 可能需要一两分钟才能就绪。如果刚配置完就访问很容易遇到 502。等几分钟再刷新即可。第二种内存不足导致 Puma 被系统杀掉。用free -h查看内存使用情况如果 Swap 也用满了基本可以确定是这个问题。解决办法是增加内存或者调低 Puma 的 worker 数量。第三种配置文件有语法错误。执行sudo gitlab-ctl reconfigure时如果报错说明配置文件有问题。仔细检查/etc/gitlab/gitlab.rb中是否有拼写错误或格式问题。排查时可以查看 Puma 的日志sudo gitlab-ctl tail puma日志中会明确告诉你 Puma 是否正常启动以及具体的错误信息。5.2 代码推送失败的排查链路代码推送失败是另一个高频问题可能的原因比较多需要按链路逐一排查。先确认是 SSH 方式还是 HTTP 方式推送。如果是 SSH 方式先用ssh -T gityour-gitlab-host -p 2222测试连接。如果提示“Welcome to GitLab”说明 SSH 配置正常。如果提示权限拒绝或连接超时检查防火墙端口是否开放、GitLab 的 SSH 端口配置是否正确。如果是 HTTP 方式检查 GitLab 的 external_url 是否和实际访问地址一致。不一致的话GitLab 生成的克隆地址会是错误的导致推送失败。还有一种情况是仓库大小超过了限制。GitLab 默认对单个推送的大小有限制可以在 Admin Area 的 Settings 中调整。如果推送的提交中包含大文件建议使用 Git LFS 来管理。5.3 磁盘空间告警的处理方法GitLab 运行一段时间后磁盘空间可能会被各种日志和临时文件占满。以下几个目录是“空间大户”/var/log/gitlab/各组件日志可以通过gitlab-ctl的日志轮转配置来控制大小/var/opt/gitlab/gitlab-rails/uploads/用户上传的附件/var/opt/gitlab/gitlab-rails/shared/制品、LFS 对象等/var/opt/gitlab/postgresql/data/数据库文件处理磁盘告警时先清理日志文件sudo gitlab-ctl stop sudo rm -rf /var/log/gitlab/*.log.* sudo gitlab-ctl start然后检查是否有异常大的仓库或制品。在 Admin Area 的 Monitoring 中可以看到各项目的存储占用情况。对于不再需要的项目及时归档或删除。注意直接删除/var/opt/gitlab/gitlab-rails/shared/下的文件可能导致数据不一致建议通过 GitLab 的界面或 API 来清理。6. 升级策略与日常维护经验6.1 版本升级的正确姿势GitLab 的版本升级有一条铁律不能跨大版本升级。比如你当前是 15.x想升到 16.x必须先升到 15.x 的最后一个版本再升到 16.0然后逐步升到 16.x 的最新版。跨版本升级几乎必然导致数据库迁移失败。升级前务必做三件事第一完整备份第二查看官方升级路径文档确认当前版本到目标版本的升级路线第三在测试环境先验证一遍。升级命令本身很简单sudo apt update sudo apt install gitlab-ce sudo gitlab-ctl reconfigure但升级过程中的数据库迁移可能需要较长时间期间 GitLab 会处于维护模式用户无法访问。建议安排在业务低峰期执行。6.2 日常巡检应该看哪些指标GitLab 部署好之后日常巡检主要关注以下几个指标检查项命令正常范围服务状态gitlab-ctl status所有服务 run内存使用free -h可用内存 1GB磁盘使用df -h使用率 80%Puma 响应gitlab-ctl tail puma无大量 timeoutSidekiq 队列Admin Area 的 Background Jobs队列无堆积如果发现 Sidekiq 队列持续堆积说明后台任务处理不过来可能需要增加 Sidekiq 的并发数或者检查是否有异常任务在消耗资源。6.3 备份恢复的实操验证备份做了不等于能用一定要定期验证备份的可用性。恢复的步骤大致如下# 停止相关服务 sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq # 恢复备份备份文件名去掉 _gitlab_backup.tar 后缀 sudo gitlab-backup restore BACKUP1700000000_2024_01_01_16.5.0 # 恢复配置文件 sudo cp /path/to/backup/gitlab.rb /etc/gitlab/gitlab.rb sudo cp /path/to/backup/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json # 重新配置并启动 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart恢复完成后检查仓库、用户、Issue 等数据是否完整。我建议至少每季度做一次恢复演练确保备份文件真的能用。7. 个人在实际部署中的几点体会部署 GitLab 这件事说难不难说简单也不简单。我第一次部署的时候在一台 2GB 内存的服务器上折腾了一整天各种 502、各种超时最后发现根本原因就是内存不够。后来换了 8GB 的机器半小时就搞定了。所以我的第一条体会是在资源上不要抠门该花的钱要花。第二条体会是关于配置文件的。/etc/gitlab/gitlab.rb这个文件里的配置项非常多但大部分你都不需要动。我见过有人把能改的都改了结果各种服务起不来。正确的做法是只改你明确知道需要改的改完之后执行gitlab-ctl reconfigure观察输出有没有报错。如果报错先回滚到上一个能用的配置再逐步排查。第三条体会是关于备份的。我曾经遇到过一台服务器磁盘故障幸好有每日备份数据只丢了不到一天。但恢复的时候发现gitlab-secrets.json没有备份导致恢复后的 GitLab 无法解密原有的 CI 变量和 Runner 注册信息。从那以后我把配置文件和密钥文件也纳入了自动备份范围。最后分享一个小技巧如果你只是想在本地快速验证某个功能可以用 Docker 跑一个临时的 GitLab 实例用完就删不污染生产环境。命令大概是这样docker run --detach \ --hostname localhost \ --publish 443:443 --publish 80:80 --publish 2222:22 \ --name gitlab-test \ --restart always \ --volume /tmp/gitlab/config:/etc/gitlab \ --volume /tmp/gitlab/logs:/var/log/gitlab \ --volume /tmp/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest等容器启动完成后访问http://localhost就能看到 GitLab 的登录页面。这种方式非常适合做功能验证和版本测试不会影响正式环境。