DSH Web UI 启动失败：从环境到端口逐项排查

DSH 启动失败时，先保存启动命令和第一条具体错误，再区分服务未启动、浏览器连接失败与任务执行失败。下面先按症状定位；版本专项说明保留各自范围，本站未运行这些 DSH 故障复现。

先保存完整错误原文

保存执行的命令、工作目录、第一条错误、最后一条错误、运行时版本和操作系统。截图适合保留界面，但可复制的错误文本更适合搜索和比较。

在公开求助前删除用户名、目录中的客户名称、Token、Cookie、内网地址和其他敏感信息。

先判断你属于哪一种情况

不要把“DSH 不能用”当成一个错误。先对照可观察症状，再进入精确页面：

如果症状不在表中，继续按下面的顺序保存证据和缩小范围，不要同时修改多个配置。

2026-08-31 复核了 0.1.2-alpha.2 的连接指示与恢复入口，基础启动命令仍按 0.1.1-rc.2 阅读。以下是官方固定来源的静态说明，没有把本站 Web 页面测试当成 DSH 本身的运行实测。

出现 web exited with code 1，先看哪条错误

web exited with code 1 表示进程以失败状态退出，仅凭这一行不能确定根因。先保存它之前的第一条具体错误、原始启动命令、DSH/Node 版本及 Profile，再对照上方症状表。

• 还未出现可访问地址：按安装与服务启动阶段检查；明确端口占用时进入端口排障。
• 日志出现 Full diagnostics：读取终端给出的实际路径；0.1.6-alpha.2 日志说明只覆盖该版本已核实的诊断实现，不给所有版本猜同一个目录。
• 进程仍在运行但浏览器打不开：核对实际地址与连接状态，见连接中断。
• 页面已打开、发送任务才失败：按错误进入模型与凭据；输入区不可用则进入工作区排障。

每次只修正一个已定位的问题，再验证服务与原失败能力。不要用重装、清空 Home 或结束全部 Node 进程代替定位。

安装卡住、ETARGET 与 pnpm 找不到：先确定失败阶段

2026-09-08 补充：先保存命令和第一条错误，按下表选择检查动作。终端还在下载 npm 包、Host 没启动、浏览器断线和模型任务失败，需要不同的证据。

只查询元数据，不先切镜像或清空缓存

以下命令不会安装 DSH。示例查询安装指南采用的固定版本；排查 ETARGET 时，应把第二条命令的包名和版本替换为错误中的实际值。

npm config get registry
npm view @deepseek-ai/[email protected] version
npm view @deepseek-ai/[email protected] version --registry=https://registry.npmjs.org/

第二条使用当前配置，第三条仅为这一次查询指定官方 registry，不修改全局配置。对比结果有助于定位 registry 差异，但不能凭一次失败断定镜像缺包，也不能凭主包存在断定全部依赖可安装。npm view 官方说明 ↗（外部链接，在新标签页打开）

不要把“安装卡住”直接等同于缓存损坏，也不要用删除 DSH Home 或 Session 作为下载故障的首步。版本选择和回退前的数据处理见更新与卸载指南。

pnpm 已安装，为什么 DSH 仍然找不到？

先在运行 DSH 的同一个终端执行 pnpm --version。macOS/Linux 用 command -v pnpm 查看路径；Windows PowerShell 用 Get-Command pnpm。系统中装过 pnpm 或 Corepack，并不能证明当前进程的 PATH 能找到 pnpm；完成安装或修改环境后，重新打开终端再检查。pnpm 官方安装说明 ↗（外部链接，在新标签页打开）

固定 0.1.2-rc.1 的插件管理源码通过子进程调用 pnpm；出现 ENOENT 时输出 pnpm not found on PATH 并返回 127。这与下载超时或 allowBuilds 拒绝构建是不同问题。固定源码 ↗（外部链接，在新标签页打开）

普通 npm 用户从安装指南启动；pnpm install 是在项目目录安装依赖的命令，不能脱离当前目录照抄源码开发流程。本节仅静态复核插件管理的 pnpm 调用，不表示已安装或运行第三方插件。

确认命令和运行时

本页历史基线的固定启动命令是 npx @deepseek-ai/[email protected] web，默认地址是 http://127.0.0.1:3080。0.1.1-rc.2 要求 Node.js ^22.19.0 || >=24.0.0。确认当前终端实际调用的是预期 Node.js，而不是系统中另一个旧版本。完整五步路线见DeepSeek Harness 安装与 Web UI 教程。

排查端口和残留进程

如果日志提示端口被占用，先确认占用者是否是另一个仍在运行的 DSH 实例。不要为了释放端口批量结束不认识的系统进程。优先正常关闭旧实例，或使用 --port 选择另一个端口。跨平台只读检查命令和 Host 限制见3080 端口占用修复。

区分网络、权限和配置问题

下载依赖失败通常与网络、代理或证书有关；写入失败通常与目录权限或安全软件有关；启动后模型不可用则更可能是配置或凭据问题。一次只改变一个变量，并记录变化后的错误。

页面打开但输入框不可用时，先检查是否选择了 Workspace。启动后模型不可用时，按模型与 Provider 配置检查凭据和路由。

如果错误是 SANDBOX_UNAVAILABLE，表示受限模式没有可用的沙箱后端并已失败关闭。不要为了绕过错误直接使用完全访问权限；先按DSH 权限与沙箱指南确认平台后端与实际风险。

页面已打开，但连接中断

先确认原启动终端中的 DSH 服务是否仍在运行。服务已经退出、地址不对或端口冲突时，点击重连不会启动服务；先处理终端错误。页面仍与 Host 连接、只有模型请求出现 401 时，也应排查凭据而不是反复重连。

在 alpha.2 的展开侧边栏中，底部“设置”旁会显示异常后的连接状态：

固定实现把手动入口连接到 Connection.reconnect()。它不是“修复全部网络问题”，更不是关闭认证或放开工作区权限的理由。连接恢复官方说明 ↗（外部链接，在新标签页打开）

重连持续失败时记录服务状态、DSH 版本、操作系统、连接提示与脱敏错误。不要公开启动链接令牌、Cookie 或真实凭据；也不要先删除 Profile、Session 或禁用防火墙。想确认是否值得评估新入口，阅读alpha.2 更新与适用范围；它没有自动替换 npm 默认安装版。

alpha.3 只减少一种“误判断线”

本小节 alpha.3 专指 0.1.2-alpha.3，不是后续版本线的同名编号。

0.1.2-alpha.3 针对 Host 被同步工作短暂阻塞的情况调整了连接判断：网关容忍有限次心跳缺失并安排后续终止检查，客户端准备阶段超时会记录警告，而不是立即把停顿 Host 当作断开。这有助于减少“后端仍在工作，却被页面提前判定断线”的情况。alpha.3 完整变化与适用范围

这不是全部连接故障的统一修复。服务进程已经退出、访问地址或端口错误、代理切断、认证令牌失效、模型 Provider 返回 401，以及网络确实不可达时，仍应按本页症状逐项排查。本站只完成固定源码审阅，没有运行 Host 停顿复现测试。

修复后怎样验证

重新执行一个最小、只读任务，确认界面、日志和输出范围都正常。如果问题仍然存在，把脱敏后的环境、命令、错误和已尝试步骤一起提交，而不是重复执行未经理解的修复脚本。

需要重新走完整流程时返回安装 DeepSeek Harness 并启动 Web UI；需要按其他故障阶段查找时进入DeepSeek Harness 错误知识库。

0.1.6-alpha.2：启动错误与日志

2026-09-18 固定源码复核；本节只覆盖 alpha.2 的启动审计，不改变下方旧版本案例。新版区分启动失败的条目与等待依赖服务的条目，等待不等于该服务已崩溃。

CLI 对 StartupError 写入实际 DSH Home 下的 logs/startup-<ISO 时间，冒号替换为短横线>-<UUID>.log，并在 stderr 显示 Full diagnostics: <实际路径>；先按终端路径找文件，不猜跨平台绝对目录。Home 可随 DSH_HOME 配置改变。日志无法写入时会提示写入失败，并把完整诊断输出到 stderr；其他普通错误不能一概套用这个文件位置。

报告包含 DSH/Node 版本、平台、Profile 和完整错误对象及其原因。启动器不主动采集环境值，但插件错误可能包含配置或凭据；分享前移除 Key、Token、私人路径和业务内容。实例占用先正常退出相应实例，不删除锁文件、清空 Home 或结束所有 Node 进程。修复后同时检查退出状态、页面和此前失败能力；发行说明中的等待改善没有本站速度实测数据。

依据：启动审计 ↗（外部链接，在新标签页打开）、诊断日志实现 ↗（外部链接，在新标签页打开）。

0.1.5-rc.1：Windows 路径和断线恢复

候选版发行说明 ↗（外部链接，在新标签页打开）列明 Windows 盘符根目录 Workspace 的分隔符、标题和绝对路径校验修复，以及 Web 断线后自动恢复修复。SDK Windows 启动修复是另一条路径，不能把 Web 页面断线统一归因于 SDK。

先记录实际版本和故障阶段：盘符根目录不能作为 Workspace 时核对路径与权限；页面断线时核对 Host 进程、地址和网络；SDK 崩溃时转Headless 与 SDK 指南。不因新版有修复就删除旧 Profile 或会话。本站未运行这些平台复现，具体错误仍按前部症状表分流。

0.1.5-alpha.2：npm 安装触发 fs-ext 编译

alpha.2 发行说明 ↗（外部链接，在新标签页打开）列明修复 npm 安装需要依赖 fs-ext 本地编译的问题。这是官方版本说明，本站未执行跨平台安装验收；不能推广为所有架构已无原生依赖问题。

需要评估 0.1.5-alpha.2 时先阅读更新与回退指南，此处修复仅指历史版本，本站当前基线与命令见维护页。不要在唯一环境上反复升级或删除缓存、配置和会话；有具体错误再按前部阶段表排查。

新版会话加载变慢，先区分性能与启动故障

2026-09-05 的默认 npm 版本为 0.1.2-rc.1；0.1.3-alpha.1 是另一条预发布线。官方说明 0.1.3-alpha.1 存在可能影响部分历史会话加载的性能回退。页面已经打开但旧会话载入缓慢，不等于端口启动失败，也不能据此判断 Session 正文丢失。

先记录实际 DSH 版本、会话是否能列出、能否打开、是否有格式或锁错误，再进入Session v2 与读取边界。alpha.1 的 read 打开也可能生成迁移文件，诊断应使用副本。遇到写入占用时先排查仍在运行的进程，不删除锁文件；格式错误时保留原文件，不清空缓存或 DSH Home。

本节只补充固定来源与官方已知问题，未运行故障复现。若需切换版本，阅读更新回退指南和0.1.3-alpha.1 专题；0.1.1-rc.2 与 0.1.2-alpha.2～alpha.5 小节保留原有适用范围。

从 rc.2 或 alpha.3 升级 alpha.4 后立即失败

历史范围：标题中的 rc.2 指 0.1.1-rc.2，alpha.3 / alpha.4 指 0.1.2-alpha.3 / 0.1.2-alpha.4；保留原标题供旧链接访问。

如果同一台机器、同一 Profile 在 0.1.1-rc.2 或 0.1.2-alpha.3 能启动，切换到 0.1.2-alpha.4 后立即失败，这属于 0.1.2-alpha.5 官方修复范围中的已知升级症状。固定实现将原因定位到 session_projcache 跨磁盘版本读取：旧缓存可能被按新版本错误解释并阻止启动。0.1.2-alpha.5 增加 v3、v4 兼容读取，并允许无法安全解释的可丢弃投影记录先备份再冷重建。

请先记录实际 DSH 版本、完整第一条与最后一条错误、Profile 路径和 Session 列表快照，再保存原数据副本。不要因为看到“缓存”就手动删除整个 Session 或 DSH Home；投影缓存与权威 Session 正文是不同数据角色。alpha.5 也不能解释端口冲突、Node 不兼容、Provider 401、网络断线或第三方插件构建失败。

本站没有执行 0.1.2-alpha.4→0.1.2-alpha.5 的真实升级。准备在隔离副本评估时，先阅读alpha.5 修复范围与升级检查表和DSH 更新、回退与卸载指南，不要把版本切换和数据清理同时进行。