netmon
自托管的本地网络监控工具，提供 24 小时速率图表与尖酸刻薄的 AI 评论，并直接推送到 Telegram。
一个轻量级的本地机器人，每小时对你的网络进行一次速度测试，使用 `nmap` 扫描局域网上的活动设备，并将所有数据记录到本地 SQLite 数据库中。
每 4 小时，它会发送一份**详细报告**，包含 24 小时趋势图，以及由 LLM 生成的、对你网络行为的尖酸评论（*“有人又在狂占带宽了”*）。
## 功能与工作流
每小时执行一次（`main.py` 中的 `SLEEP_TIME`，默认为 3600 秒）：
1. **速度测试：** 使用 `speedtest-cli` 测量下载/上传速度、ping 延迟、ISP 以及测试服务器的详细信息。
2. **局域网扫描：** 使用 `nmap` ARP 扫描本地子网，计算已连接的活动设备数量。
3. **本地存储：** 将指标和设备统计数据直接保存到本地的 `metrics.sql` SQLite 数据库中。
4. **状态提醒：** 向 Telegram 发送简短的状态更新（“一切正常”或“网络又挂了”）。
5. **24 小时 AI 报告：** 每 4 个周期（每 4 小时），通过 `matplotlib` 生成一张** 24 小时趋势图**，并附带对网络负载和速度波动的 LLM 尖酸分析。
## 技术栈
| 技术 | 用途 |
| :--- | :--- |
| **Python 3.13+** (通过 `uv`) | 核心运行时 |
| **SQLite** | 本地指标持久化 (`metrics.sql`) |
| **`speedtest-cli`** | 网络带宽和 ping 测量 |
| **`nmap`** | 用于设备发现的子网 ARP 扫描 |
| **`matplotlib`** | 24 小时指标可视化 |
| **兼容 OpenAI 的 API** | 尖刻报告与趋势分析（云端 OpenAI 或本地 LLM） |
| **Telegram API** | 提醒和图表报告推送 |
## 环境要求
* **操作系统：** macOS 或 Linux（需要 `nmap --iflist`；开箱不支持 Windows）。
* **[uv](https://docs.astral.sh/uv/)** — 为你管理 Python 版本、虚拟环境和锁定的依赖项。无需手动折腾 `python3`/`venv`/`pip`。
* **系统二进制文件：** 需要在系统范围内安装 `nmap` 和 `speedtest-cli`。
* **为 `nmap` 配置免密码的 `sudo`** — 设备计数需要真正的 ARP 扫描（原始套接字），这需要 root 权限；请参阅下文的一次性设置。
* **Token：** Telegram Bot Token、Telegram Chat ID，以及兼容 OpenAI 提供商的 API 密钥（如果你将 `AI_BASE_URL` 指向本地 LLM 服务器，则不需要）。
## 快速开始
### 1. 系统依赖
**macOS (Homebrew)：**
```
brew install nmap speedtest-cli
```
**Linux (Debian/Ubuntu)：**
```
sudo apt update && sudo apt install -y nmap speedtest-cli
```
### 2. 允许免密码运行 `nmap`（一次性）
设备计数以 root 身份运行 `nmap` 以进行真正的 ARP 扫描 —— 如果没有它，主机发现会默默退回到普通的 TCP 探测，并且会导致没有在常用端口上响应的设备统计不足。由于机器人是无人值守运行的，`sudo` 需要在每个周期中在没有密码提示的情况下工作：
```
echo "$(whoami) ALL=(root) NOPASSWD: $(command -v nmap)" | sudo tee /etc/sudoers.d/netmon-nmap
sudo chmod 440 /etc/sudoers.d/netmon-nmap
```
这仅为 `nmap` 二进制文件授予免密码的 `sudo` 权限 —— 而不是你的整个账户。
### 3. 克隆并配置环境
如果你还没有安装 [`uv`](https://docs.astral.sh/uv/)：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
然后：
```
git clone https://github.com/Role1776/netmon.git
cd netmon
uv sync
```
`uv sync` 会下载锁定的 Python 版本（参见 `.python-version`）（如果你还没有的话），创建 `.venv`，并从 `uv.lock` 安装完全锁定的依赖版本。无需系统 `python3`，无需手动激活虚拟环境。
### 4. 配置 `.env`
复制模板文件并填入你的密钥：
```
cp .env.example .env
```
`.env` 变量：
| 变量 | 说明 |
| :--- | :--- |
| `AI_API_KEY` | 你的 LLM 提供商 API 密钥（对于大多数本地服务器，任意字符串均可） |
| `AI_MODEL` | 模型名称（例如 `gpt-4o-mini`，或本地模型名称 —— 见下文） |
| `AI_BASE_URL` | 基础 API URL（例如 `https://api.openai.com/v1`，或你本地服务器的 URL） |
| `TG_BOT_TOKEN` | 来自 `@BotFather` 的 Telegram bot token |
| `TG_CHAT_ID` | 你的 Telegram Chat ID |
| `DB_PATH` | SQLite 数据库文件路径（例如 `metrics.sql`） |
### 5. 运行机器人
```
uv run main.py
```
`uv run` 始终使用该项目自身的 `.venv` 和锁定的 Python 版本，因此它不会意外使用你的系统 `python3` 来运行。
## 示例输出
### 每小时简短状态更新
```
Network Status Update
Time: 2026-07-21 14:00:00
ISP: MyISP | Server: New York
Devices online: 7
Download: 145.2 Mbps
Upload: 62.1 Mbps
Latency: 14.8 ms
Traffic used: 160.0 MB down / 70.0 MB up
Current status: Good speed and low latency
```
### 4 小时详细报告（包含图表与 AI 分析）
每 4 小时，机器人会发送一张** 24 小时 matplotlib 图表**，并附带由 LLM 生成的尖刻报告：
```
Network Speed Test Report (24h Analysis)
Client:
MyISP
Server:
New York
Latest Test Metrics
Download: 178.5 Mbps
Upload: 45.2 Mbps
Ping: 23.1 ms
Devices Online: 9
24-Hour Dynamics Analysis
Over the last 24 hours, the download speed averaged
140 Mbps, but we saw a massive drop to
20 Mbps at 8:00 PM right as device count jumped from
4 to
11 devices. Clearly, someone's hogging the bandwidth or the ISP's mice were busy chewing on the fiber line again. Latency remained stable except for a brief spike during peak hours.
Data Transfer (Latest Test)
Downloaded: 160.0 MB
Uploaded: 70.0 MB
Conclusion
Expect periodic speed drops whenever local freeloaders stream 4K movies or the ISP potato infrastructure struggles.
```
## 项目结构
```
netmon/
├── assets/ # Logo & documentation media assets
├── graphs/ # Generated 24h matplotlib graph images
├── main.py # Main execution loop & orchestrator
├── runner.py # Speedtest-cli and nmap scan execution & parsing
├── sqlite.py # SQLite database operations & schema management
├── models.py # Domain data models (NetworkMetric, SpeedTest)
├── graphs.py # Matplotlib graph rendering engine
├── ai.py # OpenAI API client & sarcastic text generator
├── tg.py # Telegram bot dispatch helper
├── config.py # Environment variable validation & config
├── pyproject.toml # Project metadata & dependencies
├── uv.lock # Locked, reproducible dependency versions
└── LICENSE # MIT License file
```
## 许可证
基于 **MIT License** 发布。详情请参阅 [`LICENSE`](LICENSE)。