# router_monitor

**Repository Path**: sammery/router_monitor

## Basic Information

- **Project Name**: router_monitor
- **Description**: 路由器监控
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 路由器流量监控 (Router Monitor)

一个轻量级的 Web 监控面板，用于监控 TP-Link 路由器的系统状态、实时流量及在线设备。支持设备拉黑、流量历史趋势分析，并通过初始化向导完成快速配置。

## 功能特性

- **实时状态监控**：展示路由器 CPU、内存及网络实时上下行速率，并附带历史趋势图表。
- **设备管理**：列出所有在线/离线设备，显示流量占比，支持查看设备详情并进行**拉黑/解封**操作。
- **流量趋势**：提供整体及单个设备的流量历史曲线（基于 Chart.js）。
- **初始化向导**：首次运行自动引导，配置路由器连接信息与管理密码。
- **安全机制**：单管理员账号（admin），密码经 `pbkdf2:sha256` 加密存储；未登录无法访问监控页。
- **持久化**：配置与流量数据存储于本地 SQLite，重启不丢失。

## 技术栈

| 模块 | 技术选型 |
| :--- | :--- |
| Web 框架 | Flask 3.x + waitress (WSGI) |
| 前端模板 | Jinja2 + 原生 JavaScript |
| 图表组件 | Chart.js v4 |
| 路由器通信 | requests (BussApi 协议封装) |
| 数据存储 | SQLite |
| 部署方式 | Docker (python:3.11-slim) |

## 目录结构

```
router_monitor/
├── main.py                 # 应用入口，负责初始化 Router 与 Flask 服务
├── app/                    # Flask 应用程序包
│   ├── __init__.py         # 应用工厂与中间件注册
│   ├── auth.py             # 全局请求鉴权 (before_request)
│   ├── config.py           # 配置加载逻辑 (支持 .env)
│   └── routes/             # 路由控制器 (views.py, api.py)
├── service/                # 后台守护服务
│   └── TPLink.py           # 路由器数据采集线程 (TPLink Router 类)
├── api/                    # 底层通信协议
│   ├── BaseApi.py          # API 基类
│   └── BussApi.py          # TP-Link BussApi 协议实现 (含登录、心跳、设备控制)
├── data/                   # 持久化存储
│   ├── config__db.py       # 系统配置存储 (密码哈希、连接信息)
│   └── traffic_db.py       # 流量记录存储
├── templates/              # HTML 模板
│   ├── index.html          # 监控面板 (首页、设备、流量 Tab)
│   ├── login.html          # 登录页
│   └── setup.html          # 初始化向导
├── static/                 # 静态资源
│   ├── css/style.css       # 样式表
│   └── js/app.js           # 前端交互逻辑 (Charts, Fetch, 拉黑操作)
├── utils/                  # 工具库 (编码、日志)
├── requirements.txt
├── Dockerfile
└── docker-compose.yml
```

## 快速开始

### 方式一：本地运行 (Python)

1. **准备环境**
   ```bash
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt
   ```

2. **启动服务**
   ```bash
   python main.py
   ```
   服务默认运行在 `http://127.0.0.1:8080`。

### 方式二：Docker 部署

项目包含 `Dockerfile` 和 `docker-compose.yml`，可一键启动。

```bash
docker compose up -d --build
```
容器内监听 `8080`，映射至宿主机 `8180` 端口。访问 `http://<宿主机IP>:8180` 即可。

## 使用说明

### 1. 初始化配置

首次启动访问应用根路径，会自动跳转到 `/setup` 向导：
1. **路由器连接**：输入路由器 IP 地址与管理密码，点击“测试连接”验证。
2. **系统设置**：设置本监控系统的管理员密码（至少 6 位）与数据采集间隔。

完成后系统自动重启，配置写入本地数据库。

### 2. 监控面板

登录后进入主界面，包含三个标签页：
- **首页 (Home)**：查看路由器系统资源（CPU/Mem）以及实时的总上行/下行速率。
- **设备 (Devices)**：
    - 展示所有在线/离线设备及其 IP、MAC、连接类型（2.4G/5G/有线）。
    - 点击操作栏的按钮可**拉黑**指定设备（阻止其上网）。
    - 点击设备名称可查看该设备的流量趋势弹窗。
- **流量 (Traffic)**：查看整体网络流量的历史曲线。

### 3. 设备拉黑

在“设备”列表中找到目标设备，点击拉黑按钮。状态会实时同步至路由器。已拉黑设备在列表中会有明显标识。

## 配置说明

### 环境变量 (`.env`)

Web 服务可通过 `.env` 文件配置：

| 变量 | 说明 | 默认值 |
| :--- | :--- | :--- |
| `HOST` | 服务监听地址 | `127.0.0.1` |
| `PORT` | 服务监听端口 | `8080` |
| `DEBUG` | Flask 调试模式 | `false` |

### 数据存储

系统的关键配置（路由器密码哈希、管理员密码、Flask SECRET_KEY 等）存储在 `data/` 目录下的 SQLite 文件中。该目录已加入 `.gitignore`，不会随代码提交泄露。

## 许可证

本项目基于 [MIT License](LICENSE) 开源。

Copyright (c) 2026 Sammery