Initial commit: NetMesh smart ops platform with 3D topology, inspection reports, RCA and AI ops assistant

2026-10-15 13:53:04 +08:00
commit 2f9f8da48e
3299 changed files with 926841 additions and 0 deletions
--- a/docs/device-commands.md
+++ b/docs/device-commands.md
@@ -0,0 +1,282 @@
+# NetMesh 设备命令速查手册
+
+> 涵盖系统巡检（Inspection Adapter）和 RCA 根因分析（AI 诊断规划）两套命令集。
+> 版本：2026-10-13
+
+---
+
+## 目录
+
+- [1. 设备 Catalog 类型](#1-设备-catalog-类型)
+- [2. Linux 服务器（catalogId: `linux`）](#2-linux-服务器catalogid-linux)
+- [3. Windows 服务器（catalogId: `windows`）](#3-windows-服务器catalogid-windows)
+- [4. 华为/H3C 交换机（catalogId: `huawei_h3c_switch`）](#4-华为h3c-交换机catalogid-huawei_h3c_switch)
+- [5. Cisco 交换机（catalogId: `cisco_switch`）](#5-cisco-交换机catalogid-cisco_switch)
+- [6. 华为防火墙（catalogId: `huawei_firewall`）](#6-华为防火墙catalogid-huawei_firewall)
+- [7. 飞塔防火墙（catalogId: `fortinet_firewall`）](#7-飞塔防火墙catalogid-fortinet_firewall)
+- [8. Shell Prompt 匹配规则](#8-shell-prompt-匹配规则)
+- [9. RCA 诊断流程](#9-rca-诊断流程)
+
+---
+
+## 1. 设备 Catalog 类型
+
+| catalogId | 名称 | Shell | Adapter 实现 | 支持指标 | 默认巡检周期 |
+|---|---|---|---|---|---|
+| `linux` | Linux 服务器 | bash/sh | ✅ 有 | cpu, memory, disk, load, uptime, process_count, online | 5 分钟 |
+| `windows` | Windows 服务器 | PowerShell | ✅ 有 | cpu, memory, disk, uptime, process_count, service_status, online | 5 分钟 |
+| `huawei_h3c_switch` | 华为/H3C 交换机 | HUAWEI CLI | ✅ 有 | cpu, memory, port_status, power_status, fan_status, device_info, online | 10 分钟 |
+| `cisco_switch` | Cisco 交换机 | IOS CLI | ❌ 暂无 | cpu, memory, port_status, power_status, fan_status, online | 10 分钟 |
+| `huawei_firewall` | 华为防火墙 | HUAWEI CLI | ❌ 暂无 | cpu, memory, session_count, online | 5 分钟 |
+| `fortinet_firewall` | 飞塔防火墙 | FortiOS CLI | ❌ 暂无 | cpu, memory, session_count, online | 5 分钟 |
+
+> ⚠️ 暂无专用 adapter 的 catalog，巡检阶段复用 **HuaweiH3CSwitchAdapter**，因此实际执行的是华为 CLI 命令。但 AI RCA 会按 catalogId 正确选择对应厂商的命令族。
+
+---
+
+## 2. Linux 服务器（catalogId: `linux`）
+
+### Shell
+bash / sh（所有主流 Linux 发行版：Ubuntu / CentOS / Debian / Alpine / RHEL）
+
+### 实际巡检命令（系统在用）
+
+| 指标 | 命令 |
+|---|---|
+| CPU | `top -bn1 2>/dev/null \| head -n 5`（兜底 `mpstat 1 1 2>/dev/null \| tail -n 1`） |
+| 内存 | `free -k 2>/dev/null \| head -n 2 \| tail -n 1`（兜底 `cat /proc/meminfo 2>/dev/null \| head -n 3`） |
+| 磁盘 | `df -h 2>/dev/null \| tail -n +2 \| grep -v '/dev/loop'` |
+
+### RCA 诊断命令（按告警类型）
+
+| 告警类型 | 推荐命令（最多 6 条） |
+|---|---|
+| CPU 高 | `top -bn1 \| head -20`, `vmstat 1 2`, `ps aux --sort=-%cpu \| head -10`, `mpstat -P ALL 1 1` |
+| 内存高 | `free -m`, `cat /proc/meminfo \| head -20`, `ps aux --sort=-%mem \| head -10`, `slabtop -s c` |
+| 磁盘高 | `df -h`, `du -sh /* 2>/dev/null \| sort -rh \| head -10`, `iostat -x 1 1 2>/dev/null \|\| echo no_iostat` |
+| 网络 | `ip -s link`, `netstat -s`, `lsof -i` |
+| 离线/连通性 | `ping -c 3 <host>`, `traceroute <host>`, `ip route` |
+| 通用体检 | `uname -a`, `uptime`, `dmesg \| tail -50`, `journalctl -xe --no-pager \| tail -50` |
+
+### Prompt 匹配
+```
+user@host:~$         # bash/zsh
+user@host:/path#     # bash 特权
+root@host:~#         # root
+```
+
+---
+
+## 3. Windows 服务器（catalogId: `windows`）
+
+### Shell
+PowerShell（通过 `powershell -NoProfile -NonInteractive -EncodedCommand <base64>` 执行 UTF-16LE Base64 编码脚本）
+
+### 实际巡检命令（系统在用）
+
+| 指标 | PowerShell 脚本摘要 |
+|---|---|
+| CPU + 内存 + 运行时间 | `Get-WmiObject Win32_Processor` + `Get-WmiObject Win32_OperatingSystem` |
+| 磁盘 | `Get-WmiObject Win32_LogicalDisk -Filter "DeviceID='C:'"` |
+| 服务状态 | `Get-Service` 检查 wuauserv / Spooler / TermService / DHCP / DNScache |
+
+### RCA 诊断命令（直接用 PowerShell 可执行形式）
+
+| 告警类型 | 推荐命令（最多 5 条） |
+|---|---|
+| CPU 高 | `Get-Process \| Sort-Object CPU -Descending \| Select-Object -First 10` |
+| 内存高 | `Get-CimInstance Win32_OperatingSystem \| Select TotalVisibleMemorySize,FreePhysicalMemory` |
+| 磁盘高 | `Get-CimInstance Win32_LogicalDisk \| Where-Object {$_.DriveType -eq 3}` |
+| 服务异常 | `Get-Service \| Where-Object {$_.Status -ne 'Running'} \| Select Name,Status` |
+| 系统日志 | `Get-EventLog -LogName System -Newest 50 \| Select TimeGenerated,EntryType,Message` |
+| 网络 | `Get-NetAdapter \| Select Name,Status,LinkSpeed`, `netstat -ano` |
+| 通用体检 | `Get-ComputerInfo`, `systeminfo` |
+
+---
+
+## 4. 华为/H3C 交换机（catalogId: `huawei_h3c_switch`）
+
+### Shell
+Huawei VRP CLI / H3C Comware CLI（SSH 登录后进入 enable 模式）
+
+### 实际巡检命令（系统在用，批量一次执行）
+
+| 指标 | 命令 | 备注 |
+|---|---|---|
+| CPU | `display cpu-usage` | 解析 `% in last 5 seconds` / `CPU Usage: XX%` |
+| 内存 | `display memory` | 解析 `Used Rate: XX%` / `Memory Using Percentage Is: XX%` |
+| 端口状态 | `display interface brief` | 匹配 `GE1/0/1 UP/DOWN` / `GigabitEthernet... UP/DOWN` |
+| 电源状态 | `display power` | 匹配 `Normal` / `Fault` / `Absent` |
+| 风扇状态 | `display fan` | 匹配 `Normal` / `Fault` / `Absent` |
+
+### RCA 诊断命令
+
+| 告警类型 | 推荐命令（最多 6 条） |
+|---|---|
+| CPU 高 | `display cpu-usage`, `display device`, `display version` |
+| 内存高 | `display memory`, `display version`, `display current-configuration` |
+| 端口异常 | `display interface brief`, `display interface <ifname>`, `display mac-address` |
+| 电源/风扇告警 | `display power`, `display fan`, `display environment` |
+| STP 环路 | `display stp brief`, `display stp topology-change` |
+| VLAN 问题 | `display vlan brief`, `display vlan <id>` |
+| 网关/路由 | `display ip routing-table`, `display vrrp brief` |
+| 日志排查 | `display logbuffer`, `display logbuffer size 512` |
+| 通用体检 | `display version`, `display device`, `display diagnostic-information` |
+
+### Prompt 匹配
+```
+<host>              # HUAWEI VRP 用户模式
+<host>              # HUAWEI VRP 特权模式
+host>               # H3C Comware
+host#               # H3C Comware 特权
+```
+
+---
+
+## 5. Cisco 交换机（catalogId: `cisco_switch`）
+
+### Shell
+Cisco IOS CLI / IOS-XE CLI
+
+> ⚠️ 当前暂无专用巡检 adapter，复用华为交换机 adapter。AI RCA 会按 catalogId 正确选 Cisco 命令族。
+
+### RCA 诊断命令（Cisco IOS 风格）
+
+| 告警类型 | 推荐命令 |
+|---|---|
+| CPU 高 | `show processes cpu sorted`, `show processes cpu history` |
+| 内存高 | `show memory summary`, `show memory allocations process sort` |
+| 端口异常 | `show interfaces brief`, `show interfaces counters errors`, `show interfaces trunk` |
+| 电源/风扇告警 | `show environment all`, `show inventory` |
+| STP | `show spanning-tree summary`, `show spanning-tree inconsistentports` |
+| VLAN | `show vlan brief`, `show vtp status` |
+| 路由/网关 | `show ip route summary`, `show ip interface brief`, `show standby brief` |
+| 日志 | `show logging tail 50`, `show logging`, `terminal length 0`（禁用分页后重定向） |
+| MAC 地址表 | `show mac address-table count`, `show mac address-table interface <ifname>` |
+| ARP | `show arp`, `show ip arp inspection statistics` |
+| 通用体检 | `show version`, `show environment`, `show controllers power inline` |
+
+### Prompt 匹配
+```
+Switch>             # IOS 用户模式
+Switch#             # IOS 特权模式
+hostname>           # IOS-XE
+hostname#
+```
+
+---
+
+## 6. 华为防火墙（catalogId: `huawei_firewall`）
+
+### Shell
+Huawei USG VRP CLI
+
+> ⚠️ 当前暂无专用巡检 adapter，复用华为交换机 adapter。
+
+### RCA 诊断命令
+
+| 告警类型 | 推荐命令 |
+|---|---|
+| CPU/内存高 | `display cpu-usage`, `display memory`, `display version` |
+| 会话数异常 | `display firewall session table`, `display firewall session table verbose` |
+| 安全策略 | `display security-policy count`, `display security-policy rule all` |
+| 服务器保护 | `display server-protect statistics`, `display server-protect attack-log` |
+| NAT | `display nat session table`, `display nat policy` |
+| 资源/连接数 | `display firewall statistic system`, `display ip session aging` |
+| 接口状态 | `display interface brief`, `display ip interface brief` |
+| 路由 | `display ip routing-table`, `display ip routing-table statistics` |
+| 日志 | `display logbuffer`, `display alarm all` |
+| 通用体检 | `display version`, `display current-configuration` |
+
+---
+
+## 7. 飞塔防火墙（catalogId: `fortinet_firewall`）
+
+### Shell
+FortiOS CLI
+
+> ⚠️ 当前暂无专用巡检 adapter，复用华为交换机 adapter。
+
+### RCA 诊断命令
+
+| 告警类型 | 推荐命令 |
+|---|---|
+| CPU/内存 | `get system status`, `get system performance status`, `get system performance cpu`, `get system performance memory` |
+| 会话数 | `get firewall session list`, `get firewall session list <count>`, `diagnose sys session stat` |
+| 接口 | `get system interface`, `get hardware nic`, `diagnose hardware deviceinfo nic` |
+| 路由 | `get router info routing-table all`, `get config route static` |
+| 策略 | `get firewall policy all`, `get firewall policy count` |
+| NAT | `get firewall nat all`, `get firewall nat count` |
+| VPN | `get vpn ipsec tunnel summary`, `get vpn ssl monitor` |
+| 资源/DoS | `get system resource usage`, `diagnose dos stat`, `diagnose debug flow stat` |
+| 硬件 | `get hardware status`, `get hardware psu`, `get hardware fan` |
+| 日志 | `execute log tail <lines>`, `get router info log dmesg` |
+| 通用体检 | `get system status`, `get system info`, `diagnose sys top` |
+
+---
+
+## 8. Shell Prompt 匹配规则
+
+文件位置：`electron/bridges/inspection/promptParser.cjs`
+
+巡检命令发送前，SSH 通道已就绪但不知道 shell 类型，需要等 prompt 出现才发命令。当前正则：
+
+| Shell 类型 | Prompt 正则 |
+|---|---|
+| Linux bash/zsh | `user@host[:~$#]`、`root@host[:~#]` |
+| 华为/H3C | `<hostname>`、`hostname>`、`hostname#` |
+| Cisco IOS | `Switch[>#]`、`hostname[>#]` |
+| FortiOS | `FortiGate[>#]`、`hostname[>#]` |
+
+⚠️ 避免用 `%` 作为通用 prompt 结尾 —— 命令输出中的百分比数值会被误识别为 prompt。
+
+---
+
+## 9. RCA 诊断流程
+
+### 触发
+
+告警中心 → 点告警行的 🤖 按钮
+
+### 执行链路
+
+```
+runRCA(alert)
+  │
+  ├─ Phase 1: AI 规划诊断命令
+  │   prompt 顶部带 catalogId（来自 inspectionHostMetrics / inspectionHostInfo）
+  │   AI 输出 JSON: { commands: [{ command, purpose }, ...], reasoning }
+  │
+  ├─ Execute: 复用 SSH session 执行命令
+  │   ├─ echo __rca_probe_ok__ 探活
+  │   ├─ 没有 SSH session → vaultHostOpen 自动开终端 tab
+  │   └─ 逐条 inspectionRunCommand（SSH session.exec）
+  │
+  ├─ Phase 2: AI 综合 RCA
+  │   输入：告警 + metrics + 所有命令 stdout/stderr
+  │   输出：{ confidence, rootCauses, recommendations[], summary }
+  │
+  └─ 前端渲染（证据区可折叠展开 stdout）
+```
+
+### 关键设计
+
+| 设计点 | 说明 |
+|---|---|
+| SSH 连接复用 | 不独立建 SSH —— 用主进程 `sessions` Map 里已有终端的 `conn.exec()` |
+| 自动开终端 | 没有 session 时调 `vaultHostOpen` 创建 tab + 等 SSH 连上（最多 10 秒轮询） |
+| Policy 绕过 | `policy.requiresChatSession: false` 的 capability 跳过 `chatSessionId` 强制检查 |
+| API Key 安全 | aiFetch 请求 header 用 `__IPC_SECURED__` placeholder → 主进程用 providerId 解密注入 |
+| Host allowlist | RCA 开头调 `aiAllowlistAddHost` 预注册 provider baseURL |
+| Prompt 可配置 | 设置 → AI → RCA 诊断 tab，运维可覆盖 Phase 1 / Phase 2 的 system prompt |
+| Fallback | 无 AI provider → 确定性兜底（按 catalogId 挑内置命令 + 规则合成 RCAResult） |
+
+### 命令执行 handler 位置
+
+- **巡检**：`electron/bridges/inspection/index.cjs` → `registerInspectionHandlers`（主进程启动时注册到 ipcMain）
+- **RCA**：`electron/bridges/mcpServerBridge/inspectionAgentHandlers.cjs` → `handleRunCommand`（MCP dispatch 路由到）
+- **SSH 执行底层**：`electron/bridges/inspection/inspectionExec.cjs` → `execSshCommand` / `execSshCommands`（prompt 检测 + 批量发送）
+
+---
+
+*本手册自动维护，基于项目 inspection adapters 和 RCA prompt 对照表生成。*