简介GitLab用户手册v2.pdf是一份面向Git初学者及企业内部开发团队的技术资料以基于Web的Git仓库管理器GitLab为核心系统梳理了从客户端安装到项目协作管理的完整流程。文档第一步指导读者在Windows环境下载并安装Git打开Git Bash后通过git config命令配置全局用户名和用户邮箱随后演示生成SSH密钥、将公钥导入GitLab服务器的具体方法包括首次登录修改初始密码、点击右上角Profile Setting菜单、进入SSH Keys页面添加新密钥等细节确保本机与服务器之间的访问安全可靠。在掌握这些准备工作后手册继续介绍创建与克隆项目、查看提交历史、管理分支与版本等基本操作并延伸讲解CI/CD持续集成管道、代码Review、项目权限管理等高阶功能帮助读者从个人使用平滑过渡到团队协作场景。资源以单个PDF文档形式提供体积仅1.04MB操作步骤清晰、界面指引直观适合作为随身查阅的手册。该手册已有538人学习下载适合想快速上手GitLab的开发者和运维人员参考。1. 内网 GitLab 用户手册 v2.pdf把「配环境」这件事一次性讲透这份 GitLab 用户手册 v2.pdf解决的是内网 GitLab 最普适的一类问题拿到账号之后怎么从零把本地 Git 环境串起来。我见过太多同事卡在同一个位置上——Git 装了仓库地址也拿到了但 push 的时候反复要密码或者 IDE 里报错最后排查下来是 SSH key 没进 GitLab。这份手册把「装 Git → 配身份 → 生成 SSH key → 导入 GitLab → 拉代码」五步走完每一步都有截图和命令对照适合刚从 SVN、Perforce 转过来的工程师也适合要给团队批量搭环境的师兄师姐。核心就一句话命令可以不用全懂但执行顺序和 key 文件位置不能错。2. 环境搭建Git 客户端安装与用户身份配置大多数 GitLab 使用教程都把「环境搭建」放在第一步但恰恰这个环节最容易出问题。很多人以为装了图形客户端就算有 Git 了结果 IDEA 里 Git 菜单是灰的PyCharm 里 push 报错最后发现是 git.exe 根本不在系统 PATH 里。手册的第一部分就是标准解法官方安装包装完验证配置身份再做任何仓库操作。2.1 下载 Git for Windows安装选项里最关键的 PATH 设置手册给出的下载地址是 https://git-for-windows.github.io现在打开会自动跳到 Git for Windows 的最新发布页。安装包是 64 位的 Git-x.x.x-64-bit.exe官方包的优点是把 Git Bash、Git GUI、ssh 客户端一起打包后面生成 SSH key 不需要额外装任何组件。安装过程大部分页面可以直接 Next但有两步要停下来手动确认。第一步是 Choosing the PATH environment一定要选第二项「Git from the command line and also from 3rd-party software」。这一项会把 git.exe 写入系统 PATH之后 IDEA、PyCharm、VSCode 才能在设置里自动识别 Git 可执行文件。如果选了第一项「仅从 Git Bash 使用 Git」命令行能跑但 IDE 里经常会显示找不到 Git。第二步是 Configuring the line ending conversions建议选「Checkout as-is, commit as-is」。这一点是 Windows 上很常见的坑如果选了 Checkout Windows-style, commit Unix-style那么项目里的 shell 脚本、Makefile 都会在 checkout 时被改成 CRLF提交到 GitLab 后 Linux 环境跑起来各种报错。选 as-is 最省心这是我在 Windows 上做开发这些年攒下的血泪经验尤其多人协作的项目里这个选项不一致会导致 diff 里全是换行符变化非常干扰 review。装完验证一下git --version看到git version 2.4x.x就说明安装成功。如果提示找不到命令多半是装的时候 PATH 选错了重装一次或者手动把C:\Program Files\Git\bin加进系统环境变量。加完环境变量窗口不会自动刷新要重新打开 Git Bash 才生效。另外提醒一句Windows 上有时会同时存在多个 Git 版本比如某些软件内置了 Git用where git可以看实际调用的路径避免 IDE 和命令行指向不同版本。2.2 配置全局 user.name 和 user.email提交记录的身份证安装完成后第一件事不是拿地址去 clone而是先告诉 Git 你是谁。在 Git Bash 里执行手册里这两条命令git config --global user.name yourname git config --global user.email emailexample.com这两条命令把身份写进用户目录下的.gitconfig文件以后本机所有仓库的 commit 都会带上这两个字段。参数说明--global表示对当前 Windows 用户全局生效不加的话只对当前仓库生效user.name填你常用的显示名user.email一定要用 GitLab 里注册过的邮箱。邮箱不匹配的后果是提交记录推上 GitLab 后不关联你的账号头像Merge Request 里显示的是「未知作者」查代码历史的时候很难定位责任人这种问题在团队审计时非常尴尬。配置完可以用下面的命令确认生效git config --list --show-origin输出里能看到每条配置来自哪个文件。如果团队内不同项目要求不同身份在某个仓库目录下去掉--global再执行一次仓库级配置会覆盖全局配置这个优先级顺序要记住。这里还有一个常见场景明明配置了user.name换一个新克隆的仓库一 commit 还是提示Please tell me who you are。原因往往是配置时所在的仓库不在当前目录或者在某个仓库里执行了不带--global的配置只对该仓库生效。解决统一补一次全局配置再用git config --list确认当前目录下实际生效的配置不要反复重装 Git问题不在安装上。2.3 Git CLI 与图形客户端的选择为什么这条链路现在必须走 CLI这份手册全篇用 Git Bash 而不是 TortoiseGit、SourceTree不是没有原因的。GitLab 上的操作记录、CI 触发条件、分支合并规则都基于 Git 命令行行为图形客户端只是二次封装遇到问题很难定位。我记得有一次同事在 TortoiseGit 里提交后 push 一直失败切到命令行一看是远端地址里少了斜杠这种黑匣子问题在纯 GUI 下特别难查。另外 GitLab 官方也提供了 glab 这个命令行工具可以直接在终端创建 MR、查看流水线、操作 issue相当于把 GitLab 网页操作搬进终端。glab 的安装方式很简单直接去项目 Releases 页拿对应平台的包解压后加进 PATH 即可但它依赖本机已经装好 Git。所以先按这一章把 Git CLI 链路走通后面无论是进 IDE 还是写脚本都是同一套底层命令。Git Bash 本身也有一点要适应它模拟的是 Linux shell路径用/c/Users/用户名/这种写法而不是C:\Users\用户名\。~就代表当前用户的主目录也就是.ssh、.gitconfig所在的目录。命令行里的路径和 Windows 资源管理器里的路径不是一回事但绝大多数命令不需要手写完整路径用~就行。3. SSH key 生成与导入让 GitLab 认识你的电脑这一步可以说是 GitLab 使用教程里最容易翻车的环节。很多人第一次接触 SSH key不知道「公钥给服务器、私钥留本地」这个基本逻辑导致把私钥直接贴到 GitLab 页面上或者复制公钥时多带了换行符连接时各种玄学报错。这份手册用一步一图的方式把这一步讲得很细我在这里补充一些命令参数和排查经验。3.1 用 ssh-keygen 生成密钥命令参数与保存路径手册里的命令是ssh-keygen -t rsa -C lijianyu_alice163.com我实际用的时候会多带一个-b 4096ssh-keygen -t rsa -b 4096 -C lijianyu_alice163.com参数说明-t rsa指定密钥算法为 RSA兼容性最好GitLab 各版本都认-b 4096指密钥长度为 4096 位安全强度比默认的 2048 更高代价只是加解密多几毫秒可以忽略-C是注释习惯性填邮箱这个字符串会出现在 id_rsa.pub 的末尾在 GitLab 页面上辨别是哪台机器非常有用。命令里的邮箱直接换成你自己的手册示例只是演示。执行后终端会依次问三个问题保存路径、密码短语、确认密码短语。保存路径默认是/c/Users/你的用户名/.ssh/id_rsa直接回车用默认。如果提示该文件已存在会问是否覆盖输入 y 之前一定要想清楚旧 key 可能已经配置在 GitLab 或其他服务器上覆盖之后那些地方全部失效。新入职的机器一般直接覆盖没问题生产环境机器千万别手滑。第三个问题是密码短语这是很多人纠结的点。这个短语相当于私钥的第二道锁就算私钥文件被拷走没有短语也解不开。可以不设直接回车跳过但公司配的笔记本我建议设一下。设了之后每次 SSH 连接都要输一次可以用 ssh-agent 缓存命令是eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa这段的作用是把私钥加载到内存中的 agent后面一段时间内的 SSH 操作免输短语。注意 Git Bash 默认不会自动启动 agent每次新开会话要重新执行这两行。如果完全不想输入在生成时空掉短语也可以但你要接受私钥泄露等于账号沦陷的风险。3.2 把公钥导入 GitLabProfile Setting 里的正确入口生成完成后~/.ssh目录下会有两个文件id_rsa是私钥id_rsa.pub是公钥。别人要的是公钥私钥绝对不要出现在聊天记录、代码仓库和 GitLab 页面上。先查看公钥内容cat ~/.ssh/id_rsa.pub输出是一行很长的字符串以ssh-rsa开头结尾是你的邮箱。复制的时候整行复制开头不要多空格结尾不要带换行。很多 Permission denied 问题就出在复制时把换行符也带进去了GitLab 会把换行解析成 key 的一部分导致验签失败。Windows 下复制终端内容时建议选中后直接 CtrlInsert 复制避免鼠标操作多选到换行。接下来打开浏览器访问http://10.10.169.27/用管理员分配的账号登录。第一次登录会强制修改初始密码这个密码只有你知道改完记得马上重新登录。登录后点右上角头像下拉框选择 Profile Setting——老版本界面是这个叫法新版本显示 Edit profile 或 Preferences入口位置不同但功能一致。进入后在左侧菜单或顶部 Tab 里找「SSH Keys」中文界面叫「SSH 密钥」。Title 填一个能记住的设备名比如 ThinkPad-T14Key 粘贴刚才复制的公钥Expiration 可选一般本地开发机不用设过期。填完点 Add SSH Key列表里出现一条以ssh-rsa开头的记录就说明导入成功。导入后建议第一时间验证ssh -T git10.10.169.27第一次连接会提示不认识这台主机输入 yes 确认指纹并缓存到 known_hosts。如果配置正确终端会输出Welcome to GitLab, 你的用户名!。看到这句话SSH key 环节就闭环了。如果报错不用反复试直接翻第 5 章的排查表对号入座。3.3 替换 IDE 自带 SSH keyMyEclipse 与 Eclipse 系的 ssh2 配置手册里专门有一段处理 MyEclipse 的截图操作把 MyEclipse 自动生成的 sshkey 改成刚才生成的删掉 id_dsa把 ssh2home 换成新 key 的目录。这段背景是 Eclipse 系 IDE 内置了自己的 SSH2 实现不完全读取系统~/.ssh而是维护一份独立列表所以就算命令行 SSH 已经通了Eclipse 里提交照样认证失败。操作路径Window - Preferences - 搜索 SSH2进入 General 页。第一项 SSH2 home 默认可能指向旧路径改成C:\Users\你的用户名\.ssh。下面 Private keys 列表把旧的 id_dsa、id_rsa 全部 Remove然后 Add 加入新生成的id_rsa文件。保存后重启 IDE再用 Team - Git 操作就不会去撞旧 key 了。IDEA 系不需要这一步因为 IDEA 默认走系统 SSH 配置但也正因如此如果你的系统 .ssh 目录里私钥文件名不是 id_rsa记得在 ~/.ssh/config 里配 IdentityFile 指定。4. 从 GitLab 克隆工程到本地IDEA、PyCharm 与 VSCode 的导入细节环境通了、key 也认了接下来就是把 GitLab 上的工程弄到本地。这里分别说命令行和三种最常见的开发环境VSCode 提示 Git not found、IDEA 插件登录失败、PyCharm push 权限不足三个问题症状不一样处理方式也完全不同。4.1 仓库地址选择与 git clone 的正确姿势GitLab 项目首页右上角有一个蓝色 Clone 按钮点开会出现两个地址SSH 和 HTTP。两者的区别见下表地址类型形如认证方式日常体验SSHgit10.10.169.27:group/project.gitSSH key一次配置后续免密HTTPhttp://10.10.169.27/group/project.git账号密码或访问令牌每次要认证容易被旧凭据干扰我的习惯是能用 SSH 就不用 HTTP。HTTP 方式在 Windows 上的凭据缓存问题特别多而且账号一旦开启两步验证普通密码就会失效只能靠个人访问令牌顶着绕了一圈还是回到密钥。第 6 章会专门讲访问令牌。命令行克隆的方式cd /d/workspace git clone git10.10.169.27:group/yourproject.git cd yourproject git status逻辑说明git clone会在当前目录创建仓库文件夹把远程默认分支拉下来并建立跟踪关系git status检查工作区状态正常会显示在On branch master/main且工作区干净。地址里的 group 是项目所属分组不要手敲地址直接从页面复制少一个斜杠都会报Repository not found——而这个报错在 GitLab 里也经常被误读成权限问题。4.2 IDEA 与 PyCharm识别 Git 可执行文件与提交套路IDEA 和 PyCharm 都是 JetBrains 系Git 集成逻辑一样。如果你打开 File - New - Project from Version Control粘贴地址后提示Git executable not found第一反应不是换下载地址而是检查 Settings/Preferences - Version Control - Git 里的 Path to Git executable。Windows 默认位置在C:\Program Files\Git\bin\git.exe手动指过去就能解决。提交代码的正确姿势我建议先建分支再改代码git checkout -b feature/login这条命令从当前分支切到新分支 feature/login等价于同时执行git branch和git checkout。在 IDE 里提交的时候Commit 窗格会列出所有改动填提交信息后 Commit 和 Push 是分开的两个按钮。第一次 Push 会要求选择远端选 origin 即可。PyCharm 里指向同一套远端没有额外配置。如果 Push 报You are not allowed to push code to protected branches说明 master 是被保护的分支你的角色是 Developer 而不是 Maintainer正确做法是把改动留在功能分支去 GitLab 页面发起 Merge Request走代码评审合并。4.3 VSCode 里克隆和提交轻量级的另一套流程VSCode 用户更常遇到的问题是「GitLab 的工程怎么下到 VSCode 里」。答案不是下载而是用 Git 克隆。按 CtrlShiftP 打开命令面板输入 Git: Clone粘贴仓库地址选择一个本地目录VSCode 会自动打开克隆下来的文件夹。提交的路径是源代码管理面板 - 修改文件后的「」号暂存 - 输入提交信息 - 点「√」提交 - 点「同步更改」推送。如果 VSCode 提示找不到 Git可以在 settings.json 里指定{ git.path: C:/Program Files/Git/bin/git.exe }参数说明git.path是 VSCode Git 扩展的可执行文件路径Windows 下建议用正斜杠避免C:\Program Files里的反斜杠被 JSON 转义成别的路径。配置完需要重启 VSCode。VSCode 的 Git 提交是基于 Git CLI 的所以第 2 章 PATH 配置没做好这里一定会出错这也是很多人忽略的依赖关系。4.4 分支、权限与提交信息的边界GitLab 的成员角色分为 Guest、Reporter、Developer、Maintainer、Owner落在仓库上的具体动作权限不同。Developer 能推送功能分支、创建 MR但不一定能推 master/main。团队里经常问「GitLab Developer 可以提交代码到 master 吗」标准答案是看分支保护设置受保护分支不允许非 Maintainer 直接 push强行 push 会收到上面的英文报错。所以团队协作的常规路径是功能分支 Merge Request Code Review这也是 GitLab 高级操作里最核心的一环。提交信息方面项目 README 或 CONTRIBUTING 里如果有模板就照模板写常见的feat: 描述、fix: 描述格式能被 MR 标题自动归纳对后面查历史有很大帮助。5. GitLab 使用避坑版本兼容、SSH 连接与认证失败排查这一章把前面每一步可能踩到的问题集中列出来每条都是真实环境里发生过的。我在团队里做 Git 支持时收到的求助里八成就是下面这几类按现象、原因、解决的顺序写方便直接对号入座。5.1 IDEA 登录 GitLab 报 login failed提示 14.0 版本不支持现象在 IDEA 或 PyCharm 里想通过 GitLab 插件登录仓库弹窗提示login failed. gitlab versions older than 14.0 are not supported. log in via git if the version is older账号密码明明正确也进不去。原因JetBrains 新版 IDE 的 GitLab 插件对服务器 API 版本有硬性要求GitLab 版本低于 14.0 时走老接口的登录会被插件主动拒绝。公司内网如果一直沿用旧版本这个报错就会复现。类似报错还有login failed. check api token or gitlab version本质都是版本或 token 认证问题。解决不要和插件较劲。最省事的办法是绕开 IDE 内置登录用命令行git clone把仓库拉到本地然后用 IDEA 的 Open 打开本地目录日常提交推送完全不受影响。报错信息里那句 log in via git就是在提示你换命令行方式。如果确实需要在 IDE 里操作远端可以用 HTTP 地址加个人访问令牌在远端配置里认证但老版本 GitLab 对 token 的支持也需要确认命令行始终是兜底方案。5.2 SSH key 已添加但 clone 提示 Permission denied (publickey)现象GitLab 页面的 SSH Keys 列表里能看到刚添加的公钥执行ssh -T git10.10.169.27却返回Permission denied (publickey)clone 仓库自然也是同样报错。原因绝大多数不是服务器没收到 key而是本地 ssh-agent 没加载私钥或者公钥内容复制时带了换行再或者 Git 默认读取的私钥文件名不是 id_rsa。解决先跑一次诊断命令ssh -T git10.10.169.27 -v-v参数会打印完整握手过程重点看输出里Offering public key之后跟的是哪个文件路径。如果显示 no such file说明 Git 没找到你的私钥。按顺序检查公钥文件末尾是不是完整的邮箱、没有空行私钥名字是不是 id_rsa如果自定义过文件名在~/.ssh/config加上 IdentityFile 指定路径。如果是 agent 没加载执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa再试一次。这条命令的eval负责把 agent 的环境变量注入当前 shellssh-add把私钥读入内存。同一个 Git Bash 会话里只需要跑一次重新开会话要再执行。5.3 HTTP 方式反复要求密码Windows 凭据管理器里全是旧账现象用http://10.10.169.27/...地址 clone 的仓库push 时一直弹认证窗口输对密码也不行换一台电脑克隆也拉不下来。原因HTTP 模式下 Git 会调用 Windows 凭据管理器缓存认证信息如果第一次输错了密码或者 GitLab 账号改过密码、开了两步验证缓存里的旧凭据就会一直留着导致每次都在拿旧凭据撞服务器。解决两条路。一条是彻底换掉远端地址git remote set-url origin git10.10.169.27:group/yourproject.gitset-url只改当前仓库的远端地址不影响其他仓库。改完再git push就直接走 SSH key 了。另一条是如果没法用 SSH就在控制面板 - 凭据管理器 - Windows 凭据里找到git:http://10.10.169.27这条删掉然后重新 push让 Git 弹窗输入新密码或访问令牌。5.4 用 Docker 自建 GitLab 一直 502端口、内存与初始化时间现象用docker run起 GitLab 容器浏览器访问映射端口一直 502等半小时还是这个状态。原因GitLab 是全家桶式架构内部有 Nginx、PostgreSQL、Redis、Sidekiq 等一整套进程首次启动重新配置的时间常常超过五分钟502 期间是正常现象。另一个高频原因是宿主机 80 端口和 22 端口被其他服务占用容器启动异常但从docker ps看容器又确实存在特别容易误判。解决改端口映射把宿主机端口换成不冲突的docker run -d --name gitlab -p 8080:80 -p 8022:22 \ -v /srv/gitlab/config:/etc/gitlab \ -v /srv/gitlab/logs:/var/log/gitlab \ -v /srv/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce参数说明-p 8080:80把容器的 80 端口映射到宿主机 8080访问地址变成http://服务器IP:8080-p 8022:22给 SSH 通道换端口后面 clone 地址要写成ssh://git服务器IP:8022/group/project.git。三个-v卷映射不能少否则容器删了数据全丢。启动后看日志docker logs -f gitlab滚动输出里出现GitLab is up!或gitlab Reconfigured!再访问。这一步对应很多自建 GitLab 教程里「Ubuntu GitLab 更改 80 端口号」的问题本质都是端口冲突或初始化没等完。5.5 GitLab 高危漏洞与升级别等爆出来再补后悔药现象收到安全通告说当前 GitLab 版本存在未修复高危漏洞要求尽快处置。原因GitLab 每月都有安全更新老版本在 Web 前端、API 层都有已知漏洞暴露面且通常没有自动化修复手段只能升级或打补丁。解决普通开发者此刻能做的很有限最实际的是轮换自己的 SSH key 和密码把本机私钥重新生成一次降低信息泄露窗口。管理员侧的升级要按官方 upgrade path 来比如 13.x 只能先升到 13.12再升 14.x跨大版本直接升极容易起不来。升级前必须备份GitLab 自带备份命令gitlab-backup create这条命令在 GitLab 服务器上执行会把 Git 仓库、数据库、上传目录打包到备份目录。备份属于后悔药宁可每次升级前都拍一张也别赌它不出问题。升级之后记得让团队重新验证一次ssh -T git...某些大版本升级会重建 SSH 相关配置key 本身不会失效但 known_hosts 指纹会变新的报错提示容易让人误以为是密钥坏了。6. GitLab 访问令牌与 CI 流水线两个能直接提效的进阶点如果前面的链路都通了日常工作基本够用。但 GitLab 的价值不在「能拉代码」而在它把代码托管、权限、评审、自动化构建都拢到了一起。这一章挑两个最有性价比的进阶动作个人访问令牌和最小化 CI 配置。6.1 个人访问令牌HTTP 提交的临时密码在 GitLab 右上角头像 - Edit profile / Preferences - Access Tokens访问令牌页面Name 填 git-tokenScope 按需勾选read_repository、write_repository或api点击创建后页面会展示一次 token 字符串。它只在生成后展示一次关掉页面就再也看不见丢了只能重新建。token 的使用场景很直接用 HTTP 地址 clone 时git 提示输入密码把 token 粘进去而不是登录密码。它在 IDEA、VSCode 的远端认证里同样生效适合不方便配 SSH key 的临时环境。注意 token 有权限范围和有效期临时用完了可以回页面 revoke比改密码快。6.2 一条能跑的 .gitlab-ci.ymlCI/CD 的入口是仓库根目录下放一个.gitlab-ci.yml。推送到 GitLab 后只要项目里有可用的 Runner流水线就会按文件定义执行。最小示例stages: - test unit-test: stage: test script: - echo running unit tests only: - merge_requests逻辑说明stages声明流水线的阶段这里只有 testunit-test是一个 jobscript是阶段内要执行的命令only控制触发条件这里限制为只有 Merge Request 事件才跑。注意 YAML 里缩进必须是空格不能是 Tab更不能把stages拼成stage。这个文件加上去之后每次提交 MR 都会自动触发流水线日志可以在 GitLab 项目页 CI/CD - Pipelines 里看这一步基本就能覆盖「GitLab CI 怎么用」的疑问。我自己带人的习惯是新同事入职第一周强制走一遍第 2 章到第 4 章的空仓库链路装 Git、配 config、生成 key、导入 GitLab、clone 验证哪一步卡住就去查第 5 章的对应条目。访问令牌和 SSH key 不要混用一个走 HTTP 一个走 SSH这种混用引起的凭据错乱我见过太多次。这份 gitlab用户手册v2.pdf 里每一步都有截图对照配合上面的命令和参数说明从零走一遍基本不会栽。希望帮到你。本文还有配套的精品资源点击获取