iPerf3 分布式网络测试工具

服务器资源赞助： VPS.Town
本项目运行所需的服务器与网络基础设施由 VPS.Town 提供支持，为分布式 iperf3 性能测试提供稳定、高带宽的运行环境。

iPerf3 分布式网络测试工具

A lightweight master/agent distributed network testing toolkit with one-click installation, auto-update, and visual monitoring.

轻量级 主控/代理 分布式网络测试工具，支持一键安装、自动更新和可视化监控。

✨ 核心特性 / Key Features

功能	说明
🚀 一键安装更新	单条命令完成安装和更新，自动检测版本差异
📊 现代化仪表盘	商业级 UI 设计，实时监控节点状态、三网延迟、流媒体解锁
⏰ 定时任务	周期性测试，自动生成趋势图表和流量统计
🛤️ 路由追踪	Metro-line 可视化、AS 路径分析、路由变化告警
📈 Ping 趋势	实时延迟监控，趋势箭头和迷你图显示
🎬 流媒体检测	Netflix、Disney+、ChatGPT 等服务解锁状态检测
🤖 Telegram 通知	路由变化、任务失败等事件推送
🔐 IP 白名单	防止 iperf3 服务被滥用
🌐 分布式架构	Master/Agent 模式，轻松管理多节点

🎯 快速开始 / Quick Start

安装主控节点 (Master)

# 克隆仓库
git clone https://github.com/podcctv/iperf3-test-tools.git
cd iperf3-test-tools

# 一键安装主控节点
bash ./update_iperf3_master.sh

安装完成后访问：http://your-ip:9100/web

安装 Agent 节点

# 下载并执行安装脚本
curl -sSL https://raw.githubusercontent.com/podcctv/iperf3-test-tools/main/install_agent.sh | bash -s -- \
  --master-url http://master-ip:9000 \
  --node-name "节点名称"

📦 系统架构 / Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│  Master Node (主控节点)                                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ FastAPI + PostgreSQL + Redis + APScheduler                          │    │
│  │ ├─ REST API (/api/*)                                                │    │
│  │ ├─ Web Dashboard (/web) - 现代化仪表盘                               │    │
│  │ ├─ Traceroute 页面 (/web/trace) - Metro-line 可视化                  │    │
│  │ ├─ 定时任务调度 (iperf3 + traceroute)                                │    │
│  │ ├─ Ping 趋势监控 (缓存 + 批量请求)                                    │    │
│  │ ├─ 流媒体解锁检测 (Netflix, Disney+, ChatGPT 等)                     │    │
│  │ ├─ Telegram 通知                                                    │    │
│  │ └─ IP 白名单管理                                                     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ PostgreSQL + Redis                                                  │    │
│  │ ├─ nodes, test_results, test_schedules                              │    │
│  │ ├─ trace_schedules, trace_results                                   │    │
│  │ ├─ ping_history (延迟趋势)                                           │    │
│  │ └─ asn_cache (PeeringDB 缓存)                                        │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                               │ HTTP API
                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Agent Nodes (测试节点)                                                       │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │ Agent 1          │  │ Agent 2          │  │ Agent N          │          │
│  │ Flask API        │  │ Flask API        │  │ Flask API        │          │
│  │ iperf3 Server    │  │ iperf3 Server    │  │ iperf3 Server    │          │
│  │ mtr/traceroute   │  │ mtr/traceroute   │  │ mtr/traceroute   │          │
│  │ IP 白名单验证    │  │ IP 白名单验证    │  │ IP 白名单验证    │          │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
└─────────────────────────────────────────────────────────────────────────────┘

组件说明

组件	技术栈	功能
Master API	FastAPI + PostgreSQL + Redis	REST API、Web 面板、调度器、缓存
Agent	Flask + iperf3 + mtr	执行测试、路由追踪、流媒体检测、IP 过滤
Scheduler	APScheduler	定时 iperf3 测试和 traceroute 监控

🎨 功能详情 / Features

1. 节点监控仪表盘 (Dashboard)

✅ 现代化 UI 设计（商业级视觉效果）
✅ 节点状态卡片（在线呼吸动画）
✅ 三网延迟显示（电信/联通/移动）
✅ Ping 趋势迷你图 + 趋势箭头
✅ 流媒体解锁徽章（区域标识）

2. 路由追踪 (Traceroute)

✅ Metro-line 可视化 - 地铁线路图风格显示
✅ Hop 卡片样式 - 现代化节点信息展示
✅ 延迟胶囊徽章 - 颜色编码 (绿<50ms/黄<150ms/红>150ms)
✅ AS 路径面包屑 - 水平箭头连接显示
✅ ISP/IX/Tier 徽章 - CN2、9929、NTT 等识别
✅ 双向对比追踪
✅ 多源对比追踪
✅ 定时监控 + 路由变化告警
✅ 变化跳点红色高亮

3. iperf3 测试

✅ TCP/UDP 协议支持
✅ 单向/双向测试
✅ UDP 带宽设置
✅ 并行连接配置
✅ 测试结果可视化

4. 定时任务

✅ 周期性 iperf3 测试
✅ 24小时趋势图
✅ 每日流量统计徽章
✅ VPS 日统计卡片

5. 流媒体检测

✅ 视频流媒体: Netflix (全解锁/自制剧)、Disney+、YouTube Premium
✅ AI 服务: ChatGPT、Gemini、Claude
✅ 区域标识角标
✅ 自动缓存（24小时）

6. Telegram 通知

✅ 路由变化告警
✅ 定时任务失败通知
✅ 节点离线告警

🔧 配置参考 / Configuration

环境变量

变量名	说明	默认值
`DATABASE_URL`	PostgreSQL 连接字符串	`postgresql://iperf:iperf_pass@db:5432/iperf_db`
`REDIS_URL`	Redis 连接字符串	`redis://redis:6379`
`DASHBOARD_PASSWORD`	面板密码	首次启动自动生成
`MASTER_API_PORT`	API 端口	`9000`
`MASTER_WEB_PORT`	Web 面板端口	`9100`

Docker Compose 部署

# docker-compose.yml
services:
  master-api:
    build: ./master-api
    ports:
      - "9000:9000"
    depends_on:
      - db
      - redis
    environment:
      - DATABASE_URL=postgresql://iperf:iperf_pass@db:5432/iperf_db
      - REDIS_URL=redis://redis:6379

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: iperf
      POSTGRES_PASSWORD: iperf_pass
      POSTGRES_DB: iperf_db

  redis:
    image: redis:7-alpine

🔄 更新升级 / Update

常规更新

cd iperf3-test-tools
git pull origin main
docker compose build --no-cache master-api
docker compose up -d

Agent 自动更新

Agent 支持自动更新功能，当 Master 版本升级时，Agent 可以自动检测并更新。

# 一键安装自动更新
curl -sSL https://raw.githubusercontent.com/podcctv/iperf3-test-tools/main/setup-agent-autoupdate.sh | sudo bash

📊 API 端点 / API Endpoints

核心 API

方法	路径	说明
GET	`/nodes`	获取所有节点
POST	`/nodes`	注册新节点
GET	`/nodes/{id}/ping-history`	获取节点 Ping 历史
POST	`/tests`	执行测试
GET/POST	`/schedules`	定时任务管理

路由追踪 API

方法	路径	说明
POST	`/api/trace/run`	执行 traceroute
GET	`/api/trace/schedules`	获取追踪任务
GET	`/api/trace/results`	获取追踪历史

Telegram API

方法	路径	说明
GET	`/admin/telegram`	获取设置
POST	`/admin/telegram`	保存设置
POST	`/admin/telegram/test`	发送测试消息

完整 API 文档：http://your-ip:9000/docs

🐛 故障排查 / Troubleshooting

容器无法启动

docker logs iperf3-test-tools-master-api-1
docker compose down
docker compose up -d --build --force-recreate

Agent 连接失败

# 检查 Agent 状态
curl http://agent-ip:8000/health

# 检查防火墙
ufw allow 8000/tcp
ufw allow 62001/tcp

重置密码

docker compose exec master-api python -m app.auth --set-password 'YourNewPass' --force

📝 版本历史 / Changelog

v1.6.0 (Latest)

✅ 全站视觉统一 - 深色玻璃拟态风格 (Glassmorphism) 全面覆盖
✅ 路由追踪导航重构 - 丝滑的 Hash 路由切换，告别页面刷新
✅ 侧边栏主题按钮 - 修复显示问题，清晰的暗黑模式标识
✅ 鉴权体验优化 - 智能识别访客身份，菜单自动显隐
✅ 普通路由追踪 - 新增常规 traceroute 定时任务支持

v1.5.0

✅ Dashboard UI 现代化 - 商业级仪表盘设计
✅ Trace 页面 Metro-line 样式 - 地铁线路图可视化
✅ 延迟胶囊徽章 - 颜色编码延迟显示
✅ AS 路径面包屑 - 水平箭头流程显示
✅ Hop 卡片样式 - 现代化节点信息展示
✅ 流媒体徽章优化 - 区域角标 + 颜色统一

v1.4.0

✅ Agent 自动更新 (Watchdog)
✅ Ping 趋势箭头显示
✅ VPS 卡片运营商延迟徽章
✅ 版本同步检测和更新通知

v1.2.0

✅ Telegram 通知集成
✅ 路由追踪定时任务
✅ ISP/IX 徽章显示
✅ 路由变化智能检测
✅ UDP 带宽设置

v1.1.0

✅ IP 白名单保护
✅ 流媒体解锁检测
✅ 定时任务图表

v1.0.0

✅ 基础 iperf3 测试
✅ 节点管理
✅ Web 面板

📄 License

MIT License - 详见 LICENSE 文件

🤝 贡献 / Contributing

欢迎提交 Issue 和 Pull Request！

快速链接：

Name		Name	Last commit message	Last commit date
Latest commit History 653 Commits
.agent		.agent
.github/workflows		.github/workflows
agent		agent
data		data
docs		docs
master-api		master-api
tools		tools
.cursorrules		.cursorrules
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
agent-watchdog.sh		agent-watchdog.sh
agent.sh		agent.sh
agent_configs.json		agent_configs.json
analyze_main.py		analyze_main.py
deploy_agents.sh		deploy_agents.sh
docker-compose.yml		docker-compose.yml
fix_encoding_main.py		fix_encoding_main.py
install_agent.sh		install_agent.sh
install_master.sh		install_master.sh
list_funcs.py		list_funcs.py
map_code.py		map_code.py
redis.conf		redis.conf
result_sample.json		result_sample.json
salvage_main.py		salvage_main.py
setup-agent-autoupdate.sh		setup-agent-autoupdate.sh
temp_main.py		temp_main.py
test_cache_performance.py		test_cache_performance.py
test_optimization.py		test_optimization.py
truncate_main.py		truncate_main.py
update_iperf3_master.sh		update_iperf3_master.sh

Folders and files

Latest commit

History

Repository files navigation

iPerf3 分布式网络测试工具

✨ 核心特性 / Key Features

🎯 快速开始 / Quick Start

安装主控节点 (Master)

安装 Agent 节点

📦 系统架构 / Architecture

组件说明

🎨 功能详情 / Features

1. 节点监控仪表盘 (Dashboard)

2. 路由追踪 (Traceroute)

3. iperf3 测试

4. 定时任务

5. 流媒体检测

6. Telegram 通知

🔧 配置参考 / Configuration

环境变量

Docker Compose 部署

🔄 更新升级 / Update

常规更新

Agent 自动更新

📊 API 端点 / API Endpoints

核心 API

路由追踪 API

Telegram API

🐛 故障排查 / Troubleshooting

容器无法启动

Agent 连接失败

重置密码

📝 版本历史 / Changelog

v1.6.0 (Latest)

v1.5.0

v1.4.0

v1.2.0

v1.1.0

v1.0.0

📄 License

🤝 贡献 / Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages