# dsh-server-deck 中文文档

规范地址：https://npmcn.com/package/dsh-server-deck/

版本：0\.5\.0
npm 元数据更新时间：2026-11-03T11:38:49.874Z
中文译文更新时间：2026-11-03T15:34:03.481Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dsh-server-deck
原文对照：https://npmcn.com/package/dsh-server-deck/?lang=original
项目主页：https://github.com/meyaomiao/dsh-server-deck#readme
源码仓库：https://github.com/meyaomiao/dsh-server-deck

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：826 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：@deepseek-ai/dsh-tools ^0\.2\.1-rc\.5，@deepseek-ai/dsh-system-prompt ^0\.2\.1-rc\.5，@deepseek-ai/dsh-host-webserver ^0\.2\.1-rc\.5，@deepseek-ai/dsh-client-connection ^0\.2\.1-rc\.5
- 首次发布：2026-08-26T10:21:31.504Z
- 最新版本发布：2026-11-03T11:38:49.722Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

DSH 能力插件:服务器卡片仪表盘——实时状态/CPU/内存/磁盘 + 趋势记录与可视化(1h/24h/7d/30d) + 点卡片进入 xterm 交互终端

## 安装

```sh
npm install dsh-server-deck
```

也可以使用：`pnpm add dsh-server-deck`、`yarn add dsh-server-deck`、`bun add dsh-server-deck`

## README

# DSH Server Deck 🖧

**DeepSeek Harness 的服务器卡片仪表盘** —— 已连接服务器的卡片视图(在线状态 / CPU / 内存 / 磁盘 / 延迟),点卡片进入 xterm.js 交互终端;独立趋势视图记录并可视化一段时间的 CPU / 内存 / 磁盘变化。

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com/) [![dsh-plugin](https://img.shields.io/badge/dsh-plugin-4d6bfe)](https://github.com/topics/dsh-plugin) [![npm](https://img.shields.io/npm/v/dsh-server-deck)](https://www.npmjs.com/package/dsh-server-deck) [![license](https://img.shields.io/badge/license-MIT-green)](https://npmcn.com/package/dsh-server-deck/LICENSE)

## 🤝 合作伙伴：米云

[![米云 MIYUN · 多模型 AI API 聚合平台 momotoken.win](https://npmcn.com/package/dsh-server-deck/docs/assets/miyun-banner.png)](https://momotoken.win/)

**[米云 MIYUN](https://momotoken.win/)** —— 多模型 AI API 聚合平台：稳定不降智，模型上线快又多；统一 API 接入、按量使用、余额集中管理。

## ⭐ 欢迎点星收藏

如果 server-deck 帮到了你，欢迎到 [GitHub 仓库](https://github.com/meyaomiao/dsh-server-deck) 点个 Star ⭐，让更多 DSH 用户看到它。问题与建议请提 Issue。

## 📋 兼容性

| 插件版本 | 状态 | 对应 DSH |
| --- | --- | --- |
| **0.5.x**（当前主线） | ✅ | **0.2.1-rc.5 起的 0.2.1 线**；使用官方 Connection 鉴权与桌面 WebSocket transport，发版验证覆盖 `0.2.1-rc.5` |
| 0.3.x / 0.4.x | 历史版本 | 旧 DSH 原生右侧栏；建议同时升级 DSH 和插件，以获得本次终端及鉴权修复 |
| 0.2.x | 历史版本 | DSH ≤ 0.1.2-rc.1；better-sidebar 页签或独立抽屉 |

### 本次升级功能变化

-   **导入先预览再确认**：先扫描 SSH 配置，查看候选、已有项及跳过原因，再勾选确认；需要的跳板依赖一起导入，取消不改台账。
-   **跳板机**：手工配置与 SSH 配置导入支持 ProxyJump 链，校验缺失引用、自指和环；更新或删除跳板会让依赖连接按新配置重建。
-   **终端与鉴权**：终端通过 DSH 官方 Connection 选择桌面/浏览器传输；REST 和 PTY 都检查宿主认证、Host 与 Origin，保留仅回环的访问范围。
-   **升级要求**：先将 DSH 升级到 `0.2.1-rc.5` 或更新的 0.2.1 版本，再更新插件并重启宿主。无法确认鉴权能力的旧宿主会关闭插件的网络入口。

![服务器卡片仪表盘](https://npmcn.com/package/dsh-server-deck/docs/screenshots/dashboard.png)

## ✨ 功能一览

### 卡片式服务器仪表盘

每台服务器一张卡,**状态一目了然**:

| 元素 | 说明 |
| --- | --- |
| 🟢🟡🔴⚪ 状态点 | 在线(带呼吸光晕)/ 离线 / 探测中 / 未知 |
| 系统信息行 | OS 名称(Linux PRETTY\_NAME / macOS / Windows Caption / BSD uname)、运行时长、核数、握手延迟 |
| 三条用量条 | CPU · 内存 · 磁盘,<60% 绿 / ≥60% 黄 / ≥85% 红 |
| 网速 / 本月 | 实时 ↓接收 / ↑发送(Linux 约 1s,其它系统取相邻采集点均值);本机日历月累计流量。跳过 lo / docker / veth 等虚拟口 |
| 错误详情 | 离线时内联展示失败原因(悬停看全文) |

自动刷新周期可选 **手动 / 10s / 15s / 30s / 60s**(读主机侧快照,不再现场 SSH);「刷新」按钮强制立即探测一轮。

### 📈 趋势视图

卡片与趋势两个独立视图互相切换(不是叠在卡片里)。每台主机 **CPU / 内存 / 磁盘各一张独立图**(不叠线):

| 项 | 说明 |
| --- | --- |
| 窗口 | 1 小时(滚动,默认)/ 24 小时(滚动)/ 一周 / 一个月(本地自然日 0 点起,含今天)/ 自定义(≤31 天) |
| 粒度 | 自动 / 10s / 30s / 1m / 5m / 15m / 1h;单次查询上限 1200 点,超限自动升档 |
| 摘要 | 最新值 + 窗口均值;悬停竖线读该时刻数值,tooltip 含最高 / 最低 / 样本数 |
| 采集 | 主机侧常驻,默认 10s(可选 30s / 1m / 5m),与面板是否打开无关;离线也记一条用于画断档 |
| 落盘 | `~/.dsh/server-deck-metrics/{hostId}/`:raw 3h、1m 24h、15m 7d、1h 31d、`net-month.json` 当月流量;删除主机级联清理 |
| 历史回填 | 窗口早于本地记录时,尝试 `sar -u` / `sar -r`(sysstat)回填 CPU / 内存;磁盘容量无法回填 |

打开「服务器」页签 → 点工具栏「📈 趋势」。窗口默认 1 小时滚动;「24 小时」也是滚动过去 24 小时,不是当天 0 点起。刚启用时图上可能只有右侧一小段,等几个采集周期就会铺开。

![趋势视图:每机三张独立 CPU / 内存 / 磁盘图](https://npmcn.com/package/dsh-server-deck/docs/screenshots/trend.png)

### ⌨ 点卡片进交互终端

xterm.js 全功能终端:5000 行回滚、256 色、窗口尺寸实时同步、光标闪烁。Node 半区做 WebSocket ↔ ssh2 shell 双向桥。

![交互终端](https://npmcn.com/package/dsh-server-deck/docs/screenshots/terminal.png)

### ⤓ 一键导入 `~/.ssh/config`

解析标准 ssh config(Host / HostName / User / Port / IdentityFile / ProxyJump)。点击「导入」后先显示候选预览，勾选并确认后才写入台账：

-   标明通配条目、缺少用户名、已存在项与无效配置的处理原因；
-   跳过 Git 托管平台密钥别名(如 `Host github.com-xxx` / `User git`)；
-   多别名行(`Host 1.2.3.4 prod-gw`)优先取语义化别名做展示名；
-   自动包含选中主机需要的跳板；已有主机可经确认补齐缺失关联，冲突或循环不会静默变成直连；
-   检测后配置发生变化时要求重新预览，避免确认与实际写入不一致。

`Include`、`Match` 与通配默认值不会自动展开，预览会说明这些限制；无法表达的连接配置显示原因并禁选。

![导入 SSH 配置：候选预览、跳过原因与勾选确认](https://npmcn.com/package/dsh-server-deck/docs/screenshots/import-preview.png)

### ＋ 手动添加主机

密码 / 私钥文件(+口令)/ SSH Agent 三种认证;可选台账里的另一台主机作跳板机(跳板机使用自己的认证);连接测试按钮即时反馈延迟。

![添加服务器表单](https://npmcn.com/package/dsh-server-deck/docs/screenshots/add-host.png)

## 🔀 三种挂载方式

| 环境 | 形态 |
| --- | --- |
| DSH 提供官方原生右侧栏 | 优先注册「服务器」原生页签 |
| 原生栏不可用且安装 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) | 注册侧边栏「服务器」页签，按可见状态刷新 |
| 两种页签均不可用 | 独立右侧面板，支持展开/收起与拖动宽度 |

官方侧栏与可选 better-sidebar 通过动态子插件等待；页签就绪时自动收起独立面板，避免双入口。客户端声明 `slots` 和 `connection` 服务。

## 📦 安装

```bash
# 方式〇:npm 安装(推荐)
dsh plugin --profile web add dsh-server-deck

# 方式一:从 GitHub 直接装(dsh CLI,免 npm)
dsh plugin --profile web add github:meyaomiao/dsh-server-deck

# 方式二:克隆后本地挂载
git clone https://github.com/meyaomiao/dsh-server-deck.git
cd dsh-server-deck && pnpm install && pnpm build
dsh plugin --profile web add .
```

安装后**重启 `dsh web`**(host 半新增了路由与常驻采集器),浏览器 Ctrl+F5 强刷。侧边栏「+」菜单出现「服务器」页签即成功。

## 🔐 安全模型

-   所有 API 与 PTY 升级路由通过 DSH Connection 检查已认证 cookie、Host 与 Origin，并额外仅允许回环地址(127.0.0.1/::1)；缺少宿主鉴权 API 时返回不可用，不降为匿名访问；
-   密码 / 私钥口令单独存放 `~/.dsh/server-deck.secrets.json`(0600),台账文件不含秘密,**API 响应永不回传**;
-   删除主机仅移出台账并断开连接池,不会在远端执行任何操作;
-   对话工具 `server_deck_hosts` / `server_deck_exec` 走同一条 SSH 连接池做非交互下发,不经过卡片 xterm,也不暴露成浏览器 REST;
-   指标采集：Linux / macOS / BSD 走只读 POSIX sh 探针（固定交给 `/bin/sh`，不经过登录壳；Linux 读 `/proc`，FreeBSD/OpenBSD 读 `sysctl`，macOS Darwin 回退）。Windows OpenSSH 无 sh 时再跑一次 `powershell.exe -EncodedCommand`（CIM）。解析失败的字段显示「—」。

## 🏗️ 架构

```
┌─ Client(lib/client.js)──────────────────┐   ┌─ Host(lib/index.js)─────────────────────┐
│ 官方原生栏/better-sidebar 页签 ⇄ 独立抽屉 │◄──│ /server-deck/api/*  REST(仅回环)         │
│ React 卡片网格 / 趋势图 / 表单 / xterm.js │WS▶│ /server-deck/ws/pty ws↔ssh2 PTY 桥      │
└─────────────────────────────────────────┘   │ ssh2 连接池 · 台账 ~/.dsh/*.json         │
                                              │ MetricRecorder 常驻采集(默认 10s)        │
                                              └─────────────────────────────────────────┘
```

## 🛠️ 开发

```bash
pnpm install
pnpm build       # esbuild:server bundle + client bundle(ModuleLoader 包装)
pnpm typecheck   # tsc --noEmit
pnpm test        # 单元、HTTP/WS 鉴权、真实 SSH 跳板和回归测试；Node 20/22/24
pnpm exec playwright install chromium
pnpm test:ui     # 真实 React/xterm 浏览器布局与导入确认交互
```

核心发版链路见 [docs/core-flows.md](https://npmcn.com/package/dsh-server-deck/docs/core-flows.md)。

改仓库前先读 [CONTRIBUTING.md](https://npmcn.com/package/dsh-server-deck/CONTRIBUTING.md)（Issue → 分支 → Draft PR）。思考原则见 [AI-ISSUE-WORKFLOW.md](https://npmcn.com/package/dsh-server-deck/AI-ISSUE-WORKFLOW.md)。

## License

[MIT](https://npmcn.com/package/dsh-server-deck/LICENSE)

## 常见问题

### dsh-server-deck 是什么？

DSH 能力插件:服务器卡片仪表盘——实时状态/CPU/内存/磁盘 \+ 趋势记录与可视化\(1h/24h/7d/30d\) \+ 点卡片进入 xterm 交互终端

### 如何安装 dsh-server-deck？

在项目目录运行 npm install dsh-server-deck，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/dsh-tools（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-system-prompt（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-host-webserver（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-client-connection（^0\.2\.1-rc\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### dsh-server-deck 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dsh-server-deck 是否存在。

### dsh-server-deck 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dsh-server-deck 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### dsh-server-deck 可以商用吗？

dsh-server-deck 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-server-deck 还在维护吗？

最新版本 0\.5\.0 发布于 2026/11/03（今天）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。