第一次接触GitLab的时候我其实挺懵的。GitHub用得挺熟但公司不让把代码放外部平台要自己在内网搭一套代码托管系统。当时查了一堆资料装完以后又是没域名、又是改端口、又是没法跑CI硬是把一个“入门”搞成了“折腾”。回头来看如果一开始有人把GitLab从安装、配置、日常使用到CI/CD一条线讲清楚我至少能少走两三天弯路。这篇就当是给当年的自己写的一份手册也希望能帮到正打算上手GitLab的人。GitLab说到底就是一个基于Git的代码托管平台它和GitHub最大的区别就是可以完全部署在你自己的服务器上代码、用户、权限、CI/CD全都在自己掌控内。它还能干很多GitHub社区版干不了的事比如内置的CI/CD流水线、项目级别的代码质量检查、更细粒度的分支保护。对中小团队来说部署一套GitLab基本等于把代码托管和自动化发布一并解决了。这篇“骨灰级入门”不打算讲太玄的东西我会从最基础的部分拆开讲适合这几类人刚接触GitLab、连仓库都不会建的新手负责在公司内网搭建GitLab的运维或全栈想用GitLab CI/CD发布项目但被各种概念卡住的后端、前端工程师。1. 先搞清楚GitLab解决什么问题再决定要不要用它1.1 为什么团队需要一个私有代码托管平台我见过不少团队一开始就是网盘传代码、U盘拷贝代码甚至直接在服务器上改文件。代码量小的时候还能忍等团队超过三个人问题就全冒出来了谁改了什么不知道两个人在不同电脑上改同一份文件最后对不上。Git本身解决的是版本管理问题但Git没有一个“中心仓库”来统一权限、做代码评审、记录问题于是就需要一个平台把这层能力补上。GitLab在这类工具里算是最省心的选择之一。它开箱即用安装包里把Web界面、Git仓库、数据库、Redis、Sidekiq后台任务全部打包好了。部署在本地服务器后团队成员只需要在浏览器里打开一个地址就能创建项目、提Merge Request、看代码提交记录。对外部网络来说代码完全不出内网这一点对很多公司来说是刚需。GitLab的定位其实比GitHub更“公司化”。GitHub是一个开放社区而GitLab更强调自托管和企业级工作流。它内置了很完整的权限模型比如Guest、Reporter、Developer、Maintainer、Owner五种角色分支可以设置保护只有指定角色才能直接推代码Merge Request里可以做讨论、指派 Reviewer、设置流水线状态为“绿色”才能合并。这些能力组合起来就能形成一套很完整的代码评审流程。1.2 CE、EE、版本选择别再绕晕了GitLab分成两个版本Community EditionCE社区版和 Enterprise EditionEE企业版。社区版免费覆盖了绝大多数中小企业需要的功能项目托管、Issue跟踪、Merge Request、内置CI/CD、Container Registry、Wiki等。企业版多了不少审计、合规和扩展功能比如多集群部署支持、合规流水线、项目级别安全报告等但需要付费订阅。我的建议很简单刚开始用CE版本就够完全没必要一开始就上EE。你后续如果真需要企业功能在GitLab的管理界面里直接操作升级数据不会丢配置文件也不用大动。别一上来就纠结“要不要花钱”先把核心流程跑通比什么都强。还需要注意一个点GitLab有两个安装方向Omnibus一体化包和Cloud NativeKubernetes Helm Chart。除非你团队已经全面Kubernetes化否则我强烈建议用Omnibus方式所有组件都由同一个包管理升级、备份、排障都简单很多。下面我讲的所有内容也都基于Omnibus方式。2. 本地服务器搭建Docker、离线包和域名配置2.1 服务器资源怎么规划才不翻车GitLab是出了名的吃内存。官方建议最低配置是2核心4GB内存跑一个小型实例但实测下来内存至少4GB起步最好给到8GB否则你在上面再跑Runner、跑CI流水线内存直接爆掉。我个人的经验是50人以下小团队4核8GB内存、100GB SSD存储这个配置能撑住如果你们还要用Docker构建镜像磁盘一定要留足镜像文件非常占空间。有条件的建议把数据目录单独挂一块磁盘GitLab的所有数据都在/var/opt/gitlab下面以后就算系统盘挂了数据还在。SSD和机械盘的区别非常大GitLab有很多后台任务会频繁读写机械盘会导致页面卡顿、仓库响应慢甚至操作超时。这块别省。安装GitLab前还要想好域名。最正规的做法是给GitLab分配一个子域名比如gitlab.example.com后面还要配HTTPS证书。如果没有域名直接拿服务器IP访问也能用但后面会遇到一个问题clone地址显示的是“机器ID”而不是域名成员拉代码时一脸懵。这个坑在后面详细说。2.2 Docker安装GitLab十分钟跑起来Docker是现在搭GitLab最舒服的方式。只要服务器装了Docker一条命令就能把GitLab拉起来。我常用的方式是把所有配置都放到环境变量里数据持久化到宿主机目录这样升级容器不会丢数据。docker run --detach \ --name gitlab \ --hostname gitlab.example.com \ --publish 443:443 \ --publish 80:80 \ --publish 22:22 \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ --env GITLAB_OMNIBUS_CONFIGexternal_url https://gitlab.example.com; \ gitlab/gitlab-ce:16.11.0-ce.0提示生产环境建议指定具体版本号不要无脑用latest。latest在自动更新时可能带来不可控的版本变化尤其是大版本升级接口和数据格式都可能变。这条命令里有几个关键点external_url是GitLab对外访问的基础地址所有clone链接都会以它开头。比如你用http://192.168.1.10:8080来访问那clone地址就是http://192.168.1.10:8080/group/repo.git。--publish 22:22是让容器里的SSH服务直接占用宿主机的22端口这样以后用gitgitlab.example.com这种方式拉代码才能通。如果宿主机的22端口已经被占用了那就改成--publish 2222:22但团队成员clone时就要在SSH URL里写明端口稍微麻烦一点。数据卷一定要挂不挂的话容器一删GitLab的数据就全没了。启动后别急着访问GitLab初始化很慢尤其是第一次启动要等两到五分钟。你可以一直看日志docker logs -f gitlab日志里看到类似“GitLab is ready”的字样时再用浏览器访问。初始管理员账号是root首次访问会让你设置密码。如果页面一直返回502说明服务还在初始化多等等就行。2.3 Linux离线部署GitLab完全断网环境下的操作有些内网环境压根访问不了外网Docker拉镜像都成问题这时候就得提前准备离线安装包。GitLab官方提供了rpm包和deb包分别对应CentOS系和Debian系系统。你需要在能联网的机器上下载对应版本的安装包再用U盘或堡垒机拷进内网。# CentOS / RedHat rpm -ivh gitlab-ce-16.11.0-ce.0.el7.x86_64.rpm # Debian / Ubuntu dpkg -i gitlab-ce_16.11.0-ce.0_amd64.deb离线安装最大的困难不是装包而是依赖。GitLab依赖很多系统基础库比如curl、policycoreutils、openssh-server、postfix等。建议在离线内网里先配置好本地Yum/Apt源或者提前把所有依赖也下载好一起拷进去。装完包之后修改配置文件/etc/gitlab/gitlab.rb把external_url设置成你的访问地址然后执行gitlab-ctl reconfigure gitlab-ctl statusreconfigure会把所有组件按配置重新生成一遍这个过程要几分钟。执行完后用gitlab-ctl status看各服务状态正常就基本完成了。离线环境要特别注意权限和防火墙GitLab使用的80、443、22或自定义端口都要放通不然团队成员只能干瞪眼。2.4 域名配置和HTTPS别让clone地址变成机器ID我见过太多人装完GitLab之后页面里显示的clone地址是http://192.168.1.10/group/repo.git或者干脆显示一串机器ID。这归根到底就是external_url没配好。如果你的场景是内网访问最简单的方案是把external_url设为http://gitlab.example.com然后在DNS或内网hosts里把gitlab.example.com指向GitLab服务器IP。改完配置后执行gitlab-ctl reconfigure页面所有链接就都会以这个域名为前缀了。# /etc/gitlab/gitlab.rb external_url http://gitlab.example.com如果要提供HTTPS可以在外部用Nginx反向代理也可以直接让GitLab自己接管证书。GitLab内置了Lets Encrypt的自动证书申请前提是你的域名能正常解析到这台服务器且80端口可被外网验证external_url https://gitlab.example.com letsencrypt[enable] true letsencrypt[contact_emails] [adminexample.com]内网环境下没有外网域名也可以使用自签证书不过团队成员每台机器都要把证书安装到信任列表否则clone时会提示证书不受信任。建议还是统一用内网CA或者一台公共的DNS服务器解析域名会省很多麻烦。注意改了external_url后老项目里的clone地址不会自动变。GitLab会在后台把HTTP地址改成新的域名但本地已有仓库的remote地址需要自己手动更新git remote set-url origin http://gitlab.example.com/group/repo.git。3. 上手操作SSH、建项目、传代码和IDE集成3.1 SSH密钥配置一次性搞定不用每次输密码在GitLab上拉取和推送代码最推荐的方式是SSH密钥。原理很简单你本地生成一对公私钥公钥放到GitLab上以后GitLab看到用这把公钥签名的请求就承认是你的操作不需要再输密码。生成密钥ssh-keygen -t ed25519 -C your_emailexample.com一直回车默认生成在~/.ssh/id_ed25519。然后把公钥内容复制出来cat ~/.ssh/id_ed25519.pub登录GitLab头像 - Preferences - SSH Keys把公钥粘贴进去保存即可。建议密钥类型用ed25519比传统的RSA更短更安全GitLab新版本完全支持。验证是否配置成功ssh -T gitgitlab.example.com如果返回Welcome to GitLab, username!就说明通了。如果提示权限被拒绝先检查你本地的私钥是否是当前使用的私钥再看GitLab上公钥是否正确。3.2 同一台电脑同时连GitLab和GitHub很多人本地既要用GitHub又要用公司私有GitLab默认配置下会冲突。解决办法也不难用SSH config给不同Host起别名。编辑~/.ssh/configHost github.com HostName github.com User git IdentityFile ~/.ssh/id_github Host gitlab.example.com HostName gitlab.example.com User git IdentityFile ~/.ssh/id_gitlab然后分别生成两对密钥、分别添加到两个平台。这样在GitHub项目里用gitgithub.com在GitLab项目里用gitgitlab.example.comGit会自动选择不同的私钥互不影响。核心思路就是一个平台对应一把私钥通过Host区分。3.3 从建仓库到上传代码完整走一遍在GitLab页面上点击“New project”创建仓库。可以用“Create blank project”创建一个空仓库也可以选择“Import project”从GitHub、Bitbucket等平台导入还可以直接上传现有文件夹。创建完之后页面会给出完整的命令提示。假设你的仓库地址是http://gitlab.example.com/dev/web-demo.git那么上传已有本地项目cd my-project git init git add . git commit -m init project git branch -M main git remote add origin http://gitlab.example.com/dev/web-demo.git git push -u origin main拉取仓库代码到本地git clone http://gitlab.example.com/dev/web-demo.git新手经常搞混一个点clone地址里的路径是“用户/项目”或“组/项目”。如果项目建在某个Group下URL里就会带Group名没建Group则通常在用户名下。拉代码之前先到项目首页右上角点击“Clone”复制页面给的地址就肯定不会错。3.4 页面上传文件、在线编辑和Web IDEGitLab不仅是一个代码仓库附带的Web功能也够用。如果只是临时改一个README、补一个配置文件完全不用本地拉代码直接在页面上编辑即可。在项目页面打开文件列表右上角有“Add file”按钮可以直接上传文件也可以新建文件。点“Edit”能在网页里修改内容并直接提交。还可以打开Web IDE它是一个轻量级的在线编辑器支持多文件编辑、Git操作、终端模拟拿来应急改代码挺顺手。这类功能适合轻量级操作任何有可能冲突的大批量改动还是建议本地开发通过Merge Request走评审流程别直接在网页上改一堆核心代码。3.5 IDEA里登录GitLab和切换账号开发工具里最常用的就是IntelliJ IDEA。第一次使用时在Settings - Version Control - GitLab里点击“Add”填GitLab地址和Access Token。但很多人不知道Access Token哪里找GitLab右上角头像 - Preferences - Access Tokens勾选API、read_repository、write_repository等权限设置一个Token并复制保存。公司里经常遇到离职同事或换号后IDE还在旧账号的情况。IDEA里切换GitLab账号先把原来的账号移除再添加新Token。要注意一点光在GitLab设置里删除Token不够IDEA的底层凭据也存了一份。Windows环境打开“控制面板 - 凭据管理器”把带gitlab的凭据删干净再重新添加不然会一直报403。经验分享Access Token的权限不要一次给满了按需分配。给Token设置过期时间防止长期暴露造成泄密。IDEA里填Token时如果提示Authenticate失败多半是Token过期或API权限不足。4. CI/CD实战Runner、流水线和Docker镜像自动化部署4.1 GitLab Runner让代码自己跑起来GitLab本身的Web服务不负责执行CI任务它只负责调度真正干活的是GitLab Runner。Runner可以装在同一台服务器上也可以装在独立的构建机上甚至可以在Kubernetes里按需创建。刚开始入门最简单的方式是把它装在你自己的服务器上。Runner安装完以后需要注册到GitLab。先到项目的Settings - CI/CD - Runners找到Project registration token。然后在Runner服务器上执行gitlab-runner register过程中它会问GitLab URL填http://gitlab.example.com/填注册Token给Runner起一个描述名字填写执行器类型。第一次用建议选shell它最简单直接在Runner机器上用shell执行构建命令。如果你选dockerRunner会在Docker容器里执行任务环境更干净但一开始还要折腾镜像和挂载问题。注册完成之后在GitLab Runners页面就能看到这个Runner在线。这里有一个新手绕弯的点同一个Runner可以注册成项目级Runner也可以注册成整个GitLab实例共享的Runner。个人项目先用项目级Runner就行等以后项目多了再考虑加一个Shared Runner统一复用。4.2 没有.gitlab-ci.ymlRunner会不会触发这个问题几乎每个团队都会有人问“我没写.gitlab-ci.yml但push代码后还是看到Runner有动静是不是触发了”直接说结论没有.gitlab-ci.yml文件GitLab不会生成Pipeline也就不会真正执行任何CI作业。你看到Runner“有动静”通常有这几种可能你配置了Project或Group级别的Runner它只是在线保持心跳并不是在跑任务你在GitLab UI里手动点了“Run pipeline”系统会提示你缺少配置文件并拒绝执行你通过API或Webhook触发了某一个项目但项目根目录或指定路径下没有找到.gitlab-ci.yml流水线会直接显示“No configurations found”。所以真正要跑CI必须在仓库里放一个.gitlab-ci.yml它放在项目根目录就默认生效。如果你的配置文件在别的位置可以在项目设置里指定CI/CD configuration path。更准确地说没有YAML文件Runner根本不会执行构建步骤这是GitLab设计的规则不是Bug。4.3 写一个从构建Docker镜像到自动部署的流水线现在来点实战。假设你有一个Java后端项目目标是推送代码后自动构建Docker镜像推到GitLab Container Registry然后部署到一台测试服务器。先让项目支持Container Registry。在项目页面Settings - General - Visibility, project features, permissions把Container Registry打开。然后写.gitlab-ci.yml最简版本如下stages: - build - deploy variables: IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA build: stage: build image: docker:24 services: - docker:24-dind script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG only: - main deploy: stage: deploy image: alpine:latest before_script: - apk add --no-cache openssh-client script: - sshpass -p $SSH_PASSWORD ssh -o StrictHostKeyCheckingno root$DEPLOY_SERVER docker login -u \$CI_REGISTRY_USER\ -p \$CI_REGISTRY_PASSWORD\ $CI_REGISTRY docker pull $IMAGE_TAG docker rm -f app || true docker run -d --name app -p 8080:8080 $IMAGE_TAG only: - main这里解释几个关键概念$CI_REGISTRY_IMAGE、$CI_REGISTRY_USER、$CI_REGISTRY_PASSWORD是GitLab预置的环境变量分别表示当前项目的镜像仓库地址、登录账号和登录密码。CI_COMMIT_SHORT_SHA是当前这次提交的短哈希用它做镜像标签每次提交都生成新镜像部署时不会互相覆盖。docker:24-dind服务用来在Runner容器内部运行Docker守护进程否则你在Docker环境里没法再执行docker build。Docker登录还需要注意不要用交互式docker login否则会卡在密码输入上。更稳妥的方式是在项目的CI/CD Variable里直接设置CI_REGISTRY_PASSWORD并在脚本里用echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRYDEPLOY_SERVER和SSH_PASSWORD这些敏感信息放到项目Settings - CI/CD - Variables里不要写死在YAML文件里更不要提交进代码仓库。GitLab Variable在Pipeline执行时自动注入日志里默认会被掩码相对安全。4.4 Jenkins配置GitLab connection要不要放弃Runner有些团队已经在用Jenkins想用GitLab做代码托管又不想把CI全部迁到GitLab Runner。那就可以用Jenkins的GitLab插件打通两边。首先在GitLab生成一个Personal Access Token右上角头像 - Preferences - Access Tokens勾选api权限生成并保存。然后在Jenkins的Manage Jenkins - Configure System - GitLab里填入Connection name随便起比如company-gitlabGitLab host URL填你GitLab的访问地址Credentials - Add - GitLab API token填入刚才生成的Token勾选“Ignore SSL certificate errors”如果是自签名证书填完点“Test Connection”如果返回“Success”说明Jenkins和GitLab已经连通。之后你在Jenkins里创建Pipeline任务在构建触发器里勾选“Build when a change is pushed to GitLab”把Webhook地址复制到GitLab项目Settings - Webhooks里Jenkins就能通过Webhook感知代码推送并自动触发构建。整个流程跑通了你就能得到一套完全基于Jenkins的自动化流水线。不过我的个人感受是既然已经用了GitLab不如直接用GitLab Runner省掉Jenkins这一层复杂度。除非你们有历史资产必须留在Jenkins否则没必要同时维护两套CI系统。当然Jenkins的插件生态确实成熟有些人就是习惯了它的自由风格这也完全合理。5. 安全问题、登录失败和日常维护避坑5.1 GitLab高危漏洞与防御措施GitLab作为代码仓库一旦被攻破整个代码资产都会泄露所以安全维护必须重视。网上说的“GitLab高危漏洞修复方案”最核心的其实不是打某一个补丁而是做好基础加固。第一升级永远是最有效的修复。GitLab每个版本发布时官方都会同步修复已知的高危漏洞尤其SSRF、任意文件读取、RCE这类问题几乎都要求升级到对应修复版本才安全。你可以在管理界面看到当前版本然后对照官方发布记录决定是否升级。生产环境升级前要先备份不能直接莽。第二关闭公开注册。新装好的GitLab默认允许用户自行注册大家都在内网还好但只要暴露到公网这就是一个风险口。管理员界面 - Settings - General - Sign-up restrictions取消勾选“Sign-up enabled”把注册入口关掉所有账号统一由管理员创建。第三开启强制2FA。大型团队可能推进困难但至少管理员账号必须开2FA。把管理员账号和个人日常账号分开普通用户使用时不给予Owner权限减少误操作和账号泄露带来的影响。第四合理设置项目可见性。默认项目可见性建议改为“Private”不要使用“Public”。一旦项目设成Public任何登录用户都能看到代码这种事故我见过太多次了。我整理了一个简单的安全加固清单项目操作版本升级每季度至少升级一次重大漏洞发布后尽快升级注册控制关闭公开注册关闭注册验证码入口密码策略设置最小密码长度定期强制改密管理员账号启用2FA指定专用管理员SSH/Token定期巡检Token权限删除不用的密钥备份每日自动备份备份数据隔离存放5.2 Login failed. Check API token or GitLab version这条报错太经典了我在Jenkins连接GitLab、命令行用API访问GitLab时都遇到过。报错原文一般是ERROR: The GitLab connection is failing! Please check GitLab connection settings and GitLab version. ERROR: Login failed. Check API token or GitLab version. Log in via Git if the version is unsupported.出现这个报错原因基本都在下面几个方向API Token无效。旧Token过期了或者生成Token时没勾选api权限。重新生成一个Token再试。GitLab版本和工具版本不兼容。老版本的GitLab用的是V3 API新工具默认打V4接口导致登录失败。检查GitLab版本升级到较新版本或者把工具的API版本调到和GitLab匹配。自签名证书问题。请求API时SSL校验失败也可能表现出“login failed”。在Jenkins那个连接配置里勾选“Ignore SSL certificate errors”或者在客户端设置信任。网络不通。如果GitLab地址从外部访问不通或者防火墙拦截了也会报连接失败。先用浏览器或curl试一下http://gitlab.example.com/api/v4/projects看看返回什么能通过网页正常访问再排查认证问题。排查顺序建议是先确认网络通不通再确认Token有没有权限最后看版本是否过老。别一上来就怀疑机器配置那样容易浪费时间。5.3 Clone域名是机器ID不是域名一次改到位“gitlab clone with http 怎么clone设置为域名 不是机器ID”——这句话说明很多人真的被这个问题折磨过。出现这个现象最直接的原因就是/etc/gitlab/gitlab.rb里的external_url没有设置或者设置成了服务器IP或者用的是默认机器ID。GitLab在生成项目clone地址时完全依赖external_url这个配置。解决办法就是编辑/etc/gitlab/gitlab.rb把external_url改成域名执行gitlab-ctl reconfigure让配置生效如果是Docker部署需要在启动命令里通过GITLAB_OMNIBUS_CONFIG传入external_url旧项目如果已经有本地clone链接手动更新remote地址。改完配置后在项目页面按一下刷新clone下拉框里的地址就会变成域名。如果还不生效检查DNS和hosts解析确认域名确实指向了GitLab服务器IP然后再reconfigure一次。5.4 核心目录备份和恢复GitLab的数据都在/var/opt/gitlab目录下备份本质上就是把这个目录打包带走。官方提供了更优雅的方式gitlab-backup create执行后会生成一个Backup压缩包默认在/var/opt/gitlab/backups目录里。恢复时先执行gitlab-ctl stop puma和gitlab-ctl stop sidekiq然后gitlab-backup restore BACKUPxxxx_timestamp恢复完成后启动服务gitlab-ctl start我在实际运维里会再加一个定时任务每天凌晨把backup目录同步到另一台机器防止整个服务器一起挂掉时数据全丢。备份这件事宁可冗余一点也不要等出事了再后悔。6. 写在最后几个我能帮你省时间的习惯其实落到真实业务中GitLab入门最大的坎不是某个命令不会写而是不知道该先做什么、后做什么。我的经验是先把安装和域名跑通不要急着折腾CI然后在日常项目里真实推送几周代码熟悉GitLab的权限和Merge Request流程等这些都变成肌肉记忆了再上手Runner和流水线你会发现一切都是顺其自然的。最后再分享一个小技巧新装GitLab时第一时间就把external_url配成域名把Container Registry打开把公开注册关掉。这三件事前五分钟做掉后面能少踩无数坑。代码需要备份配置同样需要备份/etc/gitlab/gitlab.rb出问题比代码出问题更让你头大。我用GitLab这几年最大的体会是它并不复杂只是信息太散很多细节都要自己试错。希望这篇能让你少走几步弯路把时间花在真正有产出的事情上。