DSH插件安装失败排障：从git缺失到网络线路故障

开头

上周三下午，团队里一位同学在群里甩了一张截图：DSH 插件安装失败，终端里只有一行红字和一堆看不懂的堆栈。他先后试了重装、重启、换版本，从下午两点折腾到快五点，最后把希望寄托在“是不是网络问题”这个万能结论上。我接手之后，从确认 git 是否安装开始，一路查到真正的网络线路故障，前后花了不到四十分钟。这次排障过程里踩过的判断误区非常典型——先是把依赖缺失当成网络问题，后来又差点把线路抖动误判成服务端故障。

DSH 是我日常在用的一个插件化工作台，它本身不带业务功能，全部能力靠插件扩展，插件由官方仓库统一分发，安装时由内部的分发客户端去拉取源码包和制品包。所以“DSH 插件安装失败”这句话背后，其实横跨了三层东西：本地基础工具链、客户端缓存与版本约束、到仓库的网络链路。任何一层出问题，用户看到的报错都可能长得很像。这篇复盘就是按照我实际的排查顺序写下来的，从“git 未安装”这一层开始，逐层往外，直到定位到网络线路本身。适合正在被同类问题卡住的同学，也适合想把自己排障流程梳理得更顺手的人——文中所有命令都可以直接复制执行，域名和路径我做了脱敏处理。

1. 先把现场还原：这次插件安装失败到底卡在哪

1.1 环境与前置条件速览

排障最忌讳一上手就乱试命令。我做的第一件事是把环境信息拉齐，因为同一个报错在不同环境下的成因可能完全相反。这次出问题的机器是一台开发用的笔记本，系统是最新的长期支持版本，客户端版本比较新，插件是通过命令行方式安装的。

这张表看起来平平无奇，但第三行和第五行放在一起，问题就已经露头了：DSH 的插件生态里有相当一部分插件是以源码形式分发的，客户端在安装这类插件时的第一步就是调用版本控制工具去克隆仓库。机器上根本没有装这个东西，克隆动作必然失败，而这个失败被客户端的错误处理包装之后，呈现在用户面前的就变成了含糊的“安装失败”。

提示：碰到任何安装类问题，先把“环境清单”写出来，哪怕只是记在便签里。清单不需要多专业，但必须包含系统版本、客户端版本、运行时版本、网络出口、是否配过自定义源这五项。后面每排除一项，就在清单上划掉一项，能极大减少重复劳动。

我见过太多人跳过这一步，直接去搜报错文本，搜到一堆似是而非的方案，一个个试过去，把环境越搞越乱。清单法的价值不在于它多聪明，而在于它把“未知”变成了“有限的待验证项”。

1.2 报错信息的第一手记录

原始报错只有三行，我让他重新跑了一次，并把日志级别调到最详细，才拿到完整信息。脱敏后的关键片段是这样的：

$ dsh plugin install sample-plugin-x [INFO] resolving plugin manifest ... [INFO] manifest ok, source type: git [INFO] cloning source from https://git.dsh.example/sample-plugin-x.git [ERROR] failed to spawn git: No such file or directory [ERROR] plugin install aborted (code 128) [WARN] fallback to binary package: not available

注意倒数第三行，failed to spawn git，这句话已经把病因说得非常清楚了：客户端想启动一个名为 git 的子进程，系统找不到这个可执行文件。后面的code 128是版本控制工具自己定义的一类通用错误码，但在这里它其实根本没跑到版本控制工具内部就被拦下了。

这行日志的坑在于，它出现在一堆[INFO]后面，很多人会下意识认为前面都成功了，问题在后面。实际上[INFO]只表示流程走到了那一步，并不代表那一步真的成功。这是绝大多数分发客户端日志的通病：日志记录的是“意图”而不是“结果”。

注意：看安装日志时，重点找第一个ERROR出现的位置，往上再看一行。真正的病因往往就在那往上的一行里，而不是ERROR那一行本身。

1.3 排障的整体思路：从最内层依赖往外层网络收敛

我把这次排查拆成了三层，顺序是固定的：先本地依赖，再本地环境与缓存，最后才动网络。这个顺序不是拍脑袋定的，而是基于成本收益：本地依赖检查一条命令、耗时几秒；本地环境清理一条命令、耗时几十秒；网络排查要抓包、要换线路、要多次对比，动辄半小时起。从便宜的动作做起，能用五秒钟解决的问题绝不要花半小时。

另一个考虑是可逆性。改本地依赖和清缓存都是可逆或者影响极小的操作，而改网络配置、改 hosts、动系统级设置属于“改了之后自己也容易忘”的操作，一旦动手，后续排查就会被自己的改动污染。我个人的原则是：除非已经确认是网络层问题，否则不碰任何网络相关的配置。

还有一层考虑是证据链。从内往外的排查天然形成一条证据链：每排除一层，就有一组明确的输出作为证据。等到最后定位到网络线路时，我手里已经有完整的证据说明“不是依赖问题、不是缓存问题、不是认证问题、只剩下链路本身”。这套证据在给团队做复盘、或者推动基础设施同事处理时特别有用，比“我试了很多次就是不行”有效一百倍。

2. 第一层排查：git 未安装导致的依赖拉取中断

2.1 为什么插件安装会依赖 git

很多人对“装个插件为什么要版本控制工具”感到困惑，觉得这是客户端设计得不合理。其实这是插件分发的一种常见权衡。插件以源码形式分发，好处是体积小、可按需构建、能精确对应到某个提交，坏处是客户端必须自己具备“把仓库拉下来”的能力，而这个能力标准做法就是调用版本控制工具。

对比一下两种分发形态就清楚了：

源码分发的失败面明显更宽，但它换取的是版本精确性和体积优势。DSH 的插件清单里，source type: git这个字段就是在告诉客户端“这个插件走源码路线”。如果清单里写的是source type: registry，那就不需要版本控制工具了。所以严格来说，这是一个“清单声明的分发方式”与“本机工具链缺失”之间的冲突，而不是客户端自身的缺陷。

顺带说一句，这类问题在团队里出现的频率远高于个人环境。原因是团队通常有统一的机器镜像，镜像里装了什么、没装什么，取决于当初做镜像的人觉得“开发机应该有什么”。版本控制工具属于那种“做镜像的人觉得人人都有、实际新人机器上经常没有”的典型漏网之鱼。

2.2 各系统下的确认与安装步骤

确认方式极简，一条命令：

git --version

如果输出类似git version 2.x.x，说明已装，可以跳过本节。如果报command not found或者不是内部或外部命令，那就是缺了。接着按系统装：

# Debian / Ubuntu 系 sudo apt-get update sudo apt-get install -y git # Fedora / RHEL 系 sudo dnf install -y git # macOS，用 Homebrew brew install git # Windows，用 winget winget install --id Git.Git -e --source winget

Windows 上还有一个隐藏问题：装完之后当前终端不会立刻生效，因为环境变量是在新进程中读取的。所以装完必须关掉终端重新开一个，否则git --version依然报找不到。这个细节每年都能坑到一批人。

装完不要只验证git --version，还要验证一下网络可达性和证书配置，因为克隆失败的原因常常藏在后面：

git --version git config --global --list git ls-remote https://git.dsh.example/sample-plugin-x.git

第三条命令只做“列举远端引用”，不下载任何内容，是最轻量的连通性验证。如果它能返回一串提交哈希，说明克隆链路本身是通的，问题不在版本控制工具。

提示：在无人值守或者 CI 场景里执行克隆，一定要加GIT_TERMINAL_PROMPT=0。不然一旦远端要求输入凭据，进程就会静默卡住，表现出来就是“安装一直没反应”，排查方向会被彻底带偏。

2.3 装完 git 之后仍失败的三种典型残留

我们装完版本控制工具，重新执行安装，报错变了：

[INFO] cloning source from https://git.dsh.example/sample-plugin-x.git [ERROR] RPC failed; curl 56 Recv failure: Connection reset by peer [ERROR] early EOF [ERROR] index-pack failed [ERROR] plugin install aborted

报错从“找不到程序”变成了“连接被重置”。这是一个非常关键的信号：问题已经从本地依赖层转移到了网络层。但在直接跳到网络排查之前，还有三种“残留问题”需要先排除，因为它们造成的现象和网络故障高度相似。

第一种是权限残留。如果之前有人用管理员权限跑过安装，缓存目录里会留下属于其他用户的文件，普通用户再跑就会在写入阶段失败，报错文本里常带EACCES或Permission denied。检查方法很简单，看缓存目录的所有者是不是当前用户。

第二种是半成品目录残留。克隆中断之后，客户端往往会在缓存里留下一个不完整的目录，下次安装时如果客户端没有做“失败即清理”，就会在一个残缺的基础上继续，报错五花八门。这类问题最典型的特征是：报错内容每次都不一样，或者同一个命令时好时坏。

第三种是全局配置残留。有人曾经为了“加速”改过全局的下载缓冲、超时、URL 替换规则，改完忘了。这些配置会在所有项目里生效，造成“明明换了新项目还是同样的错”。用git config --global --list和客户端自己的config list各看一遍，能发现不少历史遗留。

注意：排除残留的顺序建议是“先看权限，再清目录，最后查配置”。因为查配置最费眼，而权限问题一条ls -l就能看出来。

3. 第二层排查：本地环境与缓存污染

3.1 缓存目录结构与清理策略

分发客户端的缓存一般分三块：元数据缓存（清单、版本索引）、制品缓存（下载下来的包）、临时构建目录（源码克隆和编译的中间产物）。三块的生命周期不同，清理方式也不同。

清理前先搞清楚路径。多数客户端的缓存路径遵循系统惯例：

# Linux / macOS 常见位置 ~/.cache/dsh/ # 制品与临时目录 ~/.dsh/cache/ # 元数据 ~/.dsh/logs/ # 日志，清理前先备份 # Windows 常见位置 %LOCALAPPDATA%\dsh\cache\ %APPDATA%\dsh\logs\

清理的原则是“清缓存不清配置”。配置里可能有你的仓库地址、认证凭据、团队约定，清掉之后重配很麻烦；缓存删了只是下次重新下载，代价可控。所以我一般只删缓存目录，配置目录原样保留。

清理完之后立即重试一次，看报错有没有变化。如果报错完全一样，说明缓存不是主因，可以进入下一层；如果报错变了，那就是有进展，需要重新读日志。这个“清理后对比报错”的动作我通常会做两轮，第一轮清制品缓存，第二轮清临时构建目录，分开做，为的是能分辨到底是哪一块脏了。

3.2 运行时版本与权限的两类隐形坑

运行时版本不匹配是第二层里最容易被忽略的。插件清单里通常有engines之类的字段，声明它支持的运行时版本范围。版本低于下限时，客户端有时不会明确报“版本不满足”，而是在构建阶段崩溃，报一堆语法错误或者模块找不到。这类报错的迷惑性极强，因为错误信息指向的是插件代码，而不是你的运行时版本。

排查方法是对着插件清单看声明，再对比本机：

node -v # 或者 python --version，取决于插件运行时 dsh plugin info sample-plugin-x --show-engines

权限问题则更隐蔽。典型触发路径是：某次用管理员权限跑了一次安装，失败了，缓存目录里留下一批属于管理员的文件；之后用普通权限跑，客户端试图覆盖这些文件，被系统拒绝。表现出来就是“我什么都没改，昨天还好好的，今天突然不行了”。

排查权限的标准动作：

ls -ld ~/.cache/dsh ~/.dsh/cache # 所有者不是当前用户时，修正归属 sudo chown -R "$(id -u):$(id -g)" ~/.cache/dsh ~/.dsh/cache

这里有个经验：修权限比删目录更值得优先尝试。因为删目录会连带删掉已经下载好的包，重下又要花时间，而修权限是原地解决，代价最小。当然，如果目录结构已经乱了，那就直接删。

提示：日常养成习惯，安装插件一律不加管理员前缀。真需要提权的场景，客户端会明确告诉你，而不是让你靠猜。

3.3 用详细日志定位真正的失败行

到了这一步，普通的日志已经不够用了，必须开最详细的级别，让客户端把每一步的外部命令调用、返回码、标准错误全部吐出来。

# 通用做法：把日志级别调到最详细，并落盘 dsh plugin install sample-plugin-x --log-level verbose 2>&1 | tee install-verbose.log # 如果底层用的是 Node 生态的包管理器 npm install --loglevel=verbose # 如果底层用的是 Python 生态的包管理器 pip install -v <package>

拿到详细日志之后，不要从头读，用关键词定位：

grep -n -i -E "error|fail|timeout|reset|refused|denied" install-verbose.log | head -50

这一步的价值在于把“客户端包装过的友好错误”还原成“底层工具的原生错误”。同一件事，客户端说“安装失败”，底层说“连接被重置”，后者才是有信息量的。我这次就是在这个日志里看到了curl 56和early EOF，才把方向从本地彻底转向网络。

补充一句，日志里如果有时间戳，一定要留意每一步之间的间隔。间隔特别长的那一步，往往就是卡住的地方。比如“开始克隆”到“连接被重置”之间隔了三十秒，那大概率是握手成功但数据传输阶段被中断，这个特征后面会用到。

4. 第三层排查：网络线路问题的识别与验证

4.1 先判断是“线路”还是“服务端”

在动手测网络之前，必须先回答一个问题：是只有我这台机器不行，还是大家都一样？这个判断决定了后续所有工作的方向。如果服务端本身有故障，你在本地无论如何折腾都没用。

判断方法有三种，成本从低到高：

1. 问同事。最快，但样本少，容易误判。
2. 用另一台机器、另一条网络出口试同一个命令。有对比才有结论。
3. 如果有公开的状态页或者健康检查接口，直接请求它。

我这次的做法是：让那位同学用手机热点再试一次，结果成功了。这就基本锁定了“办公室这条线路有问题”，而不是服务端故障。但“基本锁定”不等于“确定”，因为换个出口同时也换了 DNS 解析结果、换了链路质量、换了可能的中间设备，变量太多。

所以我又做了第二组对照：在同一条办公网上，用另一台机器安装同一个插件，也失败；在同一条办公网上，访问仓库的健康检查接口，成功。这两条信息合起来看，问题就不是“整条线路断了”，而是“访问仓库这条链路在特定环节上有问题”。这个结论比单纯“换个网就好了”精确得多，也更有说服力。

注意：做对比实验时，一次只变一个变量。换网络的同时又换了客户端版本、又清了缓存，那结论就是不可信的。我这次严格保持客户端版本、插件版本、命令参数完全一致，只换网络出口。

4.2 分阶段验证：DNS、TCP、TLS、应用层

网络问题之所以难查，是因为“网络不通”这四个字太笼统。真正的网络链路要经过好几段：域名解析 → TCP 建连 → TLS 握手 → HTTP 传输。每一段都有独立的失败模式和独立的排查命令，必须分段测。

第一段：域名解析。

nslookup plugins.dsh.example # 或者 dig +short plugins.dsh.example

要看的不是“有没有结果”，而是“结果稳不稳定”。连续跑五次，看每次返回的地址是否一致。如果不同次解析到了不同网段的地址，而其中某些网段在你这条线路上质量很差，那就找到了一个可能的原因。我这次连续跑了五次，解析结果稳定，所以 DNS 不是主因。

第二段：TCP 建连。

curl -v --connect-timeout 5 https://plugins.dsh.example/health

重点看输出里的Connected to ...那一行和耗时。如果建连就慢或者直接超时，问题在更底层；如果建连很快，那说明链路通，问题在后面的数据传输。我这次建连只用了不到一百毫秒，说明 TCP 层没问题。

第三段：TLS 握手。

openssl s_client -connect plugins.dsh.example:443 -servername plugins.dsh.example -brief

这一段的典型失败是证书链不完整、证书过期、系统时间不对。如果握手报certificate verify failed，还要先检查本机时间：

date -u

系统时间偏差过大时，证书校验会失败，而报错看起来跟网络毫无关系。这个坑我踩过不止一次，尤其是长时间没重启的虚拟机。

第四段：应用层传输。

curl -o /dev/null -w "dns:%{time_namelookup} connect:%{time_connect} tls:%{time_appconnect} total:%{time_total} speed:%{speed_download}\n" \ https://plugins.dsh.example/health

这条命令能一次性把四段耗时打出来。我这次的输出里，前三段加起来不到两百毫秒，而total接近三十秒，speed_download极低。这就是典型的“能连上，但传不动”。

4.3 大包传输中断与长连接两类隐蔽故障

“能连上但传不动”这个现象，最常见的两个成因是链路质量差导致丢包重传和中间设备对大流量长连接做了限制。

先看丢包：

# Linux / macOS ping -c 20 plugins.dsh.example # 观察丢包率和延迟抖动

如果丢包率超过几个百分点，或者延迟忽高忽低，那么小请求（比如健康检查，几十字节）能秒回，大请求（克隆仓库，几十兆）就会反复重传直到超时。这完美解释了为什么健康检查成功、插件安装失败。我这次测下来丢包率接近两成，延迟抖动极大，基本吻合。

再看 MTU。很多办公网和家用网络的实际 MTU 小于标准值，导致大包被静默丢弃，表现出来就是“小文件能下、大文件卡死”。探测方法：

# Linux：不分片，逐步缩小包大小 ping -M do -s 1472 plugins.dsh.example ping -M do -s 1400 plugins.dsh.example # macOS ping -D -s 1472 plugins.dsh.example

1472 是 1500 减去 IP 头和 ICMP 头的值。如果 1472 不通而 1400 通，说明链路上有 MTU 限制。这种情况下，把客户端的传输方式调整为分块或者降低单次传输大小就能缓解。

还有一个更隐蔽的因素：中间设备对长连接的回收策略。克隆仓库是一个持续时间较长的连接，如果链路上有设备在固定时间（比如几十秒）后回收“空闲”连接，而克隆过程恰好有一段时间没有数据流动，连接就被掐断，报错就是本次看到的Connection reset by peer。

针对这两类问题，客户端和底层工具一般都有对应的调优参数：

# 让底层工具在低速时尽快报错，而不是无限等待 export GIT_HTTP_LOW_SPEED_LIMIT=1000 export GIT_HTTP_LOW_SPEED_TIME=30 # 增大缓冲区，缓解大包传输失败 git config --global http.postBuffer 524288000 # 客户端侧调整重试策略（示例，参数名以实际帮助为准） dsh config set fetch.retries 3 dsh config set fetch.timeout 120

提示：这些参数是“缓解”而不是“根治”。如果链路本身丢包严重，调参只能让它偶尔成功，稳定性依然很差。真正的根治办法是换一条链路，或者让负责网络的同事去查链路上的设备。

4.4 三条线路的对比实验与结论固化

为了把结论做扎实，我做了三组对比：办公网、手机热点、家用宽带，每条线路跑三次安装，记录结果。表格如下：

这张表说明两件事。第一，办公网的建连速度其实是最快的，但传输质量最差——这正是它最坑的地方，因为在前面几步测试里它表现得“最健康”，很容易把人误导到别的方向。第二，问题只出现在办公网这条链路上，与客户端版本、插件本身、仓库服务端都无关。

结论固化下来就是三句话：本地工具链缺失是首要诱因，修复后暴露了真实的链路质量问题；链路问题的特征是建连正常、传输极差；换链路可以立即恢复，但根因需要通过基础设施渠道反馈处理。

影响范围方面，这次故障不只影响一个人。同一个办公网段下的其他同事装同类插件时大概率也会失败，只是他们失败后通常归因为“插件坏了”而不是“网坏了”，所以没有人反馈。另外，如果团队的持续集成流水线跑在同一个网段，那么所有依赖源码克隆的构建任务都会间歇性失败，表现为“构建时好时坏”这种最难排查的形态。这就是为什么我在复盘里强调：不要把“换网能装”当成解决方案交付出去，那只是临时绕过，根因还在。

5. 常见问题速查表与固化下来的操作习惯

5.1 报错文本与成因对照

这张表是我把这次和以往几次类似问题整理出来的，按“日志里出现的关键词”索引，比按现象描述索引快得多。

用这张表的时候有个技巧：先匹配关键词再看成因，不要先看成因再去找关键词。因为人的主观预设会让我们只看到自己相信的证据，很容易在日志里“找到”一个其实并不存在的线索。

5.2 我固化下来的几条操作习惯

第一条，安装任何插件前先跑一次环境自检，把版本控制工具、运行时版本、客户端版本、网络出口四项打出来。这四条命令加起来不到十秒，但能省掉后面几十分钟的猜测。

第二条，所有安装命令都带日志落盘。我用的是2>&1 | tee这个组合，好处是屏幕上能实时看到进度，同时留一份完整文件。事后复盘、贴给同事看、对比两次失败差异，全靠这份文件。没有日志的排障基本等于蒙。

第三条，报错升级路径固定为：本地依赖 → 本地缓存权限 → 运行时版本 → 网络分段验证。这个顺序我从这次之后就没改过，因为它确实把平均定位时间压下来了。中途我从“缓存”跳到“网络”那次，事后证明是弯路——虽然缓存确实不是主因，但跳过去之后我又回头补做了权限检查，反而更慢。

第四条，永远保留一条“已知可用”的对照链路。手机热点是最方便的一条，它不只用来验证，还能在紧急情况下让你先把活干完。但要清楚这是绕过而非解决，绕完之后必须把证据整理好反馈出去，否则下一个人还得重走一遍。

第五条，也是我踩过最多次的：不要在排查过程中顺手升级任何东西。我有一次在排查安装失败时，觉得“顺便把客户端也升一下”，结果升完之后报错全变了，之前的证据链全废，等于重头再来。排查期间，环境必须是冻结的，所有变更都要单独记录、单独验证。

提示：如果你在团队里带人，可以把上面五条写成一张卡片贴在入职文档里。新人最常见的错误不是不会用命令，而是把排查当成试错，随机组合各种方案，最后把环境搞得一团糟还没有任何结论。

这套流程我用了大半年，期间又碰到过两次“装不上”的情况，一次是 Windows 上的终端没重开导致工具不生效，一次是缓存目录被管理员权限污染。两次都是按顺序走，几分钟就定位了。真正耗时的永远是那些跨层的、现象相似的复合故障，而对付复合故障唯一可靠的办法，就是把每一层单独验证干净，不要给自己留下“这里应该没问题吧”的模糊地带。