周六下午,同事在群里甩过来一句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 地址长这样:gitgithub.com:用户名/仓库名.git。注意那个开头的git,这是固定用户名,后面的域名是平台地址,冒号后面是路径。SSH 走的是密钥对认证,配置一次之后长期有效,不用反复输密码,而且配合 ssh-agent 之后连密码短语都不用敲。我用下来最直观的差别是:HTTPS 每次换机器、换网络环境、令牌到期,都要重新折腾一遍;SSH 只要私钥跟着你走,在哪台机器上都是即插即用。所以只要不是完全没法用 SSH 的极端环境(比如某些限制 22 端口的公司网络),我都会优先选 SSH。1.2 公钥和私钥:一把锁和一把钥匙很多人配完密钥其实并不清楚自己在干什么,这里用一个生活化的类比讲清楚。你可以把公钥想象成一把挂在门上的挂锁,谁都能看到它、拿到它,甚至复制一把一模一样的挂锁走。但这把锁有个特性:一旦锁上,只有配套的那把钥匙才能打开。私钥就是那把钥匙,它必须牢牢攥在你自己手里,谁拿到钥匙,谁就能开这把锁。放到 Git 的场景里:你把公钥交给 GitHub,相当于把挂锁挂在了 GitHub 的门上;GitHub 需要验证你确实是账号主人时,就用这把挂锁锁一个随机信息发给你;你手里有钥匙,能打开它,于是证明了自己的身份。整个过程中私钥从来没有离开过你的机器,GitHub 也永远拿不到它。这就是非对称加密最朴素的应用。理解了这一层,你就能明白后面为什么那些操作是那个样子:为什么私钥权限必须是 600、为什么私钥绝对不能发给任何人、为什么公钥可以随便贴。1.3 哪些场景必须上 SSH使用场景HTTPS 是否可行SSH 的收益个人单账号日常开发可行,需缓存凭据免密、长期有效一台机器管理多个平台账号麻烦,凭据容易串通过 config 精确隔离服务器上 git pull 部署令牌明文存储风险高部署密钥更安全CI/CD 流水线拉代码需要额外注入令牌用 deploy key 更干净内网自建 Git 服务需要额外配证书直接走密钥认证从这张表能看出来,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固定 256 位约等于 3072 位 RSA极快主流平台均支持RSA4096 位4096 位慢兼容性最好ECDSA521 位高快部分老平台支持不佳DSA1024 位已过时快已基本淘汰,不要用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_emailexample.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_emailexample.com The keys 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_emailexample.com从ssh-ed25519开始,到邮箱结束,整行完整复制。各平台的添加路径大同小异:平台添加位置GitHubSettings → SSH and GPG keys → New SSH keyGitLabPreferences → SSH KeysGitee设置 → SSH 公钥自建 GitLab用户设置 → SSH Keys几个实操细节:粘贴时只粘那一整行,不要带任何换行或者多余空格,尤其别把cat出来的提示符一起复制进去。有些平台有过期时间选项,个人开发建议留空,或者设一个远期时间,否则到期后你会突然发现自己推不了代码,还找不到原因。GitHub 上那把 key 有一个 Allow write access 选项,那是给部署密钥用的,普通账号密钥不需要勾。添加成功后,平台通常会显示这把密钥的指纹。用ssh-keygen -lf ~/.ssh/id_ed25519.pub可以本地算出指纹,和平台上显示的比对一下,一致就说明贴对了。3.3 验证连接:返回信息怎么读公钥贴好之后,不要急着去推代码,先用这条命令验证:ssh -T gitgithub.com-T的意思是禁止分配伪终端,因为我们只是想测试认证,不需要真的登录一个 shell。第一次连接会看到这样的提示:The authenticity of host github.com (140.82.xx.xx) cant 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 你的用户名! Youve successfully authenticated, but GitHub does not provide shell access.这句话的意思是认证成功了,但我们不提供 shell 登录。看到 successfully authenticated 就说明 SSH 这条链路已经打通了,可以正常用 SSH 地址克隆和推送了。GitLab 的返回是Welcome to GitLab, 你的用户名!,Gitee 是Hi 你的用户名! Youve successfully authenticated...,内容不同,但看到 success 或者 Welcome 就是成功了。如果没成功,加-v参数看详细日志:ssh -Tv gitgithub.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_ed25519AddKeysToAgent 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 地址长这样:gitgithub.com:用户名/仓库.git用别名之后要改成:gitgithub-personal:用户名/仓库.git注意就是把github.com替换成你的别名,其余部分不动。改法有两种。克隆时直接写别名:git clone gitgithub-personal:用户名/仓库.git已经克隆下来的仓库,改 remote:git remote set-url origin gitgithub-personal:用户名/仓库.git改完记得验证:git remote -v输出里应该能看到别名版本的地址。这一步我建议养成习惯,改完必查,因为 remote 配错是能克隆不能推送或者推到错误账号这类诡异问题的常见源头。提示:如果你用的是gitgithub.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 gitgithub.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)但密钥明明配了。按这个顺序排查:ssh -Tv gitgithub.com看它到底加载了哪些密钥。确认公钥真的贴到平台上了,而且贴的是.pub文件内容。确认 config 里IdentitiesOnly yes和IdentityFile路径都对。确认~/.ssh/config本身权限是 600,权限不对配置文件会被忽略。no matching host key type found。这是算法协商问题,常见于连接一些老服务器。可以在 config 里针对该主机显式允许老算法,但更推荐的办法是升级服务端。5.4 问题速查表报错信息最可能原因处理方式Permission denied (publickey)公钥未部署/密钥不匹配用 -Tv 查加载了哪把密钥Permissions 0644 are too open私钥权限过宽chmod 600 私钥Host key verification failed主机指纹变化ssh-keygen -R 删除旧记录Connection timed out22 端口被限制改用 443 端口入口Could not open a connectionssh-agent 未启动eval 启动 agent 或设为自启no matching key type算法不被支持换 RSA 4096 或放开算法Bad owner or permissions on configconfig 权限不对chmod 600 ~/.ssh/config把这张表存下来,遇到报错先对一遍,大部分问题三分钟内能定位。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 关于密钥轮换和日常维护密钥配好不是一劳永逸的。我现在保持的习惯是:每把密钥都有明确用途,命名里带上设备和场景,不用key1key2这种名字。平台上的公钥定期清理,把已经不用的设备密钥删掉。我一般半年过一遍。重要环境的密钥设置密码短语,并且不放在共享目录里。服务器上的部署密钥用只读权限,需要写入的单独配一把,把权限切开。这套习惯看起来有点啰嗦,但真出事的时候能省掉大麻烦。我见过有人图方便,一个私钥到处复制到七八台机器上,后来某台机器退役要回收,完全不知道该不该删那个公钥,因为删了别的环境就断了。5.7 一个快速自检清单最后给你一个可以随时跑的检查流程,新配环境或者怀疑出问题的时候走一遍:ls -la ~/.ssh ssh -T gitgithub.com ssh -T gitgitlab.com ssh -T gitgitee.com git remote -v第一条看目录里都有什么、权限对不对;中间三条测试各平台的连通性;最后一条看当前仓库的 remote 地址是不是你期望的那个。这一套跑完,基本能覆盖绝大多数配置问题。我每次换新电脑、新环境,都会走一遍这个流程,顺利的话两分钟就能全部搞定。说到底,SSH 密钥配置这件事的难点从来不是命令本身,而是理解谁在什么情况下用哪一把钥匙这件事。想清楚这一点,config 文件怎么组织、多账号怎么隔离、报错怎么排查,都是顺理成章的。我个人的经验是,前期多花十分钟把命名和 config 规划清楚,后面能省下几十次排查的时间,这笔账怎么算都划算。