重启控制 darkchaox/dsh-restart-control

dsh-restart-control

为 DSH Web 提供跨平台、受控的「重启 DSH」设置页面。管理员可以在 Web UI 发出固定格式的重启请求，插件会先保存状态，再根据主机环境选择交给外部服务管理器重启，或由内置的 portable helper 重新拉起 DSH。

[!WARNING]
若 DSH 已由 PM2、Docker、Windows Service、systemd 或其他服务管理器负责自动重启，请使用 DSH_RESTART_CONTROL_MODE=external，避免外部管理器与 portable helper 同时拉起多个 DSH 进程。若 DSH 是在 Windows、macOS 或没有服务管理器的 Linux 上手动启动，默认的 auto 模式会使用跨平台 portable helper。

功能

- Web 设置页： 在 DSH Web 的设置页加入「重启 DSH」区块，提供确认、状态显示与重新整理按钮。
- 跨平台重启： 支持 Windows、macOS 及 Linux；没有 systemd 或其他外部管理器时，可由内置 helper 重新拉起原本的 DSH 进程。
- 外部管理器整合： 在 systemd、PM2、Docker、Windows Service 等环境中，可只退出并返回固定的 exit code 75，让既有管理器依其重启策略接管。
- 受控重启： 浏览器只提交 settings 状态，不接受 shell 命令、文件路径或服务管理器参数。
- 可靠确认： 宿主端先保存 scheduled 状态；新进程产生新的 bootId 后才会将状态标记为 success。
- 失败可见： 请求逾期、时间格式错误、连续重启过快、状态保存失败或 helper 无法启动时，UI 会显示失败原因，不会伪报成功。
- 无需广泛权限： 插件不要求为 DSH Web 授予 root、sudo、systemd 或 shell 执行权限。

重启策略

插件读取环境变量 DSH_RESTART_CONTROL_MODE。只接受下列固定值；未设置或填入未知值时会回到 auto：

| 值 | 行为 | 适用情境 |
| auto（默认） | Windows 直接使用 portable；macOS／Linux 检测到 systemd 管理环境时使用 external，否则使用 portable。 | 手动启动的 DSH，或希望由插件自动判断的环境。 |
| portable | 启动内置 helper，等待当前 DSH 进程退出后，以原本的 Node executable、参数、工作目录与环境重新拉起 DSH。 | Windows、macOS、没有服务管理器的 Linux。 |
| external | 保存 scheduled 后以 exit code 75 结束当前进程，不自行启动子进程。 | systemd、PM2、Docker、Windows Service 或其他已配置自动重启的管理器。 |
| systemd | external 的兼容别名。 | 旧版只使用 systemd 命名的部署配置。 |

auto 不会调用 systemctl 或其他服务管理命令；在非 Windows 环境只读取 systemd 注入的 INVOCATION_ID、NOTIFY_SOCKET 或 SYSTEMD_EXEC_PID 来判断是否交给外部管理器。若部署环境的检测结果不符合预期，请明确设置 portable 或 external。

建议选择

- Windows 本机手动启动： 保持 auto，或明确设置为 portable。
- macOS／Linux 手动启动： 保持 auto；没有 systemd 时会使用 portable。
- systemd 服务： 保持 auto 即可；插件检测到 systemd 后会使用 external。也可以明确设置 external。
- PM2、Docker、Windows Service 或其他管理器： 明确设置 external，由原有管理器处理 exit code 75。
- 不要在同一个 DSH 进程同时使用 portable 与外部自动重启： 否则可能产生重复进程。

设置环境变量

在 Windows PowerShell 7 中，先在同一 PowerShell 会话设置，再使用原本的 DSH 启动命令：

~~~powershell
$env:DSH_RESTART_CONTROL_MODE = 'portable'

在此执行你原本的 DSH 启动命令

若 DSH 由 Windows Service、PM2 或 Docker 启动，请把 DSH_RESTART_CONTROL_MODE=external 加到该管理器的服务环境，而不是只在交互式 PowerShell 中设置。设置完成后，必须重启 DSH，新的环境变量才会生效。

安全模型

插件把浏览器请求限制在 dsh-restart-control settings namespace，请求只包含下列固定状态字段：

| 字段 | 用途 |
| state | idle、requested、scheduled、success 或 failed |
| requestId | 识别单次重启请求，只接受受限格式的字符串 |
| requestedAt | 判断请求是否仍在 10 分钟有效期内 |
| scheduledAt、completedAt | 记录排程与完成时间 |
| bootId | 识别当前 DSH 进程，确认服务确实经历了重启 |
| message | 显示受控流程的结果或失败原因 |

宿主端的处理顺序如下：

1. 验证 state、requestId 与 requestedAt，拒绝不合法、过期或时间超前过多的请求。
2. 以 scheduled 状态保存请求，让前端在 DSH 暂时离线前取得可靠的排程记录。
3. 在 portable 模式启动本地 helper；在 external 模式不启动子进程，只以 exit code 75 结束。
4. portable helper 不使用 shell，会等待原本的 DSH 进程退出，再使用宿主在启动时的 executable、参数、工作目录与环境拉起新的 DSH。
5. 新进程产生新的 bootId，读到上一个 scheduled 请求后标记为 success。
6. Web UI 在服务短暂离线期间轮询 settings.describe，只有在看到相同 requestId、新的 bootId 与 success 时才显示重启成功。

浏览器提交的 payload 没有 command、path、executable 或服务管理器参数字段。插件不把用户提供的内容拼接成命令行，也不执行 shell: true、exec 或 systemctl。

环境需求

- 已安装 DSH Web，并使用 web profile。
- DSH 运行环境提供下列 peer dependencies：
- @deepseek-ai/cordis ^4.0.1
- @deepseek-ai/dsh-settings 0.1.0-rc.7
- @deepseek-ai/schemastery ^3.18.1
- Web client 可使用 DSH Web 已提供的 React runtime。
- 若使用 external，外部服务管理器必须已配置在 DSH 退出后自动重启。
- 若使用 portable，DSH 必须由可重复使用的 Node executable、参数与工作目录启动；插件会沿用当前进程的启动信息。

安装

使用官方 DSH CLI（推荐）

如果主机已安装官方 dsh CLI，推荐直接使用以下命令从 GitHub 安装。这也是 DSH 插件市场优先识别的官方安装入口；若 CLI 不可用，市场才会回退到 GitHub bundle 安装。

~~~sh
dsh plugin --profile web install darkchaox/dsh-restart-control

以下命令在 DSH 主机上执行。先将 GitHub repository clone 到本地插件目录，再把该目录加入 web profile。

Linux、macOS 或其他 Unix-like 环境

~~~sh
git clone https://github.com/darkchaox/dsh-restart-control.git /home/dsh/local-plugins/dsh-restart-control
dsh plugin --profile web add /home/dsh/local-plugins/dsh-restart-control

若 DSH 由 systemd 管理，完成插件安装后可使用原本的服务管理命令重启：

~~~sh
sudo systemctl restart deepseek-harness.service

systemd 环境可以保持 DSH_RESTART_CONTROL_MODE=auto；插件会依 systemd 注入的环境信息选择 external。如需明确设置，可在服务单元加入：

~~~ini
[Service]
Environment=DSH_RESTART_CONTROL_MODE=external

Windows PowerShell 7

以下示例使用 PowerShell 7；请把本地目录替换为你的 DSH 插件目录：

~~~powershell
New-Item -ItemType Directory -Force -Path 'C:/dsh/local-plugins' | Out-Null
git clone https://github.com/darkchaox/dsh-restart-control.git 'C:/dsh/local-plugins/dsh-restart-control'
dsh plugin --profile web add 'C:/dsh/local-plugins/dsh-restart-control'

Windows 本机手动启动 DSH 时，推荐使用默认的 auto，或在同一个 PowerShell 会话中明确使用 portable：

~~~powershell
$env:DSH_RESTART_CONTROL_MODE = 'portable'

执行你原本的 DSH 启动命令

如果 DSH 已由 Windows Service 或其他 Windows 服务管理器启动，请改用 external，并在该服务的环境设置中加入：

~~~text
DSH_RESTART_CONTROL_MODE=external

不要在 Windows Service 已配置自动重启时使用 portable；portable helper 与 Windows Service 可能同时拉起 DSH。

更新插件

Linux、macOS：

~~~sh
git -C /home/dsh/local-plugins/dsh-restart-control pull --ff-only
dsh plugin --profile web add /home/dsh/local-plugins/dsh-restart-control

Windows PowerShell 7：

~~~powershell
git -C 'C:/dsh/local-plugins/dsh-restart-control' pull --ff-only
dsh plugin --profile web add 'C:/dsh/local-plugins/dsh-restart-control'

更新后请使用 DSH 原本的启动方式重启一次。重新整理 DSH Web 设置页；若侧栏没有立即出现新项目，请使用 Ctrl + F5 清除旧的 client bundle cache。

使用方式

1. 打开 DSH Web 的设置页。
2. 找到「重启 DSH」区块，先按「重启 DSH」。
3. 确认当前所有 Web 连接会短暂中断，再按「确认重启」。
4. 插件保存 scheduled 状态后，会依重启模式退出或启动 portable helper。
5. 等待 DSH 重新连接。UI 会在最多 60 秒内轮询服务状态。
6. 只有新的 DSH 进程完成启动并回报新的 bootId，画面才会显示「重启成功」。

重启期间请不要重复提交请求。宿主端有 10 秒冷却时间，用于避免连续重启。

外部服务管理器设置

systemd

systemd 服务需要具备自动重启策略，例如 Restart=on-failure。可先检查：

~~~sh
systemctl show deepseek-harness.service --property=Restart

预期输出：

~~~text
Restart=on-failure

插件在 systemd 下使用 external，以 exit code 75 結束，讓 systemd 依服務單元設定重新拉起 DSH。若服務不是 systemd 啟動，請不要只套用 systemd 指令，改用對應的管理器日誌與重啟設定。

PM2、Docker、Windows Service

這些管理器都應使用 external。核心要求是：管理器要把 DSH 的 exit code 75 視為需要重新啟動的結束狀態。

Docker Compose 的環境設定可參考：

~~~yaml
services:
dsh:
environment:
DSH_RESTART_CONTROL_MODE: external
restart: on-failure

PM2、Windows Service 或其他管理器請在其服務環境中設定 DSH_RESTART_CONTROL_MODE=external，並確認既有的「進程異常退出後重啟」策略已啟用。插件不會替你修改這些管理器的設定。

故障排查

畫面顯示「重啟超時」

這表示 Web UI 在 60 秒內沒有等到新的 DSH 進程。請先確認你使用的重啟模式：

- 手動啟動的 Windows、macOS 或 Linux：確認 DSH_RESTART_CONTROL_MODE 是 auto 或 portable，並確認原本的 DSH 啟動命令仍可正常執行。
- systemd、PM2、Docker、Windows Service 或其他管理器：確認設定為 external，且管理器確實會在 exit code 75 後重新啟動 DSH。
- 不要在外部管理器已經自動重啟時使用 portable，避免同時出現兩個 DSH 進程。

接著查看對應啟動程序的日誌：

- systemd：journalctl -u deepseek-harness.service -n 100 --no-pager
- Docker：查看容器 logs 及容器的 restart status。
- PM2：查看 PM2 process log 與 process status。
- Windows Service：查看 Windows Event Viewer 或該服務管理器的日誌。
- 手動啟動：查看啟動 DSH 的 PowerShell、終端機或程序日誌。

畫面顯示「重啟失敗」

常見原因包括：

- 請求超過 10 分鐘有效期，或 requestedAt 不是有效的 ISO 8601 時間。
- 距離上次重啟不足 10 秒，觸發冷卻保護。
- DSH settings service 無法保存 scheduled 或 failed 狀態。
- 上一個進程在保存 scheduled 前就中斷，插件因此不會在新進程中自動重試。
- portable helper 無法啟動，或原本的 executable、參數、工作目錄已不再可用。

請先查看 UI 顯示的 message，再檢查 DSH 日誌與啟動程序設定。

Windows 出現重複進程

這通常表示 Windows Service 或其他管理器已負責自動重啟，但模式仍為 portable 或 auto。在服務管理器的環境設定中加入：

~~~text
DSH_RESTART_CONTROL_MODE=external

然後停止重複的 DSH 進程，只保留一個由服務管理器管理的實例，再重新啟動服務。

設定頁沒有出現插件

請依序確認：

1. 插件已加入 web profile，而不是其他 profile。
2. dsh plugin --profile web add 使用的是包含 package.json 與 cordis.patch.yml 的插件根目錄。
3. 已使用 DSH 原本的方式重新啟動 DSH。
4. 瀏覽器已使用 Ctrl + F5 重新載入 client bundle。
5. DSH 日誌沒有顯示 peer dependency 或插件載入錯誤。

發布披露

此插件不把資料傳送到外部雲端，也不需要 API key、Token 或其他外部憑據。以下資訊與 package.json 的 disclosure 欄位保持一致：

- 雲端依賴： 否；network 為空陣列，插件不主動連線到外部端點。
- 離線模式： 是；插件只透過 DSH 自身的 settings 與 Web RPC 工作，不依賴外部網路服務。
- 憑據處理： 不讀取、儲存或寫入 API key、Token、密碼或其他秘密，也不會把秘密寫入日誌。
- 環境變數： 只讀取 DSH_RESTART_CONTROL_MODE，並把它限制在 auto、portable、external 及相容別名 systemd。
- 進程權限： 重啟請求通過驗證且狀態保存成功後，插件以 exit code 75 結束自身進程；portable 模式另外啟動固定用途的 restart-helper。helper 只使用宿主提供的 executable、參數、工作目錄與環境，不使用 shell。
- 檔案系統： 插件不直接讀寫檔案；重啟狀態由 DSH settings service 持久化，helper 只負責等待與重新啟動進程。
- DSH settings： 只讀寫 dsh-restart-control namespace 的固定狀態欄位。
- 法域標籤： 未宣稱特定法域；本項不構成法律意見。
- 資料保留： server；只保留重啟流程狀態，不保留使用者對話內容。狀態清理方式請參考「回滾」章節。

檔案結構

~~~text
dsh-restart-control/
├── cordis.patch.yml # 將插件加入 web profile 的 Cordis patch ├── package.json # 插件 metadata、peer dependencies 與 disclosure ├── README.md # 本說明文件 └── src/ ├── client.js # DSH Web 設定頁 bundle ├── host.mjs # DSH 宿主端狀態機與重啟策略 └── restart-helper.mjs # 跨平台 portable 重啟輔助程序

開發與驗證

本插件沒有額外的 build script；宿主端與 Web client 由 DSH 的插件載入流程直接使用。提交變更前，可以使用 Node.js 進行基本語法與打包檢查： ~~~powershell
node --check .\src\host.mjs
node --check .\src\client.js
node --check .\src\restart-helper.mjs
npm pack --dry-run --json --ignore-scripts

也可以用相同的 Node major version 启动一个短暂测试进程，验证 helper 会等父进程退出后再拉起指定进程；不要直接对正在运行的正式 DSH 实例做重启测试。

插件的 runtime dependencies 由 DSH 执行环境提供，请不要把 DSH 的配置档、服务密钥或本地主机数据提交到仓库。

回滚

移除插件后，请用 DSH 原本的服务管理方式重启：

~~~powershell
dsh plugin --profile web remove dsh-restart-control

使用原本的 DSH 启动命令或服务管理器重新启动

Linux systemd 可以用：

~~~sh
sudo systemctl restart deepseek-harness.service

移除插件不会删除其他 settings namespace。若要清理插件留下的状态，请先确认不再需要重启记录，再由 DSH 设置页或受控的配置档维护流程移除 dsh-restart-control 分节。

许可证

本项目采用 MIT License。