Git SSH密钥配置、ed25519与多账号排查指南

周六下午,同事在群里甩过来一句"git push 一直报 Permission denied (publickey)",配了张终端截图。我扫了一眼就知道,又是 SSH 密钥没配明白。这类问题从我第一次自己搭 Git 仓库到现在,前前后后大概处理过几百次,踩过的坑能写满一整页笔记。git 中的 SSH 密钥的配置,表面上看只是敲三行命令的事,实际牵扯到非对称加密的基本原理、目录权限校验、多账号身份隔离、known_hosts 主机指纹这一整套机制,任何一个环节想当然,后面都得花十倍的时间找回来。

这篇东西写给三类人看:刚装完 Git、还不清楚 SSH 是什么的新手;手里同时挂着公司 GitLab、GitHub、Gitee 三个账号、被"用错密钥"折磨过的开发者;以及需要在服务器和 CI 环境里做免密拉取、想搞清楚背后逻辑的运维同学。我会把每一步为什么这么做讲透,把踩过的坑摊开说,让你照着做一遍就能用,而不是复制粘贴一堆命令然后继续报错。

1. 先搞明白 SSH 密钥到底在解决什么问题

1.1 HTTPS 和 SSH 是两条完全不同的路

刚接触 Git 的人最容易混淆的一点:克隆仓库时那个地址,其实有 HTTPS 和 SSH 两种形态,它们走的是两套完全不同的认证体系。

HTTPS 地址长这样:https://github.com/用户名/仓库名.git。它的认证靠的是账号密码或者个人访问令牌,每次推送都可能被要求输入凭据。虽然 Git 提供了凭据缓存机制,但本质上它还是一套"用户名 + 密码"的老路子,令牌还会过期,过期之后又是一轮折腾。

SSH 地址长这样:git@github.com:用户名/仓库名.git。注意那个开头的git@,这是固定用户名,后面的域名是平台地址,冒号后面是路径。SSH 走的是密钥对认证,配置一次之后长期有效,不用反复输密码,而且配合 ssh-agent 之后连密码短语都不用敲。

我用下来最直观的差别是:HTTPS 每次换机器、换网络环境、令牌到期,都要重新折腾一遍;SSH 只要私钥跟着你走,在哪台机器上都是即插即用。所以只要不是完全没法用 SSH 的极端环境(比如某些限制 22 端口的公司网络),我都会优先选 SSH。

1.2 公钥和私钥:一把锁和一把钥匙

很多人配完密钥其实并不清楚自己在干什么,这里用一个生活化的类比讲清楚。

你可以把公钥想象成一把挂在门上的挂锁,谁都能看到它、拿到它,甚至复制一把一模一样的挂锁走。但这把锁有个特性:一旦锁上,只有配套的那把钥匙才能打开。私钥就是那把钥匙,它必须牢牢攥在你自己手里,谁拿到钥匙,谁就能开这把锁。

放到 Git 的场景里:你把公钥交给 GitHub,相当于把挂锁挂在了 GitHub 的门上;GitHub 需要验证"你确实是账号主人"时,就用这把挂锁锁一个随机信息发给你;你手里有钥匙,能打开它,于是证明了自己的身份。整个过程中私钥从来没有离开过你的机器,GitHub 也永远拿不到它。

这就是非对称加密最朴素的应用。理解了这一层,你就能明白后面为什么那些操作是那个样子:为什么私钥权限必须是 600、为什么私钥绝对不能发给任何人、为什么公钥可以随便贴。

1.3 哪些场景必须上 SSH

从这张表能看出来,SSH 的价值不只是"免密",更重要的是"身份可控"。你给每个仓库、每台机器配一把独立的密钥,哪天某台机器退役了,直接把对应的公钥从平台删掉就行,不影响其他环境。HTTPS 那套令牌体系做不到这么细的粒度。

2. 动手之前:环境确认和参数选型

2.1 先确认 Git 环境和基础配置

别急着敲 ssh-keygen。先花两分钟确认环境,能省掉后面很多莫名其妙的报错。

git --version git config --global user.name "你的名字" git config --global user.email "你的邮箱"

git --version用来确认 Git 装没装、版本是多少。低版本 Git 对 ed25519 的支持可能有问题,遇到怪问题的时候第一件事就是看版本。

后面两个是全局身份配置,决定了你每次提交时 commit 里记录的作者信息。这里有个新手高频误解必须点破:git config里配的邮箱,和 SSH 认证用的密钥,完完全全是两回事。前者只是提交记录里的一个文本标签,后者才是真正决定你有没有权限推送的凭证。我见过有人改了半天 user.email,以为能解决 push 报错,方向完全错了。

提示:全局配置的邮箱建议和你各平台账号绑定的主邮箱保持一致,否则 GitHub 上不会把提交归到你名下。如果你不想暴露真实邮箱,平台都提供了匿名邮箱地址,填那个也行。

2.2 ed25519 还是 RSA:算法怎么选

这是选型里最需要解释"为什么"的一步。目前的答案很明确:能用 ed25519 就用 ed25519。

ed25519 的优势在于:密钥本身短(公钥私钥加起来才几百字节,贴到哪里都不费劲),签名验证快,而且抗侧信道攻击的设计更现代。它在安全强度上对标 3072 位以上的 RSA,但体积和性能好得多。

那为什么还要提 RSA?因为兼容性。一些自建的 GitLab 老版本、某些内网代码服务器,或者旧版本的 SSH 客户端,可能不认识 ed25519 这种密钥类型。遇到no matching key exchange method found或者key type ssh-ed25519 not supported这类报错,退回到 RSA 4096 基本都能解决。

至于 ECDSA 和 DSA,我的建议是直接跳过。DSA 已经属于历史遗留,现在很多平台直接拒绝;ECDSA 本身没问题,但它对随机数生成质量极度敏感,历史上出过几次随机数复用导致私钥泄露的事件,而且部分平台的兼容性还不如 RSA。没有特殊理由不用碰。

2.3 密钥放哪、叫什么名字

默认情况下,ssh-keygen 会把密钥生成到~/.ssh/目录下。这个波浪号在 Linux 和 macOS 上代表当前用户的家目录,Windows 上对应的路径通常是C:\Users\你的用户名\.ssh。

文件名这一步有讲究:

• 如果你只有一个Git 账号,直接用默认名id_ed25519,最省事,什么都不用额外配置。
• 如果你有多个账号,必须给每个密钥起不同的名字,比如id_ed25519_github、id_ed25519_gitlab、id_ed25519_work。原因在第四章会详细说,简单讲就是:SSH 客户端默认只会拿id_rsa、id_ed25519这几个固定名字去尝试,起了别的名字就得靠 config 文件指路。

另外提前把目录权限设好,这个细节后面会救你很多次:

chmod 700 ~/.ssh

.ssh目录必须是 700(只有自己能读写执行),私钥必须是 600,公钥 644 没问题。SSH 客户端有个安全校验:如果它发现私钥权限太开放,会直接拒绝使用这个密钥,并且报错说权限不对。这个机制虽然烦人,但它是为了保护你——想象一下你把私钥设成所有人可读,那和把家门钥匙挂在门把手上没区别。

3. 从零生成并部署 SSH 密钥

3.1 ssh-keygen 的完整交互过程,逐行解读

确认完环境和选型,就可以正式生成了。以 ed25519 为例:

ssh-keygen -t ed25519 -C "your_email@example.com"

参数含义:-t指定算法类型,-C是给密钥加一个注释标签。很多人以为-C里的邮箱和认证有关,其实它只是写进公钥末尾的一个纯文本标记,方便你在平台上管理一堆公钥时能认出哪把是哪把。认证过程完全不看这个注释。但正因为它是给人看的,建议就填邮箱或者"设备名-用途"这种一眼能认出来的内容,半年后回来看的时候你会感谢自己。

敲下命令之后,会有三段交互:

Generating public/private ed25519 key pair. Enter file in which to save the key (/home/you/.ssh/id_ed25519):

第一问是保存路径。单账号直接回车走默认。多账号的话,这里输入完整的自定义路径,例如/home/you/.ssh/id_ed25519_github。

Enter passphrase (empty for no passphrase): Enter same passphrase again:

第二、三问是设置密码短语。这里要说清楚一个取舍:

• 留空:方便,拉代码推代码全程不用输任何东西。缺点是任何拿到你这个私钥文件的人,都能直接冒充你。
• 设置短语:私钥文件被拿走也用不了,多一层保护。代价是每次用都要输一遍,除非配合 ssh-agent 缓存。

我的习惯是:个人笔记本上的开发密钥,如果设备本身有开机密码和磁盘加密,可以留空图方便;公司共享机器、服务器上放的密钥,一定设短语,并且配合 ssh-agent 管理。

生成成功后会看到类似这样的输出:

Your identification has been saved in /home/you/.ssh/id_ed25519 Your public key has been saved in /home/you/.ssh/id_ed25519.pub The key fingerprint is: SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx your_email@example.com The key's randomart image is: +--[ED25519 256]--+ | .o. | | . + . | +----[SHA256]-----+

那个方块图叫 randomart,是密钥指纹的可视化表示,方便你肉眼快速比对。SHA256:开头那一长串才是真正的指纹,校验密钥是否一致的时候看它。

注意:私钥是id_ed25519,没有后缀;公钥是id_ed25519.pub,有.pub后缀。要发给平台的是带.pub的那个,千万别复制错。这个错误我见过太多了,尤其是习惯用文件管理器拖拽的人。

3.2 把公钥贴到平台上

生成完公钥,用这条命令把内容打印出来:

cat ~/.ssh/id_ed25519.pub

输出的内容是一整行,形如:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...... your_email@example.com

从ssh-ed25519开始,到邮箱结束,整行完整复制。

各平台的添加路径大同小异:

几个实操细节:

• 粘贴时只粘那一整行,不要带任何换行或者多余空格,尤其别把cat出来的提示符一起复制进去。
• 有些平台有"过期时间"选项,个人开发建议留空,或者设一个远期时间,否则到期后你会突然发现自己推不了代码,还找不到原因。
• GitHub 上那把 key 有一个 "Allow write access" 选项,那是给部署密钥用的,普通账号密钥不需要勾。

添加成功后,平台通常会显示这把密钥的指纹。用ssh-keygen -lf ~/.ssh/id_ed25519.pub可以本地算出指纹,和平台上显示的比对一下,一致就说明贴对了。

3.3 验证连接:返回信息怎么读

公钥贴好之后,不要急着去推代码,先用这条命令验证:

ssh -T git@github.com

-T的意思是禁止分配伪终端,因为我们只是想测试认证,不需要真的登录一个 shell。

第一次连接会看到这样的提示:

The authenticity of host 'github.com (140.82.xx.xx)' can't be established. ED25519 key fingerprint is SHA256:xxxxxx. Are you sure you want to continue connecting (yes/no/[fingerprint])?

这是在问你要不要信任这台主机。输入yes回车,它会把这台主机的指纹记到~/.ssh/known_hosts文件里,以后再连就不会问了。这里输入 yes 的前提是你确认这是官方主机——GitHub、GitLab 的官方指纹都在官网文档里有公布,敏感环境里建议核对一下。

如果一切正常,会看到:

Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.

这句话的意思是"认证成功了,但我们不提供 shell 登录"。看到 "successfully authenticated" 就说明 SSH 这条链路已经打通了,可以正常用 SSH 地址克隆和推送了。

GitLab 的返回是Welcome to GitLab, @你的用户名!,Gitee 是Hi 你的用户名! You've successfully authenticated...,内容不同,但看到 success 或者 Welcome 就是成功了。

如果没成功,加-v参数看详细日志:

ssh -Tv git@github.com

它会打印出尝试加载了哪些密钥文件、和服务器协商了哪些算法、最后在哪一步失败。排查问题的时候,这个输出基本能定位到九成的问题。

3.4 ssh-agent:让密码短语不再烦人

如果你给密钥设了密码短语,每次都输肯定受不了。ssh-agent 就是来解决这个的——它把解开的私钥缓存在内存里,后续使用自动调用。

启动 agent 并添加密钥:

eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519

第一行启动 agent 并把它的环境变量导入当前 shell。第二行添加密钥,会让你输一次密码短语,输完就缓存住了。

但这个方案有个坑:每次新开一个终端窗口,环境变量变了,缓存就失效了。解决办法是在 shell 的启动文件里配置自动处理。不过更省心的做法是直接用 config 文件加一个配置项:

Host * AddKeysToAgent yes IdentityFile ~/.ssh/id_ed25519

AddKeysToAgent yes会让 SSH 在第一次用到某个密钥时自动把它加进 agent,不用手动 ssh-add。

macOS 上还有专门钥匙串支持,把密码短语存进系统钥匙串,重启也不丢:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

对应的 config 里加上UseKeychain yes。

Windows 上的处理方式不太一样,它用的是系统服务。以管理员身份打开 PowerShell:

Get-Service ssh-agent Set-Service -Name ssh-agent -StartupType Automatic Start-Service ssh-agent ssh-add ~/.ssh/id_ed25519

把服务设为自动启动之后,密钥缓存就能跨终端保持了。这套流程我帮好几个 Windows 同事配过,配完之后体验和 Linux 上没什么差别。

4. 多账号共存:config 文件才是关键

4.1 为什么多账号一定需要 config

这是整个话题里最容易出问题、也最需要讲清楚原理的部分。

假设你在同一台电脑上,既有公司的 GitLab 账号,又有自己的 GitHub 账号。你生成了两把密钥:id_ed25519_work和id_ed25519_personal,公钥也分别贴到了对应平台。然后你克隆公司的仓库,推送,结果报错说没有权限——为什么?

因为 SSH 客户端在连接某个主机时,默认会按顺序尝试~/.ssh目录下的几个固定名字的密钥(id_rsa、id_ecdsa、id_ed25519等),你起的那两个自定义名字压根不在它的自动尝试列表里。即使它能尝试,它也不知道"连 GitHub 该用哪把",可能拿着公司的密钥去连 GitHub,自然认证失败。

~/.ssh/config文件就是用来解决这个问题的:你可以为每个主机(或者说每个身份)指定专门用哪把密钥。

4.2 config 配置模板与 Host 别名机制

先确保存在这个文件,并设好权限:

touch ~/.ssh/config chmod 600 ~/.ssh/config

然后写入配置。多账号的典型写法有两种,先看第一种——用真实域名,靠 IdentityFile 区分:

Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal IdentitiesOnly yes Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yes

这个写法适用于不同平台域名不同的情况。Host是你在命令行里要写的主机名,HostName是实际要连的地址,User对 Git 服务来说基本固定是git,IdentityFile指定用哪把私钥。

关键是IdentitiesOnly yes这一行。它的作用是强制 SSH 只用 config 里明确指定的密钥,不去尝试 agent 里缓存的其他密钥。如果不加这一行,SSH 可能会在尝试了你指定的密钥失败后,继续拿其他密钥去试,表现就是"我明明配对了,偶尔还是能用错身份"。这个参数是无数人踩坑之后总结出来的,强烈建议每个 Host 块都加上。

再看第二种情况,更有意思——同一个平台,两个账号。比如你有两个 GitHub 账号,github.com这个域名是同一个,靠 Host 区分不了,这时候就要用 Host 别名:

Host github-personal HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal IdentitiesOnly yes Host github-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yes

这里的github-personal和github-work是你自己编的别名,并不真实存在。SSH 看到这个别名,会去查 HostName,发现实际要连的还是 github.com,但用不同的密钥。

4.3 仓库 remote 地址要跟着改

用了 Host 别名之后,仓库的 remote 地址也必须改成别名,否则前面配的全都白费。

原来 SSH 地址长这样:

git@github.com:用户名/仓库.git

用别名之后要改成:

git@github-personal:用户名/仓库.git

注意就是把github.com替换成你的别名,其余部分不动。

改法有两种。克隆时直接写别名:

git clone git@github-personal:用户名/仓库.git

已经克隆下来的仓库,改 remote:

git remote set-url origin git@github-personal:用户名/仓库.git

改完记得验证:

git remote -v

输出里应该能看到别名版本的地址。这一步我建议养成习惯,改完必查,因为 remote 配错是"能克隆不能推送"或者"推到错误账号"这类诡异问题的常见源头。

提示:如果你用的是git@github.com:用户名/仓库.git这种标准地址,而 config 里配的 Host 就是github.com,那两者是对得上的,不需要改 remote。只有用了自定义别名才必须改。

5. 高频踩坑和排查实录

5.1 权限问题:最没技术含量但最常见

Permissions 0644 for 'id_ed25519' are too open.这个报错我估计见过上百次。原因就是私钥文件权限太开放,SSH 出于安全考虑拒绝使用。

修复很简单:

chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub chmod 700 ~/.ssh chmod 600 ~/.ssh/config chmod 600 ~/.ssh/known_hosts

一套配下来,权限就规矩了。

Windows 上的情况更复杂一点。Windows 的 SSH 客户端会检查文件 ACL,有些人是从别的地方复制过来的密钥文件,继承了父目录的权限,就会报这个错。修复方式是在文件属性里改安全设置,把其他用户的权限去掉,只留自己。也可以直接删掉重新生成一把,有时候比折腾权限还快。

注意:别偷懒用chmod 777或者chmod 755去"解决"这个问题。SSH 检查的就是权限是不是过于开放,你设得越开放它越拒绝。必须是 600。

5.2 known_hosts 冲突:服务器换了指纹怎么办

报错长这样:

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! Host key verification failed.

这个报错的意思是:服务器返回的主机指纹,和你本地known_hosts里记录的不一致。常见原因有几类:

• 服务器重装了系统,重新生成了主机密钥。
• 平台换了负载均衡节点,指纹变了(某些自建服务会出现)。
• 你的域名解析到了错误的地址,连到了不该连的机器上。

前两种是正常的,删掉旧记录重新信任就行:

ssh-keygen -R github.com

把域名换成报错里提到的那个主机名,然后重新连接,会重新问你 yes/no,输入 yes 即可。

但如果是第三种情况,就要警惕了——那可能是有人在中间拦截你的连接。判断方法是把服务器返回的指纹拿去找服务提供方核对,或者从可信渠道获取官方指纹做比对。生产环境里这个环节不要图省事跳过。

顺带说一句,StrictHostKeyChecking这个参数有人为了省事设成no,让它自动接受所有主机。我不建议这么干,至少在正式环境里不要。这个校验机制是你抵御中间人攻击的最后一道防线,关掉它等于把门敞开。

5.3 连接超时、端口不通、密钥匹配失败

除了权限和指纹,还有几类报错:

连接超时或者连接被拒绝。先测端口通不通:ssh -T git@github.com卡很久没反应,可能是网络层面对 22 端口有限制。GitHub 提供了 443 端口的备用入口,改 config:

Host github.com HostName ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519_personal

注意 HostName 变成了ssh.github.com,Port 是 443。这个配置在限制 22 端口的环境里非常有用。

Permission denied (publickey)但密钥明明配了。按这个顺序排查:

1. ssh -Tv git@github.com看它到底加载了哪些密钥。
2. 确认公钥真的贴到平台上了,而且贴的是.pub文件内容。
3. 确认 config 里IdentitiesOnly yes和IdentityFile路径都对。
4. 确认~/.ssh/config本身权限是 600,权限不对配置文件会被忽略。

no matching host key type found。这是算法协商问题,常见于连接一些老服务器。可以在 config 里针对该主机显式允许老算法,但更推荐的办法是升级服务端。

5.4 问题速查表

把这张表存下来,遇到报错先对一遍,大部分问题三分钟内能定位。

5.5 我踩过的几个坑,说出来给你省时间

第一个坑:把公钥私钥搞反了往上贴。有一段时间我图快,直接从文件管理器里把id_ed25519拖过去上传,结果平台报格式错误。后来才反应过来该传.pub。这个错误看起来很蠢,但真的很多人犯。分辨方法很简单:私钥文件开头通常是-----BEGIN OPENSSH PRIVATE KEY-----,内容是一大坨多行文本;公钥就是一行,以ssh-ed25519或ssh-rsa开头。看到多行开头的那个,立刻停手。

第二个坑:多账号下没加 IdentitiesOnly。当时配了三个账号,测试的时候每个单独测都通过,一到实际推代码就随机失败。折腾了半天才发现是 agent 缓存了三把密钥,SSH 挨个试,试到对的那把之前就已经被服务端拒绝了(有些平台对失败次数有阈值,连续失败会临时封禁)。加上IdentitiesOnly yes之后,问题彻底消失,而且速度明显变快——因为它不再无意义地尝试一堆密钥。

第三个坑:VSCode 远程开发时密钥环境不一致。用 VSCode 的 Remote-SSH 连远程服务器开发时,远程那台机器上要有你的密钥,而且 agent 转发可能要单独配置。我遇到过本地配得好好的,在远程终端里拉代码却报权限错误,原因就是远程环境里根本没有对应的私钥。解决方案是在远程机器的~/.ssh下重新生成一套密钥并部署,或者配置 agent 转发让本地的 agent 服务远程会话。这个点比较细,但用远程开发的人迟早会遇到。

第四个坑:换了台新电脑,以为密钥会自动同步。私钥不会跟着账号走。新机器上必须重新生成一套密钥并部署到平台,或者从安全渠道把旧私钥迁移过来(迁移的话注意权限设置)。我现在习惯把每台设备用独立的密钥,并在平台上的密钥名称里标注设备和用途,比如macbook-pro-2024、workstation-office,这样哪台设备不用了,直接删对应的公钥就行,不影响其他设备。

5.6 关于密钥轮换和日常维护

密钥配好不是一劳永逸的。我现在保持的习惯是:

• 每把密钥都有明确用途,命名里带上设备和场景,不用"key1""key2"这种名字。
• 平台上的公钥定期清理,把已经不用的设备密钥删掉。我一般半年过一遍。
• 重要环境的密钥设置密码短语,并且不放在共享目录里。
• 服务器上的部署密钥用只读权限,需要写入的单独配一把,把权限切开。

这套习惯看起来有点啰嗦,但真出事的时候能省掉大麻烦。我见过有人图方便,一个私钥到处复制到七八台机器上,后来某台机器退役要回收,完全不知道该不该删那个公钥,因为删了别的环境就断了。

5.7 一个快速自检清单

最后给你一个可以随时跑的检查流程,新配环境或者怀疑出问题的时候走一遍:

ls -la ~/.ssh ssh -T git@github.com ssh -T git@gitlab.com ssh -T git@gitee.com git remote -v

第一条看目录里都有什么、权限对不对;中间三条测试各平台的连通性;最后一条看当前仓库的 remote 地址是不是你期望的那个。

这一套跑完,基本能覆盖绝大多数配置问题。我每次换新电脑、新环境,都会走一遍这个流程,顺利的话两分钟就能全部搞定。

说到底,SSH 密钥配置这件事的难点从来不是命令本身,而是理解"谁在什么情况下用哪一把钥匙"这件事。想清楚这一点,config 文件怎么组织、多账号怎么隔离、报错怎么排查,都是顺理成章的。我个人的经验是,前期多花十分钟把命名和 config 规划清楚,后面能省下几十次排查的时间,这笔账怎么算都划算。