在windows平台上通过ssh-agent实现git凭证持久化

在 Windows 上实现持久的 Git SSH 认证：告别重复输入密码

引言

在日常开发中，使用 SSH 密钥对 Git 私有仓库进行认证是一种常见且安全的方式。然而，许多 Windows 用户都遇到过这样的困扰：每次打开新的终端窗口进行 Git 操作时，都需要重新输入 SSH 私钥的密码。这不仅打断了工作流，也降低了效率。

问题的根源在于，Git for Windows 自带的 SSH 套件其生命周期受限于单个命令行会话。一旦关闭窗口或启动新的独立 Git 命令进程，之前缓存的认证上下文便会丢失。

本文将介绍如何利用 Windows 10/11 自带的 OpenSSH 身份验证代理服务，实现一套系统级、持久化的 SSH 密钥管理方案，并完美支持多 Git 账号场景，让你彻底告别重复输入密码的烦恼。

关于多 Git 账号配置：本文聚焦于认证持久化，多账号 SSH 密钥的配置细节可参考笔者之前的文章《在 Windows 平台上如何做到 Git 多 SSH-Key 兼容》，其核心在于 ~/.ssh/config 文件的主机别名映射。

解决方案概览

传统的 Git for Windows SSH 代理是进程级的，而我们需要的是一套系统级服务。解决方案的核心在于启用并配置 Windows 内置的 OpenSSH Authentication Agent 服务，它将作为所有 SSH 认证请求的中央管理器，其生命周期与系统绑定，而非某个终端窗口。

详细步骤

第一步：准备 SSH 密钥对

如果你还没有密钥，可以使用以下命令生成。这里以更现代、更安全的 ED25519 算法为例：

# 为用户1生成密钥
ssh-keygen -t ed25519 -C "user1@example.com" -f ~/.ssh/id_ed25519_user1

# 为用户2生成密钥
ssh-keygen -t ed25519 -C "user2@example.com" -f ~/.ssh/id_ed25519_user2

生成时，系统会提示你为私钥设置一个密码（passphrase）。请务必牢记此密码，后续我们只需输入一次。

第二步：配置 SSH 客户端 (~/.ssh/config)

为了让系统区分不同的 Git 服务或账号，需要在 ~/.ssh/config 文件中进行主机别名配置。

# 用户 user1 的配置
Host github-user1
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_user1
    IdentitiesOnly yes
    # 注意：切勿设置 ‘IdentityAgent none’，否则将绕过代理服务

# 用户 user2 的配置
Host github-user2
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_user2
    IdentitiesOnly yes

关键说明：

• Host 是一个自定义的别名（如 github-user1），后续在克隆或设置远程仓库时需使用此别名。
• IdentityFile 指向对应的私钥。
• IdentitiesOnly yes 确保 SSH 只尝试指定的密钥，不试探其他默认密钥。
• 切勿添加 IdentityAgent none：此选项会强制 SSH 客户端忽略代理，直接读取磁盘上的私钥文件，从而导致每次都需要输入密码。

第三步：启用并配置 Windows OpenSSH 代理服务

这是实现持久化的核心步骤。我们将把 SSH 代理作为一个 Windows 服务来运行。

1. 通过服务管理器启用：

   • 按下 Win + R，输入 services.msc 并回车。
   • 在服务列表中找到 OpenSSH Authentication Agent。
   • 双击打开属性，将“启动类型”设置为 自动，然后点击“启动”按钮，最后点击“确定”。

2. 通过 PowerShell（管理员）配置：

   • 在开始菜单中搜索“PowerShell”，右键选择 “以管理员身份运行”。
   • 执行以下命令以确保服务已启用并自动启动：

     Set-Service -Name ssh-agent -StartupType Automatic
     Start-Service ssh-agent
     Get-Service ssh-agent | Select-Object Status, StartType
     

     确认输出中 Status 为 Running，StartType 为 Automatic。

第四步：将私钥添加到系统代理

服务启动后，我们需要将私钥“托管”给它。在刚才的管理员 PowerShell 中执行：

# 请注意使用 Windows 风格的绝对路径
ssh-add C:\Users\<你的用户名>\.ssh\id_ed25519_user1
ssh-add C:\Users\<你的用户名>\.ssh\id_ed25519_user2

执行每条命令后，输入一次该私钥的密码。只需输入这一次，之后系统重启也无需再次输入。

第五步：验证密钥加载状态

在普通 PowerShell 或 CMD 中运行以下命令验证：

ssh-add -l

如果成功，你将看到类似如下的输出，列出了已加载密钥的指纹：

256 SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx user1@example.com (ED25519)
256 SHA256:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy user2@example.com (ED25519)

第六步：强制 Git 使用系统 SSH 客户端（关键）

为确保 Git 命令（如 git pull, git push）使用我们刚刚配置好的系统代理，需要设置全局配置：

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

此命令告知 Git 使用 Windows 原生的 SSH 客户端，而非其自带的版本，从而能够连接到系统级的 ssh-agent 服务。

第七步：测试 SSH 连接

现在，使用你在 config 文件中配置的 Host 别名进行测试：

# 测试 user1 的配置
ssh -T git@github-user1

# 测试 user2 的配置
ssh -T git@github-user2

如果一切顺利，你将直接看到 GitHub 的成功认证欢迎信息（例如 Hi username! You‘ve successfully authenticated...），而不会出现密码输入提示。

第八步：使用与测试 Git 操作

1. 克隆仓库时，使用配置的 Host 别名：

   git clone git@github-user1:username/repo.git
   

2. 对于已有仓库，可修改远程地址以匹配别名：

   git remote set-url origin git@github-user1:username/repo.git
   

3. 之后执行任何 git fetch, git push 操作，都应实现无感知的自动认证。

故障排查

• ssh-add -l 显示 The agent has no identities：表示代理服务运行正常，但未加载密钥。请以管理员身份重新执行 第四步。
• 操作仍要求输入密码：
  1. 检查 ~/.ssh/config 中对应主机的 IdentityFile 路径是否正确。
  2. 确认仓库的远程地址（git remote -v）是否与 config 中定义的 Host 别名完全匹配。
  3. 运行 ssh -Tv git@<你的Host别名> 查看详细的调试信息，确认其尝试使用的密钥路径。
• SmartGit 等 GUI 工具仍需要密码：请在工具的设置中将 SSH 客户端选项改为 “System SSH” 或 “Native”，使其使用系统环境。

总结

通过将 SSH 认证委托给 Windows 自带的 OpenSSH Authentication Agent 服务，我们成功构建了一个系统级、持久化的 Git 认证管理方案。这套方案的核心优势在于：

1. 一劳永逸：私钥密码只需输入一次，即可在系统重启后持续有效。
2. 全局生效：无论是 CMD、PowerShell、Git 还是支持系统 SSH 的 GUI 工具（如 SmartGit），都能共享同一套认证状态。
3. 支持多账号：通过灵活的 ~/.ssh/config 配置，可以轻松管理多个 Git 服务平台的不同账号。

希望本文能帮助你彻底解决 Windows 下 Git 操作的密码输入困扰，让开发流程更加顺畅高效。

Git Bash兼容性处理

如果你同时使用 Git Bash（一个基于 Cygwin 的模拟环境），可能会发现其中的 ssh-add -l 命令无法连接到系统代理。这是因为 Git Bash 有自己的 PATH 环境优先级和可能的命令缓存。这个问题笔者尝试了多种方案，但尚未完全解决，待以后找到合适解法后再追更。