最近后台收到好几个朋友问同一个问题2026年了想在自己服务器上装一套最新版GitLab为什么网上教程都是零几年的老古董照着一步步操作全是坑我前阵子刚好帮团队在四台不同系统的机器上部署了一遍GitLab —— 一台Ubuntu 24.04、一台Debian 12、一台CentOS Stream 9还有一台Windows上的测试服务器。折腾下来最大的感受是GitLab官方文档其实写得相当清楚真正让人头大的从来不是“命令敲不对”而是不同系统之间依赖差异、软件源配置方式、权限模型和端口策略完全不一样一套教程根本吃不下所有环境。这篇文章我就把自己在2026年这个时间点部署最新版GitLab的完整过程、选型逻辑和踩坑记录整理出来。内容覆盖Linux系统Debian/Ubuntu系、RHEL/CentOS系和Windows/macOS环境下的常见安装路径重点讲清楚每个命令背后的原因以及装完之后的初始化配置、升级迁移和常见问题排查。适合运维、后端开发、团队技术负责人参考也适合第一次接触自托管代码平台的新手照着操作。1. 动手之前先定三件事系统、硬件与域名规划很多人拿到GitLab安装教程就开始敲命令五分钟装完半小时后发现自己在一个完全跑不动的环境里硬撑。我在部署之前会先把三件事定下来用什么操作系统、机器配置够不够、域名和端口怎么规划。这三件事没想清楚后面每一步都会别扭。1.1 内存是第一道门槛不同配置的真实表现GitLab是一套综合体不只是Web界面它同时跑着Nginx、Puma新版已经彻底用Puma替代了Unicorn、PostgreSQL、Redis、Sidekiq、Prometheus等一堆组件。官方推荐配置是4GB内存起步8GB才会“舒服”。但现实里很多人手头只有2GB甚至1GB的云主机所以你需要知道不同配置下的真实表现内存能否安装实际体验1GB可以装但基本跑不动安装完成reconfigure耗时很长打开页面经常超时Sidekiq频繁重启2GB勉强运行小团队几人代码托管和Issue能用但推送大仓库时会卡顿4GB推荐最低线日常操作流畅但CI并发跑起来压力明显8GB及以上推荐多项目、多成员、CI Runner并发都相对稳定如果你手头只有2GB我的建议是安装前先配Swap。GitLab在刚启动时对内存的瞬时需求很高我见过不少2GB内存机器装完以后Puma进程直接被系统杀掉的情况加了4GB Swap之后才稳定下来。配置Swap很简单sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile不过要记住Swap只是兜底方案GitLab本身对磁盘I/O敏感Swap用多了照样卡。有条件还是把内存加上去。1.2 系统版本怎么选LTS优先还是尝鲜不同系统安装GitLab的难度差异主要来自软件源配置和依赖库版本。我在2026年实测的几个系统里体验排序大概是这样的Ubuntu LTS22.04/24.04官方支持最完善软件源脚本一键配置依赖冲突最少。如果不是有特殊原因这是省心程度最高的选择。Debian12/13和Ubuntu走同样的deb包路线同样稳定。需要注意的是部分精简版Debian系统自带依赖不全装之前先补基础软件包。CentOS Stream / RHEL系走rpm包路线整体也没问题但默认的防火墙策略firewalld和SELinux会在装完后给你制造额外的“惊喜”需要额外处理。Windows/macOS官方不提供原生安装包主流的做法是Docker容器化或者干脆用虚拟机跑Linux。这在后面会单独展开。系统选型的核心逻辑就一句话能用Linux就用Linux能用最新LTS版本就别用老版本。GitLab对较老系统的支持窗口是有限的比如某些老版本系统在新版GitLab发布后很快就从官方支持列表中移除等你想升级GitLab时会发现系统先不满足要求了进退两难。1.3 external_url决定后续一切域名与端口想清楚再装很多人忽略了这个看起来无关紧要的配置实际上external_url是GitLab安装配置里最核心的一个选项。它决定了GitLab内置Nginx监听什么域名、生成的项目克隆地址长什么样、API和Webhook回调会往哪里发。我见过最经典的错误是装的时候图省事填了一个IP地址比如http://192.168.1.100结果后面配置了HTTPS证书GitLab生成的克隆地址还是http://192.168.1.100所有项目都要手动改地址CI/CD里的Webhook全部要重新配置。我的建议是即使你现在没有正式域名也请先在hosts里绑定一个规划好最终要用的域名比如http://gitlab.example.local或者https://git.example.com。同时想清楚端口策略默认GitLab占用80/443如果你机器上已经有其他Nginx在跑就要提前给GitLab换端口而不是装完再改不然装完第一步reconfigure就可能听到端口冲突的报错。2. Linux系安装软件源配置与Omnibus包的前后细节Linux系统上安装GitLab主线方案只有一条使用官方Omnibus安装包。这套方案把GitLab及其依赖的PostgreSQL、Redis、Nginx等全部打包成一套整体安装完由gitlab-ctl统一管理省去了手动装数据库和Web服务器的步骤。2.1 为什么Omnibus包是官方推荐路径网上有一些“源码安装”教程告诉你从GitLab源码仓库拉代码、装一堆Ruby依赖、自己配数据库最后还要手动维护Unicorn/Puma进程。我强烈建议你看到这类教程直接关掉。源码安装意味着每次升级都要手动处理依赖变动、数据库迁移、配置文件合并任何一个环节出错都可能让整个服务起不来。Omnibus包的好处在于所有组件版本都经过官方测试和锁定升级的时候只要换新包然后跑一遍gitlab-ctl reconfigure和gitlab-ctl upgrade数据库迁移和配置文件检查会自动完成。它把“安装GitLab”这件事从一个复杂的系统集成项目变成了“装一个软件包改一个配置文件”的标准化操作。2.2 Ubuntu/Debian系完整安装步骤在Ubuntu 24.04上安装的过程我完整梳理如下第一步安装基础依赖sudo apt-get update sudo apt-get install -y curl openssh-server ca-certificates perl第二步配置GitLab软件源。官方给出的方式是通过一个脚本自动添加cd /tmp curl -L https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash这个脚本做的事情包括添加GitLab官方的apt仓库、导入GPG公钥、确认你的系统版本。执行完以后软件源里就有了gitlab-ce包。如果你在的网络环境访问packages.gitlab.com很慢可以把源地址替换为可访问的镜像站把deb https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/这一行的域名换成对应的镜像地址。这一步影响的是下载速度不影响后续任何功能。第三步正式安装。安装时就直接指定external_urlsudo EXTERNAL_URLhttp://gitlab.example.local apt-get install gitlab-ce这一步会下载几百MB的安装包安装完成后GitLab会自动执行初始配置看到gitlab Reconfigured!就说明成功了。如果你忘记指定EXTERNAL_URL也没关系装完之后可以在/etc/gitlab/gitlab.rb里修改再执行sudo gitlab-ctl reconfigure同样生效。2.3 RHEL/CentOS系完整安装步骤CentOS Stream 9上整体流程类似但有几个细节不同。首先是依赖安装用yum/dnfsudo dnf install -y curl policycoreutils openssh-server perl然后开启SSH服务CentOS Stream默认有但确认一下不会错sudo systemctl enable sshd sudo systemctl start sshd软件源配置同样用官方脚本cd /tmp curl -L https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash接着放行防火墙端口这一步在Ubuntu上不需要但在CentOS系上不做会直接导致外部访问不了sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --reload最后安装sudo EXTERNAL_URLhttp://gitlab.example.local dnf install -y gitlab-ce2.4 两条路线的差异与软件源访问问题Debian系和RHEL系在安装逻辑上没有本质区别都是配源、装包、reconfigure三步。但有两个差异值得单独说。第一RHEL系的SELinux默认是开启的。如果SELinux状态是EnforcingGitLab需要操作的一些目录和端口特别是非默认端口可能被拦截导致服务看起来启动正常但访问时连接被拒绝。临时排查时可以先用setenforce 0确认是不是SELinux的问题如果是就配置对应的SELinux策略不要图省事永久关闭。第二软件源访问问题。GitLab官方源在国内和部分网络环境下访问速度不稳定这个在2026年依然是很多人卡住的第一关。解决思路有两个一个是前面提到的换镜像源另一个是提前把安装包下载到本地然后离线安装也就是把.deb或.rpm文件传到目标机器上用dpkg -i或rpm -ivh安装。离线安装的好处是不依赖网络环境适合内网服务器。3. Windows与macOS容器化是绕不开的解法在系统选型那节我提过GitLab官方对Windows/macOS没有原生安装包。很多从Windows接触服务器的人第一次搜到这个消息会愣一下连Windows这么主流的系统都不支持确实不支持。GitLab官方设计上就是一个跑在Unix/Linux系系统上的服务它对进程管理、socket并发、文件权限的依赖都很深移植到Windows原生环境的成本和收益完全不成正比。所以Windows和macOS上跑GitLab主流方案就两个Docker容器化或者虚拟机跑Linux。前者轻量适合开发测试后者更接近生产环境但资源占用高一层。3.1 Docker方式跑GitLab CE的完整命令与参数说明以Windows 11上装Docker Desktop为例拉取官方镜像跑一个GitLab CE容器核心命令是这样的docker run --detach \ --hostname gitlab.example.local \ --publish 8929:80 --publish 2224:22 \ --name gitlab \ --restart unless-stopped \ --volume $PWD/gitlab/config:/etc/gitlab \ --volume $PWD/gitlab/logs:/var/log/gitlab \ --volume $PWD/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest这里有几个参数需要解释清楚--hostname对应GitLab内部的external_url域名和Linux安装时那个EXTERNAL_URL是一个东西。--publish 8929:80把容器的80端口映射到宿主机8929端口。为什么不用80因为Windows上80端口经常被系统或其他程序占用映射一个高位端口省去很多冲突麻烦。访问时用http://localhost:8929。--publish 2224:22容器的22端口SSH协议映射到宿主机的2224端口。这样GitLab的SSH克隆地址端口会变成2224。--volume数据持久化映射。这三条volume是把GitLab的配置、日志、数据都存到Windows本地目录容器删除重建数据不丢。这是最容易被忽视的点很多人图省事不映射volume容器一删什么都没了。容器第一次启动会自动执行初始配置因为要初始化数据库和编译一堆资产通常会等两三分钟这个阶段看到容器状态是running但页面打不开是正常的多等一会儿再看。3.2 Docker Compose管理方式跑测试环境用上面的docker run够了但如果要在Windows/macOS上长期跑一个供团队使用的GitLab实例我建议直接用Docker Compose配置写进文件里后续改端口、加卷、升级都清晰得多。services: gitlab: image: gitlab/gitlab-ce:latest container_name: gitlab restart: unless-stopped hostname: gitlab.example.local ports: - 8929:80 - 2224:22 volumes: - ./gitlab/config:/etc/gitlab - ./gitlab/logs:/var/log/gitlab - ./gitlab/data:/var/opt/gitlab然后docker compose up -d用Compose的好处是环境定义即文件团队里任何人都能一键复现同一个GitLab环境。我自己的习惯是再配一个.env文件把端口和域名参数提取出来避免写死。3.3 macOS的Homebrew与Docker选择macOS上除了Docker Desktop还有人习惯用Homebrew装软件。我直说结论Homebrew确实有和GitLab相关的formula但那些要么是老版本要么是社区维护的第三方包不建议在2026年作为正式安装路径。macOS上最稳的还是Docker Desktop。如果你不喜欢Docker Desktop的商业许可条款也可以用colima一个基于Lima的容器运行时配合Docker CLI来跑。流程上安装colima后启动即可后续docker命令和Desktop模式基本一致但需要自己额外维护一些环境细节对新手稍微多一层成本。日常开发和单机测试Docker Desktop是省心选择。4. 装完不等于能用首次配置五连击安装完成指令跑完、看到gitlab Reconfigured!很多人就以为大功告成。实际上这个阶段GitLab只是“能启动”距离“能正常使用”还有几步关键的初始化配置。我把新装实例必做的几件事总结成五个动作按顺序做一遍基本不会漏。4.1 首次访问与root初始密码新装的GitLab近几个大版本首次访问时不会给你随机密码而是让你在页面上自己设置root管理员的初始密码。这是一次性的设置完就要记住邮箱默认是adminexample.com用户名root密码是你自己设的那一串。如果你装的是某些老教程对应的老版本可能会出现初始密码存在/etc/gitlab/initial_root_password文件里的情况。新版本已经不再自动生成这个文件了也不用再去翻。我第一次升级后发现找不到密码文件还以为是安装有问题后来才确认是版本行为变更。4.2 修改external_url和时区装的时候如果没指定域名或者后来换了域名需要修改/etc/gitlab/gitlab.rbexternal_url http://gitlab.example.local如果不打算用域名直接用IP也是常见的但前面说过后期改HTTPS会很麻烦。这里还是建议一开始就用最终域名。时区配置在同一文件下gitlab_rails[time_zone] Asia/Shanghai这两处改完都要执行sudo gitlab-ctl reconfigurereconfigure是GitLab里最常用的命令它的作用是把你对gitlab.rb的修改翻译成实际服务配置然后重启受影响的服务。修改任何配置之后都要跑一遍这个习惯一定要养成。4.3 HTTPS证书与端口调整生产环境不可能一直用HTTP。我常用的方案有两个一是用Lets Encrypt自动申请免费证书GitLab原生支持二是用内部CA签发的证书适合纯内网环境。Lets Encrypt方式需要在gitlab.rb里开启配置external_url https://gitlab.example.com letsencrypt[enable] true letsencrypt[contact_emails] [adminexample.com]然后reconfigureGitLab会自动完成证书申请和续期配置。这种方式要求你的域名能公网解析到这台机器且80端口能被Lets Encrypt验证服务访问到。内网证书方式则是自己生成证书然后把证书和私钥路径填到配置里nginx[ssl_certificate] /etc/gitlab/ssl/gitlab.example.com.crt nginx[ssl_certificate_key] /etc/gitlab/ssl/gitlab.example.com.key关于端口如果80/443被占用修改Nginx监听端口在这里nginx[listen_port] 8080 nginx[listen_https_options] ssl http2改完reconfigure即可。注意端口一变克隆地址和Webhook地址都会带上端口团队里每个人都要同步更新习惯。4.4 备份策略从第一天就要启动GitLab里存的是代码、Issue、CI/CD配置、Merge Request记录这些数据的价值不用多讲。我见过不止一个团队用了大半年GitLab从来没有做过备份直到硬盘故障才发现恢复无门。备份策略一定要在装完当天就启动。手工备份一条命令sudo gitlab-backup create新版GitLab的备份命令是gitlab-backup老版本叫gitlab-rake gitlab:backup:create。备份文件默认生成在/var/opt/gitlab/backups目录。我还建议你额外的备份三样东西/etc/gitlab/gitlab.rb配置文件丢了它备份数据也没法恢复/etc/gitlab/gitlab-secrets.json保存着GitLab的各种加密密钥这个文件丢了即使有备份也恢复不了因为加密数据解不开/var/opt/gitlab/backups目录下的备份文件本身4.5 小内存优化项如果你是在2GB内存的机器上跑GitLab装完还要做几个瘦身动作否则跑几天就会发现服务越来越慢甚至直接OOM。我常用的优化项# 限制Puma worker数量 puma[worker_processes] 2 puma[min_threads] 1 puma[max_threads] 4 # 关闭不需要的监控组件 prometheus_monitoring[enable] false # 调低PostgreSQL缓存 postgresql[shared_buffers] 256MB改了配置以后reconfigure生效。这些优化会轻微影响并发能力但换来了小内存下的稳定运行值得。等以后机器升级了再把这些配置还原回去。5. 从安装到升级的常见坑我踩过的五处雷安装过程本身不复杂真正的挑战藏在各种“意外”里。我把自己在不同系统上踩过、也帮别人排查过的几个高频问题整理出来每个都给出排查思路不是直接丢结论方便你遇到类似情况能自己顺着线索找根因。5.1 系统时间不准导致服务起不来现象安装没报错但打开页面提示证书过期或者登录请求异常。这里的根因是系统时间和真实时间偏差太大。GitLab内部大量使用TLS和Token机制时间不对会导致证书有效期校验失败、Session机制错乱。这个问题在离线安装的机器上尤其常见很多内网服务器长期不开NTP。排查方法date如果时间偏差明显先校时sudo timedatectl set-ntp true sudo systemctl restart systemd-timesyncd校完时间再访问GitLab很多莫名其妙的证书报错就消失了。5.2 80/443端口被其他Nginx占用现象reconfigure时报出nginx相关错误或者GitLab起来了但访问到的是另一个Web服务。在已经有Web服务的机器上装GitLab是最容易撞这个坑的。GitLab内置了Nginx默认监听80/443。如果系统里已经有一个Nginx在监听这些端口GitLab的Nginx自然起不来。排查方法sudo ss -tlnp | grep -E :80|:443看占用端口的进程是谁。解决方案有两种一是让GitLab换端口改/etc/gitlab/gitlab.rb里的nginx[listen_port]二是关闭系统原有的Nginx让GitLab独占80/443。我的建议是除非这台机器就是专职跑GitLab的否则优先让GitLab换端口避免影响已有的Web服务。5.3 软件源超时或GPG签名校验失败现象配置软件源时能打开网页但apt/yum更新时报超时或者安装时提示GPG key验证失败。软件源连接不稳定是2026年依然普遍存在的问题。超时可以直接换镜像源解决。GPG校验失败则通常是镜像源和官方源的key不同步解决办法是把官方GPG key重新导入一次或者改用官方源重新添加。这里有个经验很多人一遇到源的问题就怪网络急着换各种源其实很多情况下只是防火墙代理设置的问题。先把curl -I通不通测试一下再决定换哪个源。盲目的多源切换只会留下安全隐患。5.4 跨大版本升级先备份再查路线现象从老版本直接跳到最新版升级后数据库迁移失败服务起不来。GitLab官方建议的升级策略是大版本升级不要跨多个major版本直接跳。比如从16.x升到17.x没问题但从15.x直接跳到17.x就会面临数据库结构变化过大导致的迁移风险。我踩过最惨的一次是把一个测试环境的GitLab从低版本直接升到最新版升级过程中数据库迁移卡住手动介入后迁移出了错误最终只能从备份恢复。正确流程是先执行sudo gitlab-backup create备份确认当前版本和要升级的目标版本之间的路径如果需要跨多个大版本先升级到中间版本再继续下一个大版本每次升级后都要跑sudo gitlab-ctl reconfigure和sudo gitlab-ctl upgrade欲速则不达升级这种事稳就是快。5.5 备份恢复在不同系统之间迁移现象把一台机器的备份恢复到了另一台系统不同的机器恢复完成后项目能看到但仓库是空的。备份文件里保存的是GitLab的PostgreSQL数据库数据、仓库文件、上传附件等。不同系统的文件路径基本一致都是/var/opt/gitlab理论上备份恢复是跨系统可用的。但有个前提恢复前要保证GitLab的版本一致。跨大版本恢复备份会有兼容问题。另外恢复时一定要先把GitLab停掉再恢复否则数据库还在写入恢复过程会触发锁冲突sudo gitlab-ctl stop puma sudo gitlab-ctl stop sidekiq sudo gitlab-backup restore BACKUPxxxx sudo gitlab-ctl reconfigure sudo gitlab-ctl restartBACKUP后面填的是备份文件的名称在/var/opt/gitlab/backups目录里能看到不带_gitlab_backup.tar后缀。新版本恢复时会提示需要确认因为恢复操作会覆盖现有数据记得确认。6. 说两个比安装更值得养成的习惯安装只是用GitLab的第一步。我用了几年GitLab之后发现真正影响长期体验的往往是两个看起来不太起眼的运维习惯。第一个习惯是所有配置变更都以/etc/gitlab/gitlab.rb为中心不要手动去改/var/opt/gitlab下的服务配置文件。GitLab的Omnibus设计思路是“gitlab.rb是唯一入口”你手动改的任何组件配置下次reconfigure就会被覆盖。我一开始不习惯这种设计总觉得直接改Nginx配置更灵活后来发现每次升级配置就被重置才明白规范化的好处。配置文件里我习惯给每个修改项写上注释注明修改日期和原因一个月以后回头查改动记录会非常省心。第二个习惯是学会看日志而不是遇到问题就重启。GitLab的日志查看命令是sudo gitlab-ctl tail nginx sudo gitlab-ctl tail puma sudo gitlab-ctl tail postgresql sudo gitlab-ctl tail sidekiqgitlab-ctl tail可以只查看单个服务的日志对定位问题是决定性的帮助。很多人遇到故障的第一反应是gitlab-ctl restart全套服务重启这样不仅浪费时间还可能把关键错误信息冲掉。正确的做法是先翻对应服务的日志找到第一处报错再决定怎么处理。最后想说的一点是GitLab这套系统虽然组件多、依赖重但它的运维模型其实非常规范。只要把规划域名、硬件、系统想清楚安装Omnibus包走标准路径初始化配置、HTTPS、备份做完整后续的使用和维护都很顺。这比我早年折腾源码安装时的体验不知道好了多少。如果你正准备部署记住我在文章里反复强调的那句话装之前的规划比装本身重要得多。