# 性能压力测试套件

水务管理系统性能压力测试工具集，覆盖 REST API、WebSocket、MQTT IoT、数据库查询四大模块。

## 📁 文件说明

| 文件 | 说明 |
|------|------|
| `locustfile.py` | REST API 压力测试 (Locust 框架) |
| `websocket_stress.py` | WebSocket 长连接并发测试 |
| `mqtt_iot_stress.py` | IoT MQTT 设备并发模拟 |
| `db_query_stress.py` | 大数据量数据库查询性能测试 |
| `run_all_benchmarks.sh` | 统一压测入口脚本 |
| `report_template.md` | 压测报告模板 |
| `requirements.txt` | Python 依赖 |

## 🚀 快速开始

### 1. 安装依赖

```bash
cd tests/performance
pip install -r requirements.txt
```

### 2. 运行全部测试

```bash
# 完整测试（约 30 分钟）
bash run_all_benchmarks.sh

# 快速模式（约 5 分钟，适合 CI/CD）
bash run_all_benchmarks.sh --quick

# 指定输出目录
bash run_all_benchmarks.sh --output-dir ./my-report
```

### 3. 运行单项测试

#### REST API 压测

```bash
# 图形界面模式（浏览器打开 http://localhost:8089）
locust -f locustfile.py --host=http://localhost:8080

# 无头模式，100 并发，运行 5 分钟
locust -f locustfile.py --host=http://localhost:8080 \
    --headless -u 100 -r 10 --run-time 5m

# 梯度负载测试
locust -f locustfile.py --host=http://localhost:8080 \
    --headless --class-picker StepLoadShape
```

#### WebSocket 压测

```bash
# 100 并发连接，60 秒
python websocket_stress.py --clients 100 --duration 60

# 梯度测试 (100/500/1000/5000)
python websocket_stress.py --step --output ws_result.json
```

#### MQTT IoT 压测

```bash
# 模拟 500 设备，每 5 秒上报，运行 2 分钟
python mqtt_iot_stress.py --devices 500 --duration 120 --freq 5

# 梯度测试
python mqtt_iot_stress.py --step --output mqtt_result.json

# 高频上报 (1 秒)
python mqtt_iot_stress.py --devices 1000 --freq 1 --duration 60
```

#### 数据库查询压测

```bash
# 生成 100 万条数据 + 运行查询测试 + 索引对比
python db_query_stress.py --generate-data 1000000 --index-compare

# 跳过数据生成（已有数据）
python db_query_stress.py --skip-data-gen --index-compare

# 指定数据库连接
python db_query_stress.py --host db.example.com --db water_management \
    --user admin --password secret --generate-data 500000
```

## 📊 解读报告

### REST API 报告

| 指标 | 说明 | 参考阈值 |
|------|------|----------|
| 平均响应时间 | 所有请求的平均耗时 | < 200ms |
| P95 响应时间 | 95% 请求的耗时上限 | < 1000ms |
| P99 响应时间 | 99% 请求的耗时上限 | < 3000ms |
| 吞吐量 (RPS) | 每秒处理请求数 | 越高越好 |
| 错误率 | 失败请求占比 | < 1% |

### WebSocket 报告

| 指标 | 说明 | 参考阈值 |
|------|------|----------|
| 连接成功率 | 成功建立连接的比例 | > 99% |
| 消息延迟 | 消息从发送到收到的时间 | < 100ms |
| 断连率 | 连接断开的比例 | < 5% |
| 内存消耗 | 服务器内存使用 | 视硬件而定 |

### MQTT 报告

| 指标 | 说明 | 参考阈值 |
|------|------|----------|
| 连接成功率 | 设备连接成功率 | > 99% |
| 发布延迟 | 消息发布时间 | < 50ms |
| 吞吐量 | 每秒消息处理量 | 视配置而定 |

### 数据库报告

| 指标 | 说明 | 参考阈值 |
|------|------|----------|
| 简单查询 | 单表查询耗时 | < 100ms |
| 聚合查询 | GROUP BY 聚合耗时 | < 500ms |
| JOIN 查询 | 多表关联耗时 | < 1000ms |
| GIS 查询 | 空间查询耗时 | < 500ms |

## ⚙️ 环境变量配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `API_HOST` | localhost | REST API 地址 |
| `API_PORT` | 8080 | REST API 端口 |
| `WS_HOST` | localhost | WebSocket 地址 |
| `WS_PORT` | 8765 | WebSocket 端口 |
| `MQTT_BROKER` | localhost | MQTT Broker 地址 |
| `MQTT_PORT` | 1883 | MQTT Broker 端口 |
| `DB_HOST` | localhost | 数据库地址 |
| `DB_PORT` | 5432 | 数据库端口 |
| `DB_NAME` | water_management | 数据库名 |
| `DB_USER` | postgres | 数据库用户 |
| `DB_PASS` | postgres | 数据库密码 |

## ❓ 常见问题

### Q: Locust 安装失败
```bash
pip install --upgrade pip setuptools wheel
pip install locust
```

### Q: psycopg2 安装失败
```bash
# Debian/Ubuntu
sudo apt-get install libpq-dev
pip install psycopg2-binary

# macOS
brew install postgresql
pip install psycopg2-binary
```

### Q: WebSocket 连接被拒绝
确认 WebSocket 服务已启动且端口正确：
```bash
# 检查端口
ss -tlnp | grep 8765
# 或用 curl 测试
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:8765/ws
```

### Q: MQTT 连接失败
确认 EMQX 或其他 MQTT Broker 已启动：
```bash
# Docker 方式启动 EMQX
docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 18083:18083 emqx/emqx
```

### Q: 数据库查询测试报错
确认 PostgreSQL 已启动且可访问：
```bash
psql -h localhost -U postgres -d water_management -c "SELECT 1"
```

### Q: 测试数据太多占磁盘
```bash
# 测试完成后清理
psql -h localhost -U postgres -d water_management -c \
    "TRUNCATE TABLE perf_sensor_data, perf_alarms, perf_devices"
```

## 📈 推荐测试流程

1. **先单项测试**：分别运行四个测试，确认各自正常
2. **再快速模式**：`run_all_benchmarks.sh --quick` 快速验证全流程
3. **最后完整测试**：`run_all_benchmarks.sh` 执行完整压力测试
4. **分析瓶颈**：对比各项结果，找出系统瓶颈
5. **优化后复测**：针对瓶颈优化后重新测试，对比改善效果

## 📝 License

本项目内部使用，请遵循项目根目录的 LICENSE。