gitgitee.com: Permission denied (publickey). Could not read from remote repository.这行红字大概是每个刚把代码往 Gitee 上搬的人都会撞一次的墙。它出现的位置很讨厌——往往是在你已经写完代码、建好仓库、复制了那条 SSH 地址、敲下git push之后终端毫不留情地甩给你一句 Permission denied然后告诉你 Please make sure you have the correct access rights and the repository exists。很多人第一反应是我账号密码没错啊第二反应是是不是 Gitee 挂了第三反应就开始怀疑人生。其实这条报错跟你的账号密码基本没关系它说的是 SSH 层面的身份校验没过——Gitee 的服务器拿着你的公钥指纹去比对没找到匹配项于是拒绝你读取仓库。这篇文章就围绕这一个报错展开把公钥私钥的配对逻辑、密钥生成时的参数取舍、多平台密钥共存、权限位、agent 缓存、日志读法这些平时没人细讲的东西一次讲透。不管你是刚装完 Git 的新手还是被这个问题卡了半天准备放弃的人照着走一遍基本都能通。1. 这条报错到底在说什么1.1 字面含义与真实触发链路先把这条报错拆开看。gitgitee.com是你在用的远程地址git是用户名——注意Gitee 的 SSH 接入用户名固定就是git这个字符串不是你的账号名也不是你的邮箱这一点很多人会搞混。Permission denied (publickey)是 OpenSSH 客户端抛出来的意思是我尝试了所有能试的认证方式只剩公钥这一条路而公钥认证失败了。后面那句Could not read from remote repository是 Git 对上层结果的转述它并不代表仓库不存在只是告诉你因为认证没过所以读不到。真实的链路是这样的你在本地执行git push或git cloneGit 发现远程地址是gitgitee.com:xxx/yyy.git这种 SCP 风格于是调用系统里的ssh程序让 ssh 去连gitee.com的 22 端口并声明要以git用户身份登录。ssh 客户端会先做主机密钥校验再进入用户认证阶段。用户认证默认会尝试none、publickey、password等几种方式而 Gitee 只接受公钥认证。于是 ssh 会把本地能找到的私钥逐个拿去做签名挑战服务器用对应公钥验签验过就放行。如果本地一个可用的私钥都没找到或者找到的私钥在服务端没有登记对应公钥就返回这句 Permission denied。关键认知这条报错是客户端没拿出正确钥匙不是服务端不让你进门。绝大多数情况下问题在你的本地环境不在 Gitee。1.2 哪些操作最容易踩到这个坑从我这几年帮人看问题的经验触发场景其实高度集中。第一种是刚装完 Git、第一次连 Gitee压根没生成过密钥用的是仓库页面给的 SSH 地址自然认证失败。第二种是生成了密钥也加到了 Gitee但密钥文件名不是默认的id_rsa或id_ed25519ssh 默认只扫这两个名字扫描不到就等于没有。第三种是把公钥和私钥搞反了——把id_rsa的内容贴进了 Gitee 的公钥框或者把id_rsa.pub留在了本地当私钥用。第四种是多平台混用本地已经有 GitHub 的密钥Gitee 又生成了一个新名字的密钥没写 config 文件ssh 不知道该给谁用。第五种最隐蔽在 Linux 或 macOS 上私钥文件的权限位太开放比如644甚至777OpenSSH 出于安全考虑会直接忽略这个私钥然后一路走到 Permission denied。还有一种不太算错的场景公司网络限制了 22 端口出入ssh 连不上 22超时或者被重置表现出来也可能是连接被拒。这种时候得换协议或者换入口后面会细说。1.3 先做三件事别急着删密钥重来很多人一遇到这个报错就把.ssh目录清空重来这是最亏的做法因为原有密钥可能还挂在别的服务上。正确的第一步是先自检。打开终端先看目录里有什么ls -al ~/.ssh。第二步用 ssh 自己测一次连接ssh -T gitgitee.com。第三步看这句测试命令的输出到底停在哪如果提示Host key verification failed那是主机指纹问题如果提示 Permission denied那才是密钥问题如果直接卡住不动最后超时那是网络或端口问题。三步走完你就知道自己面对的是哪一类故障再去动手效率完全不一样。注意ssh -T gitgitee.com里的-T是明确告诉 ssh不要分配终端因为 Gitee 只做认证不给你 shell。不加这个参数会看到一句奇怪的提示容易让人误判。2. 公钥私钥这对东西是怎么工作的2.1 一把锁和一把钥匙的类比SSH 密钥认证的本质非常简单可以用一把挂锁来理解。你生成密钥对的时候其实同时造出了一把锁和一把钥匙。公钥就是那把锁你可以随便复制、随便贴到任何平台上贴到 Gitee 就相当于把锁挂在了 Gitee 的大门上私钥是那把唯一的钥匙它必须留在你自己的电脑里谁拿到它谁就能冒充你。当你连接 Gitee 时服务器会说我这挂着一把你给的锁你能打开它吗你的 ssh 客户端就用本地私钥去开这把锁开得了就证明你确实是锁的主人。这里面有一个常被误解的点公钥是可以公开的贴到任何地方都不算泄露私钥一旦泄露必须立刻作废重新生成因为别人拿它就能以你的身份推送代码。所以千万不要把私钥内容贴到任何网页、聊天窗口或者 issue 里也不要为了让别人帮你调试而把私钥发出去。我见过有人把id_rsa的完整内容贴到论坛求帮忙那基本等于把家门钥匙拍照发到了网上。2.2 Gitee 校验时真正比对的四个环节从具体流程看Gitee 侧的公钥校验大致经过四个环节。第一ssh 客户端发起连接声明自己支持的认证方式第二服务端返回可接受的认证方式列表其中包含 publickey第三客户端发送我想用某个公钥的指纹试试服务端在自己的公钥库里检索这个指纹找不到就直接拒绝这一层失败会立刻报 Permission denied连签名挑战都不会做第四服务端找到指纹后发一段随机数据让客户端用私钥签名服务端用登记的公钥验签验过才通过。这四个环节对应了四类不同的排错方向指纹根本不在库里说明公钥没添加或添加错了指纹在库里但验签失败说明私钥和公钥不配对或者本地用的私钥不是你贴上去那把对应的私钥服务端压根没返回 publickey 选项那通常是连错了主机全程没到第三步就断了那是网络层问题。2.3 不是所有 Permission denied 都是密钥问题有一种情况需要特别提醒Permission denied (publickey)也有可能是你在跟错的主机说话。比如有些人的 DNS 或者 hosts 被改动过gitee.com解析到了一个不该去的地方又比如你在~/.ssh/config里写过Host *的通配规则把gitee.com的 User 改成了自己的账号名那 Gitee 收到的是以你的账号名登录而不是以 git 登录照样会拒绝。还有一种情况是仓库地址本身就不需要 SSH。你在 Gitee 仓库页面点克隆/下载的时候可以选 HTTPS 或 SSH 两种地址。如果你复制的是 SSH 地址那必须有密钥如果你只是想快速拉个开源项目看看代码用 HTTPS 地址完全够用公开仓库甚至不需要登录。搞清楚这个区别能省掉一大半折腾。3. 从零配一套能用的 Gitee SSH 密钥3.1 先确认本机有没有现成的密钥动手之前先看一眼别重复造。打开 Git BashWindows或终端macOS/Linux执行ls -al ~/.ssh。如果有id_rsa和id_rsa.pub这一对或者id_ed25519和id_ed25519.pub这一对说明你已经有默认密钥了那就跳到第 3.3 节直接把已有的.pub内容贴到 Gitee 即可。如果目录不存在或者只有一个known_hosts文件那就老老实实从头生成。Windows 上要特别注意一件事系统里可能同时存在两套 ssh。一套是 Windows 自带的 OpenSSH通常在C:\Windows\System32\OpenSSH\下另一套是 Git for Windows 自带的通常在 Git 安装目录的usr\bin\下。这两套读的配置文件位置可能不一样~/.ssh的家目录解释也可能不同。判断当前用的是哪一套执行which sshGit Bash 里或where sshCMD 里就能看出来。如果 Git 用的是一套、你配置密钥时命令行用的是另一套就会出现我明明配好了为什么还是不行的诡异现象。3.2 生成密钥的参数选择与取舍逻辑生成命令的核心是ssh-keygen。最推荐的写法是ssh-keygen -t ed25519 -C 你的邮箱或备注这里的-t指定算法类型-C是给密钥加一个注释通常填邮箱方便你以后在 Gitee 的公钥列表里认出这是哪台机器的密钥。注释只是标签不影响认证但强烈建议填因为当你手上有好几台设备时删错公钥是很常见的事故。算法为什么优先选 ed25519 而不是 rsaed25519 是近几年主流的椭圆曲线算法密钥长度短、生成快、签名验签也快安全性足够而且它生成的公私钥文本都很短贴进网页表单不会因为长度被截断。老牌的 rsa 需要至少 2048 位才有基本安全性一般建议 4096 位生成时会有几秒卡顿公钥文本也比较长。如果你维护的是十年以上的老系统可能遇到不支持 ed25519 的情况那就退回ssh-keygen -t rsa -b 4096 -C 你的邮箱。执行命令后会有三个交互。第一个问保存路径直接回车用默认的~/.ssh/id_ed25519就行如果你要区分多平台这里可以输入自定义路径比如~/.ssh/id_ed25519_gitee。第二个和第三个问 passphrase也就是给私钥再加一层密码。加了之后每次使用都要输密码安全性更高但麻烦如果你觉得本机是自己独占的、懒得输直接两次回车留空也可以。我的建议是笔记本随身带、有丢失风险的加一个 passphrase固定工位台式机可以不加。3.3 把公钥贴到 Gitee 的正确位置生成完之后用cat ~/.ssh/id_ed25519.pub把公钥内容打印出来。你会看到一整行以ssh-ed25519开头、以你的注释结尾的文本。注意这里要复制的是.pub结尾的那个文件不是没有后缀的私钥文件。复制这整行内容登录 Gitee进入个人设置找到安全设置里的SSH 公钥点击添加公钥。标题随便填能区分设备就行比如办公台式机、家里笔记本。公钥内容粘贴进去保存。Gitee 会校验这串文本的格式格式不对会直接提示你这也是为什么不要手工改动里面任何一个字符——多一个空格、少一个换行都可能失败。提示Gitee 允许一个账号添加多个公钥也允许同一个公钥被不同账号添加因为公钥只是标识不代表独占。但同一个公钥反复添加是没有意义的重复添加不会加速任何事情。3.4 首次连接要做的主机指纹确认添加完公钥再回到终端执行ssh -T gitgitee.com。第一次连接时ssh 会问你是否信任这台主机提示大概长这样The authenticity of host gitee.com cant be established... Are you sure you want to continue connecting (yes/no)?。这里输入yes回车ssh 会把 Gitee 的主机指纹记到~/.ssh/known_hosts里。之后再连接就不会问了。如果输出类似Hi XXX! Youve successfully authenticated, but Gitee.com does not provide shell access.的句子恭喜你认证通了。那句不提供 shell 访问是正常的因为 Gitee 只用来托管 Git 仓库不给你登录用的命令行。看到这句话就说明 SSH 这一层已经打通接下来git clone、git push都不会再报 Permission denied。反过来如果还是 Permission denied那就带着这套已经配好的环境进入下一章的排查流程。3.5 多平台、多账号共存时 config 怎么写现在很多人手上不止一个代码托管平台也可能一个平台有工作号和私人号两个账号。这种情况下默认密钥名id_rsa、id_ed25519就不够用了必须靠~/.ssh/config来分流。假设你为 Gitee 生成了~/.ssh/id_ed25519_gitee那 config 里可以这样写Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes这段配置的含义是当目标主机是gitee.com时用git作为用户名只使用id_ed25519_gitee这一把私钥。其中IdentitiesOnly yes是关键它告诉 ssh 不要自作聪明地去尝试其他所有能找到的私钥。不加这一行ssh 可能会把 GitHub 的密钥也拿去试尝试次数太多会被服务端限流反而拖慢连接。配置文件对格式很讲究Host顶格写下面的选项缩进两个空格冒号后面的值不要有多余空格。写完保存用ssh -T gitgitee.com验证通了就说明配置生效。如果你有多个平台就多写几个 Host 块互不干扰。4. 分场景排查不同细节对应不同病根4.1 排查速查表现象最可能的原因处理方式从未生成过密钥本地没有密钥对执行 ssh-keygen 生成并添加公钥有密钥但报错不变公钥未添加或添加成了私钥检查 Gitee 公钥内容是否为 .pub 内容密钥名非默认ssh 不会自动扫描写 config 指定 IdentityFileLinux/macOS 权限报错私钥权限过于开放chmod 700 ~/.sshchmod 600 私钥连接直接超时22 端口不通换 HTTPS 协议或确认网络策略提示 Host key verification failed主机指纹变了清理 known_hosts 中对应条目后重连同一个密钥多平台混用未做分流用 config 按 Host 指定不同密钥添加公钥后立刻报错复制时多了换行或空格重新完整复制粘贴这张表基本覆盖了九成以上的实际案例。遇到问题先按表格对一遍比漫无目的试命令要快得多。4.2 私钥权限这个坑Linux 和 macOS 上最容易踩Windows 上因为文件系统权限模型不一样OpenSSH 对权限的要求相对宽松很多人从 Windows 转到 macOS 或 Linux 后直接把整个.ssh目录复制过来权限位也跟着复制了结果就是一直 Permission denied。在 macOS 和 Linux 上ssh 对私钥文件权限是强校验的私钥必须是600只有自己可读写.ssh目录建议700只有自己可进入公钥和known_hosts一般644。如果私钥是644或更开放ssh 会直接跳过它并在-v日志里留下ignoring key之类的记录。修复命令就三条chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub改完立刻再测一次ssh -T gitgitee.com很多人的问题到这里就结束了。4.3 ssh-agent 到底要不要用ssh-agent 是一个在后台帮你保管私钥的小服务。它的价值在于当你的私钥设了 passphrase没有 agent 的话每次 git 操作都要重新输一遍密码有了 agent你只在开机后ssh-add一次后面就不用了。是否启用看你自己的习惯。启用方式分三步先启动 agenteval $(ssh-agent -s)再把密钥加进去ssh-add ~/.ssh/id_ed25519最后验证ssh-add -l会列出当前已加载的密钥指纹。这里有个常见误区agent 里加载的密钥和你实际要用的密钥不是同一把。比如你加载了 GitHub 的密钥但连接 Gitee 时应该用id_ed25519_gitee那还是不行。所以 agent 加载完最好用ssh-add -l对一下指纹确认加进去的那把确实是你要用的。Windows 上还有一个额外可能如果你用 PowerShell 而不是 Git Basheval这种写法不通用得用系统服务方式启动 ssh-agent或者干脆在 Git Bash 里操作。混用不同终端是 Windows 下排查这类问题的常见障碍。4.4 用 ssh -vT 读日志的正确姿势当前面的招数都用过了还是不行就该看日志了。命令是ssh -vT gitgitee.com-v会打印详细的握手过程。日志很长新手容易看晕你只需要盯几个关键行。看到Offering public key: ...说明客户端确实拿出了某把公钥看到Server accepts key: ...说明服务端认可这把公钥的指纹看到Authentications that can continue: publickey说明服务端要求公钥认证最终如果出现Permission denied往前翻几行看它到底试了哪几把密钥路径是什么。如果你发现日志里Offering的密钥路径跟你以为的不一样那就是 ssh 读的目录和你配置的目录不一致多半是 Windows 双 ssh 环境的问题或者 config 文件的位置不对。这种时候用ssh -vT输出里Reading configuration data那一行确认它到底加载了哪个 config 文件是解决问题的钥匙。5. 一次完整的报错到推送成功的现场记录5.1 现场还原我拿一台刚装完系统、只装了 Git for Windows 的机器复现了一次。第一步装完 Git 后直接在项目目录里执行git remote add origin gitgitee.com:user/demo.git然后git push -u origin master。终端立刻返回文章标题里那条完整报错。第二步执行ls -al ~/.ssh提示目录不存在确认是从来没生成过密钥。第三步ssh-keygen -t ed25519 -C demoexample.com路径全默认passphrase 两次回车跳过。第四步cat ~/.ssh/id_ed25519.pub复制整行去 Gitee 后台添加公钥。第五步ssh -T gitgitee.com输入 yes 确认指纹返回成功认证的提示。第六步重新git push -u origin master这次顺利推上去了。整个流程不到五分钟。这也说明一件事新手遇到这个报错先别折腾先确认自己有没有密钥往往一步就能定位。5.2 顺带把 HTTPS 免密也配好有些场景下 SSH 确实不好使比如公司网络封了 22 端口或者你的运行环境里不方便管理密钥文件。这种时候 HTTPS 是更好的选择。Gitee 的 HTTPS 地址可以配合私人令牌使用把令牌当成密码就能避免每次输账号密码——虽然现在 Gitee 更多是让你用密钥和令牌结合的方式最省事的其实是本地凭据缓存。Git 提供了一个凭据存储机制执行下面这条命令开启缓存git config --global credential.helper store之后第一次推送时输入账号和令牌Git 会把它存到本地后续就不用再输了。Windows 上还可以用 Git Credential Manager图形化弹窗体验更接近日常软件的登录方式。要注意的是store是明文存储如果机器是多人共用的建议换成cache模式或者干脆继续用 SSH。提示HTTPS 和 SSH 两条路可以并存。同一台机器上用一个仓库走 SSH、另一个仓库走 HTTPS 完全没问题Git 是按仓库的 remote 地址来决定用哪种协议的。5.3 迁移到新机器时的顺手操作换电脑这件事很多人处理得很糙直接把自己的.ssh目录整个拷过去然后发现权限不对、config 里的绝对路径不对、agent 里的密钥没带过去。更稳妥的做法是只迁移必要的东西把私钥和公钥这两对文件拷过去把 config 文件也拷过去然后在目标机器上重新跑一遍权限设置重启一次 agent 并重新ssh-add。同时建议在 Gitee 后台给新机器单独加一个公钥而不是复用旧机器的——这样万一某台机器出问题你可以精确地吊销某一台而不影响其他设备。6. 几条踩过坑之后总结的心得6.1 密钥管理上的几条硬规矩第一条私钥永远不出本机不截图、不发聊天、不贴网页。第二条一个设备一对密钥别在多台机器之间共享同一把私钥出了问题你都不知道是哪台泄露的。第三条公钥在 Gitee 后台的标题写清楚设备和用途删除的时候不犹豫凡是看起来不认识的公钥都值得警惕。第四条定期清理known_hosts里已经不存在的主机条目虽然不影响使用但会让日志变干净。第五条也是我认为最重要的遇到认证问题先跑ssh -T gitgitee.com再动手。这一条命令相当于一次独立体检它把 Git 这一层剥掉了直接测 SSH 认证。体检通过那问题就在 Git 的 remote 地址或者仓库权限上体检不通过那就在密钥体系里。先把故障域缩到一半再深挖效率差距非常大。6.2 几个高频疑问的直给答案有人会问为什么我在 GitHub 上好好的到 Gitee 就不行因为两个平台的公钥库是互相独立的你在 GitHub 添加过的公钥Gitee 那边没有记录必须重新添加。密钥本身可以复用同一把只是公钥要分别贴到两个平台。还有人问我明明把公钥加上了为什么还报错先检查你加的是不是.pub文件的内容再检查你本地是不是只生成过一对密钥但生成时改了路径。前者是复制对象错了后者是 ssh 找不到密钥。另外常见的是仓库地址用错了。Gitee 仓库页面上的 SSH 地址格式是gitgitee.com:用户名/仓库名.git如果是自己复制时多带了空格或者把 HTTPS 地址当成 SSH 用都会出错。用git remote -v看一眼当前远程地址是最快的确认方式。最后一个是我加了 passphrase 之后每次都提示要输。这是正常行为嫌烦就启动 ssh-agent 并ssh-add或者重新生成一对不带 passphrase 的密钥。没有别的原因也不用怀疑配置。6.3 后续还能往哪走这套密钥体系打通之后能延展的事情其实不少。比如你可以在 CI 流水线里配置部署密钥让构建机器能拉取私有仓库可以给自己的服务器配免密登录省掉每次输密码的麻烦也可以用同样的思路处理多平台账号共存把工作号和私人号彻底隔开。核心逻辑始终是那一条公钥贴到被访问的一端私钥留在发起访问的一端中间靠 config 文件决定给谁用哪把。我个人在多台设备之间来回切换之后最大的体会是密钥这件事一开始花二十分钟理解清楚后面能省下几十次抓耳挠腮。真正让人卡住的从来不是命令有多难而是不知道报错在说什么。现在再看到Permission denied (publickey)它对我而言就是一句话本地没有拿出正确的那把钥匙。确认钥匙在不在、名字对不对、权限对不对、平台登记了没有四个问题问完问题基本就解决了。