2026年GitLab安装部署全攻略：从包管理到Docker及初始化配置

GitLab版本一年年往前追，不同系统下的安装方式也跟着变。早些年大家习惯先装一堆依赖再手动配，现在官方推荐的基本就是Omnibus包或者Docker容器两条路。这篇就按我实际部署的经验，把2026年这个时间点上，几类主流系统装最新版GitLab的完整流程、坑点、和安装之后的必要配置一次讲清楚。无论你是刚接触GitLab的新手，还是准备给公司内部搭一套代码托管平台的老手，按着下面的步骤走，基本都能顺下来。

先说一个重要的认知：GitLab的安装其实不复杂，复杂的是版本选型和环境适配。官方对不同系统的支持优先级不同，有些系统用包管理器一行命令搞定，有些系统就得走Docker化路线。别一上来就“我想在某某老系统上装”，先确认你的系统版本在不在官方支持列表里，不然装到一半遇到依赖冲突，排查起来非常头疼。这篇文章主要覆盖Ubuntu/Debian、CentOS/RHEL系、Docker以及Windows/macOS的开发环境方案，这几种是我实际验证过的主流路径。

1. 不同系统安装方案该怎么选

1.1 先搞明白几个版本概念

在动手之前，先把几个关键词理清楚，不然很容易装错东西。

GitLab分两个发行版：CE（Community Edition，社区版）和EE（Enterprise Edition，企业版）。CE功能对中小团队完全够用，EE主要是多了LDAP高级集成、审计事件、多集群管理等企业级功能。现在官方下载页默认引导下载EE，但EE装了之后没License会自动以CE模式运行，所以很多人为了省事直接装EE包。我的建议是：如果你确定不需要企业功能，就直接安装CE包，名字就叫gitlab-ce，干净利落。

另外要注意“最新版”这个词。2026年这个节点，GitLab的月度发布节奏还在延续，大版本已经迭代到了17.x，小版本号每月递增。所谓最新版，建议理解为“当前最新的稳定版本”，不要追RC版本。RC版本虽然功能新，但踩坑概率明显更高，生产环境千万别用。

最后，GitLab官方还区分了Omnibus安装方式和源码安装方式。源码方式现在基本已经不推荐了，编译时间长、升级麻烦、依赖复杂，除非你有极特殊需求，否则一律用Omnibus包。它相当于把PostgreSQL、Redis、Nginx、Puma等所有组件全部打包在一起，安装完直接通过gitlab-ctl这个命令统一管理，省心得多。

1.2 系统兼容性与资源要求

GitLab对服务器的要求不算低，尤其是内存。我列一个参考表，按团队规模来选配置：

团队规模	推荐内存	推荐CPU	存储建议	说明
个人/小型团队（5人以下）	4GB	2核	SSD 20GB+	基本能跑，但别开太多CI并发
中型团队（10-50人）	8GB	4核	SSD 50GB+	日常使用流畅，可跑轻量CI
大型团队（50人以上）	16GB+	8核+	SSD 100GB+	强烈建议独立服务器部署

内存低于4GB的机器跑GitLab会很吃力，Swapping会频繁发生，页面打开慢不说，后台Sidekiq任务还可能堆积。最简单的判断标准：如果你的云服务器只有2GB内存，建议要么上Docker方案并限制内存，要么直接选择托管版，别硬撑。

系统支持方面，Ubuntu 20.04/22.04/24.04、Debian 11/12、CentOS 7/8/9（包括Rocky Linux、AlmaLinux等衍生版）都在官方支持列表上。RHEL系和Debian系的安装方式略有不同，后面我分开讲。

2. 安装前的基础准备与环境检查

2.1 系统更新、依赖整理与主机名

安装之前，先把系统自带的包索引更新到最新。这里有个小提示：不要盲目执行apt upgrade或yum update把所有包都升一遍，尤其是生产服务器，升级内核或其他关键库可能导致现有服务异常。只更新包索引就行，把依赖留给GitLab的安装脚本去处理。

类Debian系统执行：

sudo apt update

类RHEL系统执行：

sudo yum check-update

接下来检查主机名。GitLab默认会使用当前机器的主机名生成访问地址，如果你不提前设置好，装完访问起来会很别扭。建议先把主机名改成你的目标域名，比如git.example.local。

sudo hostnamectl set-hostname git.example.local

同时确保/etc/hosts里配置了对应的解析条目，至少本机解析要通：

echo "127.0.0.1 git.example.local" | sudo tee -a /etc/hosts

这一步很多人忽略，但实际影响很大。GitLab安装过程中会基于主机名生成本地存储目录和URL配置，如果后头再改，涉及的东西比较多，一会儿我给流程。

2.2 防火墙与端口规划

GitLab默认通过Nginx监听80端口（HTTP）和443端口（HTTPS）。如果你的服务器上有其他服务占用了80，或者你打算把GitLab挂在非标准端口上，建议在安装前就规划清楚。

在云服务器上操作时，还需要同步检查安全组规则。我遇到过好多次，装完之后本机curl没问题，外部浏览器就是访问不了，最后一查全是安全组只开放了22端口，忘了放行80和443。

Ubuntu自带的UFW防火墙需要放开端口：

sudo ufw allow 80/tcp sudo ufw allow 443/tcp

CentOS自带的firewalld用：

sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --permanent --add-service=https sudo firewall-cmd --reload

端口规划这里多说一句：如果80和443已经被其他Web服务占用，有两个选择，一是把所有服务通过反向代理统一管理，给GitLab分配子路径或子域名；二是改GitLab的external_url，把端口设置成8080之类的自定义端口。我更推荐第一种方式，统一入口好维护，证书也好管理。

2.3 配置GitLab软件源

在包管理器直接安装GitLab之前，需要先把官方软件源配好。不同发行版的源地址不同，但原理都一样。

Ubuntu/Debian系统，执行官方脚本一键添加：

curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

RHEL/CentOS系统则执行：

curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash

这个脚本会自动写入对应的.list或.repo文件。如果你自己手动添加源，注意保持packages.gitlab.com这个官方源地址，第三方镜像源的时效性和安全性都没法保证。

国内网络环境下，这个源有可能连接缓慢。我的经验是apt源偶尔超时，可以适当调整APT的重试时间和超时时间：

sudo sh -c 'echo "Acquire::Retries \"5\";" > /etc/apt/apt.conf.d/80-retries'

这样至少能避免网络抖动导致的中断。

3. 各主流系统的GitLab安装实操步骤

3.1 Ubuntu/Debian系安装流程

Ubuntu系的安装命令非常简洁，只需要一条命令指定好地址和版本包名，安装脚本会自动处理依赖：

sudo EXTERNAL_URL="http://git.example.local" apt-get install -y gitlab-ce

这条命令相当于先设置external_url为GitLab生成初始配置，再安装包。安装过程会持续几分钟，中间会自动完成依赖安装、数据库初始化、服务启动一系列动作。正常情况看到gitlab Reconfigured!就说明安装成功了。

如果你之前已经装过老版本GitLab，需要升级到最新版，直接执行：

sudo apt-get update sudo apt-get install -y gitlab-ce

它会自动拉取最新版本并原地升级，配置文件一般不需要动。但务必注意：升级前一定要备份，不是“应该备份”，是“必须备份”。

Debian系统的安装过程和Ubuntu基本一致，唯一的差异在于Debian的软件源策略偏保守，可能默认没有安装curl或gnupg，需要先补齐：

sudo apt-get install -y curl gnupg

然后再执行添加源的脚本。

3.2 CentOS/RHEL系安装流程

RHEL系服务器用yum/dnf安装，命令形式类似：

sudo EXTERNAL_URL="http://git.example.local" dnf install -y gitlab-ce

CentOS 7及一些老系统默认用的还是yum，写法相同，把dnf替换成yum即可。RHEL系有一个很典型的坑：默认的SELinux策略可能会拦截GitLab的Nginx访问，报错往往表现为网页打不开，但本机端口正常监听。

如果你在RHEL系的机器上安装后访问异常，建议先临时把SELinux设为permissive模式验证一下：

sudo setenforce 0

如果设置之后能正常访问，说明问题出在SELinux策略上。你可以选择永久关闭SELinux（测试环境无所谓），也可以在SELinux开启状态下放行对应端口，生产环境建议用后者：

sudo semanage port -a -t http_port_t -p tcp 80 sudo semanage port -a -t http_port_t -p tcp 443

CentOS 8/9系上，注意默认的dnf源里也可能缺一些依赖。官方安装脚本会先把epel-release源装好，这是正常的，不用管。

3.3 Docker方式安装与升级

如果你的服务器不想装一堆依赖，或者说你本身就是容器化运维的实践者，那直接用Docker跑GitLab会清爽很多。先拉镜像：

docker pull gitlab/gitlab-ce:latest

然后挂载三个目录：配置目录、数据目录、日志目录。官方推荐的方式是全部挂在一个总目录下：

sudo mkdir -p /srv/gitlab/config /srv/gitlab/data /srv/gitlab/logs docker run --detach \ --hostname git.example.local \ --publish 443:443 --publish 80:80 --publish 22:22 \ --name gitlab \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ --shm-size 256m \ gitlab/gitlab-ce:latest

这里有个细节：--shm-size 256m容易被人忽略，GitLab对应的PostgreSQL和Puma在容器里如果共享内存给得太小，某些高并发场景容器可能出现诡异的内存错误，提前给大一些能避免这个问题。

Docker方式升级更轻松，先停掉容器，然后重新拉取最新镜像再启动：

docker stop gitlab docker rm gitlab docker pull gitlab/gitlab-ce:latest docker run ... # 同样的参数

数据都保存在宿主机挂载目录里，所以镜像升级对数据无影响，前提是你没有手滑删掉/srv/gitlab目录。我有一个习惯，任何容器性删除操作之前都先把目录改个名字备份，例如mv /srv/gitlab /srv/gitlab_bak，升级确认没问题再清掉，稳妥得很。

3.4 macOS与Windows上的轻量方案

macOS用户最常见的场景是本地开发调试，并不建议直接跑一个完整GitLab，太吃资源。如果你就是想在本地快速体验最新版，推荐用Colima或者Docker Desktop跑容器版，命令和上一小节一样，只是不需要设置太大的--shm-size，本地调调用默认的256m就够。

Windows环境分两种情况：如果你的开发环境是基于WSL2，那在WSL发行版里用Docker跑GitLab完全没问题，甚至可以直接在WSL2里安装Ubuntu，再按Ubuntu正式流程安装，效果等同于一台Linux服务器。如果你是纯Windows环境且没有WSL，那就只能靠Docker Desktop支撑，操作上也绕不开虚拟化这一层，性能有损耗，但作为临时体验和环境验证也足够。

需要特别提醒的是：Windows上直接访问容器里的22端口可能会和本机的OpenSSH服务冲突。如果遇到端口占用，可以把容器端口映射成宿主机的其他端口，比如--publish 2222:22。之后在GitLab里配置SSH地址时，记得使用ssh://[e-mail]:2222/group/project.git这种带端口的URL格式。

4. 安装完成后的初始化配置与核心设置

4.1 首次访问与root密码

安装完成后，访问你设置的EXTERNAL_URL，第一次访问会强制要求设置root用户的密码。默认root密码其实已经存在了，它被存放在临时文件里，虽然很多新版本给了Web端设置引导，但我更习惯直接用命令行设置：

sudo gitlab-rails runner "user = User.where(username: 'root').first; user.password = '新密码'; user.password_confirmation = '新密码'; user.save!"

设置完成之后，用root账号登录，第一件事是到“Admin Area”里关闭用户自注册功能，或者开启管理员审核。不然任何访问到你GitLab首页的人都能自己注册账号，这在公网环境下就是严重的安全隐患。

4.2 关闭Prometheus等非必要组件

GitLab Omnibus版本默认会一起安装Prometheus、Grafana、Alertmanager等监控组件。这些组件对个人部署来说几乎用不到，但占用的内存和CPU却实实在在。我实测过，关闭这些组件能让内存占用下降不少，对资源紧张的服务器来说非常值。

打开/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 gitlab_exporter['enable'] = false

改完后执行：

sudo gitlab-ctl reconfigure

这时候内存占用会明显降下来。我的经验是，一台默认配置的GitLab在刚装完时内存占用可能在3GB以上，关闭不必要的组件后可以控制到2GB左右。

4.3 配置HTTPS证书

HTTP方式跑GitLab在局域网内没问题，但一旦涉及公网访问，或者浏览器里总是弹不安全警告，就得配置HTTPS。官方最省事的方案是直接内置的Let's Encrypt自动申请：

在gitlab.rb中设置：

external_url 'https://git.example.local' letsencrypt['enable'] = true letsencrypt['contact_emails'] = ['[e-mail]']

执行reconfigure之后，GitLab会自动完成证书申请和续期。不过要注意，自动申请Let's Encrypt证书的前提是：服务器80和443端口在公网能被直接访问到，且域名解析正常指向服务器IP。若满足不了这个条件，申请过程会一直报错，这时你就得走手动配置证书的路子，把证书文件放到服务器上，然后在gitlab.rb里指定：

nginx['ssl_certificate'] = "/etc/gitlab/ssl/fullchain.pem" nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/private.key"

4.4 配置SMTP邮件服务

GitLab很多功能依赖邮件通知，比如注册确认、找回密码、流水线失败提醒。如果没有配置SMTP，用户名下这些通知全都收不到。在gitlab.rb里追加几行配置即可，这里用常见的SMTP示例：

gitlab_rails['smtp_enable'] = true gitlab_rails['smtp_address'] = "smtp.example.com" gitlab_rails['smtp_port'] = 465 gitlab_rails['smtp_user_name'] = "[e-mail]" 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-ctl reconfigure生效。要验证发送功能是否正常，可以用Rails Runner发一封测试邮件：

sudo gitlab-rails runner "Notify.test_email('[e-mail]', 'Hello', 'Body').deliver_now"

如果收到邮件，说明SMTP配置成功。没收到的话优先检查端口是否被云平台安全组屏蔽，以及邮箱账号是否使用了独立授权码。

5. 日常运维与常见问题排查实录

5.1 配置修改后如何正确生效

很多人在gitlab.rb里改了配置，然后顺手重启一下服务，发现没生效，原因是改配置后的标准动作不是重启，而是reconfigure。

sudo gitlab-ctl reconfigure

这个命令会根据最新的gitlab.rb重新生成所有子服务的配置，并重启受影响的服务。它才是修改配置之后的唯一正确动作。

如果你只是改了环境变量或者代码相关配置，想快速让改动生效而不做完整reconfigure，可以单独重启某一项服务。比如重启Puma：

sudo gitlab-ctl restart puma

5.2 常见安装问题排查速查

问题现象	可能原因	排查/解决方式
安装完成后网页打不开	防火墙/安全组未放行80、443	检查UFW/firewalld及云安全组
访问显示502，后台无法启动	内存不足，Puma或PostgreSQL崩了	查看日志：sudo gitlab-ctl tail，适当增加内存或关监控组件
yum install报依赖冲突	软件源缓存问题	先yum clean all清理缓存，再重试
Docker容器反复重启	挂载目录权限问题	确认/srv/gitlab目录归属和权限，必要时chmod -R 755
升级后看不到新版本	软件源缓存未刷新	apt源执行apt-get update，yum源执行yum makecache
Let's Encrypt证书申请失败	80端口不通或域名解析不对	验证公网端口连通性，确认DNS解析到该服务器

5.3 备份与恢复的正确姿势

GitLab的备份命令是很经典的：

sudo gitlab-backup create

它会默认把备份文件存到/var/opt/gitlab/backups目录。这里有一个关键点：上面的命令只备份了数据库和仓库数据，不包括gitlab.rb配置文件、TLS证书等。完整的备份应该手动把/etc/gitlab/目录也拷贝一份。

我个人的习惯是写一个简单的cron任务，每周日凌晨执行数据库备份，每天执行一次配置文件同步：

0 2 * * * /usr/bin/gitlab-backup create CRON=1 30 2 * * * tar czf /backups/gitlab-config-$(date +\%F).tar.gz /etc/gitlab

注意cron环境变量和PATH配置问题，建议在crontab里用命令的绝对路径。

恢复数据时，先停掉相关服务，然后执行：

sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq sudo gitlab-backup restore BACKUP=你的备份文件名

恢复完成再启动服务，并执行reconfigure确保配置重新渲染。整个过程中最怕的就是备份文件权限不对，导致恢复到一半报错。所以备份完要顺手检查一下文件是否存在、权限是否为git:git。

5.4 清理日志与仓库维护

GitLab运行时间长了，日志文件会越堆越大，CI任务日志更夸张。定期清理是个好习惯。

sudo gitlab-ctl logrotate

这样可以手动触发一次日志滚动。仓库层面，GitLab自带垃圾回收机制，一般不需要干预。但如果你发现某个大仓库执行Git操作卡顿，可以在项目界面里触发一次“Housekeeping”，或者在服务器上针对性地执行：

cd /var/opt/gitlab/git-data/repositories/你的仓库路径 sudo git gc --prune=now --aggressive

只是执行前最好确认仓库没有正在进行的写入操作，不然会锁仓库。我吃过这个亏，凌晨执行GC把仓库锁了几小时，正好撞上同事跑CI，搞得大家都懵了。

6. 升级路线与长期维护心得

6.1 要不要追最新稳定版

GitLab的升级节奏是一个月一个版本，从15.x到16.x到17.x，每个大版本的升级路径都有官方文档说明。这里我给一个实用建议：没必要每个小版本都追，但也不要跨大版本太多。合理的升级节奏是每两到三个月份升级一次到当时的稳定版，升级前先把官方升级文档的注意事项过一遍，特别是涉及数据库迁移的部分。

跨大版本升级一定要按官方路径走。比如从16.x升级到17.x，如果当前版本距离目标版本中间隔了太多版本，官方会要求先升级到指定的中间版本，再继续往上跳。这个步骤不是走走形式，是因为数据库结构需要逐版本迁移，跳级经常会出现字段冲突或数据不一致。

6.2 环境隔离与演练

升级GitLab不是小事，我强烈建议在测试环境先演练一遍完整流程。操作步骤是这样的：

1. 在另一台相同系统版本的机器上装一份相同版本的GitLab
2. 定期把生产环境的备份文件拷贝过来，恢复到测试环境
3. 在测试环境执行升级
4. 升级成功后对关键功能做冒烟测试

这套流程看着繁琐，但能帮你提前发现80%以上的升级问题。尤其是大型团队，一旦生产环境升级失败，恢复过程可比升级过程痛苦多了。

6.3 关于gitlab.rb配置，尽量最小化修改

最后说一个我自己的经验教训。GitLab的gitlab.rb有几百个可配置项，但你真正需要改的可能就四五个：external_url、SMTP、证书路径、是否启用某些组件、git_data_dir等。剩下的大部分设置保持默认值就好，不要看到什么觉得“优化一下”就去改。每改一项配置，之后升级都可能成为需要额外关注的点。配置越多，升级时发生冲突的概率就越大。

有一次我在客户的服务器上看到一份被改得面目全非的gitlab.rb，前面的运维为了“追求性能”改了几十项参数。结果每次升级都提心吊胆，还要手动对比新旧配置。后来我花了一个晚上把配置重构回最简状态，只保留必要项，之后升级就顺畅多了。这个案例说明，保持配置精简，长期维护的负担会小很多。

在实际使用中，我的最终体会是：GitLab的部署本身不是瓶颈，真正考验人的是对这个系统的理解和长期维护的耐心。版本选型、备份策略、升级节奏，这些都在安装之前就应该想清楚。按照本文的路径走完一遍，后续的日常使用基本不会有什么大问题。遇到特殊情况时，优先看日志再动手，多数问题都能定位出来。