# 执行计划 - 目标机资源监控（SSH方式）

> **关联 PRD**：`_PRD_目标机资源监控（SSH方式）.md`
> **创建日期**：2026-08-21
> **预计总工时**：2 天

---

## 一、执行概述

本计划将 PRD 中的「目标机资源监控（SSH方式）」功能分为 3 个 Phase 实施：

1. **Phase 1**：TargetResourceMonitor 后端采集模块 + 集成到执行引擎（1 天）
2. **Phase 2**：实时监控页 + 批量监控页目标机资源 UI（0.5 天）
3. **Phase 3**：报告页目标机资源区块 + 联调测试（0.5 天）

---

## 二、任务分解

### Phase 1：TargetResourceMonitor 后端采集模块 + 集成到执行引擎

**目标**：实现 `TargetResourceMonitor` SSH 采集类，集成到 `PerformanceExecutor`，目标机资源数据随 WebSocket 快照推送，执行结束后写入 `target_resource_summary`。

| # | 任务 | 关键文件 | 验收标准 |
|---|------|---------|---------|
| 1.1 | 新建 `TargetResourceMonitor` 类（SSH 连接 + 单次命令批量采集 + CPU 差值计算 + 断线重连） | `backend/app/executors/target_resource_monitor.py` | connect() 成功建立 SSH 连接；sample() 返回含 cpuPercent/memPercent 的字典；无数据时返回 None |
| 1.2 | 集成到 `PerformanceExecutor`：`_target_resource_loop` 协程 | `backend/app/executors/performance_executor.py` | 并行运行，每 2 秒采集一次，合并进快照 data.targetResource |
| 1.3 | 执行结束后写入 `target_resource_summary` | `backend/app/services/performance_service.py` | 任务 JSON 字段存储采样序列和统计 |
| 1.4 | PerformanceTask 模型增加 `target_resource_summary` 字段 | `backend/app/models/performance.py` | JSON 字段，nullable，to_dict() 输出 |
| 1.5 | 报告 API 返回 target_resource_summary | `backend/app/routers/performance.py` + `backend/app/schemas/performance.py` | GET 报告接口响应含 targetResourceSummary |
| 1.6 | 数据库迁移：增加 `target_resource_summary` 列 | `backend/app/database.py` | migration 脚本执行成功 |
| 1.7 | 配置项：TARGET_MONITOR 系列（host/port/username/password/interval/alert） | `backend/app/config.py` | 可通过环境变量控制；默认关闭 |

**验收方式**：执行一个压测任务，观察 WebSocket 推送消息含 targetResource 字段；执行完成后报告 API 返回 target_resource_summary。

---

### Phase 2：实时监控页 + 批量监控页目标机资源 UI

**目标**：`MonitorPanel.vue` 和 `BatchMonitor.vue` 增加目标机资源卡片和趋势图。

| # | 任务 | 关键文件 | 验收标准 |
|---|------|---------|---------|
| 2.1 | PerformanceSnapshot 类型增加 targetResource 字段；Report 类型增加 targetResourceSummary | `frontend/src/types/performance.ts` | 编译通过 |
| 2.2 | MonitorPanel 目标机资源卡片（CPU/内存/信息） | `frontend/src/views/performance/MonitorPanel.vue` | 收到快照后实时更新；无数据时隐藏 |
| 2.3 | MonitorPanel 目标机资源趋势图（CPU + 内存双折线） | 同上 | 随时间动态更新；默认折叠 |
| 2.4 | 目标机 CPU/内存 > 85% 红色告警提示 | 同上 | 卡片数值超过阈值变红；连接断开提示「未连接」 |
| 2.5 | BatchMonitor 目标机资源趋势图 | `frontend/src/views/performance/BatchMonitor.vue` | 无数据时隐藏 |

**验收方式**：压测执行中，监控页显示目标机资源卡片实时更新；趋势图正常渲染。

---

### Phase 3：报告页目标机资源区块 + 联调测试

**目标**：`ReportPanel.vue` 展示目标机资源汇总和趋势图，端到端联调。

| # | 任务 | 关键文件 | 验收标准 |
|---|------|---------|---------|
| 3.1 | ReportPanel 目标机信息卡片 + 资源汇总卡片 + 趋势图 | `frontend/src/views/performance/ReportPanel.vue` | 汇总数据正确显示；无数据时隐藏 |
| 3.2 | 端到端联调测试 | 全部相关文件 | 创建 → 执行 → 监控 → 报告全流程目标机资源数据正常 |
| 3.3 | 降级验证：目标机 SSH 不可达 | `target_resource_monitor.py` | 任务正常执行，目标机资源区块隐藏 |
| 3.4 | 降级验证：TARGET_RESOURCE_MONITOR_ENABLED=false | 配置文件 | 目标机监控不启动，不影响现有功能 |
| 3.5 | 前端构建验证 | `frontend/` | npm run build 无错误 |

**验收方式**：端到端流程——执行压测 → 实时监控目标机资源 → 查看报告目标机资源趋势 → SSH 关闭时正常降级。

---

## 三、验收标准总览

| 验收项 | 对应 Phase |
|--------|-----------|
| TargetResourceMonitor SSH 采集 CPU/内存 | Phase 1 |
| 目标机资源指标随 WebSocket 快照推送 | Phase 1 |
| 执行结束后 target_resource_summary 落库 | Phase 1 |
| 报告 API 返回 target_resource_summary | Phase 1 |
| 监控页实时目标机资源卡片 + 趋势图 | Phase 2 |
| 批量监控页目标机资源趋势图 | Phase 2 |
| 报告页目标机资源汇总 + 趋势图 | Phase 3 |
| SSH 不可达时降级跳过 | Phase 3 |
| 默认关闭时不影响现有功能 | Phase 3 |
| 端到端全流程正常 | Phase 3 |

---

## 四、关键实现细节

### 4.1 TargetResourceMonitor 核心接口

```python
class TargetResourceMonitor:
    def __init__(self, host, port=22, username="root", password=None,
                 private_key=None, sampling_interval=2.0, timeout=10):
        """host: 目标机 IP; 其余 SSH 参数; interval: 采样间隔(秒)"""

    def connect(self) -> bool:
        """建立 SSH 连接，获取元信息(hostname/os/cpu_cores)"""

    def sample(self) -> dict | None:
        """单次 SSH 采集: 读取 /proc/stat + /proc/meminfo + /proc/loadavg
        返回: {cpuPercent, memPercent, memUsedMb, memTotalMb, loadAvg, connected}
        或 None(连接失败)"""

    def dispose(self):
        """关闭 SSH 连接"""
```

### 4.2 SSH 命令（单次往返）

```bash
cat /proc/stat | head -1; echo '---MEM---'; cat /proc/meminfo | grep -E 'MemTotal|MemAvailable'; echo '---LOAD---'; cat /proc/loadavg
```

输出解析示例：
```
cpu  39182048 16096 12959752 643287885 9806532 2812300 983700 18734 0 0
---MEM---
MemTotal:       15853548 kB
MemAvailable:    3579428 kB
---LOAD---
1.09 2.98 2.61 1/123 45678
```

### 4.3 CPU 计算逻辑

```
cpu2 = sum(POSITIONS[0,1,2,3,4,5,6,7,8,9]) = user+nice+system+idle+iowait+irq+softirq+steal+guest+guest_nice
idle2 = POSITIONS[3] = idle

total_delta = cpu2 - cpu1
idle_delta = idle2 - idle1

cpu_percent = 100.0 * (1.0 - idle_delta / total_delta)  # 当 total_delta != 0 时
```

### 4.4 断线重连逻辑

```
sample()
  → try:
      exec_command() → 采集
  → except (SSHException, socket.error, EOFError, OSError):
      attempt reconnect (最多1次)
      → 成功: 重新采集
      → 失败: return None, fail_count++
      → fail_count >= 5: 停止监控，log 警告
  → 正常返回: fail_count = 0
```

### 4.5 前端资源区块组织

```
MonitorPanel.vue
├── 执行机资源区块（已有，默认折叠）
│   ├── 资源卡片 x4
│   └── 资源趋势图
├── 目标机资源区块（新增，默认折叠，无数据时隐藏）
│   ├── 目标机信息卡片（主机名/系统/核数/连接状态）
│   ├── 资源卡片 x2（CPU / 内存） + 告警
│   └── 目标机资源趋势图
```

---

## 五、测试计划

### 单元测试
- `TargetResourceMonitor` SSH 连接/断开/重连
- `/proc/stat` 差值计算正确性
- `/proc/meminfo` 解析正确性
- sample() 返回 None 降级场景

### 集成测试
- 压测执行 + 目标机资源采集全流程
- 目标机资源合并到 WebSocket 快照
- SSH 连接断开 → 自动重连 → 恢复采集

### 手动测试
- 监控页目标机资源卡片实时刷新
- 目标机资源趋势图动态渲染
- 关闭目标机 SSH → 监控页提示「未连接」→ 压测正常完成
- 设置 TARGET_RESOURCE_MONITOR_ENABLED=false → 无目标机资源区块

---

## 六、风险评估

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 目标机 SSH 凭据变更 | 无法采集 | 环境变量配置；凭据变更仅需重启后端 |
| 目标机 CPU 计算首次为 0 | 首点数据异常 | 首轮只记录原始值，第二轮开始计算 |
| SSH 连接在长压测中中断 | 部分时段无数据 | 自动重连 + 连续失败 5 次后停止 |
| 多任务同时执行时 SSH 冲突 | 多个 SSH 连接 | 每个任务独立 TargetResourceMonitor 实例 |
| 目标机文件系统只读 | 无法访问 /proc | /proc 是虚拟文件系统，不影响 |

---

## 七、后续工作

- [ ] Phase 1-3 实施完成后更新 CLAUDE.md 当前进度
- [ ] 更新 HANDOFF_性能测试.md 交接文档
- [ ] Git 提交（Conventional Commits）
- [ ] 部署到 5.60 服务器（如需要）

---

## 八、附录

### 关键文件清单

| 文件 | 操作 | 用途 |
|------|------|------|
| `backend/app/executors/target_resource_monitor.py` | **新建** | TargetResourceMonitor SSH 采集类 |
| `backend/app/executors/performance_executor.py` | 修改 | 集成 _target_resource_loop |
| `backend/app/services/performance_service.py` | 修改 | 写入 target_resource_summary |
| `backend/app/models/performance.py` | 修改 | 增加 target_resource_summary 字段 |
| `backend/app/schemas/performance.py` | 修改 | 报告 schema 增加 targetResourceSummary |
| `backend/app/routers/performance.py` | 修改 | 报告 API 返回 targetResourceSummary |
| `backend/app/database.py` | 修改 | 数据库迁移增加列 |
| `backend/app/config.py` | 修改 | 增加目标机监控配置项 |
| `frontend/src/types/performance.ts` | 修改 | 增加 targetResource 类型 |
| `frontend/src/views/performance/MonitorPanel.vue` | 修改 | 目标机资源卡片 + 趋势图 |
| `frontend/src/views/performance/BatchMonitor.vue` | 修改 | 目标机资源趋势图 |
| `frontend/src/views/performance/ReportPanel.vue` | 修改 | 目标机资源汇总 + 趋势图 |
| `Docs/PRD/性能测试/需求文档/_PRD_目标机资源监控（SSH方式）.md` | **新建** | 需求文档 |
| `Docs/PRD/性能测试/需求文档/_PRD_目标机资源监控（SSH方式）_计划执行.md` | **新建** | 本计划执行文档 |

---

*本文档由 prd-plan skill 生成，关联 PRD：`_PRD_目标机资源监控（SSH方式）.md`*