CentOS 7 离线部署 GitLab 13.1.2 实战：Omnibus 安装、汉化与性能调优

1. 为什么在 CentOS 7 上装 GitLab 13.1.2 这件事值得单独写一篇CentOS 7 的生命周期已经进入尾声但现实情况是大量中小团队的内网服务器、离线机房、测试环境里跑的还是 CentOS 7。GitLab 13.1.2 这个版本发布于 2020 年年中属于 13.x 系列里相对稳定的一版很多团队当年就是拿它做代码托管和 CI 起步的。现在回头看这个组合有点老将配老枪的意思但它依然有非常实际的价值内网代码托管、离线环境部署、老硬件复用、以及作为升级到更高版本的跳板。我前后在三四套不同的 CentOS 7 环境里装过 GitLab从最开始的照着官方文档一路回车到后来被各种报错教育踩过的坑足够写满一页纸。这篇内容就是把这些经验整理出来面向的是需要在 CentOS 7 上落地 GitLab 13.1.2 的运维和开发同学不管你是第一次装还是装到一半卡住了都能从里面找到能直接用的东西。需要先明确一点GitLab 13.1.2 的安装方式有好几种源码编译、Docker、Omnibus 包。在 CentOS 7 上Omnibus 包是唯一值得推荐的方式原因后面会详细说。这篇内容围绕 Omnibus 展开把环境准备、安装、配置、汉化、常见报错、性能调优这几块讲透。2. 装之前必须想清楚的几件事版本、硬件与安装方式2.1 为什么锁定 13.1.2 而不是直接上最新版很多人会问既然要装为什么不装最新的这里有几个现实约束。第一是系统兼容性。GitLab 从 14.x 开始逐步收紧对 CentOS 7 的支持到 15.x、16.x 基本要求 CentOS 8 或 Rocky/Alma 这类替代品。CentOS 7 的内核是 3.10glibc 版本也偏老新版本 GitLab 依赖的一些组件在这个环境下会出问题。13.1.2 是最后一个在 CentOS 7 上原生舒适的大版本区间之一。第二是资源占用。GitLab 是个全家桶它把 Nginx、PostgreSQL、Redis、Gitaly、Sidekiq、Prometheus 这些组件全打包在一起。13.1.2 相比后来的版本内存占用要温和一些。我实测过13.1.2 在 4GB 内存的机器上勉强能跑起来而 15.x 在同样配置下基本会 OOM。第三是升级路径。GitLab 的升级有严格的路径要求不能跨大版本乱跳。如果你现在装 13.1.2未来想升到 14、15是有明确升级链的但如果一开始就装个中间版本反而可能卡在某个升级节点上。2.2 硬件配置的最低线和推荐线GitLab 官方给的最低配置是 2 核 4GB但这是能启动的线不是能用的线。我把实际经验整理成下面这张表使用场景CPU内存磁盘说明个人测试/学习2 核4GB20GB必须配 swap否则容易 OOM5-10 人小团队4 核8GB50GB推荐配置日常使用流畅20 人以上团队8 核16GB100GB需要额外调优考虑拆分组件带 CI/CD 的场景8 核起16GB 起按构建量定Runner 最好独立部署这里有个容易被忽略的点磁盘 IO 比磁盘容量更重要。GitLab 的 PostgreSQL 和 Gitaly 对随机读写很敏感如果用机械硬盘clone 大仓库的时候会明显卡顿。条件允许的话数据盘用 SSD。2.3 Omnibus、Docker、源码编译三条路的取舍我把三种方式的对比列出来方便你做决策Omnibus 包官方维护一条命令安装所有组件版本经过验证升级方便。缺点是黑盒感强出问题要翻日志。CentOS 7 首选。Docker 部署隔离性好迁移方便。但在 CentOS 7 上老版本 Docker 和 GitLab 镜像的兼容性需要额外验证而且数据卷管理、端口映射对新手不友好。源码编译能深度定制但依赖管理极其痛苦Ruby、Node、Go 各版本要求严格编译一次大半天。除非有特殊定制需求否则不要碰。结论很明确CentOS 7 GitLab 13.1.2走 Omnibus。3. 环境准备那些装完才后悔没提前做的事3.1 系统基础配置与依赖补齐拿到一台干净的 CentOS 7别急着装 GitLab先把地基打好。第一步是更新系统并装基础工具yum update -y yum install -y curl policycoreutils-python openssh-server openssh-clients systemctl enable sshd systemctl start sshdpolicycoreutils-python这个包很关键GitLab 安装过程中会用到semanage命令来配置 SELinux 策略缺了它安装脚本会报错。很多人卡在这一步就是因为最小化安装的 CentOS 7 没带这个包。接下来处理防火墙。GitLab 默认用 80 和 443 端口如果你改了端口记得同步放行firewall-cmd --permanent --add-servicehttp firewall-cmd --permanent --add-servicehttps firewall-cmd --reload注意如果你的环境里 SELinux 是 enforcing 状态GitLab 的安装脚本会自动配置相关策略。但如果之前手动改过 SELinux 配置建议先确认状态避免安装后服务起不来。3.2 主机名、时区与 swap 的隐藏影响主机名这件事看起来小但影响不小。GitLab 生成的仓库地址、clone URL 都会用到主机名。如果主机名是默认的localhost后面改起来很麻烦。建议提前设置hostnamectl set-hostname gitlab.internal echo 127.0.0.1 gitlab.internal /etc/hosts时区也要设对否则 GitLab 里的提交时间、日志时间全是 UTC排查问题时会很别扭timedatectl set-timezone Asia/Shanghaiswap是 4GB 内存机器的救命稻草。GitLab 的组件多内存峰值容易冲高没有 swap 的话 OOM Killer 会直接把进程干掉。创建 swap 的方法dd if/dev/zero of/swapfile bs1M count4096 chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo /swapfile swap swap defaults 0 0 /etc/fstab这里有个经验swap 大小建议是物理内存的 1 到 2 倍但不要超过 8GB太大反而拖慢系统。另外swappiness参数可以调低一点让系统尽量用物理内存echo vm.swappiness 10 /etc/sysctl.conf sysctl -p3.3 安装源配置与网络连通性检查GitLab 的 Omnibus 包体积不小13.1.2 的包大概 700MB 左右。如果你的服务器不能直连外网需要提前把包下载好传进去。能联网的话配置好 yum 源然后安装 GitLab 的仓库配置脚本curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash这个脚本会自动配置 yum 源。但要注意它会拉取最新的仓库配置如果你要装特定版本后面用yum install时指定版本号即可。网络检查这块重点确认两件事一是服务器能不能访问 GitLab 的包仓库二是安装完成后客户端能不能访问服务器的 80/443 端口。前者用curl -I测后者装完再测。4. 正式安装从拉包到首次登录的完整链路4.1 指定版本安装与依赖解析配置好源之后安装命令要指定版本否则会装成最新版yum install -y gitlab-ce-13.1.2-ce.0.el7.x86_64如果提示找不到这个版本可以先看看仓库里有哪些版本yum list gitlab-ce --showduplicates | sort -r安装过程中yum 会自动解析依赖。GitLab 的 Omnibus 包依赖不多主要是openssh-server、postfix这类基础组件。如果卡在依赖上多半是 yum 源的问题检查一下/etc/yum.repos.d/下的配置。安装完成后先别急着启动。GitLab 的配置文件在/etc/gitlab/gitlab.rb第一次启动前最好先改好外部访问地址否则启动后再改要重新配置耗时更长。4.2 gitlab.rb 里真正需要改的那几个参数/etc/gitlab/gitlab.rb这个文件有几千行但真正需要动的就那么几个。我把它整理成表格参数默认值建议值作用external_urlhttp://gitlab.example.comhttp://你的域名或IP外部访问地址gitlab_rails[time_zone]UTCAsia/Shanghai时区unicorn[worker_processes]自动内存GB数1Web 工作进程数postgresql[shared_buffers]自动内存的 1/4数据库缓存prometheus_monitoring[enable]true小内存机器设 false监控组件开关改external_url是最关键的一步。如果你用 IP 访问就写http://192.168.x.x如果有域名写域名。注意这里不要带端口除非你确实改了端口。对于 4GB 内存的机器强烈建议关掉 Prometheus 监控能省下几百 MB 内存prometheus_monitoring[enable] false改完配置后执行重配置gitlab-ctl reconfigure这一步会跑很久5 到 15 分钟都正常因为它要初始化数据库、编译资源、启动所有组件。期间不要中断中断了可能要清理状态重来。4.3 首次登录与初始密码处理reconfigure跑完之后检查服务状态gitlab-ctl status看到所有组件都是run状态就说明起来了。然后浏览器访问你配置的external_url。GitLab 13.1.2 的初始密码处理有个变化早期版本会把初始密码写在一个文件里13.x 开始要求首次访问时直接设置 root 密码。如果你访问页面后没看到设置密码的界面可以手动重置gitlab-rails console -e production进入控制台后user User.where(id: 1).first user.password 你的新密码 user.password_confirmation 你的新密码 user.save! exit注意密码至少 8 位且不能是弱密码否则保存会失败。控制台里操作要小心改错了可能影响其他数据。登录进去之后第一件事是创建普通用户、建组、建项目验证 clone 和 push 是否正常。这一步能跑通说明基础功能没问题。5. 装完之后的高频报错与排查思路5.1 502 错误Unicorn 没起来还是超时502 是装完 GitLab 后最常见的报错。它的本质是 Nginx 转发请求给 UnicornGitLab 的 Web 服务但 Unicorn 没响应。原因通常有三类第一类是内存不足。Unicorn 启动需要一定内存如果机器内存被占满进程起不来。排查方法free -h gitlab-ctl status看 Unicorn 的状态如果是down或者反复重启基本就是内存问题。解决办法是加内存或加 swap或者减少unicorn[worker_processes]。第二类是启动超时。GitLab 首次启动时Unicorn 要加载大量 Ruby 代码如果机器性能差可能超过 Nginx 的等待时间。这种情况等几分钟再刷新通常就好了。第三类是配置错误。比如external_url写错、端口冲突。检查/var/log/gitlab/unicorn/下的日志能看到具体报错。5.2 邮件不发送Postfix 与 SMTP 的配置陷阱GitLab 默认用本机的 Postfix 发邮件但本机 Postfix 发出去的邮件基本会被当成垃圾邮件而且很多环境根本没配 Postfix。实际使用中建议直接配置外部 SMTPgitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.example.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] gitlabexample.com gitlab_rails[smtp_password] 你的密码 gitlab_rails[smtp_domain] example.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] true gitlab_rails[gitlab_email_from] gitlabexample.com改完reconfigure之后可以用控制台测试发信gitlab-rails consoleNotify.test_email(testexample.com, Test Subject, Test Body).deliver_now如果报错重点看密码是不是授权码很多邮箱服务要用授权码而不是登录密码、端口对不对465 是 SSL587 是 STARTTLS。5.3 磁盘涨得比预期快日志与备份的清理GitLab 跑一段时间后磁盘会莫名其妙涨得很快。主要来源有三个日志/var/log/gitlab/下的日志尤其是 Nginx 和 Sidekiq 的默认不轮转或轮转周期长。备份如果你配了自动备份/var/opt/gitlab/backups/会堆积。Prometheus 数据如果没关监控/var/opt/gitlab/prometheus/会持续增长。处理办法在gitlab.rb里配置日志轮转定期清理备份小内存机器直接关掉 Prometheus。另外/var/opt/gitlab/gitlab-rails/uploads/和shared/目录也会随使用增长要纳入监控。6. 汉化、调优与日常维护的实战经验6.1 汉化包的获取与版本匹配GitLab 官方不带中文需要自己打汉化补丁。汉化包的版本必须和 GitLab 版本严格对应13.1.2 就要找 13.1.2 的汉化包差一个小版本都可能出问题。汉化的基本流程是下载对应版本的汉化包覆盖到 GitLab 的安装目录然后重新编译资源。具体路径和命令因汉化包而异核心是先备份原文件出问题能回滚。注意汉化后升级 GitLab 时汉化会被覆盖需要重新打。所以如果团队对中文界面不是刚需建议直接用英文省去维护成本。6.2 针对小内存机器的参数调优4GB 内存的机器要跑 GitLab必须做减法。除了前面说的关 Prometheus还有几个参数可以调unicorn[worker_processes] 2 unicorn[worker_timeout] 60 sidekiq[concurrency] 10 postgresql[shared_buffers] 512MB postgresql[max_worker_processes] 4sidekiq[concurrency]控制后台任务并发数默认值偏高小机器上降到 10 左右比较稳。postgresql[shared_buffers]设成内存的 1/4 左右4GB 机器给 512MB 到 1GB。调完这些reconfigure一次然后用free -h和gitlab-ctl status观察一段时间确认稳定。6.3 备份、恢复与升级前的准备动作GitLab 自带的备份命令很好用gitlab-rake gitlab:backup:create备份文件默认在/var/opt/gitlab/backups/。恢复的时候gitlab-ctl stop unicorn gitlab-ctl stop sidekiq gitlab-rake gitlab:backup:restore BACKUP备份文件名 gitlab-ctl start升级前一定要做两件事一是完整备份二是确认升级路径。GitLab 不能跨大版本升级13.1.2 要升到 14.x得先升到 13.x 的最后一个版本再升 14.x 的第一个版本一步步来。升级命令就是yum install指定新版本然后reconfigure。我在实际维护中最大的体会是GitLab 的稳定性很大程度上取决于前期配置是否合理。装的时候多花半小时调参数比后面出问题再救火划算得多。尤其是内存和磁盘这两块小机器上一定要提前规划别等 OOM 了才想起来加 swap。另外分享一个小技巧gitlab-ctl tail可以实时看所有组件的日志排查问题时比一个个翻日志文件高效得多。配合gitlab-ctl status一起用大部分问题都能快速定位。