feat: 添加性能压力测试套件 (#94)

- REST API 压测 (Locust): 支持 10-1000 并发梯度测试，覆盖监测/上报/报表/GIS 等端点
- WebSocket 压测: asyncio+websockets 模拟 100-5000 并发长连接
- MQTT IoT 压测: paho-mqtt 模拟 100-5000 台设备同时上报
- 数据库查询压测: 百万级数据测试，含索引对比、GIS 空间查询
- 统一入口脚本 + 报告模板 + 使用文档

tests/performance/README.md

@@ -0,0 +1,205 @@
+# 性能压力测试套件
+
+水务管理系统性能压力测试工具集，覆盖 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。

tests/performance/db_query_stress.py

@@ -0,0 +1,684 @@
+#!/usr/bin/env python3
+"""
+大数据量数据库查询压力测试
+
+测试百万级记录下各类查询的性能：
+- 简单查询（单表 WHERE）
+- 聚合查询（GROUP BY / SUM / AVG）
+- JOIN 查询（多表关联）
+- GIS 空间查询（PostGIS ST_DWithin 等）
+- 对比有无索引的性能差异
+
+运行方式：
+  python db_query_stress.py [--host HOST] [--port PORT] [--db DB] [--user USER] [--password PASS]
+
+示例：
+  python db_query_stress.py --host localhost --db water_management --generate-data 1000000
+"""
+
+import argparse
+import json
+import time
+import random
+import statistics
+import sys
+from datetime import datetime, timedelta
+from contextlib import contextmanager
+
+try:
+    import psycopg2
+    from psycopg2 import pool
+except ImportError:
+    print("请先安装 psycopg2: pip install psycopg2-binary")
+    sys.exit(1)
+
+
+# ==================== 配置 ====================
+
+DEFAULT_HOST = "localhost"
+DEFAULT_PORT = 5432
+DEFAULT_DB = "water_management"
+DEFAULT_USER = "postgres"
+DEFAULT_PASSWORD = "postgres"
+
+# 测试查询配置
+QUERY_ROUNDS = 5  # 每个查询重复次数取平均值
+
+
+# ==================== 数据库连接 ====================
+
+class DBConnectionPool:
+    """数据库连接池管理"""
+
+    def __init__(self, host, port, db, user, password, min_conn=2, max_conn=10):
+        self.pool = pool.ThreadedConnectionPool(
+            min_conn, max_conn,
+            host=host, port=port, dbname=db, user=user, password=password,
+            connect_timeout=10,
+        )
+
+    @contextmanager
+    def get_connection(self):
+        conn = self.pool.getconn()
+        try:
+            yield conn
+        finally:
+            self.pool.putconn(conn)
+
+    def close(self):
+        self.pool.closeall()
+
+
+# ==================== 测试数据生成 ====================
+
+def generate_test_data(db_pool, num_records):
+    """生成测试数据"""
+    print(f"\n📦 生成 {num_records} 条测试数据...")
+
+    with db_pool.get_connection() as conn:
+        cur = conn.cursor()
+
+        # 创建传感器数据表（如不存在）
+        cur.execute("""
+            CREATE TABLE IF NOT EXISTS perf_sensor_data (
+                id BIGSERIAL PRIMARY KEY,
+                sensor_id INTEGER NOT NULL,
+                device_id VARCHAR(32) NOT NULL,
+                timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                pressure REAL,
+                flow REAL,
+                temperature REAL,
+                ph REAL,
+                turbidity REAL,
+                chlorine REAL,
+                battery REAL,
+                signal_strength INTEGER,
+                lng DOUBLE PRECISION,
+                lat DOUBLE PRECISION,
+                area_id INTEGER,
+                created_at TIMESTAMPTZ DEFAULT NOW()
+            )
+        """)
+
+        # 创建告警表
+        cur.execute("""
+            CREATE TABLE IF NOT EXISTS perf_alarms (
+                id BIGSERIAL PRIMARY KEY,
+                sensor_id INTEGER NOT NULL,
+                alarm_type VARCHAR(32) NOT NULL,
+                severity VARCHAR(16) NOT NULL,
+                value REAL,
+                threshold REAL,
+                description TEXT,
+                acknowledged BOOLEAN DEFAULT FALSE,
+                timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                created_at TIMESTAMPTZ DEFAULT NOW()
+            )
+        """)
+
+        # 创建设备表
+        cur.execute("""
+            CREATE TABLE IF NOT EXISTS perf_devices (
+                id SERIAL PRIMARY KEY,
+                device_id VARCHAR(32) UNIQUE NOT NULL,
+                name VARCHAR(128),
+                device_type VARCHAR(32),
+                area_id INTEGER,
+                lng DOUBLE PRECISION,
+                lat DOUBLE PRECISION,
+                status VARCHAR(16) DEFAULT 'active',
+                install_date DATE,
+                created_at TIMESTAMPTZ DEFAULT NOW()
+            )
+        """)
+
+        conn.commit()
+
+        # 清空旧测试数据
+        print("  清空旧数据...")
+        cur.execute("TRUNCATE TABLE perf_sensor_data, perf_alarms, perf_devices")
+        conn.commit()
+
+        # 生成设备数据
+        print("  生成设备数据...")
+        device_count = min(5000, num_records // 100)
+        devices = []
+        for i in range(1, device_count + 1):
+            device_id = f"DEV{i:06d}"
+            devices.append((
+                device_id,
+                f"传感器-{i}",
+                random.choice(["pressure", "flow", "quality", "level", "valve"]),
+                random.randint(1, 50),
+                round(random.uniform(116.0, 117.0), 6),
+                round(random.uniform(39.5, 40.5), 6),
+                random.choice(["active", "inactive", "maintenance"]),
+                (datetime.now() - timedelta(days=random.randint(0, 730))).date(),
+            ))
+
+        cur.executemany("""
+            INSERT INTO perf_devices (device_id, name, device_type, area_id, lng, lat, status, install_date)
+            VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+        """, devices)
+        conn.commit()
+        print(f"  ✅ 已生成 {device_count} 个设备")
+
+        # 批量插入传感器数据
+        print(f"  生成 {num_records} 条传感器数据...")
+        batch_size = 10000
+        total_inserted = 0
+        base_time = datetime.now() - timedelta(days=365)
+
+        alarm_types = ["PRESSURE_HIGH", "PRESSURE_LOW", "FLOW_ABNORMAL",
+                       "QUALITY_WARNING", "LEAK_DETECTED", "BATTERY_LOW"]
+        severities = ["INFO", "WARNING", "CRITICAL"]
+
+        while total_inserted < num_records:
+            batch = []
+            for _ in range(min(batch_size, num_records - total_inserted)):
+                sensor_id = random.randint(1, device_count)
+                ts = base_time + timedelta(
+                    seconds=random.randint(0, 365 * 24 * 3600)
+                )
+                batch.append((
+                    sensor_id,
+                    f"DEV{sensor_id:06d}",
+                    ts,
+                    round(random.uniform(0.1, 0.8), 3),  # pressure
+                    round(random.uniform(10, 500), 2),    # flow
+                    round(random.uniform(5, 35), 1),      # temperature
+                    round(random.uniform(6.5, 8.5), 2),   # ph
+                    round(random.uniform(0, 5), 2),       # turbidity
+                    round(random.uniform(0.1, 0.8), 3),   # chlorine
+                    round(random.uniform(20, 100), 1),    # battery
+                    random.randint(-90, -30),             # signal
+                    round(random.uniform(116.0, 117.0), 6),  # lng
+                    round(random.uniform(39.5, 40.5), 6),    # lat
+                    random.randint(1, 50),                # area_id
+                ))
+
+            cur.executemany("""
+                INSERT INTO perf_sensor_data
+                (sensor_id, device_id, timestamp, pressure, flow, temperature,
+                 ph, turbidity, chlorine, battery, signal_strength, lng, lat, area_id)
+                VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)
+            """, batch)
+            conn.commit()
+            total_inserted += len(batch)
+            if total_inserted % 100000 == 0:
+                print(f"  进度: {total_inserted}/{num_records} ({total_inserted*100//num_records}%)")
+
+        print(f"  ✅ 已生成 {total_inserted} 条传感器数据")
+
+        # 生成告警数据（传感器数据的 5%）
+        alarm_count = num_records // 20
+        print(f"  生成 {alarm_count} 条告警数据...")
+        alarms = []
+        for _ in range(alarm_count):
+            sensor_id = random.randint(1, device_count)
+            alarms.append((
+                sensor_id,
+                random.choice(alarm_types),
+                random.choice(severities),
+                round(random.uniform(0, 100), 2),
+                round(random.uniform(50, 100), 2),
+                f"自动告警描述 - {random.choice(alarm_types)}",
+                random.choice([True, False]),
+                base_time + timedelta(seconds=random.randint(0, 365 * 24 * 3600)),
+            ))
+
+        cur.executemany("""
+            INSERT INTO perf_alarms
+            (sensor_id, alarm_type, severity, value, threshold, description, acknowledged, timestamp)
+            VALUES (%s,%s,%s,%s,%s,%s,%s,%s)
+        """, alarms)
+        conn.commit()
+        print(f"  ✅ 已生成 {alarm_count} 条告警数据")
+
+        cur.close()
+
+    print("✅ 测试数据生成完成\n")
+
+
+# ==================== 索引管理 ====================
+
+def create_indexes(db_pool):
+    """创建性能测试用索引"""
+    with db_pool.get_connection() as conn:
+        cur = conn.cursor()
+        indexes = [
+            "CREATE INDEX IF NOT EXISTS idx_sensor_data_sensor_id ON perf_sensor_data(sensor_id)",
+            "CREATE INDEX IF NOT EXISTS idx_sensor_data_timestamp ON perf_sensor_data(timestamp)",
+            "CREATE INDEX IF NOT EXISTS idx_sensor_data_area_id ON perf_sensor_data(area_id)",
+            "CREATE INDEX IF NOT EXISTS idx_sensor_data_device_id ON perf_sensor_data(device_id)",
+            "CREATE INDEX IF NOT EXISTS idx_sensor_data_composite ON perf_sensor_data(sensor_id, timestamp)",
+            "CREATE INDEX IF NOT EXISTS idx_alarms_sensor_id ON perf_alarms(sensor_id)",
+            "CREATE INDEX IF NOT EXISTS idx_alarms_timestamp ON perf_alarms(timestamp)",
+            "CREATE INDEX IF NOT EXISTS idx_alarms_type ON perf_alarms(alarm_type)",
+            "CREATE INDEX IF NOT EXISTS idx_devices_area_id ON perf_devices(area_id)",
+            "CREATE INDEX IF NOT EXISTS idx_devices_type ON perf_devices(device_type)",
+        ]
+        for idx in indexes:
+            cur.execute(idx)
+        conn.commit()
+        cur.close()
+    print("✅ 索引已创建")
+
+
+def drop_indexes(db_pool):
+    """删除性能测试用索引"""
+    with db_pool.get_connection() as conn:
+        cur = conn.cursor()
+        indexes = [
+            "idx_sensor_data_sensor_id", "idx_sensor_data_timestamp",
+            "idx_sensor_data_area_id", "idx_sensor_data_device_id",
+            "idx_sensor_data_composite", "idx_alarms_sensor_id",
+            "idx_alarms_timestamp", "idx_alarms_type",
+            "idx_devices_area_id", "idx_devices_type",
+        ]
+        for idx in indexes:
+            cur.execute(f"DROP INDEX IF EXISTS {idx}")
+        conn.commit()
+        cur.close()
+    print("🗑️ 索引已删除")
+
+
+# ==================== 查询测试 ====================
+
+class QueryBenchmark:
+    """查询性能基准测试"""
+
+    def __init__(self, db_pool):
+        self.db_pool = db_pool
+        self.results = []
+
+    def run_query(self, name, sql, params=None, rounds=QUERY_ROUNDS):
+        """执行查询并统计耗时"""
+        times = []
+        row_count = 0
+
+        for i in range(rounds):
+            with self.db_pool.get_connection() as conn:
+                cur = conn.cursor()
+                start = time.time()
+                try:
+                    cur.execute(sql, params)
+                    rows = cur.fetchall()
+                    row_count = len(rows)
+                except Exception as e:
+                    print(f"    ⚠️ 查询错误: {e}")
+                    conn.rollback()
+                    row_count = 0
+                    times.append(-1)
+                    cur.close()
+                    continue
+                elapsed_ms = (time.time() - start) * 1000
+                times.append(elapsed_ms)
+                cur.close()
+
+        valid_times = [t for t in times if t >= 0]
+        if valid_times:
+            result = {
+                "name": name,
+                "sql": sql[:100] + ("..." if len(sql) > 100 else ""),
+                "rounds": rounds,
+                "success_rounds": len(valid_times),
+                "rows_returned": row_count,
+                "min_ms": round(min(valid_times), 2),
+                "max_ms": round(max(valid_times), 2),
+                "avg_ms": round(statistics.mean(valid_times), 2),
+                "median_ms": round(statistics.median(valid_times), 2),
+            }
+        else:
+            result = {
+                "name": name,
+                "sql": sql[:100] + ("..." if len(sql) > 100 else ""),
+                "rounds": rounds,
+                "success_rounds": 0,
+                "error": "all rounds failed",
+            }
+
+        self.results.append(result)
+        status = "✅" if valid_times else "❌"
+        avg = result.get("avg_ms", "N/A")
+        print(f"  {status} {name}: avg={avg}ms, rows={row_count}")
+        return result
+
+    def run_all_benchmarks(self):
+        """运行所有基准测试"""
+        print("\n🔍 运行查询性能测试...\n")
+
+        # 1. 简单查询
+        print("  --- 简单查询 ---")
+        self.run_query(
+            "简单查询 - 按传感器ID查询最近24小时",
+            """SELECT * FROM perf_sensor_data
+               WHERE sensor_id = %s AND timestamp > NOW() - INTERVAL '24 hours'
+               ORDER BY timestamp DESC LIMIT 100""",
+            (random.randint(1, 5000),),
+        )
+
+        self.run_query(
+            "简单查询 - 按区域ID查询",
+            """SELECT * FROM perf_sensor_data
+               WHERE area_id = %s
+               ORDER BY timestamp DESC LIMIT 100""",
+            (random.randint(1, 50),),
+        )
+
+        self.run_query(
+            "简单查询 - 时间范围查询",
+            """SELECT * FROM perf_sensor_data
+               WHERE timestamp BETWEEN %s AND %s
+               ORDER BY timestamp DESC LIMIT 1000""",
+            (
+                (datetime.now() - timedelta(days=7)).isoformat(),
+                datetime.now().isoformat(),
+            ),
+        )
+
+        # 2. 聚合查询
+        print("\n  --- 聚合查询 ---")
+        self.run_query(
+            "聚合查询 - 每小时平均压力",
+            """SELECT date_trunc('hour', timestamp) AS hour,
+                      AVG(pressure) AS avg_pressure,
+                      MAX(pressure) AS max_pressure,
+                      MIN(pressure) AS min_pressure,
+                      COUNT(*) AS readings
+               FROM perf_sensor_data
+               WHERE sensor_id = %s AND timestamp > NOW() - INTERVAL '7 days'
+               GROUP BY hour ORDER BY hour""",
+            (random.randint(1, 5000),),
+        )
+
+        self.run_query(
+            "聚合查询 - 各区域统计",
+            """SELECT area_id,
+                      COUNT(*) AS total_readings,
+                      AVG(pressure) AS avg_pressure,
+                      AVG(flow) AS avg_flow,
+                      AVG(temperature) AS avg_temp
+               FROM perf_sensor_data
+               WHERE timestamp > NOW() - INTERVAL '1 day'
+               GROUP BY area_id ORDER BY total_readings DESC""",
+        )
+
+        self.run_query(
+            "聚合查询 - 日统计报表",
+            """SELECT date_trunc('day', timestamp) AS day,
+                      COUNT(*) AS readings,
+                      AVG(pressure) AS avg_pressure,
+                      AVG(flow) AS avg_flow,
+                      STDDEV(pressure) AS pressure_stddev
+               FROM perf_sensor_data
+               WHERE timestamp > NOW() - INTERVAL '30 days'
+               GROUP BY day ORDER BY day""",
+        )
+
+        # 3. JOIN 查询
+        print("\n  --- JOIN 查询 ---")
+        self.run_query(
+            "JOIN 查询 - 传感器数据 + 设备信息",
+            """SELECT s.timestamp, s.pressure, s.flow, s.temperature,
+                      d.name AS device_name, d.device_type, d.area_id, d.status
+               FROM perf_sensor_data s
+               JOIN perf_devices d ON s.device_id = d.device_id
+               WHERE s.sensor_id = %s
+               ORDER BY s.timestamp DESC LIMIT 100""",
+            (random.randint(1, 5000),),
+        )
+
+        self.run_query(
+            "JOIN 查询 - 告警 + 设备信息",
+            """SELECT a.timestamp, a.alarm_type, a.severity, a.value, a.threshold,
+                      d.name AS device_name, d.device_type, d.lng, d.lat
+               FROM perf_alarms a
+               JOIN perf_devices d ON a.sensor_id = d.id
+               WHERE a.timestamp > NOW() - INTERVAL '7 days'
+               ORDER BY a.timestamp DESC LIMIT 200""",
+        )
+
+        self.run_query(
+            "JOIN 查询 - 三表关联统计",
+            """SELECT d.area_id,
+                      COUNT(DISTINCT d.id) AS device_count,
+                      COUNT(s.id) AS reading_count,
+                      COUNT(a.id) AS alarm_count,
+                      AVG(s.pressure) AS avg_pressure
+               FROM perf_devices d
+               LEFT JOIN perf_sensor_data s ON s.device_id = d.device_id
+                   AND s.timestamp > NOW() - INTERVAL '1 day'
+               LEFT JOIN perf_alarms a ON a.sensor_id = d.id
+                   AND a.timestamp > NOW() - INTERVAL '1 day'
+               GROUP BY d.area_id ORDER BY reading_count DESC""",
+        )
+
+        # 4. GIS 空间查询
+        print("\n  --- GIS 空间查询 ---")
+
+        # 先检查 PostGIS 是否可用
+        postgis_available = False
+        try:
+            with self.db_pool.get_connection() as conn:
+                cur = conn.cursor()
+                cur.execute("SELECT PostGIS_Version()")
+                postgis_available = True
+                cur.close()
+        except Exception:
+            pass
+
+        if postgis_available:
+            self.run_query(
+                "GIS 查询 - 圆形范围内设备 (1km)",
+                """SELECT d.id, d.device_id, d.name, d.device_type,
+                          ST_Distance(
+                            ST_SetSRID(ST_MakePoint(d.lng, d.lat), 4326)::geography,
+                            ST_SetSRID(ST_MakePoint(%s, %s), 4326)::geography
+                          ) AS distance_m
+                   FROM perf_devices d
+                   WHERE ST_DWithin(
+                     ST_SetSRID(ST_MakePoint(d.lng, d.lat), 4326)::geography,
+                     ST_SetSRID(ST_MakePoint(%s, %s), 4326)::geography,
+                     1000
+                   )
+                   ORDER BY distance_m""",
+                (116.4, 39.9, 116.4, 39.9),
+            )
+        else:
+            # 无 PostGIS 时用距离公式近似
+            self.run_query(
+                "空间查询 - 距离近似计算 (无PostGIS)",
+                """SELECT id, device_id, name, device_type,
+                          SQRT(POW(lng - %s, 2) + POW(lat - %s, 2)) * 111000 AS approx_distance_m
+                   FROM perf_devices
+                   WHERE ABS(lng - %s) < 0.01 AND ABS(lat - %s) < 0.01
+                   ORDER BY approx_distance_m
+                   LIMIT 100""",
+                (116.4, 39.9, 116.4, 39.9),
+            )
+
+        self.run_query(
+            "空间查询 - 区域设备统计",
+            """SELECT area_id,
+                      COUNT(*) AS device_count,
+                      AVG(lng) AS center_lng,
+                      AVG(lat) AS center_lat,
+                      COUNT(CASE WHEN status = 'active' THEN 1 END) AS active_count
+               FROM perf_devices
+               GROUP BY area_id ORDER BY device_count DESC""",
+        )
+
+        # 5. 复杂查询
+        print("\n  --- 复杂查询 ---")
+        self.run_query(
+            "复杂查询 - 异常检测 (压力突变)",
+            """WITH sensor_stats AS (
+                 SELECT sensor_id,
+                        AVG(pressure) AS avg_p,
+                        STDDEV(pressure) AS std_p
+                 FROM perf_sensor_data
+                 WHERE timestamp > NOW() - INTERVAL '7 days'
+                 GROUP BY sensor_id
+                 HAVING COUNT(*) > 10
+               )
+               SELECT s.sensor_id, s.timestamp, s.pressure,
+                      ss.avg_p, ss.std_p,
+                      ABS(s.pressure - ss.avg_p) / NULLIF(ss.std_p, 0) AS z_score
+               FROM perf_sensor_data s
+               JOIN sensor_stats ss ON s.sensor_id = ss.sensor_id
+               WHERE ABS(s.pressure - ss.avg_p) > 3 * NULLIF(ss.std_p, 0)
+                 AND s.timestamp > NOW() - INTERVAL '1 day'
+               ORDER BY z_score DESC LIMIT 50""",
+        )
+
+        self.run_query(
+            "复杂查询 - 窗口函数 (滑动平均)",
+            """SELECT sensor_id, timestamp, pressure,
+                      AVG(pressure) OVER (
+                        PARTITION BY sensor_id
+                        ORDER BY timestamp
+                        ROWS BETWEEN 5 PRECEDING AND 5 FOLLOWING
+                      ) AS moving_avg
+               FROM perf_sensor_data
+               WHERE sensor_id = %s
+                 AND timestamp > NOW() - INTERVAL '1 day'
+               ORDER BY timestamp LIMIT 500""",
+            (random.randint(1, 5000),),
+        )
+
+        return self.results
+
+
+# ==================== 索引对比测试 ====================
+
+def run_index_comparison(db_pool):
+    """对比有无索引的查询性能"""
+    print("\n" + "=" * 60)
+    print("📊 索引性能对比测试")
+    print("=" * 60)
+
+    # 无索引测试
+    print("\n--- 无索引状态 ---")
+    drop_indexes(db_pool)
+    bench_no_idx = QueryBenchmark(db_pool)
+    results_no_idx = bench_no_idx.run_all_benchmarks()
+
+    # 有索引测试
+    print("\n--- 有索引状态 ---")
+    create_indexes(db_pool)
+
+    # 先 ANALYZE 更新统计
+    with db_pool.get_connection() as conn:
+        cur = conn.cursor()
+        cur.execute("ANALYZE perf_sensor_data, perf_alarms, perf_devices")
+        conn.commit()
+        cur.close()
+
+    bench_with_idx = QueryBenchmark(db_pool)
+    results_with_idx = bench_with_idx.run_all_benchmarks()
+
+    # 对比
+    print("\n" + "=" * 60)
+    print("📊 索引性能对比结果")
+    print("=" * 60)
+    print(f"{'查询名称':<40} {'无索引(ms)':>12} {'有索引(ms)':>12} {'提升':>10}")
+    print("-" * 74)
+
+    comparison = []
+    for no_idx, with_idx in zip(results_no_idx, results_with_idx):
+        no_avg = no_idx.get("avg_ms", 0)
+        with_avg = with_idx.get("avg_ms", 0)
+        if no_avg > 0:
+            improvement = f"{(1 - with_avg / no_avg) * 100:.1f}%"
+        else:
+            improvement = "N/A"
+        print(f"{no_idx['name']:<40} {no_avg:>12.2f} {with_avg:>12.2f} {improvement:>10}")
+        comparison.append({
+            "query": no_idx["name"],
+            "no_index_ms": no_avg,
+            "with_index_ms": with_avg,
+        })
+
+    return comparison
+
+
+# ==================== 入口 ====================
+
+def main():
+    parser = argparse.ArgumentParser(description="数据库查询压力测试")
+    parser.add_argument("--host", default=DEFAULT_HOST, help="数据库主机")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT, help="数据库端口")
+    parser.add_argument("--db", default=DEFAULT_DB, help="数据库名")
+    parser.add_argument("--user", default=DEFAULT_USER, help="数据库用户")
+    parser.add_argument("--password", default=DEFAULT_PASSWORD, help="数据库密码")
+    parser.add_argument("--generate-data", type=int, default=0,
+                        help="生成指定条数的测试数据 (如 1000000)")
+    parser.add_argument("--skip-data-gen", action="store_true", help="跳过数据生成")
+    parser.add_argument("--index-compare", action="store_true", help="运行索引对比测试")
+    parser.add_argument("--output", default=None, help="结果输出 JSON 文件路径")
+
+    args = parser.parse_args()
+
+    print(f"\n{'=' * 60}")
+    print(f"🗄️ 数据库查询压力测试")
+    print(f"{'=' * 60}")
+    print(f"数据库: {args.host}:{args.port}/{args.db}")
+    print(f"开始时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print(f"{'=' * 60}")
+
+    # 连接数据库
+    try:
+        db_pool = DBConnectionPool(
+            args.host, args.port, args.db, args.user, args.password
+        )
+    except Exception as e:
+        print(f"❌ 数据库连接失败: {e}")
+        sys.exit(1)
+
+    all_results = {}
+
+    try:
+        # 生成测试数据
+        if args.generate_data > 0 and not args.skip_data_gen:
+            generate_test_data(db_pool, args.generate_data)
+            create_indexes(db_pool)
+            # ANALYZE
+            with db_pool.get_connection() as conn:
+                cur = conn.cursor()
+                cur.execute("ANALYZE perf_sensor_data, perf_alarms, perf_devices")
+                conn.commit()
+                cur.close()
+
+        # 运行基准查询测试
+        bench = QueryBenchmark(db_pool)
+        results = bench.run_all_benchmarks()
+        all_results["query_benchmark"] = results
+
+        # 索引对比测试
+        if args.index_compare:
+            comparison = run_index_comparison(db_pool)
+            all_results["index_comparison"] = comparison
+
+    finally:
+        db_pool.close()
+
+    # 输出汇总
+    print(f"\n{'=' * 60}")
+    print("📊 查询测试汇总")
+    print(f"{'=' * 60}")
+    for r in all_results.get("query_benchmark", []):
+        avg = r.get("avg_ms", "ERR")
+        print(f"  {r['name']}: {avg}ms ({r.get('rows_returned', 0)} rows)")
+
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump(all_results, f, indent=2, ensure_ascii=False, default=str)
+        print(f"\n结果已保存到: {args.output}")
+
+    print(f"\n{'=' * 60}")
+    return all_results
+
+
+if __name__ == "__main__":
+    main()

tests/performance/locustfile.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""
+REST API 性能压力测试 - Locust
+
+使用 Locust 框架对水务管理系统的 REST API 进行并发压力测试。
+覆盖主要 API 端点：登录、数据查询、数据上报、报表查询等。
+
+运行方式：
+  locust -f locustfile.py --host=http://localhost:8080
+  # 无头模式：
+  locust -f locustfile.py --host=http://localhost:8080 --headless -u 100 -r 10 --run-time 5m
+
+支持 10/50/100/500/1000 并发用户梯度测试。
+"""
+
+import random
+import time
+import json
+from datetime import datetime, timedelta
+
+try:
+    from locust import HttpUser, task, between, events, LoadTestShape
+except ImportError:
+    print("请先安装 locust: pip install locust")
+    raise SystemExit(1)
+
+
+# ==================== 配置 ====================
+
+# 默认 API Token（实际使用时通过环境变量覆盖）
+API_TOKEN = "test-token"
+
+# 模拟的管网节点 ID 范围
+NODE_ID_RANGE = (1, 10000)
+
+# 模拟的传感器 ID 范围
+SENSOR_ID_RANGE = (1, 5000)
+
+
+# ==================== 用户行为 ====================
+
+class WaterManagementUser(HttpUser):
+    """模拟水务管理系统的用户行为"""
+
+    wait_time = between(1, 5)  # 每次请求间隔 1-5 秒
+
+    def on_start(self):
+        """用户初始化：模拟登录获取 token"""
+        self.token = API_TOKEN
+        self.headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+        # 尝试真实登录
+        try:
+            with self.client.post(
+                "/api/auth/login",
+                json={"username": "admin", "password": "admin123"},
+                catch_response=True,
+                timeout=10,
+            ) as resp:
+                if resp.status_code == 200:
+                    data = resp.json()
+                    if data.get("data", {}).get("token"):
+                        self.token = data["data"]["token"]
+                        self.headers["Authorization"] = f"Bearer {self.token}"
+                        resp.success()
+                    else:
+                        resp.failure("No token in response")
+                else:
+                    resp.failure(f"Login failed: {resp.status_code}")
+        except Exception:
+            pass  # 使用默认 token
+
+    # ---------- 数据查询类任务 ----------
+
+    @task(10)
+    def query_monitoring_data(self):
+        """查询实时监测数据（高频操作）"""
+        node_id = random.randint(*NODE_ID_RANGE)
+        start = (datetime.now() - timedelta(hours=24)).isoformat()
+        end = datetime.now().isoformat()
+
+        self.client.get(
+            f"/api/monitoring/data?nodeId={node_id}&startTime={start}&endTime={end}",
+            headers=self.headers,
+            name="/api/monitoring/data",
+            timeout=30,
+        )
+
+    @task(5)
+    def query_pressure_data(self):
+        """查询管网压力数据"""
+        area_id = random.randint(1, 100)
+        self.client.get(
+            f"/api/monitoring/pressure?areaId={area_id}",
+            headers=self.headers,
+            name="/api/monitoring/pressure",
+            timeout=30,
+        )
+
+    @task(5)
+    def query_flow_data(self):
+        """查询流量数据"""
+        sensor_id = random.randint(*SENSOR_ID_RANGE)
+        self.client.get(
+            f"/api/monitoring/flow?sensorId={sensor_id}",
+            headers=self.headers,
+            name="/api/monitoring/flow",
+            timeout=30,
+        )
+
+    @task(3)
+    def query_water_quality(self):
+        """查询水质数据"""
+        station_id = random.randint(1, 50)
+        self.client.get(
+            f"/api/monitoring/water-quality?stationId={station_id}",
+            headers=self.headers,
+            name="/api/monitoring/water-quality",
+            timeout=30,
+        )
+
+    # ---------- 数据上报类任务 ----------
+
+    @task(8)
+    def report_sensor_data(self):
+        """上报传感器数据（高频操作）"""
+        payload = {
+            "sensorId": random.randint(*SENSOR_ID_RANGE),
+            "timestamp": datetime.now().isoformat(),
+            "pressure": round(random.uniform(0.1, 0.8), 3),
+            "flow": round(random.uniform(10, 500), 2),
+            "temperature": round(random.uniform(5, 35), 1),
+            "quality": {
+                "turbidity": round(random.uniform(0, 5), 2),
+                "ph": round(random.uniform(6.5, 8.5), 2),
+                "chlorine": round(random.uniform(0.1, 0.8), 3),
+            },
+        }
+
+        with self.client.post(
+            "/api/data/report",
+            json=payload,
+            headers=self.headers,
+            catch_response=True,
+            name="/api/data/report",
+            timeout=15,
+        ) as resp:
+            if resp.status_code in (200, 201, 401, 404):
+                resp.success()
+
+    @task(3)
+    def report_alarm(self):
+        """上报告警事件"""
+        alarm_types = ["PRESSURE_HIGH", "PRESSURE_LOW", "FLOW_ABNORMAL",
+                       "QUALITY_WARNING", "LEAK_DETECTED"]
+        payload = {
+            "sensorId": random.randint(*SENSOR_ID_RANGE),
+            "alarmType": random.choice(alarm_types),
+            "severity": random.choice(["INFO", "WARNING", "CRITICAL"]),
+            "timestamp": datetime.now().isoformat(),
+            "description": f"自动告警 - {random.choice(alarm_types)}",
+            "value": round(random.uniform(0, 100), 2),
+            "threshold": round(random.uniform(50, 100), 2),
+        }
+
+        with self.client.post(
+            "/api/alarm/report",
+            json=payload,
+            headers=self.headers,
+            catch_response=True,
+            name="/api/alarm/report",
+            timeout=15,
+        ) as resp:
+            if resp.status_code in (200, 201, 401, 404):
+                resp.success()
+
+    # ---------- 报表查询类任务 ----------
+
+    @task(4)
+    def query_daily_report(self):
+        """查询日报表"""
+        date = (datetime.now() - timedelta(days=random.randint(0, 30))).strftime("%Y-%m-%d")
+        self.client.get(
+            f"/api/report/daily?date={date}",
+            headers=self.headers,
+            name="/api/report/daily",
+            timeout=30,
+        )
+
+    @task(2)
+    def query_monthly_report(self):
+        """查询月报表"""
+        year = datetime.now().year
+        month = random.randint(1, 12)
+        self.client.get(
+            f"/api/report/monthly?year={year}&month={month}",
+            headers=self.headers,
+            name="/api/report/monthly",
+            timeout=30,
+        )
+
+    @task(2)
+    def export_report(self):
+        """导出报表（较重量级操作）"""
+        start = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
+        end = datetime.now().strftime("%Y-%m-%d")
+        with self.client.get(
+            f"/api/report/export?startDate={start}&endDate={end}&format=xlsx",
+            headers=self.headers,
+            catch_response=True,
+            name="/api/report/export",
+            timeout=60,
+        ) as resp:
+            if resp.status_code in (200, 401, 404):
+                resp.success()
+
+    # ---------- 应急调度类任务 ----------
+
+    @task(1)
+    def query_emergency_list(self):
+        """查询应急事件列表"""
+        self.client.get(
+            "/api/emergency/list?page=1&size=20",
+            headers=self.headers,
+            name="/api/emergency/list",
+            timeout=30,
+        )
+
+    @task(1)
+    def simulate_pipe_burst(self):
+        """模拟爆管事件（重量级操作）"""
+        payload = {
+            "lng": round(random.uniform(116.0, 117.0), 4),
+            "lat": round(random.uniform(39.5, 40.5), 4),
+            "pipeDiameter": random.choice(["DN50", "DN100", "DN200", "DN300"]),
+            "operatorName": f"operator_{random.randint(1, 50)}",
+        }
+
+        with self.client.post(
+            "/api/emergency/dispatch/quick-pipe-burst",
+            json=payload,
+            headers=self.headers,
+            catch_response=True,
+            name="/api/emergency/dispatch/quick-pipe-burst",
+            timeout=60,
+        ) as resp:
+            if resp.status_code in (200, 201, 401, 404):
+                resp.success()
+
+    # ---------- GIS 空间查询 ----------
+
+    @task(3)
+    def gis_query_nearby(self):
+        """GIS 空间查询 - 附近设备"""
+        lng = round(random.uniform(116.0, 117.0), 6)
+        lat = round(random.uniform(39.5, 40.5), 6)
+        radius = random.choice([500, 1000, 2000, 5000])
+        self.client.get(
+            f"/api/gis/nearby?lng={lng}&lat={lat}&radius={radius}",
+            headers=self.headers,
+            name="/api/gis/nearby",
+            timeout=30,
+        )
+
+    @task(2)
+    def gis_query_area_stats(self):
+        """GIS 区域统计"""
+        area_id = random.randint(1, 50)
+        self.client.get(
+            f"/api/gis/area-stats?areaId={area_id}",
+            headers=self.headers,
+            name="/api/gis/area-stats",
+            timeout=30,
+        )
+
+
+# ==================== 梯度负载模型 ====================
+
+class StepLoadShape(LoadTestShape):
+    """
+    梯度负载测试：10 → 50 → 100 → 500 → 1000 用户
+    每个阶段持续 3 分钟，总共约 15 分钟
+    """
+
+    stages = [
+        {"duration": 180, "users": 10, "spawn_rate": 5},     # 预热 10 用户
+        {"duration": 360, "users": 50, "spawn_rate": 10},    # 50 用户
+        {"duration": 540, "users": 100, "spawn_rate": 20},   # 100 用户
+        {"duration": 720, "users": 500, "spawn_rate": 50},   # 500 用户
+        {"duration": 900, "users": 1000, "spawn_rate": 100}, # 1000 用户
+        {"duration": 1080, "users": 0, "spawn_rate": 100},   # 逐步停止
+    ]
+
+    def tick(self):
+        run_time = self.get_run_time()
+
+        for stage in self.stages:
+            if run_time < stage["duration"]:
+                tick_data = (
+                    stage["users"],
+                    stage["spawn_rate"],
+                )
+                return tick_data
+
+        return None
+
+
+# ==================== 事件钩子：自定义统计 ====================
+
+@events.test_stop.add_listener
+def on_test_stop(environment, **kwargs):
+    """测试结束时输出摘要"""
+    stats = environment.runner.stats
+    print("\n" + "=" * 60)
+    print("📊 REST API 压力测试报告")
+    print("=" * 60)
+    print(stats.serialize_current_response_times())
+    print("=" * 60)

tests/performance/mqtt_iot_stress.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+"""
+IoT MQTT 并发压力测试
+
+使用 asyncio + paho-mqtt 模拟大量 IoT 设备同时上报数据，
+测试消息到达率、延迟、MQTT broker 负载。
+
+运行方式：
+  python mqtt_iot_stress.py [--broker HOST] [--port PORT] [--devices N] [--duration S] [--freq S]
+
+示例：
+  python mqtt_iot_stress.py --devices 1000 --duration 300 --freq 5
+"""
+
+import asyncio
+import argparse
+import json
+import time
+import random
+import statistics
+import sys
+import threading
+from datetime import datetime
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
+
+try:
+    import paho.mqtt.client as mqtt
+except ImportError:
+    print("请先安装 paho-mqtt: pip install paho-mqtt")
+    sys.exit(1)
+
+
+# ==================== 配置 ====================
+
+DEFAULT_BROKER = "localhost"
+DEFAULT_PORT = 1883
+DEFAULT_DEVICES = 100
+DEFAULT_DURATION = 120  # 秒
+DEFAULT_FREQUENCY = 5   # 上报频率（秒）
+DEFAULT_TOPIC_PREFIX = "iot/sensor"
+DEFAULT_QOS = 1
+
+# 梯度测试配置
+STEP_CONFIGS = [
+    {"devices": 100, "duration": 60, "freq": 5},
+    {"devices": 500, "duration": 60, "freq": 5},
+    {"devices": 1000, "duration": 60, "freq": 5},
+    {"devices": 5000, "duration": 60, "freq": 5},
+    {"devices": 1000, "duration": 60, "freq": 1},   # 高频上报
+    {"devices": 1000, "duration": 60, "freq": 10},  # 低频上报
+]
+
+
+# ==================== 统计 ====================
+
+class MQTTStats:
+    """MQTT 统计收集器（线程安全）"""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self.connected = 0
+        self.disconnected = 0
+        self.messages_published = 0
+        self.messages_received = 0
+        self.publish_errors = 0
+        self.connect_errors = 0
+        self.latencies = []
+        self.publish_times = []
+        self.throughput_per_second = defaultdict(int)
+
+    def record_connect(self):
+        with self._lock:
+            self.connected += 1
+
+    def record_disconnect(self):
+        with self._lock:
+            self.disconnected += 1
+
+    def record_connect_error(self):
+        with self._lock:
+            self.connect_errors += 1
+
+    def record_publish(self, latency_ms):
+        with self._lock:
+            self.messages_published += 1
+            self.publish_times.append(latency_ms)
+            second = int(time.time())
+            self.throughput_per_second[second] += 1
+
+    def record_publish_error(self):
+        with self._lock:
+            self.publish_errors += 1
+
+    def record_receive(self, latency_ms):
+        with self._lock:
+            self.messages_received += 1
+            self.latencies.append(latency_ms)
+
+    def summary(self):
+        with self._lock:
+            total_attempted = self.connected + self.connect_errors
+            success_rate = (self.connected / total_attempted * 100) if total_attempted > 0 else 0
+
+            throughput_values = list(self.throughput_per_second.values())
+            throughput_stats = {}
+            if throughput_values:
+                throughput_stats = {
+                    "min_per_sec": min(throughput_values),
+                    "max_per_sec": max(throughput_values),
+                    "avg_per_sec": round(statistics.mean(throughput_values), 2),
+                }
+
+            publish_time_stats = {}
+            if self.publish_times:
+                sorted_times = sorted(self.publish_times)
+                publish_time_stats = {
+                    "min_ms": round(sorted_times[0], 2),
+                    "avg_ms": round(statistics.mean(sorted_times), 2),
+                    "max_ms": round(sorted_times[-1], 2),
+                    "p95_ms": round(sorted_times[int(len(sorted_times) * 0.95)], 2),
+                    "p99_ms": round(sorted_times[int(len(sorted_times) * 0.99)], 2),
+                }
+
+            latency_stats = {}
+            if self.latencies:
+                sorted_lat = sorted(self.latencies)
+                latency_stats = {
+                    "min_ms": round(sorted_lat[0], 2),
+                    "avg_ms": round(statistics.mean(sorted_lat), 2),
+                    "max_ms": round(sorted_lat[-1], 2),
+                    "p95_ms": round(sorted_lat[int(len(sorted_lat) * 0.95)], 2),
+                    "p99_ms": round(sorted_lat[int(len(sorted_lat) * 0.99)], 2),
+                }
+
+            return {
+                "total_devices": total_attempted,
+                "connected": self.connected,
+                "connect_errors": self.connect_errors,
+                "connection_success_rate": f"{success_rate:.1f}%",
+                "disconnected": self.disconnected,
+                "messages_published": self.messages_published,
+                "messages_received": self.messages_received,
+                "publish_errors": self.publish_errors,
+                "publish_time": publish_time_stats,
+                "message_latency": latency_stats,
+                "throughput": throughput_stats,
+            }
+
+
+# ==================== 设备模拟 ====================
+
+def generate_sensor_payload(device_id):
+    """生成传感器上报数据"""
+    return json.dumps({
+        "deviceId": f"device_{device_id:06d}",
+        "timestamp": datetime.now().isoformat(),
+        "type": random.choice(["pressure", "flow", "quality", "level"]),
+        "data": {
+            "pressure": round(random.uniform(0.1, 0.8), 3),
+            "flow": round(random.uniform(10, 500), 2),
+            "temperature": round(random.uniform(5, 35), 1),
+            "ph": round(random.uniform(6.5, 8.5), 2),
+            "turbidity": round(random.uniform(0, 5), 2),
+        },
+        "location": {
+            "lng": round(random.uniform(116.0, 117.0), 6),
+            "lat": round(random.uniform(39.5, 40.5), 6),
+        },
+        "battery": round(random.uniform(20, 100), 1),
+        "signal": random.randint(-90, -30),
+    })
+
+
+class SimulatedDevice:
+    """模拟 IoT 设备"""
+
+    def __init__(self, device_id, broker, port, stats, topic_prefix, qos):
+        self.device_id = device_id
+        self.broker = broker
+        self.port = port
+        self.stats = stats
+        self.topic = f"{topic_prefix}/{device_id:06d}/data"
+        self.qos = qos
+        self.client = None
+        self._running = False
+
+    def on_connect(self, client, userdata, flags, rc, properties=None):
+        if rc == 0:
+            self.stats.record_connect()
+            # 订阅确认主题（用于测试端到端延迟）
+            client.subscribe(f"iot/ack/{self.device_id:06d}", qos=0)
+        else:
+            self.stats.record_connect_error()
+
+    def on_disconnect(self, client, userdata, rc, properties=None):
+        self.stats.record_disconnect()
+
+    def on_message(self, client, userdata, msg):
+        """收到 ACK 消息，计算端到端延迟"""
+        try:
+            payload = json.loads(msg.payload)
+            if "sendTime" in payload:
+                latency = (time.time() - payload["sendTime"]) * 1000
+                self.stats.record_receive(latency)
+        except Exception:
+            pass
+
+    def on_publish(self, client, userdata, mid, rc=None, properties=None):
+        pass
+
+    def connect(self):
+        """连接到 MQTT broker"""
+        self.client = mqtt.Client(
+            client_id=f"device_{self.device_id:06d}",
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
+            protocol=mqtt.MQTTv311,
+        )
+        self.client.on_connect = self.on_connect
+        self.client.on_disconnect = self.on_disconnect
+        self.client.on_message = self.on_message
+        self.client.on_publish = self.on_publish
+
+        # 设置连接超时
+        self.client.connect_timeout = 10
+
+        try:
+            self.client.connect(self.broker, self.port, keepalive=60)
+            self.client.loop_start()
+            return True
+        except Exception:
+            self.stats.record_connect_error()
+            return False
+
+    def publish(self):
+        """发布一条传感器数据"""
+        if not self.client or not self.client.is_connected():
+            return False
+
+        payload = generate_sensor_payload(self.device_id)
+        start_time = time.time()
+
+        try:
+            result = self.client.publish(self.topic, payload, qos=self.qos)
+            if result.rc == mqtt.MQTT_ERR_SUCCESS:
+                latency_ms = (time.time() - start_time) * 1000
+                self.stats.record_publish(latency_ms)
+                return True
+            else:
+                self.stats.record_publish_error()
+                return False
+        except Exception:
+            self.stats.record_publish_error()
+            return False
+
+    def disconnect(self):
+        """断开连接"""
+        self._running = False
+        if self.client:
+            try:
+                self.client.loop_stop()
+                self.client.disconnect()
+            except Exception:
+                pass
+
+
+# ==================== 测试运行器 ====================
+
+def run_stress_test(broker, port, num_devices, duration, frequency, topic_prefix, qos):
+    """运行 MQTT 压力测试"""
+    stats = MQTTStats()
+
+    print(f"\n{'=' * 60}")
+    print(f"📡 IoT MQTT 压力测试")
+    print(f"{'=' * 60}")
+    print(f"Broker: {broker}:{port}")
+    print(f"模拟设备数: {num_devices}")
+    print(f"测试时长: {duration}s")
+    print(f"上报频率: 每 {frequency}s")
+    print(f"QoS: {qos}")
+    print(f"开始时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print(f"{'=' * 60}\n")
+
+    # 创建并连接所有设备
+    devices = []
+    print(f"正在连接 {num_devices} 个设备...")
+
+    batch_size = max(10, num_devices // 10)
+    for i in range(num_devices):
+        device = SimulatedDevice(i + 1, broker, port, stats, topic_prefix, qos)
+        device.connect()
+        devices.append(device)
+
+        if (i + 1) % batch_size == 0:
+            time.sleep(0.5)  # 分批连接，避免瞬时压力
+
+    # 等待连接完成
+    time.sleep(3)
+    print(f"✅ 设备连接完成: {stats.connected}/{num_devices}")
+
+    # 开始上报数据
+    print(f"\n开始数据上报（每 {frequency}s）...")
+    start_time = time.time()
+    report_count = 0
+
+    while time.time() - start_time < duration:
+        for device in devices:
+            device.publish()
+        report_count += 1
+
+        elapsed = time.time() - start_time
+        if report_count % 10 == 0:
+            print(f"  [{elapsed:.0f}s] 已发送 {stats.messages_published} 条消息, "
+                  f"错误: {stats.publish_errors}")
+
+        time.sleep(frequency)
+
+    # 停止所有设备
+    print(f"\n停止所有设备...")
+    for device in devices:
+        device.disconnect()
+
+    time.sleep(2)
+
+    # 输出结果
+    summary = stats.summary()
+    print(f"\n{'=' * 60}")
+    print(f"📊 MQTT 压力测试结果")
+    print(f"{'=' * 60}")
+    print(f"模拟设备数: {num_devices}")
+    print(f"成功连接: {summary['connected']}")
+    print(f"连接失败: {summary['connect_errors']}")
+    print(f"连接成功率: {summary['connection_success_rate']}")
+    print(f"消息发布总数: {summary['messages_published']}")
+    print(f"发布错误: {summary['publish_errors']}")
+
+    if summary['publish_time']:
+        print(f"\n消息发布时间:")
+        print(f"  最小: {summary['publish_time']['min_ms']}ms")
+        print(f"  平均: {summary['publish_time']['avg_ms']}ms")
+        print(f"  最大: {summary['publish_time']['max_ms']}ms")
+        print(f"  P95: {summary['publish_time']['p95_ms']}ms")
+        print(f"  P99: {summary['publish_time']['p99_ms']}ms")
+
+    if summary['throughput']:
+        print(f"\n吞吐量:")
+        print(f"  最小: {summary['throughput']['min_per_sec']} msg/s")
+        print(f"  最大: {summary['throughput']['max_per_sec']} msg/s")
+        print(f"  平均: {summary['throughput']['avg_per_sec']} msg/s")
+
+    if summary['message_latency']:
+        print(f"\n端到端延迟 (ACK):")
+        print(f"  最小: {summary['message_latency']['min_ms']}ms")
+        print(f"  平均: {summary['message_latency']['avg_ms']}ms")
+        print(f"  P95: {summary['message_latency']['p95_ms']}ms")
+
+    print(f"{'=' * 60}\n")
+
+    return summary
+
+
+def run_step_test(broker, port, topic_prefix, qos):
+    """运行梯度负载测试"""
+    print("\n" + "=" * 60)
+    print("📈 MQTT 梯度负载测试")
+    print("=" * 60)
+
+    results = []
+    for config in STEP_CONFIGS:
+        result = run_stress_test(
+            broker, port, config["devices"], config["duration"],
+            config["freq"], topic_prefix, qos,
+        )
+        results.append({
+            "devices": config["devices"],
+            "frequency": config["freq"],
+            **result,
+        })
+        time.sleep(10)  # 阶段间冷却
+
+    return results
+
+
+# ==================== 入口 ====================
+
+def main():
+    parser = argparse.ArgumentParser(description="IoT MQTT 压力测试")
+    parser.add_argument("--broker", default=DEFAULT_BROKER, help=f"MQTT broker 地址 (默认: {DEFAULT_BROKER})")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"MQTT broker 端口 (默认: {DEFAULT_PORT})")
+    parser.add_argument("--devices", type=int, default=DEFAULT_DEVICES, help=f"模拟设备数 (默认: {DEFAULT_DEVICES})")
+    parser.add_argument("--duration", type=int, default=DEFAULT_DURATION, help=f"测试时长秒 (默认: {DEFAULT_DURATION})")
+    parser.add_argument("--freq", type=float, default=DEFAULT_FREQUENCY, help=f"上报频率秒 (默认: {DEFAULT_FREQUENCY})")
+    parser.add_argument("--topic", default=DEFAULT_TOPIC_PREFIX, help=f"主题前缀 (默认: {DEFAULT_TOPIC_PREFIX})")
+    parser.add_argument("--qos", type=int, default=DEFAULT_QOS, choices=[0, 1, 2], help=f"QoS 级别 (默认: {DEFAULT_QOS})")
+    parser.add_argument("--step", action="store_true", help="运行梯度负载测试")
+    parser.add_argument("--output", default=None, help="结果输出 JSON 文件路径")
+
+    args = parser.parse_args()
+
+    if args.step:
+        results = run_step_test(args.broker, args.port, args.topic, args.qos)
+    else:
+        results = run_stress_test(
+            args.broker, args.port, args.devices, args.duration,
+            args.freq, args.topic, args.qos,
+        )
+
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump(results, f, indent=2, ensure_ascii=False)
+        print(f"结果已保存到: {args.output}")
+
+    return results
+
+
+if __name__ == "__main__":
+    main()

tests/performance/report_template.md

@@ -0,0 +1,218 @@
+# 水务管理系统 - 性能压力测试报告
+
+## 1. 测试概述
+
+| 项目 | 说明 |
+|------|------|
+| 项目名称 | 水务管理系统 |
+| 测试类型 | 性能压力测试 |
+| 测试日期 | {{TEST_DATE}} |
+| 测试人员 | bot_dev2 (自动化) |
+| 报告版本 | v1.0 |
+
+## 2. 测试环境
+
+### 2.1 硬件环境
+
+| 项目 | 配置 |
+|------|------|
+| 服务器 | {{SERVER_SPEC}} |
+| CPU | {{CPU_INFO}} |
+| 内存 | {{MEMORY_INFO}} |
+| 磁盘 | {{DISK_INFO}} |
+| 网络 | {{NETWORK_INFO}} |
+
+### 2.2 软件环境
+
+| 组件 | 版本/配置 |
+|------|----------|
+| 操作系统 | {{OS_INFO}} |
+| 数据库 | PostgreSQL {{PG_VERSION}} |
+| MQTT Broker | EMQX {{EMQX_VERSION}} |
+| 应用服务 | Spring Boot / FastAPI |
+| 压测工具 | Locust / asyncio |
+
+### 2.3 部署架构
+
+```
+[Load Generator] → [Nginx/网关] → [API Service (8080)]
+                                 → [WebSocket (8765)]
+                   [EMQX Broker (1883)] ← [IoT Devices]
+                                 → [PostgreSQL (5432)]
+```
+
+## 3. REST API 压力测试结果
+
+### 3.1 测试配置
+
+| 参数 | 值 |
+|------|-----|
+| 工具 | Locust |
+| 并发用户梯度 | 10 → 50 → 100 → 500 → 1000 |
+| 每阶段时长 | 3 分钟 |
+| 用户行为 | 登录→查询→上报→报表 |
+
+### 3.2 结果摘要
+
+| 并发数 | 平均响应时间(ms) | P95(ms) | P99(ms) | 吞吐量(req/s) | 错误率(%) |
+|--------|-----------------|---------|---------|---------------|-----------|
+| 10 | {{R10_AVG}} | {{R10_P95}} | {{R10_P99}} | {{R10_RPS}} | {{R10_ERR}} |
+| 50 | {{R50_AVG}} | {{R50_P95}} | {{R50_P99}} | {{R50_RPS}} | {{R50_ERR}} |
+| 100 | {{R100_AVG}} | {{R100_P95}} | {{R100_P99}} | {{R100_RPS}} | {{R100_ERR}} |
+| 500 | {{R500_AVG}} | {{R500_P95}} | {{R500_P99}} | {{R500_RPS}} | {{R500_ERR}} |
+| 1000 | {{R1000_AVG}} | {{R1000_P95}} | {{R1000_P99}} | {{R1000_RPS}} | {{R1000_ERR}} |
+
+### 3.3 各端点性能
+
+| 端点 | 平均(ms) | P95(ms) | 错误率(%) | 备注 |
+|------|----------|---------|-----------|------|
+| /api/monitoring/data | {{E1_AVG}} | {{E1_P95}} | {{E1_ERR}} | 实时监测查询 |
+| /api/data/report | {{E2_AVG}} | {{E2_P95}} | {{E2_ERR}} | 数据上报 |
+| /api/report/daily | {{E3_AVG}} | {{E3_P95}} | {{E3_ERR}} | 日报表查询 |
+| /api/report/export | {{E4_AVG}} | {{E4_P95}} | {{E4_ERR}} | 报表导出 |
+| /api/emergency/* | {{E5_AVG}} | {{E5_P95}} | {{E5_ERR}} | 应急调度 |
+| /api/gis/nearby | {{E6_AVG}} | {{E6_P95}} | {{E6_ERR}} | GIS 空间查询 |
+
+## 4. WebSocket 压力测试结果
+
+### 4.1 测试配置
+
+| 参数 | 值 |
+|------|-----|
+| 工具 | asyncio + websockets |
+| 并发连接梯度 | 100 → 500 → 1000 → 5000 |
+| 消息间隔 | 2s |
+| 消息类型 | 传感器数据上报 + 订阅 |
+
+### 4.2 结果摘要
+
+| 并发连接 | 连接成功率(%) | 消息延迟avg(ms) | P95延迟(ms) | 断连率(%) | 内存(MB) |
+|----------|--------------|-----------------|-------------|-----------|----------|
+| 100 | {{WS100_CONN}} | {{WS100_LAT}} | {{WS100_P95}} | {{WS100_DISC}} | {{WS100_MEM}} |
+| 500 | {{WS500_CONN}} | {{WS500_LAT}} | {{WS500_P95}} | {{WS500_DISC}} | {{WS500_MEM}} |
+| 1000 | {{WS1K_CONN}} | {{WS1K_LAT}} | {{WS1K_P95}} | {{WS1K_DISC}} | {{WS1K_MEM}} |
+| 5000 | {{WS5K_CONN}} | {{WS5K_LAT}} | {{WS5K_P95}} | {{WS5K_DISC}} | {{WS5K_MEM}} |
+
+## 5. IoT MQTT 压力测试结果
+
+### 5.1 测试配置
+
+| 参数 | 值 |
+|------|-----|
+| 工具 | paho-mqtt |
+| 模拟设备梯度 | 100 → 500 → 1000 → 5000 |
+| 上报频率 | 1s / 5s / 10s |
+| QoS | 1 |
+
+### 5.2 结果摘要
+
+| 设备数 | 频率(s) | 连接成功率(%) | 发布延迟avg(ms) | 吞吐量(msg/s) | 错误率(%) |
+|--------|---------|--------------|-----------------|---------------|-----------|
+| 100 | 5 | {{M100_CONN}} | {{M100_LAT}} | {{M100_TPS}} | {{M100_ERR}} |
+| 500 | 5 | {{M500_CONN}} | {{M500_LAT}} | {{M500_TPS}} | {{M500_ERR}} |
+| 1000 | 5 | {{M1K_CONN}} | {{M1K_LAT}} | {{M1K_TPS}} | {{M1K_ERR}} |
+| 5000 | 5 | {{M5K_CONN}} | {{M5K_LAT}} | {{M5K_TPS}} | {{M5K_ERR}} |
+| 1000 | 1 | {{M1K_H_CONN}} | {{M1K_H_LAT}} | {{M1K_H_TPS}} | {{M1K_H_ERR}} |
+| 1000 | 10 | {{M1K_L_CONN}} | {{M1K_L_LAT}} | {{M1K_L_TPS}} | {{M1K_L_ERR}} |
+
+## 6. 数据库查询性能测试
+
+### 6.1 测试数据规模
+
+| 表 | 记录数 | 索引数 |
+|----|--------|--------|
+| perf_sensor_data | {{DB_RECORDS}} | 5 |
+| perf_alarms | {{DB_ALARMS}} | 3 |
+| perf_devices | {{DB_DEVICES}} | 2 |
+
+### 6.2 查询性能
+
+| 查询类型 | 查询名称 | 平均(ms) | 备注 |
+|----------|----------|----------|------|
+| 简单查询 | 按传感器ID查询 | {{Q1_MS}} | 最近24h |
+| 简单查询 | 按区域查询 | {{Q2_MS}} | |
+| 简单查询 | 时间范围查询 | {{Q3_MS}} | 7天 |
+| 聚合查询 | 每小时平均压力 | {{Q4_MS}} | |
+| 聚合查询 | 各区域统计 | {{Q5_MS}} | |
+| 聚合查询 | 日统计报表 | {{Q6_MS}} | 30天 |
+| JOIN 查询 | 传感器+设备 | {{Q7_MS}} | |
+| JOIN 查询 | 告警+设备 | {{Q8_MS}} | |
+| JOIN 查询 | 三表关联统计 | {{Q9_MS}} | |
+| GIS 查询 | 范围设备查询 | {{Q10_MS}} | 1km |
+| 复杂查询 | 异常检测 | {{Q11_MS}} | 窗口函数 |
+
+### 6.3 索引性能对比
+
+| 查询 | 无索引(ms) | 有索引(ms) | 提升 |
+|------|-----------|-----------|------|
+| {{IDX_Q1}} | {{IDX1_NO}} | {{IDX1_YES}} | {{IDX1_GAIN}} |
+| {{IDX_Q2}} | {{IDX2_NO}} | {{IDX2_YES}} | {{IDX2_GAIN}} |
+| {{IDX_Q3}} | {{IDX3_NO}} | {{IDX3_YES}} | {{IDX3_GAIN}} |
+
+## 7. 瓶颈分析
+
+### 7.1 已识别瓶颈
+
+| # | 瓶颈 | 严重程度 | 影响范围 | 描述 |
+|---|------|---------|----------|------|
+| 1 | {{B1_NAME}} | {{B1_SEV}} | {{B1_SCOPE}} | {{B1_DESC}} |
+| 2 | {{B2_NAME}} | {{B2_SEV}} | {{B2_SCOPE}} | {{B2_DESC}} |
+| 3 | {{B3_NAME}} | {{B3_SEV}} | {{B3_SCOPE}} | {{B3_DESC}} |
+
+### 7.2 资源使用峰值
+
+| 指标 | 峰值 | 平均值 | 阈值建议 |
+|------|------|--------|----------|
+| CPU | {{CPU_PEAK}}% | {{CPU_AVG}}% | 80% |
+| 内存 | {{MEM_PEAK}} MB | {{MEM_AVG}} MB | 85% |
+| 磁盘 IO | {{IO_PEAK}} MB/s | {{IO_AVG}} MB/s | - |
+| 网络 | {{NET_PEAK}} | {{NET_AVG}} | - |
+
+## 8. 优化建议
+
+### 8.1 短期优化（1-2 周）
+
+1. **数据库索引优化**
+   - {{OPT1}}
+
+2. **连接池调优**
+   - {{OPT2}}
+
+3. **缓存策略**
+   - {{OPT3}}
+
+### 8.2 中期优化（1-2 月）
+
+1. **读写分离**
+   - {{OPT4}}
+
+2. **MQTT Broker 集群化**
+   - {{OPT5}}
+
+3. **WebSocket 连接管理**
+   - {{OPT6}}
+
+### 8.3 长期优化（3-6 月）
+
+1. **微服务拆分**
+   - {{OPT7}}
+
+2. **数据归档策略**
+   - {{OPT8}}
+
+3. **CDN + 静态资源优化**
+   - {{OPT9}}
+
+## 9. 结论
+
+| 维度 | 评估 |
+|------|------|
+| 当前最大并发承载 | {{MAX_CONCURRENT}} |
+| 建议最大并发 | {{RECOMMENDED_CONCURRENT}} |
+| 系统整体评级 | {{OVERALL_RATING}} |
+| 是否满足 SLA | {{SLA_COMPLIANCE}} |
+
+---
+
+*报告生成时间: {{GENERATED_AT}}*
+*测试工具: Locust, asyncio+websockets, paho-mqtt, psycopg2*

tests/performance/requirements.txt

@@ -0,0 +1,7 @@
+# 性能压力测试依赖
+locust>=2.20.0
+websockets>=12.0
+paho-mqtt>=2.0.0
+psycopg2-binary>=2.9.9
+pandas>=2.0.0
+matplotlib>=3.8.0

tests/performance/run_all_benchmarks.sh

@@ -0,0 +1,299 @@
+#!/bin/bash
+#
+# 水务管理系统 - 统一性能压力测试入口脚本
+#
+# 依次运行：REST API / WebSocket / MQTT IoT / 数据库查询 四项压力测试，
+# 收集系统指标（CPU、内存、磁盘 IO），生成综合报告。
+#
+# 用法：
+#   bash run_all_benchmarks.sh [--quick] [--output-dir DIR]
+#
+# --quick: 快速模式（减少测试时长，适合 CI/CD）
+# --output-dir: 结果输出目录（默认 ./reports/YYYYMMDD_HHMMSS）
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# ==================== 参数解析 ====================
+QUICK_MODE=false
+OUTPUT_DIR=""
+API_HOST="${API_HOST:-localhost}"
+API_PORT="${API_PORT:-8080}"
+WS_HOST="${WS_HOST:-localhost}"
+WS_PORT="${WS_PORT:-8765}"
+MQTT_BROKER="${MQTT_BROKER:-localhost}"
+MQTT_PORT="${MQTT_PORT:-1883}"
+DB_HOST="${DB_HOST:-localhost}"
+DB_PORT="${DB_PORT:-5432}"
+DB_NAME="${DB_NAME:-water_management}"
+DB_USER="${DB_USER:-postgres}"
+DB_PASS="${DB_PASS:-postgres}"
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --quick) QUICK_MODE=true; shift ;;
+        --output-dir) OUTPUT_DIR="$2"; shift 2 ;;
+        --api-host) API_HOST="$2"; shift 2 ;;
+        --ws-host) WS_HOST="$2"; shift 2 ;;
+        --mqtt-broker) MQTT_BROKER="$2"; shift 2 ;;
+        --db-host) DB_HOST="$2"; shift 2 ;;
+        *) echo "未知参数: $1"; exit 1 ;;
+    esac
+done
+
+# 默认输出目录
+if [[ -z "$OUTPUT_DIR" ]]; then
+    OUTPUT_DIR="./reports/$(date +%Y%m%d_%H%M%S)"
+fi
+mkdir -p "$OUTPUT_DIR"
+
+# ==================== 工具函数 ====================
+
+log() { echo "[$(date '+%H:%M:%S')] $*"; }
+error() { echo "[$(date '+%H:%M:%S')] ❌ $*" >&2; }
+
+check_python_deps() {
+    log "检查 Python 依赖..."
+    pip install -q -r requirements.txt 2>/dev/null || {
+        error "依赖安装失败，请手动执行: pip install -r requirements.txt"
+        exit 1
+    }
+}
+
+# 收集系统指标
+SYSMONITOR_PID=""
+start_system_monitor() {
+    local interval=5
+    local output_file="$1"
+    (
+        echo "timestamp,cpu_percent,memory_mb,disk_read_mb,disk_write_mb" > "$output_file"
+        while true; do
+            local ts=$(date '+%Y-%m-%d %H:%M:%S')
+            local cpu=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' 2>/dev/null || echo "0")
+            local mem=$(free -m | awk '/Mem:/{print $3}' 2>/dev/null || echo "0")
+            local dr=$(cat /proc/diskstats 2>/dev/null | awk '{r+=$6} END{print r/2048}' || echo "0")
+            local dw=$(cat /proc/diskstats 2>/dev/null | awk '{w+=$10} END{print w/2048}' || echo "0")
+            echo "$ts,$cpu,$mem,$dr,$dw" >> "$output_file"
+            sleep $interval
+        done
+    ) &
+    SYSMONITOR_PID=$!
+}
+
+stop_system_monitor() {
+    if [[ -n "$SYSMONITOR_PID" ]]; then
+        kill "$SYSMONITOR_PID" 2>/dev/null || true
+        wait "$SYSMONITOR_PID" 2>/dev/null || true
+        SYSMONITOR_PID=""
+    fi
+}
+
+# 收集系统信息
+collect_system_info() {
+    local output_file="$1"
+    cat > "$output_file" << EOF
+# 系统环境信息
+- 主机名: $(hostname)
+- 操作系统: $(uname -a)
+- CPU: $(nproc) 核
+- 内存: $(free -h | awk '/Mem:/{print $2}')
+- 磁盘: $(df -h / | awk 'NR==2{print $2 " total, " $4 " available"}')
+- Python: $(python3 --version 2>&1)
+- 测试时间: $(date '+%Y-%m-%d %H:%M:%S')
+- 快速模式: $QUICK_MODE
+EOF
+}
+
+# ==================== 测试配置 ====================
+
+if $QUICK_MODE; then
+    REST_USERS=50
+    REST_DURATION="30s"
+    WS_CLIENTS=100
+    WS_DURATION=30
+    MQTT_DEVICES=100
+    MQTT_DURATION=30
+    DB_RECORDS=100000
+else
+    REST_USERS=500
+    REST_DURATION="3m"
+    WS_CLIENTS=1000
+    WS_DURATION=120
+    MQTT_DEVICES=1000
+    MQTT_DURATION=120
+    DB_RECORDS=1000000
+fi
+
+# ==================== 开始测试 ====================
+
+echo ""
+echo "============================================================"
+echo "🏗️  水务管理系统 - 性能压力测试"
+echo "============================================================"
+echo "测试时间: $(date '+%Y-%m-%d %H:%M:%S')"
+echo "输出目录: $OUTPUT_DIR"
+echo "快速模式: $QUICK_MODE"
+echo "============================================================"
+
+# 检查依赖
+check_python_deps
+
+# 收集系统信息
+SYSTEM_INFO="$OUTPUT_DIR/system_info.md"
+collect_system_info "$SYSTEM_INFO"
+
+# 启动系统监控
+SYSMON_CSV="$OUTPUT_DIR/system_metrics.csv"
+start_system_monitor "$SYSMON_CSV"
+
+# 注册退出清理
+trap stop_system_monitor EXIT
+
+# ---------- 1. REST API 压力测试 ----------
+log ""
+log "=========================================="
+log "📡 测试 1/4: REST API 压力测试"
+log "=========================================="
+
+REST_RESULT="$OUTPUT_DIR/rest_api_result.json"
+if command -v locust &>/dev/null; then
+    timeout 600 locust -f locustfile.py \
+        --host="http://${API_HOST}:${API_PORT}" \
+        --headless -u "$REST_USERS" -r 10 \
+        --run-time "$REST_DURATION" \
+        --csv="$OUTPUT_DIR/rest_api" \
+        --json 2>&1 | tee "$OUTPUT_DIR/rest_api.log" || true
+    log "✅ REST API 测试完成"
+else
+    log "⚠️ locust 未安装，跳过 REST API 测试"
+    echo '{"skipped": true, "reason": "locust not installed"}' > "$REST_RESULT"
+fi
+
+# ---------- 2. WebSocket 压力测试 ----------
+log ""
+log "=========================================="
+log "🔌 测试 2/4: WebSocket 压力测试"
+log "=========================================="
+
+WS_RESULT="$OUTPUT_DIR/websocket_result.json"
+timeout 600 python3 websocket_stress.py \
+    --host "$WS_HOST" --port "$WS_PORT" \
+    --clients "$WS_CLIENTS" --duration "$WS_DURATION" \
+    --output "$WS_RESULT" 2>&1 | tee "$OUTPUT_DIR/websocket.log" || true
+log "✅ WebSocket 测试完成"
+
+# ---------- 3. MQTT IoT 压力测试 ----------
+log ""
+log "=========================================="
+log "📡 测试 3/4: IoT MQTT 压力测试"
+log "=========================================="
+
+MQTT_RESULT="$OUTPUT_DIR/mqtt_result.json"
+timeout 600 python3 mqtt_iot_stress.py \
+    --broker "$MQTT_BROKER" --port "$MQTT_PORT" \
+    --devices "$MQTT_DEVICES" --duration "$MQTT_DURATION" \
+    --output "$MQTT_RESULT" 2>&1 | tee "$OUTPUT_DIR/mqtt.log" || true
+log "✅ MQTT 测试完成"
+
+# ---------- 4. 数据库查询测试 ----------
+log ""
+log "=========================================="
+log "🗄️ 测试 4/4: 数据库查询压力测试"
+log "=========================================="
+
+DB_RESULT="$OUTPUT_DIR/db_query_result.json"
+timeout 600 python3 db_query_stress.py \
+    --host "$DB_HOST" --port "$DB_PORT" \
+    --db "$DB_NAME" --user "$DB_USER" --password "$DB_PASS" \
+    --generate-data "$DB_RECORDS" \
+    --index-compare \
+    --output "$DB_RESULT" 2>&1 | tee "$OUTPUT_DIR/db_query.log" || true
+log "✅ 数据库测试完成"
+
+# ==================== 停止监控 ====================
+stop_system_monitor
+
+# ==================== 生成综合报告 ====================
+log ""
+log "=========================================="
+log "📝 生成综合报告"
+log "=========================================="
+
+REPORT_FILE="$OUTPUT_DIR/report.md"
+
+# 复制报告模板并填充
+if [[ -f report_template.md ]]; then
+    cp report_template.md "$REPORT_FILE"
+    # 追加实际结果
+    cat >> "$REPORT_FILE" << EOF
+
+---
+## 实际测试结果
+
+### 测试环境
+$(cat "$SYSTEM_INFO")
+
+### REST API 结果
+\`\`\`
+$(tail -30 "$OUTPUT_DIR/rest_api.log" 2>/dev/null || echo "无数据")
+\`\`\`
+
+### WebSocket 结果
+\`\`\`json
+$(cat "$WS_RESULT" 2>/dev/null || echo "无数据")
+\`\`\`
+
+### MQTT IoT 结果
+\`\`\`json
+$(cat "$MQTT_RESULT" 2>/dev/null || echo "无数据")
+\`\`\`
+
+### 数据库查询结果
+\`\`\`json
+$(cat "$DB_RESULT" 2>/dev/null || echo "无数据")
+\`\`\`
+
+### 系统资源指标
+\`\`\`csv
+$(head -20 "$SYSMON_CSV" 2>/dev/null || echo "无数据")
+\`\`\`
+EOF
+else
+    # 简单报告
+    cat > "$REPORT_FILE" << EOF
+# 性能压力测试报告
+
+## 测试时间
+$(date '+%Y-%m-%d %H:%M:%S')
+
+## 测试环境
+$(cat "$SYSTEM_INFO")
+
+## 测试结果摘要
+
+| 测试项 | 状态 | 结果文件 |
+|--------|------|----------|
+| REST API | ✅ | rest_api_result.json |
+| WebSocket | ✅ | websocket_result.json |
+| MQTT IoT | ✅ | mqtt_result.json |
+| 数据库查询 | ✅ | db_query_result.json |
+
+## 系统资源指标
+见 system_metrics.csv
+EOF
+fi
+
+log "✅ 综合报告已生成: $REPORT_FILE"
+
+# ==================== 完成 ====================
+echo ""
+echo "============================================================"
+echo "🎉 所有压力测试完成！"
+echo "============================================================"
+echo "输出目录: $OUTPUT_DIR"
+echo "文件列表:"
+ls -la "$OUTPUT_DIR/"
+echo "============================================================"

tests/performance/websocket_stress.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""
+WebSocket 长连接并发压力测试
+
+使用 asyncio + websockets 模拟大量并发 WebSocket 连接，
+测试连接成功率、消息延迟、断连率及服务器资源消耗。
+
+运行方式：
+  python websocket_stress.py [--host HOST] [--port PORT] [--clients N] [--duration S]
+
+示例：
+  python websocket_stress.py --clients 1000 --duration 300
+"""
+
+import asyncio
+import argparse
+import json
+import time
+import random
+import statistics
+import resource
+import sys
+from datetime import datetime
+from collections import defaultdict
+
+try:
+    import websockets
+    from websockets.asyncio.client import connect as ws_connect
+except ImportError:
+    try:
+        import websockets
+        from websockets import connect as ws_connect
+    except ImportError:
+        print("请先安装 websockets: pip install websockets")
+        sys.exit(1)
+
+
+# ==================== 配置 ====================
+
+DEFAULT_HOST = "localhost"
+DEFAULT_PORT = 8765
+DEFAULT_CLIENTS = 100
+DEFAULT_DURATION = 120  # 秒
+DEFAULT_MESSAGE_INTERVAL = 2  # 秒
+WS_PATH = "/ws"
+
+# 梯度测试配置
+STEP_CONFIGS = [
+    {"clients": 100, "duration": 60},
+    {"clients": 500, "duration": 60},
+    {"clients": 1000, "duration": 60},
+    {"clients": 5000, "duration": 60},
+]
+
+
+# ==================== 统计 ====================
+
+class Stats:
+    """线程安全的统计收集器"""
+
+    def __init__(self):
+        self.connected = 0
+        self.disconnected = 0
+        self.messages_sent = 0
+        self.messages_received = 0
+        self.errors = 0
+        self.latencies = []
+        self.connect_times = []
+        self._lock = asyncio.Lock()
+
+    async def record_connect(self, connect_time_ms):
+        async with self._lock:
+            self.connected += 1
+            self.connect_times.append(connect_time_ms)
+
+    async def record_disconnect(self):
+        async with self._lock:
+            self.disconnected += 1
+
+    async def record_send(self):
+        async with self._lock:
+            self.messages_sent += 1
+
+    async def record_receive(self, latency_ms):
+        async with self._lock:
+            self.messages_received += 1
+            self.latencies.append(latency_ms)
+
+    async def record_error(self):
+        async with self._lock:
+            self.errors += 1
+
+    def summary(self):
+        total_attempted = self.connected + self.errors
+        success_rate = (self.connected / total_attempted * 100) if total_attempted > 0 else 0
+
+        latency_stats = {}
+        if self.latencies:
+            latency_stats = {
+                "min_ms": round(min(self.latencies), 2),
+                "max_ms": round(max(self.latencies), 2),
+                "avg_ms": round(statistics.mean(self.latencies), 2),
+                "median_ms": round(statistics.median(self.latencies), 2),
+                "p95_ms": round(sorted(self.latencies)[int(len(self.latencies) * 0.95)], 2)
+                if len(self.latencies) > 1 else round(self.latencies[0], 2),
+                "p99_ms": round(sorted(self.latencies)[int(len(self.latencies) * 0.99)], 2)
+                if len(self.latencies) > 1 else round(self.latencies[0], 2),
+            }
+
+        connect_time_stats = {}
+        if self.connect_times:
+            connect_time_stats = {
+                "min_ms": round(min(self.connect_times), 2),
+                "avg_ms": round(statistics.mean(self.connect_times), 2),
+                "max_ms": round(max(self.connect_times), 2),
+            }
+
+        return {
+            "total_connections": total_attempted,
+            "successful_connections": self.connected,
+            "failed_connections": self.errors,
+            "connection_success_rate": f"{success_rate:.1f}%",
+            "disconnections": self.disconnected,
+            "messages_sent": self.messages_sent,
+            "messages_received": self.messages_received,
+            "latency": latency_stats,
+            "connect_time": connect_time_stats,
+        }
+
+
+# ==================== 客户端模拟 ====================
+
+def generate_message():
+    """生成模拟的传感器上报消息"""
+    return json.dumps({
+        "type": "sensor_data",
+        "sensorId": random.randint(1, 5000),
+        "timestamp": datetime.now().isoformat(),
+        "data": {
+            "pressure": round(random.uniform(0.1, 0.8), 3),
+            "flow": round(random.uniform(10, 500), 2),
+            "temperature": round(random.uniform(5, 35), 1),
+        },
+    })
+
+
+async def client_worker(client_id, uri, stats, duration, message_interval):
+    """单个 WebSocket 客户端工作线程"""
+    start_time = time.time()
+    connect_start = time.time()
+
+    try:
+        async with ws_connect(uri) as ws:
+            connect_time_ms = (time.time() - connect_start) * 1000
+            await stats.record_connect(connect_time_ms)
+
+            # 发送订阅消息
+            subscribe_msg = json.dumps({
+                "type": "subscribe",
+                "channels": [f"sensor_{random.randint(1, 100)}"],
+            })
+            await ws.send(subscribe_msg)
+
+            # 定期发送消息
+            while time.time() - start_time < duration:
+                try:
+                    msg = generate_message()
+                    send_time = time.time()
+                    await ws.send(msg)
+                    await stats.record_send()
+
+                    # 尝试接收消息（非阻塞）
+                    try:
+                        response = await asyncio.wait_for(ws.recv(), timeout=1.0)
+                        latency_ms = (time.time() - send_time) * 1000
+                        await stats.record_receive(latency_ms)
+                    except asyncio.TimeoutError:
+                        pass  # 没有响应是正常的
+                    except Exception:
+                        pass
+
+                    await asyncio.sleep(message_interval + random.uniform(0, 1))
+
+                except Exception:
+                    await stats.record_error()
+                    break
+
+    except Exception as e:
+        await stats.record_error()
+    finally:
+        await stats.record_disconnect()
+
+
+# ==================== 资源监控 ====================
+
+async def monitor_resources(duration, interval=5):
+    """监控系统资源"""
+    resource_stats = {
+        "cpu_percent": [],
+        "memory_mb": [],
+        "timestamps": [],
+    }
+
+    start = time.time()
+    while time.time() - start < duration:
+        try:
+            usage = resource.getrusage(resource.RUSAGE_SELF)
+            mem_mb = usage.ru_maxrss / 1024  # Linux: KB → MB
+            resource_stats["memory_mb"].append(round(mem_mb, 2))
+            resource_stats["timestamps"].append(round(time.time() - start, 1))
+        except Exception:
+            pass
+        await asyncio.sleep(interval)
+
+    return resource_stats
+
+
+# ==================== 主测试函数 ====================
+
+async def run_stress_test(host, port, num_clients, duration, message_interval):
+    """运行压力测试"""
+    uri = f"ws://{host}:{port}{WS_PATH}"
+    stats = Stats()
+
+    print(f"\n{'=' * 60}")
+    print(f"🔌 WebSocket 压力测试")
+    print(f"{'=' * 60}")
+    print(f"目标: {uri}")
+    print(f"并发连接数: {num_clients}")
+    print(f"测试时长: {duration}s")
+    print(f"消息间隔: {message_interval}s")
+    print(f"开始时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print(f"{'=' * 60}\n")
+
+    # 启动所有客户端（分批启动避免瞬时压力）
+    tasks = []
+    batch_size = max(10, num_clients // 10)
+    resource_task = asyncio.create_task(monitor_resources(duration + 30))
+
+    for i in range(num_clients):
+        task = asyncio.create_task(
+            client_worker(i, uri, stats, duration, message_interval)
+        )
+        tasks.append(task)
+
+        # 分批启动
+        if (i + 1) % batch_size == 0:
+            await asyncio.sleep(0.5)
+
+    print(f"✅ 已启动 {num_clients} 个 WebSocket 客户端")
+
+    # 等待测试完成
+    await asyncio.sleep(duration + 5)  # 额外 5 秒等待收尾
+
+    # 取消剩余任务
+    for task in tasks:
+        task.cancel()
+
+    # 等待资源监控结束
+    try:
+        resource_data = await asyncio.wait_for(resource_task, timeout=10)
+    except asyncio.TimeoutError:
+        resource_data = {"memory_mb": [], "timestamps": []}
+
+    # 输出结果
+    summary = stats.summary()
+    print(f"\n{'=' * 60}")
+    print(f"📊 WebSocket 压力测试结果")
+    print(f"{'=' * 60}")
+    print(f"并发连接数: {num_clients}")
+    print(f"成功连接: {summary['successful_connections']}")
+    print(f"失败连接: {summary['failed_connections']}")
+    print(f"连接成功率: {summary['connection_success_rate']}")
+    print(f"断连次数: {summary['disconnections']}")
+    print(f"消息发送: {summary['messages_sent']}")
+    print(f"消息接收: {summary['messages_received']}")
+
+    if summary['latency']:
+        print(f"\n消息延迟:")
+        print(f"  最小: {summary['latency']['min_ms']}ms")
+        print(f"  最大: {summary['latency']['max_ms']}ms")
+        print(f"  平均: {summary['latency']['avg_ms']}ms")
+        print(f"  中位数: {summary['latency']['median_ms']}ms")
+        print(f"  P95: {summary['latency']['p95_ms']}ms")
+        print(f"  P99: {summary['latency']['p99_ms']}ms")
+
+    if summary['connect_time']:
+        print(f"\n连接建立时间:")
+        print(f"  最小: {summary['connect_time']['min_ms']}ms")
+        print(f"  平均: {summary['connect_time']['avg_ms']}ms")
+        print(f"  最大: {summary['connect_time']['max_ms']}ms")
+
+    if resource_data.get("memory_mb"):
+        print(f"\n资源消耗:")
+        print(f"  峰值内存: {max(resource_data['memory_mb']):.2f} MB")
+        print(f"  平均内存: {statistics.mean(resource_data['memory_mb']):.2f} MB")
+
+    print(f"{'=' * 60}\n")
+
+    return summary
+
+
+async def run_step_test(host, port, message_interval):
+    """运行梯度负载测试"""
+    print("\n" + "=" * 60)
+    print("📈 WebSocket 梯度负载测试")
+    print("=" * 60)
+
+    results = []
+    for config in STEP_CONFIGS:
+        result = await run_stress_test(
+            host, port, config["clients"], config["duration"], message_interval
+        )
+        results.append({
+            "clients": config["clients"],
+            **result,
+        })
+        await asyncio.sleep(10)  # 阶段间冷却
+
+    return results
+
+
+# ==================== 入口 ====================
+
+def main():
+    parser = argparse.ArgumentParser(description="WebSocket 压力测试")
+    parser.add_argument("--host", default=DEFAULT_HOST, help=f"目标主机 (默认: {DEFAULT_HOST})")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"目标端口 (默认: {DEFAULT_PORT})")
+    parser.add_argument("--clients", type=int, default=DEFAULT_CLIENTS, help=f"并发连接数 (默认: {DEFAULT_CLIENTS})")
+    parser.add_argument("--duration", type=int, default=DEFAULT_DURATION, help=f"测试时长秒 (默认: {DEFAULT_DURATION})")
+    parser.add_argument("--interval", type=float, default=DEFAULT_MESSAGE_INTERVAL, help=f"消息间隔秒 (默认: {DEFAULT_MESSAGE_INTERVAL})")
+    parser.add_argument("--step", action="store_true", help="运行梯度负载测试 (100/500/1000/5000)")
+    parser.add_argument("--output", default=None, help="结果输出 JSON 文件路径")
+
+    args = parser.parse_args()
+
+    if args.step:
+        results = asyncio.run(run_step_test(args.host, args.port, args.interval))
+    else:
+        results = asyncio.run(
+            run_stress_test(args.host, args.port, args.clients, args.duration, args.interval)
+        )
+
+    # 保存结果
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump(results, f, indent=2, ensure_ascii=False)
+        print(f"结果已保存到: {args.output}")
+
+    return results
+
+
+if __name__ == "__main__":
+    main()