1. 为什么选择离线包安装而不是官方仓库直装很多人第一次在 Ubuntu 上部署 GitLab第一反应就是照着官方文档加个仓库源然后apt install一把梭。我最早也是这么干的结果在一台内网机器上卡了整整一个下午——仓库源拉取慢、依赖解析反复超时最后装到一半还因为磁盘空间不足直接崩了。后来我换成了下载完整程序包再本地安装的方式整个过程不到二十分钟就跑通了。这个经历让我意识到安装方式的选择本身就是部署效率的分水岭。GitLab 的安装方式大致可以分成三类官方 apt 仓库在线安装、Docker 容器化部署、以及下载独立程序包也就是 omnibus 包离线安装。这三种方式没有绝对的好坏但适用场景差别很大。在线仓库安装的好处是升级方便apt upgrade就能搞定但它对网络环境的依赖非常强而且每次安装都会去远程拉取几百兆甚至上 G 的依赖在内网或者网络不稳定的环境下体验极差。Docker 方式适合已经有一套容器编排体系的团队但对于只是想快速跑起来一个 GitLab 实例的人来说多了一层容器网络和存储卷的配置成本。而独立程序包安装本质上是把 GitLab 及其所有依赖Ruby 运行时、PostgreSQL、Redis、Nginx 等全部打包成一个.deb文件下载下来之后本地dpkg安装不依赖外部仓库装完即用。我之所以在标题里强调“下载程序包后快速安装部署”就是因为这个方式最适合以下几类人一是内网环境或者网络受限的服务器没法稳定访问外部仓库二是想快速搭一个测试环境验证功能不想在依赖问题上浪费时间三是需要对安装版本做精确控制避免在线安装时被自动升级到不兼容的新版本。这几种场景在实际工作中非常常见尤其是做私有化部署或者内部工具链搭建的时候。还有一个容易被忽略的点独立程序包安装对系统环境的侵入性更可控。在线安装时apt 会顺带更新一堆系统库有时候会跟你机器上已有的服务产生冲突。而离线包安装的依赖关系相对封闭GitLab 自带了自己的 PostgreSQL 和 Redis不会去动系统里已有的数据库实例。这一点在多服务共存的服务器上特别重要我就遇到过因为 apt 自动升级了系统 PostgreSQL 导致另一个业务库连接异常的情况后来全部改成离线包部署就没再出过这类问题。当然离线包安装也不是没有代价。最大的问题是升级不如在线方式方便每次升级都得手动下载新版本的包再安装。但换个角度想这反而给了你一个明确的升级控制点不会出现某天早上起来发现 GitLab 被自动升级到新版本、结果插件不兼容的情况。对于生产环境来说可控性往往比便利性更重要。2. 安装前的系统准备磁盘、内存与依赖的硬性门槛在动手下载程序包之前有几项系统层面的准备工作必须做扎实否则装到一半报错会让你非常被动。我踩过的最大的坑就是磁盘分区没规划好GitLab 默认把所有数据都放在/var/opt/gitlab下面仓库数据、数据库、日志全在里面如果/var分区只给了 20G用不了多久就会爆。2.1 硬件资源的最低要求与推荐配置GitLab 官方给出的最低配置是 2 核 CPU、4G 内存但这是“能跑起来”的底线实际使用中如果只有 4G 内存光是 GitLab 自身的一堆服务Puma、Sidekiq、PostgreSQL、Redis、Nginx、Gitaly 等就能把内存吃满稍微有几个仓库或者并发请求就会触发 OOM。我的经验是个人测试环境至少 4 核 8G小团队使用建议 8 核 16G 起步。磁盘方面系统盘之外最好单独挂一块数据盘给/var容量根据仓库规模来定纯代码仓库的话 100G 能撑很久但如果要存 CI 产物或者大文件就得按实际情况往上加。内存这块还有一个细节GitLab 的 Puma 和 Sidekiq 的 worker 数量是可以调的默认值往往偏保守或者偏激进需要根据实际内存来调整。这个后面在配置章节会详细说。先记住一个原则——内存不够的时候宁可减少 worker 数量也不要让系统去用 swap因为 GitLab 对 swap 的响应非常敏感一旦开始 swap整个 Web 界面会卡到无法使用。2.2 系统依赖包的安装与 locale 设置虽然独立程序包已经把 GitLab 自身的依赖都打包进去了但它仍然依赖一些系统级的基础库和工具。在 Ubuntu 上安装之前建议先执行下面这组命令把常用的依赖补齐sudo apt update sudo apt install -y curl openssh-server ca-certificates tzdata perl这里面curl用于后续可能的健康检查openssh-server是 GitLab 通过 SSH 协议进行 Git 操作的基础ca-certificates保证 HTTPS 通信正常tzdata和perl则是 GitLab 内部一些脚本运行所必需的。这些包体积都不大但缺了任何一个都可能在安装后出现莫名其妙的问题。另外一个容易被忽视的是locale 设置。如果系统的 locale 没有正确配置成 UTF-8GitLab 在初始化数据库时可能会报编码相关的错误。检查方法很简单locale如果输出里LANG不是en_US.UTF-8或者zh_CN.UTF-8之类的 UTF-8 编码就需要手动设置一下sudo locale-gen en_US.UTF-8 sudo update-locale LANGen_US.UTF-8设置完之后最好重新登录一下 shell让环境变量生效。这个步骤看起来不起眼但我确实见过因为 locale 问题导致 GitLab 安装后中文显示乱码、甚至数据库迁移失败的案例。2.3 防火墙与端口规划GitLab 默认会占用几个端口80HTTP、443HTTPS、22SSH。这里有个常见的冲突点——Ubuntu 服务器本身可能已经跑了 SSH 服务在 22 端口而 GitLab 也想用 22 端口来做 Git over SSH。解决办法有两种要么把系统 SSH 改到别的端口让 GitLab 用 22要么保持系统 SSH 在 22把 GitLab 的 SSH 端口改成别的比如 2222。我个人倾向于后者因为改系统 SSH 端口容易把自己锁在外面风险更高。如果决定让 GitLab 用非标准 SSH 端口需要在后续配置文件里显式指定并且克隆仓库的时候要带上端口号比如git clone ssh://gityour-host:2222/group/project.git。这一点在团队协作时要提前跟所有人说清楚不然大家用默认的 22 端口克隆会一直失败。防火墙方面Ubuntu 默认的 ufw 如果开启了需要放行相应端口sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 2222/tcp如果服务器前面还有一层云厂商的安全组也别忘了在安全组里放行同样的端口。我遇到过好几次“本地防火墙开了但安全组没开”的情况排查半天才发现问题出在云平台那一层。3. 程序包下载与安装从获取到 dpkg 执行准备工作做完之后就进入核心的下载和安装环节了。这一步看起来简单但里面有几个关键决策点会影响后续的使用体验。3.1 版本选择社区版还是企业版GitLab 分为社区版CE和企业版EE。社区版是开源的功能对于大多数团队来说已经足够企业版多了一些高级功能比如更细粒度的权限控制、审计日志、高级 CI 特性等但需要授权。对于个人学习或者小团队内部使用社区版完全够用。下载的时候注意文件名里带ce的就是社区版带ee的是企业版。版本号方面建议选择最新的稳定版本但不要选刚发布没几天的版本因为可能存在一些未暴露的 bug。我一般会选发布至少两周以上、社区反馈比较稳定的版本。另外要注意 Ubuntu 的版本对应关系比如 Ubuntu 20.04 对应的包名里会带focal22.04 对应jammy24.04 对应noble。下载错了版本虽然不一定装不上但可能会遇到依赖不匹配的问题。3.2 下载方式与校验下载程序包有两种途径一种是从官方提供的下载页面直接获取另一种是通过命令行工具下载。无论哪种方式下载完成后都建议做一次完整性校验避免因为下载中断导致包损坏。校验的方法通常是比对 SHA256 校验和sha256sum gitlab-ce_xxx_amd64.deb然后把结果跟官方公布的校验值对比。这一步很多人会跳过但如果包在下载过程中损坏安装时报的错会非常难排查可能表现为解压失败、依赖缺失等各种奇怪的现象。花一分钟校验一下能省掉后面可能浪费的半小时。3.3 dpkg 安装过程与常见报错处理下载完成后用dpkg命令安装sudo dpkg -i gitlab-ce_xxx_amd64.deb这个命令执行后GitLab 会自动完成一系列初始化工作包括创建git用户、建立目录结构、安装内置的 PostgreSQL 和 Redis 等。整个过程可能需要几分钟取决于机器性能。安装完成后终端会输出一段提示告诉你接下来需要配置外部访问地址并执行重新配置命令。这里有几个常见的报错场景需要提前知道怎么处理。第一个是依赖缺失如果系统里缺少某些基础库dpkg会报依赖错误这时候执行sudo apt install -f可以自动修复依赖关系。第二个是端口冲突如果 80 端口已经被 Nginx 或者 Apache 占用了安装过程本身不会报错但后续启动服务时会失败需要先停掉占用端口的服务或者修改 GitLab 的监听端口。第三个是磁盘空间不足这个在安装过程中就会直接报错退出需要清理空间后重新安装。安装完成后GitLab 的配置文件位于/etc/gitlab/gitlab.rb这是整个部署过程中最重要的文件几乎所有配置项都在这里修改。修改完之后需要执行sudo gitlab-ctl reconfigure让配置生效这个命令会重新生成所有服务的配置文件并重启相关服务。第一次执行 reconfigure 的时间会比较长因为要初始化数据库、编译资源等耐心等待即可。4. 核心配置调整让 GitLab 真正可用装完不配置GitLab 等于没装。默认配置下GitLab 只能通过http://主机名访问而且很多参数都不适合实际使用。这一章我把最关键的几个配置项拆开来讲每一项都说明为什么改、怎么改、改完什么效果。4.1 外部访问地址与端口设置打开/etc/gitlab/gitlab.rb找到external_url这一行。默认情况下它是被注释掉的你需要把它改成实际的访问地址external_url http://git.example.com或者如果直接用 IP 访问external_url http://192.168.1.100如果不想用 80 端口可以写成http://192.168.1.100:8080这样的形式。这里有个细节external_url 一旦设定GitLab 生成的仓库克隆地址、Web 界面里的链接都会基于这个地址。如果后面改了地址已经克隆到本地的仓库的 remote 地址不会自动更新需要手动改。所以最好在第一次配置时就确定好最终的访问地址避免后期迁移的麻烦。如果要用 HTTPSexternal_url 写成https://git.example.com然后还需要配置 SSL 证书。GitLab 支持自动申请 Lets Encrypt 证书也支持手动指定证书路径。自动申请需要域名能公网解析内网环境一般用手动证书或者干脆先用 HTTP后面再通过反向代理加 SSL。4.2 邮件服务配置让通知真正发出去GitLab 默认不发邮件这意味着用户注册、密码重置、MR 通知等功能都无法正常工作。配置邮件服务需要修改gitlab.rb里的 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配置完之后执行 reconfigure然后可以用gitlab-rails console进入控制台测试发信Notify.test_email(testexample.com, Test Subject, Test Body).deliver_now如果收不到邮件先检查垃圾箱再检查 SMTP 参数是否正确特别是端口和加密方式是否匹配。很多邮件服务商对 587 端口用 STARTTLS465 端口用 SSL配错了就连不上。4.3 内存与 worker 数量调优前面提到过GitLab 默认的 worker 数量可能不适合你的机器。在gitlab.rb里可以调整 Puma 和 Sidekiq 的并发参数puma[worker_processes] 2 sidekiq[max_concurrency] 10puma[worker_processes]控制 Web 服务的 worker 进程数一般设置为 CPU 核心数或者核心数减一。sidekiq[max_concurrency]控制后台任务处理的并发数内存小的话可以调低到 5 或者更少。调整的原则是在内存够用的前提下尽量提高并发但一旦发现系统开始频繁使用 swap就要果断往下调。还有一个内存相关的配置是 PostgreSQL 的共享缓冲区postgresql[shared_buffers] 256MB默认值通常偏小适当调大可以提升数据库性能但不要超过总内存的 25%。这些参数没有绝对的最优值需要根据实际负载慢慢调。我的建议是先用默认值跑一段时间观察free -h和gitlab-ctl status的输出再针对性地调整。4.4 备份策略与数据安全GitLab 自带备份工具可以通过gitlab-backup命令创建备份。在gitlab.rb里可以配置备份保留时间和备份路径gitlab_rails[backup_keep_time] 604800 gitlab_rails[backup_path] /var/opt/gitlab/backupsbackup_keep_time的单位是秒604800 就是保留 7 天。备份路径建议改到独立的数据盘上避免跟系统盘抢空间。创建备份的命令是sudo gitlab-backup create这个命令会备份数据库、仓库数据、上传文件等但不包括配置文件。所以完整的备份策略应该是程序数据用 gitlab-backup 备份配置文件/etc/gitlab 目录单独用 tar 打包备份。恢复的时候先恢复配置文件再恢复数据顺序不能反。5. 首次访问与初始化设置配置完成并 reconfigure 成功之后就可以通过浏览器访问 GitLab 了。第一次访问会要求设置 root 用户的密码这个密码至少 8 位设置完成后用 root 账号登录。登录之后有几件事建议立刻做。第一是修改 root 用户的邮箱默认是adminexample.com改成真实邮箱才能收到系统通知。第二是关闭用户注册如果这是内部使用的实例在设置里把注册功能关掉避免陌生人注册账号。第三是创建第一个普通用户和项目验证整个流程是否正常。如果访问时出现 502 错误通常是 Puma 还没完全启动等一两分钟再刷新。如果一直 502检查gitlab-ctl status看哪个服务没起来再看对应的日志/var/log/gitlab/下面定位问题。最常见的原因是内存不足导致 Puma 被 OOM killer 杀掉了这时候需要降低 worker 数量或者加内存。还有一个首次访问常见的问题是静态资源加载失败页面样式全乱。这通常是因为 external_url 配置的地址跟实际访问的地址不一致导致浏览器加载 CSS/JS 时请求了错误的域名。检查一下 external_url 是否跟浏览器地址栏里的一致包括协议http/https和端口号。6. 踩坑记录那些文档里不会写的细节这一章我专门记录几个在实际部署中踩过的坑都是官方文档里不会重点提、但一旦遇到就很头疼的问题。6.1 reconfigure 卡住不动的排查思路gitlab-ctl reconfigure有时候会卡在某一步很久不动看起来像是死掉了。这种情况大多数时候不是真的卡死而是在执行一些耗时的初始化操作比如数据库迁移、资源预编译等。判断方法很简单另开一个终端用top或者htop看 CPU 和内存占用如果 Ruby 或者 PostgreSQL 进程在活跃地跑就说明还在工作耐心等就行。但如果 CPU 占用很低、进程也几乎不动那可能是真的卡住了。常见原因是网络问题导致某个远程请求超时或者磁盘 I/O 瓶颈。这时候可以看/var/log/gitlab/reconfigure.log里的最后几行通常能定位到卡在哪一步。如果是网络问题检查一下机器是否能正常解析域名、是否能访问外部地址。6.2 磁盘空间被日志吃满的处理GitLab 的日志量不小尤其是开启了 CI/CD 之后各种构建日志会快速堆积。默认情况下日志会一直保留时间长了能把磁盘吃满。解决办法有两个一是配置日志轮转在gitlab.rb里设置logging[logrotate_frequency] daily logging[logrotate_rotate] 7这样日志每天轮转一次保留 7 份。二是定期清理旧的 CI 构建日志可以在 Web 界面的管理区域里手动清理也可以通过 API 批量删除。我建议两个都做轮转是兜底定期清理是主动控制。6.3 升级时的注意事项离线包安装的升级方式是下载新版本的.deb包然后再次执行dpkg -i。但升级前一定要做两件事备份数据和备份配置文件。升级过程中如果出现意外没有备份就只能重装了。另外GitLab 不支持跨大版本直接升级比如从 14.x 直接升到 16.x 是不行的需要先升到 15.x 的最后一个版本再升到 16.x。这个升级路径在官方文档里有说明升级前务必确认清楚。升级完成后同样需要执行gitlab-ctl reconfigure然后检查各个服务是否正常启动。如果升级后发现某些功能异常可以查看升级日志或者回滚到旧版本前提是有备份。6.4 性能问题的常见来源GitLab 跑起来之后如果感觉慢通常有几个来源。一是内存不足导致频繁 swap这个用free -h一看便知。二是 PostgreSQL 的配置不合理比如 shared_buffers 太小、work_mem 不够等。三是 Gitaly 的磁盘 I/O 瓶颈如果仓库很多很大Gitaly 的磁盘读写会成为瓶颈建议把仓库存储放在 SSD 上。四是 Puma 的 worker 数量跟 CPU 核心数不匹配太少处理不过来太多互相抢资源。排查性能问题我一般按这个顺序来先看内存和 swap再看 CPU 负载然后看磁盘 I/O最后看具体服务的日志。大部分情况下加内存和换 SSD 能解决 80% 的性能问题。7. 日常运维的几条实用建议部署完成只是开始日常运维才是真正考验人的地方。我分享几条自己总结的实用建议都是实际工作中验证过的。第一条是定期检查备份是否可用。很多人配了备份但从来没验证过恢复流程等到真需要恢复的时候才发现备份文件是坏的或者恢复步骤不对。建议至少每个季度做一次恢复演练在测试环境里用备份文件完整恢复一次确保流程走得通。第二条是监控磁盘和内存的使用趋势。可以用简单的 shell 脚本配合 cron 定时记录也可以用现成的监控工具。关键是要在磁盘快满之前收到告警而不是等满了之后服务挂了才发现。第三条是保持版本更新但不要追新。安全补丁要及时打但大版本升级要谨慎等社区反馈稳定了再升。升级前做好备份和回滚预案。第四条是文档化所有配置变更。每次改了gitlab.rb里的什么参数、为什么改、改完什么效果都记下来。时间长了之后这些记录就是最好的运维手册比任何官方文档都管用。第五条是控制用户和项目的增长节奏。GitLab 用久了之后用户和项目会越来越多如果不加管理磁盘和性能都会吃不消。建议定期清理不活跃的项目和用户对仓库大小设置上限避免有人往仓库里提交大文件。这些建议看起来都是常识但真正坚持做下来的人不多。我在实际运维中最大的体会就是部署本身可能只需要半小时但让这套系统稳定运行半年一年靠的是日复一日的细心维护。把备份、监控、文档这三件事做好基本上就不会出大问题。