简介GitLab 用户手册 v2.pdf 是一份面向开发团队、运维人员及测试人员的 GitLab 实操入门指南系统梳理了从环境搭建到高级功能应用的完整链路。手册以 Git 客户端安装为起点逐步讲解全局用户名与邮箱配置、通过 GIT BASH 执行 ssh-keygen 生成 SSH 密钥、将公钥导入 GitLab 服务器含修改初始密码、Profile Setting、SSH Keys 页面操作等关键环节后半部分则进一步覆盖项目创建与克隆、版本历史与提交记录查看以及 CI/CD 管道、代码评审、权限管理等进阶能力全程配合图文步骤说明适合初涉 GitLab 的开发者按步骤快速上手。PDF 文件共 1 个压缩包仅 1.04MB体积轻量便于随时查阅。文档配有具体命令与界面操作说明可帮助读者理解 Git 与 GitLab 的协作机制掌握项目版本管理、提交记录查看及团队协作的核心技能。已有 538 人学习下载是入门 GitLab 的实用参考资料。1. 为什么 GitLab 手册能写两百页核心却只有这几件事拿到《gitlab用户手册v2.pdf》这份文档的人多半不是想通读而是带着具体问题来的新同事要配 SSH 密钥、团队要导入一批代码仓库、服务器重启后 GitLab 起不来了、仓库越来越大磁盘快满了。这三类问题基本覆盖了 GitLab 从部署到日常使用的全部场景。这本手册如果把每个功能都展开写篇幅会非常吓人。但对一线工程师来说真正值得花时间掌握的只有一条主线账号与认证怎么配、项目怎么建怎么导、权限怎么卡、备份怎么做、出了故障怎么排查。其余功能都是在主线上长出来的枝叶。本文不打算复述整本 PDF而是把手册里最容易被跳过、却最能救命的章节挑出来配上一线踩坑记录让你看完能直接回到工位上动手。目录、权限、CI、运维各取所需。如果你刚接手团队 GitLab看完至少能回答两个问题这系统现在健不健康以及我能不能在不动全局的情况下把日常管理撑起来。2. 账号与认证SSH 密钥、HTTP 凭据与 login failed 的真相2.1 SSH 密钥配置从生成到测试的完整链路GitLab 的开发者日常交互九成走 SSH 协议。这里说的配置不是简单把公钥贴到网页里就完事而是整条链路都要通。首先生成密钥我一般建议用 ed25519兼容性和安全性都优于老旧的 RSA 2048ssh-keygen -t ed25519 -C your_emailexample.com -f ~/.ssh/gitlab_ed25519生成后把公钥内容复制出来登录 GitLab 网页端在「用户设置 → SSH 密钥」页面粘贴并保存。密钥类型会自动识别为 Ed25519有效期字段可以留空默认表示永不过期。然后配置~/.ssh/config让 Git 知道连 GitLab 时该用哪个私钥这对一台机器配多个 Git 服务的情况尤其重要Host gitlab.example.com HostName gitlab.example.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yesIdentitiesOnly yes这个参数容易被忽略它的作用是禁止 SSH 尝试所有已加载的私钥强制只使用指定文件。如果不加当本机有其他密钥时认证过程会逐个尝试GitLab 服务端看到太多无效签名偶尔会直接拒绝连接。配置完成后用ssh -T gitgitlab.example.com验证看到 Welcome to GitLab 字样就说明链路通了。2.2 HTTP 方式与凭据管理器什么时候不推荐 SSH并非所有场景都能走 SSH。有些公司的网络策略只放行 443 端口GitLab 的 SSH 端口被防火墙挡死这时候只能退到 HTTP 协议。HTTP 方式的关键在于凭据保存否则每次 push 都要输一次用户名和密码。Linux 下我一般启用 Git 自带的凭证存储git config --global credential.helper store这个命令把凭据明文存在~/.git-credentials里安全级别不高适合内网环境。如果对安全有要求换成cache模式只缓存内存里一段时间。Windows 环境下通常用 Git Credential Manager首次输入密码后由 Windows 凭据管理器代为保存会自动弹出登录窗口体验比 Linux 下完整不少。很多人不知道的是HTTP 方式的账号密码并非登录密码而是需要单独生成访问令牌。在 GitLab 网页端「用户设置 → 访问令牌」里勾选write_repository和read_repository权限生成一串令牌push 时用户名填任意非空值、密码填令牌即可。热词里提到的login failed. check api token or gitlab version. log in via git if the versi这类报错九成出现在 IDE 的 GitLab 集成插件里原因就是填了登录密码而不是访问令牌或者令牌权限没勾仓库读写。2.3 登录失败排查令牌、版本与缓存的三方博弈这类login failed报错通常发生在 IDEA、VS Code 的 GitLab 插件或第三方桌面客户端里现象是插件提示无法连接但命令行 Git 一切正常。先确认版本匹配GitLab 15.0 之后旧版的插件 API 调用可能失效GitLab 16 又改了部分接口的返回格式。插件若长期不更新就会出现「命令行能用、插件永远登录失败」的怪象。提示登录失败时先打开浏览器访问 GitLab 首页确认服务正常再在命令行执行git ls-remote http://gitlab.example.com/group/repo.git验证令牌是否有效。两步都通过问题就锁定在插件缓存上清掉 IDE 的 GitLab 插件缓存重试即可。还有一个低频但隐蔽的坑某些版本里令牌有api和read_api的单独开关插件要求令牌具备api权限而用户在创建令牌时只勾了read_repository结果读仓库正常、写操作和元数据拉取全部失败。做法是重新生成令牌直接勾选api权限一劳永逸。3. 项目导入与仓库管理从新增项目到 pack 文件瘦身3.1 新增项目流程四种来源与权限的默认选择GitLab 里新增项目是高频操作但团队里最常犯的错误是把「新建空项目」和「导入现有项目」混为一谈。网页端「新建项目」按钮下有四个分支空白项目、导入项目、从 CI/CD 模板创建、从运维模板创建。导入项目又分 GitLab 实例间迁移、GitHub 导入、Bitbucket 导入、以及任意 URL 导入。选择任意 URL 导入时源仓库地址支持 HTTP 和 SSH 两种格式HTTP 方式需要提供源仓库的凭据GitLab 后台会异步执行导入大仓库可能需要几分钟。创建项目时命名规范建议直接定死我经手的团队一般统一小写字母加连字符比如backend-user-service禁止驼峰和下划线。可见性级别选「私有」默认不要开「内部」或「公开」避免代码意外泄露。初始化仓库时建议同时勾选「使用默认 README 初始化」这样项目自带一个默认分支后续推送代码不会出现「空白仓库 push 被拒」的困惑。3.2 本地项目上传到 GitLab两种命令路径与分支错位很多开发者的本地项目已有 Git 历史这时不需要重新 init直接添加远程地址推送即可git remote add origin gitgitlab.example.com:group/backend-user-service.git git branch -M main git push -u origin mainbranch -M main这步是强制把本地分支改名避免本地叫master而 GitLab 默认分支叫main导致推送后两边分支不一致、网页端看到两条默认分支的混乱局面。如果是全新目录则先git init再走同样流程。要注意推送前先确认git status里没有敏感文件.env、密钥、打包产物等必须写进.gitignore。另一个常见问题是提交时未配置 user.name 和 user.email推送会被 GitLab 拒绝或提交显示为未知用户排查时先执行git config --global user.name your name git config --global user.email your_emailexample.com邮箱建议用 GitLab 账号绑定的邮箱否则提交记录不会关联到你的用户头像代码量统计也会漏人。3.3 pack 文件过大仓库膨胀的元凶与清理手段热词里有一条非常具体gitlab pack-fb5fe7dfac8e953d5cc65d26074f72d5fa961d98.pack文件很大。这是管理员视角的问题出现在服务端仓库存储目录里。GitLab 的仓库存储本质上就是裸 Git 仓库所有历史对象都被打包成.pack文件。团队频繁推送大文件、误提交二进制又没有后续清理pack 文件会在几次 GC 后快速膨胀。先定位哪些仓库占空间sudo gitlab-rake gitlab:git:gc:status sudo du -sh /var/opt/gitlab/git-data/repositories/*/*/*.git第二行命令按实际仓库路径层级调整。找到大仓库后要区分是历史里藏了大文件还是当前工作区就很大。用git rev-list --objects --all加git cat-file组合排查最准git rev-list --objects --all | git cat-file --batch-check%(objecttype) %(objectname) %(objectsize) %(rest) | awk /^blob/ {print $3, $4} | sort -rn | head -20这条命令列出仓库历史中体积最大的 20 个 blob 对象文件名和大小一目了然。确认是历史遗留问题后用git filter-repo做历史重写把特定路径从全部历史中抹除。重写后所有克隆过该仓库的开发者都需要重新 clone因为 commit hash 全部变了。历史清理完成后在 GitLab 后台执行仓库 GC 或运行gitlab-rake gitlab:git:gc触发一次全量垃圾回收pack 文件会重新打包。提示清理大文件属于高危操作操作前必须做一次仓库级的备份。git filter-repo支持--dry-run模式先跑一遍看影响范围再实际执行能极大减少翻车概率。4. 权限、代码量统计与日常协作手册里最常被翻烂的部分4.1 权限模型Guest、Reporter、Developer、Maintainer、OwnerGitLab 的权限分级一共五档从低到高是 Guest访客、Reporter报告者、Developer开发者、Maintainer维护者、Owner所有者。大部分人只用过 Guest 和 Developer 两档但权限设计失当引发的安全事故几乎都出现在中间档位。Reporter 能看代码、看 CI 日志不能 pushDeveloper 能 push 到非保护分支、能创建分支和标签Maintainer 能改保护分支规则、能合并代码、能调整项目设置Owner 是项目最高权限可以删除项目或转移项目。实操中我一般这么分配外包或实习生给 Reporter正式开发给 Developer技术组长或模块负责人给 MaintainerOwner 只保留一两个人。保护分支默认保护main和master规则是只有 Maintainer 能直接 push其余人必须走合并请求。这个默认规则建议不要改松否则代码评审形同虚设。热词里的「gitlab新增项目流程」其实也和权限相关——新建项目时默认的 Owner 是创建者本人如果创建者离职项目会进入无人管理的状态需要管理员在后台转移项目所有者。4.2 代码量与注释率统计别被单点数据骗了「gitlab仓库代码量和注释率统计」这个热词背后是考核需求。GitLab 本身不提供「代码量排行榜」这种开箱即用的报表但有两种可靠做法。第一是走 Git 底层在服务器上对每个仓库跑git ls-files | xargs wc -l这条命令统计当前分支所有跟踪文件的代码行数按目录、文件类型都能拆分。注释率需要结合语言类型处理Python 和 Shell 的注释语法不同写脚本时按扩展名分支处理即可。第二种做法是在 GitLab 的 Insights 功能里配置自定义报表能统计提交频率、活跃贡献者、代码变更量但需要管理员开启功能并写 YAML 配置在「项目 → 分析 → 洞察」里生效。统计时有个必须注意的坑git ls-files只统计当前 checkout 出来的文件不包含历史版本分支上的代码可能已经合并到 main也可能躺在功能分支上没合入。做团队考核时要统一基准分支和统计口径否则同一个仓库不同人统计出来的行数差异巨大。更合理的指标是「新增行数减去删除行数」可以用git log --since限定时间窗口后统计这才是真实的产出量。注释率比较适合做代码健康度参考不适合做硬性考核因为不同团队的注释风格差异太大容易诱导堆注释。4.3 拉取代码与下载项目协议与分支的四个注意点「gitlab怎么下载项目」和「gitlab拉取代码到本地」这两个热词看来简单但团队新人最常在这上面卡壳。先分清两种含义一个是「把代码拉到本地仓库」另一个是「从网页下载 ZIP 包」。网页端下载 ZIP 在项目主页的「代码 → 下载」但这个包只包含当前分支的最新快照没有 Git 历史不能继续在本地做版本管理。真正的拉取代码是git clone gitgitlab.example.com:group/repo.git cd repo git checkout -b feature/your-work origin/mainclone 默认拉取所有分支的引用和完整历史但只 checkout 默认分支。切到功能分支开发最后合并回 main这是标准协作流。需要拉取指定历史阶段的代码时用git checkout commit-hash进入 detached HEAD 状态此时不能直接提交需要先git switch -c new-branch-name建临时分支。拉取代码时还需要区分 HTTP 和 SSH克隆地址在项目主页的「克隆」按钮里可以切换协议。内网环境如果配了 SSH 但 clone 用了 HTTP 地址会提示输入密码容易让新人误以为账号密码错了。排查这一步最快的方法是直接看克隆地址第二段是git还是http://。5. 部署、备份与升级避坑Ubuntu 24.04、Docker 与启动失败的排查路径5.1 Ubuntu 24.04 与 GitLab 19系统兼容性是个硬门槛热词里「gitlab 19只支持ubuntu 24.04」这条信息对准备新部署的团队非常重要。GitLab 的版本策略有一个明显趋势新版本会提前放弃对旧系统的支持。如果服务器用的是 Ubuntu 22.04而你想装最新的大版本大概率会在 apt 安装阶段就报依赖错误。这属于上游决策不会因为机器配置高就绕过去。我一般建议部署前先确认 GitLab 官方对当前 OS 的支持矩阵重点看两件事——操作系统的 EOL 日期和 GitLab 版本要求的 GLIBC 版本。Ubuntu 24.04 的 GLIBC 版本较新能支撑新版 GitLab而 22.04 如果硬装新版可能出现软件包依赖无法满足的报错。这不是 bug而是系统底层库太旧。做法有两种一是把系统升级到 24.04 再装 GitLab二是安装 GitLab 对应该系统支持的最后一个大版本然后固定在那个版本上等系统迁移后再升级 GitLab。后一种做法更稳适合生产环境。5.2 Docker 部署 GitLab 社区版最省心的方案也有三个参数要调社区版用 Docker 部署是当前中小企业的主流选择因为不用处理 Ruby 和 PostgreSQL 的环境依赖。最小启动命令如下sudo docker run --detach \ --hostname gitlab.example.com \ --publish 8443:443 --publish 8022:22 --publish 8080:80 \ --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端口映射里有讲究8022:22是把宿主机的 8022 映射到容器的 SSH 端口避免和宿主机自身的 22 端口冲突。8080:80是让 HTTP 访问走 8080。但注意容器内部的 GitLab 配置必须同步修改否则网页端显示的克隆地址还是默认端口复制出来的地址无法直接使用。启动后进入容器修改配置sudo docker exec -it gitlab vim /etc/gitlab/gitlab.rb # 修改 external_url http://gitlab.example.com:8080 # 修改 gitlab_rails[gitlab_shell_ssh_port] 8022 sudo docker exec -it gitlab gitlab-ctl reconfiguregitlab-ctl reconfigure是应用配置的关键步骤忘记执行会导致端口修改不生效。容器方式跑 GitLab 的好处是备份方便——直接把三个 volume 目录打包即可恢复时用相同参数重新启动容器挂载回同样的数据目录。社区版没有高可用能力但单机场景完全够用。Docker 部署还有一个隐性注意点latest标签会在docker pull时升级到新版本这会导致容器重建后 GitLab 自动跨版本升级。跨大版本升级有一系列迁移操作如果忘了执行页面可能白屏或出现数据库错误。稳妥做法是固定版本号例如gitlab/gitlab-ce:17.5.2-ce.0每次升级都走手动流程。5.3 备份与恢复gitlab-backup的正确姿势与常见误解热词「gitlab备份」对应的官方命令如下sudo gitlab-backup create这条命令默认备份数据库和 Git 仓库备份文件生成在/var/opt/gitlab/backups目录。但很多人不知道它默认不包含以下文件gitlab.rb配置文件、/etc/gitlab/gitlab-secrets.json密钥文件、以及计划任务配置。这三个文件才是恢复的关键——如果没有gitlab-secrets.json恢复后的实例无法解密已有的 Runner 注册令牌和 2FA 数据。所以完整备份实际是两个动作sudo gitlab-backup create sudo tar -czf /var/opt/gitlab/backups/etc-gitlab-backup.tar.gz /etc/gitlab恢复操作同样要两步先解压配置文件到/etc/gitlab再执行gitlab-backup restore。恢复时要求 GitLab 版本与备份时的版本一致跨版本恢复会直接报错。备份文件的保留策略默认只留 7 天生产环境建议在gitlab.rb里调大backup_keep_time到 30 天并把备份目录挂载到独立磁盘或对象存储避免数据盘故障时备份也丢失。5.4 启动不了与高危漏洞修复三条快速定位路径「gitlab启动不了」是运维热词出现概率最高的三类根因磁盘写满、PostgreSQL 数据损坏、权限被改动。先看目录占用df -h sudo gitlab-ctl statusgitlab-ctl status会列出所有服务组件的运行状态哪个显示down就先处理哪个。如果是postgresql起不来查看日志sudo gitlab-ctl tail postgresql日志里频繁出现的could not open file或No space left on device基本就是磁盘问题清掉/var/log/gitlab下超过 30 天的旧日志再留出 20% 余量即可。处理权限问题要小心/var/opt/gitlab目录的属主必须是git:git如果之前手动改过目录权限恢复命令如下sudo chown -R git:git /var/opt/gitlab sudo chown -R git:git /var/log/gitlab「gitlab高危漏洞修复方案」这个热词对应的是 GitLab 定期发布的安全版本。修复动作没有惊喜升级到修复后的版本即可。但升级前必须做全量备份且注意大版本升级不能跳跃——比如从 16.x 直接升 18.x 很可能失败需要先生到 17.x 再升 18.x。这个规则在官方升级路径文档里有明确说明别试图跳级。6. 最后一章GitLab 日常巡检的五个命令与一个习惯接手中途接手 GitLab 实例先跑一遍巡检比看任何手册都有用。下面这五条命令覆盖健康度、备份、脏数据、权限和磁盘五个维度每季度跑一次能避免大多数突发故障。# 1. 服务健康度 sudo gitlab-ctl status | grep -E (run|down) | wc -l # 2. 备份是否成功看最后一行是否有备份文件 sudo find /var/opt/gitlab/backups -name *.tar -mtime -7 # 3. 有没有项目处于异常状态 sudo gitlab-rake gitlab:check # 4. 仓库里是否有超大的 pack 文件 sudo find /var/opt/gitlab/git-data/repositories -name *.pack -size 1G -exec ls -lh {} \; # 5. 磁盘余量 df -h /var/opt/gitlab | awk NR2 {print used:$5}第一条里grep出来的数字正常应该和总服务数一致数字不一致说明有组件挂了。第二条有输出代表最近一周有成功备份没有输出就要立刻补一次手动备份。第三条的gitlab:check会输出一堆检测项重点看Checking GitLab ... Finished和Checking Environment ... Finished之间有没有红色ERROR。第四条找出超过 1G 的 pack 文件结合上一章的清理流程处理。第五条不用解释磁盘满了一切服务都会停。最后说一个我养成的习惯每次做任何配置变更前先把/etc/gitlab/gitlab.rb和/etc/gitlab/gitlab-secrets.json拷贝一份带日期的备份。这个文件只有几十 KB但它是整个 GitLab 实例的「后悔药」。配置改坏了把文件回滚再跑gitlab-ctl reconfigure就能救回来比重新部署实例快得多。很多 GitLab 翻车现场最终都是靠这两个文件 仓库备份救回来的。希望这份基于手册的实战拆解能帮到你。下一份手册再更新时拿着这五条命令和排查思路去对照你会发现大部分内容都可以略读真正要精读的始终只有认证、数据、备份和升级这四条主线。本文还有配套的精品资源点击获取