# 需求文档：检测项丰富化（参考目录移植）

## 文档信息

- 创建时间：2026-07-22
- 需求来源：用户需求
- 关联模块：service_monitor
- 参考目录：`E:\GithubData\ubains-module-test\platform-auto-test\临时目录\服务监测\`

---

## 1. 背景与目标

### 1.1 背景

当前服务监测模块有 30 个检测脚本（13 系统 + 17 服务），display_names.py 收录 539 个检测项 KEY。用户希望对比参考目录（老版 PowerShell + Shell 巡检工具集）继续丰富检测项。

参考目录是平台自动化测试项目中的旧版巡检工具，采用 PowerShell 模块 + Shell 脚本混合架构，检测维度比当前项目更广。

### 1.2 目标

1. **补全已有脚本输出但未收录的 KEY**：当前部分脚本输出的 KEY 未在 display_names.py 中定义
2. **重构 depth 脚本**：`23_mysql_depth.sh` 和 `25_redis_depth.sh` 使用 `echo` 而非 `output_result`，需重构以适配标准解析器
3. **移植参考目录特有的全新检测类别**：18 类新检测项

---

## 2. 当前项目已有检测类别（30 个脚本）

### 系统类（13）
01_system_basic, 02_cpu_check, 03_memory_check, 04_disk_check, 05_oom_check, 06_process_check, 07_network_check, 11_scheduled_tasks, 12_port_check, 40_comprehensive_diagnosis, 43_security_compliance, 44_system_logs, 45_time_sync

### 服务类（17）
20_docker_basic, 21_docker_deep, 22_mysql_basic, 23_mysql_depth, 24_redis_basic, 25_redis_depth, 26_emqx_basic, 27_emqx_deep, 28_java_check, 29_python_check, 30_nginx_check, 31_nacos_check, 33_app_logs, 34_nginx_deep, 35_nacos_deep, 37_ustorage_check, 38_utracker_check

---

## 3. 阶段一：补全已有脚本缺失的 KEY

### 3.1 display_names.py 缺失项

| 模块 | 缺失 KEY | 中文名 |
|------|---------|--------|
| 03_memory | VM_PGMajFAULT | 主缺页错误数 |
| 21_docker_deep | DOCKER_DAEMON_CPU | Docker守护进程CPU |
| 21_docker_deep | DOCKER_DAEMON_MEM | Docker守护进程内存 |
| 34_nginx_deep | NGINX_CONTAINER_LEVEL | Nginx容器级别 |
| 35_nacos_deep | NACOS_CONTAINER_LEVEL | Nacos容器级别 |

### 3.2 depth 脚本重构

**23_mysql_depth.sh** 当前用 `echo "KEY:value"`，需改为 `output_result "KEY" "value"`，KEY 加 `MYSQL_DEPTH_` 前缀避免冲突：

| 当前 KEY | 重构后 KEY | 中文名 |
|---------|-----------|--------|
| hit_rate | MYSQL_DEPTH_BUFFER_POOL_HIT_RATE | 缓冲池命中率 |
| slow_enabled | MYSQL_DEPTH_SLOW_QUERY_ENABLED | 慢查询日志开启 |
| slow_count | MYSQL_DEPTH_SLOW_QUERY_COUNT | 慢查询数量 |
| conn_rate | MYSQL_DEPTH_CONNECTION_USAGE | 连接使用率 |
| io_running | MYSQL_DEPTH_SLAVE_IO_RUNNING | 从库IO线程 |
| sql_running | MYSQL_DEPTH_SLAVE_SQL_RUNNING | 从库SQL线程 |
| seconds_behind | MYSQL_DEPTH_SLAVE_DELAY | 主从延迟秒数 |
| table_count | MYSQL_DEPTH_TABLE_COUNT | 表数量 |
| qps | MYSQL_DEPTH_QPS | 每秒查询数 |
| uptime | MYSQL_DEPTH_UPTIME_DAYS | 运行天数 |
| ... | ... | ... |

**25_redis_depth.sh** 同理，KEY 加 `REDIS_DEPTH_` 前缀。

---

## 4. 阶段二：移植全新检测类别（18 类）

### P1 优先级（深度检测 + 安全 + 中间件连接）

| 编号 | 新模块 | 检测项 | 参考来源 |
|------|--------|--------|---------|
| 46 | MySQL深度检测（重构） | 缓冲池命中率、慢查询、连接使用率、主从复制、TOP大表、QPS基线 | check_mysql_deep.sh, MiddlewareCheck.psm1 |
| 47 | Redis深度检测（重构） | RDB/AOF持久化、内存碎片率、缓存命中率、主从复制、键空间统计 | check_redis.sh, MiddlewareCheck.psm1 |
| 48 | 安全合规深度检测 | MySQL Root访问范围、空密码用户、Redis密码、EMQX默认密码、SUID文件、异常crontab、SSH暴力破解、异常端口 | SecurityCheck.psm1 |
| 49 | 中间件连接检测 | MQTT订阅、MQTT推送、Redis连接、MySQL连接、FastDFS上传下载 | middleware_check.sh, MiddlewareCheck.psm1 |

### P2 优先级（平台服务检测）

| 编号 | 新模块 | 检测项 | 参考来源 |
|------|--------|--------|---------|
| 50 | 系统类型识别 | ujava/upython/upython_voice 变体识别 | ServerProfile.psm1 |
| 51 | 平台服务检测 | auth/gateway/system/meeting/mqtt/quartz/message/extapi 服务状态 | ServiceCheck.psm1 |
| 52 | 配置IP检测 | 硬编码IP扫描、配置文件IP检查 | ConfigIPCheck.psm1, config_check.sh |
| 53 | Console配置检测 | true→false 配置检查 | check_server_health.sh |

### P3 优先级（辅助功能）

| 编号 | 新模块 | 检测项 | 参考来源 |
|------|--------|--------|---------|
| 54 | 文件权限检测 | 关键文件权限检查 | FilePermission.psm1 |
| 55 | 定时任务预期检测 | 预期任务缺失检测 | check_server_health.sh |
| 56 | FastDFS功能验证 | 上传/下载/完整性测试 | check_fdfs_arm.sh |
| 57 | Android设备检测 | adb连接、日志导出 | AndroidCheck.psm1 |
| 58 | 数据备份检测 | MySQL dump、打包、下载 | DataBackup.psm1 |
| 59 | 配置日志导出 | 远程配置/日志拉取 | LogExport.psm1 |
| 60 | 修复能力检测 | DNS/NTP/端口/容器修复链 | issue_handler.sh |

---

## 5. 技术方案

### 5.1 每个新模块的完整实现

每个新检测类别需要：

1. **bash 脚本**：`assets/system/XX_name.sh` 或 `assets/service/XX_name.sh`
   - 遵循现有脚本格式：加载 config.sh + common.sh，使用 `output_result "KEY" "value"`
   - 容器名用 `CONTAINERS[name]` 模糊匹配模式
2. **模块注册**：`check_modules.py` 的 `ALL_MODULES` 列表新增 `CheckModule` 条目
3. **显示名**：`display_names.py` 新增 KEY→中文名映射
4. **阈值**（如适用）：`thresholds.py` 新增阈值规则
5. **config 模板**（如需凭据）：`config.sh.template` 新增容器/凭据配置
6. **上传清单**：`deploy/upload_to_server.py` 确认脚本会被上传（assets 目录已整体上传）

### 5.2 移植注意事项

- **参考目录是 PowerShell**：需翻译为 bash，保留检测逻辑
- **参考目录是 Shell 老格式**：需适配 `output_result` 标准输出
- **容器名匹配**：参考目录用精确名，本项目用 `grep -iE` 模糊匹配
- **凭据注入**：参考目录硬编码，本项目用 `__占位符__` + executor 渲染
- **阈值**：参考目录内嵌，本项目用 `thresholds.py` 集中管理

### 5.3 测试策略

每个新模块：
1. 本地语法检查：`bash -n script.sh`
2. 单元测试：`check_modules.test_get_suite` 等已有测试通过
3. 部署后在目标机实际运行验证
4. 统计页面确认新检测项出现在选择器中

---

## 6. 验收标准

| 标准 | 验证方法 |
|------|---------|
| display_names.py 缺失项补全 | 脚本输出 KEY 都有中文名 |
| depth 脚本重构完成 | 用 output_result 格式，统计页面可识别 |
| 新模块 bash 脚本创建 | 语法检查通过 |
| check_modules.py 注册 | get_suite('full') 包含新模块 |
| display_names.py 新增映射 | 新 KEY 有中文名 |
| 统计页面显示新检测项 | 选择器中出现新模块和检测项 |
| 单元测试通过 | pytest 全绿 |

---

## 7. 风险评估

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 工作量大，单会话无法完成 | 进度缓慢 | 分阶段实现，每阶段独立可部署 |
| bash 脚本在目标机环境差异 | 检测失败 | 容器名模糊匹配 + 命令存在性检查 |
| 参考目录逻辑复杂 | 移植出错 | 保留核心检测逻辑，简化边缘功能 |
| 新增 KEY 命名冲突 | 解析混乱 | 加模块前缀（MYSQL_DEPTH_ 等） |

---

## 8. 执行路线图

- **阶段一**（本次）：补全 display_names 缺失项 + 重构 2 个 depth 脚本
- **阶段二**：P1 优先级 4 个新模块（MySQL深度/Redis深度/安全合规深度/中间件连接）
- **阶段三**：P2 优先级 4 个新模块（系统类型/平台服务/配置IP/Console配置）
- **阶段四**：P3 优先级 7 个新模块（文件权限/定时任务预期/FastDFS/Android/数据备份/日志导出/修复能力）
