ChatGPTClaudeGrok / X / CursorGemini

dsh 启动失败先查哪一层:命令层、环境层、端口层与插件层的固定排查顺序,别急着重装碰运气

故障排查发布于 2026-11-02作者: DeepSeek Plugin 插件市场
dsh 启动启动失败故障排查决策树DeepSeek Harness
只看到一句「起不来」时,按命令层、环境层、端口层、插件层依次判断。每层给出检查动作、判断标准与该跳到哪一步,避免反复重装碰运气。

dsh 启动失败时不要从「重装」开始,而要从最外层往里查:命令层 → 环境层 → 端口层 → 插件层。 这四层有明确的依赖关系,外层没通过时,查内层得到的结论都是假的。

dsh 启动层一:命令层与固定顺序

「起不来」是一个结果,不是一个原因,四层里任何一层出问题都会表现成同一句话。 没有固定顺序时,人会同时改 Node、改端口、删插件,最后即使能启动,也不知道是哪一步修好的,下次照样复发。

固定顺序的价值在于:每一层都只回答一个是非问题,答完立刻决定往哪走。下面每一层都给出检查动作、判断标准和出口。

顺序排好之后,第一层就是命令层。

命令层只回答一个问题:终端调用的 dsh 到底是哪一个文件、能不能执行。 检查动作:

  1. 执行 which -a dsh,看是否出现多条路径;
  2. 执行 dsh --version,看是正常输出版本还是报错;
  3. 执行 type dsh,确认没有被 shell 别名或函数劫持;
  4. 若用 npx,改用 npx @deepseek-ai/dsh --version 单独验证。

判断标准:路径唯一、版本能打印、别名不指向别的东西。 三条都满足才算通过。

出口:which 无输出说明根本没装或 PATH 不含安装目录;输出了但报权限错误说明文件不可执行;type 显示别名说明有人改过 shell 配置。 这三种都属于命令层,处理完再回到本层复测。

dsh 启动层二:环境层

环境层回答的是:命令找到了,但它依赖的运行时和网络条件是否满足。 检查动作:

  1. node -v,确认版本落在官方文档要求的区间内;
  2. npm -v 与 npx -v,确认两者都不是被裁剪过的极端版本;
  3. 执行 npm ping 或访问一次 registry,确认网络与证书正常;
  4. 检查 echo $DSH_HOME,确认数据目录可写;
  5. 若用代理,确认 HTTP_PROXY、HTTPS_PROXY 与实际网络一致。

判断标准:Node 版本合规、registry 可达、DSH_HOME 目录可写。 三条缺一条都会在启动阶段报错,只是报错文本不同。

出口:版本过低就去升级 Node;registry 不可达就处理代理或镜像;目录不可写就改权限或换 DSH_HOME。 环境层的问题往往伴随下载或写入类报错,看到这两类关键词可以直接跳到本层。

dsh 启动层三:端口层

端口层回答的是:服务有没有在预期地址上真正监听。 检查动作:

  1. 执行 lsof -i :3080,看是否已有进程占用;
  2. 启动时留意日志里的监听地址,默认是 127.0.0.1:3080;
  3. 用 curl -I http://127.0.0.1:3080 确认有响应而不是连接被拒;
  4. 若改过 --host,确认监听范围与访问来源匹配;
  5. 检查本机防火墙或安全软件是否拦截本地端口。

判断标准:只有一个进程监听、curl 有响应、监听地址与你要访问的地址一致。 注意「页面打不开」和「端口不通」不是一回事,前者可能已经是第四层。

出口:被占用就换端口或结束旧进程;curl 通但浏览器不通,先排除浏览器代理;监听在 127.0.0.1 却从别的机器访问,属于监听范围问题。 端口层的处理原则是只改一处再复测,不要同时改端口和 host。

dsh 启动层四:插件层

插件层回答的是:服务能起来,但 profile 组装是否成功。 检查动作:

  1. 看启动日志最后 30 行,找第一条错误而不是最后一条;
  2. 记录当前 profile 下已安装的插件列表;
  3. 禁用或卸载最近新增的插件,重启复测;
  4. 仍失败时用二分法只恢复一半,逐步收窄;
  5. 检查 profile 目录是否存在半装残留。

判断标准:最小插件集下能完整启动,说明问题在插件层而非内核。

出口:定位到具体插件后,先看它的版本是否与当前 dsh 版本匹配,再看是否装进了启动时使用的那个 profile。 插件报错的形态很多,但「装错 profile」和「版本不兼容」占大头。

四层走完,再并排对照一遍,顺序就不容易记混。

把四层并排看,才能看出该先做哪一步。 对照如下:

层只回答一个问题关键命令通过标志
命令层调用的 dsh 是哪一个which -a dsh路径唯一且能打印版本
环境层运行时与网络是否够用node -v、npm ping版本合规、registry 可达
端口层服务是否在监听lsof -i :3080有响应且只有一条监听
插件层profile 是否组装成功查看插件列表与日志最小插件集可启动

顺序不能乱的原因:外层失败时,内层的所有现象都不可信。 比如 PATH 指向旧版本,你在插件层怎么调都不会对。

dsh 启动误判与重装时机

误判比不查更浪费时间,因为它会让你在错误的层反复操作。 常见误判:

  1. 把「命令找不到」当成没装,实际是 PATH 没刷新;
  2. 把「下载失败」当成网络问题,实际是证书过期;
  3. 把「页面空白」当成端口问题,实际是前端资源没加载;
  4. 把「插件报错」当成内核坏了,实际只是装错 profile;把「重启后失效」当成偶发,实际是旧进程没退干净。

每一条误判都对应一个更省事的检查动作。 遇到现象先问「它属于哪一层」,而不是先动手。

误判排除之后,才轮到重装这个兜底动作。

重装是最后一层的兜底,不是第一反应。 满足下面任一条再考虑:

  1. 命令层确认已安装,但可执行文件损坏、重新安装能稳定复现修复;
  2. 环境层全部通过,仍然在初始化阶段崩溃且日志无可读错误;
  3. 插件层已排除到最小集仍失败,且 profile 目录无法修复;
  4. 迁移过 DSH_HOME,怀疑数据目录结构已损坏。

重装前先备份 DSH_HOME。 配置、会话与凭据都在里面,删掉再装等于从零开始。

dsh 下一步

先按四层走一遍,再决定要不要动配置。 想看单条命令报错怎么读,读 dsh 启动命令报错;想看整体启动失败的常见原因,读 dsh 启动失败;想看端口冲突的具体处理,读 修复 dsh 端口冲突;想主动配置监听地址与端口,读 dsh 启动参数与环境变量。

来源:DeepSeek Harness 官方文档、dsh CLI README、deepseek-harness 仓库

ChatGPTClaudeGrok / X / CursorGemini

常见问题

dsh 启动失败时,为什么建议先查命令层而不是立刻重装一遍?

dsh 启动失败先查命令层,是因为命令层是唯一能解释「命令本身有没有被正确执行」的一层。重装会覆盖证据,而命令层只需要 which dsh 和 dsh --version 两条命令就能判断,成本最低。

端口层检查已经通过、页面也能打开,还需要继续往下查插件层吗?

端口层通过、dsh 页面也能打开时,还要看现象决定是否继续查插件层。页面能开但界面空白或功能缺失,问题已经不在端口,而在插件层或数据目录。端口层通过只代表服务在监听,不代表 profile 组装成功。

dsh 四层都查过还是起不来时,向他人求助前应该保留哪些关键信息?

先保留启动日志最后 30 行、dsh --version 输出、DSH_HOME 路径与目录树、以及 3080 的监听状态。这四样能覆盖绝大多数判断,比截图整屏日志有效。

把插件全部禁用后 dsh 能启动,能说明是哪个插件的问题吗?

只能说明问题在插件层,还不能定位到具体插件。用二分法恢复一半插件复测,几轮就能收窄到单个包,再去看它的版本与 profile 是否匹配。

相关术语

决策树
决策树是按固定顺序逐层判断的排查路径,每一层只回答一个问题,答完就决定下一步,避免同时怀疑所有组件。— DeepSeek Harness 官方文档
命令层
命令层是排查的第一层,用来确认 shell 找到的 `dsh` 是不是你以为的那个可执行文件。— dsh CLI README
profile
profile 是 DeepSeek Harness 的具名组装环境,web、headless、desktop 各自维护独立依赖,插件装错 profile 就不会随启动加载。— dsh CLI README
DSH_HOME
DSH_HOME 是 DeepSeek Harness 的数据根目录,默认 ~/.dsh,保存配置、会话、插件与凭据。— DeepSeek Harness 官方文档

来源