docs(handoff): 更新会话交接文档（服务监测深度扩展+SSH修复）

Co-Authored-By: Claude <noreply@anthropic.com>

docs(handoff): 更新会话交接文档（服务监测深度扩展+SSH修复）
Co-Authored-By: Claude <noreply@anthropic.com>
b9bd58fd · 陈泽健 · c926a633 · b9bd58fd
--- a/HANDOFF.md
+++ b/HANDOFF.md
-# HANDOFF — P2 级功能增强 + 平台化改造（已部署，待提交 + 密码修改）
+# HANDOFF — 服务监测模块深度扩展与 SSH 连接问题修复

-> 最后更新：2026-07-14 16:00 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：研发组（Claude 协助）
+> 最后更新：2026-07-20 18:26 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：czj

 ---

 ## 1. 我们在做什么

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

-本会话完成了三项主要工作：
+本次会话有两项主要任务：

-1. **P2-1 语义搜索升级**：SearchEngine 加 Embedding 向量搜索能力（代码就绪，用户因担心 API 扣费暂关闭 `embedding_enabled: false`，搜索走 TF-IDF）
-2. **P2-2 移动端响应式适配**：三档断点 + 触控热区 + 弹窗适配 + SSE 滚动跟随
-3. **平台化改造**：新增平台首页 `/`（模块卡片），问题排查助手降级为 `/troubleshoot` 模块，预留"服务监控"模块
+### 任务一：SSH 连接测试失败问题修复

-还完成了两个额外需求：
- **普通用户项目名称输入限制**：`/api/projects` 角色鉴权，普通用户返回空列表防泄露
- **架构文档**：根目录新建 `ARCHITECTURE.md`，说明技术栈、部署方式、模块注册机制
+用户在服务监测平台新建远程目标服务器（192.168.5.44），点击"测试连接"提示"SSH 连接失败"。经排查发现服务器 5.60 上**未安装 paramiko**，且错误信息过于笼统，无法区分网络/认证/依赖问题。

-**关键决策**：
- Embedding 向量搜索**暂停使用**（用户决定），启用只需改 `config.json` 的 `embedding_enabled: true` + 生成向量文件
- 平台化用**同服务不同路由**（非微服务），共用 Flask + 认证，各模块独立 Blueprint
- 模块注册用声明式 `modules.py`，新增模块只需追加声明 + 注册 Blueprint
+### 任务二：服务监测模块深度扩展
+
+在核心子集（7个模块）基础上，扩展更多检测能力：
+- 补充常用系统模块：OOM检测、进程检测、网络检测、计划任务、端口检测
+- 补充服务深度检测：Docker深度、MySQL深度、Redis深度
+- 新增业务容器监测：UStorage、UTracker
+
+需求文档位置：
+- `Docs/需求文档/服务监测/PRD_需求文档_服务监测模块.md`
+- `Docs/需求文档/服务监测/PRD_计划执行_服务监测模块.md`

 ---

 ## 2. 已经完成了什么

-### ✅ 2.1 P2-1 语义搜索升级（代码完成，功能关闭）
+### 任务一：SSH 连接问题修复 ✅

- `search_engine.py` 加向量加载/查询/降级，**公开接口零变更**（`search()` 签名不变）
- 新增 `utils/vector_builder.py` 预计算脚本
- `config.json` 新增 `embedding_enabled: false` / `embedding_model` / `embedding_api_timeout`
- `/api/health` 暴露 `search.mode: tfidf` + 版本升至 1.3.0
- **验证**：`/api/health` 确认 `search.mode=tfidf, vector_loaded=false`
+1. **部署 paramiko** ✅
+   - 在服务器 5.60 执行 `pip3 install --break-system-packages paramiko` 安装 5.0.0
+   - 重启服务验证 SSH 连接成功

-### ✅ 2.2 P2-2 移动端响应式适配（已部署）
+2. **增强错误分类** ✅
+   - `executor.py` 新增 `DependencyError`、`SSHConnectionError` 异常类
+   - 新增 `classify_ssh_error()` 函数，按异常类型返回 6 种错误码
+   - `BaseExecutor.test_connection()` 改为抛出分类后的异常

- `templates/index.html`：viewport + 三档断点 + 触控热区 ≥44px + 弹窗/代码块适配 + SSE 滚动
- `templates/login.html`：viewport + 移动端断点
- **验证**：Chrome DevTools iPhone 模拟，登录→搜索→AI 分析全流程正常
+3. **API 返回详细错误** ✅
+   - `target_service.test_connection()` 返回 `detail` + `error_code` 字段
+   - `routes.py` 直接返回完整结果
+   - 前端 `targets.html` 显示详细错误，鼠标悬停查看详情

-### ✅ 2.3 普通用户项目名称输入限制（已部署）
+4. **上传脚本增加依赖检查** ✅
+   - `deploy/upload_to_server.py` 新增 `_check_and_install_deps()` 函数
+   - 部署时自动检查并安装 paramiko/cryptography

- `routes/troubleshoot.py` 的 `/api/projects` 角色鉴权：普通用户返回 `[]`，管理员返回 120 项
- **验证**：`verify_deployment.py` 全通过，未登录调 `/api/projects` 返回 0 项
+5. **输出 PRD 文档** ✅
+   - `Docs/需求文档/服务监测/PRD_问题处理_SSH连接测试失败.md`
+   - `Docs/需求文档/服务监测/PRD_计划执行_SSH连接测试失败修复.md`

-### ✅ 2.4 平台化改造（已部署）
+**验证结果**：
+- 认证失败返回 `"认证失败：用户名或密码错误"` + `AUTH_FAILED`
+- 不可达 IP 返回 `"连接被拒绝：目标端口未开放或 SSH 服务未运行"` + `CONNECTION_REFUSED`
+- 连接成功返回 `"连接成功"`

- `utils/modules.py` **新建**：模块清单声明 + `get_modules(role)`，预留"服务监控"模块（`enabled: false`）
- `routes/platform.py` **新建**：平台首页路由 `/`，登录后显示模块卡片
- `templates/platform.html` **新建**：平台首页模板（渐变背景 + 卡片网格 + 响应式）
- `routes/auth.py`：删除原 `/` 路由（由 platform 接管）
- `routes/troubleshoot.py`：新增 `/troubleshoot` 页面路由 + `page_login_required`
- `templates/index.html`：顶部用户信息栏加"🏠 返回首页"链接
- `server.py`：注册 `platform` Blueprint
- **验证**：Chrome DevTools 确认 `/` 显示"运维辅助平台"首页，点击"问题排查助手"卡片进入 `/troubleshoot`，返回首页正常
+### 任务二：模块扩展 ✅

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

- 根目录 `ARCHITECTURE.md`：技术栈、项目结构、架构图、服务器部署、systemd 配置、环境变量、新增模块步骤
+2. **迁移 service 深度模块** ✅
+   - 从 `临时目录/服务器监测/lib/service/` 迁移 3 个模块到 `assets/service/`
+   - 模块：21_docker_deep、23_mysql_depth、25_redis_depth

-### ✅ 2.6 P2 级功能增强已提交推送（`b4fad0c1`）
+3. **新增业务容器监测** ✅
+   - 新建 `37_ustorage_check.sh`：容器状态、健康检查、存储容量与IO
+   - 新建 `38_utracker_check.sh`：容器状态、健康检查、处理能力

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

- 145 用例全绿（2.77s）
- `verify_deployment.py` 全通过
- Chrome DevTools 手动验证：首页 → 排查助手 → 返回首页
+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. 当前卡在哪

-**有一个未完成项**：用户要求修改密码，**尚未执行**：
- admin 密码改为 `Ubains@1357`
- 普通用户 user 密码改为 `Ubains@123`
-
-需要用 `auth.py` 的 `UserManager.update_password()` 生成 scrypt 哈希后更新 `users.json`，然后重新部署。
+**无卡点**。所有任务已完成，等待用户下一步指令。

-**平台化改造代码已部署但未提交 git**（6 个修改文件 + 5 个新文件）。
+工作区有未提交的改动（本次会话的修改），建议提交后再结束。

 ---

 ## 4. 下一步计划

-1. **修改用户密码**：更新 `users.json` 中 admin 和 user 的 `password_hash`，然后部署到 5.60
-2. **提交 git 并推送**：平台化改造 6 个修改文件 + 5 个新文件（含 ARCHITECTURE.md + modules.py + platform.py/html + PRD 文档），用 `/git-commit`
-3. **启用向量搜索（可选）**：将 `config.json` 的 `embedding_enabled` 改为 `true` + 执行 `python -m utils.vector_builder` 生成 `搜索向量.json` + 部署
-4. **接入"服务监控"模块**：在 `modules.py` 中将 `service-monitor` 的 `enabled` 改为 `true` + 创建对应的 Blueprint 和模板
+按优先级排序：
+
+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：删除 auth.py 的 `/` 路由时多删了 `render_template` 导入
- **现象**：删 `page_login_required` 导入时把 `render_template` 也删了，导致 `/login` GET 请求 500
- **原因**：`login()` 函数仍用 `render_template('login.html')`，但导入被一起删掉
- **避免**：删除导入前 grep 确认函数体内无引用
+### 坑 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 上传时没转换。

-### 🚨 坑 2：平台首页 `/` 与 auth 的 `/` 路由冲突
- **现象**：Flask 注册两个 Blueprint 都有 `/` 路由会报 `AssertionError: duplicate route`
- **避免**：平台化后 `/` 只由 `platform.py` 定义，`auth.py` 的 `/` 必须删除
+**避免**：
+- `upload_to_server.py` 已增加 `_sftp_put_unix_lines()` 自动转换 `.sh`/`.template` 文件
+- 未来上传脚本文档要强调换行符问题

-### 🚨 坑 3：向量功能关闭后测试 `test_vector_load_success` 失败
- **现象**：`config.json` 的 `embedding_enabled: false` 导致 `_load_vectors` 跳过加载
- **避免**：向量测试类加 `autouse` fixture 注入临时配置 `embedding_enabled: True`
+### 坑 3：templates/service_monitor 子目录未上传

-### 🚨 坑 4：conftest autouse 注入向量文件路径会干扰降级测试
- **避免**：autouse fixture 默认 `VECTOR_INDEX_PATHS=[]`，需要向量的测试单独注入路径
+**坑**：部署后模板目录为空，页面 404。

-### ⚠️ 坑 5：修改 `/api/projects` 返回值破坏现有测试
- **避免**：改后端 API 返回值时，必须同步检查并按角色拆分测试用例
+**原因**：`DIRS_TO_UPLOAD` 只上传一层文件，`templates/service_monitor/` 子目录被忽略。

-### ⚠️ 坑 6：平台首页 `/` 未登录时的重定向行为
- **注意**：`platform.py` 用 `session.get('user')` 手动判断，不用 `@page_login_required`（因为未登录应重定向而非返回 401），与 `auth.py` 原 `/` 行为一致
+**避免**：已修改上传脚本，子目录递归上传。
+
+### 坑 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. 关键文件与命令速查

-### 本次新增/修改的核心文件
-
-| 文件 | 状态 | 说明 |
-|------|------|------|
-| `skill/code/web/utils/modules.py` | **新增** | 模块清单声明 + `get_modules(role)` |
-| `skill/code/web/routes/platform.py` | **新增** | 平台首页路由 `/` |
-| `skill/code/web/templates/platform.html` | **新增** | 平台首页模板 |
-| `skill/code/web/utils/vector_builder.py` | **新增**（P2-1） | 向量预计算脚本 |
-| `skill/code/web/search_engine.py` | 修改 | 向量加载/查询/降级 + `get_search_mode()` |
-| `skill/code/web/routes/auth.py` | 修改 | 删除 `/` 路由 |
-| `skill/code/web/routes/troubleshoot.py` | 修改 | 新增 `/troubleshoot` 页面 + health 搜索模式 + projects 鉴权 |
-| `skill/code/web/server.py` | 修改 | 注册 platform Blueprint |
-| `skill/code/web/templates/index.html` | 修改 | 移动端适配 + 返回首页导航 |
-| `skill/code/web/templates/login.html` | 修改 | 移动端适配 |
-| `skill/code/web/config.json` | 修改 | `embedding_enabled: false` |
-| `skill/code/web/container.py` | 修改 | `load_config` 补 embedding 默认值 |
-| `skill/code/web/services/record_service.py` | 修改 | 同步重建向量 |
-| `skill/code/web/utils/paths.py` | 修改 | `VECTOR_INDEX_FILENAME` |
-| `deploy/upload_to_server.py` | 修改 | 补 search_engine.py + DEPLOY_FILES + 更新注释 |
-| `skill/code/tests/conftest.py` | 修改 | 向量 fixture + mock |
-| `skill/code/tests/test_search_engine.py` | 修改 | +12 向量用例 |
-| `skill/code/tests/test_routes_auth.py` | 修改 | TestIndex 适配平台首页 |
-| `skill/code/tests/test_routes_troubleshoot.py` | 修改 | projects 拆 3 角色用例 |
-| `ARCHITECTURE.md` | **新增** | 技术架构与部署说明 |
-| `Docs/PRD_需求文档_P2级功能增强.md` | **新增** | — |
-| `Docs/PRD_计划执行_P2级功能增强.md` | **新增** | — |
-| `Docs/PRD_需求文档_普通用户项目名称输入限制.md` | **新增** | — |
-| `Docs/PRD_计划执行_普通用户项目名称输入限制.md` | **新增** | — |
-| `Docs/PRD_需求文档_平台化改造与模块切换.md` | **新增** | — |
-| `Docs/PRD_计划执行_平台化改造与模块切换.md` | **新增** | — |
+### 本次修改的核心文件
+
+| 文件 | 用途 |
+|------|------|
+| `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
-# 全量单元测试（145 用例，应全绿）
-cd skill/code && python -m pytest -v
-
-# 部署到 5.60（用 ! 前缀在会话内执行）
-! cd "E:/github/ubains-module-test/troubleshoot-ai-assistant/deploy" && SSH_PASSWORD='***' python upload_to_server.py
+# 单元测试（51 用例，应全绿）
+cd skill/code && python -m pytest web/service_monitor/tests/ -v

-# 权威验证部署
-cd deploy && python verify_deployment.py
+# 部署到 5.60
+cd deploy && SSH_PASSWORD='***' python upload_to_server.py

-# 检查搜索模式
-curl -s http://192.168.5.60:8088/api/health | python -c "import sys,json; d=json.load(sys.stdin); print('mode:', d['search']['mode'])"
+# 登录密码
+admin / Ubains@1357

-# 修改用户密码（在 web/ 目录下执行）
-python -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('新密码'))"
-# 然后替换 users.json 中的 password_hash 字段
+# 健康检查
+curl -s http://192.168.5.60:8088/api/health

-# 生成向量文件（暂不执行，需 API 联网）
-cd skill/code/web && python -m utils.vector_builder
-```
-
-### Git 状态（未提交 — 平台化改造部分）
+# 快速巡检
+curl -s -b cookies.txt "http://192.168.5.60:8088/api/service-monitor/run/stream?target_id=local&suite=quick"

-```
- M deploy/upload_to_server.py
- M skill/code/tests/test_routes_auth.py
- M skill/code/web/routes/auth.py
- M skill/code/web/routes/troubleshoot.py
- M skill/code/web/server.py
- M skill/code/web/templates/index.html
-?? ARCHITECTURE.md
-?? Docs/PRD_需求文档_平台化改造与模块切换.md
-?? Docs/PRD_计划执行_平台化改造与模块切换.md
-?? skill/code/web/routes/platform.py
-?? skill/code/web/templates/platform.html
-?? skill/code/web/utils/modules.py
-?? HANDOFF.md
+# 全量巡检
+curl -s -b cookies.txt "http://192.168.5.60:8088/api/service-monitor/run/stream?target_id=local&suite=full"
 ```

-### 用户密码信息（待修改）
+### 参考目录

- admin：当前密码 `Admin@2026` → **改为** `Ubains@1357`
- user：当前密码未知（哈希存储） → **改为** `Ubains@123`
+- 参考脚本：`临时目录/服务器监测/lib/`
+- 需求文档：`Docs/需求文档/服务监测/`
+- 会话交接：`HANDOFF.md`