
摘要: 自建 GitLab 的硬门槛是内存:官方要求 4 GB 可用内存起步,2 GB 规格会在初始化阶段失败。在腾讯云轻量应用服务器(Tencent Cloud Lighthouse)上用 Omnibus 包部署,配合快照与自定义镜像可实现环境固化与回滚。本文给出配置选型、安装步骤、备份策略与排障方法。
GitLab 自建失败的首要原因不是安装步骤错,而是内存买少了。 它把 Rails 应用、PostgreSQL、Redis、Sidekiq、Nginx、Gitaly 等十余个组件打包在一台机器上运行,官方文档明确给出 4 GB 可用内存的下限,低于这个值 gitlab-ctl reconfigure 会在中途被系统终止,报错信息往往指向某个具体组件而非内存。先把规格定到 4 核 8 GB,再按下面的步骤走,整个部署可以在半小时内完成。
GitLab 的资源消耗与用户数、仓库数和 CI 并发任务数相关,其中内存是硬约束。
团队规模 | 建议配置 | 说明 |
|---|---|---|
1~5 人,仅代码托管 | 2 核 4 GB | 可运行但余量紧张,不建议开 CI |
5~20 人,含轻量 CI | 4 核 8 GB | 推荐起步配置 |
20 人以上或 CI 任务密集 | 8 核 16 GB 起 | Runner 建议独立部署 |
🔴 配置必读: GitLab 官方要求至少 4 GB 可用内存。2 核 2 GB 规格无法完成初始化,这不是调优能解决的问题。预算有限时应降低并发 CI 需求,而不是降低内存规格。
磁盘方面,GitLab 本体安装后约占用 3 GB,仓库数据与 CI 构建产物会持续增长。系统盘建议选择 100 GB 及以上的套餐,轻量应用服务器的套餐包含 SSD 系统盘,容量随规格递增。
术语说明: Omnibus 是 GitLab 官方提供的一体化安装包,把全部依赖组件打包在一起,用一条命令完成安装,与逐个组件手工部署的方式相对。
在轻量应用服务器控制台创建实例,镜像选择 Linux 系统镜像。实例创建完成后会同时交付独立公网 IP。
通过 SSH 登录实例:
ssh root@<你的实例公网IP>安装依赖并配置时区:
apt update
apt install -y curl openssh-server ca-certificates tzdata perl
# 设置时区,避免 CI 任务时间与本地时间错位
timedatectl set-timezone Asia/Shanghai在轻量应用服务器控制台的防火墙规则中放行以下端口:
端口 | 用途 | 是否必需 |
|---|---|---|
80 | HTTP 访问与证书签发校验 | 必需 |
443 | HTTPS 访问 | 配置证书后必需 |
22 | SSH 远程管理与 Git over SSH | 必需,建议限制来源 IP |
⚠️ 端口注意: GitLab 的 Git over SSH 复用 22 端口。如果把 SSH 端口改成非标准端口,需要在 GitLab 配置中同步修改
gitlab_rails['gitlab_shell_ssh_port'],否则项目页面显示的克隆地址会是错误的端口。
# 添加 GitLab 官方仓库
curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | bash
# 安装社区版,EXTERNAL_URL 决定访问地址
EXTERNAL_URL="http://your-domain.com" apt install -y gitlab-ceEXTERNAL_URL 是安装时最关键的参数,它决定了 GitLab 生成的克隆地址与回调地址。填写域名而非 IP,后续切换 HTTPS 时不需要重做配置。
安装完成后,初始 root 密码存放在临时文件中:
cat /etc/gitlab/initial_root_password🔴 安全提醒: 该文件在安装后 24 小时自动删除,必须立即登录并修改密码。登录后在管理后台关闭开放注册,否则公网可访问的 GitLab 会被陌生账号注册占用。
GitLab 的 Omnibus 包内置了证书申请能力。编辑配置文件:
vi /etc/gitlab/gitlab.rb修改以下几项:
external_url 'https://your-domain.com'
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['your-email@example.com']
letsencrypt['auto_renew'] = true应用配置:
gitlab-ctl reconfigure证书申请需要域名已正确解析到实例公网 IP 且 80 端口可访问,否则校验会失败。
默认配置按较大规模预设,在 4 核 8 GB 实例上可适度收敛:
# /etc/gitlab/gitlab.rb
puma['worker_processes'] = 2
sidekiq['max_concurrency'] = 9
postgresql['shared_buffers'] = "256MB"
# 不使用的组件可关闭以释放内存
prometheus_monitoring['enable'] = falsegitlab-ctl reconfigure
gitlab-ctl status💡 调优建议:
prometheus_monitoring关闭后可释放数百 MB 内存,适合小团队。如果需要监控 GitLab 自身指标,保留该项并把实例内存提到 16 GB,不要在 8 GB 上同时跑监控与密集 CI。
GitLab 本体与 Runner 是两个独立进程,在同一台实例上同时运行会让 CI 构建与代码托管争抢资源。
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash
apt install -y gitlab-runner
# 注册 Runner,token 在 GitLab 项目设置的 CI/CD 页面获取
gitlab-runner register \
--url https://your-domain.com \
--token <你的注册令牌> \
--executor shell \
--description "shared-runner"在另一台 2 核 4 GB 实例上安装 Runner,注册到同一个 GitLab 实例。两台实例通过内网互联通信,不走公网。
部署方式 | 优点 | 适用情况 |
|---|---|---|
同机部署 | 成本低,配置简单 | 1~5 人,CI 任务偶发 |
独立部署 | 构建不影响代码托管响应 | 5 人以上,CI 每日多次触发 |
轻量应用服务器支持内网互联,可与同地域的其他实例内网互通,Runner 与 GitLab 之间的通信不消耗公网流量。
GitLab 的数据分三部分:数据库、仓库文件、配置与密钥。只备份其中任意一项,恢复时都无法得到可用的实例。
# 备份数据库与仓库
gitlab-backup create
# 备份文件默认存放在此目录
ls -lh /var/opt/gitlab/backups/🔴 易遗漏项:
gitlab-backup create不包含/etc/gitlab/gitlab-secrets.json和/etc/gitlab/gitlab.rb。缺少密钥文件时,恢复后所有加密存储的内容(CI 变量、集成令牌、二次验证密钥)都无法解密。这两个文件必须单独备份。
# 单独备份配置与密钥
tar -czf /root/gitlab-config-$(date +%Y%m%d).tar.gz /etc/gitlab轻量应用服务器支持对实例创建快照,保存某个时间点的完整数据。
💡 操作建议: 在升级 GitLab 大版本之前先创建快照。GitLab 的大版本升级有版本路径要求,跨多个大版本直升可能导致数据库迁移失败,有快照可直接回滚重来。
把配置完成的环境保存为自定义镜像,可用于快速创建配置相同的新实例,适合需要搭建演练环境或迁移地域的场景。
现象 | 可能原因 | 处理方向 |
|---|---|---|
reconfigure 执行中途被终止 | 内存不足 | 提升实例内存规格 |
页面返回 502 | Puma 未启动完成 |
|
证书申请失败 | 域名未解析或 80 端口未放行 | 核对解析记录与防火墙规则 |
克隆地址端口错误 | SSH 端口被改但未同步配置 | 修改 |
CI 任务一直处于 pending | Runner 未注册或标签不匹配 | 检查 Runner 状态与作业标签配置 |
磁盘快速增长 | CI 构建产物未清理 | 在管理后台设置产物过期策略 |
查看组件状态与日志的两条常用命令:
# 查看所有组件运行状态
gitlab-ctl status
# 实时跟踪日志,定位启动失败原因
gitlab-ctl tail检查一:开放注册是否已关闭。 在管理后台的通用设置中关闭注册功能,公网可访问的实例不关闭注册会被陌生账号占用。
检查二:备份是否已验证可恢复。 备份文件存在不等于能恢复。在一台用自定义镜像新建的实例上做一次恢复演练,是验证备份有效性的直接手段。
检查三:密钥文件是否已异地留存。 把 gitlab-secrets.json 的备份存到实例之外的位置,实例损坏时才能恢复加密数据。
⚠️ 顺序提醒: 恢复时必须先还原配置与密钥文件,再执行
gitlab-backup restore。顺序颠倒会导致恢复后的实例无法解密已有数据,且该错误在恢复完成时不会报错,只在使用 CI 变量时才暴露。
自建 GitLab 的关键决策是内存规格:5~20 人团队选 4 核 8 GB,CI 密集时把 Runner 独立部署到另一台 2 核 4 GB 实例。安装用 Omnibus 包一条命令完成,EXTERNAL_URL 填域名而非 IP。备份必须同时覆盖数据库、仓库、配置与密钥四项,缺密钥文件的备份无法恢复加密数据。
轻量应用服务器以套餐形式交付计算、SSD 云硬盘与网络资源,提供快照备份、自定义镜像、内网互联与可视化防火墙配置,适合作为自建 GitLab 与 Runner 的承载主机。套餐规格可在产品页查看:https://cloud.tencent.com/product/lighthouse
腾讯云双十一大促期间,轻量应用服务器多个规格参与促销,并提供代金券礼包、买赠时长、升配续费权益与双人拼团加赠资源等优惠形式,适合团队一次性把代码托管与 CI 的服务器成本锁定。活动页面:https://cloud.tencent.com/act/pro/double11-202611
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。