# 🖥️ 服务器看板 · dsh-server-dashboard

在 DSH Web 中通过 SSH 集中查看多台 Linux 服务器的 GPU、进程、系统资源和训练日志。适合同时维护多个实验、需要快速定位空闲显卡或异常任务的研究工作流。

可独立使用；安装研究主线图后，可将实验节点关联到主机、日志和命令特征。插件执行读取状态和日志的远端命令，不提供启动训练、杀进程或修改远端文件的操作。

## 看板与资源总览

- 每台主机一张卡片，展示 GPU 利用率、显存、温度、功耗和占用进程，以及 CPU、内存、磁盘和负载。
- GPU 热力总览支持点击定位主机和显卡；查看进程用户与采样命令行，帮助区分实验。
- 主机可固定常驻，或收起到“其他服务器”；异常状态通过卡片、徽章和总览提示。
- 支持停靠、浮动和右侧栏 GPU 入口，适应不同工作区布局。
- 无 GPU 或驱动不可用时，仍可展示能够读取的 CPU、内存和磁盘信息。

## 训练日志与曲线

可手动指定日志，也可以在设置页发现候选：检查进程输出重定向、命令行和工作目录。每张 GPU 还会尝试根据关联进程查找日志。自动发现受文件权限及训练程序写日志方式影响，找不到时可以手动配置。

支持常见的 `name=value`、`name: value`、epoch、tqdm 进度条、YOLO 表格和 JSON 行格式，处理 ANSI 转义、回车刷新和日志轮转。

图表支持平滑开关、同主机多卡叠图、放大查看、指标选择、CSV 下载和剪贴板复制。重启后从日志尾部恢复部分历史曲线，恢复范围受尾读窗口和数据点上限限制；这不是完整训练指标数据库。

## 告警、刷新与连接恢复

| 情况 | 展示方式与边界 |
|---|---|
| 主机失联或恢复 | 状态变化提示，失败期间进入退避 |
| GPU 高温 | 卡片、总览和事件提示 |
| 日志持续无变化 | 按观察到的变化时间判断停滞，首次观察有宽限期 |
| 原有 GPU 训练进程消失 | 持续超过阈值后提示，正常结束也可能满足这个条件 |
| 系统通知 | 取决于用户授权与浏览器能力 |

事件通过 `/dash/events` 长轮询交付，告警中心保存当前会话记录。**检测时延仍取决于采样周期**，不能理解为远端变化发生时立即获知。

失败退避依次为 1、2、5、10、30 分钟。手动刷新、单台立即重试或重新保存设置可以清除相应退避；宿主更新绑定凭据后，也会清除对应主机的退避。SSH 连接可跨轮询复用，失效后重新连接。

## 第一次连接

1. 安装后完整重启 DSH，打开服务器看板设置。
2. 手动填写主机、端口和用户名，或从本机 `~/.ssh/config` 导入候选。
3. 选择认证方式，填写密码或私钥，或使用导入的本地密钥文件。
4. 测试连接并保存；如果已有主机指纹，连接必须与它匹配。
5. 需要训练曲线时，发现或填写日志路径；在看板中固定常用主机。

首次未配置指纹的连接采用 TOFU：接受首次观察到的主机密钥并尝试记录，后续校验该指纹。TOFU 本身不验证第一次连接的身份，已知指纹可以事先填写；指纹不匹配时应先核实服务器变更。

“默认身份”模式尝试本机常见默认密钥，不等价于完整 OpenSSH 客户端。导入器也不是完整 SSH 配置解释器，复杂跳板、交互式认证和加密私钥口令流程需另外核对。

## 安装与更新

[GitHub Release v0.3.0](https://github.com/smilewhenever777/dsh-scholar/releases/tag/v0.3.0) 提供预构建包和校验文件。GitHub 发布与 npm 发布相互独立；本次没有发布 npm 版本。使用源码安装时可先在仓库根目录执行 `git checkout v0.3.0` 固定版本。

npm 已发布版本：

```sh
dsh plugin --profile web add dsh-server-dashboard
```

当前源码，在仓库根目录执行：

```sh
npm ci --prefix dsh-server-dashboard
npm run build --prefix dsh-server-dashboard
dsh plugin --profile web add ./dsh-server-dashboard
```

完整重启宿主并重新加载页面。源码可能领先于 npm，见 [更新记录](./CHANGELOG.md)。

部分 DSH 版本不能正确注册含空格的本地路径。优先使用无空格路径；必要时校正 profile `package.json` 中 `dsh-server-dashboard` 的 `link:` 路径和 `dsh.profile.bundles`，在 profile 目录运行 `pnpm install`，确认链接指向正确插件目录。路径使用正斜杠。

## 设置与凭据

| 配置 | 默认值或作用 |
|---|---|
| `hosts` | 主机列表：地址、端口、用户、认证、指纹、日志和显示状态 |
| `refreshIntervalS` | 30 秒；可设为 10–300 秒 |
| `staleMinutes` | 日志停滞观察阈值，默认 10 分钟 |
| `alertIdleMin` | 原有训练进程消失后的告警阈值，默认 5 分钟 |

密码和私钥交给 DSH 凭据服务，配置只保存引用，也支持本地密钥文件。凭据名称由服务端根据主机 ID 派生；请求不能指定任意凭据条目用于其他主机。地址、用户名或认证方式变化时，已绑定的凭据需要重新确认输入。

每次实际采集重新解析绑定凭据，避免宿主更换密钥后仍复用旧值。旧引用迁移只在能够确认所属关系的情况下进行；未知别名需要重新保存认证信息。

删除主机通过宿主 `credentials.unset` 清理该主机派生的条目。清理失败会明确提示配置已保存、凭据仍需检查；可能共享的历史别名不会被任意删除。存储保护由宿主 provider 决定，不能假定所有本地凭据存储都经过加密。

## 隐私与访问边界

- 数据通过 SSH 从用户配置的主机返回，包含进程命令行和日志；这些内容本身可能含实验路径或业务信息，分享截图和导出文件前应自行检查。
- `/dash/*` 仅接受本机 loopback 来源，并校验 Host、浏览器 Origin 与写请求类型；不因宿主绑定 `0.0.0.0` 就对局域网开放。
- 插件不设置独立遥测，不向第三方服务器转发监控数据。
- 自动发现和日志读取服从 SSH 账户权限；不会通过提权绕过其他用户的文件权限。

## 故障排查

| 现象 | 检查方向 |
|---|---|
| 找不到已绑定凭据 | 重新保存该主机认证信息，核对旧引用迁移 |
| `All configured authentication methods failed` | 核对用户、认证方式、密钥和服务器授权；可用相同配置的系统 SSH 对照 |
| 指纹不匹配 | 核实目标服务器和主机密钥变化后再调整 |
| 连接恢复后仍显示旧状态 | 点击立即重试；确认宿主与客户端都已更新 |
| 无日志或无曲线 | 核对文件权限、日志路径、进程关联和格式，必要时手动指定 |
| 保存返回 409 | 配置已变化或版本缺失；重新加载，核对草稿后保存 |
| 配置已保存但凭据失败 | 按错误提示重新加载、重新输入，或检查宿主凭据管理 |

## 开发接口与配置协议

| 路由 | 方法 | 作用 |
|---|---|---|
| `/dash/config` | GET / PATCH / PUT | 配置读写，不返回密码或私钥 |
| `/dash/snapshots` | GET | 主机快照；`cached=1` 只取缓存，不启动 SSH 采集 |
| `/dash/import-ssh` | GET | 导入候选 |
| `/dash/test` | POST | 测试连接 |
| `/dash/discover-logs` | POST | 日志候选 |
| `/dash/events` | GET | 长轮询事件 |

写配置先 GET 获得 `{ config, revision }`，再携带 revision 提交 PATCH。阈值只发改动字段；主机每次选择一种操作：`addHosts`、`updateHost: { id, changes }` 或 `removeHostId`。整表 PUT 也必须携带版本。

版本缺失或过期返回 409；客户端保留草稿，不自动用旧列表覆盖新配置。配置与凭据是两个持久化服务，无法承诺跨服务事务；部分完成时明确返回错误。**升级必须同时加载新宿主与新客户端。**

## 开发与许可证

SSH 采集位于 `src/host/collector.ts`，配置和路由位于 `src/index.ts`，界面位于 `src/client/`。构建检查宿主和客户端类型；`npm pack` 自动重新构建。

[测试说明](../tests/README.md) · [更新记录](./CHANGELOG.md) · [MIT 许可证](./LICENSE)