1. 为什么选择在 Ubuntu 上自建 GitLab1.1 自建代码托管平台的核心动机很多团队在起步阶段会直接使用公有代码托管服务省事、零维护这没什么问题。但当项目规模变大、代码资产变多之后自建代码托管平台的需求就会逐渐浮现出来。我在几个不同规模的团队里都经历过这个转折点最常见的触发因素有三个一是代码资产的私密性要求提高某些项目不希望源码存放在第三方平台上二是需要和内部系统做深度集成比如 CI/CD 流水线要直接访问内网服务、制品库、测试环境三是成本考量当团队人数增长到一定规模后按席位付费的公有服务账单会变得相当可观。GitLab 社区版CE是目前自建方案里功能最完整、生态最成熟的选择之一。它不只是一个 Git 仓库管理工具还集成了代码审查Merge Request、议题跟踪Issue、持续集成CI/CD、制品仓库、容器镜像仓库等一整套研发协作能力。对于中小团队来说一套自建的 GitLab 基本可以替代三到四个独立的工具。选择 Ubuntu 作为宿主系统理由也很直接GitLab 官方对 Ubuntu 的支持最完善官方软件仓库直接提供 Ubuntu 的安装包依赖关系处理得最干净。相比之下在 CentOS 或其它发行版上安装虽然也能跑起来但经常会遇到依赖版本冲突、SELinux 策略拦截之类的问题排查起来很费时间。1.2 本文适合哪些人参考这篇文章面向的是有一定 Linux 基础、需要在 Ubuntu 服务器上快速部署 GitLab 的运维人员或后端开发者。你不需要是 Linux 专家但至少要熟悉基本的命令行操作、会用apt管理软件包、能看懂系统服务状态。如果你之前从来没接触过 GitLab 的自建部署跟着这篇文章走一遍大概半小时到一小时内能完成全部配置。我下面要讲的方案核心思路是使用 GitLab 官方提供的软件仓库和安装包而不是用 Docker 或者从源码编译。这三种方式我都试过Docker 方式灵活但网络和存储配置容易踩坑源码编译耗时太长且升级麻烦官方软件包方式是最省心、最适合快速上线的路径。当然每种方式都有适用场景我会在后面的章节里对比说明。2. 部署前的整体方案设计与选型对比2.1 三种主流安装方式的取舍在动手之前先把安装方式选清楚这决定了后面所有步骤的走向。GitLab 在 Ubuntu 上的安装方式主要有三种我把它们的核心差异整理成了一张表安装方式部署速度升级维护资源占用适用场景官方软件包Omnibus快一条命令简单apt 升级较高内置所有组件生产环境、快速上线Docker 容器中等需配置挂载中等需管理镜像可控依赖宿主机测试环境、多实例源码编译慢数小时复杂需手动处理最低可裁剪特殊定制需求官方软件包方式也叫 Omnibus 包把 GitLab 需要的所有组件——PostgreSQL、Redis、Nginx、Gitaly、Sidekiq 等等——全部打包在一起通过一个配置文件/etc/gitlab/gitlab.rb统一管理。这意味着你不需要单独去装数据库、配反向代理安装包会帮你搞定。代价是资源占用相对高一些但对现代服务器来说这点开销完全可以接受。Docker 方式的好处是环境隔离干净迁移方便但你需要自己处理数据卷挂载、端口映射、容器网络而且 GitLab 容器对内存的要求不低配置不当容易出现服务起不来的情况。源码编译我一般只在有特殊定制需求时才考虑比如要修改某些核心逻辑否则纯粹是浪费时间。提示如果你的服务器内存小于 4GB官方软件包方式可能会在安装过程中因为内存不足而失败。GitLab 官方建议至少 4GB 内存实际使用中 8GB 会更从容。2.2 服务器规格与系统要求在选好安装方式之后下一步是确认服务器规格。GitLab 对硬件的要求不算低尤其是内存。我整理了一份实际部署中总结出来的配置建议CPU至少 2 核推荐 4 核。GitLab 的 Web 服务和后台任务都比较吃 CPU核心数太少会导致页面响应慢。内存最低 4GB推荐 8GB。内存不足是安装失败和运行卡顿的头号原因。磁盘至少 20GB 可用空间推荐 50GB 以上。Git 仓库、制品、日志都会持续增长。系统版本Ubuntu 20.04 LTS 或 22.04 LTS。LTS 版本稳定性好官方支持周期长。关于系统版本我特别建议用 LTS长期支持版本而不是最新的非 LTS 版本。非 LTS 版本的生命周期短可能过几个月就不再接收安全更新而 GitLab 的官方仓库对非 LTS 版本的支持也可能滞后。我踩过一次坑在一台 Ubuntu 非 LTS 的机器上装 GitLab结果官方仓库里没有对应版本的包最后只能降级系统重装。2.3 网络与域名规划GitLab 部署好之后是要给团队成员访问的所以网络和域名需要提前规划。这里涉及几个关键点第一确定访问地址。如果你有内部 DNS可以给服务器分配一个内部域名比如gitlab.internal.example。如果没有 DNS直接用服务器 IP 也可以但后续如果 IP 变了所有仓库的远程地址都要改比较麻烦。所以有条件的话尽量用域名。第二确定访问协议。GitLab 默认支持 HTTP 和 HTTPS。生产环境强烈建议上 HTTPS否则代码推送时的凭据是明文传输的。HTTPS 证书可以用内部 CA 签发也可以用公开的证书服务。如果只是内网测试HTTP 也能凑合用但要清楚其中的风险。第三确认端口。GitLab 默认的 Web 端口是 80 和 443SSH 端口默认是 22。如果服务器上已经有其它服务占用了这些端口需要在配置时改掉。我遇到过好几次服务器上已经跑了 Nginx 或者 SSH 服务的情况端口冲突导致 GitLab 起不来排查了半天才发现是端口被占。3. 下载程序包与快速安装部署实操3.1 系统环境准备与依赖检查正式安装之前先做几项准备工作。第一步是更新系统包索引并升级已有软件sudo apt update sudo apt upgrade -y这一步看起来简单但很重要。如果系统里有大量待更新的包不先处理掉后面安装 GitLab 时可能会因为依赖版本不匹配而报错。我有一次偷懒跳过了这步结果安装过程中提示某个库版本过低又回头来升级反而多花了时间。第二步是安装几个基础工具后面配置时会用到sudo apt install -y curl openssh-server ca-certificates tzdata perl这几个包的作用分别是curl用于下载和测试网络请求openssh-server提供 SSH 服务Git 通过 SSH 推送代码时需要ca-certificates管理证书tzdata处理时区perl是 GitLab 某些脚本的依赖。第三步是配置时区。GitLab 的日志、提交时间、CI 任务调度都和时区有关如果时区不对排查问题时会很困惑。设置时区的命令是sudo timedatectl set-timezone Asia/Shanghai设置完可以用timedatectl确认一下。我建议在安装 GitLab 之前就把时区设好而不是装完之后再改因为 GitLab 首次启动时会读取系统时区并写入配置装完再改需要重新配置。第四步是配置邮件服务。GitLab 需要发送通知邮件比如新用户注册、合并请求提醒如果不配置邮件这些功能会静默失败。最简单的方案是用系统的 Postfix 来发邮件sudo apt install -y postfix安装过程中会弹出一个配置界面选择 Internet Site 即可。当然如果你有企业邮箱或者第三方邮件服务也可以在 GitLab 配置里指定 SMTP 服务器这个后面会讲。3.2 添加官方仓库与下载安装包准备工作做完接下来就是核心步骤添加 GitLab 官方软件仓库然后安装。GitLab 官方提供了一个脚本可以自动完成仓库配置curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash这个脚本做的事情是检测你的系统版本添加对应的 GitLab 仓库地址导入 GPG 签名密钥。执行完之后可以用下面的命令确认仓库是否添加成功apt-cache policy gitlab-ce如果能看到候选版本信息说明仓库配置正确。接下来就是安装sudo EXTERNAL_URLhttp://gitlab.example.com apt install -y gitlab-ce这里的EXTERNAL_URL是 GitLab 的访问地址安装时会写入初始配置。注意这个地址要和你实际访问的地址一致否则后面生成的仓库地址、邮件里的链接都会不对。如果你暂时没有域名可以先用服务器 IP比如http://192.168.1.100。注意EXTERNAL_URL一旦设定后续修改需要重新运行gitlab-ctl reconfigure而且已经生成的仓库地址不会自动更新。所以最好一开始就确定好。安装过程会持续几分钟取决于服务器性能和网络速度。安装包大概有 1GB 左右下载加上解压配置耐心等一会儿。安装完成后终端会输出一段提示告诉你 GitLab 已经安装成功并提示你运行配置命令。3.3 首次配置与初始化安装完成后需要运行一次配置命令让 GitLab 根据/etc/gitlab/gitlab.rb里的设置来初始化各个组件sudo gitlab-ctl reconfigure这个命令是 GitLab Omnibus 包的核心它会读取配置文件然后依次配置 PostgreSQL、Redis、Nginx、Gitaly 等服务。第一次运行时间比较长大概三到五分钟期间会输出大量日志。如果中间没有报错最后会显示 gitlab Reconfigured!。配置完成后检查一下各个服务的状态sudo gitlab-ctl status正常情况下你应该能看到run: nginx、run: postgresql、run: redis、run: gitaly等服务都是run状态。如果有服务显示down需要查看对应日志排查。常见的起不来原因包括内存不足、端口被占用、配置文件语法错误。接下来获取初始管理员密码。GitLab 首次安装后会自动生成一个随机密码存放在/etc/gitlab/initial_root_password文件里sudo cat /etc/gitlab/initial_root_password这个文件在首次配置后 24 小时内有效之后会被自动删除。拿到密码后用浏览器访问你设置的EXTERNAL_URL用用户名root和这个密码登录。登录后第一件事就是修改 root 密码并创建自己的管理员账号。3.4 关键配置项调整默认配置能跑起来但有几个地方我建议根据实际情况调整。打开配置文件sudo vim /etc/gitlab/gitlab.rb第一个要关注的是外部访问地址external_url http://gitlab.example.com如果你安装时设的地址不对或者后来换了域名改这里然后重新reconfigure。第二个是 SSH 端口。如果服务器上 22 端口已经被占用比如系统自带的 SSH 服务需要给 GitLab 的 SSH 换个端口gitlab_rails[gitlab_shell_ssh_port] 2222同时要确保gitlab_rails[gitlab_shell_ssh_port]和实际监听的端口一致。改完之后用户克隆仓库时需要用ssh://githost:2222/group/project.git这种格式。第三个是邮件配置。如果你不用系统 Postfix而是用第三方 SMTP配置大概是这样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_password gitlab_rails[smtp_domain] example.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[gitlab_email_from] gitlabexample.com第四个是备份和日志的保留策略。GitLab 默认会保留一定时间的日志和备份如果磁盘空间紧张可以调整gitlab_rails[backup_keep_time] 604800这个值是秒数604800 秒等于 7 天。意思是超过 7 天的备份会被自动清理。每次修改配置文件后都要运行sudo gitlab-ctl reconfigure让改动生效。如果只改了某些组件的配置也可以只重启对应服务比如sudo gitlab-ctl restart nginx但为了保险起见我一般还是跑完整的 reconfigure。4. 安装后的验证与常见问题排查4.1 功能验证清单安装配置完成后不要急着交付给团队用先自己走一遍核心功能确认没有问题。我通常按下面的清单来验证Web 访问浏览器打开EXTERNAL_URL能看到登录页面用 root 账号能登录。创建项目新建一个测试项目确认能创建成功。SSH 克隆在本地用git clone通过 SSH 协议克隆测试项目确认 SSH 密钥认证正常。HTTP 克隆用 HTTP 协议克隆确认凭据认证正常。推送代码往测试项目推一个提交确认推送成功。合并请求创建一个合并请求确认页面能正常显示 diff。邮件通知触发一个会发邮件的操作比如新用户注册确认邮件能收到。这几项都过了基本可以确认 GitLab 的核心功能是正常的。如果某一项失败根据失败环节去查对应日志。4.2 常见问题速查表下面这张表是我在实际部署中遇到过的典型问题以及对应的排查思路和解决方法问题现象可能原因排查方法解决方法安装时提示内存不足服务器内存小于 4GBfree -h查看内存增加内存或加 swap502 错误后端服务未启动gitlab-ctl status查看日志重启服务SSH 克隆失败SSH 端口不对或被防火墙拦截ss -tlnp查看端口调整端口配置或防火墙规则邮件发不出去SMTP 配置错误gitlab-rails console测试检查 SMTP 参数页面加载慢内存不足或 CPU 瓶颈top查看资源占用升级配置或优化reconfigure 报错配置文件语法错误查看报错行号修正配置文件关于 502 错误这是最常见的问题。502 表示 Nginx 能收到请求但后端的 GitLab 应用Puma 或 Unicorn没有响应。原因通常是后端服务还在启动中或者因为内存不足被系统杀掉了。先等几分钟如果还是 502就去看/var/log/gitlab/gitlab-rails/production.log里的错误信息。关于 SSH 克隆失败我踩过好几次坑。最常见的原因是服务器防火墙没放行 GitLab 的 SSH 端口。如果你用的是 UFW需要执行sudo ufw allow 2222/tcp假设端口是 2222。另外如果服务器本身有 SSH 服务在 22 端口GitLab 的 SSH 会默认用 22导致冲突这时候必须改端口。4.3 性能调优与资源控制GitLab 默认配置对资源的利用比较保守如果服务器配置较高可以适当调优。但如果服务器配置一般反而需要限制资源占用避免 GitLab 把整台机器拖垮。对于内存较小的服务器4GB 左右我建议做以下调整puma[worker_processes] 2 sidekiq[max_concurrency] 10 postgresql[shared_buffers] 256MB这几个参数分别控制 Web 服务的 worker 数量、后台任务并发数、数据库共享缓冲区大小。调小这些值可以降低内存占用代价是并发处理能力下降。对于小团队十几个人来说这个配置够用了。对于配置较好的服务器16GB 以上可以适当调大puma[worker_processes] 4 sidekiq[max_concurrency] 25 postgresql[shared_buffers] 2GB另外GitLab 的日志会持续增长建议配置日志轮转。Omnibus 包默认已经配置了 logrotate但你可以检查一下/etc/gitlab/gitlab.rb里的logging相关配置确保日志不会把磁盘占满。提示调整任何参数后都要运行sudo gitlab-ctl reconfigure然后观察一段时间确认服务稳定。不要一次性改太多参数否则出问题不好定位是哪个改动导致的。5. 日常维护与升级策略5.1 备份与恢复自建 GitLab 最重要的一件事就是备份。代码资产丢了那是灾难性的。GitLab 提供了内置的备份命令sudo gitlab-backup create这个命令会备份数据库、仓库、上传文件等核心数据生成一个 tar 包放在/var/opt/gitlab/backups/目录下。备份文件名里包含时间戳方便识别。但要注意这个命令不备份/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json这两个文件。前者是配置文件后者包含数据库加密密钥、CI 密钥等敏感信息。这两个文件必须单独备份否则恢复时会出问题。我一般会把它们复制到一个安全的地方比如另一台服务器的备份目录。恢复的步骤稍微复杂一些大致流程是先停掉相关服务把备份文件放到指定目录运行恢复命令再重启服务。具体命令是sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq sudo gitlab-backup restore BACKUP备份文件名 sudo gitlab-ctl reconfigure sudo gitlab-ctl restart恢复完成后一定要验证数据是否完整比如检查仓库数量、用户数量、最近的提交记录。5.2 版本升级的注意事项GitLab 的版本升级有讲究不能随便跨大版本升级。官方建议的升级路径是先升级到当前大版本的最新小版本再升级到下一个大版本的最新小版本逐步推进。比如从 15.x 升到 17.x需要先升到 15 的最新版再升到 16 的最新版最后升到 17。升级命令本身很简单sudo apt update sudo apt install -y gitlab-ce sudo gitlab-ctl reconfigure但升级前一定要做两件事一是完整备份二是查看官方升级文档里的注意事项。有些版本升级会涉及数据库迁移如果中途失败回滚会很麻烦。我一般会在升级前把服务器做个快照万一出问题可以快速恢复。另外升级过程中服务会短暂中断建议安排在业务低峰期进行。如果团队对可用性要求高可以考虑搭建高可用架构但那涉及多节点部署复杂度会高很多不在本文讨论范围内。5.3 监控与告警GitLab 跑起来之后需要持续监控它的健康状态。最简单的监控方式是定期检查服务状态和关键指标。GitLab 自带了一个健康检查接口curl http://gitlab.example.com/-/health如果返回GitLab OK说明基本服务正常。还有更详细的检查接口比如/-/readiness和/-/liveness可以集成到监控系统里。对于资源监控我建议关注几个核心指标CPU 使用率、内存使用率、磁盘使用率、磁盘 IO。这些指标可以用系统自带的工具如top、iostat查看也可以接入专业的监控系统。磁盘使用率尤其要关注因为 GitLab 的仓库和日志会持续增长磁盘满了会导致服务不可用。告警方面至少要配置磁盘空间告警和内存告警。磁盘使用率超过 80% 就应该收到告警内存使用率持续超过 90% 也要告警。这些告警能让你在问题恶化之前介入处理。6. 我踩过的坑与实操心得6.1 内存不足导致的安装失败我第一次在一台 2GB 内存的服务器上装 GitLab安装过程直接卡死最后报错说内存不足。当时以为是安装包的问题重试了好几次后来才意识到是内存不够。GitLab 的 Omnibus 包在安装和首次配置时会启动多个服务内存峰值可能超过 3GB。如果服务器内存只有 2GB基本不可能装成功。解决办法有两个一是加内存二是加 swap。加 swap 是临时方案性能会差一些但至少能装起来。加 swap 的命令是sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile然后在/etc/fstab里加上一行让 swap 开机自动挂载。不过我还是建议生产环境直接用足够的内存swap 只是应急手段。6.2 端口冲突的排查过程有一次在一台已经跑了 Nginx 的服务器上装 GitLab装完之后访问 502查了半天才发现是端口冲突。GitLab 自带的 Nginx 想监听 80 端口但系统上已经有一个 Nginx 占用了 80导致 GitLab 的 Nginx 起不来。排查方法是看端口占用sudo ss -tlnp | grep :80如果看到不是 GitLab 的进程占用了 80就需要处理。要么停掉原来的服务要么改 GitLab 的端口。改端口的话在gitlab.rb里设置nginx[listen_port] 8080然后重新配置。但改端口之后访问地址也要带上端口号比如http://gitlab.example.com:8080。6.3 备份文件恢复的坑备份恢复看起来简单但有几个细节容易忽略。第一恢复时 GitLab 的版本必须和备份时的版本一致否则可能恢复失败。第二恢复前要确保目标服务器的/etc/gitlab/gitlab-secrets.json和备份时的一致否则数据库里的加密数据无法解密。第三恢复过程中如果中断可能导致数据不一致需要重新恢复。我有一次恢复备份忘了同步gitlab-secrets.json结果恢复完成后用户能登录但 CI 变量全部失效排查了很久才发现是密钥文件不对。从那以后我每次备份都会把配置文件和密钥文件一起打包恢复时一起还原。6.4 一些实用的小技巧最后分享几个日常运维中总结的小技巧。第一用gitlab-ctl tail可以实时查看所有服务的日志排查问题时很方便不用一个个去翻日志文件。第二gitlab-rails console可以进入 Rails 控制台执行一些数据库查询或修复操作比如重置用户密码、清理卡住的任务。第三定期运行gitlab-rake gitlab:check可以检查系统状态发现潜在问题。还有一个关于性能的小技巧如果团队规模不大可以把 GitLab 的 Prometheus 监控组件关掉能省不少内存。在gitlab.rb里设置prometheus_monitoring[enable] false关掉之后自带的监控面板就不能用了但如果你有自己的监控系统这个组件确实没必要开。我在几个小团队的环境里都关掉了它内存占用能降 500MB 左右效果挺明显的。