dsh-service

English

面向自托管 DSH Web 的服务控制与运维插件。当前版本提供安全重启与自动恢复、更新提示、健康诊断、精确增量模型用量图表、容器探活、备份管理和 Linux 文件权限维护。

项目仍处于早期开发阶段。目前主要在 Linux + Docker 环境验证；重启后的自动拉起必须由 Docker、systemd、pm2 等外部进程管理器负责。

开发进度

阶段	状态	内容
当前版本 0.11.0	✅ 功能完成	版本链接、latest/next 更新检查、模型 tok 展示、备份导入、/restart 命令和权限修复交互已实现并通过自动化测试
v0.3 安全与体验	✅ 已实现	重启安全网、重启后自动恢复、更新脚标与详情浮层、zh+en 动态切换
v0.4 可观测性	✅ 已实现	健康面板、仅返回状态码的 /healthz 探活端点
v0.5 数据与维护	✅ 已实现	会话/配置/插件清单备份、备份列表与删除、Linux 文件权限查看与受控修复
v0.6 面板与用量	✅ 已实现	版本置顶、完整健康检查、精确增量模型统计、供应商/模型与项目筛选、可切换图表、折叠维护详情
v0.7 错误统计与界面	✅ 已实现	最近 24 小时模型/工具错误、路径归一化、默认折叠错误详情、卡片分区与语义按钮颜色
v0.8 标签式服务控制	✅ 已实现	概览、模型统计、备份维护、重启四标签；功能故障标签警告、顶部汇总提醒和高对比度展示面
v0.9 原生设置页风格	✅ 已实现	概览、健康诊断、模型统计、备份维护、重启五标签；线型导航、单层内容区和简化统计布局
v0.10 自动状态检查	✅ 已实现	DSH/插件独立版本状态与发布链接；更新检查成功缓存 10 分钟、失败缓存 1 分钟；健康标签自动诊断并缓存 30 秒

目前插件已在 DSH 0.1.0-rc.7 中完成开发与验证，可以正常使用。后续 DSH 发布新版本后，本项目会同步进行兼容性测试并更新验证结果。

当前功能

• 宿主版本：显示当前安装的 @deepseek-ai/dsh 版本。
• 自动更新状态：设置页打开时从固定 npm registry 地址独立读取 DSH 与插件的 latest 和 next dist-tag，按 semver 取两者最大值作为最新版，并在版本号旁同时展示两个标签；单项失败不会污染另一项，版本号本身链接到对应 GitHub Releases。Host 对成功/部分成功结果缓存 10 分钟，对完全失败结果缓存 1 分钟。
• 安全重启：重启前检测活跃 agent、后台 job 和终端；Terminal 服务按 Agent scoped realm 读取并兼容共享 fallback。发现运行中工作时展示清单并要求显式强制，随后以退出码 42 结束当前 DSH Web 进程。对话中也可输入 /restart；该命令复用活动检查，检测到运行中工作时直接拒绝，不绕过面板的两段式确认。
• 回环 RPC：使用单层 /dsh-service channel，提供 version、check-update、web endpoint，仅接受 loopback 调用。
• 自动恢复：重启后通过 shell.overlay 显示全局状态，退避探测新的进程实例并自动刷新；60 秒未恢复时提供手动刷新。
• 双语界面：设置页、活动警告和恢复浮层跟随 DSH 的中文/英文语言设置动态切换。
• 更新脚标：设置页打开时静默检查 DSH 更新；有新版本时在侧边栏底部显示提示，点击后通过全局浮层查看当前与最新版本。registry 不可达时不打扰用户。
• 健康面板与完整诊断：显示 uptime、内存 RSS、存活/持久化会话、活跃 Agent 和后台任务；轻量指标每 5 秒刷新。首次进入健康诊断标签会自动运行完整诊断，30 秒内切换回来复用结果，过期后再次进入自动刷新；保留「重新诊断」用于强制复查。完整诊断结果位于独立实底展示区，检查项始终展开；文件权限查看/深检/修复也位于此标签。结果会把内部计数转换为可读说明，例如「备份目录可用，当前暂无备份」或「发现 N 个文件或目录权限异常」。
• 精确模型用量图表：索引按 UTC 小时保存精确聚合，RPC 根据浏览器时区重新汇总为用户本地自然日，因此 Host 运行在 UTC 时，午夜后的「今天」也不会错误显示为 0。统计包含成功模型步骤、输入 tok、输出 tok、缓存 tok 和缓存命中率，可切换全部项目或单个工作区，并以 provider/model 展示供应商前缀。首次索引顺序读取历史会话，以后用会话 revision 和 lastSeq 只折叠新增事件；索引不保存消息、Prompt 或 Tool 内容。
• 续聊与 Fork 口径：恢复旧会话沿用同一 session ID，因此后续产生的 tok 会按实际日期增量补入且不会重复；Fork 会跳过 seedLength 以内继承的父会话历史，Subagent 默认计入其实际项目。
• 模型报错统计：从 llm/retry 与最终失败回合中提取 provider 错误，按 provider/model + code + HTTP status 归类，只保留滚动最近 24 小时并按次数从高到低排列；取消、最大 tok 和 Tool 错误不计入。详情默认折叠、跟随项目筛选，并集中放在概览区域。
• 工具报错统计：统计直接 Tool 调用和 run_code 内子调用产生的失败，包括命令、读取、写入、编辑与搜索错误。优先使用稳定 error.code，缺失时归一化为 FS_NOT_OBSERVED、OLD_STRING_NOT_FOUND、PATH_NOT_FOUND、命令退出码等稳定口径；不同文件路径合并计数，索引和界面只保存/展示 <path> 级脱敏代表信息。只保留最近 24 小时、按次数降序、默认折叠、跟随项目筛选，并与模型报错一起显示在概览区域。
• 五标签服务控制：设置页拆分为「概览」「健康诊断」「模型统计」「备份维护」「重启」五个线型标签，采用接近 DSH 原生设置页的下划线选中态和单层内容区，减少嵌套背景框。展示面、文字、边框、标签和状态色全部使用 DSH 原生明暗主题令牌；普通操作使用中性填充，创建备份等主要操作使用品牌色填充，修复/删除/重启使用白字危险色填充。概览包含版本、更新、容器运行指标，以及带有「报错信息」标题的最近 24 小时模型/工具报错；完整诊断及文件权限检查/修复独立放入健康诊断。
• 简化模型统计布局：项目切换使用线型小标签，主图固定为近 7 天输入/输出/缓存 tok 堆叠柱图，并用蓝/橙/青图例区分结构。图表带有 K/M 缩写的纵轴刻度、贴近图表底部的横轴日期基线和低对比度网格线；鼠标移入任一颜色区段时，统一显示日期、输入 tok、输出 tok 和缓存命中 tok，并按四行换行。模型明细按近 7 天步骤数降序，格式为「x次· 缓存命中 x%· 输入 xM tok· 输出 xM tok」，默认只显示前三，其他模型通过 ▸ 展开并以 ▾ 收起。
• 功能故障提醒：健康/权限、统计 RPC、备份操作或重启流程发生功能故障时，对应标签显示 ⚠，并在服务控制顶部汇总受影响标签。概览本身不承载健康故障标记；没有备份不算故障；最近 24 小时的模型报错和工具报错属于统计数据，也不会触发标签或顶部提醒。
• 外部存活探针：GET / HEAD /healthz 返回空的 HTTP 200；其他方法返回 405，不暴露版本、计数或其他 DSH 信息。它适合供另一台服务器上的 Uptime Kuma、Docker、Kubernetes 或其他监控程序检查 DSH Web 进程和 HTTP 服务是否仍可达；未配置外部消费者时不会自行产生作用，也不替代面板中的完整健康诊断。若 DSH 仅监听 127.0.0.1，应通过现有 Nginx/Caddy/Traefik 反向代理暴露该路径，不建议直接开放 3080 端口。
• 备份管理：在 $DSH_HOME/backups/ 创建会话、配置和插件 profile 清单归档；按日期从新到旧列出，10 条以内直接展示，超过 10 条才折叠。每条记录都有右侧删除按钮，支持选择 .tar.gz 文件导入；删除仍需两段式确认。备份不限份数且不会自动清理，磁盘占用由用户自行管理；归档不包含凭据或 node_modules。
• Linux 文件可编辑性：打开面板时在健康诊断中检查当前 DSH/Agent 进程能否读取、写入并进入 DSH_HOME 与全部工作区根目录；手动深检递归验证同一实际访问能力，而不是要求固定的 755/644，因此 700/600 等只要 Agent 可编辑就不会误报。.git 内部元数据不属于 Agent 直接编辑目标，深检与修复均跳过。嵌套工作区只随最外层根扫描一次。修复仍需两段式确认：递归恢复当前进程属主，目录只增加 owner rwx，普通文件只增加 owner rw，不会删除执行位或放宽 group/other 权限；$DSH_HOME/.credentials.yaml 最后固定为 600，以满足 DSH 启动契约。非 Linux 不显示此功能。
• 生命周期清理：优先使用 DSH timer 服务延迟退出与调度恢复探测，使未完成的定时动作可随插件 Fiber 清理。

安装

从 GitHub 安装

dsh plugin --profile web add github:gehennawu/dsh-service

安装或更新后重启 DSH Web，使 Host 与 Client 两半插件重新加载：

dsh web

打开 DSH Web 设置页，进入 服务控制。

本地开发安装

dsh plugin --profile web add link:/path/to/dsh-service

自动重启配置

插件只发送退出信号，不负责重新启动进程。没有进程管理器时，点击重启会直接停止 DSH Web。

Docker Compose

services:
  dsh:
    restart: unless-stopped

systemd

[Service]
ExecStart=/usr/local/bin/dsh web --host 127.0.0.1
Restart=on-failure
RestartSec=2

pm2

pm2 start "dsh web --host 127.0.0.1" --name dsh-web

平台支持

环境	插件功能	重启后自动拉起	验证状态
Linux + Docker Compose	支持	配置 restart policy 后支持	已验证
Linux + systemd / pm2	预期支持	由进程管理器负责	未单独验证
macOS / Windows + pm2 等	代码未限制	由进程管理器负责	未验证
直接运行 dsh web	支持	不支持	预期行为

运行要求：Node.js >=22，且 DSH Web 能加载 Host 和 Client 两半插件。检查更新需要访问 registry.npmjs.org；网络失败不会影响其他功能。

自动化测试以及当前 Linux + Docker 的 Host/真实 Chromium 验证已完成。当前 standard preset 未挂载 Terminal backend，容器也不提供 root、CAP_CHOWN、Docker socket 或 user namespace，因此这两种不可制造的环境分支通过隔离服务回归测试和真实 subprocess 临时目录测试覆盖。

安全设计

• 浏览器端不能传入 URL、包名、命令或文件路径。
• 更新检查只访问固定的 https://registry.npmjs.org/@deepseek-ai%2Fdsh 与 https://registry.npmjs.org/@gehennawu%2Fdsh-service。
• npm 响应限制为 256 KiB，请求超时为 10 秒。
• RPC channel 仅注册为 loopback，不对外部网络开放控制接口。
• 模型用量索引仅保存 session revision/watermark、按日期/项目/provider/model 聚合的数字，以及最近 24 小时脱敏错误的稳定 code、计数、时间戳和 <path> 代表信息；不保存消息、Prompt、Tool 参数、原始文件路径、密码、私钥或其他凭据。索引固定写入 $DSH_HOME/dsh-service-usage-index.json 并使用 0600 权限。
• 重启会中断正在运行的任务；插件会先展示活动清单，只有显式确认「仍要重启」才会强制执行。

项目结构

• index.js：Host 半；版本/更新、活动保护、健康指标与诊断、增量用量索引、探活、备份和权限维护 RPC。
• client.js：Browser 半；设置页布局、可切换用量图表、更新脚标和全局状态浮层。
• cordis.patch.yml：将 Host 与 Client 插件插入 DSH Web profile。
• README.en.md：英文文档。

基础检查：

npm test
node --check index.js
node --check client.js
npm pack --dry-run

许可证

MIT