简介这是一份面向开发者和运维人员的 GitLab 实用入门手册以 PDF 形式系统梳理了从环境搭建到高级功能的完整使用链路。内容先从 Git 客户端安装与 Git Bash 环境配置讲起详细说明了设置全局用户名、邮箱以及生成 RSA 密钥的操作方法随后介绍如何登录 GitLab、修改初始密码、在 Profile Setting 中导入 SSH 密钥从而打通本地与服务器的安全连接并附有常见路径切换等细节提示。手册还覆盖了创建项目、克隆项目、查看提交记录等基本操作并延伸到 CI/CD 管道、代码审查、权限管理等进阶内容帮助读者从零搭建团队协作流程、掌握代码托管与自动化发布的核心技能。资源为单个 PDF 文件大小约 1.04MB方便离线阅读目前已有 537 人学习下载是快速上手 GitLab 协作流程的不错选择。1. GitLab 用户手册 v2别让新人再追着你问「怎么传代码」我见过太多团队把 GitLab 用户手册写成一本「功能说明书」第一章讲什么是版本控制第二章讲 Git 和 SVN 的区别等新人翻到第五章才看到怎么提 MR——然后他的代码已经在本地躺了三天。真正让团队离不开 GitLab 的不是它功能多而是每个人都能在正确的位置用正确的方式提交代码、走评审、触发构建。gitlab用户手册v2.pdf这个标题背后是团队把「知识从老员工脑子里搬到文档里」的一次整理动作它解决的是新人入职之后反复打扰、操作口径不统一、权限和流程靠口口相传这些实实在在的问题。这篇文字会把一本合格的 GitLab 用户手册拆开来看——里面该有什么、每一步怎么做、哪些地方是大多数团队会翻车的按一线落地顺序讲完。2. 从 v1 到 v2一本 GitLab 用户手册改了什么才让人愿意翻开2.1 v1 手册为什么吃灰文档失灵的三个根因先别急着写 v2得先搞明白 v1 为什么没人看。我带过的团队里第一版手册几乎都死在三个问题上。第一个问题是「按功能组织不按任务组织」。v1 手册的目录通常长这样GitLab 简介、Git 基础命令、Web IDE 使用、项目设置——这像是把 GitLab 的官方文档翻译了一遍。但新人打开手册时的真实心理诉求是「我要把本地代码推到公司仓库」或「我要把线上 bug 修复合并回 main 分支」他按目录找不到入口。第二个问题是「没有截图也没有报错对照」。手册里写「在 Settings 里配置 SSH Key」但新人打开页面发现新版 GitLab 的菜单路径完全不一样卡住之后只能转头问同事手册的可信度就此归零。第三个问题是「没有维护责任人」。v1 是某次项目结束后有人顺手写的之后 GitLab 从 14 升到 16界面和权限模型都变了手册却停留在两年前。v2 要解决的不是把内容写得更全而是让它在「被需要的那一刻」能准确命中。2.2 v2 的目录结构从「系统讲解」到「任务查找」我建议 v2 直接用「角色 任务」双维度来组织目录。所谓角色就是手册的读者不是抽象的「用户」而是有具体身份的人新入职的开发者、项目经理、运维、外包协作人员。所谓任务就是他们打开 GitLab 之后要完成的动作比如注册账号、配置 SSH、创建项目、提交代码、发起合并请求、查看 CI 结果。实际写的时候我会按下面这个顺序排章节章节内容面向对象第一章账号注册、登录、管理员审批与双因素认证所有人第二章SSH 密钥与 HTTPS 凭据配置含 Windows/macOS/Linux开发者第三章项目创建、导入已有仓库、仓库设置项目负责人第四章日常开发流程分支规范、提交规范、MR/PR 流程开发者第五章CI/CD 基础.gitlab-ci.yml 怎么写、流水线怎么看开发者运维第六章备份、恢复、迁移与权限模型运维/管理员这个结构看起来不复杂但它把「功能」拆成了「在某台电脑上完成某个目标」。比如第二章v1 可能只写「配置 SSH 密钥」五个字v2 则要从打开 Git Bash 开始到ssh -T gitgitlab.example.com验证通过结束。每一步都有预期输出每一条命令都标注了在什么操作系统下运行。2.3 黄金路径写法拿分支合并的一个例子说明白「黄金路径」Golden Path是我写手册时最常用的一种方法只写 90% 的人会走的那条路把其他可能性放到「常见问题」里。拿「发起一次合并请求」举例。v1 的写法是「合并请求Merge Request是 GitLab 中用于代码评审的功能支持在分支之间进行合并默认情况下只有 Developer 及以上角色可以发起。」这段话没错但没用。v2 的写法应该是# 假设你在 feature/login-page 分支上开发想把代码合并回 main git push origin feature/login-page推送成功后打开项目页面GitLab 会在顶部弹出提示条「Create merge request」点击后填写标题和描述描述里带上关联的 issue 编号比如Closes #123指派给 reviewer点 Submit。完事。差异在哪v1 描述的是一个功能的形态v2 描述的是一个最小可行路径。写手册的人觉得自己讲清楚了看手册的人其实只想知道第一步做什么、界面长什么样、做完之后会发生什么。后面所有章节都按这个标准重写手册才有被翻开的可能。3. 手册里的前三章账号、密钥、项目与分支的落地步骤3.1 账号注册与管理员审批为什么你的登录页提示 pending approvalGitLab 账号注册分两种常见场景公司自建的社区版以及 GitLab SaaS。自建实例的管理员在Admin Area - Settings - Sign-up restrictions里可以开启「需要管理员审批新注册账号」。开了之后新用户注册完会看到一条提示原文是Your account is pending approval from your GitLab administrator and hence blocked.这个状态会让不少新人误以为自己操作错了。我在手册里会明确写出现这行提示是正常的不是你的问题去找管理员在Admin Area - Users里点 Approve。管理员侧可以看到这个用户的注册时间、邮箱、IP确认是同事就可以批准。如果管理员希望完全关闭开放注册只允许管理员手动创建账号可以在同一个页面取消勾选Sign-up enabled。注册之后立刻要做的是绑定两步验证2FA。社区版免费支持 TOTP管理员也可以在Admin Area - Settings - Sign-in restrictions里强制全员开启。如果你不想被强制开启那天卡在登录页建议注册当天就装好一个 TOTP 应用比如 Google Authenticator 或 Authy把 GitLab 账户绑定进去。这一步在手册里必须前置因为等管理员开了强制策略再来找你要恢复码流程会麻烦不少。3.2 配置 SSH 密钥生成、添加、验证一条龙SSH 密钥是 GitLab 日常使用里最容易出问题、也最值得花整节篇幅写清楚的部分。很多 v1 手册只写「用ssh-keygen生成密钥」但实际落地时Windows 用户会遇到用什么终端、密钥存在哪个目录、多把密钥怎么区分的问题。我建议手册里按操作系统分三个小节这里给出 Linux/macOS 和 Windows Git Bash 通用的最小步骤# 生成 ed25519 密钥-C 换成你的公司邮箱 ssh-keygen -t ed25519 -C your_namecompany.com -f ~/.ssh/gitlab_ed25519 # 直接把公钥内容复制到剪贴板 cat ~/.ssh/gitlab_ed25519.pub拿到公钥内容后登录 GitLab打开Preferences - SSH Keys粘贴到 Key 文本框Title 会自动生成也可以改成「公司笔记本」这类便于识别的名字点击 Add key。这里有个关键坑如果你本机有多把 SSH 密钥比如一把用于 GitHub一把用于 GitLab就不能直接把密钥放在默认位置让系统自动选择。需要在~/.ssh/config里做区分# ~/.ssh/config Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yesIdentitiesOnly yes这行的作用是不让 SSH 客户端尝试所有密钥只使用指定的这一把。很多「Permission denied (publickey)」报错就是这么来的——系统先试了默认密钥失败后就跳过了没有继续尝试正确的那把。验证配置是否成功ssh -T gitgitlab.company.com预期输出是Welcome to GitLab, yourname!。如果提示The authenticity of host ... cant be established输入yes确认指纹就行这是首次连接的正常提示。3.3 导入已有仓库与分支保护规则设置v2 手册里我通常会建议团队在第三章讲清楚两个动作导入外部仓库、设置分支保护。这两个动作几乎是新项目启动时必然要做的。导入外部仓库的路径很简单新建项目时选Import projectGitLab 支持从 GitHub、Bitbucket、Gitee 等平台导入也支持直接填写任意 Git 仓库的 URL 做裸导入。我一般推荐裸导入因为最可控# 本地把远程仓库完整镜像下来 git clone --mirror https://github.com/old-org/old-repo.git # 在 GitLab 上创建空项目拿到新地址后把镜像推上去 cd old-repo.git git push --mirror gitgitlab.company.com:new-org/new-repo.git--mirror会把包括所有远程分支、Tag、以及 Git 引用一并推送过去比手动git push --all --tags更完整适合仓库迁移场景。分支保护是另一个常见需求。默认情况下GitLab 里 main 分支是受保护的只有 Maintainer 及以上角色能直接推送。如果你想允许开发者通过 MR 合入、但禁止直接 push需要在Settings - Repository - Protected branches里确认Allowed to merge是 Developers MaintainersAllowed to push是 Maintainers。这里有个容易忽略的细节如果你把Allowed to push设成了「No one」那出问题时要回滚代码会非常被动建议至少留 Maintainers 可推。4. 手册第六章到第八章CI/CD 配置、备份恢复与权限模型4.1 第一条流水线.gitlab-ci.yml 最小配置与参数说明GitLab 用户手册里如果只讲界面操作不讲 CI那这本手册的寿命不会超过一年。因为现在稍微正规一点的团队都会用 GitLab CI 做提交后的自动检查至少包含编译和单元测试。在手册里我会用一个最小可运行的.gitlab-ci.yml开场因为对新手来说第一目标不是写多复杂的流水线而是「我提交代码后能在 Pipelines 页面看到一个蓝色的转圈图标变成绿色的勾」。# .gitlab-ci.yml stages: - test # 用官方 Python 镜像作为执行环境 image: python:3.11-slim before_script: - pip install -r requirements.txt -q test-job: stage: test script: - pytest --junitxmlreport.xml artifacts: paths: - report.xml when: always expire_in: 1 week逻辑说明stages定义流水线的阶段顺序这里只有一个 test。image指定了每个 job 运行的 Docker 镜像意味着每个 job 的执行环境默认是隔离的、全新的所以每次跑测试都会重新pip install。artifacts是把测试报告文件保存下来when: always表示即便测试失败也要保留报告这样能在页面上直接查看失败的 JUnit 报告而不用去翻日志。参数说明里要重点提两个expire_in控制产物保留时间我一般写 1 周省磁盘script里任何一步返回非零退出码整个 job 就标记失败流水线会停在这个阶段。新手最常见的错误是把这个文件放错位置。.gitlab-ci.yml必须在仓库根目录或者你在项目Settings - CI/CD - General pipelines里指定了自定义路径。文件放错目录GitLab 不会报错只是流水线永远不触发。4.2 Docker 部署的备份与恢复每天凌晨 3 点的后悔药gitlab 的备份恢复属于「用不上最好用上能救命」的章节。在 v2 手册里我会写清楚两件事备份命令和恢复命令以及备份出来的 tar 文件放哪。如果你是 Docker 方式部署的 GitLab这是社区版最常见的部署形态备份操作要通过容器执行# 在宿主机执行容器名通常叫 gitlab docker exec -t gitlab gitlab-backup create # 同时备份配置文件 /etc/gitlab/gitlab.rb 和 gitlab-secrets.json # 这两个文件决定了备份包能不能被识别 docker cp gitlab:/etc/gitlab/gitlab.rb /backup/gitlab.rb docker cp gitlab:/etc/gitlab/gitlab-secrets.json /backup/gitlab-secrets.json备份文件会生成在容器内的/var/opt/gitlab/backups/目录文件名类似1700000000_2024_01_01_16.3.5_gitlab_backup.tar。注意gitlab-backup create这个命令不会自动备份gitlab.rb和gitlab-secrets.json这两个文件包含了数据库加密密钥缺失的话恢复出来的仓库数据根本解不了密。这是 GitLab 备份最容易被忽略的一步。恢复时要保证新实例的 GitLab 版本和备份时一致然后把备份 tar 文件放进备份目录执行# 在容器内执行 docker exec -it gitlab bash # 先停止相关服务防止数据写入 gitlab-ctl stop puma gitlab-ctl stop sidekiq # 确认备份文件在 /var/opt/gitlab/backups/ 下 gitlab-backup restore BACKUP1700000000_2024_01_01_16.3.5 # 恢复配置和密钥文件后重启 gitlab-ctl reconfigure gitlab-ctl restartBACKUP参数只填时间戳那部分不要带.tar后缀和_gitlab_backup字面量。这一步写错的话命令会报找不到备份文件。恢复过程中如果出现权限错误多半是容器内用户和备份文件属主不一致chown -R git:git /var/opt/gitlab/backups/能解决。4.3 权限模型五个角色的边界别搞混GitLab 的权限模型是五级Guest、Reporter、Developer、Maintainer、Owner。手册里这一节不需要把官方文档搬过来只需要画两笔Guest 能看 issue 和 MR 里的讨论但不能看代码仓库内容Reporter 能看代码、能拉取仓库但不能推送Developer 能推送分支、能操作非保护分支上的合并这是日常开发的主力角色Maintainer 能合并受保护分支、能修改项目设置但不一定能删除项目Owner 拥有项目的全部权限包括转移和删除项目。权限设计上最常见的做法是公司内部项目给开发者Developer外包或临时协作者给ReporterCI 机器人比如发布用的 GitLab Runner 的 token 关联账号只给必要的最小权限。运维和 team leader 给Maintainer只有极少数人拥有Owner。有一个细节值得写在手册里Maintainer不能删除受保护分支。如果你要强推git push --force被拒绝提示You are not allowed to force push code to a protected branch on this project先别急着找管理员申诉去Settings - Repository - Protected branches里看这个分支是否设置了Allowed to force push默认是关闭的。5. GitLab 手册里没写透的 5 个坑从 API 报错到仓库瘦身5.1 python-gitlab 报 login failedCheck API Token or GitLab Version现象用 python-gitlab 库写脚本时明明复制了正确的 Personal Access Token调用gl.projects.list()却抛异常报错信息片段是login failed. check api token or gitlab version. log in via git if the versi。原因python-gitlab 从 3.x 升到 4.x 后构造函数里对api_version参数做了更严格的校验。你传入的 GitLab 实例版本高于库默认支持的版本时库会警告但不一定报错真正报错多是自己拼 URL 时少了api/v4段或者 token 的 scope 里没勾api权限。解决先在页面上重新生成 tokenscope 勾上api然后在代码里显式指定版本import gitlab gl gitlab.Gitlab( https://gitlab.company.com, private_tokenglpat-xxx, api_version4 ) # 验证连通性 gl.auth() print(gl.user.username)gl.auth()会发一个轻量的验证请求如果这个调用通过了但业务请求还报错就去看 URL 拼接。很多脚本挂掉是因为用了http://而 GitLab 实例做了 HTTPS 跳转库拿到的响应不是 JSON 就报登录失败。5.2 Docker 部署的 GitLab 内存占用过高小机器直接卡死现象一台 4GB 内存的云主机Docker 启动 GitLab 之后free -h看到内存吃掉 3.5GB再跑一个构建任务整机直接无响应。原因GitLab 全家桶nginx、puma、sidekiq、postgresql、redis默认配置是为 8GB 以上内存的机器设计的。Puma 默认开多个 worker每个 worker 都是 Ruby 进程内存轻松吃掉几百 MB。解决至少在gitlab.rb里调整三处再启动# /etc/gitlab/gitlab.rb # 关闭不需要的监控组件 prometheus_monitoring[enable] false # 限制 puma worker 数量和线程数 puma[worker_processes] 2 puma[min_threads] 1 puma[max_threads] 4 # 限制 sidekiq 并发 sidekiq[max_concurrency] 5改完执行gitlab-ctl reconfigure再gitlab-ctl restart内存能压到 1.5GB 左右。这套配置适合 20 人以内的小团队如果公司规模更大就该考虑给 GitLab 单独一台机器或买官方的付费方案靠压配置撑不住。5.3 仓库 .pack 文件膨胀到几个 GB克隆越来越慢现象git clone一个仓库要十几分钟仓库目录里.git/objects/pack/*.pack文件有 3~4GB拉下来的代码本身只有 100MB。原因有人把构建产物、IDE 配置、大的二进制文件直接提交进了 Git 历史。Git 保存的是完整历史哪怕后来删除了大文件它依然躺在历史里。git filter-branch或git-filter-repo可以重写历史、物理删除这些文件。解决步骤在新副本上操作不要直接动原仓库# 安装 git-filter-repo然后删除所有历史提交中的 .zip 文件 git filter-repo --path-glob *.zip --invert-paths # 把重写后的历史强推到远程注意这会改写所有协作者的分支 git remote add origin gitgitlab.company.com:group/repo.git git push --force --all git push --force --tags--force --all会覆盖远程所有分支的引用协作成员必须重新克隆或者用git pull --rebase对齐否则他们会把旧历史重新推回去等于白做。之后再跑一遍git gc --prunenow让本地对象库瘦身。这是 GitLab 运维里最麻烦的维护操作之一手册里应该放一个「禁止提交这些类型文件」的清单从源头预防。5.4 删除仓库后想找回管理员也没有后悔药现象有同事在项目设置里点了几下项目整个消失了。找管理员求助管理员在 Admin Area 的 Project 列表里也找不到已经删除的项目。原因GitLab 项目删除后会进「延迟删除」状态默认保留 60 天管理员可以在Admin Area - Settings - General - Deleted projects里调整保留天数。超过这个时间后项目连同 Git 对象和关联的数据库记录一并清理不存在「回收站」概念。解决如果删除时间在保留期内管理员可以登录 GitLab 控制台调用恢复接口。另一种方式是从已恢复的备份包中重建这依赖于定期备份是否做到了异地保存。作为一个真实教训把删除项目的权限收紧到 Owner 一级并在手册里明确写「项目删除是不可逆操作误删后 48 小时内可以尝试从备份恢复超过 48 小时只能靠备份时效兜底」。5.5 分支保护设置过严Developer 推不动 main 分支引发连锁卡顿现象开发者完成了功能开发在 MR 里点了 Merge 按钮提示 401 或有权限报错去问管理员管理员说 MR 没问题是分支保护设置不对。原因项目初始化时默认把 main 设成了受保护分支。但 GitLab 的「受保护」有细粒度区分——Allowed to merge和Allowed to push是两组独立的权限开关。如果项目里只有一条 main 分支、所有开发都在 main 上进行保护策略设置成 Developer 禁止推送整个流程就会卡在「谁也没权限合并」的僵局里。解决在Settings - Repository - Protected branches里确认Allowed to merge至少是 DevelopersAllowed to push也至少是 Developers。很多追求敏捷的小团队直接把 main 设置为Allowed to push和Allowed to merge都是 Developers取消强制 MR让 CI 和 code review 变成约定而不是强约束这种方式在小团队里效率更高但规范必须写进团队开发流程文档否则代码质量会不可控。6. 让手册跟上 GitLab 的版本节奏维护与迭代技巧6.1 一个快速验证技巧用 rails console 直接查后台数据手册维护者通常是管理员或团队 leader经常需要快速确认某个用户、某个项目的状态。与其在页面上翻半天不如直接进控制台# 在 Docker 容器内执行进入 rails 控制台 docker exec -it gitlab gitlab-rails console # 查看用户状态 user User.find_by_username(zhangsan) puts user.state # 可选值active / blocked / pending / ldap_blocked # 查看项目是否被标记为 deleted Project.find_by_full_path(group/project).marked_for_deletion?这个技巧能帮你快速判断注册审批是否卡住、用户是否被误封、项目是否在延迟删除期内。手册里不必写多管理员知道这三个命令就能排查 80% 的日常异常。6.2 从 issue 到文档让排障记录自动沉淀进 v3手册 v2 发布之后最怕的就是回到 v1 的老路——写完就没人管了。我习惯的做法是在 GitLab 里建一个专门的文档维护 issue 模板团队里任何人在使用 GitLab 时踩了坑、找到了解决办法就按模板提交一个 issue标签设为docs。每一个季度花一个下午把积攒的 issue 筛一遍把有价值的内容合并进手册对应章节。这个流程跑起来之后手册就不再是「某个人写的文档」而是「团队共同维护的知识库」。我在 v2 手册的结尾处会留一节「如何反馈问题」写清楚四件事找哪个 issue 模板、标签是什么、改文档需要谁 review、发布 PDF 的流程是什么。v3 的素材就藏在这些 issue 里。最后留一个自己踩出来的习惯每次升级 GitLab 版本之前先翻一遍手册里提到路径的部分因为 GitLab 的 UI 路径经常在 Minor 版本里就变了。社区版 16.x 和 17.x 之间不少功能从「项目设置」迁移到了「侧边栏新的中心化入口」照着 v2 手册走但找不到菜单的时候先别急着改手册确认一下是不是版本差异。这个细节让我少走了很多弯路希望帮到你。本文还有配套的精品资源点击获取
