1. 为什么要在自己的Linux服务器上部署GitLab如果你是一个开发团队的负责人或者是一个独立开发者你可能已经厌倦了依赖GitHub、Gitee这类第三方托管平台。代码安全、网络延迟、私有仓库的收费限制甚至是简单的内网协作需求都可能让你萌生一个念头能不能自己搭一个GitLab这个集代码托管、CI/CD、项目管理于一体的DevOps平台就是解决这些痛点的绝佳选择。它不仅能让你完全掌控自己的代码资产还能让你在一个统一的平台上完成从代码编写到部署上线的全流程这对于追求效率和安全性的团队来说吸引力巨大。很多人一听到“自建GitLab”第一反应是“这很复杂吧”。确实相比直接注册一个在线账号自建需要投入一些初始的运维精力。但我想告诉你的是在今天的Linux环境下尤其是有了Docker这类容器化技术的加持搭建一个稳定可用的GitLab实例其过程已经变得相当标准化和可控。这篇内容就是基于我多次在生产环境和测试环境部署GitLab的经验为你梳理的一份从零开始的、手把手的实战指南。无论你是运维工程师还是想学习基础设施搭建的后端开发者跟着步骤走你都能在自己的服务器上拥有一个功能完备的私有GitLab。2. 部署前的关键决策安装方式与硬件准备在真正敲下安装命令之前有几个关键的决策点需要你提前想清楚。这直接决定了后续安装的顺利程度和系统的长期稳定性。盲目开始很可能中途遇到各种资源不足或配置冲突的问题。2.1 选择最适合你的安装方式GitLab官方提供了几种主流的安装方式每种都有其适用场景。1. Omnibus包安装推荐给大多数用户这是GitLab官方最推荐、也是文档最全的方式。它将GitLab所需的所有服务Ruby on Rails应用、PostgreSQL数据库、Redis、Nginx等打包成一个巨大的.deb或.rpm安装包。你只需要一个命令就能完成所有组件的安装和基础配置。优点一键安装配置管理集中所有配置都在/etc/gitlab/gitlab.rb一个文件里升级方便官方支持最好。缺点不够灵活所有组件耦合在一起会占用固定的端口如80 8080。如果你想用自己已有的Nginx或PostgreSQL会比较麻烦。适用场景全新服务器部署希望快速搭建、省心维护的团队。2. Docker容器化安装推荐给追求隔离和灵活性的用户使用Docker和Docker Compose来运行GitLab。GitLab官方提供了打包好的Docker镜像。优点环境隔离性好不会污染宿主机环境部署和迁移极其方便可以轻松调整资源分配易于实现多版本并存。缺点需要你具备一定的Docker使用经验数据持久化需要额外挂载卷性能相比原生安装可能有细微损耗通常可忽略。适用场景开发测试环境、资源有限的云服务器、或者你已经是Docker生态的重度用户。3. 源码编译安装不推荐给绝大多数用户从源代码开始手动安装和配置每一个依赖。这是最复杂、最易出错的方式。优点理论上最灵活可以深度定制每一个组件和版本。缺点耗时极长依赖解决复杂升级和维护是噩梦。适用场景需要对GitLab进行深度二次开发或研究的极客。我的建议对于生产环境或想长期稳定使用的个人项目首选Omnibus包安装。它的稳定性和可维护性经过了大量验证。本教程也将以Ubuntu 20.04/22.04 LTS系统为例详细讲解Omnibus包的安装流程。如果你钟情于Docker我也会在关键步骤后附上Docker方式的对应操作作为参考。2.2 硬件资源评估你的服务器够用吗GitLab是个“资源大户”尤其是内存。资源不足是安装失败或运行卡顿的最主要原因。以下是官方推荐的最低配置和我的经验建议CPU官方最低2核心。建议至少4核心以保证Web界面和后台任务如CI/CD流水线的流畅运行。内存这是重中之重。官方最低要求4GB但这仅能支持不超过100个用户且会非常卡顿几乎不可用于生产。我的强烈建议至少准备8GB的可用内存。这是保证基础服务GitLab、数据库、Redis稳定运行并能同时处理一些CI任务的门槛。对于小团队10-50人16GB是一个比较舒适的选择。你可以通过free -h命令查看当前服务器的可用内存。存储系统盘至少需要10GB用于安装GitLab本身和操作系统。数据盘这是存放你的代码仓库、CI产物、容器镜像等数据的地方。容量需求完全取决于你的团队规模和项目数量。建议单独挂载一块大容量磁盘如100GB或更多到/var/opt/gitlab目录GitLab默认数据目录。SSD能极大提升仓库克隆、读取的速度。网络确保服务器的80HTTP和443HTTPS端口对外开放如果要从外网访问。22端口SSH用于Git克隆推送。注意在虚拟化环境如VMware、VirtualBox或云服务器如AWS EC2、阿里云ECS中部署时请务必确认你分配的资源特别是内存是“可用内存”而不是“虚拟内存”或“突发性能”。内存不足时GitLab的Unicorn或Sidekiq进程可能会被系统OOM Killer强制结束导致服务不可用。3. 一步步安装GitLab Omnibus包假设你已经拥有一台满足上述硬件要求的、新安装的Ubuntu 22.04 LTS服务器并通过SSH登录。我们将以root用户或具有sudo权限的用户进行操作。3.1 系统更新与基础依赖安装首先更新系统软件包列表并升级现有软件这是一个好习惯。sudo apt update sudo apt upgrade -y安装一些必要的工具如curl用于下载vim用于编辑配置文件。sudo apt install -y curl vim3.2 添加GitLab官方软件仓库Omnibus包通过APT仓库分发我们需要将GitLab的官方仓库添加到系统的源列表中。下载并执行GitLab提供的仓库脚本。这里我们安装社区版CE。curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash这个脚本会自动检测你的系统版本并将GitLab的APT源添加到/etc/apt/sources.list.d/目录下。更新本地APT缓存使新添加的仓库生效。sudo apt update3.3 安装GitLab软件包现在我们可以安装GitLab了。在安装命令中我们可以通过设置环境变量EXTERNAL_URL来指定GitLab将来对外访问的地址。这非常重要因为安装程序会根据这个URL自动配置一些内部设置。将下面的https://gitlab.yourdomain.com替换为你计划使用的实际域名或IP地址。如果你还没有域名暂时使用服务器的公网IP地址如http://你的服务器IP也可以但生产环境强烈建议使用域名并配置HTTPS。sudo EXTERNAL_URLhttps://gitlab.yourdomain.com apt install gitlab-ce执行这个命令后APT会开始下载并安装GitLab社区版。安装包较大约1GB下载时间取决于你的网络速度。安装过程会自动完成以下事情安装GitLab及其所有依赖PostgreSQL, Redis, Nginx等。根据EXTERNAL_URL生成初始配置。启动所有必要的服务。Docker方式参考 如果你选择Docker安装步骤会简化为# 拉取镜像 docker pull gitlab/gitlab-ce:latest # 运行容器 docker run --detach \ --hostname gitlab.yourdomain.com \ --publish 443:443 --publish 80:80 --publish 22:22 \ --name gitlab \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest你需要提前创建好本地的数据目录/srv/gitlab并注意端口映射和宿主机目录的挂载。3.4 初始配置与管理员密码设置安装完成后GitLab服务会自动启动。但我们需要进行一些关键配置。修改主配置文件Omnibus包的所有配置都集中在/etc/gitlab/gitlab.rb这个文件里。首先用编辑器打开它。sudo vim /etc/gitlab/gitlab.rb配置外部URL关键在文件中找到external_url这一行。确保它的值与你安装时设置的EXTERNAL_URL一致或者修改为你最终确定的地址。这是GitLab生成仓库链接、发送邮件等所有功能的基准地址。external_url https://gitlab.yourdomain.com邮件服务器配置可选但重要GitLab需要发送注册确认、密码重置等通知邮件。你需要配置一个SMTP服务器。以下是一个使用第三方SMTP服务如SendGrid、阿里云邮件的示例。找到对应的配置段落取消注释并修改。gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.sendgrid.net gitlab_rails[smtp_port] 587 gitlab_rails[smtp_user_name] apikey # 通常是 apikey gitlab_rails[smtp_password] 你的SendGrid API Key gitlab_rails[smtp_domain] yourdomain.com gitlab_rails[smtp_authentication] plain gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] false # 发件人地址 gitlab_rails[gitlab_email_from] gitlabyourdomain.com如果不配置邮件用户注册等功能将无法正常使用。让配置生效每次修改gitlab.rb后都必须运行以下命令来重新配置GitLab。这个命令会根据配置文件生成所有组件的实际运行配置并重启服务。第一次运行会花费较长时间5-15分钟请耐心等待。sudo gitlab-ctl reconfigure获取初始管理员密码GitLab安装后会为默认的root管理员账户生成一个随机密码。这个密码存储在/etc/gitlab/initial_root_password文件中且24小时后会自动删除。查看它sudo cat /etc/gitlab/initial_root_password记下密码稍后登录要用。3.5 首次登录与安全加固访问Web界面在浏览器中打开你设置的EXTERNAL_URL例如https://gitlab.yourdomain.com。你会看到GitLab的登录界面。使用root账户登录用户名输入root密码输入上一步获取的随机密码。立即修改root密码登录成功后第一件事就是点击右上角头像 -Settings-Password为root账户设置一个强密码。配置SSH密钥个人电脑为了安全、方便地使用Git你需要将本机的SSH公钥添加到GitLab。在你的本地电脑上生成SSH密钥如果还没有的话ssh-keygen -t ed25519 -C your_emailexample.com然后复制~/.ssh/id_ed25519.pub文件的内容。在GitLab网页上点击右上角头像 -Settings-SSH Keys粘贴并添加。关闭开放注册生产环境必做默认情况下任何人都可以注册账号。对于内部或私有GitLab这很危险。进入Admin Area左上角菜单 -Admin -Settings-General-Sign-up restrictions取消勾选Sign-up enabled然后滚动到页面底部保存。至此一个基础可用的GitLab实例就已经搭建完成了。你可以创建项目、推送代码了。但要让其稳定、高效、安全地运行还需要进行一些优化。4. 安装后的关键优化与日常维护安装成功只是第一步接下来的优化配置决定了使用体验。很多问题如访问慢、备份失败都是由于忽略了这些配置。4.1 性能调优让GitLab跑得更快GitLab默认配置比较保守在资源充足的服务器上我们可以进行一些调整以提升性能。再次编辑/etc/gitlab/gitlab.rb。调整工作进程数unicorn是GitLab的Web应用服务器sidekiq是后台任务处理器。根据你的CPU核心数调整它们的工作进程/线程数。# 根据CPU核心数调整通常设为CPU核心数或稍多 unicorn[worker_processes] 4 sidekiq[max_concurrency] 20调整数据库连接池PostgreSQL连接池大小需要与Unicorn的worker数匹配。postgresql[max_connections] 200 gitlab_rails[db_pool] 20 # 通常建议是 unicorn worker_processes 1启用页面缓存对于静态资源启用Nginx的页面缓存可以显著提升访问速度。nginx[enable] true nginx[gzip_enabled] true修改后别忘了运行sudo gitlab-ctl reconfigure使配置生效并重启服务sudo gitlab-ctl restart。4.2 备份与恢复数据安全的生命线必须定期备份Omnibus包提供了简单的备份命令。手动备份sudo gitlab-backup create备份文件会默认存储在/var/opt/gitlab/backups/目录下文件名类似1678886400_2023_03_16_15.0.0_gitlab_backup.tar。这个备份包含了数据库、仓库、上传文件等几乎所有数据。自动备份配置Cron任务 编辑root用户的crontabsudo crontab -e添加一行例如每天凌晨2点进行备份0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON1CRON1环境变量会让备份命令在非交互模式下运行。备份配置文件同样重要备份命令不包含/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json包含加密密钥。这两个文件必须手动备份丢失gitlab-secrets.json将导致所有加密数据如CI变量无法解密。sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak.$(date %s) sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak.$(date %s)恢复演练定期在测试环境进行恢复演练。恢复命令是# 停止相关服务 sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq # 执行恢复将BACKUP_TIMESTAMP替换为你的备份文件时间戳 sudo gitlab-backup restore BACKUP1678886400_2023_03_16_15.0.0 # 重启并重载配置 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart4.3 监控与日志排查掌握系统状态当出现问题时日志是你最好的朋友。查看所有服务状态sudo gitlab-ctl status跟踪实时日志# 查看所有服务的综合日志 sudo gitlab-ctl tail # 查看特定服务日志如nginx sudo gitlab-ctl tail nginx # 查看应用日志 sudo tail -f /var/log/gitlab/gitlab-rails/production.log检查服务健康度GitLab内置了健康检查端点。访问https://gitlab.yourdomain.com/-/health可以快速查看应用是否存活。sudo gitlab-rake gitlab:check命令可以执行更全面的系统检查。4.4 升级与版本管理GitLab版本迭代很快定期升级可以获取新功能和安全补丁。升级前务必完整备份。查看当前版本sudo cat /opt/gitlab/embedded/service/gitlab-rails/VERSION升级到最新版本sudo apt update sudo apt install gitlab-ceAPT会处理依赖和升级。升级完成后通常需要运行sudo gitlab-ctl reconfigure。大版本升级注意事项跨越大版本如14.x - 15.x时务必先查阅官方升级文档。通常有特定的升级路径和需要手动执行的迁移命令。5. 常见问题与故障排查实录即使按照教程操作你也可能会遇到一些“坑”。这里记录了几个我亲自踩过并且高频出现的问题。5.1 首次访问出现“502 Whoops, GitLab is taking too much time to respond.”这是最常见的问题几乎90%是由于服务器内存不足导致的。GitLab在启动和首次运行时需要大量内存来加载环境和编译资产。排查与解决检查内存立刻运行free -h和top命令查看可用内存和哪个进程占用高。如果可用内存available低于1GB基本可以确定是内存问题。增加Swap空间如果物理内存确实不足为系统添加Swap交换分区是一个临时的缓解方案。# 创建一个4GB的Swap文件 sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 永久生效编辑 /etc/fstab添加一行 echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab终极方案升级服务器配置增加物理内存。对于生产环境这是必须的。5.2 邮件发送失败用户收不到注册或通知邮件邮件配置错误是另一个高频问题。日志里会明确报错。排查与解决检查配置确认/etc/gitlab/gitlab.rb中的SMTP配置完全正确特别是密码、端口和加密方式TLS/SSL。测试邮件发送进入GitLab Rails控制台进行测试。sudo gitlab-rails console在控制台中执行Notify.test_email(your-emailexample.com, Test Subject, Test Body).deliver_now观察控制台输出会有详细的SMTP交互信息是排查问题的关键。检查网络与防火墙确保服务器可以访问你配置的SMTP服务器地址和端口如smtp.gmail.com:587。可以使用telnet或nc命令测试连通性。5.3 备份文件过大或备份失败随着使用仓库和CI产物会越来越多备份文件可能变得巨大。排查与解决排除不需要的备份内容在gitlab.rb中可以配置跳过某些目录的备份如CI产物artifacts和容器镜像registry。gitlab_rails[backup_upload_connection] { provider Local, local_root /var/opt/gitlab/backups } gitlab_rails[backup_upload_remote_directory] gitlab_backups gitlab_rails[backup_archive_permissions] 0644 # 跳过CI产物和容器镜像 gitlab_rails[backup_skip] [artifacts, registry]修改后需reconfigure。备份到远程存储本地磁盘满了会导致备份失败。可以将备份自动上传到远程对象存储如AWS S3、阿里云OSS、MinIO。这需要在gitlab.rb中配置backup_upload_connection具体配置请参考GitLab官方文档。定期清理旧备份写一个简单的Shell脚本配合Cron任务定期删除超过一定天数的本地备份文件。5.4 如何修改GitLab的访问IP或端口如果你在安装时使用了IP后来想换为域名或者需要更改默认的80/443端口。解决方案修改/etc/gitlab/gitlab.rb中的external_url例如external_url http://new-ip:8080或external_url https://new-domain.com。如果你改了端口还需要确保Nginx监听新端口。对于非80/443端口通常external_url包含端口号即可GitLab的Nginx配置会自动调整。运行sudo gitlab-ctl reconfigure。注意更改external_url后所有用户仓库的远程地址都会改变需要通知团队成员更新他们本地的git remote地址。安装和运维自己的GitLab就像打理一个花园。初期需要投入精力去松土、播种安装配置后期则需要定期浇水、修剪监控、备份、升级。这个过程不仅能让你完全掌控代码生命周期的每一个环节更能深刻理解一个复杂Web应用背后的基础设施是如何协同工作的。从我自己的经验来看自建GitLab后团队对CI/CD流程的理解、对服务器资源的敏感度都有了实实在在的提升。开始可能会遇到一两个“坑”但一旦系统稳定跑起来那种一切尽在掌握的感觉是使用任何SaaS服务都无法替代的。