dsh 启动失败先查哪一层:命令层、环境层、端口层与插件层的固定排查顺序,别急着重装碰运气
dsh 启动失败时不要从「重装」开始,而要从最外层往里查:命令层 → 环境层 → 端口层 → 插件层。 这四层有明确的依赖关系,外层没通过时,查内层得到的结论都是假的。
dsh 启动层一:命令层与固定顺序
「起不来」是一个结果,不是一个原因,四层里任何一层出问题都会表现成同一句话。 没有固定顺序时,人会同时改 Node、改端口、删插件,最后即使能启动,也不知道是哪一步修好的,下次照样复发。
固定顺序的价值在于:每一层都只回答一个是非问题,答完立刻决定往哪走。下面每一层都给出检查动作、判断标准和出口。
顺序排好之后,第一层就是命令层。
命令层只回答一个问题:终端调用的 dsh 到底是哪一个文件、能不能执行。 检查动作:
- 执行
which -a dsh,看是否出现多条路径; - 执行
dsh --version,看是正常输出版本还是报错; - 执行
type dsh,确认没有被 shell 别名或函数劫持; - 若用
npx,改用npx @deepseek-ai/dsh --version单独验证。
判断标准:路径唯一、版本能打印、别名不指向别的东西。 三条都满足才算通过。
出口:which 无输出说明根本没装或 PATH 不含安装目录;输出了但报权限错误说明文件不可执行;type 显示别名说明有人改过 shell 配置。 这三种都属于命令层,处理完再回到本层复测。
dsh 启动层二:环境层
环境层回答的是:命令找到了,但它依赖的运行时和网络条件是否满足。 检查动作:
node -v,确认版本落在官方文档要求的区间内;npm -v与npx -v,确认两者都不是被裁剪过的极端版本;- 执行
npm ping或访问一次 registry,确认网络与证书正常; - 检查
echo $DSH_HOME,确认数据目录可写; - 若用代理,确认
HTTP_PROXY、HTTPS_PROXY与实际网络一致。
判断标准:Node 版本合规、registry 可达、DSH_HOME 目录可写。 三条缺一条都会在启动阶段报错,只是报错文本不同。
出口:版本过低就去升级 Node;registry 不可达就处理代理或镜像;目录不可写就改权限或换 DSH_HOME。 环境层的问题往往伴随下载或写入类报错,看到这两类关键词可以直接跳到本层。
dsh 启动层三:端口层
端口层回答的是:服务有没有在预期地址上真正监听。 检查动作:
- 执行
lsof -i :3080,看是否已有进程占用; - 启动时留意日志里的监听地址,默认是
127.0.0.1:3080; - 用
curl -I http://127.0.0.1:3080确认有响应而不是连接被拒; - 若改过
--host,确认监听范围与访问来源匹配; - 检查本机防火墙或安全软件是否拦截本地端口。
判断标准:只有一个进程监听、curl 有响应、监听地址与你要访问的地址一致。 注意「页面打不开」和「端口不通」不是一回事,前者可能已经是第四层。
出口:被占用就换端口或结束旧进程;curl 通但浏览器不通,先排除浏览器代理;监听在 127.0.0.1 却从别的机器访问,属于监听范围问题。 端口层的处理原则是只改一处再复测,不要同时改端口和 host。
dsh 启动层四:插件层
插件层回答的是:服务能起来,但 profile 组装是否成功。 检查动作:
- 看启动日志最后 30 行,找第一条错误而不是最后一条;
- 记录当前 profile 下已安装的插件列表;
- 禁用或卸载最近新增的插件,重启复测;
- 仍失败时用二分法只恢复一半,逐步收窄;
- 检查 profile 目录是否存在半装残留。
判断标准:最小插件集下能完整启动,说明问题在插件层而非内核。
出口:定位到具体插件后,先看它的版本是否与当前 dsh 版本匹配,再看是否装进了启动时使用的那个 profile。 插件报错的形态很多,但「装错 profile」和「版本不兼容」占大头。
四层走完,再并排对照一遍,顺序就不容易记混。
把四层并排看,才能看出该先做哪一步。 对照如下:
| 层 | 只回答一个问题 | 关键命令 | 通过标志 |
|---|---|---|---|
| 命令层 | 调用的 dsh 是哪一个 | which -a dsh | 路径唯一且能打印版本 |
| 环境层 | 运行时与网络是否够用 | node -v、npm ping | 版本合规、registry 可达 |
| 端口层 | 服务是否在监听 | lsof -i :3080 | 有响应且只有一条监听 |
| 插件层 | profile 是否组装成功 | 查看插件列表与日志 | 最小插件集可启动 |
顺序不能乱的原因:外层失败时,内层的所有现象都不可信。 比如 PATH 指向旧版本,你在插件层怎么调都不会对。
dsh 启动误判与重装时机
误判比不查更浪费时间,因为它会让你在错误的层反复操作。 常见误判:
- 把「命令找不到」当成没装,实际是 PATH 没刷新;
- 把「下载失败」当成网络问题,实际是证书过期;
- 把「页面空白」当成端口问题,实际是前端资源没加载;
- 把「插件报错」当成内核坏了,实际只是装错 profile;把「重启后失效」当成偶发,实际是旧进程没退干净。
每一条误判都对应一个更省事的检查动作。 遇到现象先问「它属于哪一层」,而不是先动手。
误判排除之后,才轮到重装这个兜底动作。
重装是最后一层的兜底,不是第一反应。 满足下面任一条再考虑:
- 命令层确认已安装,但可执行文件损坏、重新安装能稳定复现修复;
- 环境层全部通过,仍然在初始化阶段崩溃且日志无可读错误;
- 插件层已排除到最小集仍失败,且 profile 目录无法修复;
- 迁移过 DSH_HOME,怀疑数据目录结构已损坏。
重装前先备份 DSH_HOME。 配置、会话与凭据都在里面,删掉再装等于从零开始。
dsh 下一步
先按四层走一遍,再决定要不要动配置。 想看单条命令报错怎么读,读 dsh 启动命令报错;想看整体启动失败的常见原因,读 dsh 启动失败;想看端口冲突的具体处理,读 修复 dsh 端口冲突;想主动配置监听地址与端口,读 dsh 启动参数与环境变量。
常见问题
dsh 启动失败先查命令层,是因为命令层是唯一能解释「命令本身有没有被正确执行」的一层。重装会覆盖证据,而命令层只需要 which dsh 和 dsh --version 两条命令就能判断,成本最低。
端口层通过、dsh 页面也能打开时,还要看现象决定是否继续查插件层。页面能开但界面空白或功能缺失,问题已经不在端口,而在插件层或数据目录。端口层通过只代表服务在监听,不代表 profile 组装成功。
先保留启动日志最后 30 行、dsh --version 输出、DSH_HOME 路径与目录树、以及 3080 的监听状态。这四样能覆盖绝大多数判断,比截图整屏日志有效。
只能说明问题在插件层,还不能定位到具体插件。用二分法恢复一半插件复测,几轮就能收窄到单个包,再去看它的版本与 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 官方文档
来源
- DeepSeek Harness 官方文档· deepseek-harness
- dsh CLI README· deepseek-ai
- deepseek-harness 仓库· deepseek-ai