DeepSeek-Harness部署踩坑

DeepSeek-Harness(dsh) 本地部署踩坑总结

简介

DeepSeek-Harness（简称dsh）是DeepSeek推出的本地网页调试工具，方便对各类大模型API进行对比调试。

⚠️重要：它不是双击运行的EXE桌面软件，是基于Node.js的命令行工具。

• 关闭终端窗口 / 电脑重启，服务直接停止，不会后台驻留。
• API Key、模型配置全部保存在用户目录 .dsh，重启电脑不会丢失配置。

三种启动方式

方式1：npx临时运行（无需全局安装）

不需要安装，直接在 PowerShell / CMD 执行：

npx @deepseek-ai/dsh web

• 原理：npx按需拉取npm包运行，不写入系统。
• 缺点：npm缓存清理、版本更新时，会重新下载包。
• 默认访问地址：http://127.0.0.1:3080

方式2：全局安装（推荐，避免重复下载）

1. 执行全局安装

npm install -g @deepseek-ai/dsh

2. 后续直接启动服务

dsh web

3. 校验全局安装是否成功

dsh --version

输出版本号，代表环境正常。

方式3：桌面启动器 dsh-launcher（双击即用，推荐新手）

dsh-launcher 是社区开发的 Windows 原生启动器，把命令行操作封装成双击即用的桌面程序，安装包仅 ~1.4MB。

核心优势：

• 双击启动，不用敲命令
• 支持开机自启
• 独立小窗口（WebView2 内嵌页面），不用开浏览器
• 自动拉起 dsh 服务并等待就绪
• 出错弹窗带错误码，统一日志 ~/.dsh/dsh-launcher/dsh.log
• 支持托盘驻留、窗口位置记忆、主题跟随
• 不内置 dsh，缺失依赖（Node.js 等）按需补齐，不改动系统环境

安装方法

MSI 安装包（推荐新手）：

1. 前往 Releases 下载 dsh-launcher-<版本>.msi
2. 双击安装，安装向导里可勾选「开机自启」
3. 安装完成后桌面会出现快捷方式，双击即可启动
4. 卸载：设置 → 应用 → dsh-launcher

便携版 ZIP：

1. 下载 dsh-launcher-windows-<版本>.zip
2. 解压后双击 DshWeb.exe 即可运行
3. 删除文件夹即卸载

双击没反应？先运行解压目录里的 check-prereq.cmd，它会检测 .NET / WebView2 / Node 并给出缺失项的安装命令。

配套插件：服务驻留模式

安装 dsh-launcher-lifetime 插件后，可在 dsh 设置页「Node服务驻留」中切换三种模式：

• 随窗口驻留：关窗口即停服务
• 常驻：关窗口后服务继续后台运行
• 随托盘驻留：最小化到托盘，服务持续运行

安装命令：

dsh plugin --profile web add dsh-launcher-lifetime

一键诊断

遇到问题可执行诊断命令，导出脱敏诊断包：

DshWeb.exe --diagnose

Windows一键双击启动bat脚本

如果不想装桌面启动器，也可以用批处理脚本快速启动。新建文本文档，复制下面代码，保存，修改后缀为 启动dsh.bat，编码选择ANSI。

@echo off
dsh web
pause

• pause：防止程序报错窗口一闪而过，可以看到终端报错信息。
• ✅只双击这个bat文件。
• ❌禁止双击 node_modules 文件夹内部的脚本文件，会弹出"此应用无法在你的电脑上运行"报错。

常见报错排错

1. 弹窗：此应用无法在你的电脑上运行

• 原因：直接双击了内部js脚本，dsh是命令行工具，不能双击运行原始脚本。
• 解决：使用终端命令、bat脚本或 dsh-launcher 桌面启动器启动，不要直接双击脚本文件。

2. 'dsh' 不是内部或外部命令

• 原因：全局安装完成，系统PATH环境变量没有刷新。
• 解决：关闭全部终端窗口，重新打开PowerShell再次执行命令。

3. 3080端口被占用

手动指定其他端口启动：

dsh web --port 3081

访问地址变为 http://127.0.0.1:3081

4. Node版本报错

检查node版本：

node -v

硬性要求 Node.js >=22，版本过低需要重装Node.js。

5. dsh-launcher 双击没反应

• 运行解压/安装目录里的 check-prereq.cmd 检测依赖
• 确认已安装 Node.js >=22、WebView2、.NET 运行时
• 查看日志 ~/.dsh/dsh-launcher/dsh.log 定位具体错误

使用注意事项

1. 命令行/bat方式启动后，黑色终端窗口不能关闭，关闭服务立刻停止。
2. 电脑重启，服务不会自动启动（除非使用 dsh-launcher 并开启开机自启）。
3. 命令行方式启动成功后，全部操作在浏览器打开本地地址完成；dsh-launcher 则在独立窗口内操作。
4. dsh-launcher 仅为启动壳，不修改 dsh 本身的功能和配置，所有插件、API Key 等与原版完全通用。

最简完整流程

方案A：命令行派

1. PowerShell执行全局安装：npm install -g @deepseek-ai/dsh
2. 启动服务：dsh web
3. 浏览器访问：http://127.0.0.1:3080
4. 后续开机直接双击bat脚本一键拉起服务。

方案B：桌面派（推荐新手）

1. 下载 dsh-launcher MSI 安装包并安装
2. 双击桌面快捷方式，自动拉起 dsh 服务并打开窗口
3. 安装时勾选开机自启，以后开机自动运行

如果全局npm环境异常，可以退回npx模式，原有配置不会丢失。