#iPerf3 分布式网络测试工具全攻略：从安装到进阶监控

#项目简介

iPerf3 分布式网络测试工具 是一款基于 Python 开发的轻量级分布式网络监控套件。它通过 Master（主控） 与 Agent（代理） 的协同配合，实现了跨节点的带宽测试（iPerf3）、延迟监控（Ping）和路由追踪（Traceroute）可视化分析。

#核心亮点

#系统架构

项目采用解耦的分布式架构设计。主控节点负责数据持久化、任务调度与 Web 展示；代理节点则专注于执行网络探测任务并回传结果。

#组件技术栈

#环境准备

在开始部署前，请确保您的服务器满足以下条件：

#系统要求

• 操作系统：Ubuntu 20.04+、Debian 11+、CentOS 7+ 或其他主流 Linux 发行版
• 硬件配置：至少 1 核 CPU / 512MB 内存（建议 2 核 / 1GB 以获得更好体验）
• 基础依赖：已安装 Docker、Docker Compose 和 Git

#网络端口

请确保以下端口在防火墙和安全组中已开放：

#快速部署

#安装主控节点 (Master)

主控节点包含数据库、缓存和管理后台，是整个系统的核心枢纽。

步骤 1：克隆项目仓库

git clone https://github.com/podcctv/iperf3-test-tools.git
cd iperf3-test-tools

步骤 2：执行一键安装脚本

bash ./update_iperf3_master.sh

安装过程中，脚本会自动完成以下工作：

• 拉取并构建 Docker 镜像
• 初始化 PostgreSQL 数据库
• 生成随机管理员密码
• 启动所有服务容器

步骤 3：访问仪表盘

安装完成后，访问以下地址进入管理面板：

http://<服务器 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 "香港 BGP 节点"

参数说明：

安装完成后，新节点会自动出现在主控仪表盘的节点列表中。

#核心功能详解

#节点监控仪表盘

仪表盘首页提供全方位的节点状态概览：

• 节点状态卡片：实时显示在线/离线状态，在线节点有呼吸动效
• 三网延迟：同时监测电信、联通、移动三大运营商的连接延迟
• Ping 趋势图：通过 Sparkline 迷你图展示 24 小时延迟波动曲线
• 流媒体检测徽章：自动识别 Netflix、Disney+、ChatGPT 等服务的解锁状态，并显示区域角标（如 HK / US / SG）

#可视化路由追踪 (Metro-line)

该工具将复杂的 Traceroute 数据转化为类似"地铁线路图"的可视化界面：

核心功能：

• AS 路径分析：清晰展示数据包经过的自治系统（AS 编号及名称）
• 延迟胶囊徽章：根据延迟自动着色（绿色 < 50ms / 黄色 < 150ms / 红色 > 150ms）
• ISP/IX 徽章识别：自动识别 CN2、9929、NTT 等优质线路
• 智能变化告警：当路由节点发生变化时，系统通过 Telegram 推送高亮对比差异

#定时任务调度

您可以设置周期性的 iPerf3 测试任务，系统将自动记录并分析：

• 上下行带宽：支持 TCP / UDP 双模式测试
• 并行连接数：可配置同时建立的连接数量
• 趋势图表：24 小时内的带宽波动曲线
• 流量统计：展示节点日消耗流量，适合管理有流量配额的 VPS

#Telegram 智能通知

配置 Telegram Bot 后，系统可自动推送以下事件：

• 📡 路由变化告警（附带跳点差异对比）
• ⚠️ 定时任务执行失败通知
• 🔴 节点离线告警

#配置参考

#环境变量

#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

#API 接口一览

#核心接口

#路由追踪接口

#Telegram 配置接口

#更新与维护

#常规版本升级

在 Master 节点执行以下命令进行版本升级：

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

#Agent 自动更新

Agent 节点支持 Watchdog 自动更新机制。运行以下脚本开启自动同步：

curl -sSL https://raw.githubusercontent.com/podcctv/iperf3-test-tools/main/setup-agent-autoupdate.sh | sudo bash

启用后，当 Master 版本升级时，Agent 会自动检测并完成更新。

#故障排查

#常见问题速查表

#密码重置命令

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

#强制重建容器

docker compose down
docker compose up -d --build --force-recreate

#结语

iPerf3 分布式网络测试工具通过极简的部署流程和强大的可视化分析能力，为多机房网络性能管理提供了高效的解决方案。无论是日常的带宽监控、路由追踪分析，还是跨节点的网络质量对比，该工具都能满足您的需求。

如有任何问题或建议，欢迎前往 GitHub 仓库 提交 Issue 或参与贡献！

#参考链接

• GitHub 仓库
• 在线 API 文档：部署完成后访问 http://your-ip:9000/docs
• 问题反馈