dsh-service

English

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

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

开发进度

阶段	状态	内容
当前版本 0.10.0	✅ 功能完成	双版本自动更新状态、缓存检查和进入健康标签自动诊断已实现并通过自动化测试
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 与插件版本状态，单项失败不会污染另一项。当前 @gehennawu/dsh-service 尚未发布到 npm，HTTP 404 会明确显示「尚未发布可检查版本」，DSH 仍可正常显示是否最新；两者均提供发布记录链接。Host 对成功/部分成功结果缓存 10 分钟，对完全失败结果缓存 1 分钟。
• 安全重启：重启前检测活跃 agent、后台 job 和终端；Terminal 服务按 Agent scoped realm 读取并兼容共享 fallback。发现运行中工作时展示清单并要求显式强制，随后以退出码 42 结束当前 DSH Web 进程。
• 回环 RPC：使用单层 /dsh-service channel，提供 version、check-update、web endpoint，仅接受 loopback 调用。
• 自动恢复：重启后通过 shell.overlay 显示全局状态，退避探测新的进程实例并自动刷新；60 秒未恢复时提供手动刷新。
• 双语界面：设置页、活动警告和恢复浮层跟随 DSH 的中文/英文语言设置动态切换。
• 更新脚标：设置页打开时静默检查 DSH 更新；有新版本时在侧边栏底部显示提示，点击后通过全局浮层查看当前与最新版本。registry 不可达时不打扰用户。
• 健康面板与完整诊断：显示 uptime、内存 RSS、存活/持久化会话、活跃 Agent 和后台任务；轻量指标每 5 秒刷新。首次进入健康诊断标签会自动运行完整诊断，30 秒内切换回来复用结果，过期后再次进入自动刷新；保留「重新诊断」用于强制复查。完整诊断结果位于独立实底展示区，检查项始终展开；文件权限查看/深检/修复也位于此标签。结果会把内部计数转换为可读说明，例如「备份目录可用，当前暂无备份」或「发现 N 个文件或目录权限异常」。
• 精确模型用量图表：按 Host 本地自然日统计成功模型步骤、输入 Token、输出 Token、缓存 Token 和缓存命中率，可切换全部项目或单个工作区，并以 provider/model 展示供应商前缀。首次索引顺序读取历史会话，以后用会话 revision 和 lastSeq 只折叠新增事件；索引不保存消息、Prompt 或 Tool 内容。
• 续聊与 Fork 口径：恢复旧会话沿用同一 session ID，因此后续产生的 Token 会按实际日期增量补入且不会重复；Fork 会跳过 seedLength 以内继承的父会话历史，Subagent 默认计入其实际项目。
• 模型报错统计：从 llm/retry 与最终失败回合中提取 provider 错误，按 provider/model + code + HTTP status 归类，只保留滚动最近 24 小时并按次数从高到低排列；取消、最大 Token 和 Tool 错误不计入。详情默认折叠并跟随项目筛选。
• 工具报错统计：统计直接 Tool 调用和 run_code 内子调用产生的失败，包括命令、读取、写入、编辑与搜索错误。优先使用稳定 error.code，缺失时归一化为 FS_NOT_OBSERVED、OLD_STRING_NOT_FOUND、PATH_NOT_FOUND、命令退出码等稳定口径；不同文件路径合并计数，索引和界面只保存/展示 <path> 级脱敏代表信息。只保留最近 24 小时、按次数降序、默认折叠并跟随项目筛选。
• 五标签服务控制：设置页拆分为「概览」「健康诊断」「模型统计」「备份维护」「重启」五个线型标签，采用接近 DSH 原生设置页的下划线选中态和单层内容区，减少嵌套背景框。普通操作统一使用中性实底和细边框，创建备份等主要操作使用低饱和品牌描边，修复/删除/重启默认使用浅红危险描边，只有最终确认使用实心红。概览只放版本、更新和现有容器运行指标；完整诊断及文件权限检查/修复独立放入健康诊断。
• 简化模型统计布局：项目切换使用线型小标签，主图固定为近 7 天输入/输出/缓存 Token 堆叠柱图，并用蓝/橙/青图例区分结构。图表带有 K/M 缩写的纵轴刻度、横轴日期基线和低对比度网格线；鼠标移入颜色区段会高亮该区段，并在鼠标旁显示日期、类型和精确 Token 数。图表、图例、今日/近 7 天摘要、缓存命中率和 provider/model 排行位于同一个连续统计区域；今天与近 7 天都统一显示输入、输出、缓存 Token、成功步骤和缓存命中率。模型明细按近 7 天步骤数降序，默认只显示前三，其他模型通过 ▸ 展开并以 ▾ 收起。折叠错误区域继续使用留白与分隔线组织。
• 功能故障提醒：健康/权限、统计 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 清单归档；列表默认折叠，可查看文件名、大小、时间和总体积，并通过两段式确认删除。备份不限份数且不会自动清理，磁盘占用由用户自行管理；归档不包含凭据或 node_modules。
• Linux 文件权限：打开面板时在健康卡片内自动浅检查 DSH_HOME 与全部工作区根目录并直接显示异常摘要，路径详情默认折叠；手动深度检查递归扫描属主、目录 755、普通文件 644，对 $DSH_HOME/.credentials.yaml 则按宿主凭据插件的真实契约要求 group/other 权限位为零（仅所有者可读写；0400/0600 等 owner-only 形式均合规，并非必须恰好 600），且该例外只作用于这一个文件，不作用于工作区里的同名文件。嵌套工作区（如 /workspace 与其子目录同时注册）只按外层根扫描一次，不重复计数。修复仍需两段式确认，先处理一般目录/文件，再显式恢复凭据文件 600，避免 DSH 凭据插件因权限过宽而拒绝启动。非 Linux 不显示此功能。容器内若以 root 运行 DSH，目标仍是 root，因此该修复不能降权为普通用户。
• 生命周期清理：优先使用 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。
• 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