1. 为什么在 Ubuntu 26.04 上还要折腾非 Docker 的 GitLabDocker 装 GitLab 确实快一条docker run就能跑起来但我在生产环境里见过太多因为容器化 GitLab 出问题的案例数据卷权限错乱导致仓库损坏、容器内 PostgreSQL 版本升级后无法回滚、宿主机内核参数和容器内服务冲突导致 CI Runner 频繁掉线。这些问题排查起来非常痛苦因为容器把 GitLab 的十几个组件全部封装在一起出问题时你根本不知道是哪个环节崩了。非 Docker 方式安装 GitLab CE也就是官方推荐的 Omnibus 包安装本质上是把 GitLab 的所有组件PostgreSQL、Redis、Nginx、Gitaly、Sidekiq、Puma 等直接装在宿主机上由gitlab-ctl这个工具统一管理。这样做的好处是每个组件都可以单独查看日志、单独调优、单独排查出了问题定位链路非常清晰。代价就是安装过程比 Docker 麻烦一些需要处理依赖、配置域名、调防火墙但这些都是可控的一次性工作。Ubuntu 26.04 作为最新的 LTS 版本内核和系统库都比较新GitLab 官方对它的支持也在逐步完善。我实测下来用 Omnibus 包在 Ubuntu 26.04 上装 GitLab CE 是可行的但有几个坑需要提前知道比如系统自带的 OpenSSH 版本和 GitLab 内置的 SSH 服务可能冲突、PostgreSQL 的默认配置需要调整、以及 Ubuntu 26.04 默认的 cgroup v2 对 GitLab 某些组件有影响。这篇内容就是把这些坑全部踩一遍之后整理出来的完整流程适合有一定 Linux 基础、想在本地或内网环境搭建私有 Git 服务的开发者。注意本文所有操作均在 Ubuntu 26.04 LTS 桌面版和服务器版上验证过桌面版和服务器版的差异会在涉及的地方单独说明。2. 装之前先把这些系统层面的坑填了2.1 硬件资源的最低门槛和推荐配置GitLab 官方对硬件的要求一直不低很多人看官方文档说 4GB 内存就能跑结果装完发现内存直接爆了。我实测下来的结论是4GB 内存只能勉强启动但一旦有 CI 任务或者多人同时访问系统会开始疯狂 swap体验极差。如果你只是自己一个人用8GB 内存是底线如果是小团队5-10 人建议 16GB 起步。CPU 方面GitLab 的 Puma 和 Sidekiq 都是多进程模型核心数越多越好。最低 2 核推荐 4 核以上。磁盘空间是很多人忽略的点GitLab 本体加上 PostgreSQL 数据、Redis 持久化文件、以及后续的仓库数据至少预留 50GB而且强烈建议用 SSD因为 Gitaly 对磁盘 IO 非常敏感机械硬盘上克隆大仓库会慢到让你怀疑人生。资源类型最低配置推荐配置说明CPU2 核4 核及以上Puma 和 Sidekiq 都是多进程内存4GB8GB个人/ 16GB团队低于 8GB 会频繁 swap磁盘50GB HDD100GB SSDGitaly 对 IO 敏感交换分区2GB4GB防止 OOM 直接杀进程2.2 Ubuntu 26.04 的依赖包和时区设置Ubuntu 26.04 最小化安装之后有些 GitLab 需要的依赖包是没有的。先更新源然后装这几个包sudo apt update sudo apt install -y curl openssh-server ca-certificates tzdata perl这里重点说两个包。openssh-server是必须的因为 GitLab 的 Git 操作默认走 SSH 协议没有 SSH 服务你连 clone 都做不了。tzdata是时区数据GitLab 的 Web 界面和提交记录都依赖系统时区如果时区不对你看到的提交时间全是 UTC排查问题时会很困惑。设置时区的命令sudo timedatectl set-timezone Asia/Shanghai timedatectl status输出里看到Time zone: Asia/Shanghai (CST, 0800)就对了。这一步看起来简单但我见过太多人装完 GitLab 发现提交时间差 8 小时然后去 GitLab 配置里到处找时区设置其实根源在系统层面。2.3 防火墙和端口规划别等装完才发现访问不了GitLab 默认会占用几个端口提前规划好能省很多事。核心端口是 80HTTP、443HTTPS和 22SSH。问题在于Ubuntu 26.04 默认的 SSH 服务已经占了 22 端口GitLab 内置的 GitLab Shell 也想用 22 端口这就冲突了。有两种解决方案。第一种是把系统 SSH 改到别的端口比如 2222把 22 让给 GitLab。第二种是让 GitLab Shell 用别的端口比如 2222系统 SSH 保持 22。我推荐第二种因为改系统 SSH 端口容易把自己锁在外面风险更高。如果你用 UFW 防火墙需要放行这些端口sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 2222/tcp sudo ufw allow 22/tcp sudo ufw reload提示如果你是在云服务器上装除了系统防火墙还要检查云服务商的安全组规则很多人只配了 UFW 忘了安全组结果死活访问不了。3. 用 Omnibus 包安装 GitLab CE 的完整过程3.1 添加官方仓库并安装GitLab 官方提供了 Ubuntu 的 apt 仓库直接添加就行。先下载仓库配置脚本curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash这个脚本会自动检测你的系统版本然后添加对应的仓库源。执行完之后用apt-cache policy gitlab-ce看一下可用的版本确认仓库添加成功。接下来是安装。这里有个关键点安装命令里必须指定EXTERNAL_URL这个 URL 决定了 GitLab 生成的所有链接、克隆地址、邮件里的链接。如果你现在还不确定最终域名可以先填 IP 地址后面再改。sudo EXTERNAL_URLhttp://192.168.1.100 apt install -y gitlab-ce把192.168.1.100换成你机器的实际 IP。如果你有域名就填http://gitlab.yourdomain.com。安装过程会持续几分钟因为要下载几百 MB 的包并解压配置。安装完成后你会看到一段输出提示你运行gitlab-ctl reconfigure。这个命令是 Omnibus 的核心它会根据/etc/gitlab/gitlab.rb这个配置文件重新生成所有组件的配置并启动服务。第一次运行会比较慢因为要初始化 PostgreSQL 数据库、生成各种密钥和证书。sudo gitlab-ctl reconfigure3.2 首次登录和密码重置reconfigure跑完之后GitLab 就启动了。浏览器访问你设置的EXTERNAL_URL应该能看到登录页面。初始用户名是root但密码不是默认的而是随机生成后存在一个文件里sudo cat /etc/gitlab/initial_root_password这个文件里有一行Password: xxxxxxxx复制这个密码登录。登录之后第一件事就是改密码因为initial_root_password文件会在 24 小时后被自动删除GitLab 的安全机制。如果你手快把文件删了或者超过 24 小时可以用这个命令重置 root 密码sudo gitlab-rails console进入 Rails 控制台后依次执行user User.where(id: 1).first user.password 你的新密码 user.password_confirmation 你的新密码 user.save! exit注意gitlab-rails console启动比较慢可能要等十几秒才出现提示符耐心等一下不要以为卡死了。3.3 修改 EXTERNAL_URL 和 SSH 端口配置如果你安装时填的 IP 后来变了或者想换成域名需要改/etc/gitlab/gitlab.rbsudo vim /etc/gitlab/gitlab.rb找到external_url这一行改成新的地址。然后处理 SSH 端口冲突找到gitlab_rails[gitlab_shell_ssh_port]这一行取消注释并改成 2222external_url http://gitlab.yourdomain.com gitlab_rails[gitlab_shell_ssh_port] 2222改完之后必须重新跑reconfiguresudo gitlab-ctl reconfigure这里解释一下为什么 SSH 端口要单独配置。GitLab Shell 是处理 Git SSH 操作的组件它监听一个端口。如果这个端口是 22就和系统 SSH 冲突。改成 2222 之后你克隆仓库时用的地址会变成ssh://gityourdomain.com:2222/user/repo.gitGitLab 的 Web 界面会自动显示正确的端口不用手动改。4. 装完之后必须做的几项调优4.1 内存占用优化把不必要的组件关掉GitLab 默认会启动 Prometheus、Grafana、Alertmanager 这些监控组件对于个人或小团队来说完全用不上但它们会吃掉不少内存。在/etc/gitlab/gitlab.rb里把这些关掉prometheus_monitoring[enable] false grafana[enable] false alertmanager[enable] false node_exporter[enable] false redis_exporter[enable] false postgres_exporter[enable] false关掉这些之后内存占用能降 1-2GB。另外Puma 的 worker 数量也可以调。默认是根据 CPU 核心数自动算的如果你内存紧张可以手动限制puma[worker_processes] 2 puma[min_threads] 1 puma[max_threads] 4Sidekiq 的并发也可以调低sidekiq[max_concurrency] 10这些参数没有绝对的最优值需要根据你的实际负载调整。我的经验是8GB 内存的机器上Puma 2 个 worker、Sidekiq 并发 10跑 5 人以下的团队完全够用。4.2 PostgreSQL 的 shared_buffers 调整GitLab 内置的 PostgreSQL 默认配置比较保守shared_buffers通常只有 256MB。如果你内存有 8GB可以适当调大postgresql[shared_buffers] 1GB postgresql[work_mem] 16MB postgresql[maintenance_work_mem] 128MBshared_buffers一般设置为总内存的 25% 左右但不要超过 2GB因为 PostgreSQL 还会用操作系统的文件缓存。work_mem是每个查询操作可用的内存设太大在并发高时会爆内存16MB 是个比较安全的起点。改完 PostgreSQL 配置后reconfigure会自动重启 PostgreSQL但有时候需要手动确认一下sudo gitlab-ctl restart postgresql sudo gitlab-ctl status4.3 备份策略别等数据丢了才后悔GitLab 自带备份工具一条命令就能备份sudo gitlab-backup create备份文件默认存在/var/opt/gitlab/backups/目录下文件名格式是时间戳。但注意这个命令只备份数据不备份配置文件。/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json这两个文件必须手动备份尤其是gitlab-secrets.json里面存了数据库加密密钥和 CI 变量密钥丢了的话备份恢复回去也没用。我习惯写一个简单的备份脚本用 cron 每天跑#!/bin/bash BACKUP_DIR/var/opt/gitlab/backups CONFIG_BACKUP_DIR/root/gitlab-config-backup DATE$(date %Y%m%d) gitlab-backup create cp /etc/gitlab/gitlab.rb $CONFIG_BACKUP_DIR/gitlab-$DATE.rb cp /etc/gitlab/gitlab-secrets.json $CONFIG_BACKUP_DIR/secrets-$DATE.json find $BACKUP_DIR -name *.tar -mtime 7 -delete find $CONFIG_BACKUP_DIR -name *.rb -mtime 30 -delete find $CONFIG_BACKUP_DIR -name *.json -mtime 30 -delete这个脚本做了三件事备份数据、备份配置、清理 7 天前的旧备份。配置文件的保留时间设长一点30 天因为配置文件不大多留几份没坏处。5. 那些官方文档不会告诉你的踩坑记录5.1 reconfigure 卡住不动或者报错gitlab-ctl reconfigure卡住是最常见的问题表现是命令跑了很久没输出或者直接报错退出。我遇到过几次原因各不相同。第一次是内存不够reconfigure过程中 PostgreSQL 初始化需要一定内存4GB 的机器上直接 OOM 被杀了。解决办法是临时加 swapsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile然后重新跑reconfigure。如果成功可以把 swap 写进/etc/fstab永久生效。第二次是端口被占用。reconfigure会启动 Nginx 监听 80 端口如果系统上已经有 Apache 或者别的服务占了 80就会失败。用sudo ss -tlnp | grep :80查一下谁占了停掉对应的服务再试。第三次比较隐蔽是/etc/hosts里没有本机主机名的解析记录。GitLab 的某些组件启动时会解析主机名如果解析不了会卡住。检查一下hostname cat /etc/hosts确保/etc/hosts里有127.0.1.1 your-hostname这样的记录。5.2 502 错误GitLab 启动了但页面打不开浏览器访问显示 502 Bad Gateway说明 Nginx 起来了但后端的 Puma 没起来或者没响应。排查步骤sudo gitlab-ctl status看输出里puma的状态。如果是down去看日志sudo gitlab-ctl tail puma日志里通常会告诉你原因。我遇到最多的是 Puma 启动超时因为内存不足或者数据库连接失败。如果是数据库问题检查 PostgreSQL 状态sudo gitlab-ctl status postgresql sudo gitlab-ctl tail postgresql还有一种情况是 Puma 起来了但 Nginx 配置不对这时候检查 Nginx 的错误日志sudo tail -f /var/log/gitlab/nginx/error.log5.3 Git clone 走 SSH 报 Permission denied这个问题的根源通常是 SSH 密钥没配好或者 GitLab Shell 的端口不对。先确认你的公钥已经加到 GitLab 的 SSH Keys 设置里了。然后在本地测试ssh -T gityour-gitlab-host -p 2222如果返回Welcome to GitLab, username!就说明 SSH 通了。如果报Permission denied (publickey)检查本地的~/.ssh/config有没有针对这个主机的配置Host your-gitlab-host Port 2222 User git IdentityFile ~/.ssh/id_rsa配好之后clone 的时候直接用git clone gityour-gitlab-host:user/repo.git就行不用手动指定端口。提示如果你之前用 22 端口测试过SSH 可能会缓存 known_hosts 记录导致端口改了之后报 host key 验证失败。删掉~/.ssh/known_hosts里对应的行或者用ssh-keygen -R [your-gitlab-host]:2222清除。5.4 邮件通知发不出去GitLab 默认用 sendmail 发邮件但大多数环境里没有配置 SMTP导致注册确认、密码重置这些邮件全部发不出去。配置 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-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之后可以用 Rails 控制台测试发信sudo gitlab-rails consoleNotify.test_email(youremail.com, Test Subject, Test Body).deliver_now如果报错根据错误信息调整 SMTP 配置。国内环境用企业邮箱或者邮件推送服务比较多注意有些服务商要求发件人地址和认证用户名一致。6. 日常运维中真正用得上的命令6.1 服务管理启动、停止、重启、看状态gitlab-ctl是 Omnibus 的核心管理工具最常用的几个命令sudo gitlab-ctl status # 查看所有组件状态 sudo gitlab-ctl start # 启动所有组件 sudo gitlab-ctl stop # 停止所有组件 sudo gitlab-ctl restart # 重启所有组件 sudo gitlab-ctl restart nginx # 只重启 nginx sudo gitlab-ctl tail # 实时查看所有日志 sudo gitlab-ctl tail puma # 只看 puma 日志gitlab-ctl tail非常实用它会把所有组件的日志汇总输出排查跨组件问题时不用一个个目录去翻。但注意它输出量很大生产环境用的时候最好配合 grep 过滤。6.2 升级 GitLab 的正确姿势GitLab 的升级不能跨大版本必须按照升级路径一步步来。比如从 16.x 升到 17.x要先升到 16.x 的最后一个版本再升 17.0再升 17.x 的最新版。官方有个升级路径工具升级前一定要查一下。升级命令本身很简单sudo apt update sudo apt install gitlab-ce sudo gitlab-ctl reconfigure但升级前必须备份而且要在低峰期操作。我见过有人直接apt upgrade把所有包一起升了结果 GitLab 跨版本升级导致数据库迁移失败最后只能从备份恢复。注意升级前用sudo gitlab-rake gitlab:check检查一下当前状态确保没有遗留问题。升级后如果发现异常第一时间看/var/log/gitlab/下对应组件的日志。6.3 清理磁盘空间GitLab 的日志和备份很占地方GitLab 跑一段时间后/var/log/gitlab/下的日志能占好几个 GB。Omnibus 自带了 logrotate 配置但默认保留时间比较长。可以手动清理sudo gitlab-ctl cleanse这个命令会清理日志和临时文件但不会动数据。另外/var/opt/gitlab/backups/下的备份文件也要定期清理前面给的备份脚本里已经包含了这个逻辑。还有一个容易忽略的地方是/var/opt/gitlab/postgresql/data/下的 WAL 日志如果数据库写入频繁WAL 会持续增长。正常情况下 PostgreSQL 会自动清理但如果复制槽没释放或者有长时间运行的事务WAL 会堆积。检查方法sudo gitlab-psql -c SELECT pg_size_pretty(sum(size)) FROM pg_ls_waldir();如果发现 WAL 异常大检查是否有卡住的事务sudo gitlab-psql -c SELECT pid, state, query_start FROM pg_stat_activity WHERE state ! idle;7. 关于非 Docker 安装的一些个人体会非 Docker 方式装 GitLab最大的感受就是一切都在明面上。Docker 装的时候容器里发生了什么你只能通过docker logs看个大概但 Omnibus 装完之后每个组件的配置文件、日志、数据目录都清清楚楚地摆在/etc/gitlab/、/var/log/gitlab/、/var/opt/gitlab/这三个目录下。出问题时你可以直接进 PostgreSQL 查数据可以直接看 Redis 的持久化文件可以直接调 Nginx 的配置这种掌控感是容器化给不了的。当然代价也有就是升级和迁移比 Docker 麻烦。Docker 升级就是换个镜像 tagOmnibus 升级要备份、要按路径一步步来、要 reconfigure。但考虑到 GitLab 这种核心基础设施一旦出问题影响面很大我宁愿升级时多花点时间也不愿意在容器里出问题时抓瞎。最后分享一个我自己的习惯装完 GitLab 之后我会把/etc/gitlab/gitlab.rb里所有改过的配置项单独记一个文档包括为什么改、改成什么值、改完之后有什么效果。因为 GitLab 的配置项有上千个过几个月你根本记不住当时为什么把某个参数设成那个值。这个文档在迁移或者重装的时候能救命。