blinkzero/pcap-replaya-backend

PCAP Replaya

一个现代化的Web应用，用于通过tcpreplay重放网络数据包捕获（PCAP）文件。基于React前端、Flask后端构建，完全使用Docker容器化。

!https://img.shields.io/badge/version-1.3.11-blue.svg !https://img.shields.io/badge/license-MIT-green.svg !https://img.shields.io/badge/docker-ready-blue.svg

✨ 功能特性

• 📁 文件上传: 拖放式PCAP上传，支持格式验证（.pcap、.pcapng、.cap，最大1GB）
• 📊 PCAP分析: 自动分析数据包数量、持续时间及协议类型
• 🔄 灵活重放: 支持倍数或PPS（每秒数据包）模式的速度控制
• 🔁 持续重放: 循环重放PCAP文件直至手动停止
• 📈 实时监控: 通过WebSocket更新实时进度跟踪
• 📋 重放历史: 带分页、搜索和过滤的持久化历史记录
• ⬇️ 下载功能: 下载之前重放过的PCAP文件
• 🖥️ 接口选择: 动态检测网络接口
• 📱 响应式UI: 现代Material-UI界面

🚀 快速开始

一键部署（推荐）

bash
curl -sSL https://raw.githubusercontent.com/blink-zero/pcap-replaya/main/quick-deploy.sh | sudo bash

手动部署

bash
# 下载生产配置
curl -sSL https://raw.githubusercontent.com/blink-zero/pcap-replaya/main/docker-compose.prod.yml -o docker-compose.yml

# 启动应用
sudo docker-compose up -d

访问应用

• 前端: http://localhost
• 后端API: http://localhost:5000/api

📋 前提条件

• Docker和Docker Compose
• Linux环境（用于网络接口访问）
• Root/sudo权限（tcpreplay网络访问需要）

🔄 更新

快速更新

bash
cd pcap-replaya-deploy
curl -sSL https://raw.githubusercontent.com/blink-zero/pcap-replaya/main/update.sh | sudo bash

手动更新

bash
sudo docker-compose pull
sudo docker-compose down
sudo docker-compose up -d

📖 使用指南

1. 上传PCAP文件

• 拖放或点击选择PCAP文件
• 支持格式：.pcap、.pcapng、.cap
• 最大大小：1GB

2. 配置重放

• 接口: 选择网络接口
• 速度: 选择倍数（0.1x-100x）或PPS（1-1,000,000）
• 持续: 启用持续循环
• 高级: 循环次数和预加载选项

3. 监控进度

• 实时进度更新
• 实时数据包和数据传输统计
• 随时停止重放

4. 查看历史

• 浏览所有之前的重放记录
• 按状态搜索和过滤
• 下载原始PCAP文件
• 使用相同配置重放

🔌 API文档

基础URL

http://localhost:5000/api

认证

本地部署无需认证。

端点

健康与系统

文件管理

重放控制

数据包操作

日志

请求示例

开始重放

bash
curl -X POST http://localhost:5000/api/replay/start \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "uuid-of-uploaded-file",
    "interface": "eth0",
    "speed": 2.0,
    "speed_unit": "multiplier",
    "continuous": false,
    "loop": 1,
    "preload_pcap": false
  }'

上传文件

bash
curl -X POST http://localhost:5000/api/upload \
  -F "file=@example.pcap"

获取重放历史

bash
curl "http://localhost:5000/api/replay/history?limit=20&offset=0&search=test&status=completed"

响应示例

重放状态

json
{
  "replay_id": "uuid",
  "status": "running",
  "progress_percent": 45.2,
  "packets_sent": 1250,
  "bytes_sent": 892400,
  "elapsed_time": 12.5,
  "packets_per_second": 100.0,
  "continuous": false,
  "loop_count": 1  
}

上传响应

json
{
  "message": "File uploaded successfully",
  "file_id": "uuid",
  "filename": "example.pcap",
  "file_size": 1048576,
  "pcap_info": {
    "packet_count": 1000,
    "duration": 30.5,
    "file_format": "pcap",
    "protocols": ["IP", "TCP", "UDP"]
  }
}

历史响应

json
{
  "history": [
    {
      "id": "uuid",
      "filename": "example.pcap",
      "file_id": "file-uuid",
      "status": "completed",
      "started_at": "2025-08-08T15:30:00Z",
      "duration": 25.3,
      "packets_sent": 1000,
      "config": {
        "interface": "eth0",
        "speed": 2.0,
        "speed_unit": "multiplier",
        "continuous": false
      }
    }
  ],
  "total_count": 50,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

WebSocket事件

连接地址：ws://localhost:5000

⚙️ 配置

环境变量

Docker配置

应用使用主机网络和特权容器以访问网络接口。

🏗️ 架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Frontend│◄──►│  Flask Backend  │◄──►│   tcpreplay     │
│                 │    │                 │    │                 │
│ • 文件上传      │    │ • API端点       │    │ • 数据包重放    │
│ • 配置UI        │    │ • 文件处理      │    │ • 速度控制      │
│ • 进度监控      │    │ • WebSocket     │    │ • 接口管理      │
│ • 历史视图      │    │ • 进程管理      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ 开发

本地开发

后端

bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

前端

bash
cd frontend
npm install
npm start

从源码构建

bash
git clone https://github.com/blink-zero/pcap-replaya.git
cd pcap-replaya
sudo docker-compose up --build

🔧 故障排除

常见问题

权限被拒绝

bash
# 确保Docker有必要的权限
sudo docker-compose down
sudo docker-compose up --build

tcpreplay无法工作

bash
# 检查容器中的tcpreplay
docker-compose exec backend tcpreplay --version

文件上传失败

• 检查文件大小（最大1GB）
• 验证文件格式（.pcap、.pcapng、.cap）
• 确保磁盘空间充足

调试命令

bash
# 查看日志
docker-compose logs -f

# 检查系统状态
docker-compose exec backend python -c "
import psutil
print(f'CPU: {psutil.cpu_percent()}%')
print(f'Memory: {psutil.virtual_memory().percent}%')
"

# 测试tcpreplay
docker-compose exec backend tcpreplay --version

📊 技术栈

后端

• Flask 2.3.3 - Web框架
• Flask-SocketIO 5.3.6 - WebSocket通信
• Scapy 2.5.0 - PCAP分析
• psutil 5.9.5 - 系统监控
• tcpreplay - 数据包重放

前端

• React 18.2.0 - 前端框架
• Material-UI 5.14.1 - UI组件
• axios 1.4.0 - HTTP客户端
• socket.io-client 4.7.2 - WebSocket客户端

基础设施

• Docker & Docker Compose - 容器化
• Nginx - 反向代理
• Python 3.11 - 后端运行时
• Node.js 18 - 前端构建

📝 许可证

本项目采用MIT许可证 - 详见LICENSE文件。

🤝 贡献

1. Fork仓库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开Pull Request

📞 支持

• 问题: https://github.com/blink-zero/pcap-replaya/issues
• 文档: 查看上述故障排除部分
• 日志: 使用docker-compose logs -f进行调试

🏷️ 版本历史

• v1.3.11 - 在UI中添加GitHub链接并清理界面
• v1.3.10 - 改进持续重放模式的历史详情显示
• v1.3.9 - 完全重写README并完善API文档
• v1.3.8 - 为重放历史添加PCAP下载功能
• v1.3.7 - 修复持续模式在历史详情中的显示
• v1.3.6 - 修复速度单位显示（PPS正确显示）
• v1.3.5 - 修复关键状态覆盖错误（停止vs失败）
• v1.3.4 - 改进手动停止重放的状态处理
• v1.3.3 - 修复持续参数的关键验证器错误
• v1.3.2 - 修复持续重放前端逻辑
• v1.3.1 - 修复持续重放进程通信
• v1.3.0 - 添加持续重放功能
• v1.2.1 - 修复Docker版本显示和搜索输入焦点
• v1.2.0 - 增强重放历史的分页和搜索功能
• v1.1.0 - 为重放历史添加分页
• v1.0.0 - 初始版本

🙏 致谢

• tcpreplay - 网络数据包重放工具
• Scapy - 数据包操作库
• https://reactjs.org/ - 前端框架
• https://flask.palletsprojects.com/ - 后端框架
• https://mui.com/ - UI组件库