1. 先聊清楚GitLab到底是什么为什么每个团队都在用第一次接触GitLab的人十有八九会把Git、GitHub和GitLab混成一锅粥。我当年也经历过这个阶段对着终端里的git命令一脸懵完全搞不清楚它和网页上那个代码仓库到底是什么关系。这里先用最直白的话把这三者的关系捋顺。Git本身是一个分布式版本控制系统它负责在你本地跟踪代码的每一次改动记录谁在什么时候改了什么文件。它不依赖于任何服务器你甚至可以在断网状态下用Git管理自己的项目。而GitLab和GitHub都是基于Git的代码托管平台它们把本地的Git仓库同步到远程服务器上提供网页端的代码浏览、分支管理、合并请求、问题跟踪等功能。如果拿拍照来类比Git是相机本身负责按下快门记录瞬间而GitLab和GitHub是相册让你把照片洗出来、分类归档、分享给别人看。GitLab和GitHub最大的区别在于GitHub是SaaS服务代码托管在人家服务器上私有仓库数量有限而且很多企业级功能要付费而GitLab是开源软件你可以把它安装在自己的服务器上数据完全由自己掌控。这就是为什么大量公司会选择在内部搭建一套GitLab代码不出内网安全可控同时还能利用GitLab自带的CI/CD流水线能力实现自动化部署。标题里提到的“ssh key生成及使用”是使用GitLab绕不开的第一步。很多新手在克隆代码时习惯了输入用户名密码的HTTPS方式但一旦涉及自动化部署、频繁pull/push、或者公司强制要求安全认证SSH Key就成了必经之路。这篇内容就围绕GitLab的基本使用方式展开重点带你走通SSH Key的生成、配置、排查全流程挨个把坑踩平。2. 为什么强烈推荐用SSH Key连GitLab2.1 HTTPS和SSH两种连接方式到底差在哪在你把一个远程仓库克隆到本地之前Git需要确认“你确实是这个项目的成员”。GitLab支持两种认证方式第一种是HTTPS方式链接长这样https://gitlab.com/yourgroup/project.git。每次执行git push或者git pull的时候Git都会弹出窗口让你输入GitLab的用户名和密码实际是Token或个人访问令牌。如果装了Git的凭据管理器它能帮你把密码记住不用每次手动输但这种方式本质上还是“账号密码服务器验证”。第二种就是SSH方式链接长这样gitgitlab.com:yourgroup/project.git。它用的是公钥加密和私钥签名的认证机制你只需要提前把公钥配置到GitLab账号里之后的每一次连接都走密钥自动认证不会再弹出任何密码输入框。两种方式的体验差异就好比一个是每次进小区都要在门卫那儿登记身份证另一个是刷脸进门一次录入之后畅通无阻。2.2 SSH Key的工作原理用生活例子讲明白SSH Key是一对非对称加密钥匙包含一个私钥和一个公钥。私钥保存在你本地电脑上默认在~/.ssh/id_ed25519绝对绝对不能泄露公钥则是一串明文文本你可以大方地把它配置到GitLab上。它的认证过程是这样的当你向GitLab发起SSH连接时服务器会生成一段随机数据发送给你你的SSH客户端用私钥对这段数据进行签名然后把签名结果发回给服务器。服务器用你预先配置的公钥验证这段签名如果验证通过说明“持私钥的人确实是公钥的主人”于是认证成功。这个机制和保险柜的原理很像公钥是保险柜的锁任何人都可以看到锁长什么样但只有拿着正确钥匙私钥的人才能打开柜子。你不需要把钥匙交给别人只需要让服务器记住“这把锁认哪把钥匙”后续的身份验证就全部自动化了。2.3 为什么说配置SSH Key是开发效率的分水岭在实际开发中SSH Key的优势体现在几个非常具体的场景里。第一个场景是日常开发中的高频push操作。用HTTPS方式如果没配凭据管理器每次都输Token不仅烦还容易输错配了凭据管理器多账号切换又容易出错。SSH方式一劳永逸绑定一次以后无感操作。第二个场景是CI/CD自动化。Jenkins、GitLab Runner这类自动化工具在拉取代码时需要一个无人值守的认证方式。账号密码会过期、Token轮换需要改配置而SSH Key只要不被吊销就能一直稳定工作。很多团队最初的自动化构建跑不起来排查到最后发现就是认证方式选错了。第三个场景是安全合规。私钥不出本地机器公钥才传给服务器整个认证链条里没有明文密码在网络中传输安全等级明显高于用户名密码。3. SSH Key生成实操从零到一3.1 生成之前先看看自己有没有“老钥匙”在动手生成新Key之前我强烈建议你先检查一下本地是否已经存在SSH Key。很多新手不查直接一路回车生成了新的密钥对然后把公钥配置到GitLab上结果发现之前配的GitHub、服务器或者其他平台的连接全断了——因为新的密钥对覆盖了旧的。打开终端执行下面这个命令ls -al ~/.ssh这条命令会列出.ssh目录下的所有文件。如果你看到id_rsa、id_rsa.pub、id_ed25519、id_ed25519.pub这类文件说明本地已经有一对密钥了。其中.pub后缀的是公钥没有后缀的是私钥。此时你有两个选择如果之前生成的Key还在正常使用完全可以直接沿用跳到下一节把公钥配置到GitLab即可。如果确定这些Key已经废弃了或者你就是想给GitLab单独生成一把独立的Key强烈推荐后面会讲原因那可以跳过旧文件用另一个名字生成新Key。3.2 正式生成选择合适的加密算法和管理口令现代GitLab环境我推荐直接生成ED25519类型的密钥命令如下ssh-keygen -t ed25519 -C 你的邮箱地址-t ed25519指定密钥类型为Ed25519这是一种比传统RSA更安全、性能更好、密钥长度更短的算法。-C后面的备注信息会写进公钥文件的末尾方便你在GitLab服务器上识别这把Key是哪个设备、哪个用途的比如-C work-laptop或者-C rootubuntu-server。执行命令后终端会提示你输入保存密钥的文件路径Generating public/private ed25519 key pair. Enter file in which to save the key (/home/user/.ssh/id_ed25519):这里我建议不要直接回车用默认文件名而是给它一个能区分场景的名字比如~/.ssh/id_ed25519_gitlab。原因在于如果你同时使用GitHub、Gitee、公司GitLab等多个代码平台每个平台用一把独立的Key后续通过配置文件来分流会省去很多管理上的麻烦。这个方案我下面会详细展开。接着系统会询问是否设置passphraseEnter passphrase (empty for no passphrase): Enter same passphrase again:passphrase是给私钥再加一层密码保护。即使有人拷贝了你的私钥文件没有passphrase也无法使用。但代价是每次使用SSH Key时都要输一次密码体验稍打折扣。我的建议是个人开发机可以留空方便快捷公司配发的电脑或者有高安全要求的服务器务必设置passphrase。还有一个折中方案是用ssh-agent把解锁过的私钥加载到内存里设置一个较长的存活时间既安全又不用反复输密码。生成完成后再次查看.ssh目录你会看到两个新文件id_ed25519_gitlab # 私钥留在本地 id_ed25519_gitlab.pub # 公钥可以给别人千万记住私钥文件权限应该是600公钥文件权限是644。如果你发现权限不对可以执行chmod 600 ~/.ssh/id_ed25519_gitlab修正。Linux和macOS对密钥文件权限很敏感权限太开放直接拒绝使用。3.3 查看公钥内容的正确姿势公钥文件就是一段纯文本你可以用任何文本编辑器打开。终端里查看最方便cat ~/.ssh/id_ed25519_gitlab.pub输出内容长这样ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINxxxxxxxxxxxxxxxxxxxxx work-laptop从ssh-ed25519开头到最后的备注信息结束这一整行都是公钥。复制的时候要完整复制不能漏掉任何字符尤其不能漏掉开头的算法标识和结尾的注释部分。很多人在这一步翻车复制的时候只复制了一部分导致配置到GitLab上之后一直认证失败。4. 把公钥配置到GitLab3分钟搞定4.1 在GitLab网页上添加公钥登录GitLab后点击右上角的头像在下拉菜单中选择“Preferences”偏好设置这是旧版GitLab的入口。新版GitLab中这个菜单可能叫“Edit Profile”或者直接显示你的用户名。在偏好设置页面左侧菜单中找到“SSH Keys”选项中文界面叫“SSH密钥”。点击进入后你会看到一个表单包含三个字段Key粘贴你刚才复制的完整公钥内容Title给这把Key起个名字方便识别建议格式是“设备名-用途”例如office-pc-main、home-macbook、ci-runnerExpiration date过期日期可选。如果不填就永不过期。出于安全考虑公司服务器或者CI Runner这类长期使用的Key建议设置一个定期轮换的过期时间比如一年填写完成后点击“Add key”绿色按钮页面刷新后你的公钥就出现在密钥列表中了。4.2 验证SSH连接是否正常配置完公钥后别急着克隆代码先验证一下连接是否打通ssh -T gitgitlab.com如果你是连接自己公司内网搭建的GitLab域名换成对应的内网地址比如ssh -T gitgitlab.yourcompany.com第一次连接时系统会提示确认远程主机的指纹信息The authenticity of host gitlab.com (xxx.xxx.xxx.xxx) cant be established. ED25519 key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxx. Are you sure you want to continue connecting (yes/no)?这里输入yes并回车之后系统才会输出连接结果。如果一切正常你会看到类似这样的欢迎信息Welcome to GitLab, yourusername!看到这行字就说明SSH认证已经全部打通接下来就能愉快地克隆和推送代码了。4.3 一次配置管理多个平台密钥的进阶方案很多开发者的实际情况是GitHub有自己的项目公司GitLab有业务代码可能还有一台自己买的云服务器。每个平台需要用不同的SSH Key以免一个私钥泄露导致所有平台全部沦陷。这时候就需要在~/.ssh/config文件里做分流配置。如果.ssh目录下没有这个文件手动创建一个即可。配置内容示例# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github # 公司GitLab Host gitlab.yourcompany.com HostName gitlab.yourcompany.com User git IdentityFile ~/.ssh/id_ed25519_gitlab # 个人云服务器 Host myserver HostName 203.0.113.10 User root IdentityFile ~/.ssh/id_ed25519_server配置完成后SSH客户端会根据你连接的主机名自动匹配对应的私钥互不干扰。这也是我前面强调要为不同平台生成独立Key的原因。5. SSH Key配置完成后日常开发的核心操作5.1 克隆代码SSH链接和HTTPS链接的区分在GitLab项目主页点击“Clone”按钮会弹出两个TabClone with HTTPS和Clone with SSH。如果你完成了上面的SSH配置就直接复制SSH链接。举个例子HTTPS链接长这样https://gitlab.com/yourgroup/project.gitSSH链接长这样gitgitlab.com:yourgroup/project.git克隆命令完全一样git clone gitgitlab.com:yourgroup/project.git区别在哪HTTPS克隆下来之后每次git push可能都要验证身份SSH克隆下来之后push操作全程静默完成不需要手动输入任何凭据。这个差异在日常使用中感知非常明显。5.2 一次完整的代码提交流程配合SSH Key一次标准的代码提交推送流程非常顺畅。假设你已经克隆了项目并且创建了一个新功能分支# 1. 查看当前状态 git status # 2. 添加所有改动到暂存区 git add . # 3. 提交到本地仓库附带清晰的提交信息 git commit -m feat: 添加用户登录功能 # 4. 推送本地分支到远程仓库 git push origin feature-login推送完成后你去GitLab网页上刷新项目页面就能看到远程分支已经更新。之后通常是在网页上发起一个Merge Request合并请求邀请同事评审代码评审通过后合并到主分支。5.3 分支管理创建、切换、合并、删除在实际团队协作中分支操作频率很高。日常常用的命令如下创建并切换到一个新分支git checkout -b feature-xxx切回主分支git checkout main把功能分支合并到当前分支git merge feature-xxx推送本地分支到远程并设置上游跟踪git push -u origin feature-xxx删除本地分支git branch -d feature-xxx删除远程分支git push origin --delete feature-xxx这些命令和是否配置SSH Key没有直接关系但SSH连接让整个流程更顺畅特别是频繁push、pull切换分支的时候不用反复验证身份体验上的提升非常明显。5.4 解决日常开发里最让人头疼的合并冲突冲突是多人协作里完全绕不开的问题。两个人都改了同一个文件的同一段代码Git无法自动合并只能让人工介入。假设你在feature-login分支上修改了Login.java同事在主分支上也改了同一个文件的同一个方法合并时就会出现冲突。解决方案是先把远程主分支的最新代码拉取下来然后在本地解决冲突。# 1. 切到主分支拉取最新代码 git checkout main git pull origin main # 2. 切回功能分支 git checkout feature-login # 3. 把主分支合并到功能分支此时可能产生冲突 git merge main如果冲突产生了Git会在冲突文件中用 HEAD和 main这样的标记把两边的内容标识出来。这时候用VS Code或者其他编辑器打开文件逐处确认保留哪一边的代码、还是两边都保留并手动整合。解决完所有冲突后git add . git commit -m merge: 解决与主分支的冲突 git push origin feature-login这几十行命令覆盖了本地日常开发中最核心的操作流程足够应付绝大多数场景。6. 踩坑经验SSH Key使用中高频出现的几个问题6.1 Permission denied (publickey)这是最经典的报错出现频率堪称SSH问题之王。它表示服务器验证公钥失败可能性很多公钥粘贴的时候漏了字符或者用截图OCR识别导致乱码私钥路径配置错误SSH客户端根本找不到对应的私钥本地.ssh目录下有多个私钥但第一个加载的私钥不是GitLab对应的那把GitLab上的公钥被管理员删除了或者过期了排查思路是先用ssh -T gitgitlab.com查看详细错误信息再用ls -al ~/.ssh确认密钥文件是否存在。如果用多个私钥优先推荐配置~/.ssh/config文件指定IdentityFile。6.2 Host key verification failed这个报错在网络环境变化或服务器重建后经常出现。原因是本地的~/.ssh/known_hosts文件里还保存着旧的主机指纹而服务器端的指纹已经变了SSH发现两者对不上就拒绝继续连接。解决方案很简单用命令删除旧指纹ssh-keygen -R gitlab.com然后重新连接按提示接受新的指纹即可。如果你连接的自建GitLab端口不是22记得额外指定端口ssh -T -p 2222 gitgitlab.yourcompany.com在克隆代码时非标准端口写法也不同git clone ssh://gitgitlab.yourcompany.com:2222/yourgroup/project.git6.3 同一个仓库为什么push还是提示输密码这种情况往往是因为克隆的时候用了HTTPS链接而不是SSH链接。你手上的SSH Key就算配置得再完美HTTPS连接也完全不会使用它。检查方式是命令git remote -v如果输出里remote地址以https://开头说明当前仓库用的是HTTPS方式。改成SSH方式git remote set-url origin gitgitlab.com:yourgroup/project.git之后再push就会走SSH认证不会再输密码。6.4 换新电脑后原来的SSH Key怎么办这是一个高频但很多人操作错误的场景。有人直接把旧电脑的私钥文件拷贝到新电脑这个做法可行但有风险。更规范的做法是旧电脑上如果可能把旧Key从GitLab上删掉防止私钥泄露后被人利用在新电脑上生成全新的Key把新公钥再添加回GitLab如果你的工作同时涉及GitHub和GitLab记得每个平台都用独立的Key不要图省事共用一把这样即使某个平台被打穿其他平台的代码仓库还是安全的。6.5 常见问题速查表我把高频问题和对应解法整理成一张表方便收藏备查问题现象可能原因快速解法Permission denied (publickey)公钥未配置或私钥路径不对重新添加公钥检查IdentityFile配置Host key verification failed服务器指纹变更ssh-keygen -R gitlab.com后重连push仍提示输密码仓库用的是HTTPS地址git remote set-url origin改SSH地址多个Key对不上号没有配置~/.ssh/config按Host指定各自的IdentityFile连接超时或卡住网络不通或端口被防火墙拦截检查22端口连通性或改用443端口GitLab提示Key已过期Key设置了Expiration date在GitLab上更新Key并重新配置6.6 几个独家避坑小技巧第一~/.ssh目录的权限一定要正确。私钥文件权限如果是664或777SSH会直接拒绝使用并提示Permissions 0664 for id_ed25519 are too open。新生成的文件默认权限是对的但如果从别人那儿拷贝了密钥文件过来这个坑特别容易踩。第二CI/CD环境里使用SSH Key时不要把私钥直接硬编码到gitlab-ci.yml文件里而应该使用GitLab的CI/CD变量Settings - CI/CD - Variables来存储私钥内容流水线里用echo $SSH_PRIVATE_KEY注入到环境变量中避免密钥泄露到代码仓库。第三GitLab管理员在后台能看到每个账号加载了哪些Key建议定期梳理账号下的密钥列表及时删掉已经不再使用的设备Key。我给公司的建议是每半年做一次密钥巡检宁可让同事重新配置一遍也不能留下无人认领的“僵尸Key”。7. 从SSH Key往后走GitLab的更多可能性7.1 当SSH Key遇到CI/CD自动化很多团队用GitLab不只是为了管代码还会借助GitLab CI/CD实现自动构建和部署。流水线里Runner在拉取代码的时候用的就是SSH认证。简单说下流程GitLab Runner是一个独立服务它可以从GitLab服务器接收构建任务。Runner执行任务时需要把代码仓库拉取到执行机这时候Runner机器上就要配置能访问对应项目的SSH Key。踩过的坑是Runner的SSH Key不能和个人开发机的Key共用应该单独生成一把独立的Key并且把公钥添加到一个专门为CI创建的GitLab账号上或者用Deploy Key的方式只授权某个特定的仓库。否则一旦Runner的执行机被入侵你的个人GitLab账号也会跟着遭殃。7.2 用Deploy Key实现仓库级别的访问控制GitLab提供了一种叫Deploy Key的功能它绑定的是仓库而不是个人账号。也就是说你可以为某一个特定仓库单独生成一对Key公钥配置到仓库的Settings - Repository - Deploy Keys中。这样CI Runner或者某台服务器只能访问这一个仓库即使密钥泄露攻击者也进不了你的个人账号和其他项目。这是我在实践中最推荐的CI认证方案安全边界非常清晰。7.3 本地多账号场景的最终解法如果你手里同时维护着GitHub、公司GitLab、个人GitLab等多个代码平台前面提到的~/.ssh/config方案是目前最优雅的解法之一。我再给出一个常见配置片段Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/id_ed25519_personal配置完成后无论你连接哪个平台SSH都会自动选择对应的私钥完全无感切换。这个方案配合SSH Key使用基本可以覆盖开发者日常工作中的绝大多数认证场景。8. 关于SSH Key安全最后想多说几句SSH Key是本地机器和GitLab之间的唯一身份凭证私钥一旦泄露别人就能登录你的GitLab账号拉取你所有的私有仓库甚至以你的名义推送恶意代码。这个后果非常严重因为代码仓库是公司最核心的资产之一。几个安全习惯强烈建议养成私钥不要通过即时通讯工具、邮件或网盘传输。如果需要在新电脑上配置请在新电脑上现场生成新Key不要跨机器拷贝私钥文件。定期检查GitLab账号里的Key列表删除不再使用的设备Key。特别是离职员工的设备管理员要及时清除。可以给Key设置Expiration date。虽然到期续期稍微麻烦一点但这个麻烦是值得的它能保证即使密钥被泄露也只是一个短期有效的泄漏。执行重要操作之前先确认一下自己当前用的是哪把Key。命令行可以快速查看ssh -T gitgitlab.com如果输出里的用户名不是你以为的那个人那就要立刻停下来排查千万别继续操作。我在实际维护公司GitLab的过程中遇到过太多因为SSH Key配置不当引发的生产事故有开发者的私钥泄露到公开仓库导致代码被爬走有CI Runner因为Key过期导致整条流水线崩溃还有同事把多个平台的Key混用导致权限混乱。这些问题一旦发生排查起来往往比直接配置还要费时。所以宁可在一开始多花十分钟把Key管理好也别等出了问题再回头补救。SSH Key这个东西配置一次受益几年但前提是你真的把它当回事儿来对待。