SiriusWJ/dsh-restart-btn

dsh-restart-btn

在 DSH 设置页 General 区加一行「重启 Web 服务」按钮：点一下就把 dsh web 重启一遍，
用于让插件 / 主题 / 配置改动生效，不用再去双击桌面快捷方式。

页面会在服务重启期间短暂断开，服务回来后自动重新载入——不需要手动刷新。

界面文案中英双语，跟随 DSH 的语言设置；没有显式选择语言时取浏览器（即系统）语言。

设计目标只有一个：换台机器、换个启动方式，也照样能重启——而不是只在作者那台机器上能跑。

兼容的环境

| 环境 | 处理方式 |
| --- | --- |
| Windows：终端 / 桌面快捷方式启动（有控制台） | cmd /c start /b 让助手孤儿化，助手再 taskkill /T /F 停旧服务 |
| Windows：无控制台（服务、计划任务、explorer 启动） | 同上；助手是 node，不像 powershell.exe 那样依赖控制台 |
| Windows：非管理员、AppLocker 禁 PowerShell 脚本、执行策略受限 | 助手不经过 PowerShell、不建计划任务、不需要提权；PowerShell 只在最后可选回退里出现 |
| Windows：node 装在含空格路径（C:\Program Files\nodejs） | start "" /b "" ""，已实测可用 |
| Linux / macOS / WSL | detached: true（setsid）起独立会话；SIGTERM 超时后 SIGKILL；lsof → fuser → ss 依次探测监听者 |
| 源码树运行（pnpm dsh web）、nvm / volta / pnpm 全局安装 | 复用 process.execPath + 原 argv + process.execArgv，不猜安装路径 |
| 非默认端口、--port 0（系统随机端口） | 端口以浏览器地址栏为准，重写 argv 里的 --port，不会重启到另一个端口上 |
| 端口被外来进程占用 / 找不到监听者 | 退化为停掉「发起重启的那个进程」（selfPid），而不是什么都不做 |

本仓库的 CI 验证在 Windows 上完成（含助手全流程集成测试）；POSIX 分支（setsid + lsof/fuser/ss + SIGTERM/SIGKILL）在本机没有 Linux/macOS 环境，未做端到端实测——它要么成功，要么明确报错，不会静默假成功。

为什么会有这个插件

「把助手脚本发出去」有几条隐蔽的死路，共同特征是看起来成功了，实际一行都没跑：

1. detached: true（Node）/ DETACHED_PROCESS：进程拿不到控制台，而 powershell.exe
是控制台程序——它会立刻以退出码 0 结束，脚本一行都不执行。spawn 不抛错，
于是调用方以为发起成功。
2. schtasks /Create：命令行按 ANSI 代码页写入，含非 ASCII 字符（例如中文工作区
...\OneDrive\文档\txt2）的路径会被静默损坏，任务报 Last Result: 0 但什么都没做；
而且在非管理员上下文里它常常直接 ERROR: Access is denied.
3. 助手是子进程：即便起来了，也会被助手自己发起的 taskkill /T /F（清掉 dsh 进程树）一起杀掉。

本版本的处理方式：

1. 助手用 node 运行（不用 PowerShell）：解释器就是正在跑这个服务的那个 node
（process.execPath），因此不存在「系统里没有 PowerShell / 执行策略不允许 / 编码页损坏路径」这类问题。
2. 助手被拉出进程树：Windows 用 cmd /c start /b（cmd 立刻退出 → 助手成为孤儿），
POSIX 用 setsid。助手因此不会被自己执行的那次 taskkill /T /F 杀掉。
3. 发起后必须验证：助手的第一件事就是写 helper.launch（含自己的 PID），
宿主轮询最多 6 秒；没等到就返回 500 + 原因，前端会把原因显示出来，绝不谎报成功。
4. 所有用户相关路径（node、入口、参数、工作目录、日志）走 UTF-8 JSON 配置文件，
不进命令行，避开各平台 shell 的引号 / 编码差异。

它怎么重启

| 步骤 | 做法 |
| --- | --- |
| 0 | 暂存 restart-helper.cjs + UTF-8 JSON 配置，拉出进程树启动，并验证 helper.launch 出现 |
| 1 | 延迟若干秒，让 HTTP 响应先回到浏览器 |
| 2 | 按端口找到监听进程（Windows netstat -ano；POSIX lsof/fuser/ss），Windows taskkill /T /F、POSIX SIGTERM（超时升级 SIGKILL） |
| 3 | 用 TCP 轮询等端口真正释放 |
| 4 | 用同一个 node 加上原启动参数（execArgv + 原 argv，端口重写为当前端口）拉起新服务，stdout/stderr 重定向到日志文件 |
| 5 | TCP 轮询就绪（最多 45s）——不用 HTTP 探测，避免把「401 未授权」误判成失败 |
| 6 | 直连启动失败时（仅 Windows + 3080），回退执行桌面启动器 %LOCALAPPDATA%\DeepSeekHarness\start-dsh.ps1 |

服务端身份（instance）在每次进程启动时不同，前端只有在 ping 到另一个 instance 时才刷新页面，
因此不会把「还没死掉的旧服务」误认成「新服务已就绪」。

重启后为什么会话有时要重新授权

dsh 的 Web 认证是绑定 authority 的签名 cookie（dsh-auth-）。
它没有「关闭认证」的开关：requestRejection() 先做 Host/Origin 围栏（403），
再要求 cookie 通过（401）；trustedHosts 只放宽围栏，不能绕过 cookie。

签名密钥存在凭据库里、重启不变，所以同一个 cookie 重启后依然有效（实测：重启前后都是 200）。
但 cookie 有寿命，而一个长期开着的标签页可以活得比它的 cookie 更久——页面还能用只是因为连接早就建好了，
这时一次普通刷新就会撞上 dsh web authentication required。

token 的唯一作用是把 cookie 种进浏览器。 桌面快捷方式之所以「总是能用」，正是因为
dsh web 启动时会打印 http://127.0.0.1:/?token=… 并打开它，于是每次启动都重新签发 cookie。

所以本插件不自己转发任何 token：重启时不加 --no-open，让 dsh 照常打印并打开那个已授权地址
（行为与桌面快捷方式完全一致）。新页面完成 token 兑换后，同一个 authority 的 cookie 被刷新，
旧标签页的探测（GET / 是否 200）随之通过并自动重载——因此前端不会盲目刷新，
探测不通过就提示用桌面快捷方式，绝不会把页面刷成一片 401。

安装

本地目录
dsh plugin --profile web add D:/Code/dsh/dsh-restart-btn

或从 GitHub
dsh plugin --profile web add github:SiriusWJ/dsh-restart-btn

改完 bundle 需要重启一次 dsh 生效（第一次请手动重启）。

路由

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | /dsh-restart-btn/restart | 同源校验；body {"port":"3080"}；返回 instance / log / trigger |
| GET | /dsh-restart-btn/ping | 返回 {ok, instance, pid, platform}，供页面判断新进程是否就绪 |

失败响应统一带稳定 code（如 helper-not-started、staging-failed）与英文 error；前端按当前语言本地化，code 清单见 client/client.js 的 HOST_ERROR_KEYS。

日志与排错

暂存目录：Windows %LOCALAPPDATA%\dsh-restart-btn（用户名含非 ASCII 时依次退到
%ProgramData% / %SystemRoot%\Temp / %TEMP% / ~/.dsh），Linux/macOS 为 $TMPDIR/dsh-restart-btn。

| 文件 | 内容 |
| --- | --- |
| restart.log | 重启全过程（停进程 / 端口释放 / 启动 / 就绪 / 失败原因 + stderr 尾部） |
| helper.launch | 助手启动凭证（PID），由助手写出、宿主读取校验 |
| dsh.out.log | 新服务的 stdout（含它打印的 token 地址） |
| dsh.err.log | 新服务的 stderr |

排错第一步永远是看 restart.log；若暂存目录不在预期位置，以 POST /dsh-restart-btn/restart
返回的 log 字段为准。

开发与测试

npm run check   # 语法检查
npm test        # 3 组：助手全流程集成（假旧服务 → 停 → 起 → 就绪）、启动校验、重启参数拼装

tests/helper.test.js 会在一个空闲端口上起一个假服务，跑真实的 restart-helper.cjs
把它换掉，并断言日志出现 RESTART OK——即整套重启契约，不碰你正在用的 dsh。

已知取舍

- 重启时不加 --no-open，所以每次重启浏览器都会多开一个已授权的标签页（与桌面快捷方式一致）。
旧标签页靠 cookie 刷新后自动重载。想改成不弹新标签页，需要让插件把新 launch url 转交给页面，
代价是插件要对外提供一次完整会话凭据。
- 只停监听该端口的进程：若 dsh 由某个 supervisor 托管并会自动拉起，可能变成「重启后又回来」，
这时 restart.log 会显示端口一直没释放。
- macOS 的 lsof 需要完整系统（自带）；极简 Linux 镜像若无 lsof/fuser/ss 三者，
助手会明确报「找不到监听者」并退化为停 selfPid。

License

MIT