Web 服务托管 zheyuanlinye7/dsh-web-service

dsh-web-service

把 dsh web 变成 Windows 服务：开机自启、无黑窗、注销也在跑。

一个 DeepSeek Harness 插件（MCP 工具 + 命令行），底层用 nssm 或 WinSW 托管的服务包装器。

为什么需要它

dsh web 是一个前台进程：关掉那个命令行窗口，Web UI 就没了；注销、重启之后它也不会自己回来。想做一台「随时能连的 DSH 主机」，就必须把它交给 Windows 服务控制管理器（SCM）。

但 Node 程序不能直接当 Windows 服务——SCM 要求程序调用 StartServiceCtrlDispatcher 并周期性上报心跳，一个普通的 node.exe 做不到，30 秒后就会被 SCM 判定为无响应而杀掉。所以必须有一个原生包装器（nssm、WinSW）夹在中间。

手工配置这个包装器有一堆坑：LocalSystem 账户下 ~ 指向的是系统配置目录而不是你的用户目录，于是 DSH_HOME、USERPROFILE、APPDATA 全都得显式写进服务环境变量；--no-open 不能忘；日志轮转、重启策略、优雅停止窗口都要设。这个插件把这些一次性做对。

它做什么

- 安装/修复服务：探测 node、@deepseek-ai/dsh/lib/bin.js、$DSH_HOME、profile 目录、服务包装器，生成完整参数并注册服务，然后启动并探测端口。
- 诊断：解析服务日志，把「为什么起不来」翻译成人话——端口被占、profile 插件与新版本 dsh 不兼容、插件树加载失败、profile 目录不存在、权限被拒。每条结论都给出可执行的修复建议。
- 控制：start / stop / restart，并等待 SCM 真正报告新状态，而不是把 sc start 的退出码当成结果。
- 零副作用预演：plan 会打印出将要执行的每一条命令和将要写入的每一个文件，一个字节都不落盘。
- 两种包装器：nssm（公有领域）和 WinSW（MIT），自动探测，不需要手工指定路径。

它不做什么

- 不打包也不下载任何二进制。它只用机器上已有的 nssm 或 WinSW。下载可执行文件这件事应该由你决定，而不是由插件替你决定。
- 不改动 dsh 本体。不 patch DSH 源码，不碰它的监听绑定。
- 不需要管理员权限来看。status、plan、diagnose 全是只读的；只有 install / uninstall / start / stop 需要提权。

安装

从 GitHub 安装
dsh plugin --profile web add "github:zheyuanlinye7/dsh-web-service"

装完 重启一次 dsh。插件包的 cordis.patch.yml 会把 MCP 工具挂上去，但默认是关的：

- id: mcp-dsh-web-service
name: '@deepseek-ai/dsh-mcp-client'
disabled: true # 装个包不该顺带获得管理员能力

想用 agent 管理服务，就在 Plugins 页面把这一行打开（或把 disabled 改成 false）再重启。

前置条件

- Windows（win32），Node.js 22+
- 一个服务包装器：nssm 或 WinSW
- 放在 PATH 上，或者任意常见位置（%USERPROFILE% 下 4 层以内、Program Files、ProgramData），插件会自动找到；也可以用 --nssm / --winsw 显式指定。

快速开始

命令行

先看现状：服务在不在、谁占着端口、HTTP 通不通、日志在哪
npx dsh-web-service status

看它打算做什么（只读，不改任何东西）
npx dsh-web-service plan

以管理员身份执行
npx dsh-web-service install

起不来的时候问它为什么
npx dsh-web-service diagnose

让 agent 来做

打开 MCP 工具行之后，直接跟 agent 说：

把 dsh web 装成 Windows 服务，端口 3080，开机自启。

模型会看到这些工具：

| 工具 | 作用 |
| mcp__winsvc__service_status | 服务状态、端口占用者、HTTP 探测、日志路径 |
| mcp__winsvc__service_plan | 预演安装，不改动任何东西 |
| mcp__winsvc__service_install | 创建/重写服务并启动 |
| mcp__winsvc__service_uninstall | 停止并删除服务 |
| mcp__winsvc__service_control | start / stop / restart |
| mcp__winsvc__service_diagnose | 读日志解释失败原因 |
| mcp__winsvc__service_logs | 打印日志尾部 |

配置项

CLI 与 MCP 工具共用同一组选项（CLI 用 --dry-run，MCP 用 dryRun: true）：
| 选项 | 默认值 | 说明 |
| --name / name | dsh-web | 服务名 |
| --profile / profile | web | 要托管的 dsh profile |
| --port / port | 3080 | 监听端口 |
| --host / host | 不传 | 绑定地址；不传就用 profile 里组合出来的值。想让局域网直连就传 0.0.0.0 |
| --dsh-home / dshHome | $DSH_HOME → ~/.dsh | harness 主目录 |
| --dsh-bin / dshBin | 自动探测 | @deepseek-ai/dsh/lib/bin.js |
| --node / node | 当前 node | 服务要跑的 node.exe |
| --nssm / nssm | 自动探测 | nssm.exe 路径 |
| --winsw / winsw | 自动探测 | WinSW 可执行文件路径 |
| --account / account | LocalSystem | 服务账户 |
| --log / log | <用户目录>\<服务名>.log | 服务日志（stdout 与 stderr 合并，10 MB 轮转） |
| --force / force | false | 服务已存在时先删除再重建 |
| --json | false | 机器可读输出（CLI） |

工作原理

安装一个服务，本质上就是把这五件事写对：

1. 谁来跑：node.exe <...>\dsh\lib\bin.js web --no-open --port 3080
2. 在什么环境下跑：因为服务以 LocalSystem 身份运行，~ 是系统配置目录。所以 DSH_HOME、USERPROFILE、HOMEDRIVE、HOMEPATH、APPDATA、LOCALAPPDATA、TEMP 都必须显式写进服务环境，否则 dsh 会去 C:\Windows\System32\config\systemprofile\.dsh 找 profile——然后告诉你 profile 不存在。
3. 工作目录：必须是一个真实存在的目录，否则某些相对路径解析会失败。
4. 日志：stdout 与 stderr 指向同一个文件，开轮转（10 MB，保留一份），否则跑一个月就是几个 GB。
5. 退出之后：AppRestartDelay 2000 + AppExit Default Restart 让它崩了自动回来；AppStopMethodConsole 5000 给它 5 秒优雅退出。

更多实现细节见 docs/architecture.md。

故障排查

这些不是假想的场景，是这套工具在真机上被写出来的原因。完整版见 docs/troubleshooting.md。

服务在重启循环里刷 EADDRINUSE

Error: listen EADDRINUSE: address already in use 0.0.0.0:3080

已经有一个 dsh web 占着端口——通常是你之前手动起的那个。服务进程启动、绑定失败、退出，nssm 两秒后重启它，周而复始。先停掉手动实例，或者换一个 --port。

更新 dsh 之后服务就废了

dsh: skipping profile bundle "dshmarket": Error: Plugin dshmarket@1.18.1
is incompatible with dsh 0.2.0-rc.2: peerDependencies { ... }

某个 profile 插件的 peer 依赖对不上新版运行时。dsh 的策略是跳过这个 bundle：包还在磁盘上，但启动时不会挂载，于是它的界面直接消失。升级那个插件，或者给它授权精确版本豁免。

插件树整个加载不了

Error: dsh: plugin tree failed to load: failed to apply loader entry
include (cordis:include): failed to import loader entry dsh-lan-guard

一个插件的 import 阶段就抛异常，整棵树跟着挂掉，dsh 直接退出——服务于是重启循环。找出日志里那个包名，升级、禁用或移除它。

diagnose 把历史错误也报出来了

日志是轮转追加的，历史上崩过的记录永远在里面。所以当服务正在运行且 HTTP 有响应时，日志里的 ERROR 会被降级成 INFO 并标注"日志里保留的早期失败"，只有真正当前的故障才报 ERROR。

安全说明

安装服务需要管理员权限，请在有权限的终端里执行（install 之外的动作都不需要）。

--host 0.0.0.0 会把 Web UI 暴露到整个局域网。dsh 自身对 Web UI 有基于 token 的浏览器会话鉴权，但如果你另外打过绕过鉴权的补丁，那么任何能访问该端口的设备都能完全控制这台机器上的 agent——包括它的文件访问和命令执行能力。想清楚再开。

兼容性

| 项 | 值 |
| 平台 | Windows（win32） |
| Node.js | >= 22 |
| dsh | >=0.2.0-rc.1 <0.3.0（声明于 dsh.engines） |
| 包装器 | nssm（公有领域）、WinSW（MIT） |

开发

node test/run-tests.mjs # 17 个单元测试，不碰机器状态
node test/mcp-list.mjs # 真实 stdio 管道的 MCP 握手 + tools/list
node mcp/server.mjs --self-test

测试里的日志样本是从真机上逐字摘下来的——src/diagnose.mjs 的每一条规则都对应一次真实故障，不是猜的。

许可

MIT。本项目不包含也不分发任何第三方二进制；nssm 与 WinSW 的授权说明见 THIRD_PARTY.md。