早些年我帮团队搭代码托管平台最先想到的往往是部署一套GitLab。这东西用起来顺手社区版功能也够用但第一次真去装的时候还是绕了不少弯子。网上教程要么太老要么跳步严重照着做很容易卡在某一步。后来给不同的服务器环境陆陆续续装过十几次从 CentOS、Ubuntu 到 Docker 离线包都折腾过该踩的坑基本都踩遍了。这篇就把 GitLab 从零安装到日常维护的完整过程摊开来讲重点说透每步背后的原因附带排错经验希望能帮你一次装成功少走几趟弯路。1. 装GitLab前先把部署思路和硬件底子摸清很多教程一上来就贴命令导致不少人在安装前就埋了坑。比如装到一半发现内存不够、端口冲突或者部署方式选错了后面升级维护都受影响。所以在动手前我建议先把下面几个问题想明白。1.1 GitLab是什么为什么用自行部署而不是直接用线上平台GitLab 是一个基于 Git 的代码托管与 DevOps 平台除了托管仓库它还集成了 Issue 管理、代码评审、CI/CD、容器镜像仓库等功能。和 GitHub/Gitee 这类公共平台相比自建的 GitLab 最大的优势有几个代码完全存放在内网服务器对代码保密性要求高的团队更放心。不受公共平台的仓库数量、成员人数限制社区版完全免费。可与内网已有的 LDAP、Jenkins、K8s 等系统深度集成。离线网络环境也能正常使用这对一些隔离网络里的项目团队特别重要。如果你只是个人用或者不想折腾服务器和日常维护直接用线上平台当然省心。但如果是团队内部要做代码资产沉淀或者有严格的代码安全合规要求那自己部署一套 GitLab 就是很常见的选择。1.2 版本选择CE社区版与EE企业版怎么选部署方式哪个合适GitLab 官方分两个大版本CECommunity Edition社区版和 EEEnterprise Edition企业版。对于绝大多数团队来说CE 的功能已经非常丰富代码托管、Merge Request、CI/CD、Wiki、Issue 这些核心功能都不缺而且是完全免费的。EE 增加的主要是面向大型企业的功能比如多集群管理、审计事件、效能分析等这些通常要掏授权费。建议在没有明确企业版需求的情况下直接选 CE。部署方式上目前主流是三种官方 Omnibus 包安装也就是用 yum/apt 直接装 RPM/DEB 包。它把 GitLab 依赖的 Nginx、PostgreSQL、Redis 等组件全部打包好安装简单不易出现依赖冲突适合没有特殊定制需求的场景也是我最推荐的方式。Docker 容器部署。适合喜欢容器化、要快速迁移或已经在全容器环境里的团队。镜像官方维护一条 docker run 就能起一个实例升级回滚都方便但数据卷、网络、备份策略需要自己好好规划。源码编译安装。适合二次开发或者有特殊定制需求的极少数场景基本不推荐普通人去折腾耗时长维护成本高。从我的实际经验来看如果你是第一次部署建议直接用 Omnibus 包方式最稳。Docker 方式适合已经对 GitLab 有一定了解、且熟悉容器操作的工程师。1.3 硬件和系统要求别让 GitLab 跑在鸡肋配置上GitLab 是出了名的吃内存大户。它一启动就会拉起 PostgreSQL、Redis、Sidekiq、Nginx、Prometheus 等一系列组件内存小了真的会卡到怀疑人生。官方文档推荐的配置是约 4GB 内存 4 核 CPU可以顺畅支撑 500 人以下的团队日常使用。2GB 内存是能装但跑起来很勉强经常出现 502 或页面加载超时个人学习测试可以生产环境不建议。磁盘建议 SSD预留至少 20GB 以上的可用空间。仓库多、镜像多的团队建议单独挂一块数据盘给 Git 仓库目录。操作系统方面CentOS 7/8、Rocky Linux、Ubuntu 18.04/20.04/22.04 这些都是 GitLab 官方长期支持的平台优先选择 LTS 版本。内核太老或者系统太非主流的版本容易出现莫名奇妙的兼容问题。注意安装之前用free -h看一眼内存再用df -h看一下磁盘余量。如果条件不够先加配置或者优化方案别硬装。2. 环境准备系统基础配置、端口规划与域名解析这部分虽然看起来琐碎但准备工作做得好不好直接决定后面安装顺不顺利。很多安装失败都是卡在端口冲突、防火墙拦截、主机名不对这些细节上。2.1 系统初始化与 SSH 基础配置如果是新服务器先做几个基本操作。更新系统源和软件包避免部分组件版本过旧带来兼容问题。然后确认 SSH 服务已经开启因为 Git 仓库的 SSH 协议就是通过服务器的 SSH 服务来提供支持的如果 SSH 没装好后续通过 SSH 方式 clone 代码会很麻烦。# CentOS / Rocky yum update -y # Ubuntu / Debian apt update apt upgrade -y # 检查并启动 sshd 服务 systemctl status sshd systemctl enable --now sshd很多人在安装后遇到无法通过 SSH 克隆代码排查一圈才发现是服务器默认没开启 SSH 服务或者防火墙把 22 端口挡住了。这个前置检查一分钟就能做完省得后面头疼。另外建议给服务器设置合适的主机名。虽然可以通过 IP 访问但后面配置 HTTPS 证书、CI 域名绑定、内网 DNS 解析时一个规范的主机名能省很多事情。hostnamectl set-hostname gitlab.example.com2.2 防火墙与端口规划80、443、22 一个都不能少GitLab 默认会用 80 端口HTTP、443 端口HTTPS和 22 端口SSH。如果这台服务器上还跑着其他服务比如 Nginx、Tomcat、Jenkins那端口冲突几乎是必然的。所以安装前把端口占用情况摸清楚。# 查看端口占用 ss -lntp | grep -E :(80|443|22)\s如果发现端口被占用有两个处理思路停掉占用这些端口的服务让给 GitLab。改 GitLab 的端口配置比如让 Nginx 监听 8080SSH 用 2222。这个后续在 gitlab.rb 里调。另外防火墙要提前放行这些端口。CentOS 上默认开启了 firewalld 的话操作如下firewall-cmd --permanent --add-port80/tcp firewall-cmd --permanent --add-port443/tcp firewall-cmd --permanent --add-servicessh firewall-cmd --reload如果是云服务器阿里云、腾讯云、华为云等还要记得在安全组里同步放行对应端口光在服务器内部放防火墙没用云平台的安全组是另一层过滤。2.3 域名解析与服务器时间同步GitLab 对外访问的地址默认是http://服务器IP但生产环境建议使用独立域名比如gitlab.company.com。提前把域名解析到服务器 IP 上避免装完之后 external_url 里的域名没法访问。还有一个小细节容易被忽略服务器时间不同步会导致 Git 提交时间显示异常、HTTPS 证书校验失败等问题。用 NTP 做一次时间同步避免这些坑。# CentOS / Rocky yum install -y chrony systemctl enable --now chronyd # Ubuntu / Debian apt install -y chrony systemctl enable --now chrony时间同步这个事没出问题的时候看不出价值一旦出现证书报错或者提交记录时间错乱排查成本远高于这个准备工作。3. CentOS/Rocky 传统方式安装 GitLab 完整流程环境准备做好后就可以正式安装了。这一节以 CentOS/Rocky 系为例使用 Omnibus 包方式这也是我最推荐的生产环境安装方式。3.1 配置 yum 源并安装依赖GitLab 官方提供了独立的 yum 源配置方式很简单。国外服务器直接使用官方源即可国内服务器建议替换为清华或中科大的镜像源速度会明显更快也更稳定。# 官方源国外服务器 curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | bash # 国内镜像源清华 cat /etc/yum.repos.d/gitlab-ce.repo EOF [gitlab-ce] nameGitlab CE Repository baseurlhttps://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/yum/el$releasever/ gpgcheck0 enabled1 EOF yum makecache这个阶段如果报 GPG 密钥错误可以在 repo 文件里把 gpgcheck 设为 0或者导入官方 GPG key。国内服务器用清华源时通常直接设 0 就行又不影响安装安全性。3.2 执行安装命令并配置 external_urlGitLab 安装命令很直接难得的是在执行前要先把 external_url 想清楚。这个参数会写入 GitLab 的 nginx 配置、网页中的 clone 地址、CI 环境变量等很多地方如果装完再去改虽然也能改但容易遗漏引起后续使用混乱。这里有我踩过的一个很典型的坑第一次安装时我没设置 external_url直接用默认的http://gitlab.example.com装完结果登录进去页面上的项目 clone 地址显示的是http://gitlab.example.com/xxx.git在内网根本没法用。后来重装才解决。所以建议大家安装前就把 external_url 设置为最终要使用的地址比如准备用 IP 访问就设置 IP准备用域名访问就先解析好域名再设置域名。# 直接设置外部访问地址并安装这一步会自动下载、依赖安装和配置 yum install -y gitlab-ce # 或者用环境变量方式一步到位 EXTERNAL_URLhttp://192.168.1.100 yum install -y gitlab-ce如果是先安装再配置可以在安装完成后修改 /etc/gitlab/gitlab.rb 文件中的这一行external_url http://192.168.1.100然后重新配置并启动gitlab-ctl reconfigure gitlab-ctl start3.3 首次访问、管理员密码设置与中文界面首次访问http://服务器IP页面会强制让你设置 root 用户的初始密码。设置完成后就可以用 root 账号登录系统。这里有个细节使用 Omnibus 方式安装时系统里会同时创建一个gitlab-ctl命令很多后续管理操作都需要通过它来执行比如gitlab-ctl status、gitlab-ctl restart、gitlab-ctl tail等这些命令在后面的运维中会经常用到。如果希望界面显示中文可以在用户头像下拉菜单中依次进入 Preferences → Localization把 Language 切换为 Chinese保存后刷新页面即生效。这个操作是用户级的每个账号要单独设置但胜在不用改服务器配置简单安全。4. 用 Docker 部署 GitLab迁移简单、升级省心如果你所在团队的基础设施已经容器化或者你希望在一台机器上快速部署一套 GitLab 来验证方案Docker 方式也非常推荐。官方在 Docker Hub 提供了持续维护的gitlab/gitlab-ce镜像版本更新及时用起来省心。4.1 为什么选 Docker 部署适合什么场景Docker 部署最大的优势是环境隔离和可移植性。你不需要关心宿主机上装的是 CentOS 还是 Ubuntu只要 Docker 能跑GitLab 的行为基本一致。版本升级时只需要拉取新镜像重新启动容器比传统包方式要容易回滚。另外如果想在一台机器上起多套 GitLab 做测试Docker 方式也方便得多。当然Docker 方式也有前提你至少要熟悉 Docker 的基本操作理解端口映射、数据卷挂载这些概念。否则出了问题排查难度比传统方式要高一些。4.2 Docker run 一条命令起一个 GitLab 实例先准备好一个宿主机目录比如/srv/gitlab把配置、数据、日志三个目录都挂载出来这样容器即使删了重建数据也不丢。docker run --detach \ --hostname gitlab.example.com \ --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 \ gitlab/gitlab-ce:latest这里几个关键参数的意图--hostname设置容器内部看到的服务器主机名GitLab 会根据这个值生成 external_url所以尽量设置为最终要用的域名。--publish 80:80把容器内 80 端口映射到宿主机 80对外提供 HTTP 服务。--publish 22:22把容器内 SSH 端口映射到宿主机 22否则无法通过 SSH 协议拉取代码。--volume挂载三个数据目录这是数据持久化的关键没有挂载目录的容器一旦删除所有仓库数据全丢这个教训希望你别亲身体会。启动后容器日志会提示配置阶段耗时通常要等两三分钟看到日志中出现了gitlab Reconfigured!之类的信息再访问页面。4.3 docker-compose 更省心推荐用于生产环境虽然 docker run 简单直接但生产环境我更推荐用 docker-compose 把配置固化下来方便团队评审、版本管理和后续其他人接手维护。下面是一个可用的 compose 文件模板version: 3.8 services: gitlab: image: gitlab/gitlab-ce:latest container_name: gitlab restart: always hostname: gitlab.example.com environment: GITLAB_OMNIBUS_CONFIG: | external_url http://gitlab.example.com gitlab_rails[gitlab_shell_ssh_port] 22 ports: - 80:80 - 22:22 volumes: - /srv/gitlab/config:/etc/gitlab - /srv/gitlab/logs:/var/log/gitlab - /srv/gitlab/data:/var/opt/gitlab shm_size: 256mGITLAB_OMNIBUS_CONFIG环境变量可以直接向容器内的 gitlab.rb 注入配置相当于传统方式里手动编辑 /etc/gitlab/gitlab.rb 的效果。shm_size是给容器加大共享内存GitLab 在跑 CI 或执行 Git 操作时会使用共享内存太小可能导致一些偶发异常。启动命令docker-compose up -d docker-compose logs -f gitlab后续要升级只需要先docker-compose pull再docker-compose up -d容器会基于新镜像重建数据卷里的数据都还在非常方便。5. 核心配置域名、clone 地址、SSH、备份与 Jenkins 联动安装完成只是第一步日常真正用得多的其实是这些后续配置。这一节集中整理几个高频核心操作每个都是实际工作中必用的。5.1 external_url 改错了怎么处理HTTP clone 地址变成机器 ID 怎么办有次运维同事反馈GitLab 页面上显示的项目 clone 地址是http://gitlab-102-34-56-78/root/demo.git这种带机器 ID的格式不是我们预期的http://gitlab.company.com/root/demo.git。这个问题的根因就是安装时 external_url 没设置对。解决办法是修改 /etc/gitlab/gitlab.rb 中的 external_url设置为完整的域名或 IP然后执行gitlab-ctl reconfigure。改完后记得清理一下浏览器缓存再刷新页面clone 地址就会跟着变。如果在 Docker 方式下遇到同样问题处理方式是通过环境变量或直接改容器内的配置文件再重启保持容器内外地址一致即可。5.2 SSH 密钥配置与 HTTPS 切换很多团队要求成员用 SSH 方式 clone 代码避免每次都要输密码。具体流程不复杂在本地电脑生成 SSH 密钥对ssh-keygen -t ed25519 -C your_emailexample.com。查看公钥内容并复制cat ~/.ssh/id_ed25519.pub。登录 GitLab进入 Preferences → SSH Keys把公钥粘贴进去。配置成功后就可以用gitgitlab.example.com:group/project.git这样的地址 clone 了。注意这里的git后面不是 IP 也不是普通用户名而是 GitLab 固定的 SSH 登录名很多新手容易搞混。如果是通过 HTTPS 方式每次 push 需要输入账号密码。不想频繁输密码的话可以在 clone 时用带凭证的地址或者在本地配置凭证存储工具。5.3 备份与恢复代码数据是无价的GitLab 自带了一套备份机制用起来不复杂关键是要养成定期备份的习惯。Omnibus 方式下执行gitlab-backup create备份文件生成在/var/opt/gitlab/backups目录下默认保留 7 天内备份可通过 gitlab.rb 中的backup_keep_time调整保留时长。恢复时先停掉与数据库相关的服务再执行# 停止数据库写入相关的服务 gitlab-ctl stop puma gitlab-ctl stop sidekiq # 恢复指定备份文件注意文件名不带 _gitlab_backup.tar 后缀 gitlab-backup restore BACKUP1700000000_2023_11_15_16.1.0恢复完成后启动服务gitlab-ctl start如果是 Docker 方式备份和恢复命令是在容器内执行的所以要先docker exec -it gitlab gitlab-backup create。另外一个很容易被忽略的重点GitLab 的备份默认只备份数据库和 Git 仓库不包含/etc/gitlab/gitlab.rb这样的配置文件。所以备份策略里应该把 gitlab.rb、证书、SSH 主机密钥这些关键文件一并备份才能真正做到数据不丢。5.4 GitLab 与 Jenkins 连接配置好多团队用 Jenkins 做持续集成GitLab 作为代码源两者联动很常见。当你在 Jenkins 里配 GitLab connection 时提示login failed. check api token or gitlab version通常是因为 API Token 无效或者 GitLab 版本与插件版本不兼容。正确的操作流程是在 GitLab 中创建一个访问令牌进入 User Settings → Access Tokens勾选api权限生成 token。在 Jenkins 的 Manage Jenkins → Configure System → GitLab 配置区域填上 GitLab 的 URL比如http://gitlab.example.com和刚才生成的 token。测试连接提示 Success 后保存。如果提示 login failed先检查 token 是否过期、是否有 api 权限再检查 GitLab 版本是不是太老。有些老版本 GitLab 对 API 的某些接口支持不完整导致 Jenkins 插件无法正常调用这种情况通常只能升级 GitLab 或者调整 Jenkins 插件版本。6. 日常维护和故障排查内存、端口、版本漏洞与隐蔽的坑装好只是开始后续维护才是考验人的地方。这里把我在实际操作中经常遇到的问题列出来附上排查思路和解决办法。6.1 内存不足GitLab 频繁 502 怎么办最有代表性的问题是访问 GitLab 页面时经常出现 502或者服务器负载很高。用free -h一看Swap 都吃满了明显是内存不够。如果是小团队使用但机器内存只有 2GB可以尝试关掉 GitLab 自带的 Prometheus 监控模块# 编辑 /etc/gitlab/gitlab.rb prometheus_monitoring[enable] false这能省出不少内存。再配置一下 swap 空间作为兜底临时救急够了。但本质上生产环境还是建议内存加到 4GB 以上否则 GitLab 用起来会比较难受。6.2 端口冲突改了端口后 clone 地址怎么办如果 80 端口被其他服务占用可以在 gitlab.rb 里改 Nginx 监听端口nginx[listen_port] 8080改完后 reconfigure访问地址就变成http://服务器IP:8080。同样如果 22 端口被系统 SSH 占用可以把 GitLab SSH 端口改到 2222gitlab_rails[gitlab_shell_ssh_port] 2222这里有一个容易忽略的点GitLab 页面上的 SSH clone 地址需要手动带上端口号形式类似ssh://gitgitlab.example.com:2222/group/project.git。如果你改了端口但页面上 clone 地址没显示端口那多半是gitlab_shell_ssh_port没配对检查一下就好。6.3 高危漏洞修复GitLab 升级不要拖GitLab 历史上出过几个比较严重的安全漏洞包括未授权远程命令执行、账户接管等。这类漏洞一旦被利用影响面很大而修复方式基本都是升级到官方发布的安全版本。升级的过程其实不复杂Omnibus 方式下直接执行yum update gitlab-ce gitlab-ctl reconfigure gitlab-ctl restartDocker 方式则拉取新镜像重建容器。不过升级前一定先做备份大版本升级前最好查阅官方升级路径文档避免跨版本太远导致数据库迁移失败。6.4 其他人容易忽略的隐藏坑最后分享几个我吃过大亏的小细节/etc/gitlab/gitlab.rb里的配置改完必须执行gitlab-ctl reconfigure否则不生效这个很多人知道但经常忘了 restart 服务。修改 MSYS2 或 Windows 上的 SSH 配置时注意 OpenSSH 的版本兼容问题。使用国内服务器的话安装和拉取镜像时速度很慢记得配好 yum/apt 镜像源或者 Docker 镜像加速器。GitLab 的日志文件有时候能膨胀到好几个 G建议配置 logrotate 或定期手动清理/var/log/gitlab目录。页面操作删除项目时默认只是软删除后台还会保留一定时间。如果你真要彻底清理空间需要管理员在后台执行清理任务。这些细节单独拿出来都不是大事但在实际运维中会反复遇到积累下来能省很多事。我在实际安装配置以及后续维护 GitLab 的过程中最大的体会是不要迷信一条命令装好的路数关键是要理解每个配置项背后的意义尤其是 external_url、数据持久化、备份恢复机制这三块它们直接决定了你的 GitLab 好不好用、数据安不安全。每次升级之前做好备份每次调整配置前先想清楚影响面这套工具就能安安稳稳地陪团队走很久。希望这篇总结能帮你顺利装好 GitLab少踩一点我当年踩过的坑。