# SwitchMonitor

**Repository Path**: you1217/SwitchMonitor

## Basic Information

- **Project Name**: SwitchMonitor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 26
- **Forks**: 13
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SwitchMonitor 交换机监控系统

> 轻量级、高可用的企业级交换机监控与 NetDevOps 自动化运维平台，跑通"数据采集 → 时序存储 → 阈值告警 → 可视化展示 → 自动化巡检与安全审计"完整闭环。
> 支持多协议（SNMP + CLI + ICMP + Trap + Syslog）、设备离线深度告警、配置合规审计、24/48口拟真前面板矩阵、NOC 驾驶舱大屏。

当前版本: **v2.6.0** (最新稳定版)

## 🚀 最近更新说明 (v2.4 ~ v2.6)

### 【v2.6.0 维护与缺陷修复】(2026-09-10)
- **未纳管设备 SNMP Trap 智能过滤与告警抗干扰**：非系统纳管设备 Trap 报文直接静默丢弃（不落库、不广播、不打印冗余日志），启动时自动自愈清理历史残留无效记录，彻底杜绝局域网心跳刷屏与对全局端口告警的干扰。
- **巡检报告导出全链路修复 (PDF 与 HTML)**：后端重构 `loadCJKFont` 支持跨平台（Windows / Linux / Docker）多路径自动探测与 TrueType (`.ttf`) 格式回退，彻底解决 PDF 导出 500 异常；前端批量巡检 HTML 报告导出迁移至统一 HTTP 客户端，增加 Token 鉴权自动续期与 Blob JSON 错误反序列化解析。
- **构建与发布工具自适应路径支持**：`scripts/build/build_v26.py` 改为动态获取项目根目录，支持 Windows、Linux、Docker 三大平台在不同工作区下平滑自动化编译与打包。

### 【v2.6.0】深度代码质量审计、安全加固与高并发重构 (2026-09-08)
- **Web 终端防越权与 CSWSH 防护**：WebSocket 握手实施严格的同源与白名单校验，强制非管理员角色拦截，杜绝跨站劫持与未授权访问。
- **凭证敏感信息脱敏与透明解密**：非管理员 SNMP Community 统一脱敏为掩码；设备探测、候选发现、LLDP 导入与画像自检打通透明解密链路，彻底消除凭证加密后 SNMPv3 鉴权失败问题。
- **数据库连接池定制与防锁表**：针对 PostgreSQL（50 max / 10 idle）与 SQLite（10 max / 5 idle）动态配置连接池参数，彻底杜绝连接耗尽与 SQLite 锁表崩溃。
- **Trap / Syslog 异步 Worker 协程池与 IP 缓存加速**：解耦网络高频接收与磁盘数据库 IO，引入 1000/2000 缓冲队列与 Worker 并发消费，结合设备 IP 内存缓存防穿透。
- **报表防 OOM 与批量任务即时取消**：报表统计跨度限制最大 90 天且历史告警限制 5000 条防 OOM；批量 CLI 支持随时上下文响应取消中断下发。
- **前端全链路实时事件流与角色守卫**：WebSocket 消息流支持 Trap 与 Syslog 实时推送到设备详情页无刷新更新；前端路由为终端与批量 CLI 增加超级管理员角色守卫与自动拦截。

### 【v2.5.0】秒级自愈恢复、跨库零损平移与生产加固 (2026-09-08)
- **交换机通信恢复秒级自愈与秒级恢复通知**：ICMP 高频探测与调度引擎深度联动，设备重新上线毫秒级探测命中时，秒级解除离线告警并推送恢复通知，告警自愈响应从分钟级大幅缩减至秒级。
- **关系型数据库 100% 全量无损平移 (SQLite ↔ PostgreSQL / 换库)**：支持全部 30 张业务表、关联关系与版本记录的流式迁移，具备 **Canary 防自毁金丝雀探针**，杜绝同一实例误清空；支持 PostgreSQL 序列自动校准，彻底解决主键冲突。
- **思科/锐捷/中兴特权模式自动提权 (Auto Enable)**：针对配置备份与批量巡检，自动尝试使用登录密码提权执行特权命令，解决密码受限导致的数据无法抓取。
- **配置备份中文编码智能转码**：自动适配 GBK / GB18030 / UTF-8，彻底解决现网交换机中文描述与注释乱码。
- **单镜像一体化生产部署**：单一容器端口同时承载前端 Web UI、REST API、SNMP Trap (UDP 162) 与 Syslog (UDP 514)，无需额外搭建 Nginx。

### 【v2.4.0】设备离线深度感知与智能恢复 (2026-09-04)
- **设备离线连续探测判定**：连续 2 次探测失败即触发离线告警，有效过滤网络偶发丢包与微抖动误报。
- **离线专属未恢复周期重推**：支持 30m / 1h / 2h 周期性重推告警，关键故障杜绝遗漏。
- **智能恢复语义转换**：支持自定义恢复通知标题，未配置时智能转换故障语义（如“离线 → 已恢复通信”）。
- **拓扑动态流量粒子流动**：拓扑连接边引入 SVG 动态粒子流速动画（Traffic Particles Flow），实时直观展示链路负荷。

## 文档导航

- [说明文档.md](./说明文档.md) — 项目全生命周期管理载体
- [docs/v2.6/RELEASE_NOTES_v2.6.md](./docs/v2.6/RELEASE_NOTES_v2.6.md) — **v2.6 最新发布说明与核心特性** 🚀
- [docs/v2.5/RELEASE_NOTES_v2.5.md](./docs/v2.5/RELEASE_NOTES_v2.5.md) — v2.5 发布说明与核心特性
- [docs/v2.1/RELEASE_NOTES_v2.1.md](./docs/v2.1/RELEASE_NOTES_v2.1.md) — v2.1 发布说明与核心特性
- [docs/v2.1/TASK_v2.1.md](./docs/v2.1/TASK_v2.1.md) — v2.1 任务执行与交付跟踪
- [docs/v1.0/](./docs/v1.0/)
  - [ALIGNMENT_v1.0.md](./docs/v1.0/ALIGNMENT_v1.0.md) — 需求与边界对齐
  - [CONSENSUS_v1.0.md](./docs/v1.0/CONSENSUS_v1.0.md) — 共识文档
  - [DESIGN_v1.0.md](./docs/v1.0/DESIGN_v1.0.md) — 系统架构与模块设计
  - [TASK_v1.0.md](./docs/v1.0/TASK_v1.0.md) — 任务拆分

## 技术栈

- **后端**:Go 1.25 / Gin / GORM(v2) / gosnmp / influxdb-client-go / pro-bing
- **前端**:React 18 / Vite 5 / TypeScript / ECharts / reactflow / @xterm/xterm
- **存储**:SQLite(开发)/ PostgreSQL(生产) + InfluxDB 2.x(时序)
- **告警**:钉钉 / 飞书 / 企业微信 / 邮件
- **部署**:Docker / docker-compose

## 核心功能

- **全协议网络监控**:
  - **SNMP 状态采集**: 端口流量/错包、CPU、内存、温度、风扇、电源、传感器；基于 `sysObjectID` 的 OID 自动画像 + 自愈回写，无需改代码适配 Cisco / Huawei / H3C / Ruijie / ZTE 等设备；
  - **ICMP / Ping 存活与抖动**: 15s 高频 Ping 探测引擎，计算网络时延、丢包率与 Jitter 抖动时序；
  - **SNMP Trap (UDP 162)**: 实时捕获 LinkUp / LinkDown / ColdStart / WarmStart 事件并广播；
  - **Syslog (UDP 514)**: RFC 3164/5424 日志集中收集检索与告警级别映射；
  - **PoE 以太网供电监控与控制**: 端口供电功率与负荷采集，支持远程硬断电重启与开关供电；
- **NetDevOps 自动化运维**:
  - **批量 CLI 执行与巡检**: 预设 4 套巡检模板、自动适配多厂商语法、一键导出 HTML 自动化巡检报告；
  - **安全基线合规审计**: 扫描弱口令、默认团体名、明文 Telnet 与 Syslog 配置，量化 0~100 分安全得分；
  - **配置备份与分时调度**: 支持单设备独立开启/关闭自动备份、专属执行时刻设定（分时巡检）、SSH/Telnet 自动/手动备份、gzip 压缩、双列差异对比与一键回滚；
  - **配置变更精细化告警**: 配置变更纳入告警规则引擎，支持按设备开关、自定义告警级别与指定通知推送渠道；
- **工业级拟真可视化**:
  - **24/48 口物理前面板矩阵**: 19 英寸机架金属拟真面板，四重多模式 LED（Link/Speed/PoE/Traffic）；
  - **网络拓扑与流量热力**: LLDP 自动拓扑、机房区域分组背景框、全网链路流量热力着色与流速粒子流动；
  - **NOC 大屏驾驶舱**: 专为运维中心设计的高清全屏大屏监控视图；
- **安全与可观测性**:
  - **安全加固**: JWT 双令牌、登录失败限流锁定、图形验证码、敏感凭证 AES-256-GCM 加密；
  - **生命周期清理**: 每 24 小时自动清理过期告警、Trap/Syslog、审计日志与无效 Token；
  - **性能极致调优**: Vite Manual Chunks 细粒度分包，首屏体积缩减超 54%。

## 目录结构

```
switch-monitor/
├── cmd/
│   ├── server/             # 主服务入口(main.go / seed.go)
│   └── tools/              # 运维辅助工具集(23 个子命令,见下)
├── internal/
│   ├── alert/              # 告警引擎(阈值/聚合降噪/维护静默)
│   ├── auth/               # 认证鉴权(JWT 双令牌/验证码/限流)
│   ├── cli/                # CLI 采集(光模块 DDM 等 SNMP 拿不到的数据)
│   ├── common/             # 通用工具
│   ├── config/             # 配置加载(.env + config.yaml)
│   ├── configbackup/       # 配置备份/差异/回滚(多厂商)
│   ├── crypto/             # 敏感字段 AES-256-GCM 加密
│   ├── database/           # GORM 连接与数据模型(SQLite/PostgreSQL)
│   ├── discovery/          # 网络发现扫描器
│   ├── influx/             # InfluxDB 时序写入(支持热切换)
│   ├── maintenance/        # 计划维护窗口(静默告警)
│   ├── metrics/            # Prometheus exporter + 指标预测/基线
│   ├── mib/                # MIB 库解析(OID 匹配)
│   ├── notify/             # 通知渠道(钉钉/飞书/企微/邮件)
│   ├── report/             # 报表生成(Excel / PDF)
│   ├── scheduler/          # 采集调度器(周期采集/拓扑/基线/报表)
│   ├── server/             # Gin HTTP 路由装配与静态资源托管
│   ├── snmp/               # SNMP 采集客户端与解析(多厂商)
│   ├── ssh/                # SSH/Telnet 客户端
│   ├── terminal/           # Web 终端会话管理
│   └── ws/                 # WebSocket hub(实时告警推送)
├── web/                     # 前端(React + Vite)
├── configs/                 # 配置示例
├── scripts/                 # 部署/运维脚本
├── docs/v1.0/               # 6A 工作流文档
├── Dockerfile / docker-compose.yml
├── go.mod
└── README.md
```

## 快速开始

### 方式一:本地运行

```bash
# 1. 准备环境变量
cp .env.example .env
# 编辑 .env,填入你的配置(InfluxDB/PostgreSQL/Webhook 等)

# 2. 下载依赖
go mod tidy

# 3. 编译
go build -o bin/switch-monitor ./cmd/server

# 4. 运行(首次启动会 seed 演示数据、默认 admin 用户)
./bin/switch-monitor

# 5. 验证
curl http://localhost:8080/healthz
```

前端(`web/`)单独以 Vite 开发服务器运行,或随 Docker 一起构建。

### 方式二:Docker 部署

```bash
# 启动后端(8080) + 前端(80)
docker compose up -d
```

> 注:`docker-compose.yml` 编排 backend 与 frontend 两个服务;InfluxDB / PostgreSQL 作为外部依赖需另行提供。

### 服务子命令

```bash
./bin/switch-monitor            # 启动主服务(采集 + 告警 + HTTP API)
./bin/switch-monitor version    # 输出版本信息
./bin/switch-monitor help       # 帮助
./bin/switch-monitor default-config  # 生成最小化 config.yaml 到 stdout
```

### 运维工具(`cmd/tools`)

提供 23 个独立子命令,涵盖设备/厂商探测、MIB 工具、光模块查询、数据库运维、诊断等,例如:

- 厂商探测:`probe-huawei` / `probe-h3c` / `probe-ruijie` / `probe-optical` 等
- MIB 工具:`mibdump` / `mibverify`
- 数据库运维:`sqlite-exec` / `sqlite-query` / `fix-communities` / `reset-channels`
- 诊断:`diag-profile` / `stage4-check` / `stage4-overview`

## 前端页面

- 仪表盘 `/dashboard`、NOC 大屏 `/dashboard/noc`
- 设备管理 `/devices`(列表/新增/导入/发现/详情/端口/终端)
- 拓扑图 `/topology`
- MIB 库 `/mib-library`
- 告警规则 `/alert-rules`、告警事件 `/alert-events`
- 报表 `/reports`、维护窗口 `/maintenance-windows`
- 通知渠道 `/notify-channels`、系统设置 `/settings`
- 登录 `/login`(受 ProtectedRoute 保护)

## 当前版本与开发里程碑

- [x] **v1.0 ~ v1.8 基础能力**: SNMP 多指标采集、告警引擎 + 四通道通知、Web 拟真前面板、JWT 双令牌、配置备份、Web 终端
- [x] **v2.1 全协议监控**: ICMP 高频抖动分析、SNMP Trap (UDP 162)、Syslog (UDP 514)、PoE 供电控制、安全基线合规审计
- [x] **v2.2 自动化运维**: 设备通信自愈、Admin Shutdown 告警过滤、自适应带宽利用率告警、多厂商 CLI 巡检
- [x] **v2.3 架构升级**: 前端工作台架构优化、多平台极速构建发行体系 (Windows/Linux/Docker)
- [x] **v2.4 精准告警**: 设备离线连续判定过滤、未恢复周期重推、动态流量粒子流动拓扑
- [x] **v2.5 企业级加固**: 设备恢复秒级自愈与通知、关系库 100% 全量零损平移 (含 Canary 防自毁与序列校准)、CLI 自动特权提权、中文多编码智能转码

详细工程细节与历史演进见 [说明文档.md](./说明文档.md)。