Git SSH 实战避坑指南：公私钥到跨平台连接问题解析

呜呜好困啊
11 阅读12分钟

前言

本文整理自deepseek对话，全文由AI辅助编写，如若有错请评论留言，不定时处理。

涵盖公私钥原理、工具关联（TortoiseGit/PuTTY）、常见报错解决及核心原理拆解，适合 Git 初学者及遇到 SSH 连接问题的开发者参考。

一、基础认知：Git 公私钥核心概念

1.1 公私钥本质与作用

SSH 公私钥是 Git 连接远程仓库时最常用的认证方式，本质是一对加密密钥文件：

  • 私钥（Private Key）：存于本地（Windows 路径 C:\Users\用户名\.ssh\），绝对禁止泄露
  • 公钥（Public Key）：可公开上传至远程仓库（如 GitHub 的 SSH Keys 设置页），用于验证私钥签名的合法性

1.2 SSH 认证原理

SSH 认证的核心是基于非对称加密技术，通过私钥和公钥的配合完成身份验证：

SSH认证的三个核心步骤：

  1. 本地签名：当执行Git操作（如git pull、git push）时，本地Git客户端会使用你的私钥对「连接请求数据和认证信息」进行数字签名
  2. 远程验证：远程仓库服务器收到请求后，会使用你之前上传的公钥来验证这个数字签名的合法性
  3. 授权访问：如果验证通过（即确认是持有对应私钥的用户），则允许执行Git操作；如果验证失败，则拒绝访问请求

私钥必须妥善保管在本地，绝不能泄露；而公钥可以安全地上传至任何远程仓库服务。这种机制确保了只有持有正确私钥的用户才能执行Git操作。

1.3 ED25519 与 RSA 密钥对比

SSH认证机制依赖于非对称加密算法来生成公私钥对。在实际应用中，可以选择不同的加密算法来生成这些密钥，而算法的选择直接影响连接的安全性、兼容性和性能：

不同密钥算法具有不同特性，选择合适的算法是避免兼容性问题的关键：

特性RSAED25519
推出时间1977 年（传统老牌）2011 年（现代新型）
兼容性几乎所有 SSH 服务器支持部分老系统/平台未适配
密钥长度&安全性需 2048 位以上才安全（文件较大）256 位即可达高安全（文件小）
签名/验证速度较慢极快

提示：在企业环境或老旧系统中，RSA 密钥通常具有更好的兼容性

二、工具关联：TortoiseGit 与 PuTTY 的协作

2.1 核心关系说明

Git 公私钥是「身份凭证」，PuTTY 是「Windows 平台 SSH 工具集」，TortoiseGit（小乌龟）是「Git 图形化客户端」——小乌龟在 Windows 上默认依赖 PuTTY 的 SSH 工具处理公私钥认证，但PuTTY 并非小乌龟的唯一选择。

2.1.1 关于 PuTTY 的说明与替代选项

虽然小乌龟默认使用 PuTTY，但需要注意以下几点：

  1. PuTTY 并非必需：小乌龟可以配置使用其他 SSH 客户端，包括 Windows 10/11 自带的 OpenSSH 客户端
  2. 密钥格式兼容性：使用 PuTTY 时，需要将标准 OpenSSH 格式的公钥转换为 .ppk 格式（PuTTY 专用格式）
  3. 原生支持：Windows 10 1809 版本及以上，Windows 11 系统已内置 OpenSSH 客户端，无需额外安装

公钥转换为 .ppk 格式的具体步骤

如果您已有标准 OpenSSH 格式的密钥（如通过 Windows 自带的 ssh-keygen 生成的 id_rsa 文件），并希望在 TortoiseGit 中使用 PuTTY，则需要按以下步骤将其转换为 .ppk 格式：

  1. 打开 PuTTY 工具集中的 puttygen.exe
  2. 点击「Load」按钮，在文件选择对话框中选择您的 OpenSSH 私钥文件（通常是 id_rsa）
  3. 输入私钥密码（如果设置了的话）
  4. 点击「Save private key」按钮，将转换后的密钥保存为 .ppk 格式文件
  5. 现在可以在 TortoiseGit 中使用这个 .ppk 文件进行 SSH 认证了

注意：转换过程只需处理私钥，公钥仍可按原 OpenSSH 格式上传至远程仓库（如 GitHub、GitLab 等）

配置 TortoiseGit 使用 Windows 10/11 自带 SSH

Windows 10 1809 及更高版本、Windows 11 已内置 OpenSSH 客户端，您可以直接配置 TortoiseGit 使用系统自带的 SSH，无需安装 PuTTY：

  1. 首先确保 OpenSSH 客户端已安装并启用：

    • 打开「设置」→「应用」→「可选功能」→「添加功能」
    • 检查并安装「OpenSSH 客户端」

  2. 生成 OpenSSH 格式的密钥（如果还没有的话）：

    # 在 PowerShell 或命令提示符中执行
ssh-keygen -t rsa -b 2048 -C "你的邮箱地址"

  3. 配置 TortoiseGit 使用系统 SSH：

    • 在桌面或文件夹空白处右键，选择「TortoiseGit」→「设置」
    • 左侧导航选择「网络」
    • 在「SSH 客户端」下拉菜单中选择「OpenSSH」选项
    • 或者手动输入 OpenSSH 的 ssh.exe 路径（通常为 C:\Windows\System32\OpenSSH\ssh.exe）
    • 点击「确定」保存设置

  4. 上传公钥到远程仓库：

    • 公钥文件通常位于 C:\Users\用户名\.ssh\id_rsa.pub
    • 复制文件内容并添加到您的远程仓库 SSH Keys 设置中

配置完成后，TortoiseGit 将直接使用 Windows 系统自带的 SSH 客户端进行认证，无需处理 .ppk 格式转换，简化了工作流程。

2.2 PuTTY 核心组件及其功能

PuTTY 工具集中与 Git SSH 认证相关的核心组件包括：

  • puttygen.exe：密钥生成工具，生成 .ppk 格式密钥（PuTTY 私有格式，与 OpenSSH 的 id_rsa 不兼容）
  • plink.exe：命令行 SSH 客户端，小乌龟连接远程仓库时调用它执行认证
  • pageant.exe：密钥代理工具，加载 .ppk 私钥到内存，避免每次操作都需要输入密码

2.3 TortoiseGit 工作流程

在 Windows 环境下，TortoiseGit 使用 SSH 密钥的完整工作流程：

  1. 使用 puttygen.exe 生成 .ppk 格式 RSA 密钥（推荐 RSA 以避免兼容性问题）
  2. 在 TortoiseGit 设置中指定 SSH 客户端为 PuTTY 的 plink.exe 路径
  3. 使用 pageant.exe 加载 .ppk 私钥到内存中
  4. 通过 TortoiseGit 的图形化界面进行拉取/推送操作，内部会触发 plink.exe 完成 SSH 认证

三、实战问题：常见错误分析与解决方案

3.1 ED25519 公钥无法上传至微信 Git

问题分析

微信 Git 服务器暂未支持 ED25519 算法，仅兼容 RSA 等传统算法，这是平台侧支持范围的限制，与密钥本身无关。

解决方案：生成 RSA 密钥

根据使用的 SSH 工具，选择对应方式生成 RSA 密钥：

OpenSSH 生成（Windows 10/11 自带、Linux/Mac）
# 生成 RSA 密钥，2048 位，添加邮箱标识
ssh-keygen -t rsa -b 2048 -C "你的邮箱地址"
# 保存路径默认 C:\Users\用户名\.ssh\，回车确认
# 设置私钥密码（建议设置，提升安全性）
# 生成文件：id_rsa（私钥）、id_rsa.pub（公钥，需上传）
PuTTY 生成（适配 TortoiseGit）
  1. 打开 puttygen.exe，参数选择：密钥类型 RSA，位数 2048
  2. 点击"Generate"，移动鼠标生成密钥
  3. 设置 Key passphrase（可选，增强安全性）
  4. 保存私钥（.ppk 格式），复制"Public key for pasting into OpenSSH authorized_keys file"中的内容（即 RSA 公钥）

3.2 SSH 算法协商失败（no matching host key type found）

错误表现

git.exe clone --progress -v -- "git@git.weixin.qq.com:xxx/xxx.git" "本地路径"
Cloning into '本地路径'...
Unable to negotiate with 118.89.100.150 port 22: no matching host key type found. Their offer: ssh-rsa
fatal: Could not read from remote repository.

问题根源

  • 微信 Git 服务器仅提供 ssh-rsa 算法的主机密钥（用于验证服务器身份）
  • 新版本 OpenSSH 客户端为安全考虑默认禁用 ssh-rsa 算法
  • 双方无共同支持的算法，导致协商失败

注意：此问题与您的 RSA 密钥无关，是服务器主机密钥算法与客户端算法支持的冲突

解决方案

Windows 自带 OpenSSH 配置
  1. 进入 .ssh 文件夹：C:\Users\用户名\.ssh\
  2. 新建 config 文件（无后缀），写入以下配置：
# 仅对微信 Git 生效
Host git.weixin.qq.com
  HostName git.weixin.qq.com
  # 允许用 ssh-rsa 验证服务器身份
  HostKeyAlgorithms +ssh-rsa
  # 兼容 RSA 签名
  PubkeyAcceptedAlgorithms +ssh-rsa
  1. 保存文件，重新执行 Git 命令
PuTTY 配置（适配 TortoiseGit）
  1. 打开 putty.exe，左侧导航展开「Connection → SSH → Host Keys」
  2. 勾选 Host key algorithms 中的 ssh-rsa
  3. 展开「Connection → SSH → Auth → Pubkey Authentication」
  4. 勾选「Accept ssh-rsa signatures」
  5. 保存会话配置，通过 TortoiseGit 重新执行操作

3.3 仓库不存在错误（fatal: remote error: Git:Project not found）

问题场景

解决算法协商问题后，克隆操作时提示"Project not found"，说明 SSH 连接已成功建立，但服务器找不到目标仓库。

系统化排查步骤

按优先级执行以下排查：

  1. 验证仓库地址准确性

    • 从微信 Git 网页端仓库主页的「克隆/下载」选项中复制 SSH 地址
    • 仔细检查用户名、仓库名大小写、路径符号是否完全正确

  2. 确认访问权限

    • 若仓库为私有，需确认仓库所有者已将您的账号添加为成员
    • 确保您的账号角色至少为「开发者」权限

  3. 验证公钥绑定

    • 检查微信 Git 个人设置中的 SSH 密钥
    • 确保上传的是当前使用的 RSA 公钥，内容完整无多余空格

  4. 测试 SSH 连接

    • 在命令行执行 ssh -T git@git.weixin.qq.com
    • 若输出「Welcome to WeChat Git, 用户名!」则说明公钥绑定成功

3.4 跨平台差异：为何 GitHub 可用而微信 Git 不行？

SSH 连接的两步验证机制

SSH 连接需完成两个独立的验证步骤，均需客户端与服务器算法匹配：

步骤作用协商核心
第一步：验证服务器身份确认连接的是真实服务器（防中间人攻击）服务器提供主机密钥算法，客户端需支持其中一种
第二步：验证用户身份确认用户有仓库访问权限用户提供密钥算法（如 RSA），服务器需支持

GitHub 与微信 Git 的差异对比

对比维度微信 GitGitHub
服务器主机密钥算法仅提供 ssh-rsa（单一老旧选项）提供 ed25519、ecdsa、ssh-rsa（多选项，现代为主）
客户端协商结果客户端默认禁用 ssh-rsa，协商失败客户端优先使用现代算法（如 ed25519）协商成功
用户身份验证支持 RSA 密钥（但第一步失败，无机会执行）支持 RSA 密钥（第一步成功后正常执行）

四、深层原理：known_hosts 文件的作用与机制

4.1 known_hosts 的核心作用

.ssh 文件夹中的 known_hosts 文件，用于记录曾成功连接的远程 SSH 服务器的「主机密钥」，其核心作用是 防止中间人攻击：

  • 首次连接：记录服务器主机密钥，完成信任备案
  • 后续连接：自动比对当前服务器密钥与记录，一致则允许连接，不一致则警告并阻断连接

4.2 为何存储完整公钥而非仅指纹？

指纹是公钥的哈希摘要（主要用于人类核对），而存储完整公钥是 SSH 协议的核心要求，原因如下：

  1. 实时准确验证：后续连接时，客户端需用存储的完整公钥与服务器新发送的公钥分别计算指纹并比对
  2. 建立加密通道：验证服务器身份后，客户端需用服务器公钥加密「会话密钥」，仅存指纹无法完成此操作
  3. 兼容多客户端：不同客户端支持的指纹哈希算法（SHA256/MD5）不同，存储完整公钥可实时计算对应指纹

4.3 known_hosts 文件格式解析

文件中每行对应一条信任记录，格式如下：

git.weixin.qq.com ssh-rsa AAAAC3NzaC1yc2EAAAADAQABAAABAQC...
  • git.weixin.qq.com：远程服务器地址（域名/IP）
  • ssh-rsa：服务器主机密钥算法
  • 长串 Base64 字符串：服务器主机密钥的编码形式（核心身份凭证）

五、实用工具与操作技巧

5.1 查看公钥指纹（验证公钥正确性）

上传公钥后，可通过指纹对比确认未传错，不同工具对应不同方法：

OpenSSH 工具

# 查看本地公钥文件指纹（SHA256）
ssh-keygen -lf "C:\Users\用户名\.ssh\id_rsa.pub" -E sha256

# 查看公钥字符串指纹（PowerShell）
"ssh-rsa AAAAC3NzaC1yc2E... 你的邮箱" | ssh-keygen -lf /dev/stdin

PuTTY 工具

  1. 打开 puttygen.exe，点击「Load」加载 .ppk 私钥
  2. 界面直接显示 SHA256/MD5 格式指纹（对应公钥指纹）

5.2 确认 GitHub 官方指纹（防中间人攻击）

首次连接 GitHub 时，应对比客户端显示的指纹与官方指纹，确保连接的是真实服务器：

六、 最佳实践与经验总结

通过本文的学习，我们可以提炼出以下 Git SSH 使用的最佳实践：

  1. 密钥选择策略：在企业环境或老旧系统中，优先使用 RSA 密钥确保兼容性；个人项目或现代系统可使用 ED25519 获取更高安全性和性能

  2. 工具链统一：尽量在同一环境中保持 SSH 工具的一致性，避免混合使用 OpenSSH 和 PuTTY 导致的格式问题

  3. 安全意识：私钥必须妥善保管，定期更新密钥，使用强密码保护私钥

  4. 问题排查思维：SSH 连接问题本质上是「客户端-服务器」的算法与配置匹配问题，遇到报错时应系统分析而非盲目尝试

  5. 平台差异应对：不同 Git 服务提供商（GitHub、GitLab、企业私有 Git 等）可能有不同的 SSH 配置要求，需根据目标平台特点调整本地设置

通过掌握这些核心知识和实践技巧，开发者能够有效避免 Git SSH 连接中的常见陷阱，显著提高工作效率，并在遇到问题时能够快速定位和解决。

avatar
文章
阅读
粉丝