★ FEATURED ARTICLE 简介《GitLab用户手册v2.pdf》是一份面向Git初学者和团队协作开发者的技术资料重点解决从Git客户端安装到GitLab平台日常使用中的常见配置与操作问题。手册先后梳理了环境搭建、全局用户名与邮箱设置、SSH密钥生成及导入、项目创建与克隆、版本历史查看等基础环节也介绍了CI/CD流水线、代码评审、权限管理等高级功能兼具入门指导与速查价值。整个资源以单个PDF文件构成压缩包体积约1.04MB适合下载后离线浏览或打印对照。目前已有538人浏览学习适合正在搭建GitLab环境、需要配置SSH认证或想系统了解GitLab基础与进阶操作的开发与运维人员使用。手册中结合实际命令与界面路径细致展示了GIT Bash下常用命令的用法、SSH密钥生成和导入的具体步骤以及登录GitLab后完成个人配置的跳转流程能有效减少初次使用者常见的环境与认证踩坑是一份实用的GitLab入门参考。1. GitLab 用户手册 v2把内网 Git 环境从能装到能用的一本薄手册我拆这份 GitLab 用户手册 v2.pdf 的时候最大的感受是它做的事非常朴素就是把「装 Git → 配全局用户名 → 生成 SSH key → 把公钥放进 GitLab → 能克隆能推送」这条链路按顺序写清楚了。很多团队刚搭好 GitLab比如手册里这个 http://10.10.169.27/ 的内网服务器卡人的往往不是 Git 命令本身而是 SSH 密钥这一环生成了不知道怎么导入导入了不知道成没成功。这份手册正好把这些步骤理顺了适合刚接触 GitLab 的开发者、需要给团队做环境准备的负责人以及经常换电脑、每次都要重配一遍 SSH 的重装党。下面我按自己的使用习惯把每一步重新走一遍顺带补上手册里没写透的坑。2. 环境准备从 Git 安装到 user.name 与 user.email 的全局配置2.1 下载与安装 Git三个值得手动改的默认选项手册指定的下载地址是 https://git-for-windows.github.io也就是 Git for Windows 的官方入口。下载完安装包双击运行一路 Next 确实能装完但我不建议完全用默认值。安装过程中有几步会影响后面 Git Bash 的使用体验尤其是 Adjusting your PATH environment 这一步它决定你能否在系统命令行cmd、PowerShell、IDE 内嵌终端里直接调用 git。这一步通常给三个选项Git from the command line and also from 3rd-party software、Git from the command line only、以及只从 Git Bash 里使用。我一般选第一个理由很实际很多 Java 项目或 IDE手册里提到 MyEclipse在构建或做版本操作时是从系统路径直接调 git 的如果只选了 Git Bash 内使用IDE 里执行 git 命令就会提示找不到命令。选完 PATH 后还有一步比较关键的是换行符处理Windows 默认选项是 Checkout Windows-style, commit Unix-style line endings意思是检出时自动转成 CRLF、提交时转回 LF。这个设置在纯 Windows 团队里没问题但团队只要有一个 Linux 部署脚本或 .sh 文件就容易出现「明明没改文件git status 却显示一堆 modified」的翻车现场。所以我习惯选 Checkout as-is, commit as-is把换行符的决定权交给项目自己的 .gitattributes。安装选项推荐选择原因PATH 环境Git from the command line and also from 3rd-party softwareIDE 和构建脚本能直接调用 git换行符处理Checkout as-is, commit as-is避免 CRLF/LF 混用导致大量假 diff终端模拟器Windows 默认终端复制粘贴长命令更稳定兼容性更好第三个值得动一下的是终端模拟器选择。MinTTY 和 Windows 默认终端对 Git 命令本身没有影响但 Windows 默认终端在打开多个窗口、复制超长命令时更稳我习惯选 Windows 默认。装完以后打开 Git Bash先跑一次版本确认git --version预期输出类似 git version 2.x.x。这一步同时确认两件事Git 装好了Git Bash 能正常执行外部命令。如果这里报错大概率是 PATH 选项没选对重装一次即可不用做其他排查。装完 Git 后桌面上出现 Git Bash 的图标右键菜单里也会多出 Open Git Bash here 和 Open Git GUI here 两个入口前者是我们日常主要的命令行入口后者是图形化界面适合不习惯命令行的人但功能覆盖不如命令完整建议还是以 Bash 为主。2.2 git config名字和邮箱不是随便填的Git 的提交记录里有两个字段user.name 和 user.email。手册给的命令是git config --global user.name yourname git config --global user.email emailexample.com第一条配置全局用户名会显示在提交记录的作者位置第二条配置全局邮箱这个邮箱必须和你登录 GitLab 的账号邮箱完全一致。不一致的后果很隐蔽代码能正常 push但 GitLab 的提交历史里author 不会关联到你的账号贡献统计、代码评审的指派全都会对不上。而且提交记录一旦生成事后改邮箱只能改历史在团队仓库里做这种事情非常麻烦。--global 参数的含义是写到当前系统用户目录下的 ~/.gitconfig 文件对所有仓库生效。如果一台电脑同时参与公司和个人的项目可以在某个仓库目录内执行不带 --global 的 config 命令用 --local 级别覆盖全局配置。我一般这样用全局写公司邮箱个人项目目录里单独设置避免把公司身份带进开源项目。配置完成后可以用下面这条命令检查所有生效项git config --list输出里能看到 user.name、user.email、core.autocrlf 等条目。注意如果同一配置项在多个级别都存在后输出的是优先级更高的值级别优先级从低到高是 system global local。如果发现配置不对重新执行 config 命令就能覆盖如果只想看单个配置项用 git config user.name 这种写法即可。还有一个新手容易忽略的点Git Bash 打开后的当前目录默认是用户主目录执行 git config --global 不依赖当前路径但 --local 必须先进入某个已经初始化的仓库目录否则会报错。另外user.name 可以填中文Git 本身支持但 GitLab 在部分版本里对中文 user.name 的兼容一般建议用英文或拼音避免在代码评审界面出现乱码头像。3. 生成 SSH 密钥ssh-keygen 参数与密钥文件落点3.1 为什么 GitLab 场景首选 SSH 免密GitLab 支持 HTTP 和 SSH 两种协议访问仓库。HTTP 克隆简单但每次 push 都要输入账号密码或者依赖本机的凭据管理器记住密码SSH 在第一次配置好密钥后后续所有操作全程免密。对于手册里这类内网 GitLab我默认走 SSH还有一个实际原因内网 GitLab 常用自签证书HTTP 克隆经常撞上 SSL 证书校验失败的问题而 SSH 通道不涉及证书体系直接绕开了证书信任这层麻烦。这里有个反直觉的点SSH key 是「一人多机」绑定的。同一个开发者在办公电脑、笔记本、家里电脑上可以分别生成不同的密钥然后在自己的 GitLab 账号下全部添加服务器通过公钥识别是哪台机器在连接。每台机器独立的 key 也方便某台电脑丢失时单独吊销不影响其他设备。这套机制本质上是用非对称加密客户端持有私钥服务器持有公钥连接时用私钥签名、公钥验签全程不传输密码也不怕被嗅探。这也是为什么 GitLab 使用教程里几乎都会先讲配置 SSH 密钥——它是整个免密链路的起点。3.2 ssh-keygen 生成命令每个参数都有用途手册里给的命令是ssh-keygen -t rsa -C lijianyu_alice163.com我自己的习惯是在中间加一个 -b 参数ssh-keygen -t rsa -b 4096 -C lijianyu_alice163.com执行后按三次回车即可第一次回车是确认保存路径默认是 ~/.ssh/id_rsa后两次是设置 passphrase口令可以留空也可以设置。逐项说明参数的含义-t rsa 指定密钥算法为 RSA-b 4096 指定密钥长度为 4096 位手册里没有写 -b默认是 2048对绝大多数场景够用但 4096 更稳妥-C 是注释习惯写自己的邮箱这样在 GitLab 的 SSH Keys 列表里能一眼看出这把 key 对应哪个人的哪台机器。生成过程中如果之前已经生成过密钥会出现 Overwrite (y/N)? 提示。输入 y 会直接覆盖旧私钥和公钥等于废掉旧密钥。如果旧公钥已经贴到 GitLab 或其他服务器上覆盖后需要去对应页面删掉旧公钥并导入新的否则那边会留一把永久失效的 key。如果旧密钥还在别的服务器上用覆盖前要慎重建议确定旧 key 没有作用了再执行。生成完成后密钥对落在 ~/.ssh 目录。要查看公钥内容用cat ~/.ssh/id_rsa.pub输出是一长行以 ssh-rsa 开头、末尾带邮箱注释的文本。公钥可以公开可以发给管理员也可以贴到任意需要免密的服务器上私钥 id_rsa 绝对不能给任何人。这里有个常见错误是把公钥和私钥搞反导入时贴的是私钥内容服务器直接拒绝。想确认文件是否正常可以列出 ~/.ssh 目录看看ls -la ~/.ssh正常情况下能看到 id_rsa 和 id_rsa.pub 两个文件id_rsa 的权限在 Linux 下要求是 600Windows 下虽然没有强制要求但也不要让多用户共享这份私钥。提示任何情况下都不要把私钥内容贴到网页表单里。GitLab 的 SSH Keys 页面只接受公钥也就是 .pub 文件里的内容。3.3 passphrase 的取舍免密也不等于裸奔ssh-keygen 过程中出现的 Enter passphrase 提示处理方式会影响日复一日的手感。不设置口令直接回车私钥文件是明文存储的谁拿到这份文件谁就能使用这把 key 连接所有配置过公钥的服务器设置一个口令私钥文件会被加密每次使用需要输口令但可以通过 ssh-agent 让它只输一次。我的内网团队建议是设置一个不太长的口令然后配合 ssh-agent 缓存。具体做法在第 5 章的对应坑位里展开。如果不设置口令至少要保证系统用户密码够强、硬盘启用 BitLocker 之类的全盘加密否则私钥文件泄露的后果和账号密码泄露差不多。对于 GitLab 这种承载代码资产的系统安全底线不能太低。4. 导入 SSH Key 到 GitLab登录、改密与 Profile Setting 实测路径4.1 首次登录初始密码是第一道必须过的关GitLab 管理员创建账号后会把初始密码给到个人浏览器打开手册里的服务器地址 http://10.10.169.27/用账号和初始密码登录系统会跳转到修改密码页面。这一步没有捷径初始密码不换账号就处于「知道密码的人都能登录」的状态。GitLab 在用户侧看改完密码才算真正激活账号也才能进入后面的 SSH Keys 页面。这里要插一句手册的真实情况手册里「导入 sshkey」这一大段被连续粘贴了很多次看起来像是从现场操作截图里直接拼出来的实际步骤并不多核心就是登录、改密码、进 Profile Setting、加公钥四步。被复制多遍的内容不用逐条看按下面的路径走就能完成。4.2 Profile Setting 与 Add SSH Key把公钥交给服务器登录进 GitLab 后界面右上角是头像下拉框点击后选择 Profile Setting——新版界面里可能显示为 Preferences入口位置一样。进入后左侧菜单找到 SSH Keys点击 Add SSH Key 按钮会出现两个输入区域Title 和 Key。Title 是给这把 key 起一个可识别的名字建议按「使用者-设备」的格式例如 alice-office-pc 或 alice-macbook避免出现一堆同名 key 分不清哪个是哪个。Key 区域粘贴公钥内容也就是第 3 章里 cat ~/.ssh/id_rsa.pub 输出的那一整行。GitLab 支持同一账号下添加多把公钥所以多台电脑分别生成的公钥都可以贴进来互不影响。粘贴完成后点 Add key 保存页面会出现一条带 Key fingerprint 的记录。建议把 GitLab 页面上的 fingerprint 和本机公钥生成的指纹做一次对照命令是ssh-keygen -lf ~/.ssh/id_rsa.pub输出的指纹串如果和页面上显示的一致说明本机这把公钥确实成功导入了这个动作虽然多花几秒但能彻底排除「贴错 key」的可能。4.3 用 ssh -T 验证密钥别等 push 才发现问题公钥导入 GitLab 后最直接的验证方式是让 SSH 客户端与 GitLab 建立一次连接ssh -T git10.10.169.27首次连接会出现一个确认提示询问是否信任该主机的指纹输入 yes 回车。如果一切正常服务端会返回 Welcome to GitLab, yourname!看到这一句就说明密钥链路已经打通。如果输出 Permission denied (publickey)说明密钥没被服务器接受优先按第 5 章的对应条目排查而不是反复重新粘贴公钥。这一步建议固定到每次新电脑配置的流程里。密钥验证通过后再 git clone可以把后续一连串问题挡在前面。不同 GitLab 版本的欢迎语措辞略有差异有的版本还提示 Youre about to create a project只要没有出现 denied 或 failed 字样就说明 SSH 握手成功了。验证命令不带 -T 的话会进入登录交互界面所以 -T 这个参数不能省它表示禁止分配终端。5. 避坑清单GitLab 接入中最容易翻车的五个场景5.1 Permission denied (publickey)密钥没被服务器接受现象执行 ssh -T git10.10.169.27返回 Permission denied (publickey)GitLab 页面却显示 key 已经添加成功。原因大概率是三类问题之一贴进 GitLab 的是私钥内容而不是公钥公钥粘贴时漏了开头或多了换行本机 SSH 连接时用的不是这把私钥比如 ssh-keygen 时改过默认文件名或系统里同时存在多把 key 导致 SSH 选择了错误的私钥。解决先在 GitLab 的 SSH Keys 页面删掉疑似有问题的 key重新复制 id_rsa.pub 的完整内容再添加注意必须是 .pub 结尾的文件。如果生成时用了自定义文件名连接时需要显式指定私钥ssh -i ~/.ssh/mykey -T git10.10.169.27多数情况下删掉重新贴一次就能解决。如果仍不行可以加 -v 参数跑一次详细日志看 SSH 实际尝试了哪些 keyssh -vT git10.10.169.27日志里会输出 Authenticated to ... 或 Permission denied 的关键行能看到具体是哪把 key 被拒绝了排查范围能一下子缩小。5.2 提交记录关联不上账号email 和 GitLab 不一致现象代码正常 push 到 GitLab仓库里也能看到提交但提交记录的作者区域显示 Unknown 或一串数字 id点进去关联不到任何账号。原因commit 的作者信息由本机 git config 提供提交时用的是 user.email 字段。如果这个邮箱和 GitLab 账号的邮箱不一致GitLab 无法把提交归到你的名下。这个错误没有任何报错、没有警告是最隐蔽的坑。解决先执行 git config --list 看当前配置把 user.email 改成 GitLab 账号对应的邮箱改完再提交新代码即可。已经产生的错误提交最近一次的可以用 git commit --amend --reset-author 修改如果已经推送且历史提交很多就需要 rebase 或由仓库管理员协助处理。从那以后我都把「先配 user.email 再生成密钥」当成强制顺序。5.3 每次 push 都要输 passphrasessh-agent 没接管现象明明设置的 passphrase 不想每次输入但每次 push、pull 都在问 Enter passphrase for key。原因设置口令后 SSH 每次使用私钥都需要口令只有把私钥交给 ssh-agent 缓存才能做到整个会话内免输。Git Bash 每次重启后ssh-agent 默认是空的。解决手动加载一次eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa输入一次口令后当前 shell 会话内连接 GitLab 不再追问。想长期免输可以把这两行追加到 ~/.bashrc 里Git Bash 每次启动自动执行。不推荐直接把 passphrase 留空来省事安全性差距太大agent 方案既保安全又保手感。5.4 手册命令抄下来直接报 command not found现象照着 PDF 抄ssh-keygen-trsa -C xxx163.com执行后提示 command not found。原因PDF 排版或导出时把 -t rsa 粘连成一个词了。这个现象在这份手册里原样存在值得记一笔任何 PDF 里抄出来的命令先自己拆开确认每个参数再执行。解决正确写法是 ssh-keygen -t rsa -C 邮箱参数之间必须有空格。同理git config --global 里的连字符也不要复制丢字否则会提示 git config --global 非法。这类问题还有个附带教训看用户手册时遇到命令先自己在脑子里过一遍结构见过太多人因为 PDF 里一个小粘连卡住了半小时。5.5 网页能打开克隆总超时证书与代理环境现象浏览器访问 http://10.10.169.27 正常但 git clone 走 HTTP 地址时卡住或报 SSL certificate problem。原因内网 GitLab 常用自签证书git 的 http.sslVerify 默认开启证书链不受本地信任时直接拒绝连接部分公司网络还有代理层拦截。解决手册推荐的 SSH 通道可以完全绕开证书校验。如果仓库地址已经是 HTTP 形式在内网可信环境下可以单独针对该服务器关闭校验git config --global http.sslVerify false这条命令只建议在内网 GitLab 场景使用公网仓库务必保持默认开启。更稳妥的做法是让管理员给 GitLab 配置内部 CA 证书并下发到各机器一劳永逸但需要管理员介入普通开发者先用 SSH 通道最省事。6. 密钥配好后从克隆到推送的一轮完整 Git 工作流密钥验证通过后剩下的就是日常操作。在 GitLab 的项目页面复制 SSH 地址格式是 git10.10.169.27:group/project.git然后执行git clone git10.10.169.27:group/project.git cd project git checkout -b feature/login git add . git commit -m add login page git push -u origin feature/login这是一条最常用的分支工作流。git checkout -b 创建并切换到新分支git push -u origin feature/login 把本地分支和远端分支绑定之后在同一分支上直接用 git push 即可。git add . 会把当前目录所有改动加入暂存区提交前建议先 git status 确认没有把临时的编译产物或 IDE 配置带进去。如果是把本地已有的项目上传到 GitLab流程是先在 GitLab 上新建空仓库复制它的 SSH 地址再在本地项目目录里执行git init git remote add origin git10.10.169.27:group/project.git git add . git commit -m initial commit git push -u origin main本地项目上传到 GitLab 这个场景里最常见的坑是分支名GitLab 新建仓库时默认主分支可能是 main 或 master推送前先确认远端仓库已初始化的默认分支名避免产生两个毫无关联的主分支历史。最后分享一个我长期在用的技巧给内网服务器在 ~/.ssh/config 里配置别名。手写配置Host gitlab-internal HostName 10.10.169.27 User git IdentityFile ~/.ssh/id_rsa配置后克隆地址可以写成 gitgitlab-internal:group/project.git以后服务器 IP 变了只改 HostName 一处本地的 remote url 不用动本机所有依赖这个地址的脚本也都不受影响。日常拉代码时我还保留一个习惯只走 git pull --rebase避免产生无意义的 merge commit让分支历史保持一条直线后续回溯问题时清晰很多。从那以后我在任何新电脑上配 GitLab 环境都会强制走一遍「生成 key → 导入 GitLab → ssh -T 看到 Welcome」再开始 clone这套流程放在 GitHub 或 Gitee 上同样成立。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
:聚合与收集)
