# DSH 远程监控与运维插件产品设计

> 版本：v1.1｜状态：已完成首轮可行性与一致性修订｜日期：2026-09-17。本文定义产品要求与设计默认值；宿主接入及兼容性仍须通过实现验证。

## 1. 产品目标

在 Deepseek Harness（DSH）内集中管理 SSH 服务器，通过硬件采集与 AI 巡检掌握运行情况，并将指定 Git 仓库分支的代码更新到目标服务器、重启相关服务。

首版范围已确认：面向 **DSH Web 版**；目标服务器支持 **Linux（所有版本）与 macOS**。监控支持手动检查和可配置频率的定时巡检；部署仅支持用户手动触发，触发后自动执行代码更新和服务重启。暂不做定时部署、提交触发部署等自动部署功能。

Linux 不设发行版或版本白名单，兼容目标覆盖所有 Linux 版本及 macOS；不能承诺任意历史版本上的全部功能。添加服务器至少需要兼容的 SSH、可执行远程命令的 shell 和无人值守认证；硬件采集、日志读取及项目部署分别探测工具、权限与运行环境，显示“可用／受限／不可用”及原因。项目本身不兼容目标系统时明确报告；发布时提供实测兼容矩阵。

## 2. 入口与页面

- **入口**：DSH 左侧栏底部、“设置”按钮上方新增“远程运维”菜单项。
- **页面**：服务器、监控、项目运维。监控页分为硬件、进程、日志三个板块。

接入依据：[用户提供的插件开发指南](/Users/davidwu/学习教程/deepseek-harness-dev-guide.md)（2026-09-11 整理）。指南已说明独立插件包加载、工具注册、agent 与会话接入能力，可作为后端扩展依据；指南未给出侧栏菜单和独立页面的注册接口，具体接入方式需在实现前核对 DSH Web 源码。

运行设计：SSH、巡检和部署任务由 DSH Web 服务端执行，配置与任务阶段持久化。关闭浏览器不影响任务；服务停止或插件重载后恢复未来的巡检计划，不补跑全部错过的轮次。未完成的部署标记为“中断／待核对”，核对远程实际状态后才能继续，不自动重放。

访问范围沿用当前 DSH 实例的受信任操作用户，首版不新增多租户权限系统。配置、凭据及运维接口必须受服务端访问控制保护；宿主没有可复用的认证能力时，仅面向受保护的访问环境，不能把页面入口隐藏当作权限控制。

## 3. 核心需求与设计

### 3.1 服务器配置

- 支持添加、编辑、删除多台 SSH 服务器，配置名称、地址、端口、用户及认证信息；有项目引用时先解除关联再删除。
- **配置隔离**：使用插件私有的 SSH 配置，不复用系统或用户已有的 SSH 配置。
- **密码保存**：支持保存登录密码，供后续巡检和用户触发的部署自动连接，不要求每次输入。
- 默认展示 `ssh <服务器名>`，名称由插件私有配置解析；实际执行显式指定私有配置及主机信任记录，不能直接依赖裸命令的默认环境。[OpenSSH 配置依据](https://man.openbsd.org/ssh)
- 自定义登录命令支持可解析的 SSH 连接参数，包括地址、端口、用户、私钥和跳板机；覆盖隔离设置、拼接任意 shell 脚本或仅建立隧道的命令在测试前明确拒绝，不静默忽略参数。
- 添加前必须使用拟保存的配置和凭据执行真实 SSH 登录测试，并确认能无人值守执行远程命令；成功才能添加，失败时展示可理解的原因。
- 首次连接在界面核对并保存主机指纹；指纹变化时暂停连接。必须逐次输入验证码、确认硬件密钥或交互改密的连接不能满足自动巡检，明确提示先配置可无人值守的认证方式。
- 修改连接配置或凭据时重新测试，通过后替换原配置。
- 首版支持 Linux（所有版本）与 macOS；连接方式不限定发行版，系统采集和服务操作需要适配对应环境。

凭据要求：密码、私钥及口令由服务端加密保存，解密材料与配置数据分开管理；保存后页面仅展示已配置状态。SSH 配置引用凭据，不将密码写入普通配置、命令参数、脚本或 AI 上下文；敏感输出在展示、持久化和提交模型前脱敏。SSH 配置、默认密钥、ssh-agent 和主机信任记录均与系统配置隔离，跳板机也遵守同一规则。服务重启后应可正常解密；解密材料缺失时显示凭据不可用，不退回明文保存。

### 3.2 服务器监控

| 板块 | 核心能力 | 页面呈现 |
| --- | --- | --- |
| 硬件检测 | 通过 SSH 命令采集硬件状态；包括内存、硬盘等 | CPU、内存、磁盘使用情况及最近采集时间 |
| 软件服务检测 | 默认分组展示全部运行中的进程及其信息，必须由 AI agent 检查；支持额外定制 | 分组进程列表、资源占用、运行时间、AI 异常解释和依据 |
| 日志检测 | 默认由 AI agent 检查各项目服务的日志文件，识别异常和告警；支持额外定制 | 按项目及服务展示检查状态、异常与告警摘要、日志证据和建议 |

进程与日志检测必须实际调用 AI agent 分析，单纯执行命令并展示输出不算完成；SSH 命令负责采集，agent 负责检查和解释。

- **触发方式**：支持手动检查和定时巡检，可按服务器及检查类型调整频率、启停。
- 设计要求：展示最近检查时间、当前状态和失败原因；连接失败、AI 调用失败与目标服务异常分别呈现，不能把未完成的检查标为正常。
- 巡检仅执行只读检查并提供建议，不自行修复或重启服务；AI 模型、频率和记录保留规则见第 4 节。
- 只读边界由工具权限实施，不能仅靠提示词约束；日志、进程输出和仓库内容作为待分析数据，不得改变操作权限。

**默认进程监控**

- 无需逐个添加进程，展示采集时刻服务器上可枚举的全部存活进程，包括运行、睡眠及僵尸等状态；不承诺捕获两次采集间已结束的短命进程。
- 展示进程名、PID、所属用户、常驻内存占用、CPU 占用、启动时间、运行时长及状态；统一单位并标注 CPU 统计口径，支持搜索和排序。
- 默认按关联项目／服务分组，无法归属的进程进入“未关联项目”组，确保不会因分组遗漏进程。
- agent 根据采集结果分析进程状态和资源异常，输出具体进程、证据与判断；进程列表与 AI 分析状态分别展示。
- 权限限制导致无法完整枚举或读取字段时，明确展示检测范围与不可用项，不将部分结果宣称为全量。
- 全量列表与 AI 分析覆盖率分别计算：按批次分析，显示已分析／采集进程数；模型容量、超时或额度不足时标记“部分分析”，不能以少量样本代表整台服务器正常。
- 额外定制包括关注进程、分组规则、预期运行状态、资源阈值和自然语言检查要求。

**默认日志监控**

- 覆盖已配置项目启动的各项服务，按“项目 → 服务 → 日志文件”关联，并默认纳入巡检。
- **动态发现**：配置项目时优先检查已有服务配置；尚未部署则标记“待部署后发现”。AI 从项目目录及关联的启动／服务配置搜索，保存“配置来源 → 服务 → 日志文件”证据；不每次全盘扫描。巡检核对配置变化，部署后、配置变化或路径失效时重新发现；用户定制项单独保留。
- 例如读取 Supervisor 的实际生效配置与运行状态，处理包含文件、变量、stdout/stderr 合并以及自动生成的文件路径。`/var/log/supervisor/xxx.log` 仅为示例；`NONE`、标准输出设备或无文件日志不能伪造为可读文件。[Supervisor 配置依据](https://supervisord.org/configuration.html)
- agent 检查日志中的异常、错误和告警，展示级别、摘要、发生时间及可定位的原文证据。
- 搜索不到日志来源、文件不存在或不可读时，展示对应服务的“未发现日志／检查失败”及原因，不得视为无异常。
- 首版自动检查可读取的普通日志文件；仅有 journal、容器日志接口或远端日志平台时标为“当前来源不支持”。首次部署可为目标服务配置文件日志；只读巡检不替用户修改日志配置。
- 首次默认最多读取每文件末尾 1000 行且不超过 1 MiB，后续按已持久化位置增量读取，每轮每文件上限 1 MiB，均可配置。轮转、截断、积压或截断读取时展示覆盖范围与缺口，保留可读未处理范围；不承诺恢复已被删除的日志。告警按服务、文件来源及异常特征去重，保留发生次数。
- 额外定制包括新增日志文件、关注或忽略规则、检查范围及自然语言检查要求。

### 3.3 项目运维管理

**项目配置**

- 支持多个项目与 Git 仓库，每个项目配置仓库、分支、目标服务器、代码目录及部署要求。
- 一个项目对应一个仓库和一个指定分支，可配置多个部署目标；每个目标对应服务器、代码目录、服务及健康检查配置，分别保存日志发现结果、脚本和记录。每次手动部署选择一个目标，首版不做多目标原子发布。
- SSH 登录、Git 仓库认证和安装／重启所需的提权分别配置、分别验证。远端 Git 可使用目标已配置的有效认证，或使用插件管理的项目凭据；不自动把服务器登录密码当 Git／sudo 密码，不把宿主用户的 SSH 配置转发过去。所用凭据不得进入 AI 上下文、仓库 URL 展示、脚本或任务日志。

**首次 AI 部署**

1. 用户配置项目并手动发起首次部署。
2. AI 通过 SSH 先验证项目运行条件、认证和权限，再完成环境准备、依赖安装、必要构建及服务配置；优先使用项目独立的运行环境。
3. AI 启动服务，并实际验证重启及运行情况；根据服务配置动态发现日志文件并纳入监控。
4. 环境、部署、启动、重启及健康验证全部成功后，将适合重复执行的步骤生成候选 `.sh` 文件。部署结果与脚本验证状态分开记录，生成文件不等于已验证可复用。

设计要求：目录已有仓库时核对仓库与分支；尚无代码时在指定空目录克隆配置的仓库与分支，不覆盖不明文件。AI 在变更服务前确定并记录健康检查，包括预期进程、适用的端口／接口、启动等待时限和观察窗口；首次可生成，后续复用，不能为使失败任务通过而自行降低判定标准。日志检查独立显示；没有文件日志不单独推翻已通过的服务健康检查，也不能被写成“日志正常”。所需权限不足时明确报告阻碍。

**脚本固化**

- 固化有成功执行证据、明确前置条件和完成条件的步骤；区分一次性环境安装与日常更新，不将部署对话机械拼成脚本。无法验证重复执行行为的操作保留为 AI 步骤。
- 脚本由插件按项目和目标环境管理，提供内容查看和版本记录；在目标服务器执行，绑定解释器、工作目录、环境变量引用及适用配置；不默认所有 `.sh` 都能由任意 shell 执行，不存明文凭据，不自动提交到用户仓库。
- 状态为“候选 → 已验证 → 已失效”。候选通过语法与配置检查后，在测试环境或下一次用户手动部署中由 AI 监督实际验证，通过后才成为稳定版本；不为验证而额外重装环境、执行不可重复操作或重启生产服务。
- **执行分工**：固定步骤直接执行脚本，尚未固化的步骤由 AI 执行；每次部署展示本次采用的步骤及脚本版本。
- 仓库分支、依赖声明、服务配置或环境条件变化时，在执行相关步骤前重新检查脚本适用性；失效步骤交给 AI 处理，验证后形成新版本。当前有效版本保留成功提交、来源部署摘要与验证结果，不因普通历史过期而丢失依据。

**后续手动部署**

1. 用户选择项目与目标服务器，点击部署。
2. SSH 进入服务器代码目录，核对仓库、分支、目录状态及认证条件。
3. 在服务器执行 `git pull --ff-only <remote> <branch>`：remote 必须对应配置仓库，当前分支须与配置一致；更新后核对 HEAD 与本次获取的远端提交一致并记录前后提交。显式限制只快进，避免不同 Git 配置触发合并或变基；本地独有提交、分叉及冲突均停止。[Git 更新依据](https://git-scm.com/docs/git-pull)
4. 按“固定步骤执行脚本、未固化步骤由 AI 执行”完成必要的依赖更新或构建、服务重启及健康验证，并刷新日志来源。
5. 展示执行阶段、耗时、输出、代码提交、部署结果及日志监控状态；代码更新、必需部署步骤及预先确定的健康检查全部通过才算成功。

**失败处理与执行约束**

- 部署失败允许 AI 修复当前项目的运行配置、补齐已声明的依赖并重试；每轮记录原因、动作和结果。自动修复不改写仓库跟踪源码、不升级或重启无关服务、不进行不可逆的数据修复；需要这些变更时停止并给出处理建议。
- 默认最多 2 轮自动修复，每轮包含一次修复和验证；重试上限、整个任务超时与单步骤超时均可配置，达到上限仍失败则停止。拉取成功后，本任务的修复与重试固定在已记录提交，不再次拉取新代码；结果不确定的步骤先核对后置状态，不从头盲目重放。
- 未提交改动、分支不符或拉取冲突时停止并报告，不自动覆盖、丢弃代码或替用户解决冲突；首版不提供自动回滚。
- 首版同一服务器的部署任务串行执行，覆盖环境安装及共享服务配置修改；任务、远程执行标识和阶段结果持久化。中断或停止结果未核实时保留占用状态，避免下一任务与仍存活的命令并发执行。
- 用户停止或任务超时后，先停止派发新步骤并请求终止本任务的远程命令，显示“停止中”；确认受控命令退出后才显示“已停止”。仅断开 SSH 不等于远程停止；无法确认时显示“中断／待核对”，列出已完成步骤及已知副作用，不默认关闭已启动的业务服务。
- 状态包括“待执行、部署中、修复中、成功、失败、停止中、已停止、中断／待核对”。自动修复后仍须通过原健康检查；失败或停止不代表恢复部署前状态，首版不承诺自动回滚或零停机。

## 4. 默认设置与运行规则

| 项目 | 默认行为 |
| --- | --- |
| AI 模型 | 使用 DSH 已配置的模型，插件内可选择 |
| 巡检频率 | 硬件每 60 秒；进程与日志 AI 检查每 5 分钟，均可调整 |
| 巡检权限 | 只读检查、给出建议；不因巡检发现异常而自行修复或重启 |
| 告警 | 页面内展示，暂不接外部通知渠道 |
| 历史 | 普通巡检与部署明细默认保留 30 天，可调整；配置、有效脚本、来源部署摘要及未结束任务不随普通历史清理 |

同一服务器的同类巡检不重叠执行，超出周期时合并等待中的触发，不无限堆积；AI 并发数、单轮时限与分析量设可配置上限。未配置模型或模型不可用时硬件及进程采集仍可展示，AI 检查标为不可用，需 AI 的部署步骤不能伪装完成。每次检查展示采集时间、分析覆盖及上次完整成功时间；过期、部分覆盖与失败不显示为“正常”。部署期间只标注已知服务重启造成的短暂异常，不隐藏其他告警或部署结束后的异常。

## 5. 首版验收条件

- SSH 登录验证失败不得添加服务器，不创建未验证的服务器记录。
- 在不读取系统或用户 SSH 配置的情况下，使用插件保存的凭据完成添加验证和后续自动连接。
- 在发布的 Linux/macOS 实测矩阵中分别验证三类监控；不具备某项能力时有明确状态。进程与日志结果包含实际 AI 分析和证据。
- 无需逐项配置即可分组查看全部可枚举的运行进程，包含内存占用和运行时间；无法完整检测时明确提示。
- 各已配置项目服务的日志默认参与巡检；异常和告警可定位到对应服务与日志证据，支持额外定制规则。
- 日志路径来自实际部署配置的动态发现，修改 Supervisor 等服务配置后可更新监控文件，不依赖固定目录。
- 手动检查与定时巡检均有效；关闭浏览器不停止服务端巡检，DSH 服务重启后恢复计划。
- 配置的仓库、分支、目标服务器与代码目录能够准确对应。
- 首次 AI 部署成功后生成候选脚本；只有实际验证通过的脚本被标为已验证，无法安全复用的步骤仍由 AI 执行。
- 后续手动部署通过 SSH 在服务器执行 `git pull`，完成部署、重启及健康验证，准确记录提交和结果。
- 后续部署能够组合执行固化脚本与 AI 步骤；失败时按上限自动修复、重试，仍失败则停止并保留诊断记录。
- 默认巡检只读、页面内告警、历史保留与频率设置符合约定，密码不出现在 AI 上下文、脚本或日志中。
- 菜单位置符合要求；异常和失败状态不被呈现为成功。

关键反例须纳入验收：私有配置不回落系统认证；模型超时或部分覆盖不报正常；Supervisor 自动日志、无文件日志及轮转缺口可区分；本地独有提交和冲突不被覆盖；重试不改变目标提交；SSH 断开但远程命令存活时不报已停止；第 31 天仍能追溯有效脚本的来源和验证。

## 6. 实施前必须验证的依赖

1. **DSH Web 接入**：验证可通过插件注册指定位置的菜单、页面、后端接口及访问控制；现有指南未证明这些界面扩展点。如必须改宿主，需单独评估集成方案，不能将独立网站冒充插件交付。
2. **后台 agent 与 SSH 执行**：验证无浏览器会话时可启动受限巡检和部署 agent，并验证密码登录、私有配置、远程任务标识及中断核对。`ctx.agents` 等能力存在不等于上述完整流程已被证明可用。

上述是实现前的技术验证项，不是新增产品待选项；本次文档修订没有执行真实服务器部署或验证宿主 API。