事件复盘：通过 SSH 从 Windows 服务器 clone 本地仓库失败（"does not appear to be a git repository"）并修复

日期：2026-01-02 — 2026-01-03
环境概述：Windows Server（OpenSSH for Windows），Git for Windows，仓库位于 D:\McServer...\plugins。通过 SSH（非标准端口 8307）从远端 clone 时出现 does not appear to be a git repository。本地可通过 VSCode Remote SSH 在服务器上直接使用该仓库（说明仓库存在且可用），但使用 git clone 失败。

一、问题摘要（Summary）

• 表现：从本地主机通过 SSH clone 指向服务器上已有工作树时报错：

  fatal: '/D:/.../plugins' does not appear to be a git repository
  

• 已确认：服务器上该目录是有效的 Git 仓库（git rev-parse --is-inside-work-tree 返回 true，.git 目录存在），且 git --version 在非交互 SSH 也能执行。
• 最终解决：在服务器上放置并启用一个 git-upload-pack wrapper（修正客户端传入参数），从而让 git clone 正常工作。也提供了变更 DefaultShell（将 OpenSSH 非交互 shell 改为 PowerShell）和建立裸仓库两种可选方案。

二、根因分析（Root cause）

1. Git 客户端在通过 SSH 向服务器请求时，会在远端执行类似：

   git-upload-pack '/D:/path/to/repo'
   

   注意：git 客户端在构造远端命令时为路径加了单引号和在 Windows 驱动器路径前出现了前导斜杠（/D:/... 或 'D:/...'），这在 Linux shell 下是正常的，但在 Windows 默认 shell（cmd.exe）下参数解析与 nix 不同。
2. 在 Windows 的默认远端 shell（早期行为通常是 cmd）里，单引号不被当作字符串分隔符，且命令参数解析会导致传给 git-upload-pack 的字符串不被识别为有效目录（例如前导斜杠或额外的引号导致 Git 找不到路径）。
3. 导致结果：git-upload-pack 收到不正确/额外参数，返回 usage 并退出；因此 git clone 失败。
4. 另外，where git 在非交互 SSH 会话中可能会“卡”或延迟，原因通常是 PATH 中存在不可达或慢响应的条目（网络路径等）；但本事件的主因并非 git 二进制不可用（已通过 git --version 验证）。

三、关键诊断步骤（Timeline & Commands）

（这些步骤也是复盘中实际运行过的命令 —— 可直接复用做验证）

1. 本地用非交互 SSH 验证远端能运行 git：

ssh -p 8307 Administrator@mc.5201314.vin "git --version"

2. 在服务器仓库目录确认工作树：

cd /d "D:\McServer\...path...\plugins"
dir ".git" /a
git rev-parse --is-inside-work-tree
git rev-parse --show-toplevel
git status

3. 在本地测试远端引用（最先简单读 refs）：

ssh -p 8307 Administrator@mc.5201314.vin 'git ls-remote "D:/McServer/.../plugins"'

4. 观察 git clone 失败时 ssh 发送的远端命令（启用 SSH 调试）：

$env:GIT_SSH_COMMAND = 'ssh -vvv -p 8307'
git clone "ssh://Administrator@mc.5201314.vin/D:/.../plugins" plugins-debug

• 从 ssh -vvv 日志可以看到服务端实际执行的命令（如 git-upload-pack '/D:/...'）。

5. 为诊断创建了可记录接收参数的 wrapper（写到 C:\Windows\System32\OpenSSH\git-upload-pack.cmd），并触发远端 git-upload-pack 来记录 wrapper 收到的 FULL ARGS、ARG1 RAW 等信息，从而确认传参格式。

诊断 wrapper（写入服务器）示例（最终用来观察的内容）记录日志到 C:\Temp\git-upload-pack-args.log：

• 输出示例（日志中实际显示）：

  FULL ARGS: D:/McServer/.../plugins
  ARG1 RAW: D:/McServer/.../plugins
  ARG1 TILDE: D:/McServer/.../plugins
  QUOTED ARGS: "D:/McServer/.../plugins"
  NORMALIZED FIRST: D:/McServer/.../plugins
  CALL: "C:\Program Files\Git\cmd\git.exe" upload-pack "D:/McServer/.../plugins" D:/McServer/.../plugins
  

  日志显示 wrapper 被调用，但原 wrapper 将 %*（全部参数）也传给 git，导致 git upload-pack 接收重复或多余参数并打印 usage。

四、采取的修复措施（What we changed）

两条思路都做了考虑（根本与临时）：

A. 最终短期/快速修复（已部署并验证成功）

• 在服务器上放置一个修正版的 git-upload-pack.cmd（位于 C:\Windows\System32\OpenSSH\），该脚本：
  • 从 %~1 读取第一个参数；
  • 去掉可能的单引号和前导 /（例如把 /D:... -> D:... 或把 'D:...' -> D:...）；
  • 仅以单个规范化后的路径作为参数调用 git.exe upload-pack "%FIRST%"（不要再传 %*）。
• 目的：确保无论客户端如何 quoting，最终传给 git-upload-pack 的都是一个正确的 Windows 路径参数。

修复脚本（在服务器以管理员 PowerShell 写入）：

$wrapperPath = 'C:\Windows\System32\OpenSSH\git-upload-pack.cmd'
$script = @'
@echo off
if "%~1"=="" (
  "C:\Program Files\Git\cmd\git.exe" upload-pack
  exit /b %ERRORLEVEL%
)
set FIRST=%~1
if "%FIRST:~0,1%"=="'" set FIRST=%FIRST:~1%
if "%FIRST:~-1%"=="'" set FIRST=%FIRST:~0,-1%
if "%FIRST:~0,1%"=="/" set FIRST=%FIRST:~1%
"C:\Program Files\Git\cmd\git.exe" upload-pack "%FIRST%"
exit /b %ERRORLEVEL%
'@
Set-Content -Path $wrapperPath -Value $script -Encoding ASCII -Force
icacls $wrapperPath /grant 'Administrators:RX'

B. 根本/长期建议（可选）

• 将 OpenSSH 的默认 shell 改为 PowerShell（通过注册表），因为 PowerShell 会正确解析单引号等，避免已有 quoting 的兼容性问题：

New-Item -Path 'HKLM:\SOFTWARE\OpenSSH' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\OpenSSH' -Name DefaultShell -Value 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'
Restart-Service sshd

• 或者：在服务器上创建并维护一个裸仓库作为远端（plugins.git），客户端直接 clone 裸仓库可避免工作树路径解析差异：

mkdir D:\gitrepos
git clone --bare "D:\McServer\...plugins" "D:\gitrepos\plugins.git"
# 本地 clone:
git clone "ssh://Administrator@mc.5201314.vin:8307/D:/gitrepos/plugins.git" plugins-local

C. 权限/路径检查（用于排除权限问题）

• 确认 SSH 登录用户对仓库目录和 wrapper 有读取/执行权限：

icacls "D:\McServer\...plugins"
icacls "C:\Windows\System32\OpenSSH\git-upload-pack.cmd"

五、验证（How we verified）

• 使用诊断 wrapper 记录并查看了传入参数，确认输入被正确规范化且 wrapper 只将单个路径参数传给 git。
• 本地使用 scp 风格路径并设置临时 GIT_SSH_COMMAND 成功 clone：

$env:GIT_SSH_COMMAND = 'ssh -p 8307'
git clone "Administrator@mc.5201314.vin:D:/McServer/.../plugins" plugins-local
Remove-Item Env:GIT_SSH_COMMAND

• 也通过直接触发远端 git-upload-pack 来确认 wrapper 返回了协议数据（非错误文本）。

六、归纳的排查/自助修复流程（可复用步骤）

当再次遇到类似问题，可按下列顺序排查：

1. 基本确认（服务器端）

   • 在仓库目录执行：

     git rev-parse --is-inside-work-tree
     git status
     dir .git /a

   • 在服务器交互 shell（或 VSCode Remote）能正常运行说明仓库存在。

2. 验证非交互环境能否运行 git

   • 本地：

     ssh -p <port> user@host "git --version"
     ssh -p <port> user@host 'powershell -NoProfile -Command "(Get-Command git).Source"'

   • 若 git --version 报错或找不到 git：检查系统 PATH（机器层 vs 用户层），并重启 sshd 服务（或把 Git 路径写入机器 PATH 并重启 sshd）。

3. 测试远端引用（轻量）

   • 本地运行：

     ssh -p <port> user@host 'git ls-remote "D:/path/to/repo"'

   • 若可列出 refs，说明 git-upload-pack 在远端能工作（可以进一步 debug clone 阶段的 quoting/参数问题）。

4. 打开详细日志进行定位

   • 在本地设置详细 ssh/git trace：

     $env:GIT_SSH_COMMAND='ssh -vvv -p <port>'
     $env:GIT_TRACE=1
     $env:GIT_TRACE_PACKET=1
     git clone "ssh://user@host/D:/path/to/repo" repo-debug

   • 查看 ssh 日志中 “Sending command:” 行，确定远端运行的 git-upload-pack 的参数格式（是否带前导斜杠或单引号）。

5. 如果参数有问题（如 /D:/... 或带单引号），优先考虑：

   • 临时修复：在服务器上放 git-upload-pack wrapper（如本文所示）以规范化参数；
   • 长期修复：把 DefaultShell 改为 PowerShell（写入注册表并重启 sshd）；
   • 或者创建裸仓库，客户端直接 clone 裸仓库。

6. 权限检查

   • 若出现 Permission denied (publickey) 或 NTFS 访问错误，使用 icacls 检查权限并修复。

7. 回滚/恢复

   • 在替换 wrapper 前备份原文件（例如 .bak），若新 wrapper 有问题，可恢复备份。

七、最终建议（Best practices）

• 在 Windows/OpenSSH 环境上若长期对外提供 Git 服务，优先：
  • 使用裸仓库作为远端（plugins.git），这是服务端最稳妥的做法；
  • 或确保 OpenSSH 的默认 shell 为 PowerShell（通过注册表设置 DefaultShell），因为 PowerShell 对 quoting 的行为更接近 nix 的期望；
  • 对于临时/过渡方案，可使用 wrapper 修正 quoting；但 wrapper 应只传递必要的参数（避免 %* 直接透传）。
• 在服务器 PATH 中避免不可达或网络路径，以免 where 或其它命令在非交互 SSH 中阻塞。
• 日志与诊断：在排查网络/ssh/git 问题时同时开启：
  • 本地 ssh -vvv；
  • Git 的 GIT_TRACE 和 GIT_TRACE_PACKET；
  • 在服务端启用 OpenSSH 的 DEBUG 日志（sshd_config 的 LogLevel 设置为 DEBUG3 已被开启）。

八、附录：关键命令/脚本（已实际使用）

• 创建修正 wrapper（服务器，管理员 PowerShell）：

$wrapperPath = 'C:\Windows\System32\OpenSSH\git-upload-pack.cmd'
$script = @'
@echo off
if "%~1"=="" (
  "C:\Program Files\Git\cmd\git.exe" upload-pack
  exit /b %ERRORLEVEL%
)
set FIRST=%~1
if "%FIRST:~0,1%"=="'" set FIRST=%FIRST:~1%
if "%FIRST:~-1%"=="'" set FIRST=%FIRST:~0,-1%
if "%FIRST:~0,1%"=="/" set FIRST=%FIRST:~1%
"C:\Program Files\Git\cmd\git.exe" upload-pack "%FIRST%"
exit /b %ERRORLEVEL%
'@
Set-Content -Path $wrapperPath -Value $script -Encoding ASCII -Force
icacls $wrapperPath /grant 'Administrators:RX'

• 诊断 wrapper（用于记录 wrapper 参数）示例（写入 C:\Temp\git-upload-pack-args.log，用于调试）——已在排查阶段使用过（参见上文日志）。

• 将 OpenSSH DefaultShell 改为 PowerShell（如果决定长期更改）：

New-Item -Path 'HKLM:\SOFTWARE\OpenSSH' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\OpenSSH' -Name DefaultShell -Value 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'
Restart-Service sshd

• 在本地用 scp 风格 clone（避免 ssh:// 引起的前导斜杠问题）：

$env:GIT_SSH_COMMAND = 'ssh -p 8307'
git clone "Administrator@mc.5201314.vin:D:/McServer/.../plugins" plugins-local
Remove-Item Env:GIT_SSH_COMMAND

• 创建裸仓库（备用）：

mkdir D:\gitrepos
git clone --bare "D:\McServer\...plugins" "D:\gitrepos\plugins.git"
# 然后本地：
git clone "ssh://Administrator@mc.5201314.vin:8307/D:/gitrepos/plugins.git" plugins-local

九、结论

• 本次故障的本质是 Windows 下 SSH 非交互命令参数与 Unix 风格 quoting 的不一致，导致 git-upload-pack 参数被误解析，从而 git clone 失败。
• 已采用安全低风险的修正（在 OpenSSH PATH 目录下放一个规范化 wrapper）并验证成功；长期方案为将 OpenSSH 的默认 shell 改为 PowerShell 或使用裸仓库方式。
• 已留有可回滚的备份（wrapper .bak），并记录了诊断日志文件位置（C:\Temp\git-upload-pack-args.log）供日后参考。

如果你愿意，我可以：

• 把本次事件的关键文件（最终 wrapper 脚本、诊断脚本）整理成一个可复用的脚本包并提供安装/回滚脚本；或
• 将以上内容存为项目的运维文档并提交到仓库（需要提供目标 repo）；或
• 针对你的生产服务器环境，给出一个安全审批清单（更改 DefaultShell、重启 sshd、创建裸仓库、设置备份/权限、上线验证步骤）。

你希望我接着做哪项（脚本包 / 存档到 repo / 审批清单 / 其他）？