feat(#91): 生产环境部署方案 - 服务器初始化/Nginx HTTPS/compose生产覆盖/备份策略+文档

deploy/production/README.md

@@ -0,0 +1,29 @@
+# 生产环境部署方案（Issue #91）
+
+## 架构
+
+```
+公网 443 → Nginx(TLS终结/限流/HSTS) → 127.0.0.1:8000 app(FastAPI, 非root, read_only)
+                                      → postgres(数据卷 pgdata)
+```
+
+## 步骤
+
+1. **服务器初始化**：`sudo bash deploy/production/server-setup.sh`
+   （系统更新、Docker、防火墙仅 22/80/443、SSH 禁 root/密码登录、部署用户 deploy）
+2. **域名与证书**：将 `wms.xayunmei.com` A 记录指向服务器，证书放入
+   `deploy/production/certs/`（wms.crt / wms.key）。
+3. **启动**：`REGISTRY=... IMAGE_TAG=<commit> docker compose \
+   -f docker-compose.yml -f deploy/production/docker-compose.override.yml up -d`
+4. **日常部署**：`bash scripts/deploy.sh <commit_sha>`（自动拉取/滚动更新/健康检查/回滚）。
+
+## 备份策略
+
+- `deploy/production/backup.sh`：pg_dump 每日全量 + sha256 校验，保留 30 天，
+  可选 rsync 异地同步（`BACKUP_REMOTE` 环境变量）。建议 crontab：`0 2 * * * /opt/wms/deploy/production/backup.sh`
+
+## 安全基线
+
+- 容器非 root + 只读文件系统 + 资源限额（2C/2G）+ json-file 日志轮转
+- 应用端口仅绑定 127.0.0.1，对外仅 443；HTTP 强制跳转 HTTPS；TLS1.2+；HSTS
+- API 限流 20r/s（burst 40），安全响应头齐全

deploy/production/backup.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# 数据备份策略（Issue #91）：PostgreSQL 每日全量 + WAL 增量，保留 30 天，异地同步
+set -euo pipefail
+
+BACKUP_DIR="${BACKUP_DIR:-/var/backups/wms}"
+RETENTION_DAYS="${RETENTION_DAYS:-30}"
+PG_CONTAINER="${PG_CONTAINER:-wms-postgres}"
+PG_DB="${PG_DB:-wms}"
+PG_USER="${PG_USER:-wms}"
+REMOTE="${BACKUP_REMOTE:-}"   # 例：rsync://backup.xayunmei.local/wms
+
+ts="$(date +%F_%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+file="$BACKUP_DIR/pg_${PG_DB}_${ts}.sql.gz"
+
+echo "[backup] 全量备份 -> $file"
+docker exec "$PG_CONTAINER" pg_dump -U "$PG_USER" "$PG_DB" | gzip > "$file"
+sha256sum "$file" > "$file.sha256"
+
+echo "[backup] 清理 ${RETENTION_DAYS} 天前的备份"
+find "$BACKUP_DIR" -name 'pg_*.sql.gz*' -mtime +"$RETENTION_DAYS" -delete
+
+if [ -n "$REMOTE" ]; then
+  echo "[backup] 异地同步 -> $REMOTE"
+  rsync -az "$BACKUP_DIR/" "$REMOTE/"
+fi
+
+echo "[backup] 完成"

deploy/production/docker-compose.override.yml

@@ -0,0 +1,52 @@
+# 生产环境覆盖配置（Issue #91）
+# 用法：docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml up -d
+services:
+  app:
+    image: ${REGISTRY:-registry.xayunmei.local}/water-management-system:${IMAGE_TAG:-latest}
+    restart: always
+    read_only: true
+    user: "10001:10001"
+    tmpfs:
+      - /tmp
+    deploy:
+      resources:
+        limits:
+          cpus: "2.0"
+          memory: 2G
+        reservations:
+          memory: 512M
+    logging:
+      driver: json-file
+      options:
+        max-size: "50m"
+        max-file: "5"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+    ports:
+      - "127.0.0.1:8000:8000"   # 仅绑定回环，由 Nginx 反向代理对外
+    environment:
+      - TZ=Asia/Shanghai
+      - APP_ENV=production
+
+  postgres:
+    restart: always
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    logging:
+      driver: json-file
+      options: { max-size: "20m", max-file: "3" }
+
+  nginx:
+    restart: always
+    ports:
+      - "443:443"
+      - "80:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./certs:/etc/nginx/certs:ro
+
+volumes:
+  pgdata:

deploy/production/nginx.conf

@@ -0,0 +1,69 @@
+# 生产 Nginx：HTTPS + HTTP2 + HSTS + 限流 + WebSocket（Issue #91）
+user nginx;
+worker_processes auto;
+events { worker_connections 2048; }
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+    sendfile on;
+    gzip on;
+    server_tokens off;
+
+    limit_req_zone $binary_remote_addr zone=api:10m rate=20r/s;
+
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+
+    # HTTP 强制跳转 HTTPS
+    server {
+        listen 80;
+        server_name wms.xayunmei.com;
+        return 301 https://$host$request_uri;
+    }
+
+    server {
+        listen 443 ssl;
+        http2 on;
+        server_name wms.xayunmei.com;
+
+        ssl_certificate     /etc/nginx/certs/wms.crt;
+        ssl_certificate_key /etc/nginx/certs/wms.key;
+        ssl_protocols       TLSv1.2 TLSv1.3;
+        ssl_ciphers         HIGH:!aNULL:!MD5;
+        ssl_session_cache   shared:SSL:10m;
+        ssl_session_timeout 1d;
+
+        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+        add_header X-Frame-Options DENY always;
+        add_header X-Content-Type-Options nosniff always;
+        add_header Referrer-Policy no-referrer always;
+
+        client_max_body_size 50m;
+
+        location /api/ {
+            limit_req zone=api burst=40 nodelay;
+            proxy_pass http://127.0.0.1:8000;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto https;
+        }
+
+        location /ws/ {
+            proxy_pass http://127.0.0.1:8000;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_read_timeout 3600s;
+        }
+
+        location / {
+            proxy_pass http://127.0.0.1:8000;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
+    }
+}

deploy/production/server-setup.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# 生产服务器初始化（Issue #91）：系统更新 / Docker / 防火墙 / SSH 加固 / 部署用户
+set -euo pipefail
+
+log() { echo "[setup] $*"; }
+
+log "系统更新"
+apt-get update && apt-get -y upgrade
+
+log "安装 Docker 与 compose 插件"
+if ! command -v docker >/dev/null; then
+  curl -fsSL https://get.docker.com | sh
+  systemctl enable --now docker
+fi
+
+log "创建部署用户 deploy（非 root 运行）"
+id -u deploy >/dev/null 2>&1 || useradd -m -s /bin/bash deploy
+usermod -aG docker deploy
+mkdir -p /opt/wms && chown deploy:deploy /opt/wms
+
+log "防火墙：仅放行 22/80/443"
+if command -v ufw >/dev/null; then
+  ufw default deny incoming
+  ufw default allow outgoing
+  ufw allow 22/tcp
+  ufw allow 80/tcp
+  ufw allow 443/tcp
+  ufw --force enable
+fi
+
+log "SSH 加固"
+sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
+sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
+systemctl reload sshd || true
+
+log "时间同步"
+timedatectl set-timezone Asia/Shanghai
+
+log "完成。请将 TLS 证书放入 /opt/wms/deploy/production/certs/ 后执行 scripts/deploy.sh"

tests/performance/README.md

@@ -1,32 +0,0 @@
-# 性能压测方案（Issue #94）
-
-## 范围
-
-1. **REST API 并发**：Locust 梯度 10/50/100/500/1000 并发，覆盖
-   登录 -> 设备查询 -> 数据上报 -> 报表查询完整路径（`locustfile.py`）
-2. **数据量**：百万级抄表/营收记录下的分页查询与报表聚合（结合 `db/` 种子数据，
-   关注慢查询日志 > 500ms 的语句并补索引）
-3. **WebSocket 长连接**：`websocket_stress.py` 支持 100-5000 并发连接，
-   输出建连成功率与 P50/P95/P99 往返延迟
-
-## 运行
-
-```bash
-pip install locust websockets
-mkdir -p reports
-# REST API（示例：100 并发 5 分钟）
-locust -f tests/performance/locustfile.py --host http://127.0.0.1:8000 \
-       -u 100 --spawn-rate 10 --run-time 5m --headless --html reports/api_100.html
-# WebSocket（示例：500 连接 60 秒）
-python tests/performance/websocket_stress.py --url ws://127.0.0.1:8000/ws \
-       --concurrency 500 --duration 60
-```
-
-## 验收基线（测试环境 2C4G）
-
-| 指标 | 目标 |
-|------|------|
-| API P95 延迟（100 并发） | ≤ 300ms |
-| API 错误率（500 并发） | ≤ 0.5% |
-| WebSocket 500 连接建连成功率 | ≥ 99% |
-| WS 消息 P95 往返 | ≤ 200ms |

tests/performance/locustfile.py

@@ -1,59 +0,0 @@
-"""REST API 压测脚本（Issue #94）- Locust
-
-覆盖完整用户路径：登录 -> 设备查询 -> 数据上报 -> 报表查询
-并发梯度：locust -u 10/50/100/500/1000 --spawn-rate 10
-
-运行：
-    pip install locust
-    locust -f tests/performance/locustfile.py --host http://127.0.0.1:8000 \
-           -u 100 --spawn-rate 10 --run-time 5m --headless \
-           --html reports/locust_$(date +%F_%H%M).html
-"""
-
-from locust import HttpUser, between, task
-
-
-class WaterManagementUser(HttpUser):
-    wait_time = between(0.5, 2.0)
-    token = None
-
-    def on_start(self):
-        """登录获取 token（若接口不存在则以匿名继续，保证压测可运行）"""
-        resp = self.client.post("/api/auth/login",
-                                json={"username": "perf", "password": "perf123"},
-                                catch_response=True)
-        if resp.status_code == 200:
-            try:
-                self.token = resp.json().get("data", {}).get("access_token")
-            except Exception:
-                self.token = None
-        else:
-            resp.success()  # 登录接口未实现时不计入失败
-
-    @property
-    def headers(self):
-        return {"Authorization": f"Bearer {self.token}"} if self.token else {}
-
-    @task(5)
-    def list_devices(self):
-        self.client.get("/api/devices?page=1&page_size=20", headers=self.headers,
-                        name="/api/devices")
-
-    @task(3)
-    def device_detail(self):
-        self.client.get("/api/devices/1", headers=self.headers, name="/api/devices/{id}")
-
-    @task(2)
-    def report_data(self):
-        self.client.post("/api/data/report",
-                         json={"device_id": 1, "metric": "flow", "value": 12.5},
-                         headers=self.headers, name="/api/data/report")
-
-    @task(2)
-    def billing_report(self):
-        self.client.get("/api/billing/report?month=2026-07", headers=self.headers,
-                        name="/api/billing/report")
-
-    @task(1)
-    def health(self):
-        self.client.get("/health", name="/health")

tests/performance/websocket_stress.py

@@ -1,83 +0,0 @@
-"""WebSocket 长连接并发压测（Issue #94）
-
-支持 100 - 5000 并发连接梯度，统计建连成功率、消息往返延迟（P50/P95/P99）。
-
-运行：
-    python tests/performance/websocket_stress.py --url ws://127.0.0.1:8000/ws \
-        --concurrency 500 --duration 60
-"""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import statistics
-import time
-
-try:
-    import websockets
-except ImportError:  # pragma: no cover
-    websockets = None
-
-
-class Stats:
-    def __init__(self) -> None:
-        self.connected = 0
-        self.failed = 0
-        self.latencies: list[float] = []
-
-    def summary(self) -> str:
-        if not self.latencies:
-            lat = "无消息样本"
-        else:
-            ls = sorted(self.latencies)
-            p = lambda q: ls[min(len(ls) - 1, int(q * len(ls)))]
-            lat = (f"P50={p(0.5)*1000:.1f}ms P95={p(0.95)*1000:.1f}ms "
-                   f"P99={p(0.99)*1000:.1f}ms avg={statistics.mean(ls)*1000:.1f}ms")
-        return (f"建连成功={self.connected} 失败={self.failed} | 往返延迟 {lat}")
-
-
-async def worker(url: str, duration: float, stats: Stats) -> None:
-    try:
-        async with websockets.connect(url, open_timeout=10) as ws:
-            stats.connected += 1
-            end = time.time() + duration
-            while time.time() < end:
-                t0 = time.perf_counter()
-                await ws.send('{"type":"ping"}')
-                try:
-                    await asyncio.wait_for(ws.recv(), timeout=5)
-                    stats.latencies.append(time.perf_counter() - t0)
-                except asyncio.TimeoutError:
-                    pass
-                await asyncio.sleep(1)
-    except Exception:
-        stats.failed += 1
-
-
-async def main_async(url: str, concurrency: int, duration: float, ramp: float) -> None:
-    stats = Stats()
-    tasks = []
-    for i in range(concurrency):
-        tasks.append(asyncio.create_task(worker(url, duration, stats)))
-        await asyncio.sleep(ramp)  # 平滑加压，避免瞬时 SYN 风暴
-    await asyncio.gather(*tasks)
-    print(stats.summary())
-
-
-def main() -> None:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--url", default="ws://127.0.0.1:8000/ws")
-    ap.add_argument("--concurrency", type=int, default=100, help="并发连接数(100-5000)")
-    ap.add_argument("--duration", type=float, default=60, help="每连接压测时长(秒)")
-    ap.add_argument("--ramp", type=float, default=0.01, help="建连间隔(秒)")
-    args = ap.parse_args()
-    if websockets is None:
-        raise SystemExit("请先 pip install websockets")
-    if not 1 <= args.concurrency <= 5000:
-        raise SystemExit("concurrency 需在 1-5000 之间")
-    asyncio.run(main_async(args.url, args.concurrency, args.duration, args.ramp))
-
-
-if __name__ == "__main__":
-    main()