GitLab SSH拉取失败排查：Permission denied (publickey)与密钥权限问题全解析-代码聚汇网

GitLab SSH拉取失败排查：Permission denied (publickey)与密钥权限问题全解析

刘炳琦·2026-09-02·阅读 21 GEO检测（免费）

GitLabSSHPermission denied

|难度：普通|阅读约 34 分钟

今天早上刚坐到工位，打开终端习惯性 git pull 准备拉一手最新代码，结果一行红字直接把我整不会了：

code复制git@gitlab.com: Permission denied (publickey).
fatal: Could not read from remote repository.

昨天下午还好好的，晚上也没人动过服务器，怎么就拉不下来了？我当时的反应和大多数同事一样：先怀疑 GitLab 挂了。登网页一看，项目首页、提交记录、分支列表全正常，说明服务本身没问题。再试 SSH 协议、HTTP 协议，发现 HTTP 能通，SSH 拉取必挂。这时候才意识到，问题出在 SSH 这一层的"权限"上。

这篇就是这次排查的全过程记录。里面会有我实际敲过的命令、看过的日志、翻车的位置，以及最后定位到的根因——一个看起来毫不起眼、但杀伤力巨大的本地权限问题。如果你哪天也遇到 GitLab SSH 拉取失败，报错长得像上面这样，这篇文章应该能帮你省下一上午的排查时间。

1. 故障现场：git pull 报错时的三类典型症状

1.1 "Permission denied (publickey)" 的直接打脸

最典型、也最常见的就是这一句：

code复制$ git pull origin main
git@gitlab.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

这串报错里，真正有用的信息其实只有第一句：Permission denied (publickey)。后面两句话完全是 Git 的"兜底提示"，告诉你可能没权限、可能仓库不存在，说得模棱两可。很多朋友（包括当年的我）看到 "Please make sure you have the correct access rights and the repository exists" 就去检查仓库路径、确认分支名，甚至去 GitLab 网页上看项目还在不在，方向完全跑偏了。

publickey 这个词值得拆开看。它意味着 GitLab 的 SSH 服务确实收到了你的连接请求，网络层、端口、SSH 服务本身都是通的，但认证阶段没有通过——你提供的公钥不在它的白名单里，或者你压根没把一个有效公钥提供给对方。一句话总结：连接没问题，身份没验上。

1.2 "Could not read from remote repository" 的误导性

这个报错是 Git 的一层"包装错误"。无论 SSH 底层挂掉的原因是什么——密钥没配、权限不对、主机 key 变了、网络代理劫持——Git 统一给你吐一句 fatal: Could not read from remote repository。它把真正的原因藏在前面，但很多人只记住了后半句。

code复制$ git clone git@gitlab.com:somegroup/someproject.git
Cloning into 'someproject'...
git@gitlab.com: Permission denied (publickey).
fatal: Could not read from remote repository.

注意看，真正的线索在 clone 进度下面那一行：Permission denied (publickey)。它和 Could not read from remote repository 之间是"原因和结果"的关系。以后看到这类报错，先往上看报错头部，别盯着最后一句猜。

1.3 另一类容易被误判成SSH问题的账号权限报错

还有一类报错，乍一看和 SSH 有关，其实是账号权限的事。如果你用的是 HTTP 方式，或者习惯从网页直接下载代码压缩包，报错长这样：

code复制remote: HTTP Basic: Access denied
fatal: Authentication failed for 'https://gitlab.example.com/...'

或者网页上点击 Download zip，返回一句 "You are not allowed to download code"。

这种情况跟 SSH 密钥没有任何关系，是 GitLab 账号本身对这个项目没有下载权限。在 GitLab 里，不是登录了网页就能拉所有代码。项目是 internal 或 private 时，你必须是项目成员，且角色在 Reporter 及以上，才能正常 clone 和 pull。Guest 这种角色，即使账号能登录、能看 issue，代码也拉不下来。

所以排查的第一步，永远是先分清"你是用哪种协议在拉代码"。这决定了后续要查的方向是本地 SSH 配置，还是 GitLab 账号权限。这个判断做错，后面全是无用功。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 排查链路：从握手日志一步步追到~/.ssh

2.1 先确认协议，再谈权限

我第一件事是确认仓库的 remote 地址：

code复制$ git remote -v
origin  git@gitlab.com:devops/deploy-tools.git (fetch)
origin  git@gitlab.com:devops/deploy-tools.git (push)

开头是 git@gitlab.com，说明走的是 SSH 协议。如果是 https://gitlab.com/... 开头，那就是 HTTP 协议，排查方向完全不一样。确认完协议，接下来进入 SSH 的深度检查。

2.2 -v 参数下的SSH握手过程解读

SSH 有个特别实用的调试参数 -v，能打印整个握手过程。连接 GitLab 可以这样测：

code复制$ ssh -T -v git@gitlab.com

-T 的意思是不要分配终端，因为 GitLab 的 SSH 服务不接受登录 shell，只会响应 Git 命令和握手测试。-v 是 verbose 模式。

正常情况的输出里，你会看到几行关键日志：

code复制debug1: Offering public key: /home/user/.ssh/id_rsa RSA SHA256:xxxxxxxx...
debug1: Server accepts key: /home/user/.ssh/id_rsa ...
Authenticated to gitlab.com ([xx.xx.xx.xx]:22).
Welcome to GitLab, @zhangsan!

这里的关键是 Offering public key 和 Server accepts key。前者表示本地 SSH 客户端找到了一把私钥并主动抛给服务器，后者表示服务器接受。之后出现 Welcome to GitLab, @你的用户名，就说明 SSH 认证完全打通了。

而我这次的情况是这样的：

code复制debug1: Offering public key: /c/Users/myuser/.ssh/id_rsa RSA SHA256:xxxxxxxx...
debug1: Authentications that can continue: publickey
debug1: No more authentication methods to try.
git@gitlab.com: Permission denied (publickey).

注意看，客户端确实 Offering public key 了，但服务器没有返回 Server accepts key，而是继续列出可用的认证方法，最后干脆拒绝。这说明：本地有私钥，也尝试提交了，但 GitLab 端不认这把公钥。到这一步，大概率是两种情况——要么公钥和私钥不匹配/没绑到这个账号，要么某个环节有更底层的东西拦住了（比如权限过宽导致 SSH 直接跳过这把密钥）。

2.3 真正的问题：私钥文件权限过宽

上面 -v 的日志还有一种变体，就是连 Offering public key 都没有，或者有但明显是"被过滤掉了"。这时候回到本地看一眼 ~/.ssh 目录：

code复制$ ls -la ~/.ssh
total 24
drwxrwxr-x 2 user user 4096 3月 19 10:22 .
drwxr-xr-x 8 user user 4096 3月 19 09:01 ..
-rw-r--r-- 1 user user 3381 3月 18 16:44 id_rsa
-rw-r--r-- 1 user user  742 3月 18 16:44 id_rsa.pub
-rw-r--r-- 1 user user 1234 3月 18 16:44 known_hosts

看到 id_rsa 的权限是 -rw-r--r-- 时，我心里已经明白问题出在哪了。私钥文件是不允许除了 owner 之外的人读的，而 -rw-r--r-- 表示文件 owner 以外的人也能读。OpenSSH 出于安全考虑，一旦发现私钥文件的权限过宽，会直接拒绝使用这把密钥做认证。

这里我补充一句原理，方便大家理解：SSH 私钥本质上是"身份凭证"，它不需要密码就能被用来登录你绑定的账号。如果这个文件对所有系统用户都可读，那和把家门钥匙贴在门框上没什么区别。所以 OpenSSH 客户端在加载密钥前会检查文件权限，发现太开放就直接跳过，根本不拿去认证。

这正好解释了我的 -v 日志为什么那么诡异：客户端想加载密钥，但安全检查没过，密钥被丢弃了；之后又没有其他可用密钥，于是认证失败。

3. 根因拆解：这里的"权限"至少有五种

排查到 id_rsa 权限过宽，我把 .ssh 目录修好后，顺手把这条踩坑经验整理了一下。其实"GitLab SSH 拉取失败 + 权限问题"这组关键词，指向的东西远不止一个。同一个症状背后，可能有五种完全不同的"权限"在作祟。

3.1 本地文件权限：~/.ssh 目录与密钥文件

这是本次事故的根因，也是最常见、最隐蔽的一个。OpenSSH 对本地文件权限有一套硬性要求：

路径	推荐权限	说明
`~`（用户主目录）	755 或 700	不能是 777，不能 group/world 可写
`~/.ssh` 目录	700	其他人应无任何权限
`~/.ssh/id_rsa`（私钥）	600	只有 owner 可读写
`~/.ssh/id_rsa.pub`（公钥）	644	公钥本来就是公开的，可读无妨
`~/.ssh/known_hosts`	644	记录主机指纹，可读
`~/.ssh/config`	600 或 644	可能包含代理配置，建议 600

很多人只修密钥文件的权限，忽略了 .ssh 目录本身的权限，结果照样不行。.ssh 目录权限如果过宽（比如 777），SSH 一样会警觉——目录谁都能翻，私钥就算藏得再好也等于没藏。

3.2 ssh-agent 是否加载了私钥

ssh-agent 是内存中的密钥代理。它帮你缓存私钥，避免每次 SSH 都输入 passphrase。很多情况下，密钥文件权限没问题，但 agent 里面是空的，SSH 连接也会失败。

检查方式：

code复制$ ssh-add -l
The agent has no identities.

如果有密钥，会列出 SHA256 指纹；如果提示 Could not open a connection to your authentication agent，说明 agent 进程都没起来。这在 macOS 和 Windows 上比较常见，系统重启后 agent 服务可能没自动启动，导致里面缓存的所有密钥统统消失。此时即使密钥文件权限全对，SSH 客户端也可能找不到可用私钥。

3.3 GitLab账号侧的SSH Key绑定

密钥文件权限修好了，agent 也正常了，还有一种可能：你的公钥根本没绑定到 GitLab 账号上。尤其是新换电脑、新装系统之后，很多人只在本机生成了一对新密钥，压根没把公钥贴到 GitLab 的 SSH Keys 页面。

这时 ssh -T -v 的输出往往是：客户端 offers key，服务器表示不认识，拒绝。判断标准很简单：ssh -T git@gitlab.com 如果返回 Welcome to GitLab, @username! 就表示账号侧没问题；如果还是 Permission denied，就登录 GitLab 网页，检查 Settings -> SSH Keys 里有没有对应公钥。

有个细节我要重点提醒：粘贴公钥时，一定要复制 id_rsa.pub 文件里的内容，不是 id_rsa（私钥）。私钥内容贴上去不仅认证不过，还会造成严重的安全泄露。这个错误我在同事的电脑上见过不止一次。

3.4 GitLab项目角色的权限边界

SSH 握手成功，Welcome to GitLab 也出来了，但 git pull 依然报错？那问题大概率出在 GitLab 的项目角色权限上。

GitLab 的权限体系分两层：第一层是传输层认证，也就是 SSH key 验证，决定"你是谁"；第二层是应用层授权，决定"你能对这个项目做什么"。即使第一层通过，第二层依然可能把你拦在仓库外面。

角色的权限边界大致是：Guest 可以浏览 issue、讨论，但没有代码下载权限；Reporter 起才有 clone/pull 代码的资格；Developer 可以 push 分支；Maintainer/Owner 负责更高阶的管理。你拿着合法密钥、访问一个 private 项目，如果不是项目成员，GitLab 会在应用层拒绝你的 Git 操作，返回类似 "The project you were looking for could not be found" 或者直接权限不足。

这类型问题在团队收紧权限后特别容易踩中。比如管理员把所有项目从 public 改成了 internal 或 private，又关闭了 Guest 访问，或者调整了成员角色，第二天就会有一堆人反馈"拉不了代码"。这时候不要折腾本地密钥，去 GitLab 项目成员列表看自己的角色就够了。

3.5 known_hosts 变化带来的间接"权限"错误

还有一种容易被误认成权限问题的场景：GitLab 服务器重建、容器迁移或证书更换，导致服务器的 host key 变了。SSH 客户端连接时会发现 known_hosts 里记录的指纹和服务器实际指纹不一致，于是报：

code复制WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!

虽然这本质上更接近"信任权限"问题，但很多人在它发生后会顺手重新生成密钥、折腾权限，甚至重装 GitLab 客户端，其实都没用。正确做法是确认服务器确实换过，然后删除 known_hosts 里对应条目，再重新连接并信任新指纹。如果服务器没换过却报这个，那才是真的需要警惕的安全事件。

4. 修复实操：按顺序走完这一套，九成能解决

排查完之后就是修复。下面按我实际操作顺序整理，建议你也按这个顺序来，能少走很多弯路。

4.1 修正SSH目录下的文件权限

在 Linux / macOS / Git Bash 环境下，直接跑：

code复制chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
chmod 644 ~/.ssh/known_hosts

如果你有多个私钥，比如 id_ed25519、id_ecdsa，把它们也设置成 600：

code复制chmod 600 ~/.ssh/id_*

这一步做完，再用 ssh -T -v git@gitlab.com 测试一遍。正常情况下，Offering public key 之后会紧接着出现 Server accepts key，然后就是 Welcome。我这次就是修完这步就解决了。

另外，~ 用户主目录本身的权限也要注意。如果家目录设置在共享盘或挂载目录上，出现 group/world 可写的情况，SSH 同样会拒绝加载密钥。Linux 下检查一下：

code复制ls -ld ~

如果是 777 或者 owner 之外可写，顺手 chmod 755 ~。

4.2 处理Windows下的ACL特殊权限

如果你用的是 Windows，修完 Unix 权限位仍然失败，那就要检查 NTFS 的 ACL 了。Git for Windows 的 SSH 会检查文件在 NTFS 层面的 ACL，而不仅仅是 ls -la 看到的那些权限位。

典型表现是：在 Git Bash 里 chmod 600 看似成功了，ls -la 也正常了，但 SSH 还是不认密钥。原因通常是最初从别处拷贝或解压出来的文件，ACL 里残留了 Everyone、Authenticated Users 等继承权限。

解决办法有两种。

第一种，图形界面操作：右键 .ssh 文件夹 -> 属性 -> 安全 -> 高级 -> 禁用继承 -> 将已继承的权限转换为显式权限 -> 删除所有多余的账号，只保留当前用户和 SYSTEM。对里面每个私钥文件也做同样的处理。

第二种，命令行操作，用 icacls：

code复制icacls "C:\Users\你的用户名\.ssh" /inheritance:r /grant:r "%USERNAME%:F" /grant:r "SYSTEM:F"
icacls "C:\Users\你的用户名\.ssh\id_rsa" /inheritance:r /grant:r "%USERNAME%:F"

这里 %USERNAME% 会自动替换成当前用户名。注意，如果你在终端里跑这个命令，最好在管理员权限的 PowerShell 或 CMD 里执行。

提示：如果你的 Windows 用户名是中文或有特殊字符，Git Bash 可能会报 could not create directory '/c/users/xxx/.ssh' (no such file or directory)。这是因为编码和路径解析问题，可以让 Git Bash 把 HOME 显式指向当前用户的 .ssh 所在目录，比如 export HOME="/c/Users/你的用户名"，再重新生成和加载密钥。

4.3 把密钥重新注册进ssh-agent

文件权限修好以后，顺手把密钥重新加载进 agent，避免 agent 还缓存着旧状态或者根本没加载：

code复制eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
ssh-add -l

ssh-add -l 能列出当前 agent 里已加载的密钥指纹。如果列表为空，说明加载失败，重新检查一次路径和权限。

Windows 用户如果提示无法连接 agent，需要先把 OpenSSH Authentication Agent 服务打开：

code复制Get-Service ssh-agent
Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

4.4 重新验证握手并拉取

一切就绪后，再跑一次握手测试：

code复制$ ssh -T git@gitlab.com
Welcome to GitLab, @zhangsan!

看到 Welcome 就说明认证打通了，再 git pull 基本就没问题。

如果 Welcome 出来了但拉取依然失败，就别再和 SSH 较劲了，直接去 GitLab 网页看项目权限。确认你的账号在项目成员列表里，角色至少是 Reporter 以上。如果项目是 private，而你只是被拉进去浏览 issue 的 Guest，那无论 SSH 多正常都拉不了代码。

4.5 临时救急：用HTTP加Personal Access Token

如果短时间真的搞不定 SSH（比如公司 GitLab 的 SSH 服务本身有问题，或者密钥因为合规要求不能直接配置），可以考虑用 HTTP 协议加 Personal Access Token 临时顶上。

在 GitLab 网页上生成一个 token：头像 -> Settings -> Access Tokens，勾选 read_repository 权限，生成后复制保存。

然后用 token 作为密码拉取：

code复制git clone https://oauth2:你的TOKEN@gitlab.com/group/project.git

或者不改 remote，只对单次命令生效：

code复制git -c http.extraheader="Authorization: Bearer 你的TOKEN" pull

注意，token 相当于密码，别写进脚本提交到仓库里。这只是临时方案，问题解决后尽快回到 SSH 的方式。

5. 延伸避坑：类似场景下我总结的几条经验

排查完这次问题，我复盘了一下这些年踩过的类似坑，发现"拉取失败 + 权限问题"的组合还容易在另外几个变种场景里出现。顺手整理出来，给大家做个参考。

5.1 换了电脑、容器或虚拟机，密钥别乱拷

我有个同事，把 Windows 上用的 id_rsa 直接拷到 Linux 服务器上继续用，结果 SSH 一样报 Permission denied。他以为密钥坏了，其实是因为拷贝过去的文件权限是默认的 644，SSH 又拒绝加载了。正确的做法有两条：一是新机器上重新用 ssh-keygen -t ed25519 生成新密钥，再把公钥加到 GitLab；二如果非要复用一把私钥，拷完必须立刻修正权限，并确认该密钥没有被旧设备泄露过。认真讲，一个账号一把独立的密钥更合理，哪天电脑丢了，吊销对应的 key 就行，不需要重新生成所有环境里的密钥。

5.2 多GitLab账号时，用 ~/.ssh/config 指定密钥

经常有人同时使用公司 GitLab 和个人 GitLab，两个账号各有一把密钥。如果都放在默认路径 ~/.ssh/id_rsa，SSH 会拿同一把密钥去撞两个服务器，结果往往是一个能用、一个不能用。

推荐做法是在 ~/.ssh/config 里按 Host 区分：

code复制Host gitlab.company.com
  HostName gitlab.company.com
  User git
  IdentityFile ~/.ssh/id_rsa_company

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_rsa_personal

配置里 IdentityFile 指向的私钥文件，同样需要 600 权限。这个文件配置完成后，建议 ssh -T git@gitlab.company.com 和 ssh -T git@gitlab.com 分别验证一次。

5.3 老GitLab的RSA算法兼容问题

还有一个不是权限、但报错和权限几乎一模一样的坑：老版本的 GitLab 对 SSH key 算法的兼容性问题。

如果你的本机 OpenSSH 版本在 8.8 以上，而公司的 GitLab 还停留在比较老的版本，默认情况下 OpenSSH 会禁用 ssh-rsa 签名算法，导致连接时报 Permission denied (publickey)，但你的 key 和文件权限都是对的。

解决办法是在 ~/.ssh/config 里针对该服务器放宽算法：

code复制Host gitlab.old-server.com
  HostKeyAlgorithms +ssh-rsa
  PubkeyAcceptedAlgorithms +ssh-rsa

这相当于在兼容性和安全性之间做了取舍。如果公司有计划升级 GitLab（比如很多人搜过的"gitlab docker 升级 19 版本顺序"），升级后记得把这些兼容配置清洗掉，重新走安全的默认算法。

5.4 踩坑之后，我给自己留了张诊断清单

这次事件之后，我把 GitLab SSH 拉取失败的排查流程固化成了下面这张清单，每次都是十分钟内定位问题：

git remote -v：确认用的是 SSH 还是 HTTP。
ssh -T -v git@gitlab.com：看握手日志，确认密钥是否被提交、是否被服务器接受。
ls -la ~/.ssh：检查私钥和目录权限。
ssh-add -l：确认 agent 是否加载了密钥。
登录 GitLab 网页，检查 SSH Keys 里是否有对应的公钥。
进入项目成员页面，确认账号角色在 Reporter 以上。

这六步走完，能拦截掉九成以上的"拉取失败 + 权限问题"。剩下的个别情况，比如代理拦截、防火墙限制，再用 -v 日志进一步分析。

这次复盘也让我确认了一件事：写代码时容易忽视权限设置，但它恰恰是 SSH 安全模型的根基。以后再看到 Permission denied (publickey)，我不会再第一时间怀疑服务器了，先低头检查自己机器上的 ~/.ssh 文件夹——那个最常见、最不起眼、也最容易被忽略的地方。