简介《GitLab用户手册v2.pdf》是一份面向Git初学者与团队协作开发者的实操型技术手册聚焦如何在企业内网环境下快速搭建GitLab使用环境并管理代码仓库。手册从Git客户端下载安装、全局用户名与邮箱配置讲起逐步演示SSH密钥的生成、导入到GitLab服务器的完整流程解决初学者最常见的认证配置问题随后覆盖仓库创建、克隆、提交记录查看等基础操作并延伸到CI/CD流水线、代码审查与权限管理等进阶能力帮助读者从日常使用走向团队规范化管理。整个资源为单个PDF文件大小仅1.04MB内容紧凑、图文步骤清晰适合随时查阅书中以步骤截图和命令示例为主跟随操作即可完成环境配置与日常开发。目前已有537人学习下载对于希望系统掌握GitLab操作、规避常见配置坑位的开发者来说是一份轻量实用的快速上手资料。1. GitLab 用户手册 v2从装 Git 到导公钥的完整链路GitLab 用户手册 v2 这份 PDF 解决的不是 Git 怎么提交代码而是很多团队 onboarding 里最容易卡住新人的环节从零开始装 Git、配全局身份、生成 SSH 密钥、把公钥导进 GitLab 服务器。手册对应的内网地址是 http://10.10.169.27/说明它是给内部团队用的实操文档不是官方文档的翻译。我刚拿到手时觉得步骤太细等真的按顺序走完才发现每一步都是必要的——尤其是 ssh-keygen 生成密钥后那段「删掉 id_dsa、替换 SSH2 Home 目录」的操作是网上零散教程根本不会提的。这份手册适合刚入职要连公司 GitLab 的新人也适合要写团队 Git 使用规范的人拿去做底稿。2. 环境搭建与用户配置安装向导的四个关键选项和全局身份2.1 为什么先装 Git 客户端GitLab 是服务端Git 是客户端这个边界别混GitLab 的 Web 界面负责管仓库、管权限、管合并请求但真正把代码推上去的动作还是得靠本机的 Git 命令完成。手册第一步不是打开 GitLab 网页注册账号而是先把 Git 客户端装好原因就在这里没有本机 Git后面所有 clone、commit、push 都是空话。Windows 环境下最通用的方案是 Git for Windows。它以 MSYS2 环境为基础打包会在开始菜单里生成 Git Bash、Git CMD、Git GUI 三个入口。Git Bash 提供一个类 Linux 的终端能在 Windows 上使用 ls、cat、ssh-keygen 这类命令对不熟悉 cmd 的新人非常友好Git CMD 则是把 Git 注入原生 cmd。我一般建议新人统一用 Git Bash因为后续生成密钥、查看公钥、测试 SSH 连接全在这个终端里完成工具链一致能少踩很多坑。有一点容易被人忽略Git for Windows 安装包自带 SSH 客户端和 ssh-keygen 工具所以装完 Git生成 SSH 密钥的原材料就齐了。这也是手册把「安装 Git」和「生成 SSH key」放在连续两章的原因。而且安装包里的 OpenSSH 与 Git 是同一套工具链不会出现 Git 认一套 SSH、ssh-keygen 生成另一套密钥的错位问题。2.2 安装向导里的四个关键选项PATH、编辑器、组件和行尾处理下载地址是 https://git-for-windows.github.io 页面会跳转到 Git for Windows 的官方发布页下载 exe 安装包后双击运行。安装向导大部分步骤直接 Next 就行但有四个选项建议动手改一下或者确认默认值否则后面大概率要返工。安装步骤推荐选择说明Select Components保持默认组件里包含 Git Bash、Git GUI、OpenSSH缺了哪个后面都要补装Default editor换成 VSCode 或 Notepad默认 Vim 会把新人卡在 commit 信息编辑界面出不来Adjusting your PATHUse Git from the command line...让 cmd 和 IDE 终端也能直接调用 git 命令Configuring line ending conversionsCheckout as-is, commit as-is避免团队里 Windows 与 Linux 互相改写行尾提交 diff 变成一片红装完之后打开 Git Bash执行下面这条命令确认环境就绪# 验证 Git 是否安装成功有版本输出即正常 git --version正常会输出类似 git version 2.x.windows.1 的结果x 是具体版本号。如果提示 command not found问题基本出在 PATH 那一项不用卸载重装重新运行安装包安装程序会进入维护模式修改 PATH 选项后完成即可。判断标准是任意目录下都能直接敲 git而不是只能在 Git Bash 里用。提示Default editor 这个选项很多人不看等第一次 git commit 弹出 Vim 时才发现进退两难。改编辑器是最高性价比的后悔药。2.3 全局用户名和邮箱git config 两条命令与三个常见误区安装完成后手册进入用户配置阶段。打开 Git Bash 执行# 配置全局用户名提交记录里的显示名 git config --global user.name yourname # 配置全局用户邮箱GitLab 按它归属提交记录 git config --global user.email emailexample.com # 查看当前已生效的全局配置 git config --global --listuser.name 是提交时显示的作者名user.email 是关键——GitLab 的提交记录、代码量统计、注释率统计都按邮箱归属账号。--global 表示配置写入当前用户主目录下的 .gitconfig对所有仓库生效。这里有三件事容易踩坑。第一用户名不建议填中文和带空格的特殊字符。Git 本身不拒绝但提交记录在部分 GitLab 版本 Web 渲染下可能出现显示异常统一用英文拼音加分隔符最省心。第二邮箱必须和 GitLab 注册邮箱一致否则你推上去的提交在网页端显示为「无名氏」仓库统计里你的贡献全部掉线等月底看报表才发现数据对不上。第三--global 不是必须的如果你同时维护公司项目和个人项目建议在公司仓库里去掉 --global 只对本仓库配置避免个人邮箱串到公司提交里。提示跑完两条配置命令后立刻 git config --global --list 复核一遍再继续。这个检查十秒钟能省掉后面排查提交归属问题的一小时。3. 生成 SSH 密钥对ssh-keygen 三个交互提问与密钥落点3.1 为什么 GitLab 更愿意用 SSH从免密到审计的一次性投入配置完用户信息手册进入 SSH 密钥生成环节。新人的第一反应通常是网页登录都用密码了为什么 Git 命令还要再搞一串密钥原因是 Git 命令走 SSH 协议与 Web 登录是两套认证体系。Web 登录靠账号密码建立会话SSH 认证靠密钥对公钥放 GitLab 服务器私钥留本地握手时通过签名证明身份全程不传输密码。这套机制有三个直接收益。第一免密操作配置一次之后 git pull、git push、git clone 都不需要再输凭据。第二私钥不出本地比把密码交给各种凭据管理器更可控。第三公钥能精确关联到人谁的机器出事、谁拉过哪个项目GitLab 的审计日志里都对应得上。主流 GitLab 使用教程里SSH 也基本是推荐的认证方式内部团队尤其如此。用表格对比一下 HTTPS 和 SSH 的差异会更直观对比项HTTPS 密码/TokenSSH 密钥每次推送需要凭据或依赖 helper配置后完全免密认证材料密码或访问令牌可能被记录私钥文件不出本地服务端配置有账号权限即可需要先导入公钥适合场景临时机器、公网访问长期开发机、内网 GitLab手册直接采用 SSH 方案对内部团队是最省事的选择内网地址固定、开发机固定、人员流动大公钥一绑就能在权限回收时精准管理。3.2 ssh-keygen 命令拆解与三个交互提问手册给出的生成命令是# -t rsa 指定使用 RSA 算法 # -C 邮箱 是给密钥加的注释用于标识归属 ssh-keygen -t rsa -C lijianyu_alice163.com-t rsa 指定密钥算法为 RSA这是兼容性最广的选择几乎所有 SSH 服务端和 GitLab 版本都能识别。-C 后面跟注释惯例填邮箱不参与认证计算只让人在公钥清单里认得出这把钥匙是谁的。生成后公钥文件末尾会带上这段注释。执行后终端会依次问三个问题。第一问是保存路径默认是 /c/Users/你的用户名/.ssh/id_rsa直接回车接受默认即可。手册里红框标记的路径就是这里如果你手动改了路径之后所有引用密钥文件的地方都要跟着改。第二问是确认覆盖如果该路径已有密钥会提示 Overwrite (y/n)?手册里说输入 y这里的前提是旧密钥确实不再被任何平台使用否则覆盖后旧平台会直接失联。第三问是输入 passphrase 并再次确认这是私钥的保护口令可以理解为私钥的「开机密码」留空也能生成但建议设置第五章会解释为什么这道密码值得设。生成完成后终端会输出一张由字符构成的密钥指纹图案这是给人工比对用的看不懂也没关系。此时 .ssh 目录下已经多出两个文件id_rsa 是私钥id_rsa.pub 是公钥。关于算法补充一点现在新建密钥也有人推荐 ed25519性能和安全性都更好但部分老版本 GitLab 和旧服务器不认。团队内部环境统一按手册走 RSA能少撞一堵兼容性的墙个人项目自己用 ed25519 则完全没问题。3.3 密钥文件落点.ssh 目录的隐藏属性与「不复制私钥」的边界Windows 下 .ssh 目录默认隐藏在资源管理器里看不到新手很容易以为密钥生成失败。正确打开方式是在 Git Bash 里执行# 列出 .ssh 目录内容确认密钥文件已生成 ls -la ~/.ssh # 查看公钥内容下一步要粘贴到 GitLab cat ~/.ssh/id_rsa.pub~ 代指当前用户目录即 C:\Users\你的用户名。ls -la 能显示隐藏文件看到 id_rsa 和 id_rsa.pub 两个文件就说明生成成功。cat 输出的是以 ssh-rsa 开头、以邮箱注释结尾的长文本这就是要导入 GitLab 的公钥。私钥 id_rsa 不需要打开也不需要复制。这里有一个边界条件要提前说如果这台机器之前为 GitHub 或者其他平台生成过 id_rsa你把默认路径覆盖掉那边就会突然连不上。遇到这种情况不要覆盖给每个平台生成独立密钥文件再用第六章的 SSH config 做分发。手册只讲单人单 GitLab 的最简路径这没错但实际团队里一个人对接多个 GitLab 实例很常见边界知道得早到时候就不会翻车。把公钥内容发给别人、贴到 GitLab 上都安全但私钥文件一旦泄露等于把仓库读写权限直接交给了别人轮换密钥之前你没有任何后悔药可吃。4. 把公钥导入 GitLabProfile Setting 里的五个动作4.1 动作一和二修改初始密码、重新登录并核对邮箱密钥生成完毕接下来是把公钥放进 GitLab。手册在这一节把「登录 GitLab 地址、修改初始密码、重新登录」反复粘贴了很多遍第一次读的时候很容易被绕晕。其实这段流程只代表两个动作用初始密码登录并改成自己的密码然后重新登录进主界面。导入 SSH Key 只需要在登录成功后操作一次不是每次登录都要重导。第一次登录时GitLab 会要求修改管理员分配的初始密码。部分部署版本还强制密码满足最小复杂度比如不少于 8 位且同时包含字母和数字。改完密码重新登录账号才算真正激活。这里顺手核对一件事账号邮箱和第二步里写的 git config --global user.email 是否一致。如果不一致后续你推送的提交在 GitLab 上会归到一个空账号名下显示成「神秘贡献者」代码统计和注释率统计都会漏掉你。还有一处容易产生迷惑手册写的是 Profile Setting这个菜单在 GitLab 不同版本里改过好几次名字新版可能叫 Preferences位置基本都在右上角用户头像的下拉框里。以你实际部署版本为准别因为菜单名不一样就怀疑自己走错页面。修改密码后强制重新登录也不是多此一举会话中的身份信息在密码变更后需要刷新重新登录能让新密码和新会话状态同步生效避免后续操作被旧的会话缓存干扰。4.2 动作三到五进入 Profile Setting、定位 SSH Keys、粘贴公钥并添加登录成功后按下面的顺序走点击右上角用户头像选择 Profile Setting。在左侧边栏找到 SSH Keys 入口。在 Git Bash 执行 cat ~/.ssh/id_rsa.pub复制整段输出。把内容粘贴到 Key 文本框注意开头要是 ssh-rsa。在 Title 里填一个能认出来的名字点击 Add SSH Key。Key 文本框只认公钥文本粘贴时不要带多余空格和换行。Title 是给人看的备注建议写成 用户名-设备-用途 的格式比如 alice-work-laptop密钥多了之后靠它区分哪台机器换过、哪台该删。点击 Add 后列表里出现这条记录导入动作就算完成了。导入后建议立刻验证链路是否真的通了在 Git Bash 里执行# 先看本机公钥内容确认复制时没漏字符 cat ~/.ssh/id_rsa.pub # 测试 SSH 认证通道提示 welcome 即成功 ssh -T git10.10.169.27 # 用 SSH 地址拉取项目group 为组名project 为项目名 git clone git10.10.169.27:group/project.gitssh -T 是 SSH 的测试连接方式指定了 User git 但不会真正登录GitLab 收到请求后会返回欢迎语并断开。如果输出 Welcome to GitLab, yourname!说明公钥已生效可以直接 clone 项目。这里要强调git clone 的地址取自 GitLab 项目主页 Clone 按钮里的 SSH 地址不要自己手拼接。地址中的 group 是项目所属组project 是项目名中间用冒号分隔。用 HTTPS 地址则走密码认证与刚导入的密钥无关两种方式不要混。4.3 替换 MyEclipse 旧密钥IDE 与命令行共存的处理手册里有一段容易被跳过的操作将 MyEclipse 自动生成的 SSH key 修改为刚刚生成的 SSH key删除 id_dsa把 SSH2 Home 换成新密钥所在目录。这段讲的是老一代 Eclipse 系 IDE 的密钥管理问题。MyEclipse 和旧版 Eclipse 在操作 Git 时会优先读取 Window Preferences General Network Connections SSH2 配置里的 SSH2 Home 目录。如果 IDE 自己生成过 id_dsa 密钥而 GitLab 上导入的是新建的 id_rsa 公钥IDE 推送时就会拿 id_dsa 去认证结果自然是 Permission denied。解决办法就是手册写的两件事删掉或移走旧密钥 id_dsa把 SSH2 Home 指到包含新密钥的 .ssh 目录。现在的主流 IDEA 和 VS Code 默认读取 %USERPROFILE%.ssh 下的标准密钥文件一般不用额外配置。但如果你还在用旧版 Eclipse 系 IDE遇到「命令行 push 正常、IDE push 报错」的诡异情况优先查 IDE 的 SSH2 设置页有没有指错目录。这类问题隐蔽在命令行一切正常极易被误判为 IDE 插件损坏实际只是密钥读取路径不一致。如果你完全不用 MyEclipse这一段可以跳过但要知道排查方向在哪里。5. SSH 配置避坑指南五个高频问题的现象、原因与解决SSH 层的问题大多不是玄学报错信息基本都能从密钥文件、ssh-agent 状态、GitLab 账号配置三个位置对出来。下面五条是我按手册落地时遇到的高频问题每一条都按现象、原因、解决三个部分写。5.1 Permission denied (publickey)密钥没进 agent 或没导入 GitLab现象执行 ssh -T git10.10.169.27 或者 git clone 时终端只返回 Permission denied (publickey)没有更多提示。原因这是 SSH 认证失败的通用报错常见原因有三个公钥根本没导入 GitLab 账号导入的公钥内容被改动过比如复制时漏了开头的 ssh-rsa本地使用的私钥文件不是 GitLab 上对应公钥的那一把。解决先执行 cat ~/.ssh/id_rsa.pub 把公钥完整复制出来去 GitLab SSH Keys 页面重新添加确认粘贴的是完整一段。然后检查 ssh-agent 是否加载了私钥# 列出当前 ssh-agent 已加载的密钥空列表说明私钥没进 agent ssh-add -l # 把默认私钥加载进 agent ssh-add ~/.ssh/id_rsassh-add -l 输出为空时SSH 客户端即使找到了私钥文件也可能拒绝使用特别是 Windows 上部分终端环境不会自动加载。手动加入后重新测试 ssh -T通常就能通过。如果密钥文件名不是默认的 id_rsa比如自定义为 id_rsa_company需要在连接参数里显式指定 IdentityFile或者用第六章的 SSH config。5.2 每次 Git 操作都要输入密码passphrase 与 ssh-agent 的关系现象密钥设置了 passphrase之后每次 git push 和 git pull 都被要求输入一遍口令。对高频提交的人来说这个重复输入非常打断节奏。原因passphrase 本质上是一个对称加密口令SSH 每次要使用私钥签名时都得先读私钥文件并用口令解密。如果不借助 ssh-agent每条 git 命令都会重新执行一次解密自然每次都向你索要口令。ssh-agent 解决的就是这个问题它在后台常驻把解密后的私钥保存在内存里后续 SSH 握手直接复用整个会话只需要输入一次。解决用 ssh-agent 把私钥驻留在内存里# 启动 ssh-agent 后台进程 eval $(ssh-agent -s) # 加载私钥按提示输入一次 passphrase ssh-add ~/.ssh/id_rsa之后当前终端会话的后续 Git 操作都不再询问密码。想让这个效果在每次打开 Git Bash 时自动生效可以把这两行写进 ~/.bashrc。Windows 上也可以在服务里把 OpenSSH Authentication Agent 设为自动启动并运行效果类似。这里也回应了第三章留下的问题passphrase 值得设因为私钥被复制走的时候没有口令的私钥等于直接裸奔有口令的私钥还多一层防线。5.3 login failed 报错API Token、版本兼容与账号审批状态现象命令行 Git 一切正常但某些 IDE 插件、Jenkins 或脚本调用 GitLab 接口时报 login failed. check api token or gitlab version.Web 登录也有报 your account is pending approval from your gitlab administrator 的情况。原因这条报错和 SSH 无关是工具在走 GitLab API 时鉴权失败。GitLab API 不认 SSH 密钥只认 Personal Access Token同时不同 GitLab 版本对 API 的兼容性有差异老工具连新版本时经常报这个版本不匹配的错。后面那条 pending approval 则是新注册账号还没被管理员审批激活属于账号生命周期问题。解决先去右上角用户头像 → Preferences → Access Tokens新建一个 Personal Access Token按工具要求勾选 api、read_repository、write_repository 等作用域生成后粘贴到工具配置里。如果还报版本问题对比工具文档和你部署的 GitLab 版本是否在支持范围内该升级工具就升级。pending approval 那条直接找 GitLab 管理员在 Admin Area 的 Users 列表里把账号激活不需要自己折腾服务端。5.4 公钥与私钥不匹配id_rsa.pub 内容被复制错现象GitLab SSH Keys 页面明确显示密钥已添加ssh -T 依然 Permission denied反复重新添加也没有变化。原因添加进去的公钥和本地正在使用的私钥不是同一对。典型场景包括从另一个人那里复制了公钥文本之前生成过好几把密钥自己忘了哪一对是当前机器在用的粘贴时把网页上展示的短指纹当成公钥内容贴了进去。解决用指纹比对法定位问题。在 Git Bash 执行# 查看本地公钥的指纹与 GitLab 页面对比 ssh-keygen -lf ~/.ssh/id_rsa.pubssh-keygen -lf 会输出类似 2048 SHA256:xxxx... 的指纹。打开 GitLab SSH Keys 列表找到刚才添加的那条对比指纹是否一致。如果版本较低的 GitLab 不显示指纹直接把 Key 文本框里的内容清空重新粘贴本机 cat 出来的完整公钥并保存。之后立刻重跑 ssh -T 复测。5.5 手册原文重复造成的误操作导入步骤不是要执行十遍现象手册第四章「导入 sshkey」这一节原文将登录、改密码、进入 Profile Setting、点击 SSH Keys 的步骤连续粘贴了十几次新人顺着读下来以为每次登录都要重新导入密钥有人在 GitLab 上把同一把公钥重复添加了七八次。原因原始文档编辑时发生内容重复粘贴属于文档质量问题。GitLab 允许同一用户重复添加同一把公钥不会报错但列表中会出现一串同名密钥后续做密钥轮换和权限排查时很难分清哪条有效。解决PDF 里同一段内容连续出现多次时按一次完整流程理解即可不需要重复执行。如果已经在 GitLab 上重复添加了公钥保留最早一条把后加的重复条目删除。这件事本身也是个提醒拿到团队文档先扫一遍结构发现异常重复说明文档该修订了不值得花时间复现流程中的每一步。6. 进阶SSH config 多账号管理与最小闭环验证6.1 一份可复用的 ~/.ssh/config 示例一个人对接多个 GitLab 实例的典型场景默认的 id_rsa 不够用。我的做法是给每个 GitLab 生成独立密钥然后在 ~/.ssh/config 里做映射# 公司内网 GitLab Host gitlab-company HostName 10.10.169.27 User git IdentityFile ~/.ssh/id_rsa_company IdentitiesOnly yes # 外部测试环境 Host gitlab-cloud HostName gitlab.example.com User git IdentityFile ~/.ssh/id_rsa_cloud IdentitiesOnly yesHost 是连接别名HostName 是真实地址IdentityFile 指定该别名使用的私钥IdentitiesOnly yes 强制只用这一把避免 ssh 把所有私钥挨个试一遍造成认证顺序错乱。配置生效后 clone 地址写成 gitgitlab-company:group/project.git后面的 push、pull 都会自动匹配对应密钥。6.2 一条龙验证clone、log、push 跑通完整链路无论配的是单账号还是多账号最终检验标准都是代码能不能推上去。我每次给新机器配完 GitLab 环境都会强制跑一遍最小闭环# 1. 拉取一个测试项目验证 SSH 通道是否可用 git clone git10.10.169.27:group/project.git # 2. 查看最近提交确认提交归属性正确 cd project git log --oneline -5 # 3. 改一个文件并提交推送验证写权限 echo ssh config check README.md git add README.md git commit -m docs: verify ssh configuration git push origin maingit log 这一步最容易被跳过但提交记录是否显示自己的名字和邮箱只有看输出才能发现。推送成功后去 GitLab 网页端看提交记录确认头像和名字正确。如果显示为陌生账号回头查 git config user.email 是否与 GitLab 注册邮箱一致。日常团队成员常用 git checkout -b feature/xxx 新建分支再 push origin 分支名走的是完全相同的认证链路clone、push 主分支通了分支操作也就通了。如果你是在本地已有项目准备把整个项目导入 GitLabGitLab 新建项目后会直接给出 remote add 和 push 的现成命令照着执行即可。6.3 把检查养成习惯从那以后我每次换电脑或者换团队配完 GitLab 的第一个动作不是急着拉大仓库而是先建一个空项目跑一遍 clone、log、push 的最小闭环确认名字、邮箱、密钥全部对齐再开始正式工作。这个习惯帮我省掉的排错时间远多于顺手跑几条命令花掉的时间。这份 GitLab 用户手册 v2 把最基础的链路写得很完整虽然排版粗糙、部分章节重复但照着走完一遍再补上 SSH config 的多账号管理日常场景就都覆盖到了。希望帮到你。本文还有配套的精品资源点击获取
