先说结论GitLab 绝对不只是“内网版 GitHub”那么简单。它是一套覆盖代码托管、分支合并、Issue 管理、CI/CD 流水线、容器镜像仓库的完整研发协作平台。这篇文章我不打算只甩给你一串命令而是想把我从零开始在 Linux 上装 GitLab 的全过程、决策逻辑、踩过的坑全部摊开来讲。文章会从版本选型、环境规划开始接着给出社区版最稳妥的安装路径再补充配置、汉化、SSH、常见故障排查最后聊聊从“装完”到“用好”之间那些容易被忽略的事。无论你是刚接触 Linux 的开发者还是要给团队搭内网仓库的运维这篇教程的方法都是实测可用的而且我会尽量把每一步的“为什么”也讲清楚。1. 动手之前先把版本、方式和需求想清楚1.1 GitLab 到底解决了什么问题很多人第一次接触 GitLab是因为公司不让把代码放到 GitHub 或 Gitee 上。这个场景很典型代码属于公司资产外部平台存在合规风险于是团队想在内部服务器上搞一个私有代码仓库。这时候 GitLab 几乎是默认答案它天然就是为“自托管 Git 仓库”设计的。但它解决的问题远不止“私有托管”。GitLab 自带一套完整的研发工作流Merge Request 可以把代码审查做成强制流程Issue Board 可以当简易项目管理用内置的 CI/CD 可以直接跑流水线代码推上去自动构建、测试、部署它还能同时充当 Docker 镜像仓库和依赖包仓库。换句话说你团队如果规模不大GitLab 一台机器就能把 GitHub、Jenkins、Nexus、Jira 的部分功能全部干掉。我自己的体会是很多小团队最开始只是想把代码集中管理起来结果用着用着就依赖上它了。所以安装的时候我建议你多留点资源别按“只是存个代码”的标准来配后面跑 CI 的时候你会感谢当初的自己。1.2 选社区版还是企业版GitLab 分两个版本线社区版CECommunity Edition和企业版EEEnterprise Edition。官网下载页默认引导你装 EE但 EE 的很多高级功能需要 License 才能解锁。如果你没有购买官方订阅装完 EE 后实际可用的核心功能和 CE 基本一样但社区版在资源占用上通常更轻而且不用担心授权边界问题所以个人使用、内部团队使用、甚至大多数中小企业场景选 CE 就够了。从功能上看CE 已经包含了持续集成、代码审查、Wiki、Container Registry 等核心能力。EE 的额外价值主要体现在更细粒度的权限控制、审计日志、多集群管理、合规性功能这些企业级需求上。我们团队 20 人左右用 CE 跑了一年多 CI/CD日常需求全部覆盖。安装方式上包管理器Omnibus安装的 CE 和 EE 其实用的是同一个安装框架区别只是仓库源不同。你在 GitLab 官网选择系统版本后页面默认给的命令是安装 EE 的需要手动把 gitlab-ee 改成 gitlab-ce。国内很多教程直接让你用清华源或中科大源安装 CE目的就是避开官方源在国内的慢速问题。1.3 三种安装方式怎么选GitLab 官方推荐的是 Omnibus 包安装也就是直接通过系统的包管理器yum/apt安装一个打包好的安装包。这个包里已经内置了 Nginx、PostgreSQL、Redis、Puma 等几乎所有组件装完就是一套可以用的系统维护起来也最省心。官方还提供了专门的仓库源升级时直接 yum update 或者 apt upgrade 就能一键升级。对绝大多数场景来说这就是最合适的方式。第二种是 Docker 方式镜像名为 gitlab/gitlab-ce。它的好处是起一个容器就完事不会污染宿主机环境备份就是打包整个目录迁移也方便。坏处是数据卷、网络模式、健康检查这些概念对新手不太友好而且容器本身会多一层资源开销。如果你宿主机上已经跑了 Docker 环境或者只是想快速起一个测试实例Docker 方式也挺好。第三种是源码编译从 GitHub 拉源码从头编译安装。这种方式我建议直接放弃。GitLab 组件非常多源码安装的坑多到能写一本书升级更是噩梦。除非你是在做二次开发比如想改 GitLab 源码本身否则千万不要在生产环境用源码方式部署。我的选择建议很简单新手上路直接用 Omnibus 包已经在用 Docker 或者资源隔离要求高选择 Docker 方式源码方式想都不用想。2. 安装前的环境准备这一步偷懒后面全是坑2.1 硬件和系统要求先说说硬件这是整个安装过程中最容易埋雷的环节。GitLab 是一个“麻雀虽小五脏俱全”的怪物它自带数据库、缓存、Web 服务器、后台任务队列每个组件都要吃内存。官方文档给出的最低配置是 4GB 内存但我要说实话4GB 只能保证它“能跑起来”一旦几个开发者同时操作或者 CI Runner 开始构建任务内存马上见顶然后你就会看到传说中的 502 页面。我自己的实测经验按使用规模大致可以这么规划使用规模建议内存建议CPU建议磁盘个人测试 / 2-3人小团队4GB建议加2GB swap2核50GB SSD5-20人团队日常使用8GB4核100GB SSD持续跑CI/CD,几十人团队16GB以上8核200GB SSD以上磁盘一定要用 SSDGitLab 大量小文件读写Git 对象、缓存、日志机械硬盘会明显拖慢克隆和页面加载速度。系统方面官方支持 CentOS 7/8、Rocky Linux、Ubuntu 20.04/22.04、Debian 10/11 等。我这边主要用 Rocky Linux 9 和 Ubuntu 22.04下面命令我会两个系统都覆盖到。2.2 系统基础组件与时间同步不管哪个系统安装前先把基础组件准备好。在 CentOS/Rocky 上需要安装依赖Ubuntu 上也需要安装对应包。这些依赖里最关键的是 openssh-serverSSH 协议是 Git 操作的基础和 postfix用于发通知邮件如果你不想本地发邮件也可以不装后面在配置文件里关掉邮件服务。# CentOS / Rocky Linux sudo yum install -y curl policycoreutils openssh-server openssh-clients postfix # Ubuntu / Debian sudo apt update sudo apt install -y curl openssh-server ca-certificates postfix装完 postfix 后记得启动服务sudo systemctl enable postfix sudo systemctl start postfix如果你不想用本地 postfix 发信而是计划用公司的 SMTP 服务器那这个包可以不装后面在 gitlab.rb 里配置 SMTP 信息即可。另外强烈建议安装前先确认系统时间是否准确。GitLab 的很多操作和日志记录跟时间戳强相关如果系统时间和实际时间差太多你后面排查问题时看日志会看得怀疑人生。用 chrony 或 systemd-timesyncd 同步一下时间# CentOS / Rocky sudo yum install -y chrony sudo systemctl enable --now chronyd # Ubuntu sudo timedatectl set-ntp true2.3 域名、端口和防火墙规划这一步我在第一次装的时候完全没想清楚导致后面折腾了很久。GitLab 安装时要求你指定一个 external_url也就是你访问 GitLab 的地址这个地址一旦写进配置后面修改会牵扯到 Nginx 配置、重定向逻辑、以及所有已创建项目的克隆地址非常麻烦。所以安装前先想清楚你打算用 IP 访问还是域名访问如果只是内网测试直接用 http://你的IP 就行如果打算正式使用建议给它一个域名比如 gitlab.example.com然后在 DNS 或本地 hosts 里解析到服务器 IP。域名看起来比 IP 清爽而且以后迁移服务器不用改客户端配置。端口方面GitLab 默认需要占用 80 端口HTTP和 443HTTPS。如果你的服务器上已经跑了 Nginx、Apache 或者别的 Web 服务端口冲突是最常见的问题之一。我遇到过一次因为同机部署了别的应用占用了 80 端口GitLab Nginx 起不来页面直接打不开。如果这种情况你可以把 GitLab 的 Nginx 端口改成一个自定义端口比如 8080 或者 8929后面我会讲具体配置。防火墙也要提前处理# CentOS / Rocky 使用 firewalld sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --permanent --add-port22/tcp sudo firewall-cmd --reload # Ubuntu 使用 ufw sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 22/tcp sudo ufw reload2.4 SSH 密钥准备SSH 是 Git 传输代码最常用的协议也是我第一次用时最不熟悉的地方。它的原理很简单你本地生成一对密钥公钥私钥把公钥放到 GitLab 服务器上之后本地访问 GitLab 时服务器用公钥验证你的私钥验证通过就允许操作全程不用输密码。生成密钥的命令如下ssh-keygen -t ed25519 -C your_emailexample.com一路回车就行默认会生成在 ~/.ssh/ 目录下公钥是 ~/.ssh/id_ed25519.pub。如果你不想每次操作都输密语可以留空。生成后把公钥内容复制出来后面要粘贴到 GitLab 网页端的设置里。注意如果你用的还是 RSA 类型的老密钥问题不大。但 GitLab 新版已经推荐 Ed25519 类型强度更高、性能更好命令里直接写 -t ed25519 即可。3. 完整安装实操Omnibus 包方式3.1 配置系统源并安装依赖以 CentOS/Rocky 为例官方源在国内下载速度不稳定我建议直接用国内镜像源清华和阿里都行。下面以清华源为例先把 GitLab CE 的 yum 源配好curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash这一步会往 /etc/yum.repos.d/ 下写入 gitlab_gitlab-ce.repo 文件。如果官方源脚本执行太慢你可以直接手动创建仓库文件内容指向清华镜像[gitlab-ce] nameGitlab CE Repository baseurlhttps://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/yum/el$releasever/ gpgcheck0 enabled1Ubuntu 系统同理可以配置清华源curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash # 或者手动配置 /etc/apt/sources.list.d/gitlab_gitlab-ce.list deb https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu focal main3.2 执行安装命令仓库源配好后安装就一条命令的事。关键参数是 EXTERNAL_URL它决定 GitLab 的访问地址。这里我强烈建议你在这一步就把域名或 IP 想好后面就不用折腾了# CentOS / Rocky sudo EXTERNAL_URLhttp://192.168.1.100 yum install -y gitlab-ce # Ubuntu sudo EXTERNAL_URLhttp://192.168.1.100 apt install gitlab-ce如果你是在内网测试直接用 IP 就行比如 http://192.168.1.100。如果以后要用 HTTPS也可以把地址写成 https://gitlab.example.com但 HTTPS 需要证书初装阶段建议先用 HTTP 跑通全流程等熟悉了再换 HTTPS。安装过程会拉下一个几百 MB 的包然后自动执行 reconfigure 初始化所有组件包括 PostgreSQL、Redis、Nginx、GitLab Workhorse 等。整个过程可能需要 3 到 10 分钟取决于服务器性能。看到输出里出现 “gitlab Reconfigured!” 字样就说明装好了。装完之后浏览器访问 http://你的服务器IP如果能跳转到设置密码的页面恭喜你GitLab 已经跑起来了。如果出现 502 或者连接超时别慌我后面第五部分专门列了排查清单。3.3 核心配置文件 /etc/gitlab/gitlab.rb 调整GitLab 安装完成后主要配置都集中在 /etc/gitlab/gitlab.rb 文件里。这个文件默认几乎全是注释你需要按需打开并修改。改完以后执行 sudo gitlab-ctl reconfigure 让配置生效。几个我实际用下来必须关注的配置项第一是 external_url。如果安装时忘了指定或想换个地址可以在这里改external_url http://192.168.1.100第二是时区。GitLab 默认时区是 UTC你会发现记录的时间比北京时间慢 8 小时看日志特别难受。改成上海时区gitlab_rails[time_zone] Asia/Shanghai第三是邮件通知。默认用本地 postfix 发信但很多服务器没法真正投递邮件最好配置你自己的 SMTP 服务gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.qq.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] your_emailqq.com gitlab_rails[smtp_password] authorization_code gitlab_rails[smtp_domain] qq.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_tls] true第四是端口冲突处理。如果 80 端口被占用把 Nginx 监听端口改掉nginx[listen_port] 8080然后 external_url 也要带上端口external_url http://192.168.1.100:8080。改完配置后执行sudo gitlab-ctl reconfigure sudo gitlab-ctl restart3.4 初始账号和密码我第一次安装完在登录页面试了 admin/admin 等各种组合都失败后来才知道 GitLab 的初始 root 密码是随机生成的。安装过程中 GitLab 会自动生成一个临时密码文件路径是 /etc/gitlab/initial_root_password。你可以用 cat 查看这个文件sudo cat /etc/gitlab/initial_root_password里面 Password 一行就是 root 用户的初始密码。拿着这个密码用用户名 root 登录然后第一时间去修改成自己的强密码。注意这个文件会在 24 小时后被系统自动删除GitLab 这么做是强制你尽快改密码。如果你过了很久才发现没保存密码那就走 5.4 小节的重置流程用命令行强制重置 root 密码。3.5 用 Docker 方式安装备选路径如果你的宿主机已经装了 Docker想快速起一个 GitLab下面是我常用的命令。考虑到数据安全我把配置、数据、日志目录都挂载到宿主机sudo docker run --detach \ --hostname gitlab.example.com \ --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 \ gitlab/gitlab-ce:latest第一次启动因为要初始化数据库和所有组件可能会比较慢可以看日志sudo docker logs -f gitlab看到 “gitlab Reconfigured!” 就说明容器初始化完成。这种方式的好处是升级方便换新版本镜像重新 run 一个容器就行备份就是把 /srv/gitlab 整个目录打压缩包。但要注意容器方式的 GitLab 对数据卷权限比较敏感我踩过 SELinux 拉不起来容器的坑如果你在 CentOS/Rocky 上跑 Docker 碰到 Permission denied可以尝试加上 --privileged 或者临时关闭 SELinux 验证一下。4. 安装后的关键配置SSH、仓库权限和常用设置4.1 SSH 密钥配置与连通测试GitLab 装好之后第一步就是把你的 SSH 公钥配置上去。登录 GitLab点击右上角头像选择 Preferences左侧菜单找到 SSH Keys把之前生成的 ~/.ssh/id_ed25519.pub 内容粘贴进去再起个标题方便识别。配置好之后先用一条命令验证联通性。注意这里的 git 不是真实用户是 GitLab 内置的 SSH 用户ssh -T git192.168.1.100如果正常你会看到类似这样的输出Welcome to GitLab, yourname!看到说明公钥已经生效以后 clone、push 都不用输密码。如果卡在密码输入或者报 Permission denied, 大概率是公钥没配对或者防火墙没放行 22 端口。关于 HTTPS 还是 SSH 的选择我的建议是命令行操作用 SSH 最顺手因为不用每次都在 URL 里带用户名密码。如果你在公司网络里 22 端口被墙那就用 HTTP 方式GitLab 也支持在 HTTP 请求里带 Personal Access Token 实现免密。4.2 创建第一个项目和仓库有了第一把钥匙就可以试水创建项目了。点击首页的 New project选 Create blank project填项目名和可见等级。可见等级权限从低到高是 Private、Internal、PublicGitLab 默认是 Private也就是只有被授权的成员才能看到这个设置对内网代码安全非常重要。项目创建好以后GitLab 会给你一段代码把本地已有代码推上去cd existing_folder git init --initial-branchmain git remote add origin git192.168.1.100:yourname/yourproject.git git add . git commit -m Initial commit git push -u origin main如果你想把 GitHub 上的仓库迁移过来GitLab 也支持 import在创建项目时选择 Import project然后选 GitHub 或 Gitee授权后可以直接拉取仓库包括分支、标签、Issue 历史都会带过来这个功能我们团队迁移时实测很好用。4.3 用户、群组与权限模型如果是团队共同使用我不建议所有人共用一个 root 账号正确做法是给每个成员创建独立账号。创建用户入口Admin Area - Users - New user。正式使用时可以开启邮箱验证让用户自己设置密码。权限管理上GitLab 里有“群组”这个层级你可以按部门或项目组建 Group然后把多个项目放进同一个群组里统一管理。角色从低到高依次是 Guest、Reporter、Developer、Maintainer、Owner。我的建议是日常开发给 Developer合并请求管理者给 Maintainer只有少数管理员持有 Owner。特别是主分支建议在项目的 Settings - Repository - Protected branches 里把 main 分支保护起来只有 Maintainer 能直接 push其他人都必须走 Merge Request 流程。这一步对代码质量的作用非常大我还见过一个团队没开保护分支有人直接往主分支强推把历史覆盖了来回折腾好久才恢复。4.4 时区、头像、邮箱通知等杂项先说一下头像问题。GitLab 默认集成 Gravatar但国内网络环境经常加载不出头像页面一直转圈很影响体验。可以在 Admin Area - Appearance 或者 gitlab.rb 里禁用 Gravatargitlab_rails[gravatar_enabled] false执行 sudo gitlab-ctl reconfigure 生效。禁用后默认显示字母头像干净利落。邮件通知我们前面在 gitlab.rb 里配了 SMTP改完以后最好实际发一封测试邮件验证。在 GitLab 网页端进入 Admin Area - Settings - 左侧 network 或个人设置里有发送测试邮件入口。如果邮件发不出去排查看 SMTP 配置、端口、授权码是否正确QQ邮箱和网易邮箱都要求用授权码而不是登录密码。关于中文界面GitLab 官方没有完整的简体中文语言包但前端界面支持 locale 文件覆盖。社区里有人维护汉化补丁最省心的办法是登录后进入用户偏好设置把 Language 改成 “简体中文”部分菜单和按钮会变成中文。如果你想要完整汉化可以去找对应版本的汉化包但我提醒一句GitLab 升级很频繁汉化包如果没跟上版本会出各种显示异常我一般不建议生产环境搞汉化。5. 常见问题与排查技巧实录5.1 503/502页面八成的坑都在内存这个算是 GitLab 新手最常遇到的页面了。装完之后打开网站发现 502 或者 “Whoops, GitLab is taking too much time to respond”。第一次遇到我差点以为装失败了花了大半天排查。后来总结出来95% 的情况是内存不够GitLab 的组件起不来或起了一部分就崩了。先看服务状态sudo gitlab-ctl status如果有组件显示 down 或者 exited说明哪个组件崩了。再看日志sudo gitlab-ctl tail我在只有 2GB 内存的机器上试过跑起来极其勉强动不动就 OOM。解决办法有两个。第一个是加 swap给系统加一个交换分区最直接有效sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile为了让重启后 swap 仍然生效还需要在 /etc/fstab 里加一行 /swapfile none swap sw 0 0。第二个办法是适当削减 GitLab 的资源占用。编辑 /etc/gitlab/gitlab.rb限制 Puma worker 数量或者直接关掉一些非必需组件比如 Prometheus 监控puma[worker_processes] 2 puma[min_threads] 1 puma[max_threads] 4 prometheus_monitoring[enable] false改完 reconfigure 再看502 一般就能缓解。这里我要强调一下如果机器只有 2G 内存还准备跑 CI那 502 会一直跟着你最好的方案是加到 4G 以上再上生产。5.2 端口冲突80 或 8080 被占安装后访问页面发现 Nginx 起不来日志报 “bind() to 0.0.0.0:80 failed (98: Address already in use)”基本就是 80 端口被占了。你可以用 ss -lntp 或 netstat -lntp 看看是哪个进程占用的。解决办法按优先级排列第一如果有系统自带的 httpd 或 nginx直接停掉sudo systemctl stop httpd sudo systemctl disable httpd第二如果这个端口还有别的用途改 GitLab 的端口。修改 /etc/gitlab/gitlab.rbexternal_url http://192.168.1.100:8080 nginx[listen_port] 8080记得 external_url 里也要带端口否则网页里生成的克隆地址会漏掉端口。改完 reconfigure 和 restart。5.3 登录报错Login failed. check api token or gitlab version这个报错最近在搜索里特别多我也被坑过一次。它不是网页端登录 GitLab 时报的错而是用 API 客户端、IDE 插件、或者 CI 工具配置 GitLab 连接时出现的提示。常见原因有几种一是你配置的 Personal Access Token 已经过期或者权限不够二是客户端版本与 GitLab 版本 API 不兼容三是填写的 GitLab URL 不对比如漏了 /api/v4 路径。排查顺序建议这样先确认 GitLab 版本进入 Admin Area - 底部能直接看到版本号。然后到用户设置里重新生成一个 Token权限勾选 api、read_repository、write_repository。最后检查客户端填写的地址确认接口地址是 http://你的GitLab地址/api/v4 这种格式。如果是老版本的 Jenkins 或第三方工具GitLab 版本太新也可能发生协议不兼容这时候要么升级客户端要么给工具配置一个新的低版本权限 Token。5.4 忘了 root 密码怎么办如果 initial_root_password 文件已经被删除你又没保存过密码就只能命令行重置了。GitLab 提供了一条 Rails runner 命令sudo gitlab-rails runner user User.find_by(username: root); user.password 新密码; user.password_confirmation 新密码; user.save!执行完以后用新密码登录即可。注意这条命令必须在 GitLab 服务正常的机器上执行如果服务本身就坏了先按 5.1 把服务修好再跑。5.5 升级失败与安全漏洞修复GitLab 社区版大概每个月会发布一个小版本其中有部分版本是安全修复版修复高危漏洞。关于升级我提三个要点。第一是升级前一定要备份。备份最重要的两个文件是 /etc/gitlab/gitlab.rb 和 /etc/gitlab/gitlab-secrets.json。gitlab-secrets.json 保存了数据库加密密钥、2FA 密钥等关键信息文件丢了或者损坏账号数据就彻底没法用了。第二是升级路径不能乱跳。跨大版本升级比如 14.x 直接升 16.x很容易失败GitLab 官方要求按主版本逐级升级。你可以按月社区版升级节奏走每次只升一两个小版本。第三是及时关注安全公告。GitLab 历史上曝过不少高危漏洞比如任意文件读取、账号接管之类的一旦出了高危 CVE官方都会出修复版。我的习惯是每个月检查一次当前版本和最新版本非安全更新可以攒着安全更新则尽快处理。5.6 问题速查表症状常见原因处理办法访问网站返回502/503内存不足组件挂掉加swap、限制Puma线程、关闭PrometheusNginx起不来报端口占用80端口被别的进程占用停掉冲突服务或修改listen_portSSH连接报Permission denied公钥没配对/防火墙拦22端口检查SSH Keys配置、firewall放行22端口等了好久才出页面点击操作极慢服务器磁盘慢/内存不够换SSD、加内存、优化swap邮件功能无效发不出通知SMTP配置错误/端口被封检查SMTP账号授权码用非加密端口测试推送代码时报HTTP 413Nginx上传大小限制nginx[client_max_body_size] 调大6. 最后再分享几句实在话经过这几年的使用和反复折腾我对 GitLab 安装部署最大的体会是安装本身只是一条命令的事真正花时间的是环境规划和资源规划。测试环境里 2GB 内存就能玩起来但如果你想让它成为团队日常依赖的基础设施内存、磁盘、备份、安全更新这些不能省。最后再分享一个小技巧等 GitLab 稳定运行一段时间后我强烈建议你研究一下它自带的 CI/CD 功能从写好 .gitlab-ci.yml 开始。哪怕只是加一个“push 后自动打包”这么小的流水线你也会立刻感受到这套系统的威力。GitLab 装好只是开始用起来才是真正的价值所在。我后续也会把 CI/CD、镜像仓库、Kubernetes 集成这些实践单独整理出来如果你这次顺利跑通了就到评论区告诉我你是在什么环境下装的遇到了哪些奇葩问题我们一起把坑填平。