📦 @goodandready/dsh-server-monitor

---

适用于 DeepSeek Harness 侧边栏的独立、只读 Linux 服务器监控插件。插件自行管理服务器配置和凭据，不依赖 dsh-remote-workspace，也不会复用其他插件的连接配置。

MVP 范围

• 添加和管理 Linux、macOS、BSD 和 Windows OpenSSH 的 SSH 配置。
• 支持 SSH 私钥（内联内容或 DSH 主机上的密钥路径）以及密码认证。
• 直接在 UI 中生成 Ed25519 SSH 密钥对，提供一键复制的目标服务器部署命令并支持立即测试连接。
• 显示主机、CPU、内存、交换空间、磁盘、进程、容器、网络和监听端口的当前状态。
• 侧边栏可见时每 15 秒刷新一次。
• 后台探测不会管理远程服务、进程或容器。最近一小时画成迷你图，操作者可以打开一个交互终端。

凭据边界

凭据由本插件独立管理，保存在 DSH 主机上的专属保险库中。在 POSIX 主机上，插件会设置并验证仅所有者可访问的 0600 权限；无法确保权限时会停止操作。UI 生成的私钥存储于 ~/.dsh/keys/id_ed25519_dsh，严格限制为 0600 权限（目录 0700）。密钥和私钥绝不写入 DSH 设置，也不会通过 API 返回给浏览器；配置接口只返回掩码和是否已保存的信息。私钥路径在 DSH 主机上读取。

开发测试

执行与 Gitea Actions 相同的检查：

npm ci
npm test

测试使用模拟 SSH 连接，不会连接真实服务器。Gitea Actions 会在推送和拉取请求时执行这些命令。

语言

界面内置英语和中文词典，并使用 DSH locale 服务，以便由 dsh-russian-lang 提供俄语翻译。另见 README.md 和 README.ru.md。

环境要求

• 已安装插件的 DSH web 配置，且 DSH 主机可通过 SSH 访问 Linux 服务器。
• 远程账户可运行常见只读系统命令；容器数据需要有权查询 Docker/Podman。
• 私钥路径必须指向 DSH 主机上可由 DSH 服务账户读取的文件。
• 运行依赖 (ssh2)：插件需要 ssh2 (^1.17.0) 运行时依赖（位于 dependencies，而非 peer）以管理 SSH 会话和生成 Ed25519 密钥对。通过包管理器安装插件时会自动拉取。
• 纯 JavaScript 回退（Pure JS Fallback）：DSH 主机上无需安装 C/C++ 编译器或 Python 构建工具链。虽然 ssh2 包含可选的原生加速模块（cpu-features、sshcrypto），但在缺少构建环境时会自动无缝回退到纯 JavaScript 实现。
• 离线环境部署（Air-Gapped）：若在离线网络环境中通过 .tgz 包安装，请确保预先在本地包管理器缓存或私有 npm 镜像中提供 ssh2 及其传递依赖项。

安装

将 web 替换为所用的 DSH 配置：

dsh plugin --profile web add @goodandready/dsh-server-monitor

按 CLI 提示操作。在插件设置卡片中添加服务器，选择密钥或密码认证，测试并保存，然后在侧边栏打开 Server Monitor。卸载：dsh plugin --profile web remove @goodandready/dsh-server-monitor。

配置参考

请在 DSH 设置卡片中管理配置。从 SSH 配置导入会读取 ~/.ssh/config，跳过通配和 git 主机，并让你选择要添加的主机。代理工具 server_monitor_hosts 和 server_monitor_exec 列出不含密钥的主机，并在 1–300 秒超时内执行一条非交互命令。设置仅包含连接元数据；不要将密码、私钥内容或口令写入设置或配置文件。

字段	类型	默认值	说明
profiles	数组	[]	本插件管理的 SSH 配置。
profiles[].id	字符串	自动生成	稳定配置 ID。
profiles[].name	字符串	空	显示名称。
profiles[].host	字符串	空	DSH 可访问的 Linux 主机。
profiles[].port	数字	22	SSH 端口。
profiles[].username	字符串	root	远程账户；建议限制权限。
profiles[].authType	字符串	key	key 或 password。
profiles[].privateKeyPath	字符串	空	DSH 主机上的可选密钥路径。
profiles[].shell	字符串	posix	posix 把探测脚本通过标准输入交给 /bin/sh -s。powershell 使用 powershell.exe -EncodedCommand。 没有 /proc/meminfo 时用 sysctl 采集 macOS 和 BSD。Windows 请选择 powershell。 Terminal 按钮打开仅限本机的 xterm 会话。
profiles[].tags	字符串列表	空	逗号分隔的标签。服务器列表可按一个标签和搜索文本过滤。
profiles[].proxyJump	字符串	空	另一个配置的 ID，或 user@host:port。连接经该跳板建立。
activeProfileId	字符串	空	活动配置 ID。
pollIntervalSec	数字	30	后台探测间隔：10、30、60 或 300。其他值使用 30。

秘密值保存在 DSH 主机上由插件管理的保险库中。POSIX 系统要求文件权限验证为仅所有者可访问（0600）。

SSH 密钥生成与跨插件共享

在设置卡片中，点击 生成 SSH 密钥 即可创建专属的 Ed25519 密钥对。私钥保存在 DSH 主机的 ~/.dsh/keys/id_ed25519_dsh（权限 0600）。界面会展示公钥以及用于粘贴到目标服务器的一行式部署命令。执行命令后，点击 已执行命令 — 测试连接 即可立即验证连接连通性。

该私钥路径也可直接配置到其他本地插件中（例如 dsh-remote-workspace），复用同一管理密钥而无需重复设置凭据。

采集内容

有界只读采集器获取主机/操作系统/内核/CPU、负载和运行时间、内存与 swap、文件系统使用情况、最多 12 个 CPU 占用靠前的进程、运行中的 Docker 或 Podman 容器、网络计数器以及在主机上测得的一秒接收/发送速率及 TCP/UDP 监听端口（使用 ss，否则回退到 netstat）。命令、运行时或权限不可用时，相应区块可能为空。服务器卡片显示最近的 SSH 错误和探测延迟（毫秒）。历史保存在插件指标目录中，包含原始、1 分钟、15 分钟和 1 小时样本。GET /dsh-server-monitor/history 按时间范围返回一个字段。主机安装了 sysstat 时，第一次成功探测会从 sar 复制前一天的 CPU 和内存。本月流量按 UTC 日历月累加字节差；重启后计数器回绕不会倒扣，下月 1 日重新开始。每张服务器卡片用 SVG 画出最近一小时的 CPU、内存和磁盘。间隔超过 90 秒的点会断开折线。已知 CPU 核数时，CPU 按核数换算成百分比保存。

架构

flowchart LR
  UI[DSH 侧边栏] --> Client[插件客户端]
  Client --> Routes[可信本地路由]
  Routes --> Settings[服务器配置]
  Routes --> Vault[凭据保险库]
  Routes --> SSH[SSH 服务]
  SSH --> Linux[只读 Linux 采集器]
  Linux --> Snapshot[当前快照]
  Snapshot --> Client

模块	职责
lib/index.js	Cordis 注册、设置集成和服务生命周期。
lib/client.js	侧边栏/设置界面；页面隐藏时暂停轮询。
lib/routes.js	可信请求校验、配置操作、快照缓存。
lib/profile.js	配置规范化和校验。
lib/vault-service.js	凭据保存及 POSIX 权限验证。
lib/ssh-service.js	SSH 认证、有界命令、连接复用和清理。
lib/linux-collector.js	快照解析和 Linux /proc 探测。
lib/snapshot-commands.js	macOS、BSD 和 Windows 的采集命令。
lib/pty-bridge.js	仅限本机的终端升级和 xterm 资源。
lib/agent-tools.js	列出主机并执行一条有界命令的代理工具。
lib/plugin-updater.js	版本检查以及在设置卡片中一键更新插件。

内部 HTTP 路由

这些路由只接受 loopback 客户端。Origin、Referer 和 Sec-Fetch-Site 只用于校验这台本机浏览器，不能让另一台机器通过。它们不是公开或远程管理 API。

方法	路径	用途
GET	/dsh-server-monitor/state	清理后的配置和所选 ID。
GET	/dsh-server-monitor/snapshot?profileId=<id>	当前快照；默认活动配置。
GET	/dsh-server-monitor/update	当前及最新版本状态。
POST	/dsh-server-monitor/update	通过 DSH CLI 执行一键插件在线更新。
POST	/dsh-server-monitor/profiles/save	新建/更新配置。
POST	/dsh-server-monitor/profiles/delete	删除配置、凭据、SSH 会话和本地指标文件。
POST	/dsh-server-monitor/profiles/active	选择活动配置。
POST	/dsh-server-monitor/keys/generate	在 ~/.dsh/keys 中生成 Ed25519 密钥对（权限 0600），并返回公钥与安装命令。
POST	/dsh-server-monitor/test	测试 SSH 连接。
GET	/dsh-server-monitor/history	一个配置和一个字段的历史采样。
GET	/dsh-server-monitor/profiles/import-ssh-config	本地 SSH 配置中的具体主机。
GET	/dsh-server-monitor/vendor/*	终端使用的 xterm 文件，仅限本机。
WebSocket	/dsh-server-monitor/pty	一个已保存主机的交互 shell，仅限本机。
POST	/dsh-server-monitor/containers/action	Docker/Podman 容器生命周期管理（启动、停止、重启）。
GET	/dsh-server-monitor/containers/logs	获取容器最新日志。
GET	/dsh-server-monitor/logs	查询系统 journalctl 日志（支持按服务与错误级别过滤）。
GET	/dsh-server-monitor/runbooks	获取运维脚本与运行手册列表。
POST	/dsh-server-monitor/runbooks/save	新建或更新运维脚本。
POST	/dsh-server-monitor/runbooks/delete	删除运维脚本。
POST	/dsh-server-monitor/runbooks/exec	在单台服务器或按标签批量执行脚本。
GET	/dsh-server-monitor/alerts/config	获取告警阈值及 Webhook URL 配置。
POST	/dsh-server-monitor/alerts/save	保存告警阈值及 Webhook 配置。
POST	/dsh-server-monitor/alerts/test	发送测试告警通知。
GET	/dsh-server-monitor/alerts/history	查看近期告警与异常事件历史。
GET	/dsh-server-monitor/files/read	通过 SSH 安全读取远程配置文件。
POST	/dsh-server-monitor/files/write	保存配置文件并自动生成 .bak 备份。

快照按配置缓存 15 秒，并发请求共享同一次采集；保存或删除会清除该配置缓存。

安全、支持与许可证

插件独立管理 SSH 凭据，不把秘密返回浏览器。后台探测是只读的。Terminal 按钮打开一个交互 SSH 会话，升级只接受本机 loopback。不包含告警。

• 问题和建议：GitHub Issues
• 许可证：MIT