说个我自己的真实经历。用GitLab干活的时候最烦人的不是写代码而是每次push或者clone都要输一遍账号密码。尤其是公司开了两步验证之后密码干脆用不了得去后台生成personal access token那串token又长又乱复制粘贴都容易出错。最崩溃的是token还有有效期过期一次就得重新生成一次、重新配置一次浪费时间不说还特别容易在忙的时候打断思路。后来我把本地的Git操作全部切到SSH key认证这个问题才算彻底根治——push、pull、clone全程免密不会再被任何登录弹窗打断。这篇内容就围绕配置GitLab的SSH key这件事把从密钥原理、生成步骤、GitLab后台配置、连接验证到日常排错的完整链路讲清楚。适合刚接触GitLab、正在被HTTPS认证折磨的新手也适合已经配过SSH key但偶尔还是会碰到Permission denied的老手。看完至少能少踩一半的坑。1. 为什么要给GitLab配SSH key先搞懂它到底省了什么很多人第一反应是我直接用HTTPS地址clone也能用干嘛非要折腾SSH key说实话如果只是偶尔clone一个公开仓库HTTPS确实够用。但只要你是长期在GitLab上提交代码的人HTTPS方式的痛点会随着使用频率直线上升。1.1 HTTPS方式每天都在折磨你什么用HTTPS地址clone仓库之后每次git push或者git pullGit都会要求你验证身份。最常见的流程是弹出用户名、密码输入框你得手动填。如果账号开了两步验证密码框还要填personal access token不是登录密码本身。这个token在GitLab后台的Access Tokens页面生成生成的时候要选权限范围、设过期时间稍不留神就配错。更麻烦的是很多公司的安全策略要求定期重置密码或者轮换token。这意味着你正在写代码写到一半突然一次push失败提示认证过期。你又得放下手头的活去后台搞一个新token再回到终端重新push。这种事情一个月来几次效率直接被打没。还有一个隐形坑如果本机的Git配置里缓存了旧凭据换token之后经常出现明明新密码对了却一直报认证失败的诡异问题得手动清理Windows凭据管理器或者macOS钥匙串里的旧记录排查起来非常心累。1.2 SSH认证的核心逻辑一把公钥锁一把私钥钥匙SSH key之所以省事是因为它换了一种完全不同的认证思路。它不再需要用户名密码这种每次都要传递的信息而是用一对密钥完成身份验证。这对密钥包含两个文件公钥xxx.pub和私钥没有后缀名的那一个。公钥可以放心地交给任何人、贴到任何服务器上它相当于一把挂锁私钥是你手里唯一的钥匙必须牢牢锁在自己电脑里绝对不能泄露。具体到GitLab的场景里流程是这样的你在本地生成一对密钥把公钥内容贴到GitLab后台的SSH Keys页面。GitLab记住了你的公钥并在后台把公钥和你的账号绑定。你执行git push时本机Git会向GitLab发起SSH连接。GitLab收到连接请求后会用你预先贴好的公钥生成一个加密挑战。只有持有对应私钥的电脑才能正确回应这个挑战。本机私钥自动完成签名GitLab验证签名通过连接就建立了。整个过程不需要输入任何密码私钥也始终留在本机不会在网络上传输入传输过私钥本身。网络上传送的只是签名结果即使有人抓包也拿不到能冒充你的东西。我把这个机制理解成门禁卡和门锁的关系公钥是门禁系统里登记的那张卡号私钥是你口袋里真正能刷开门的那张卡。系统验证的是你手里有没有这张卡而不是每次进门都重新报一遍卡号。1.3 配置一次受用很久SSH key配置好之后同一台电脑上所有指向该GitLab实例的操作都不再需要认证。换分支、pull、push、clone私有仓库全部静默通过。哪怕你在终端里开了几个不同的项目目录也不需要重复配置。而且SSH key的适用范围不局限于GitLab。GitHub、Gitea、Bitbucket这些Git托管平台底层走的都是同一套SSH公钥认证逻辑。在GitLab上学到的这套配置方法换到其他平台照样能用只是后台粘贴公钥的入口位置略有差别。所以我一直建议新手别嫌麻烦花十分钟配好SSH key之后省下的时间是按小时算的。2. 动手之前检查你机器上到底有没有现成的密钥很多教程上来就让你执行ssh-keygen生成新密钥但我建议先停一下看看机器上是不是已经有密钥了。盲目生成新密钥会埋下一个隐患如果之前已经有一把正在使用的私钥新生成的密钥会把事情搞混特别是当你搞不清GitLab后台到底贴的是哪把公钥的时候。2.1 找到隐藏的.ssh目录SSH的密钥默认存放在用户主目录下的.ssh隐藏文件夹里。不同操作系统进入这个目录的方式略有不同操作系统路径快速访问方式Windows 10/11C:\Users\你的用户名\.ssh文件资源管理器地址栏直接输入%userprofile%\.sshmacOS/Users/你的用户名/.ssh终端执行cd ~/.sshLinux/home/你的用户名/.ssh终端执行cd ~/.ssh检查当前是否已有密钥建议直接执行ls -la ~/.ssh然后看输出结果里有哪些文件。正常的密钥文件一般是成对出现的id_ed25519id_ed25519.pub或者id_rsaid_rsa.pub带.pub后缀的是公钥没有后缀的是私钥。2.2 已有的密钥怎么判断还能不能用如果看到上面这些文件说明你之前可能已经生成过SSH key。这时候不要急着删先用cat看一下公钥内容cat ~/.ssh/id_ed25519.pub公钥内容是一串以ssh-ed25519或ssh-rsa开头的文本结尾通常是生成时填写的注释一般是邮箱地址。你可以把这段内容和GitLab后台SSH Keys页面里已有的公钥对比一下如果完全一致说明这把钥匙已经配置过了直接跳到第5章的验证部分就行。这里要提醒一个关键点如果.ssh目录里的密钥文件是很多年前生成的而且算法是RSA 1024位建议直接废弃重生成。1024位的RSA密钥在现代安全标准下已经偏弱能不用就别用。另外还要留意一种情况有的同事习惯把公司电脑的所有平台账号都用同一把密钥。这个做法省事但风险不小——一旦这台电脑的私钥泄露所有平台的账号都跟着遭殃。我的建议是不同平台、不同用途各配一把单独的密钥宁可多生成几把也别一把钥匙开所有锁。3. 生成新密钥的实操细节参数、算法和使用意图确认没有现成密钥或者决定为GitLab单独生成一把新密钥之后就可以执行ssh-keygen了。这一步看起来简单其实算法、文件名、注释、passphrase这几个参数都值得认真对待。3.1 用ed25519还是RSA我为什么这样选我看到网上大量教程还在用ssh-keygen -t rsa -b 4096这个写法没错但放到今天已经不是最优解了。GitLab和主流Git版本很早就都支持了ed25519算法这种算法的签名更短、生成速度更快安全性上目前也没有已知的实质缺陷完全可以作为默认选择。算法密钥长度公钥长度兼容性推荐度ed25519固定256位较短68字节左右主流平台均支持推荐RSA通常2048或4096位较长数百字节兼容老系统、老平台按需选用当然如果你所在的公司内网GitLab是很老的版本或者运维明确说服务器上的SSH服务不支持ed25519那就退回RSA 4096。判断依据很简单先试ed25519如果连接时报no matching key exchange method之类的错误再改用RSA也不迟。3.2 生成命令和每个参数的含义建议用下面的命令生成一把专门给GitLab用的密钥ssh-keygen -t ed25519 -C youexample.com -f ~/.ssh/gitlab_ed25519逐个解释一下这条命令的参数-t ed25519指定密钥算法为ED25519。-C youexample.com给公钥加一个注释。习惯上填你的邮箱纯属为了自己识别并不参与验证逻辑。填什么都行但最好一眼能看出这把密钥是谁的。-f ~/.ssh/gitlab_ed25519指定密钥文件的保存路径和文件名。这里我刻意没有使用默认的id_ed25519而是用了gitlab_ed25519这个名字目的是让你这台机器上再多平台、多密钥时每把钥匙身份明确不会互相覆盖。执行命令后终端会提示你设置passphrase密钥口令Enter passphrase (empty for no passphrase):这里可以有两种选择。直接回车不设口令最方便push的时候完全静默但代价是如果有人拿到了你的私钥文件可以直接用不需要额外密码。我建议设置一个简单的passphrase成本只是每次使用前多输入一次而且可以配合后面要讲的ssh-agent让这个步骤也省掉。确认输入口令后系统还会要求再输一遍。之后.ssh目录下应该多出两个文件gitlab_ed25519和gitlab_ed25519.pub。3.3 把私钥交给ssh-agent托管如果你设置了passphrase每个SSH连接都要求输入一次口令用多了也会烦。这时候可以借助ssh-agent这个系统组件它负责把私钥加载到内存里之后同一会话内所有SSH连接自动使用加载好的密钥不再反复问你口令。macOS和Linux终端直接执行eval $(ssh-agent -s) ssh-add ~/.ssh/gitlab_ed25519Windows用户比较复杂一些。如果你用的是Git Bash命令和上面基本一致。如果你用的是PowerShell可以这样操作Get-Service ssh-agent | Set-Service -StartupType Manual Start-Service ssh-agent ssh-add $env:USERPROFILE\.ssh\gitlab_ed25519Windows 10/11自带的OpenSSH组件在默认情况下ssh-agent服务是关闭的需要手动启动。这一步属于可选优化如果你不设passphrase完全可以跳过。补充一个我自己的习惯macOS下我还会用ssh-add --apple-use-keychain ~/.ssh/gitlab_ed25519把密钥加载进系统钥匙串这样可以跨终端会话保持加载状态不用每次开终端都重新执行ssh-add。4. 把公钥交给GitLab粘贴步骤和权限范围密钥生成好了接下来就是把公钥内容贴到GitLab后台。这一步操作不复杂但很多人的问题恰恰出在这里——贴错了内容、漏了字符、粘贴时带了多余换行都会导致后面连接失败。4.1 公钥内容在哪里看怎么复制才不出错公钥文件就是上一步生成的gitlab_ed25519.pub。查看内容用cat命令最直接cat ~/.ssh/gitlab_ed25519.pub终端会输出一整行的公钥文本以ssh-ed25519开头以你生成时填的邮箱或其他注释结尾。复制的时候务必整行一次复制完整头尾都不能缺。这里有个非常容易踩的坑千万不要用Windows的记事本打开.pub文件再复制。记事本有时会把单行公钥显示成多行你手动框选的时候很容易漏掉中间的字符或者把看不见的换行符一起带进去粘贴到GitLab后服务端读取到的内容就不对了。用cat命令或者VS Code这类现代编辑器查看才是最稳的。公钥粘贴完成后自己核对一遍字符串开头必须是ssh-ed25519或ssh-rsa结尾必须是你自己填的注释。如果结尾变成了奇怪的空格或者多了一个换行GitLab虽然能保存但验证时大概率不通过。4.2 GitLab设置页里的Title和Expiration date怎么填登录GitLab右上角点头像进入Preferences / 偏好设置然后找到左侧的SSH Keys菜单。如果你用的GitLab版本比较老这个入口可能在Profile Settings / 个人资料设置下面但新版基本都统一到了Preferences里。打开SSH Keys页面后会看到这几个输入框Key粘贴你刚刚复制的公钥整行内容。Title给这把钥匙起个名字建议写成设备名用途这种能想起它是谁的格式。比如我用的是macbook-pro-work-gitlab或者windows-desktop-home。这个Title只影响你在后台识别不参与验证逻辑但多台电脑同时配key的时候没有好名字会让你想不起来哪把钥匙在哪台机器上。Expiration date可选字段设置过期时间。如果这是公司要求的安全策略就按周期填如果是个人长期使用的GitLab实例我建议留空省得到期时突然推不了代码又得临时换钥。当然安全要求严格的公司应该让你填那就按公司规矩来。填完点击Add key按钮GitLab后台就会保存这把公钥并和你的账号绑定。4.3 添加完后的后台确认添加成功后SSH Keys列表里会多出一行显示Title、指纹和添加时间。建议你顺手把页面上显示的指纹Fingerprint和本地公钥生成的指纹对比一下。本地查看指纹的命令ssh-keygen -lf ~/.ssh/gitlab_ed25519.pub输出结果类似256 SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx youexample.com (ED25519)如果后台页面显示的指纹和这串一致说明粘贴过程一切正确接下来可以放心测试连接了。5. 验证是否配置成功ssh -T 到底在干什么公钥贴好之后先别急着clone仓库先用GitLab官方提供的测试连接命令验证一下。这才是确认整条链路是否通畅的最快方式。5.1 测试命令和执行结果解读在终端执行ssh -T gitgitlab.com这里的gitgitlab.com分为两部分git是连接GitLab SSH服务的固定用户名不是你的账号名gitlab.com是你所用的GitLab实例的域名。如果你们公司用的是内网自建GitLab就替换成对应的内网地址比如ssh -T gitgitlab.example.com。第一次连接时可能会提示确认远程主机的指纹输入yes回车继续。如果一切正常你会看到类似这样的输出Welcome to GitLab, yourusername!出现这行字说明SSH key配置已经成功GitLab已经识别出了你对应的账号。这里解释一下为什么要带-T参数。-T表示不向SSH服务器请求分配终端tty因为GitLab的SSH服务只用于Git协议传输不提供交互式shell。如果不带-T部分版本的SSH客户端会尝试申请终端GitLab服务端处理不了反而会报错。5.2 连接成功后clone地址怎么选才对验证通过之后clone仓库时就要用SSH地址而不是HTTPS地址。在GitLab的仓库页面上点击Clone按钮后会看到两个地址选项HTTPS地址形如https://gitlab.com/username/repo.gitSSH地址形如gitgitlab.com:username/repo.git直接复制SSH地址来clonegit clone gitgitlab.com:username/repo.git之后在这个仓库里的所有push和pull操作就都是免密状态了。另外要说一个我在实际中反复遇到的场景很多人给GitLab配好了SSH key但克隆仓库时手滑复制了HTTPS地址。这样就导致这个仓库的remote地址一直是HTTPS协议的之后每次操作依然会要求输入密码。明明SSH配置成功了却完全没生效特别可惜。如果你已经遇到过这个问题直接把已有仓库的remote地址改成SSH格式即可git remote set-url origin gitgitlab.com:username/repo.git改完再执行一次git remote -v确认地址变成了git开头后续操作就彻底走SSH通道了。5.3 测试失败时的常见输出长什么样配置出问题时的输出通常是这样gitgitlab.com: Permission denied (publickey).这句话的意思是SSH握手过程中服务器没有接受你的公钥认证。导致这个结果的原因有几种——公钥没贴对、贴的密钥与本地使用的私钥不匹配、SSH客户端没走你粘贴的那把密钥。遇到这条报错先别慌下一步就是标准的排查流程。6. 配置完就完事了吗日常使用中的几个高频坑SSH key配置本身不难难的是配置完成后那些时不时冒出来的问题。这里把我实际踩过、也给同事排查过的一些高频坑集中整理一下每一个都是真实场景。6.1 Permission denied (publickey) 的排查链路遇到权限报错我的固定排查思路是先用verbose模式看SSH客户端到底在尝试用哪把密钥ssh -vT gitgitlab.com注意这里的-v参数它会打印整个SSH握手过程的调试日志。输出会很长不用全看重点是找这几行信息debug1: Offering public key: /Users/you/.ssh/id_ed25519 ED25519 SHA256:xxxx debug1: Authentications that can continue: publickey debug1: Trying private key: /Users/you/.ssh/gitlab_ed25519第一行已经明确告诉你客户端正在尝试哪个私钥文件。如果你看到它尝试的是id_ed25519而你在GitLab后台粘贴的是gitlab_ed25519.pub里面的内容那问题就清楚了——本地默认使用的密钥和后台贴的公钥不是同一对。解决办法有两个思路。第一个干脆把后台公钥换成本地默认密钥对应的公钥第二个是写一个~/.ssh/config配置告诉SSH客户端连gitlab.com这个主机时使用指定的密钥文件Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yes把这段追加到~/.ssh/config文件里没有这个文件就新建一个然后再次执行ssh -T gitgitlab.com测试。IdentitiesOnly yes尤其重要——它强制SSH客户端只使用配置里指定的密钥文件不要逐个尝试当前agent里加载的所有密钥避免因为客户端默认尝试了错误的密钥导致认证失败。6.2 一台电脑多把SSH key和多平台账号怎么管理很多人会同时用GitLab和GitHub甚至公司内网还有一个自建的GitLab实例。这种情况下每个平台各配一把独立的密钥是最稳妥的做法。我现在的~/.ssh/config实际长这样Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yes Host github.com HostName github.com User git IdentityFile ~/.ssh/github_ed25519 IdentitiesOnly yes Host gitlab.intra HostName 172.16.x.x User git IdentityFile ~/.ssh/gitlab_intra_ed25519 IdentitiesOnly yes几个细节解释一下。Host后面的名字是你在git clone地址里写的那段主机名。比如你想用gitgitlab.intra:team/repo.git这种地址连接内网GitLab那么Host就要写成gitlab.intraHostName写真实的IP或域名。这样的好处是即使在公司的内网环境里也能靠config自动命中正确的私钥不用每次手动指定-i参数。另外多个平台各自独立密钥还有一个实际好处如果某一天GitHub的密钥出了问题你只需要在GitHub后台删掉对应公钥、重新生成一把完全不影响GitLab的使用。共用一把密钥的话任何一个平台出问题都要全部重来。6.3 Windows环境下那些绕不开的坑Windows用户配置SSH key总要多踩几个坑这里专门列一下。第一个坑是私钥文件权限。OpenSSH在Windows上对私钥文件权限很挑剔。如果C:\Users\你的用户名\.ssh目录的权限设置得过于宽松比如允许Everyone组访问SSH客户端会直接拒绝加载私钥报错内容类似Bad permissions。解决办法是给.ssh目录收紧权限右键目录 → 属性 → 安全 → 高级把继承的权限全部移除然后只保留当前用户自己的完全控制权限。操作完再重新打开终端测试问题通常就消失了。第二个坑是换行符混入公钥。前面提到过别用记事本打开.pub文件复制公钥。Windows的记事本对Unix风格换行的处理一直有历史遗留问题视觉上是一行实际复制时可能带入隐蔽的控制字符。还是用cat命令配合终端复制或者用VS Code打开并把右下角的文件编码确认成UTF-8。第三个坑是多套OpenSSH并存。Windows 10/11自带OpenSSH客户端Git for Windows的安装选项里也可以勾选Use Git and optional Unix tools from the Command Prompt这会在PATH里加入自己的SSH程序。两套SSH混着用有时候会出现Git Bash里能连PowerShell里连不上或者反过来。建议统一环境要么在PowerShell里用系统的ssh要么在Git Bash里用Git自带的ssh别混着来。第四个坑比较隐蔽和配置无关但会影响使用体验如果Windows用户名是中文.ssh路径里会带着中文字符某些老版本的SSH工具解析路径可能出错。这种情况可以考虑把密钥文件放到一个纯英文路径然后通过config文件里的IdentityFile指定绝对路径绕过去。6.4 密钥泄露或者换电脑时的处理思路最后聊聊两个不怎么常见但一旦遇到就很棘手的情况。第一是怀疑私钥泄露。私钥文件一旦泄露留在GitLab后台的公钥已经没有意义。正确做法是登录GitLab后台在SSH Keys页面把对应的公钥删除然后重新执行第3章的步骤生成新的密钥对把新公钥再贴上去。整个过程耗时不超过五分钟比纠结到底有没有泄露、要不要换要稳妥得多。第二是换一台新电脑。新电脑上没有你原来的私钥原来的公钥贴在GitLab后台这个是配对的新电脑连不上。处理方式其实很简单新电脑上生成一把全新的密钥然后把新公钥加到GitLab后台旧电脑对应的旧公钥顺手删掉。不用把旧电脑的私钥拷过来——这是安全上的红线私钥文件在任何情况下都不应该通过网盘、聊天工具、邮件传来传去。拷贝私钥相当于把家里的钥匙复印一份交给别人风险太大。另外提一句如果你之前配置过一台旧电脑且现在已经不用了记得去GitLab后台把旧设备绑定的公钥删掉。留着只是当时图省事后面旧设备丢了、二手转卖时才想起来就来不及了。这个习惯和你离开公司时注销旧账号一个道理属于基本的安全素养。最后分享一个我自己的体会配置GitLab SSH key这件事本质上是花十分钟换未来无数个免密操作的体验。把流程拆解开来就三步生成密钥、贴公钥、测连接。每一步都有各自的坑但那些坑几乎都是原理不清楚造成的。搞清楚SSH公私钥机制再回头看报错日志里的Offering public key那行字基本上自己就能定位问题在哪。我自己后来帮同事排查时发现超过一半的Permission denied问题根因都是本地有多把密钥但默认尝试的那一把不是GitLab后台贴的那一把。所以如果你以后也遇到莫名其妙的认证失败先别急着重新生成密钥先加个-v参数看一眼日志十次里有八次能直接看出端倪。最后再补充一个实用的好习惯把ssh -T gitgitlab.com这个验证命令记在笔记里。以后新配环境、遇到问题、甚至怀疑是不是密钥过期了第一时间跑一下几秒钟就能判断出是网络问题、配置问题还是GitLab服务端的问题。只有把验证命令用到形成肌肉记忆SSH这个方案的省心优势才算真正发挥出来。 
长河君 · 2026/10/18 3:44:12 · 阅读 1.2k GitLab SSH Key配置详解：从原理到排错，彻底告别密码认证
说个我自己的真实经历。用GitLab干活的时候最烦人的不是写代码而是每次push或者clone都要输一遍账号密码。尤其是公司开了两步验证之后密码干脆用不了得去后台生成personal access token那串token又长又乱复制粘贴都容易出错。最崩溃的是token还有有效期过期一次就得重新生成一次、重新配置一次浪费时间不说还特别容易在忙的时候打断思路。后来我把本地的Git操作全部切到SSH key认证这个问题才算彻底根治——push、pull、clone全程免密不会再被任何登录弹窗打断。这篇内容就围绕配置GitLab的SSH key这件事把从密钥原理、生成步骤、GitLab后台配置、连接验证到日常排错的完整链路讲清楚。适合刚接触GitLab、正在被HTTPS认证折磨的新手也适合已经配过SSH key但偶尔还是会碰到Permission denied的老手。看完至少能少踩一半的坑。1. 为什么要给GitLab配SSH key先搞懂它到底省了什么很多人第一反应是我直接用HTTPS地址clone也能用干嘛非要折腾SSH key说实话如果只是偶尔clone一个公开仓库HTTPS确实够用。但只要你是长期在GitLab上提交代码的人HTTPS方式的痛点会随着使用频率直线上升。1.1 HTTPS方式每天都在折磨你什么用HTTPS地址clone仓库之后每次git push或者git pullGit都会要求你验证身份。最常见的流程是弹出用户名、密码输入框你得手动填。如果账号开了两步验证密码框还要填personal access token不是登录密码本身。这个token在GitLab后台的Access Tokens页面生成生成的时候要选权限范围、设过期时间稍不留神就配错。更麻烦的是很多公司的安全策略要求定期重置密码或者轮换token。这意味着你正在写代码写到一半突然一次push失败提示认证过期。你又得放下手头的活去后台搞一个新token再回到终端重新push。这种事情一个月来几次效率直接被打没。还有一个隐形坑如果本机的Git配置里缓存了旧凭据换token之后经常出现明明新密码对了却一直报认证失败的诡异问题得手动清理Windows凭据管理器或者macOS钥匙串里的旧记录排查起来非常心累。1.2 SSH认证的核心逻辑一把公钥锁一把私钥钥匙SSH key之所以省事是因为它换了一种完全不同的认证思路。它不再需要用户名密码这种每次都要传递的信息而是用一对密钥完成身份验证。这对密钥包含两个文件公钥xxx.pub和私钥没有后缀名的那一个。公钥可以放心地交给任何人、贴到任何服务器上它相当于一把挂锁私钥是你手里唯一的钥匙必须牢牢锁在自己电脑里绝对不能泄露。具体到GitLab的场景里流程是这样的你在本地生成一对密钥把公钥内容贴到GitLab后台的SSH Keys页面。GitLab记住了你的公钥并在后台把公钥和你的账号绑定。你执行git push时本机Git会向GitLab发起SSH连接。GitLab收到连接请求后会用你预先贴好的公钥生成一个加密挑战。只有持有对应私钥的电脑才能正确回应这个挑战。本机私钥自动完成签名GitLab验证签名通过连接就建立了。整个过程不需要输入任何密码私钥也始终留在本机不会在网络上传输入传输过私钥本身。网络上传送的只是签名结果即使有人抓包也拿不到能冒充你的东西。我把这个机制理解成门禁卡和门锁的关系公钥是门禁系统里登记的那张卡号私钥是你口袋里真正能刷开门的那张卡。系统验证的是你手里有没有这张卡而不是每次进门都重新报一遍卡号。1.3 配置一次受用很久SSH key配置好之后同一台电脑上所有指向该GitLab实例的操作都不再需要认证。换分支、pull、push、clone私有仓库全部静默通过。哪怕你在终端里开了几个不同的项目目录也不需要重复配置。而且SSH key的适用范围不局限于GitLab。GitHub、Gitea、Bitbucket这些Git托管平台底层走的都是同一套SSH公钥认证逻辑。在GitLab上学到的这套配置方法换到其他平台照样能用只是后台粘贴公钥的入口位置略有差别。所以我一直建议新手别嫌麻烦花十分钟配好SSH key之后省下的时间是按小时算的。2. 动手之前检查你机器上到底有没有现成的密钥很多教程上来就让你执行ssh-keygen生成新密钥但我建议先停一下看看机器上是不是已经有密钥了。盲目生成新密钥会埋下一个隐患如果之前已经有一把正在使用的私钥新生成的密钥会把事情搞混特别是当你搞不清GitLab后台到底贴的是哪把公钥的时候。2.1 找到隐藏的.ssh目录SSH的密钥默认存放在用户主目录下的.ssh隐藏文件夹里。不同操作系统进入这个目录的方式略有不同操作系统路径快速访问方式Windows 10/11C:\Users\你的用户名\.ssh文件资源管理器地址栏直接输入%userprofile%\.sshmacOS/Users/你的用户名/.ssh终端执行cd ~/.sshLinux/home/你的用户名/.ssh终端执行cd ~/.ssh检查当前是否已有密钥建议直接执行ls -la ~/.ssh然后看输出结果里有哪些文件。正常的密钥文件一般是成对出现的id_ed25519id_ed25519.pub或者id_rsaid_rsa.pub带.pub后缀的是公钥没有后缀的是私钥。2.2 已有的密钥怎么判断还能不能用如果看到上面这些文件说明你之前可能已经生成过SSH key。这时候不要急着删先用cat看一下公钥内容cat ~/.ssh/id_ed25519.pub公钥内容是一串以ssh-ed25519或ssh-rsa开头的文本结尾通常是生成时填写的注释一般是邮箱地址。你可以把这段内容和GitLab后台SSH Keys页面里已有的公钥对比一下如果完全一致说明这把钥匙已经配置过了直接跳到第5章的验证部分就行。这里要提醒一个关键点如果.ssh目录里的密钥文件是很多年前生成的而且算法是RSA 1024位建议直接废弃重生成。1024位的RSA密钥在现代安全标准下已经偏弱能不用就别用。另外还要留意一种情况有的同事习惯把公司电脑的所有平台账号都用同一把密钥。这个做法省事但风险不小——一旦这台电脑的私钥泄露所有平台的账号都跟着遭殃。我的建议是不同平台、不同用途各配一把单独的密钥宁可多生成几把也别一把钥匙开所有锁。3. 生成新密钥的实操细节参数、算法和使用意图确认没有现成密钥或者决定为GitLab单独生成一把新密钥之后就可以执行ssh-keygen了。这一步看起来简单其实算法、文件名、注释、passphrase这几个参数都值得认真对待。3.1 用ed25519还是RSA我为什么这样选我看到网上大量教程还在用ssh-keygen -t rsa -b 4096这个写法没错但放到今天已经不是最优解了。GitLab和主流Git版本很早就都支持了ed25519算法这种算法的签名更短、生成速度更快安全性上目前也没有已知的实质缺陷完全可以作为默认选择。算法密钥长度公钥长度兼容性推荐度ed25519固定256位较短68字节左右主流平台均支持推荐RSA通常2048或4096位较长数百字节兼容老系统、老平台按需选用当然如果你所在的公司内网GitLab是很老的版本或者运维明确说服务器上的SSH服务不支持ed25519那就退回RSA 4096。判断依据很简单先试ed25519如果连接时报no matching key exchange method之类的错误再改用RSA也不迟。3.2 生成命令和每个参数的含义建议用下面的命令生成一把专门给GitLab用的密钥ssh-keygen -t ed25519 -C youexample.com -f ~/.ssh/gitlab_ed25519逐个解释一下这条命令的参数-t ed25519指定密钥算法为ED25519。-C youexample.com给公钥加一个注释。习惯上填你的邮箱纯属为了自己识别并不参与验证逻辑。填什么都行但最好一眼能看出这把密钥是谁的。-f ~/.ssh/gitlab_ed25519指定密钥文件的保存路径和文件名。这里我刻意没有使用默认的id_ed25519而是用了gitlab_ed25519这个名字目的是让你这台机器上再多平台、多密钥时每把钥匙身份明确不会互相覆盖。执行命令后终端会提示你设置passphrase密钥口令Enter passphrase (empty for no passphrase):这里可以有两种选择。直接回车不设口令最方便push的时候完全静默但代价是如果有人拿到了你的私钥文件可以直接用不需要额外密码。我建议设置一个简单的passphrase成本只是每次使用前多输入一次而且可以配合后面要讲的ssh-agent让这个步骤也省掉。确认输入口令后系统还会要求再输一遍。之后.ssh目录下应该多出两个文件gitlab_ed25519和gitlab_ed25519.pub。3.3 把私钥交给ssh-agent托管如果你设置了passphrase每个SSH连接都要求输入一次口令用多了也会烦。这时候可以借助ssh-agent这个系统组件它负责把私钥加载到内存里之后同一会话内所有SSH连接自动使用加载好的密钥不再反复问你口令。macOS和Linux终端直接执行eval $(ssh-agent -s) ssh-add ~/.ssh/gitlab_ed25519Windows用户比较复杂一些。如果你用的是Git Bash命令和上面基本一致。如果你用的是PowerShell可以这样操作Get-Service ssh-agent | Set-Service -StartupType Manual Start-Service ssh-agent ssh-add $env:USERPROFILE\.ssh\gitlab_ed25519Windows 10/11自带的OpenSSH组件在默认情况下ssh-agent服务是关闭的需要手动启动。这一步属于可选优化如果你不设passphrase完全可以跳过。补充一个我自己的习惯macOS下我还会用ssh-add --apple-use-keychain ~/.ssh/gitlab_ed25519把密钥加载进系统钥匙串这样可以跨终端会话保持加载状态不用每次开终端都重新执行ssh-add。4. 把公钥交给GitLab粘贴步骤和权限范围密钥生成好了接下来就是把公钥内容贴到GitLab后台。这一步操作不复杂但很多人的问题恰恰出在这里——贴错了内容、漏了字符、粘贴时带了多余换行都会导致后面连接失败。4.1 公钥内容在哪里看怎么复制才不出错公钥文件就是上一步生成的gitlab_ed25519.pub。查看内容用cat命令最直接cat ~/.ssh/gitlab_ed25519.pub终端会输出一整行的公钥文本以ssh-ed25519开头以你生成时填的邮箱或其他注释结尾。复制的时候务必整行一次复制完整头尾都不能缺。这里有个非常容易踩的坑千万不要用Windows的记事本打开.pub文件再复制。记事本有时会把单行公钥显示成多行你手动框选的时候很容易漏掉中间的字符或者把看不见的换行符一起带进去粘贴到GitLab后服务端读取到的内容就不对了。用cat命令或者VS Code这类现代编辑器查看才是最稳的。公钥粘贴完成后自己核对一遍字符串开头必须是ssh-ed25519或ssh-rsa结尾必须是你自己填的注释。如果结尾变成了奇怪的空格或者多了一个换行GitLab虽然能保存但验证时大概率不通过。4.2 GitLab设置页里的Title和Expiration date怎么填登录GitLab右上角点头像进入Preferences / 偏好设置然后找到左侧的SSH Keys菜单。如果你用的GitLab版本比较老这个入口可能在Profile Settings / 个人资料设置下面但新版基本都统一到了Preferences里。打开SSH Keys页面后会看到这几个输入框Key粘贴你刚刚复制的公钥整行内容。Title给这把钥匙起个名字建议写成设备名用途这种能想起它是谁的格式。比如我用的是macbook-pro-work-gitlab或者windows-desktop-home。这个Title只影响你在后台识别不参与验证逻辑但多台电脑同时配key的时候没有好名字会让你想不起来哪把钥匙在哪台机器上。Expiration date可选字段设置过期时间。如果这是公司要求的安全策略就按周期填如果是个人长期使用的GitLab实例我建议留空省得到期时突然推不了代码又得临时换钥。当然安全要求严格的公司应该让你填那就按公司规矩来。填完点击Add key按钮GitLab后台就会保存这把公钥并和你的账号绑定。4.3 添加完后的后台确认添加成功后SSH Keys列表里会多出一行显示Title、指纹和添加时间。建议你顺手把页面上显示的指纹Fingerprint和本地公钥生成的指纹对比一下。本地查看指纹的命令ssh-keygen -lf ~/.ssh/gitlab_ed25519.pub输出结果类似256 SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx youexample.com (ED25519)如果后台页面显示的指纹和这串一致说明粘贴过程一切正确接下来可以放心测试连接了。5. 验证是否配置成功ssh -T 到底在干什么公钥贴好之后先别急着clone仓库先用GitLab官方提供的测试连接命令验证一下。这才是确认整条链路是否通畅的最快方式。5.1 测试命令和执行结果解读在终端执行ssh -T gitgitlab.com这里的gitgitlab.com分为两部分git是连接GitLab SSH服务的固定用户名不是你的账号名gitlab.com是你所用的GitLab实例的域名。如果你们公司用的是内网自建GitLab就替换成对应的内网地址比如ssh -T gitgitlab.example.com。第一次连接时可能会提示确认远程主机的指纹输入yes回车继续。如果一切正常你会看到类似这样的输出Welcome to GitLab, yourusername!出现这行字说明SSH key配置已经成功GitLab已经识别出了你对应的账号。这里解释一下为什么要带-T参数。-T表示不向SSH服务器请求分配终端tty因为GitLab的SSH服务只用于Git协议传输不提供交互式shell。如果不带-T部分版本的SSH客户端会尝试申请终端GitLab服务端处理不了反而会报错。5.2 连接成功后clone地址怎么选才对验证通过之后clone仓库时就要用SSH地址而不是HTTPS地址。在GitLab的仓库页面上点击Clone按钮后会看到两个地址选项HTTPS地址形如https://gitlab.com/username/repo.gitSSH地址形如gitgitlab.com:username/repo.git直接复制SSH地址来clonegit clone gitgitlab.com:username/repo.git之后在这个仓库里的所有push和pull操作就都是免密状态了。另外要说一个我在实际中反复遇到的场景很多人给GitLab配好了SSH key但克隆仓库时手滑复制了HTTPS地址。这样就导致这个仓库的remote地址一直是HTTPS协议的之后每次操作依然会要求输入密码。明明SSH配置成功了却完全没生效特别可惜。如果你已经遇到过这个问题直接把已有仓库的remote地址改成SSH格式即可git remote set-url origin gitgitlab.com:username/repo.git改完再执行一次git remote -v确认地址变成了git开头后续操作就彻底走SSH通道了。5.3 测试失败时的常见输出长什么样配置出问题时的输出通常是这样gitgitlab.com: Permission denied (publickey).这句话的意思是SSH握手过程中服务器没有接受你的公钥认证。导致这个结果的原因有几种——公钥没贴对、贴的密钥与本地使用的私钥不匹配、SSH客户端没走你粘贴的那把密钥。遇到这条报错先别慌下一步就是标准的排查流程。6. 配置完就完事了吗日常使用中的几个高频坑SSH key配置本身不难难的是配置完成后那些时不时冒出来的问题。这里把我实际踩过、也给同事排查过的一些高频坑集中整理一下每一个都是真实场景。6.1 Permission denied (publickey) 的排查链路遇到权限报错我的固定排查思路是先用verbose模式看SSH客户端到底在尝试用哪把密钥ssh -vT gitgitlab.com注意这里的-v参数它会打印整个SSH握手过程的调试日志。输出会很长不用全看重点是找这几行信息debug1: Offering public key: /Users/you/.ssh/id_ed25519 ED25519 SHA256:xxxx debug1: Authentications that can continue: publickey debug1: Trying private key: /Users/you/.ssh/gitlab_ed25519第一行已经明确告诉你客户端正在尝试哪个私钥文件。如果你看到它尝试的是id_ed25519而你在GitLab后台粘贴的是gitlab_ed25519.pub里面的内容那问题就清楚了——本地默认使用的密钥和后台贴的公钥不是同一对。解决办法有两个思路。第一个干脆把后台公钥换成本地默认密钥对应的公钥第二个是写一个~/.ssh/config配置告诉SSH客户端连gitlab.com这个主机时使用指定的密钥文件Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yes把这段追加到~/.ssh/config文件里没有这个文件就新建一个然后再次执行ssh -T gitgitlab.com测试。IdentitiesOnly yes尤其重要——它强制SSH客户端只使用配置里指定的密钥文件不要逐个尝试当前agent里加载的所有密钥避免因为客户端默认尝试了错误的密钥导致认证失败。6.2 一台电脑多把SSH key和多平台账号怎么管理很多人会同时用GitLab和GitHub甚至公司内网还有一个自建的GitLab实例。这种情况下每个平台各配一把独立的密钥是最稳妥的做法。我现在的~/.ssh/config实际长这样Host gitlab.com HostName gitlab.com User git IdentityFile ~/.ssh/gitlab_ed25519 IdentitiesOnly yes Host github.com HostName github.com User git IdentityFile ~/.ssh/github_ed25519 IdentitiesOnly yes Host gitlab.intra HostName 172.16.x.x User git IdentityFile ~/.ssh/gitlab_intra_ed25519 IdentitiesOnly yes几个细节解释一下。Host后面的名字是你在git clone地址里写的那段主机名。比如你想用gitgitlab.intra:team/repo.git这种地址连接内网GitLab那么Host就要写成gitlab.intraHostName写真实的IP或域名。这样的好处是即使在公司的内网环境里也能靠config自动命中正确的私钥不用每次手动指定-i参数。另外多个平台各自独立密钥还有一个实际好处如果某一天GitHub的密钥出了问题你只需要在GitHub后台删掉对应公钥、重新生成一把完全不影响GitLab的使用。共用一把密钥的话任何一个平台出问题都要全部重来。6.3 Windows环境下那些绕不开的坑Windows用户配置SSH key总要多踩几个坑这里专门列一下。第一个坑是私钥文件权限。OpenSSH在Windows上对私钥文件权限很挑剔。如果C:\Users\你的用户名\.ssh目录的权限设置得过于宽松比如允许Everyone组访问SSH客户端会直接拒绝加载私钥报错内容类似Bad permissions。解决办法是给.ssh目录收紧权限右键目录 → 属性 → 安全 → 高级把继承的权限全部移除然后只保留当前用户自己的完全控制权限。操作完再重新打开终端测试问题通常就消失了。第二个坑是换行符混入公钥。前面提到过别用记事本打开.pub文件复制公钥。Windows的记事本对Unix风格换行的处理一直有历史遗留问题视觉上是一行实际复制时可能带入隐蔽的控制字符。还是用cat命令配合终端复制或者用VS Code打开并把右下角的文件编码确认成UTF-8。第三个坑是多套OpenSSH并存。Windows 10/11自带OpenSSH客户端Git for Windows的安装选项里也可以勾选Use Git and optional Unix tools from the Command Prompt这会在PATH里加入自己的SSH程序。两套SSH混着用有时候会出现Git Bash里能连PowerShell里连不上或者反过来。建议统一环境要么在PowerShell里用系统的ssh要么在Git Bash里用Git自带的ssh别混着来。第四个坑比较隐蔽和配置无关但会影响使用体验如果Windows用户名是中文.ssh路径里会带着中文字符某些老版本的SSH工具解析路径可能出错。这种情况可以考虑把密钥文件放到一个纯英文路径然后通过config文件里的IdentityFile指定绝对路径绕过去。6.4 密钥泄露或者换电脑时的处理思路最后聊聊两个不怎么常见但一旦遇到就很棘手的情况。第一是怀疑私钥泄露。私钥文件一旦泄露留在GitLab后台的公钥已经没有意义。正确做法是登录GitLab后台在SSH Keys页面把对应的公钥删除然后重新执行第3章的步骤生成新的密钥对把新公钥再贴上去。整个过程耗时不超过五分钟比纠结到底有没有泄露、要不要换要稳妥得多。第二是换一台新电脑。新电脑上没有你原来的私钥原来的公钥贴在GitLab后台这个是配对的新电脑连不上。处理方式其实很简单新电脑上生成一把全新的密钥然后把新公钥加到GitLab后台旧电脑对应的旧公钥顺手删掉。不用把旧电脑的私钥拷过来——这是安全上的红线私钥文件在任何情况下都不应该通过网盘、聊天工具、邮件传来传去。拷贝私钥相当于把家里的钥匙复印一份交给别人风险太大。另外提一句如果你之前配置过一台旧电脑且现在已经不用了记得去GitLab后台把旧设备绑定的公钥删掉。留着只是当时图省事后面旧设备丢了、二手转卖时才想起来就来不及了。这个习惯和你离开公司时注销旧账号一个道理属于基本的安全素养。最后分享一个我自己的体会配置GitLab SSH key这件事本质上是花十分钟换未来无数个免密操作的体验。把流程拆解开来就三步生成密钥、贴公钥、测连接。每一步都有各自的坑但那些坑几乎都是原理不清楚造成的。搞清楚SSH公私钥机制再回头看报错日志里的Offering public key那行字基本上自己就能定位问题在哪。我自己后来帮同事排查时发现超过一半的Permission denied问题根因都是本地有多把密钥但默认尝试的那一把不是GitLab后台贴的那一把。所以如果你以后也遇到莫名其妙的认证失败先别急着重新生成密钥先加个-v参数看一眼日志十次里有八次能直接看出端倪。最后再补充一个实用的好习惯把ssh -T gitgitlab.com这个验证命令记在笔记里。以后新配环境、遇到问题、甚至怀疑是不是密钥过期了第一时间跑一下几秒钟就能判断出是网络问题、配置问题还是GitLab服务端的问题。只有把验证命令用到形成肌肉记忆SSH这个方案的省心优势才算真正发挥出来。