# HANDOFF — 服务监测模块深度扩展与 SSH 连接问题修复

> 最后更新：2026-07-20 18:26 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：czj

---

## 1. 我们在做什么

本项目是「运维辅助平台」（原"问题排查 AI 助手"），Flask Web 服务跑在 `192.168.5.60:8088`。

本次会话有两项主要任务：

### 任务一：SSH 连接测试失败问题修复

用户在服务监测平台新建远程目标服务器（192.168.5.44），点击"测试连接"提示"SSH 连接失败"。经排查发现服务器 5.60 上**未安装 paramiko**，且错误信息过于笼统，无法区分网络/认证/依赖问题。

### 任务二：服务监测模块深度扩展

在核心子集（7个模块）基础上，扩展更多检测能力：
- 补充常用系统模块：OOM检测、进程检测、网络检测、计划任务、端口检测
- 补充服务深度检测：Docker深度、MySQL深度、Redis深度
- 新增业务容器监测：UStorage、UTracker

需求文档位置：
- `Docs/需求文档/服务监测/PRD_需求文档_服务监测模块.md`
- `Docs/需求文档/服务监测/PRD_计划执行_服务监测模块.md`

---

## 2. 已经完成了什么

### 任务一：SSH 连接问题修复 ✅

1. **部署 paramiko** ✅
   - 在服务器 5.60 执行 `pip3 install --break-system-packages paramiko` 安装 5.0.0
   - 重启服务验证 SSH 连接成功

2. **增强错误分类** ✅
   - `executor.py` 新增 `DependencyError`、`SSHConnectionError` 异常类
   - 新增 `classify_ssh_error()` 函数，按异常类型返回 6 种错误码
   - `BaseExecutor.test_connection()` 改为抛出分类后的异常

3. **API 返回详细错误** ✅
   - `target_service.test_connection()` 返回 `detail` + `error_code` 字段
   - `routes.py` 直接返回完整结果
   - 前端 `targets.html` 显示详细错误，鼠标悬停查看详情

4. **上传脚本增加依赖检查** ✅
   - `deploy/upload_to_server.py` 新增 `_check_and_install_deps()` 函数
   - 部署时自动检查并安装 paramiko/cryptography

5. **输出 PRD 文档** ✅
   - `Docs/需求文档/服务监测/PRD_问题处理_SSH连接测试失败.md`
   - `Docs/需求文档/服务监测/PRD_计划执行_SSH连接测试失败修复.md`

**验证结果**：
- 认证失败返回 `"认证失败：用户名或密码错误"` + `AUTH_FAILED`
- 不可达 IP 返回 `"连接被拒绝：目标端口未开放或 SSH 服务未运行"` + `CONNECTION_REFUSED`
- 连接成功返回 `"连接成功"`

### 任务二：模块扩展 ✅

1. **迁移 system 类模块** ✅
   - 从 `临时目录/服务器监测/lib/system/` 迁移 5 个模块到 `assets/system/`
   - 改造 `LIB_DIR` 从写死改为可注入模式
   - 模块：05_oom_check、06_process_check、07_network_check、11_scheduled_tasks、12_port_check

2. **迁移 service 深度模块** ✅
   - 从 `临时目录/服务器监测/lib/service/` 迁移 3 个模块到 `assets/service/`
   - 模块：21_docker_deep、23_mysql_depth、25_redis_depth

3. **新增业务容器监测** ✅
   - 新建 `37_ustorage_check.sh`：容器状态、健康检查、存储容量与IO
   - 新建 `38_utracker_check.sh`：容器状态、健康检查、处理能力

4. **更新代码配置** ✅
   - `check_modules.py`：ALL_MODULES 从 7→17 个
   - `display_names.py`：新增 ~150 个 KEY 的中文显示名
   - `config.sh.template`：添加 ustorge/utracker 容器匹配模式

5. **修复空值问题** ✅
   - `parser.py` 新增 `_INVALID_VALUES` 过滤 N/A、无法获取、未知等无效值
   - `01_system_basic.sh` 修复 `check_command` 函数不存在的问题
   - `02_cpu_check.sh` 修复 `SCHEDULER_RUNQUEUE` 取值逻辑

**验证结果**：
- 快速巡检：5 模块，61 项
- 全量巡检：17 模块，193 项（全部有效值，无空值/N/A）
- 已部署到 5.60 并验证通过

---

## 3. 当前卡在哪

**无卡点**。所有任务已完成，等待用户下一步指令。

工作区有未提交的改动（本次会话的修改），建议提交后再结束。

---

## 4. 下一步计划

按优先级排序：

1. **提交代码**（P0）
   - 当前有 11 个修改文件 + 10 个新增文件未提交
   - 建议拆分为 3 个提交：
     - `fix: SSH 连接测试错误分类与依赖检查`
     - `feat: 服务监测模块扩展（新增 10 个检测模块）`
     - `fix: 过滤无效检测值，修复 bash 脚本检测逻辑`

2. **添加更多检测模块**（P1，可选）
   - 参考 PRD，还有 system 类（40综合诊断/43安全合规/44系统日志/45时间同步）
   - 以及 service 类（EMQX/Java/Python/Nginx/Nacos/FastDFS）

3. **远程目标巡检测试**（P2）
   - 新建 192.168.5.44 远程目标，执行快速/全量巡检
   - 验证 SSH 远程执行全链路

---

## 5. 踩过的坑（绝对不要再踩）

### 坑 1：服务器端 paramiko 未安装

**坑**：点击测试连接返回"SSH 连接失败"，但实际原因是服务器上没装 paramiko，`import paramiko` 失败被吞掉。

**原因**：HANDOFF 文档写了"待安装依赖"，但部署时跳过了。`upload_to_server.py` 只上传代码不检查依赖。

**避免**：
- `upload_to_server.py` 已增加依赖检查步骤，部署时自动安装
- 错误信息现在会明确提示"paramiko 未安装"

### 坑 2：Windows 换行符导致 bash 脚本无法执行

**坑**：bash 脚本从 Windows 上传后含 `\r\n`，Linux 执行报 `$'\r': command not found`。

**原因**：Git 默认在 Windows 上检出 CRLF，SFTP 上传时没转换。

**避免**：
- `upload_to_server.py` 已增加 `_sftp_put_unix_lines()` 自动转换 `.sh`/`.template` 文件
- 未来上传脚本文档要强调换行符问题

### 坑 3：templates/service_monitor 子目录未上传

**坑**：部署后模板目录为空，页面 404。

**原因**：`DIRS_TO_UPLOAD` 只上传一层文件，`templates/service_monitor/` 子目录被忽略。

**避免**：已修改上传脚本，子目录递归上传。

### 坑 4：检测项值为空/N/A 判定为"正常"

**坑**：报告显示大量 N/A 值被判定为"正常"，误导用户。

**原因**：Parser 不过滤无效值，所有 KEY:VALUE 都解析成检测项。

**避免**：`parser.py` 已增加 `_INVALID_VALUES` 过滤，N/A、无法获取、未知等不再输出。

### 坑 5：bash 脚本调用不存在的函数

**坑**：`check_command ulimit` 函数不存在，导致 `ULIMIT_INFO` 输出"无法获取"。

**原因**：参考脚本中有 `check_command` 函数，但 `common.sh` 没有迁移。

**避免**：迁移脚本时检查函数依赖，用 `command -v` 替代自定义函数。

---

## 6. 关键文件与命令速查

### 本次修改的核心文件

| 文件 | 用途 |
|------|------|
| `service_monitor/utils/executor.py` | SSH 连接错误分类 |
| `service_monitor/utils/parser.py` | 过滤无效检测值 |
| `service_monitor/utils/check_modules.py` | 模块清单（7→17） |
| `service_monitor/utils/display_names.py` | KEY 中文显示名 |
| `service_monitor/assets/system/*.sh` | 新增 5 个系统检测模块 |
| `service_monitor/assets/service/*.sh` | 新增 5 个服务检测模块 |
| `deploy/upload_to_server.py` | 依赖检查 + 换行符转换 |

### 常用命令

```bash
# 单元测试（51 用例，应全绿）
cd skill/code && python -m pytest web/service_monitor/tests/ -v

# 部署到 5.60
cd deploy && SSH_PASSWORD='***' python upload_to_server.py

# 登录密码
admin / Ubains@1357

# 健康检查
curl -s http://192.168.5.60:8088/api/health

# 快速巡检
curl -s -b cookies.txt "http://192.168.5.60:8088/api/service-monitor/run/stream?target_id=local&suite=quick"

# 全量巡检
curl -s -b cookies.txt "http://192.168.5.60:8088/api/service-monitor/run/stream?target_id=local&suite=full"
```

### 参考目录

- 参考脚本：`临时目录/服务器监测/lib/`
- 需求文档：`Docs/需求文档/服务监测/`
- 会话交接：`HANDOFF.md`
