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 pull，Git都会要求你验证身份。最常见的流程是弹出用户名、密码输入框，你得手动填。如果账号开了两步验证，密码框还要填personal access token，不是登录密码本身。这个token在GitLab后台的"Access Tokens"页面生成，生成的时候要选权限范围、设过期时间，稍不留神就配错。

更麻烦的是，很多公司的安全策略要求定期重置密码或者轮换token。这意味着你正在写代码写到一半，突然一次push失败，提示认证过期。你又得放下手头的活，去后台搞一个新token，再回到终端重新push。这种事情一个月来几次，效率直接被打没。

还有一个隐形坑：如果本机的Git配置里缓存了旧凭据，换token之后经常出现"明明新密码对了，却一直报认证失败"的诡异问题，得手动清理Windows凭据管理器或者macOS钥匙串里的旧记录，排查起来非常心累。

1.2 SSH认证的核心逻辑：一把公钥锁，一把私钥钥匙

SSH key之所以省事，是因为它换了一种完全不同的认证思路。它不再需要"用户名+密码"这种每次都要传递的信息，而是用一对密钥完成身份验证。

这对密钥包含两个文件：公钥（xxx.pub）和私钥（没有后缀名的那一个）。公钥可以放心地交给任何人、贴到任何服务器上，它相当于一把挂锁；私钥是你手里唯一的钥匙，必须牢牢锁在自己电脑里，绝对不能泄露。

具体到GitLab的场景里，流程是这样的：

1. 你在本地生成一对密钥，把公钥内容贴到GitLab后台的SSH Keys页面。
2. GitLab记住了你的公钥，并在后台把公钥和你的账号绑定。
3. 你执行git push时，本机Git会向GitLab发起SSH连接。
4. GitLab收到连接请求后，会用你预先贴好的公钥生成一个加密挑战。
5. 只有持有对应私钥的电脑才能正确回应这个挑战。本机私钥自动完成签名，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隐藏文件夹里。不同操作系统进入这个目录的方式略有不同：

检查当前是否已有密钥，建议直接执行：

ls -la ~/.ssh

然后看输出结果里有哪些文件。正常的密钥文件一般是成对出现的：

• id_ed25519+id_ed25519.pub
• 或者id_rsa+id_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算法，这种算法的签名更短、生成速度更快，安全性上目前也没有已知的实质缺陷，完全可以作为默认选择。

当然，如果你所在的公司内网GitLab是很老的版本，或者运维明确说服务器上的SSH服务不支持ed25519，那就退回RSA 4096。判断依据很简单：先试ed25519，如果连接时报no matching key exchange method之类的错误，再改用RSA也不迟。

3.2 生成命令和每个参数的含义

建议用下面的命令生成一把专门给GitLab用的密钥：

ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/gitlab_ed25519

逐个解释一下这条命令的参数：

• -t ed25519：指定密钥算法为ED25519。
• -C "you@example.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_ed25519

Windows用户比较复杂一些。如果你用的是Git Bash，命令和上面基本一致。如果你用的是PowerShell，可以这样操作：

Get-Service ssh-agent | Set-Service -StartupType Manual Start-Service ssh-agent ssh-add $env:USERPROFILE\.ssh\gitlab_ed25519

Windows 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 you@example.com (ED25519)

如果后台页面显示的指纹和这串一致，说明粘贴过程一切正确，接下来可以放心测试连接了。

5. 验证是否配置成功：ssh -T 到底在干什么

公钥贴好之后，先别急着clone仓库，先用GitLab官方提供的测试连接命令验证一下。这才是确认整条链路是否通畅的最快方式。

5.1 测试命令和执行结果解读

在终端执行：

ssh -T git@gitlab.com

这里的git@gitlab.com分为两部分：git是连接GitLab SSH服务的固定用户名，不是你的账号名；gitlab.com是你所用的GitLab实例的域名。如果你们公司用的是内网自建GitLab，就替换成对应的内网地址，比如ssh -T git@gitlab.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.git
• SSH地址：形如git@gitlab.com:username/repo.git

直接复制SSH地址来clone：

git clone git@gitlab.com:username/repo.git

之后在这个仓库里的所有push和pull操作就都是免密状态了。

另外要说一个我在实际中反复遇到的场景：很多人给GitLab配好了SSH key，但克隆仓库时手滑复制了HTTPS地址。这样就导致这个仓库的remote地址一直是HTTPS协议的，之后每次操作依然会要求输入密码。明明SSH配置成功了，却完全没生效，特别可惜。

如果你已经遇到过这个问题，直接把已有仓库的remote地址改成SSH格式即可：

git remote set-url origin git@gitlab.com:username/repo.git

改完再执行一次git remote -v确认地址变成了git@开头，后续操作就彻底走SSH通道了。

5.3 测试失败时的常见输出长什么样

配置出问题时的输出通常是这样：

git@gitlab.com: Permission denied (publickey).

这句话的意思是：SSH握手过程中，服务器没有接受你的公钥认证。导致这个结果的原因有几种——公钥没贴对、贴的密钥与本地使用的私钥不匹配、SSH客户端没走你粘贴的那把密钥。遇到这条报错，先别慌，下一步就是标准的排查流程。

6. 配置完就完事了吗？日常使用中的几个高频坑

SSH key配置本身不难，难的是配置完成后那些时不时冒出来的问题。这里把我实际踩过、也给同事排查过的一些高频坑集中整理一下，每一个都是真实场景。

6.1 Permission denied (publickey) 的排查链路

遇到权限报错，我的固定排查思路是先用verbose模式看SSH客户端到底在尝试用哪把密钥：

ssh -vT git@gitlab.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 git@gitlab.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地址里写的那段主机名。比如你想用git@gitlab.intra:team/repo.git这种地址连接内网GitLab，那么Host就要写成gitlab.intra，HostName写真实的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 git@gitlab.com这个验证命令记在笔记里。以后新配环境、遇到问题、甚至怀疑是不是密钥过期了，第一时间跑一下，几秒钟就能判断出是网络问题、配置问题还是GitLab服务端的问题。只有把验证命令用到形成肌肉记忆，SSH这个方案的省心优势才算真正发挥出来。