feat: 添加安全模块 - RBAC/JWT/加密/审计 (#95)

- src/security/auth.py: RBAC 角色权限 (ADMIN/OPERATOR/VIEWER/DEVICE) + JWT 认证
- src/security/middleware.py: 安全中间件 (JWT认证/CORS/限流/CSRF/安全Headers)
- src/security/encryption.py: AES-256-GCM 数据加密 + 响应脱敏
- src/security/input_validator.py: SQL注入/XSS防护 + 文件上传验证
- src/security/audit.py: 操作审计日志 (事件记录/告警/查询/双写存储)
- src/security/config.py: 安全配置 (从环境变量读取)
- src/api/rest_api.py: 认证端点 + 审计查询 + 权限示例
- tests/test_security.py: 43 个单元测试全部通过
- docs/SECURITY.md: 安全架构文档
- requirements.txt: 安全依赖 (PyJWT/passlib/bcrypt/cryptography)

docs/SECURITY.md

+# 安全架构文档
+
+## 概述
+
+水务管理系统安全模块提供完整的身份认证、权限控制、数据加密和安全审计能力，保障系统在生产环境中的安全性。
+
+## 安全架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     客户端请求                            │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────┐
+│  SecurityMiddleware（安全中间件层）                        │
+│  ├─ Rate Limiting (限流: 60 req/min/IP)                  │
+│  ├─ Security Headers (HSTS, CSP, X-Frame-Options...)    │
+│  ├─ JWT Authentication (Token 验证)                      │
+│  ├─ CORS Protection (跨域限制)                           │
+│  └─ Audit Logging (审计记录)                              │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────┐
+│  路由层 + 权限装饰器                                      │
+│  ├─ @require_role(ADMIN, OPERATOR)                       │
+│  ├─ @require_permission("data:read")                     │
+│  └─ 输入验证 (SQL注入/XSS 防护)                           │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────┐
+│  业务逻辑层                                              │
+│  ├─ 数据加密 (AES-256-GCM)                               │
+│  ├─ 响应脱敏 (手机号/身份证/邮箱)                          │
+│  └─ 审计事件触发                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+## JWT 认证流程
+
+### 登录流程
+
+```
+Client                    Server
+  │                         │
+  │  POST /auth/login       │
+  │  {username, password}   │
+  │ ───────────────────────>│
+  │                         │  1. 验证用户名/密码
+  │                         │  2. 检查账户状态
+  │                         │  3. 生成 JWT tokens
+  │  {access_token,         │
+  │   refresh_token}        │
+  │ <───────────────────────│
+  │                         │
+```
+
+### Token 使用
+
+```
+Client                    Server
+  │                         │
+  │  GET /api/resource      │
+  │  Authorization: Bearer  │
+  │  <access_token>         │
+  │ ───────────────────────>│
+  │                         │  1. 提取 Bearer token
+  │                         │  2. 验证签名和有效期
+  │                         │  3. 提取用户信息和角色
+  │                         │  4. 检查权限
+  │  200 OK                 │
+  │ <───────────────────────│
+```
+
+### Token 刷新
+
+```
+Client                    Server
+  │                         │
+  │  POST /auth/refresh     │
+  │  {refresh_token}        │
+  │ ───────────────────────>│
+  │                         │  1. 验证 refresh_token
+  │                         │  2. 生成新 access_token
+  │  {access_token}         │
+  │ <───────────────────────│
+```
+
+### Token 说明
+
+| 类型 | 有效期 | 用途 |
+|------|--------|------|
+| Access Token | 30 分钟 | API 请求认证 |
+| Refresh Token | 7 天 | 刷新 Access Token |
+
+## RBAC 角色说明
+
+### 角色定义
+
+| 角色 | 说明 | 典型用户 |
+|------|------|----------|
+| ADMIN | 系统管理员，拥有所有权限 | IT 管理员 |
+| OPERATOR | 操作员，可读写业务数据 | 值班操作员 |
+| VIEWER | 只读用户，只能查看数据 | 管理层查看 |
+| DEVICE | IoT 设备专用 | 传感器/网关 |
+
+### 权限矩阵
+
+| 权限 | ADMIN | OPERATOR | VIEWER | DEVICE |
+|------|-------|----------|--------|--------|
+| system:manage | ✅ | ❌ | ❌ | ❌ |
+| users:manage | ✅ | ❌ | ❌ | ❌ |
+| roles:manage | ✅ | ❌ | ❌ | ❌ |
+| devices:manage | ✅ | ✅ | ❌ | ❌ |
+| data:read | ✅ | ✅ | ✅ | ✅ |
+| data:write | ✅ | ✅ | ❌ | ✅ |
+| data:delete | ✅ | ❌ | ❌ | ❌ |
+| audit:read | ✅ | ❌ | ❌ | ❌ |
+| config:manage | ✅ | ❌ | ❌ | ❌ |
+| reports:read | ✅ | ✅ | ✅ | ❌ |
+| reports:export | ✅ | ✅ | ❌ | ❌ |
+
+## 加密方案
+
+### AES-256-GCM
+
+系统使用 AES-256-GCM 模式加密敏感数据：
+
+- **密钥**: 从环境变量 `AES_ENCRYPTION_KEY` 读取
+- **IV**: 每次加密自动生成 96-bit 随机 nonce
+- **认证**: GCM 模式自带完整性验证
+- **编码**: 密文以 Base64 格式存储
+
+### 适用场景
+
+- 数据库敏感字段加密（手机号、身份证号等）
+- 配置文件加密存储
+- API 响应数据脱敏前的安全存储
+
+### 密钥管理
+
+```bash
+# 生成 32 字节密钥
+python -c "import secrets; print(secrets.token_hex(16))"
+
+# 设置环境变量
+export AES_ENCRYPTION_KEY="your-hex-key-here"
+export JWT_SECRET_KEY="your-jwt-secret-here"
+```
+
+## API 安全最佳实践
+
+### 1. 始终使用 HTTPS
+
+生产环境必须使用 HTTPS，禁止明文 HTTP 传输敏感数据。
+
+### 2. 请求限流
+
+系统默认限制每 IP 每分钟 60 次请求，可通过环境变量调整：
+
+```bash
+export RATE_LIMIT_PER_MINUTE=100
+```
+
+### 3. 输入验证
+
+所有用户输入都经过以下检查：
+
+- **SQL 注入防护**: 检测常见注入模式，使用参数化查询
+- **XSS 防护**: HTML 转义所有输出内容
+- **文件上传验证**: 类型、大小、内容三重检查
+
+### 4. 安全 Headers
+
+系统自动添加以下安全响应头：
+
+| Header | 值 | 说明 |
+|--------|------|------|
+| X-Content-Type-Options | nosniff | 禁止 MIME 嗅探 |
+| X-Frame-Options | DENY | 禁止嵌套框架 |
+| X-XSS-Protection | 1; mode=block | XSS 过滤器 |
+| Strict-Transport-Security | max-age=31536000 | 强制 HTTPS |
+| Content-Security-Policy | default-src 'self' | CSP 策略 |
+| Referrer-Policy | strict-origin-when-cross-origin | 引用来源策略 |
+
+### 5. 响应脱敏
+
+敏感数据在返回客户端前自动脱敏：
+
+```python
+from src.security import mask_phone, mask_id_card, mask_email
+
+mask_phone("13812345678")     # → "138****5678"
+mask_id_card("110101199001011234")  # → "1101**********1234"
+mask_email("test@example.com")    # → "t***@example.com"
+```
+
+## 安全审计
+
+### 审计事件类型
+
+| 事件 | 说明 | 严重程度 |
+|------|------|----------|
+| login | 用户登录成功 | INFO |
+| login_failed | 登录失败 | WARNING |
+| logout | 用户登出 | INFO |
+| user_create | 创建用户 | INFO |
+| role_change | 角色变更 | WARNING |
+| permission_change | 权限变更 | WARNING |
+| data_delete | 数据删除 | WARNING |
+| config_change | 配置变更 | CRITICAL |
+| data_export | 数据导出 | INFO |
+
+### 告警规则
+
+| 规则 | 触发条件 | 严重程度 |
+|------|----------|----------|
+| 多次登录失败 | 15 分钟内 5 次失败 | CRITICAL |
+| 频繁权限变更 | 1 小时内 10 次变更 | WARNING |
+| 批量数据删除 | 10 分钟内 20 次删除 | CRITICAL |
+
+### 审计日志查询
+
+```bash
+# 查询最近审计日志
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:8000/audit/logs
+
+# 按用户过滤
+curl -H "Authorization: Bearer <token>" \
+  "http://localhost:8000/audit/logs?user_id=admin"
+
+# 查看安全告警
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:8000/audit/alerts
+```
+
+## 安全事件响应流程
+
+### 1. 检测阶段
+
+- 审计日志自动记录所有操作
+- 高危操作自动触发告警
+- 异常登录行为（多次失败、异地登录）标红
+
+### 2. 响应阶段
+
+1. **确认事件**: 查看审计日志确认事件详情
+2. **隔离影响**: 必要时禁用相关账户
+3. **修复漏洞**: 定位并修复安全问题
+4. **通知相关方**: 如涉及数据泄露，通知受影响用户
+
+### 3. 复盘阶段
+
+1. 记录事件处理过程
+2. 分析根本原因
+3. 更新安全策略
+4. 优化告警规则
+
+## 环境变量配置
+
+```bash
+# JWT 配置
+JWT_SECRET_KEY=your-secret-key-here
+JWT_ALGORITHM=HS256
+JWT_ACCESS_TOKEN_EXPIRE=30
+JWT_REFRESH_TOKEN_EXPIRE=7
+
+# 加密配置
+AES_ENCRYPTION_KEY=your-32-char-hex-key
+
+# 限流配置
+RATE_LIMIT_PER_MINUTE=60
+MAX_LOGIN_ATTEMPTS=5
+LOCKOUT_DURATION_MINUTES=15
+
+# CORS 配置
+CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://admin.yourdomain.com
+
+# 审计配置
+AUDIT_ENABLED=true
+AUDIT_LOG_FILE=logs/audit.log
+AUDIT_DB_STORAGE=true
+AUDIT_ALERT_FAILED_LOGINS=5
+
+# 密码策略
+PASSWORD_MIN_LENGTH=8
+PASSWORD_REQUIRE_UPPERCASE=true
+PASSWORD_REQUIRE_LOWERCASE=true
+PASSWORD_REQUIRE_DIGIT=true
+PASSWORD_REQUIRE_SPECIAL=false
+```
+
+## 依赖版本
+
+| 包 | 版本 | 用途 |
+|-----|------|------|
+| PyJWT | ≥2.8.0 | JWT token 生成与验证 |
+| passlib | ≥1.7.4 | 密码哈希（bcrypt） |
+| bcrypt | ≥4.0.0 | 密码哈希算法 |
+| cryptography | ≥41.0.0 | AES-256-GCM 加密 |
+| FastAPI | ≥0.100.0 | Web 框架 |
+| starlette | ≥0.27.0 | ASGI 中间件基础 |
+
+---
+
+*最后更新: 2026-06-16*

requirements.txt

+# 核心依赖
+fastapi>=0.100.0
+uvicorn[standard]>=0.23.0
+python-multipart>=0.0.6
+
+# 安全模块依赖
+PyJWT>=2.8.0
+passlib[bcrypt]>=1.7.4
+bcrypt>=4.0.0
+cryptography>=41.0.0
+
+# 可选依赖
+slowapi>=0.1.9
+starlette>=0.27.0
+httpx>=0.24.0
+
+# 数据处理
+pandas>=2.0.0
+
+# WebSocket
+websockets>=11.0

src/__init__.py

+"""
+src 模块
+"""

src/api/__init__.py

+"""
+API 模块
+"""

src/api/rest_api.py

+"""
+REST API 路由（安全模块集成）
+包含认证端点、审计日志查询端点、权限示例
+"""
+import sys
+import os
+
+# 将项目根目录加入 Python 路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", ".."))
+
+try:
+    from fastapi import FastAPI, HTTPException, Depends, Header, Request
+    from fastapi.responses import JSONResponse
+except ImportError:
+    FastAPI = None
+
+from src.security.auth import (
+    Role, hash_password, verify_password,
+    create_access_token, create_refresh_token,
+    verify_access_token, verify_refresh_token,
+    extract_token_from_header, validate_password_strength,
+    require_role,
+)
+from src.security.audit import AuditAction, AuditResult, AuditSeverity, get_audit_logger
+from src.security.middleware import SecurityMiddleware, cors_middleware, get_rate_limiter
+from src.security.encryption import mask_phone, mask_response
+from src.security.input_validator import sanitize_string, detect_sql_injection, detect_xss
+from src.security.config import security_config
+
+
+# 内存用户存储（演示用，生产环境应使用数据库）
+_users_db = {
+    "admin": {
+        "user_id": "admin",
+        "username": "admin",
+        "password_hash": hash_password("Admin@123") if True else "",
+        "roles": [Role.ADMIN.value],
+        "phone": "13800138000",
+    },
+    "operator": {
+        "user_id": "operator01",
+        "username": "operator",
+        "password_hash": hash_password("Operator@123") if True else "",
+        "roles": [Role.OPERATOR.value],
+        "phone": "13900139000",
+    },
+}
+
+
+def create_app() -> "FastAPI":
+    """创建并配置 FastAPI 应用"""
+    if FastAPI is None:
+        raise RuntimeError("FastAPI 未安装，请运行: pip install fastapi uvicorn")
+
+    app = FastAPI(
+        title="水务管理系统 API",
+        version="2.0.0",
+        description="集成安全模块的 REST API",
+    )
+
+    # 注册安全中间件
+    app.add_middleware(SecurityMiddleware, excluded_paths=[
+        "/auth/login", "/auth/refresh", "/health",
+        "/docs", "/openapi.json", "/redoc",
+    ])
+
+    # 注册 CORS 中间件
+    cors_middleware(app)
+
+    # ============ 认证端点 ============
+
+    @app.post("/auth/login")
+    async def login(request: Request):
+        """用户登录"""
+        try:
+            body = await request.json()
+        except Exception:
+            raise HTTPException(status_code=400, detail="请求体格式错误")
+
+        username = body.get("username", "")
+        password = body.get("password", "")
+
+        # 输入验证
+        username = sanitize_string(username, max_length=50)
+        if not username or not password:
+            raise HTTPException(status_code=400, detail="用户名和密码不能为空")
+
+        # SQL 注入检测
+        is_injection, msg = detect_sql_injection(username)
+        if is_injection:
+            raise HTTPException(status_code=400, detail="输入包含非法字符")
+
+        user = _users_db.get(username)
+        audit_logger = get_audit_logger()
+        client_ip = request.client.host if request.client else ""
+
+        if not user or not verify_password(password, user["password_hash"]):
+            audit_logger.log_action(
+                user_id=username,
+                action=AuditAction.LOGIN_FAILED.value,
+                ip_address=client_ip,
+                result=AuditResult.FAILURE,
+                severity=AuditSeverity.WARNING,
+                details={"reason": "用户名或密码错误"},
+            )
+            raise HTTPException(status_code=401, detail="用户名或密码错误")
+
+        # 生成 token
+        roles = [Role(r) for r in user["roles"]]
+        access_token = create_access_token(user["user_id"], roles)
+        refresh_token = create_refresh_token(user["user_id"])
+
+        audit_logger.log_action(
+            user_id=user["user_id"],
+            action=AuditAction.LOGIN.value,
+            ip_address=client_ip,
+            result=AuditResult.SUCCESS,
+        )
+
+        return {
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "token_type": "bearer",
+            "user": {
+                "user_id": user["user_id"],
+                "username": user["username"],
+                "roles": user["roles"],
+            },
+        }
+
+    @app.post("/auth/refresh")
+    async def refresh_token(request: Request):
+        """刷新 access token"""
+        try:
+            body = await request.json()
+        except Exception:
+            raise HTTPException(status_code=400, detail="请求体格式错误")
+
+        refresh_token = body.get("refresh_token", "")
+        if not refresh_token:
+            raise HTTPException(status_code=400, detail="refresh_token 不能为空")
+
+        payload = verify_refresh_token(refresh_token)
+        if payload is None:
+            raise HTTPException(status_code=401, detail="refresh_token 无效或已过期")
+
+        user_id = payload.get("sub", "")
+        user = next((u for u in _users_db.values() if u["user_id"] == user_id), None)
+        if not user:
+            raise HTTPException(status_code=401, detail="用户不存在")
+
+        roles = [Role(r) for r in user["roles"]]
+        new_access_token = create_access_token(user_id, roles)
+
+        return {
+            "access_token": new_access_token,
+            "token_type": "bearer",
+        }
+
+    @app.post("/auth/logout")
+    async def logout(request: Request):
+        """用户登出"""
+        audit_logger = get_audit_logger()
+        user = getattr(request.scope, "user", {})
+        user_id = user.get("sub", "unknown") if isinstance(user, dict) else "unknown"
+        client_ip = request.client.host if request.client else ""
+
+        audit_logger.log_action(
+            user_id=user_id,
+            action=AuditAction.LOGOUT.value,
+            ip_address=client_ip,
+        )
+
+        return {"message": "已登出"}
+
+    # ============ 审计日志端点 ============
+
+    @app.get("/audit/logs")
+    async def get_audit_logs(
+        user_id: str = None,
+        action: str = None,
+        result: str = None,
+        limit: int = 100,
+        offset: int = 0,
+        current_user: dict = None,
+    ):
+        """查询审计日志（仅管理员）"""
+        # 权限检查
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+
+        user_roles = current_user.get("roles", [])
+        if Role.ADMIN.value not in user_roles:
+            raise HTTPException(status_code=403, detail="仅管理员可查询审计日志")
+
+        audit_logger = get_audit_logger()
+        logs = audit_logger.query(
+            user_id=user_id,
+            action=action,
+            result=result,
+            limit=limit,
+            offset=offset,
+        )
+        return {"logs": logs, "total": len(logs)}
+
+    @app.get("/audit/stats")
+    async def get_audit_stats(hours: int = 24, current_user: dict = None):
+        """获取审计统计（仅管理员）"""
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+
+        user_roles = current_user.get("roles", [])
+        if Role.ADMIN.value not in user_roles:
+            raise HTTPException(status_code=403, detail="仅管理员可查看统计")
+
+        audit_logger = get_audit_logger()
+        stats = audit_logger.get_stats(hours)
+        return stats
+
+    @app.get("/audit/alerts")
+    async def get_audit_alerts(limit: int = 50, current_user: dict = None):
+        """获取安全告警（仅管理员）"""
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+
+        user_roles = current_user.get("roles", [])
+        if Role.ADMIN.value not in user_roles:
+            raise HTTPException(status_code=403, detail="仅管理员可查看告警")
+
+        audit_logger = get_audit_logger()
+        alerts = audit_logger.get_alerts(limit)
+        return {"alerts": alerts}
+
+    # ============ 业务路由示例（带权限控制） ============
+
+    @app.get("/health")
+    async def health_check():
+        """健康检查（无需认证）"""
+        return {"status": "ok", "version": "2.0.0"}
+
+    @app.get("/api/devices")
+    async def list_devices(current_user: dict = None):
+        """设备列表（需要 data:read 权限）"""
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+        return {"devices": [], "message": "设备列表"}
+
+    @app.post("/api/devices")
+    async def create_device(request: Request, current_user: dict = None):
+        """创建设备（需要 OPERATOR 或 ADMIN 角色）"""
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+
+        user_roles = current_user.get("roles", [])
+        if Role.ADMIN.value not in user_roles and Role.OPERATOR.value not in user_roles:
+            raise HTTPException(status_code=403, detail="权限不足")
+
+        return {"message": "设备创建成功"}
+
+    @app.delete("/api/devices/{device_id}")
+    async def delete_device(device_id: str, current_user: dict = None):
+        """删除设备（仅管理员）"""
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+
+        user_roles = current_user.get("roles", [])
+        if Role.ADMIN.value not in user_roles:
+            raise HTTPException(status_code=403, detail="仅管理员可删除设备")
+
+        audit_logger = get_audit_logger()
+        audit_logger.log_action(
+            user_id=current_user.get("sub", ""),
+            action=AuditAction.DATA_DELETE.value,
+            resource=f"device:{device_id}",
+            severity=AuditSeverity.WARNING,
+        )
+
+        return {"message": f"设备 {device_id} 已删除"}
+
+    @app.get("/api/users/me")
+    async def get_current_user_info(current_user: dict = None):
+        """获取当前用户信息"""
+        if not current_user:
+            raise HTTPException(status_code=401, detail="未认证")
+
+        user_id = current_user.get("sub", "")
+        user = next((u for u in _users_db.values() if u["user_id"] == user_id), None)
+        if not user:
+            raise HTTPException(status_code=404, detail="用户不存在")
+
+        # 脱敏手机号
+        return {
+            "user_id": user["user_id"],
+            "username": user["username"],
+            "roles": user["roles"],
+            "phone": mask_phone(user.get("phone", "")),
+        }
+
+    return app
+
+
+# 导出 app 实例（供 uvicorn 使用）
+try:
+    app = create_app()
+except RuntimeError:
+    app = None

src/security/__init__.py

+"""
+安全模块 (src/security)
+统一导出所有安全组件
+
+包含:
+- auth: RBAC 角色权限 + JWT 认证
+- middleware: 安全中间件（JWT 认证、CORS、限流、CSRF、安全 Headers）
+- encryption: 数据加密（AES-256-GCM）+ 响应脱敏
+- input_validator: 输入验证 + 注入防护
+- audit: 操作审计日志
+- config: 安全配置
+"""
+
+# 认证与权限
+from .auth import (
+    Role,
+    ROLE_PERMISSIONS,
+    hash_password,
+    verify_password,
+    create_access_token,
+    create_refresh_token,
+    decode_token,
+    verify_access_token,
+    verify_refresh_token,
+    get_user_roles,
+    check_permission,
+    require_role,
+    require_permission,
+    extract_token_from_header,
+    validate_password_strength,
+)
+
+# 中间件
+from .middleware import (
+    SecurityMiddleware,
+    RateLimiter,
+    get_rate_limiter,
+    generate_csrf_token,
+    validate_csrf_token,
+    get_client_ip,
+    cors_middleware,
+)
+
+# 加密
+from .encryption import (
+    FieldEncryptor,
+    get_encryptor,
+    encrypt_field,
+    decrypt_field,
+    encrypt_dict,
+    decrypt_dict,
+    encrypt_config_file,
+    decrypt_config_file,
+    mask_phone,
+    mask_id_card,
+    mask_email,
+    mask_bank_card,
+    mask_name,
+    mask_ip,
+    mask_response,
+)
+
+# 输入验证
+from .input_validator import (
+    detect_sql_injection,
+    sanitize_sql_value,
+    detect_xss,
+    escape_html,
+    sanitize_html,
+    FileUploadValidator,
+    file_validator,
+    validate_file_upload,
+    sanitize_string,
+    sanitize_number,
+    validate_email_format,
+    validate_phone_format,
+    validate_id_card_format,
+)
+
+# 审计
+from .audit import (
+    AuditAction,
+    AuditResult,
+    AuditSeverity,
+    AuditEvent,
+    AuditLogger,
+    AuditStorage,
+    AuditAlertManager,
+    get_audit_logger,
+)
+
+# 配置
+from .config import (
+    security_config,
+    SecurityConfig,
+    JWTConfig,
+    EncryptionConfig,
+    RateLimitConfig,
+    CORSConfig,
+    PasswordPolicyConfig,
+    AuditConfig,
+)
+
+__all__ = [
+    # Auth
+    "Role", "ROLE_PERMISSIONS",
+    "hash_password", "verify_password",
+    "create_access_token", "create_refresh_token",
+    "decode_token", "verify_access_token", "verify_refresh_token",
+    "get_user_roles", "check_permission",
+    "require_role", "require_permission",
+    "extract_token_from_header", "validate_password_strength",
+    # Middleware
+    "SecurityMiddleware", "RateLimiter", "get_rate_limiter",
+    "generate_csrf_token", "validate_csrf_token",
+    "get_client_ip", "cors_middleware",
+    # Encryption
+    "FieldEncryptor", "get_encryptor",
+    "encrypt_field", "decrypt_field",
+    "encrypt_dict", "decrypt_dict",
+    "encrypt_config_file", "decrypt_config_file",
+    "mask_phone", "mask_id_card", "mask_email",
+    "mask_bank_card", "mask_name", "mask_ip", "mask_response",
+    # Input Validator
+    "detect_sql_injection", "sanitize_sql_value",
+    "detect_xss", "escape_html", "sanitize_html",
+    "FileUploadValidator", "file_validator", "validate_file_upload",
+    "sanitize_string", "sanitize_number",
+    "validate_email_format", "validate_phone_format", "validate_id_card_format",
+    # Audit
+    "AuditAction", "AuditResult", "AuditSeverity", "AuditEvent",
+    "AuditLogger", "AuditStorage", "AuditAlertManager", "get_audit_logger",
+    # Config
+    "security_config", "SecurityConfig",
+    "JWTConfig", "EncryptionConfig", "RateLimitConfig",
+    "CORSConfig", "PasswordPolicyConfig", "AuditConfig",
+]

src/security/audit.py

+"""
+操作审计日志模块
+审计事件模型、记录器、查询 API、高危告警、双写存储
+"""
+import os
+import json
+import time
+import logging
+from enum import Enum
+from typing import Optional, List, Dict, Any
+from datetime import datetime, timezone, timedelta
+from dataclasses import dataclass, field, asdict
+from collections import defaultdict
+
+from .config import security_config
+
+logger = logging.getLogger(__name__)
+
+
+class AuditAction(str, Enum):
+    """审计操作类型"""
+    LOGIN = "login"
+    LOGOUT = "logout"
+    LOGIN_FAILED = "login_failed"
+    USER_CREATE = "user_create"
+    USER_UPDATE = "user_update"
+    USER_DELETE = "user_delete"
+    ROLE_CHANGE = "role_change"
+    PERMISSION_CHANGE = "permission_change"
+    PASSWORD_CHANGE = "password_change"
+    PASSWORD_RESET = "password_reset"
+    DATA_READ = "data_read"
+    DATA_WRITE = "data_write"
+    DATA_DELETE = "data_delete"
+    DATA_EXPORT = "data_export"
+    CONFIG_CHANGE = "config_change"
+    SYSTEM_RESTART = "system_restart"
+    DEVICE_REGISTER = "device_register"
+    DEVICE_DELETE = "device_delete"
+    API_ACCESS = "api_access"
+    FILE_UPLOAD = "file_upload"
+    FILE_DOWNLOAD = "file_download"
+
+
+class AuditResult(str, Enum):
+    """审计结果"""
+    SUCCESS = "success"
+    FAILURE = "failure"
+    DENIED = "denied"
+    ERROR = "error"
+
+
+class AuditSeverity(str, Enum):
+    """审计事件严重程度"""
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+@dataclass
+class AuditEvent:
+    """审计事件模型"""
+    timestamp: datetime
+    user_id: str
+    action: str
+    resource: str = ""
+    ip_address: str = ""
+    user_agent: str = ""
+    result: AuditResult = AuditResult.SUCCESS
+    severity: AuditSeverity = AuditSeverity.INFO
+    details: Dict[str, Any] = field(default_factory=dict)
+    event_id: str = ""
+
+    def __post_init__(self):
+        if not self.event_id:
+            import secrets
+            self.event_id = secrets.token_hex(16)
+        if isinstance(self.result, str):
+            self.result = AuditResult(self.result)
+        if isinstance(self.severity, str):
+            self.severity = AuditSeverity(self.severity)
+
+    def to_dict(self) -> dict:
+        """转换为字典"""
+        d = asdict(self)
+        d["timestamp"] = self.timestamp.isoformat()
+        d["result"] = self.result.value
+        d["severity"] = self.severity.value
+        return d
+
+    def to_json(self) -> str:
+        """转换为 JSON 字符串"""
+        return json.dumps(self.to_dict(), ensure_ascii=False)
+
+
+class AlertRule:
+    """告警规则"""
+
+    def __init__(
+        self,
+        name: str,
+        action: str,
+        max_count: int,
+        window_seconds: int,
+        severity: AuditSeverity = AuditSeverity.WARNING,
+    ):
+        self.name = name
+        self.action = action
+        self.max_count = max_count
+        self.window_seconds = window_seconds
+        self.severity = severity
+
+
+class AuditAlertManager:
+    """审计告警管理器"""
+
+    def __init__(self):
+        self._event_counts: Dict[str, List[float]] = defaultdict(list)
+        self.rules: List[AlertRule] = [
+            AlertRule(
+                name="多次登录失败",
+                action=AuditAction.LOGIN_FAILED.value,
+                max_count=security_config.audit.alert_on_failed_logins,
+                window_seconds=900,  # 15 分钟
+                severity=AuditSeverity.CRITICAL,
+            ),
+            AlertRule(
+                name="频繁权限变更",
+                action=AuditAction.PERMISSION_CHANGE.value,
+                max_count=10,
+                window_seconds=3600,  # 1 小时
+                severity=AuditSeverity.WARNING,
+            ),
+            AlertRule(
+                name="批量数据删除",
+                action=AuditAction.DATA_DELETE.value,
+                max_count=20,
+                window_seconds=600,  # 10 分钟
+                severity=AuditSeverity.CRITICAL,
+            ),
+        ]
+        self._alerts: List[Dict[str, Any]] = []
+
+    def check_alert(self, event: AuditEvent) -> Optional[Dict[str, Any]]:
+        """检查事件是否触发告警"""
+        now = time.time()
+
+        for rule in self.rules:
+            if event.action == rule.action:
+                key = f"{rule.name}:{event.user_id}"
+                cutoff = now - rule.window_seconds
+
+                # 清理过期记录
+                self._event_counts[key] = [
+                    t for t in self._event_counts[key] if t > cutoff
+                ]
+                self._event_counts[key].append(now)
+
+                if len(self._event_counts[key]) >= rule.max_count:
+                    alert = {
+                        "rule_name": rule.name,
+                        "user_id": event.user_id,
+                        "action": event.action,
+                        "count": len(self._event_counts[key]),
+                        "window_seconds": rule.window_seconds,
+                        "severity": rule.severity.value,
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
+                        "ip_address": event.ip_address,
+                    }
+                    self._alerts.append(alert)
+                    logger.warning(f"审计告警: {json.dumps(alert, ensure_ascii=False)}")
+                    return alert
+
+        return None
+
+    def get_alerts(self, limit: int = 50) -> List[Dict[str, Any]]:
+        """获取最近的告警列表"""
+        return self._alerts[-limit:]
+
+
+class AuditStorage:
+    """审计日志存储（文件 + 内存双写）"""
+
+    def __init__(self, log_file_path: Optional[str] = None):
+        self.log_file_path = log_file_path or security_config.audit.log_file_path
+        self._memory_store: List[Dict[str, Any]] = []
+        self._max_memory = 10000  # 内存中最多保留 10000 条
+
+        # 确保日志目录存在
+        log_dir = os.path.dirname(self.log_file_path)
+        if log_dir:
+            os.makedirs(log_dir, exist_ok=True)
+
+    def write(self, event: AuditEvent) -> None:
+        """写入审计日志"""
+        event_dict = event.to_dict()
+
+        # 写入内存
+        self._memory_store.append(event_dict)
+        if len(self._memory_store) > self._max_memory:
+            self._memory_store = self._memory_store[-self._max_memory:]
+
+        # 写入文件
+        try:
+            with open(self.log_file_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(event_dict, ensure_ascii=False) + "\n")
+        except Exception as e:
+            logger.error(f"审计日志写入文件失败: {e}")
+
+    def query(
+        self,
+        user_id: Optional[str] = None,
+        action: Optional[str] = None,
+        result: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        severity: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """
+        从内存存储查询审计日志
+
+        Args:
+            user_id: 按用户 ID 过滤
+            action: 按操作类型过滤
+            result: 按结果过滤
+            start_time: 开始时间
+            end_time: 结束时间
+            severity: 按严重程度过滤
+            limit: 返回条数限制
+            offset: 偏移量
+
+        Returns:
+            审计日志列表
+        """
+        results = self._memory_store.copy()
+
+        if user_id:
+            results = [r for r in results if r.get("user_id") == user_id]
+        if action:
+            results = [r for r in results if r.get("action") == action]
+        if result:
+            results = [r for r in results if r.get("result") == result]
+        if severity:
+            results = [r for r in results if r.get("severity") == severity]
+        if start_time:
+            start_iso = start_time.isoformat()
+            results = [r for r in results if r.get("timestamp", "") >= start_iso]
+        if end_time:
+            end_iso = end_time.isoformat()
+            results = [r for r in results if r.get("timestamp", "") <= end_iso]
+
+        # 按时间倒序
+        results.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+
+        return results[offset:offset + limit]
+
+    def get_stats(self, hours: int = 24) -> Dict[str, Any]:
+        """获取统计信息"""
+        cutoff = (datetime.now(timezone.utc) - timedelta(hours=hours)).isoformat()
+        recent = [r for r in self._memory_store if r.get("timestamp", "") >= cutoff]
+
+        action_counts = defaultdict(int)
+        result_counts = defaultdict(int)
+        user_counts = defaultdict(int)
+
+        for r in recent:
+            action_counts[r.get("action", "unknown")] += 1
+            result_counts[r.get("result", "unknown")] += 1
+            user_counts[r.get("user_id", "unknown")] += 1
+
+        return {
+            "period_hours": hours,
+            "total_events": len(recent),
+            "action_counts": dict(action_counts),
+            "result_counts": dict(result_counts),
+            "top_users": dict(sorted(user_counts.items(), key=lambda x: x[1], reverse=True)[:10]),
+        }
+
+
+class AuditLogger:
+    """审计日志记录器（主入口）"""
+
+    def __init__(self):
+        self.storage = AuditStorage()
+        self.alert_manager = AuditAlertManager()
+        self._enabled = security_config.audit.enabled
+
+    def log(self, event: AuditEvent) -> None:
+        """记录审计事件"""
+        if not self._enabled:
+            return
+
+        # 存储日志
+        self.storage.write(event)
+
+        # 检查告警
+        self.alert_manager.check_alert(event)
+
+    def log_action(
+        self,
+        user_id: str,
+        action: str,
+        resource: str = "",
+        ip_address: str = "",
+        user_agent: str = "",
+        result: AuditResult = AuditResult.SUCCESS,
+        severity: AuditSeverity = AuditSeverity.INFO,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """便捷方法：记录审计操作"""
+        event = AuditEvent(
+            timestamp=datetime.now(timezone.utc),
+            user_id=user_id,
+            action=action,
+            resource=resource,
+            ip_address=ip_address,
+            user_agent=user_agent,
+            result=result,
+            severity=severity,
+            details=details or {},
+        )
+        self.log(event)
+
+    def query(
+        self,
+        user_id: Optional[str] = None,
+        action: Optional[str] = None,
+        result: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        severity: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """查询审计日志"""
+        return self.storage.query(
+            user_id=user_id,
+            action=action,
+            result=result,
+            start_time=start_time,
+            end_time=end_time,
+            severity=severity,
+            limit=limit,
+            offset=offset,
+        )
+
+    def get_stats(self, hours: int = 24) -> Dict[str, Any]:
+        """获取审计统计"""
+        return self.storage.get_stats(hours)
+
+    def get_alerts(self, limit: int = 50) -> List[Dict[str, Any]]:
+        """获取告警列表"""
+        return self.alert_manager.get_alerts(limit)
+
+
+# 全局审计记录器实例
+_audit_logger: Optional[AuditLogger] = None
+
+
+def get_audit_logger() -> AuditLogger:
+    """获取全局审计记录器"""
+    global _audit_logger
+    if _audit_logger is None:
+        _audit_logger = AuditLogger()
+    return _audit_logger

src/security/auth.py

+"""
+RBAC 角色权限 + JWT 认证模块
+提供角色枚举、JWT token 生成/验证、权限装饰器、密码哈希
+"""
+import os
+import time
+import secrets
+from enum import Enum
+from typing import List, Optional, Set, Callable, Any
+from functools import wraps
+from datetime import datetime, timedelta, timezone
+
+try:
+    import jwt
+except ImportError:
+    jwt = None
+
+try:
+    from passlib.context import CryptContext
+except ImportError:
+    CryptContext = None
+
+from .config import security_config
+
+
+class Role(str, Enum):
+    """系统角色枚举"""
+    ADMIN = "admin"          # 管理员：完全权限
+    OPERATOR = "operator"    # 操作员：可读写，不能管理系统
+    VIEWER = "viewer"        # 只读用户
+    DEVICE = "device"        # IoT 设备专用
+
+
+# 角色权限映射
+ROLE_PERMISSIONS = {
+    Role.ADMIN: {
+        "system:manage", "users:manage", "roles:manage",
+        "devices:manage", "data:read", "data:write", "data:delete",
+        "audit:read", "config:manage", "reports:read", "reports:export",
+    },
+    Role.OPERATOR: {
+        "devices:manage", "data:read", "data:write",
+        "reports:read", "reports:export",
+    },
+    Role.VIEWER: {
+        "data:read", "reports:read",
+    },
+    Role.DEVICE: {
+        "data:write", "data:read",
+    },
+}
+
+
+# 密码哈希上下文
+pwd_context = None
+if CryptContext:
+    pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(password: str) -> str:
+    """对密码进行哈希处理"""
+    if pwd_context is None:
+        raise RuntimeError("passlib 未安装，请运行: pip install passlib[bcrypt]")
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """验证明文密码与哈希密码"""
+    if pwd_context is None:
+        raise RuntimeError("passlib 未安装，请运行: pip install passlib[bcrypt]")
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def create_access_token(
+    subject: str,
+    roles: List[Role],
+    extra_claims: Optional[dict] = None,
+) -> str:
+    """
+    生成 JWT access token
+
+    Args:
+        subject: 用户标识（user_id 或 username）
+        roles: 用户角色列表
+        extra_claims: 额外的 claims
+
+    Returns:
+        JWT token 字符串
+    """
+    if jwt is None:
+        raise RuntimeError("PyJWT 未安装，请运行: pip install PyJWT")
+
+    cfg = security_config.jwt
+    now = datetime.now(timezone.utc)
+    expire = now + timedelta(minutes=cfg.access_token_expire_minutes)
+
+    payload = {
+        "sub": subject,
+        "roles": [r.value for r in roles],
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+        "iss": cfg.issuer,
+        "type": "access",
+        "jti": secrets.token_hex(16),
+    }
+    if extra_claims:
+        payload.update(extra_claims)
+
+    return jwt.encode(payload, cfg.secret_key, algorithm=cfg.algorithm)
+
+
+def create_refresh_token(subject: str) -> str:
+    """生成 JWT refresh token"""
+    if jwt is None:
+        raise RuntimeError("PyJWT 未安装，请运行: pip install PyJWT")
+
+    cfg = security_config.jwt
+    now = datetime.now(timezone.utc)
+    expire = now + timedelta(days=cfg.refresh_token_expire_days)
+
+    payload = {
+        "sub": subject,
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+        "iss": cfg.issuer,
+        "type": "refresh",
+        "jti": secrets.token_hex(16),
+    }
+    return jwt.encode(payload, cfg.secret_key, algorithm=cfg.algorithm)
+
+
+def decode_token(token: str) -> dict:
+    """
+    解码并验证 JWT token
+
+    Returns:
+        解码后的 payload 字典
+
+    Raises:
+        jwt.ExpiredSignatureError: token 已过期
+        jwt.InvalidTokenError: token 无效
+    """
+    if jwt is None:
+        raise RuntimeError("PyJWT 未安装，请运行: pip install PyJWT")
+
+    cfg = security_config.jwt
+    return jwt.decode(
+        token,
+        cfg.secret_key,
+        algorithms=[cfg.algorithm],
+        issuer=cfg.issuer,
+    )
+
+
+def verify_access_token(token: str) -> Optional[dict]:
+    """验证 access token，返回 payload 或 None"""
+    try:
+        payload = decode_token(token)
+        if payload.get("type") != "access":
+            return None
+        return payload
+    except Exception:
+        return None
+
+
+def verify_refresh_token(token: str) -> Optional[dict]:
+    """验证 refresh token，返回 payload 或 None"""
+    try:
+        payload = decode_token(token)
+        if payload.get("type") != "refresh":
+            return None
+        return payload
+    except Exception:
+        return None
+
+
+def get_user_roles(payload: dict) -> List[Role]:
+    """从 token payload 提取角色列表"""
+    roles_str = payload.get("roles", [])
+    roles = []
+    for r in roles_str:
+        try:
+            roles.append(Role(r))
+        except ValueError:
+            continue
+    return roles
+
+
+def check_permission(roles: List[Role], permission: str) -> bool:
+    """检查角色列表是否拥有指定权限"""
+    user_permissions: Set[str] = set()
+    for role in roles:
+        user_permissions.update(ROLE_PERMISSIONS.get(role, set()))
+    return permission in user_permissions
+
+
+def require_role(*allowed_roles: Role):
+    """
+    FastAPI 路由权限装饰器
+
+    用法:
+        @app.get("/admin/users")
+        @require_role(Role.ADMIN)
+        async def get_users(current_user: dict = Depends(get_current_user)):
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # 从 kwargs 中提取 current_user
+            current_user = kwargs.get("current_user")
+            if current_user is None:
+                raise PermissionError("未提供用户信息")
+
+            user_roles = current_user.get("roles", [])
+            if not any(r in [role.value for role in allowed_roles] for r in user_roles):
+                raise PermissionError(
+                    f"权限不足，需要角色: {[r.value for r in allowed_roles]}"
+                )
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def require_permission(*permissions: str):
+    """
+    FastAPI 路由权限装饰器（基于权限名称）
+
+    用法:
+        @app.get("/data")
+        @require_permission("data:read")
+        async def get_data(current_user: dict = Depends(get_current_user)):
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            current_user = kwargs.get("current_user")
+            if current_user is None:
+                raise PermissionError("未提供用户信息")
+
+            user_roles = get_user_roles(current_user)
+            for perm in permissions:
+                if not check_permission(user_roles, perm):
+                    raise PermissionError(f"权限不足，缺少权限: {perm}")
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def extract_token_from_header(authorization: Optional[str]) -> Optional[str]:
+    """从 Authorization header 提取 Bearer token"""
+    if not authorization:
+        return None
+    parts = authorization.split()
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        return None
+    return parts[1]
+
+
+def validate_password_strength(password: str) -> tuple[bool, str]:
+    """
+    验证密码强度是否符合策略
+
+    Returns:
+        (是否通过, 错误信息)
+    """
+    policy = security_config.password_policy
+    errors = []
+
+    if len(password) < policy.min_length:
+        errors.append(f"密码长度至少 {policy.min_length} 位")
+    if policy.require_uppercase and not any(c.isupper() for c in password):
+        errors.append("密码需包含大写字母")
+    if policy.require_lowercase and not any(c.islower() for c in password):
+        errors.append("密码需包含小写字母")
+    if policy.require_digit and not any(c.isdigit() for c in password):
+        errors.append("密码需包含数字")
+    if policy.require_special:
+        special_chars = "!@#$%^&*()_+-=[]{}|;:,.<>?"
+        if not any(c in special_chars for c in password):
+            errors.append("密码需包含特殊字符")
+
+    if errors:
+        return False, "; ".join(errors)
+    return True, ""

src/security/config.py

+"""
+安全配置模块
+从环境变量读取所有安全相关配置，提供默认值
+"""
+import os
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass
+class JWTConfig:
+    """JWT 配置"""
+    secret_key: str = os.getenv("JWT_SECRET_KEY", "change-me-in-production-use-a-real-secret")
+    algorithm: str = os.getenv("JWT_ALGORITHM", "HS256")
+    access_token_expire_minutes: int = int(os.getenv("JWT_ACCESS_TOKEN_EXPIRE", "30"))
+    refresh_token_expire_days: int = int(os.getenv("JWT_REFRESH_TOKEN_EXPIRE", "7"))
+    issuer: str = os.getenv("JWT_ISSUER", "water-management-system")
+
+
+@dataclass
+class EncryptionConfig:
+    """加密配置"""
+    aes_key: str = os.getenv("AES_ENCRYPTION_KEY", "0123456789abcdef0123456789abcdef")
+    aes_iv: str = os.getenv("AES_IV", "")  # 留空则自动生成随机 IV
+
+
+@dataclass
+class RateLimitConfig:
+    """限流配置"""
+    max_requests_per_minute: int = int(os.getenv("RATE_LIMIT_PER_MINUTE", "60"))
+    max_login_attempts: int = int(os.getenv("MAX_LOGIN_ATTEMPTS", "5"))
+    lockout_duration_minutes: int = int(os.getenv("LOCKOUT_DURATION_MINUTES", "15"))
+
+
+@dataclass
+class CORSConfig:
+    """CORS 配置"""
+    allowed_origins: List[str] = field(default_factory=lambda: [
+        origin.strip()
+        for origin in os.getenv("CORS_ALLOWED_ORIGINS", "http://localhost:3000,http://localhost:8080").split(",")
+    ])
+    allowed_methods: List[str] = field(default_factory=lambda: ["GET", "POST", "PUT", "DELETE", "OPTIONS"])
+    allowed_headers: List[str] = field(default_factory=lambda: ["Authorization", "Content-Type", "X-CSRF-Token"])
+    allow_credentials: bool = True
+    max_age: int = 3600
+
+
+@dataclass
+class PasswordPolicyConfig:
+    """密码策略配置"""
+    min_length: int = int(os.getenv("PASSWORD_MIN_LENGTH", "8"))
+    require_uppercase: bool = os.getenv("PASSWORD_REQUIRE_UPPERCASE", "true").lower() == "true"
+    require_lowercase: bool = os.getenv("PASSWORD_REQUIRE_LOWERCASE", "true").lower() == "true"
+    require_digit: bool = os.getenv("PASSWORD_REQUIRE_DIGIT", "true").lower() == "true"
+    require_special: bool = os.getenv("PASSWORD_REQUIRE_SPECIAL", "false").lower() == "true"
+
+
+@dataclass
+class AuditConfig:
+    """审计日志配置"""
+    enabled: bool = os.getenv("AUDIT_ENABLED", "true").lower() == "true"
+    log_file_path: str = os.getenv("AUDIT_LOG_FILE", "logs/audit.log")
+    db_storage_enabled: bool = os.getenv("AUDIT_DB_STORAGE", "true").lower() == "true"
+    alert_on_failed_logins: int = int(os.getenv("AUDIT_ALERT_FAILED_LOGINS", "5"))
+
+
+@dataclass
+class SecurityConfig:
+    """统一安全配置"""
+    jwt: JWTConfig = field(default_factory=JWTConfig)
+    encryption: EncryptionConfig = field(default_factory=EncryptionConfig)
+    rate_limit: RateLimitConfig = field(default_factory=RateLimitConfig)
+    cors: CORSConfig = field(default_factory=CORSConfig)
+    password_policy: PasswordPolicyConfig = field(default_factory=PasswordPolicyConfig)
+    audit: AuditConfig = field(default_factory=AuditConfig)
+
+
+# 全局配置实例
+security_config = SecurityConfig()

src/security/encryption.py

+"""
+数据加密模块
+AES-256-GCM 加密、字段级加密、配置加密、响应脱敏
+"""
+import os
+import re
+import base64
+import json
+from typing import Optional, Any, Dict
+
+try:
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+except ImportError:
+    AESGCM = None
+
+from .config import security_config
+
+
+class FieldEncryptor:
+    """AES-256-GCM 字段加密器"""
+
+    def __init__(self, key: Optional[bytes] = None):
+        if AESGCM is None:
+            raise RuntimeError("cryptography 未安装，请运行: pip install cryptography")
+
+        if key is None:
+            key_hex = security_config.encryption.aes_key
+            if len(key_hex) == 32:
+                # 32 字节 hex = 16 bytes, 需要扩展到 32 bytes
+                key = self._derive_key(key_hex.encode(), b"water-mgmt-salt")
+            else:
+                key = key_hex.encode()[:32].ljust(32, b"\0")
+
+        self.aesgcm = AESGCM(key)
+
+    @staticmethod
+    def _derive_key(password: bytes, salt: bytes) -> bytes:
+        """使用 PBKDF2 派生 256 位密钥"""
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt,
+            iterations=100000,
+        )
+        return kdf.derive(password)
+
+    def encrypt(self, plaintext: str) -> str:
+        """
+        加密字符串
+
+        Args:
+            plaintext: 明文
+
+        Returns:
+            Base64 编码的密文（nonce + ciphertext）
+        """
+        nonce = os.urandom(12)  # 96-bit nonce for AES-GCM
+        ciphertext = self.aesgcm.encrypt(nonce, plaintext.encode("utf-8"), None)
+        # 拼接 nonce + ciphertext 并 base64 编码
+        combined = nonce + ciphertext
+        return base64.b64encode(combined).decode("ascii")
+
+    def decrypt(self, encrypted: str) -> str:
+        """
+        解密字符串
+
+        Args:
+            encrypted: Base64 编码的密文
+
+        Returns:
+            明文字符串
+        """
+        combined = base64.b64decode(encrypted)
+        nonce = combined[:12]
+        ciphertext = combined[12:]
+        plaintext = self.aesgcm.decrypt(nonce, ciphertext, None)
+        return plaintext.decode("utf-8")
+
+
+# 全局加密器实例（延迟初始化）
+_encryptor: Optional[FieldEncryptor] = None
+
+
+def get_encryptor() -> FieldEncryptor:
+    """获取全局加密器实例"""
+    global _encryptor
+    if _encryptor is None:
+        _encryptor = FieldEncryptor()
+    return _encryptor
+
+
+def encrypt_field(value: str) -> str:
+    """加密单个字段"""
+    if not value:
+        return value
+    return get_encryptor().encrypt(value)
+
+
+def decrypt_field(value: str) -> str:
+    """解密单个字段"""
+    if not value:
+        return value
+    try:
+        return get_encryptor().decrypt(value)
+    except Exception:
+        return value  # 解密失败返回原值（兼容未加密数据）
+
+
+def encrypt_dict(data: Dict[str, Any], fields: list) -> Dict[str, Any]:
+    """
+    加密字典中的指定字段
+
+    Args:
+        data: 原始字典
+        fields: 需要加密的字段列表
+
+    Returns:
+        加密后的字典
+    """
+    result = data.copy()
+    for field in fields:
+        if field in result and isinstance(result[field], str):
+            result[field] = encrypt_field(result[field])
+    return result
+
+
+def decrypt_dict(data: Dict[str, Any], fields: list) -> Dict[str, Any]:
+    """
+    解密字典中的指定字段
+
+    Args:
+        data: 加密后的字典
+        fields: 需要解密的字段列表
+
+    Returns:
+        解密后的字典
+    """
+    result = data.copy()
+    for field in fields:
+        if field in result and isinstance(result[field], str):
+            result[field] = decrypt_field(result[field])
+    return result
+
+
+def encrypt_config_file(input_path: str, output_path: str) -> None:
+    """
+    加密配置文件
+
+    Args:
+        input_path: 输入文件路径（JSON）
+        output_path: 输出文件路径（加密后）
+    """
+    with open(input_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    encrypted = get_encryptor().encrypt(content)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(encrypted)
+
+
+def decrypt_config_file(input_path: str, output_path: Optional[str] = None) -> dict:
+    """
+    解密配置文件
+
+    Args:
+        input_path: 加密文件路径
+        output_path: 输出文件路径（可选）
+
+    Returns:
+        解密后的 JSON 字典
+    """
+    with open(input_path, "r", encoding="utf-8") as f:
+        encrypted = f.read()
+
+    decrypted = get_encryptor().decrypt(encrypted)
+    data = json.loads(decrypted)
+
+    if output_path:
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    return data
+
+
+# ============ 响应脱敏 ============
+
+def mask_phone(phone: str) -> str:
+    """手机号脱敏: 13812345678 -> 138****5678"""
+    if not phone or len(phone) < 7:
+        return phone
+    return phone[:3] + "****" + phone[-4:]
+
+
+def mask_id_card(id_card: str) -> str:
+    """身份证号脱敏: 110101199001011234 -> 1101**********1234"""
+    if not id_card or len(id_card) < 8:
+        return id_card
+    return id_card[:4] + "*" * (len(id_card) - 8) + id_card[-4:]
+
+
+def mask_email(email: str) -> str:
+    """邮箱脱敏: test@example.com -> t***@example.com"""
+    if not email or "@" not in email:
+        return email
+    local, domain = email.split("@", 1)
+    if len(local) <= 1:
+        masked_local = local + "***"
+    else:
+        masked_local = local[0] + "***"
+    return f"{masked_local}@{domain}"
+
+
+def mask_bank_card(card: str) -> str:
+    """银行卡号脱敏: 6225880137073520 -> 6225********3520"""
+    if not card or len(card) < 8:
+        return card
+    return card[:4] + "*" * (len(card) - 8) + card[-4:]
+
+
+def mask_name(name: str) -> str:
+    """姓名脱敏: 张三 -> 张*, 欧阳修 -> 欧阳*"""
+    if not name:
+        return name
+    if len(name) <= 1:
+        return name
+    return name[:-1] + "*"
+
+
+def mask_ip(ip: str) -> str:
+    """IP 脱敏: 192.168.1.100 -> 192.168.*.*"""
+    if not ip:
+        return ip
+    parts = ip.split(".")
+    if len(parts) == 4:
+        return f"{parts[0]}.{parts[1]}.*.*"
+    return ip
+
+
+# 脱敏函数映射
+MASK_FUNCTIONS = {
+    "phone": mask_phone,
+    "id_card": mask_id_card,
+    "email": mask_email,
+    "bank_card": mask_bank_card,
+    "name": mask_name,
+    "ip": mask_ip,
+}
+
+
+def mask_response(data: Dict[str, Any], mask_rules: Dict[str, str]) -> Dict[str, Any]:
+    """
+    对响应数据进行脱敏
+
+    Args:
+        data: 原始响应数据
+        mask_rules: 脱敏规则 {field_name: mask_type}
+                   mask_type: phone, id_card, email, bank_card, name, ip
+
+    Returns:
+        脱敏后的数据
+    """
+    result = data.copy()
+    for field, mask_type in mask_rules.items():
+        if field in result and result[field]:
+            mask_func = MASK_FUNCTIONS.get(mask_type)
+            if mask_func:
+                result[field] = mask_func(str(result[field]))
+    return result

src/security/input_validator.py

+"""
+输入验证 + 注入防护模块
+SQL 注入防护、XSS 防护、文件上传验证、通用输入清理
+"""
+import re
+import html
+import os
+import mimetypes
+from typing import Optional, Tuple, List, Dict, Any
+
+
+# ============ SQL 注入防护 ============
+
+# SQL 注入关键词模式
+SQL_INJECTION_PATTERNS = [
+    re.compile(r"(\b(SELECT|INSERT|UPDATE|DELETE|DROP|UNION|ALTER|CREATE|EXEC)\b.*\b(FROM|INTO|TABLE|WHERE|SET)\b)", re.IGNORECASE),
+    re.compile(r"(--|#|/\*|\*/|;)", re.IGNORECASE),
+    re.compile(r"(\bOR\b\s+\d+\s*=\s*\d+)", re.IGNORECASE),
+    re.compile(r"('\s*(OR|AND)\s+')", re.IGNORECASE),
+    re.compile(r"(WAITFOR\s+DELAY)", re.IGNORECASE),
+    re.compile(r"(BENCHMARK\s*\()", re.IGNORECASE),
+    re.compile(r"(SLEEP\s*\()", re.IGNORECASE),
+]
+
+
+def detect_sql_injection(value: str) -> Tuple[bool, str]:
+    """
+    检测字符串是否包含 SQL 注入模式
+
+    Returns:
+        (是否检测到注入, 描述信息)
+    """
+    if not isinstance(value, str):
+        return False, ""
+
+    for pattern in SQL_INJECTION_PATTERNS:
+        match = pattern.search(value)
+        if match:
+            return True, f"检测到疑似 SQL 注入: {match.group()}"
+
+    return False, ""
+
+
+def sanitize_sql_value(value: str) -> str:
+    """
+    清理可能包含 SQL 注入的输入值
+    注意：这是辅助手段，主要防护应使用参数化查询
+    """
+    if not isinstance(value, str):
+        return value
+
+    # 移除危险字符
+    dangerous_chars = ["'", '"', ";", "--", "#", "/*", "*/", "\\", "\x00"]
+    result = value
+    for char in dangerous_chars:
+        result = result.replace(char, "")
+
+    return result.strip()
+
+
+def parameterized_query(query_template: str, params: Dict[str, Any]) -> str:
+    """
+    生成参数化查询的安全说明
+    实际使用时应直接传入参数给数据库驱动
+
+    示例:
+        # 正确做法（使用 ORM 或数据库驱动的参数化）
+        cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+
+        # 不要拼接 SQL
+        # cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
+    """
+    return query_template
+
+
+# ============ XSS 防护 ============
+
+# XSS 攻击模式
+XSS_PATTERNS = [
+    re.compile(r"<\s*script", re.IGNORECASE),
+    re.compile(r"javascript\s*:", re.IGNORECASE),
+    re.compile(r"on\w+\s*=", re.IGNORECASE),  # onclick, onerror, etc.
+    re.compile(r"<\s*iframe", re.IGNORECASE),
+    re.compile(r"<\s*object", re.IGNORECASE),
+    re.compile(r"<\s*embed", re.IGNORECASE),
+    re.compile(r"<\s*img[^>]+onerror", re.IGNORECASE),
+    re.compile(r"expression\s*\(", re.IGNORECASE),
+    re.compile(r"url\s*\(", re.IGNORECASE),
+    re.compile(r"data\s*:\s*text/html", re.IGNORECASE),
+]
+
+
+def detect_xss(value: str) -> Tuple[bool, str]:
+    """
+    检测字符串是否包含 XSS 攻击模式
+
+    Returns:
+        (是否检测到 XSS, 描述信息)
+    """
+    if not isinstance(value, str):
+        return False, ""
+
+    for pattern in XSS_PATTERNS:
+        match = pattern.search(value)
+        if match:
+            return True, f"检测到疑似 XSS 攻击: {match.group()}"
+
+    return False, ""
+
+
+def escape_html(value: str) -> str:
+    """HTML 转义，防止 XSS"""
+    if not isinstance(value, str):
+        return value
+    return html.escape(value, quote=True)
+
+
+def sanitize_html(value: str) -> str:
+    """
+    清理 HTML 内容，移除所有标签
+    用于需要纯文本的场景
+    """
+    if not isinstance(value, str):
+        return value
+
+    # 移除所有 HTML 标签
+    clean = re.sub(r"<[^>]+>", "", value)
+    # 转义剩余的特殊字符
+    return html.escape(clean, quote=True)
+
+
+# ============ 文件上传验证 ============
+
+# 允许的文件类型
+ALLOWED_MIME_TYPES = {
+    "image/jpeg": [".jpg", ".jpeg"],
+    "image/png": [".png"],
+    "image/gif": [".gif"],
+    "image/webp": [".webp"],
+    "application/pdf": [".pdf"],
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": [".xlsx"],
+    "application/vnd.ms-excel": [".xls"],
+    "text/csv": [".csv"],
+    "application/json": [".json"],
+    "text/plain": [".txt", ".log"],
+}
+
+# 最大文件大小 (10 MB)
+MAX_FILE_SIZE = 10 * 1024 * 1024
+
+# 危险文件扩展名
+DANGEROUS_EXTENSIONS = {
+    ".exe", ".bat", ".cmd", ".sh", ".bash", ".csh",
+    ".py", ".pyw", ".php", ".jsp", ".asp", ".aspx",
+    ".html", ".htm", ".js", ".vbs", ".ps1",
+}
+
+
+class FileUploadValidator:
+    """文件上传验证器"""
+
+    def __init__(
+        self,
+        allowed_types: Optional[Dict[str, List[str]]] = None,
+        max_size: int = MAX_FILE_SIZE,
+    ):
+        self.allowed_types = allowed_types or ALLOWED_MIME_TYPES
+        self.max_size = max_size
+
+    def validate(
+        self,
+        filename: str,
+        content_type: Optional[str],
+        size: int,
+        content: Optional[bytes] = None,
+    ) -> Tuple[bool, str]:
+        """
+        验证上传文件
+
+        Args:
+            filename: 文件名
+            content_type: MIME 类型
+            size: 文件大小（字节）
+            content: 文件内容（可选，用于内容检查）
+
+        Returns:
+            (是否通过, 错误信息)
+        """
+        errors = []
+
+        # 1. 检查文件大小
+        if size > self.max_size:
+            max_mb = self.max_size / (1024 * 1024)
+            errors.append(f"文件大小超过限制（最大 {max_mb:.1f} MB）")
+
+        # 2. 检查文件扩展名
+        _, ext = os.path.splitext(filename.lower())
+        if ext in DANGEROUS_EXTENSIONS:
+            errors.append(f"不允许上传 {ext} 类型的文件")
+
+        # 3. 检查 MIME 类型
+        if content_type and content_type not in self.allowed_types:
+            errors.append(f"不支持的文件类型: {content_type}")
+
+        # 4. 检查扩展名与 MIME 类型匹配
+        if content_type and content_type in self.allowed_types:
+            allowed_exts = self.allowed_types[content_type]
+            if ext and ext not in allowed_exts:
+                errors.append(f"文件扩展名 {ext} 与类型 {content_type} 不匹配")
+
+        # 5. 内容检查（如果提供了内容）
+        if content:
+            # 检查文件头（magic bytes）
+            if content[:4] == b"\x89PNG" and content_type != "image/png":
+                errors.append("文件内容与声明的类型不匹配")
+            elif content[:2] == b"\xff\xd8" and content_type != "image/jpeg":
+                errors.append("文件内容与声明的类型不匹配")
+            elif content[:4] == b"%PDF" and content_type != "application/pdf":
+                errors.append("文件内容与声明的类型不匹配")
+
+            # 检查是否包含可执行代码
+            if b"<?php" in content or b"<%" in content:
+                errors.append("文件包含可疑内容")
+
+        if errors:
+            return False, "; ".join(errors)
+        return True, ""
+
+
+# 全局验证器实例
+file_validator = FileUploadValidator()
+
+
+def validate_file_upload(
+    filename: str,
+    content_type: Optional[str],
+    size: int,
+    content: Optional[bytes] = None,
+) -> Tuple[bool, str]:
+    """便捷函数：验证文件上传"""
+    return file_validator.validate(filename, content_type, size, content)
+
+
+# ============ 通用输入清理 ============
+
+def sanitize_string(value: str, max_length: int = 0) -> str:
+    """
+    通用字符串清理
+
+    Args:
+        value: 输入字符串
+        max_length: 最大长度（0 表示不限制）
+
+    Returns:
+        清理后的字符串
+    """
+    if not isinstance(value, str):
+        return str(value) if value is not None else ""
+
+    # 移除 null 字节
+    result = value.replace("\x00", "")
+
+    # 移除控制字符（保留换行和制表符）
+    result = re.sub(r"[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]", "", result)
+
+    # 限制长度
+    if max_length > 0:
+        result = result[:max_length]
+
+    return result.strip()
+
+
+def sanitize_number(value: Any, min_val: Optional[float] = None, max_val: Optional[float] = None) -> Optional[float]:
+    """
+    验证和清理数字输入
+
+    Returns:
+        清理后的数字，无效时返回 None
+    """
+    try:
+        num = float(value)
+        if min_val is not None and num < min_val:
+            return None
+        if max_val is not None and num > max_val:
+            return None
+        return num
+    except (TypeError, ValueError):
+        return None
+
+
+def validate_email_format(email: str) -> bool:
+    """验证邮箱格式"""
+    pattern = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
+    return bool(pattern.match(email))
+
+
+def validate_phone_format(phone: str) -> bool:
+    """验证中国手机号格式"""
+    pattern = re.compile(r"^1[3-9]\d{9}$")
+    return bool(pattern.match(phone))
+
+
+def validate_id_card_format(id_card: str) -> bool:
+    """验证身份证号格式（简单校验）"""
+    pattern = re.compile(r"^\d{17}[\dXx]$")
+    return bool(pattern.match(id_card))

src/security/middleware.py

+"""
+安全中间件模块
+JWT 认证、CORS、限流、审计日志、CSRF、安全 Headers
+"""
+import os
+import re
+import time
+import secrets
+import hashlib
+import logging
+from typing import Optional, Dict, List, Callable
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from .config import security_config
+from .auth import verify_access_token, extract_token_from_header
+from .audit import AuditLogger, AuditEvent, AuditResult
+
+logger = logging.getLogger(__name__)
+
+
+class RateLimiter:
+    """基于内存的 IP 限流器（令牌桶算法）"""
+
+    def __init__(self, max_requests: int = 60, window_seconds: int = 60):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._requests: Dict[str, List[float]] = defaultdict(list)
+
+    def is_allowed(self, ip: str) -> bool:
+        """检查 IP 是否超过限流"""
+        now = time.time()
+        cutoff = now - self.window_seconds
+
+        # 清理过期记录
+        self._requests[ip] = [
+            t for t in self._requests[ip] if t > cutoff
+        ]
+
+        if len(self._requests[ip]) >= self.max_requests:
+            return False
+
+        self._requests[ip].append(now)
+        return True
+
+    def get_remaining(self, ip: str) -> int:
+        """获取剩余请求数"""
+        now = time.time()
+        cutoff = now - self.window_seconds
+        self._requests[ip] = [
+            t for t in self._requests[ip] if t > cutoff
+        ]
+        return max(0, self.max_requests - len(self._requests[ip]))
+
+    def cleanup(self):
+        """清理所有过期记录"""
+        now = time.time()
+        cutoff = now - self.window_seconds
+        expired_ips = []
+        for ip, timestamps in self._requests.items():
+            self._requests[ip] = [t for t in timestamps if t > cutoff]
+            if not self._requests[ip]:
+                expired_ips.append(ip)
+        for ip in expired_ips:
+            del self._requests[ip]
+
+
+# 全局限流器实例
+_rate_limiter = RateLimiter(
+    max_requests=security_config.rate_limit.max_requests_per_minute,
+    window_seconds=60,
+)
+
+
+def get_rate_limiter() -> RateLimiter:
+    """获取全局限流器"""
+    return _rate_limiter
+
+
+def generate_csrf_token(session_id: str) -> str:
+    """生成 CSRF token"""
+    secret = security_config.jwt.secret_key
+    timestamp = str(int(time.time()))
+    nonce = secrets.token_hex(8)
+    raw = f"{session_id}:{timestamp}:{nonce}:{secret}"
+    token = hashlib.sha256(raw.encode()).hexdigest()
+    return f"{timestamp}:{nonce}:{token}"
+
+
+def validate_csrf_token(token: str, session_id: str) -> bool:
+    """验证 CSRF token"""
+    try:
+        parts = token.split(":")
+        if len(parts) != 3:
+            return False
+        timestamp, nonce, hash_value = parts
+
+        # 检查时间戳（1小时内有效）
+        if abs(time.time() - int(timestamp)) > 3600:
+            return False
+
+        secret = security_config.jwt.secret_key
+        raw = f"{session_id}:{timestamp}:{nonce}:{secret}"
+        expected = hashlib.sha256(raw.encode()).hexdigest()
+        return secrets.compare_digest(hash_value, expected)
+    except Exception:
+        return False
+
+
+def get_client_ip(headers: dict, remote_addr: str = "") -> str:
+    """从请求头中提取客户端真实 IP"""
+    forwarded_for = headers.get("x-forwarded-for", "")
+    if forwarded_for:
+        return forwarded_for.split(",")[0].strip()
+
+    real_ip = headers.get("x-real-ip", "")
+    if real_ip:
+        return real_ip
+
+    return remote_addr
+
+
+class SecurityMiddleware:
+    """
+    FastAPI 安全中间件
+
+    用法:
+        app.add_middleware(SecurityMiddleware)
+    """
+
+    def __init__(
+        self,
+        app,
+        excluded_paths: Optional[List[str]] = None,
+    ):
+        self.app = app
+        self.excluded_paths = excluded_paths or [
+            "/auth/login",
+            "/auth/refresh",
+            "/health",
+            "/docs",
+            "/openapi.json",
+            "/redoc",
+        ]
+        self.audit_logger = AuditLogger()
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+
+        # 跳过排除路径
+        if any(path.startswith(excluded) for excluded in self.excluded_paths):
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope.get("headers", []))
+        headers = {
+            k.decode() if isinstance(k, bytes) else k:
+            v.decode() if isinstance(v, bytes) else v
+            for k, v in headers.items()
+        }
+
+        method = scope.get("method", "GET")
+        client_ip = get_client_ip(headers, scope.get("client", ("", ""))[0])
+
+        # 1. Rate Limiting
+        rate_limiter = get_rate_limiter()
+        if not rate_limiter.is_allowed(client_ip):
+            response_body = '{"detail": "请求过于频繁，请稍后再试"}'.encode("utf-8")
+            await send({
+                "type": "http.response.start",
+                "status": 429,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"retry-after", b"60"),
+                ],
+            })
+            await send({
+                "type": "http.response.body",
+                "body": response_body,
+            })
+            return
+
+        # 2. Security Headers
+        original_send = send
+
+        async def send_with_security_headers(message):
+            if message["type"] == "http.response.start":
+                extra_headers = [
+                    (b"x-content-type-options", b"nosniff"),
+                    (b"x-frame-options", b"DENY"),
+                    (b"x-xss-protection", b"1; mode=block"),
+                    (b"strict-transport-security", b"max-age=31536000; includeSubDomains"),
+                    (b"content-security-policy", b"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'"),
+                    (b"referrer-policy", b"strict-origin-when-cross-origin"),
+                    (b"permissions-policy", b"camera=(), microphone=(), geolocation=()"),
+                ]
+                message["headers"] = list(message.get("headers", [])) + extra_headers
+            await original_send(message)
+
+        # 3. JWT 认证（对需要认证的路径）
+        auth_required = not any(
+            path.startswith(p) for p in self.excluded_paths
+        )
+
+        if auth_required and method not in ("OPTIONS",):
+            auth_header = headers.get("authorization", "")
+            token = extract_token_from_header(auth_header)
+
+            if not token:
+                response_body = '{"detail": "未提供认证凭据"}'.encode("utf-8")
+                await send({
+                    "type": "http.response.start",
+                    "status": 401,
+                    "headers": [(b"content-type", b"application/json")],
+                })
+                await send({
+                    "type": "http.response.body",
+                    "body": response_body,
+                })
+                return
+
+            payload = verify_access_token(token)
+            if payload is None:
+                response_body = '{"detail": "认证凭据无效或已过期"}'.encode("utf-8")
+                await send({
+                    "type": "http.response.start",
+                    "status": 401,
+                    "headers": [(b"content-type", b"application/json")],
+                })
+                await send({
+                    "type": "http.response.body",
+                    "body": response_body,
+                })
+                return
+
+            # 将用户信息注入 scope
+            scope["user"] = payload
+
+        # 4. 审计日志
+        start_time = time.time()
+        audit_event = AuditEvent(
+            timestamp=datetime.now(timezone.utc),
+            user_id=scope.get("user", {}).get("sub", "anonymous"),
+            action=f"{method} {path}",
+            resource=path,
+            ip_address=client_ip,
+            user_agent=headers.get("user-agent", ""),
+            result=AuditResult.SUCCESS,
+        )
+
+        await self.app(scope, receive, send_with_security_headers)
+
+        # 记录审计日志
+        duration = time.time() - start_time
+        audit_event.details = {"duration_ms": round(duration * 1000, 2)}
+        self.audit_logger.log(audit_event)
+
+
+def cors_middleware(app, config=None):
+    """
+    CORS 中间件包装器
+
+    用法:
+        from starlette.middleware.cors import CORSMiddleware
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=security_config.cors.allowed_origins,
+            allow_credentials=security_config.cors.allow_credentials,
+            allow_methods=security_config.cors.allowed_methods,
+            allow_headers=security_config.cors.allowed_headers,
+            max_age=security_config.cors.max_age,
+        )
+    """
+    cfg = config or security_config.cors
+    try:
+        from starlette.middleware.cors import CORSMiddleware
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cfg.allowed_origins,
+            allow_credentials=cfg.allow_credentials,
+            allow_methods=cfg.allowed_methods,
+            allow_headers=cfg.allowed_headers,
+            max_age=cfg.max_age,
+        )
+    except ImportError:
+        logger.warning("starlette 未安装，CORS 中间件未启用")
+    return app

tests/test_security.py

+"""
+安全模块单元测试
+覆盖 JWT、权限、加密、输入验证、审计日志
+"""
+import sys
+import os
+import json
+import time
+import unittest
+from datetime import datetime, timezone
+
+# 将项目根目录加入路径
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from src.security.auth import (
+    Role, hash_password, verify_password,
+    create_access_token, create_refresh_token,
+    verify_access_token, verify_refresh_token,
+    get_user_roles, check_permission,
+    extract_token_from_header, validate_password_strength,
+)
+from src.security.encryption import (
+    FieldEncryptor, encrypt_field, decrypt_field,
+    mask_phone, mask_id_card, mask_email,
+    mask_bank_card, mask_name, mask_ip,
+    mask_response,
+)
+from src.security.input_validator import (
+    detect_sql_injection, sanitize_sql_value,
+    detect_xss, escape_html, sanitize_html,
+    sanitize_string, sanitize_number,
+    validate_email_format, validate_phone_format,
+    validate_file_upload,
+)
+from src.security.audit import (
+    AuditAction, AuditResult, AuditSeverity, AuditEvent,
+    AuditLogger, AuditStorage, AuditAlertManager,
+)
+from src.security.middleware import (
+    RateLimiter, generate_csrf_token, validate_csrf_token,
+    get_client_ip,
+)
+from src.security.config import security_config
+
+
+class TestAuth(unittest.TestCase):
+    """认证模块测试"""
+
+    def test_password_hash(self):
+        """密码哈希与验证"""
+        password = "TestPassword123"
+        hashed = hash_password(password)
+        self.assertNotEqual(password, hashed)
+        self.assertTrue(verify_password(password, hashed))
+        self.assertFalse(verify_password("wrong", hashed))
+
+    def test_create_access_token(self):
+        """生成 access token"""
+        token = create_access_token("user1", [Role.ADMIN, Role.OPERATOR])
+        self.assertIsInstance(token, str)
+        self.assertTrue(len(token) > 50)
+
+    def test_verify_access_token(self):
+        """验证 access token"""
+        token = create_access_token("user1", [Role.ADMIN])
+        payload = verify_access_token(token)
+        self.assertIsNotNone(payload)
+        self.assertEqual(payload["sub"], "user1")
+        self.assertEqual(payload["type"], "access")
+        self.assertIn("admin", payload["roles"])
+
+    def test_expired_token(self):
+        """过期 token 验证"""
+        # 通过修改配置来创建过期 token
+        import jwt as pyjwt
+        from src.security.config import security_config as cfg
+        payload = {
+            "sub": "user1",
+            "roles": ["admin"],
+            "iat": int(time.time()) - 7200,
+            "exp": int(time.time()) - 3600,  # 已过期
+            "iss": cfg.jwt.issuer,
+            "type": "access",
+        }
+        token = pyjwt.encode(payload, cfg.jwt.secret_key, algorithm=cfg.jwt.algorithm)
+        result = verify_access_token(token)
+        self.assertIsNone(result)
+
+    def test_refresh_token(self):
+        """Refresh token 生成与验证"""
+        token = create_refresh_token("user1")
+        payload = verify_refresh_token(token)
+        self.assertIsNotNone(payload)
+        self.assertEqual(payload["sub"], "user1")
+        self.assertEqual(payload["type"], "refresh")
+
+    def test_token_type_mismatch(self):
+        """Token 类型不匹配"""
+        access_token = create_access_token("user1", [Role.ADMIN])
+        # 用 verify_refresh_token 验证 access token 应该失败
+        result = verify_refresh_token(access_token)
+        self.assertIsNone(result)
+
+    def test_get_user_roles(self):
+        """从 payload 提取角色"""
+        payload = {"roles": ["admin", "operator"]}
+        roles = get_user_roles(payload)
+        self.assertEqual(len(roles), 2)
+        self.assertIn(Role.ADMIN, roles)
+        self.assertIn(Role.OPERATOR, roles)
+
+    def test_check_permission(self):
+        """权限检查"""
+        self.assertTrue(check_permission([Role.ADMIN], "system:manage"))
+        self.assertTrue(check_permission([Role.OPERATOR], "data:write"))
+        self.assertFalse(check_permission([Role.VIEWER], "data:write"))
+        self.assertFalse(check_permission([Role.VIEWER], "system:manage"))
+
+    def test_extract_token(self):
+        """从 Authorization header 提取 token"""
+        self.assertEqual(
+            extract_token_from_header("Bearer abc123"),
+            "abc123"
+        )
+        self.assertIsNone(extract_token_from_header("Basic abc123"))
+        self.assertIsNone(extract_token_from_header(""))
+        self.assertIsNone(extract_token_from_header(None))
+
+    def test_password_strength(self):
+        """密码强度验证"""
+        ok, msg = validate_password_strength("Abcdef1!")
+        self.assertTrue(ok)
+
+        ok, msg = validate_password_strength("123")
+        self.assertFalse(ok)
+
+        ok, msg = validate_password_strength("abcdefgh")
+        self.assertFalse(ok)  # 缺少大写和数字
+
+
+class TestEncryption(unittest.TestCase):
+    """加密模块测试"""
+
+    def setUp(self):
+        self.encryptor = FieldEncryptor()
+
+    def test_encrypt_decrypt(self):
+        """加密和解密"""
+        plaintext = "敏感数据123"
+        encrypted = self.encryptor.encrypt(plaintext)
+        self.assertNotEqual(plaintext, encrypted)
+
+        decrypted = self.encryptor.decrypt(encrypted)
+        self.assertEqual(plaintext, decrypted)
+
+    def test_encrypt_empty_string(self):
+        """空字符串加密"""
+        result = encrypt_field("")
+        self.assertEqual(result, "")
+
+    def test_encrypt_field_roundtrip(self):
+        """字段加密解密往返"""
+        original = "13812345678"
+        encrypted = encrypt_field(original)
+        decrypted = decrypt_field(encrypted)
+        self.assertEqual(original, decrypted)
+
+    def test_mask_phone(self):
+        """手机号脱敏"""
+        self.assertEqual(mask_phone("13812345678"), "138****5678")
+        self.assertEqual(mask_phone("138"), "138")
+        self.assertEqual(mask_phone(""), "")
+
+    def test_mask_id_card(self):
+        """身份证脱敏"""
+        self.assertEqual(mask_id_card("110101199001011234"), "1101**********1234")
+        self.assertEqual(mask_id_card(""), "")
+
+    def test_mask_email(self):
+        """邮箱脱敏"""
+        self.assertEqual(mask_email("test@example.com"), "t***@example.com")
+        self.assertEqual(mask_email("a@b.com"), "a***@b.com")
+
+    def test_mask_bank_card(self):
+        """银行卡脱敏"""
+        self.assertEqual(mask_bank_card("6225880137073520"), "6225********3520")
+
+    def test_mask_name(self):
+        """姓名脱敏"""
+        self.assertEqual(mask_name("张三"), "张*")
+        self.assertEqual(mask_name("欧阳修"), "欧阳*")
+
+    def test_mask_ip(self):
+        """IP 脱敏"""
+        self.assertEqual(mask_ip("192.168.1.100"), "192.168.*.*")
+
+    def test_mask_response(self):
+        """响应脱敏"""
+        data = {"phone": "13812345678", "name": "张三", "email": "test@test.com"}
+        rules = {"phone": "phone", "name": "name", "email": "email"}
+        result = mask_response(data, rules)
+        self.assertEqual(result["phone"], "138****5678")
+        self.assertEqual(result["name"], "张*")
+        self.assertIn("***", result["email"])
+
+
+class TestInputValidator(unittest.TestCase):
+    """输入验证测试"""
+
+    def test_sql_injection_detection(self):
+        """SQL 注入检测"""
+        is_injection, msg = detect_sql_injection("'; DROP TABLE users; --")
+        self.assertTrue(is_injection)
+
+        is_injection, msg = detect_sql_injection("1 OR 1=1")
+        self.assertTrue(is_injection)
+
+        is_injection, msg = detect_sql_injection("normal input value")
+        self.assertFalse(is_injection)
+
+    def test_sanitize_sql(self):
+        """SQL 值清理"""
+        result = sanitize_sql_value("'; DROP TABLE users;--")
+        self.assertNotIn("'", result)
+        self.assertNotIn(";", result)
+        self.assertNotIn("--", result)
+
+    def test_xss_detection(self):
+        """XSS 检测"""
+        is_xss, msg = detect_xss("<script>alert('xss')</script>")
+        self.assertTrue(is_xss)
+
+        is_xss, msg = detect_xss("javascript:alert(1)")
+        self.assertTrue(is_xss)
+
+        is_xss, msg = detect_xss("onclick=alert(1)")
+        self.assertTrue(is_xss)
+
+        is_xss, msg = detect_xss("normal text content")
+        self.assertFalse(is_xss)
+
+    def test_escape_html(self):
+        """HTML 转义"""
+        result = escape_html("<script>alert('xss')</script>")
+        self.assertNotIn("<script>", result)
+        self.assertIn("&lt;", result)
+
+    def test_sanitize_html(self):
+        """清理 HTML"""
+        result = sanitize_html("<p>Hello <b>World</b></p>")
+        self.assertNotIn("<p>", result)
+        self.assertNotIn("<b>", result)
+
+    def test_sanitize_string(self):
+        """字符串清理"""
+        result = sanitize_string("  hello world  ")
+        self.assertEqual(result, "hello world")
+
+        result = sanitize_string("hello\x00world")
+        self.assertNotIn("\x00", result)
+
+        result = sanitize_string("hello world", max_length=5)
+        self.assertEqual(len(result), 5)
+
+    def test_sanitize_number(self):
+        """数字验证"""
+        self.assertEqual(sanitize_number("123"), 123.0)
+        self.assertEqual(sanitize_number("123.45"), 123.45)
+        self.assertIsNone(sanitize_number("abc"))
+        self.assertIsNone(sanitize_number("100", min_val=200))
+        self.assertIsNone(sanitize_number("300", max_val=200))
+
+    def test_validate_email(self):
+        """邮箱格式验证"""
+        self.assertTrue(validate_email_format("test@example.com"))
+        self.assertFalse(validate_email_format("not-an-email"))
+        self.assertFalse(validate_email_format("@example.com"))
+
+    def test_validate_phone(self):
+        """手机号格式验证"""
+        self.assertTrue(validate_phone_format("13812345678"))
+        self.assertFalse(validate_phone_format("12345678901"))
+        self.assertFalse(validate_phone_format("138"))
+
+    def test_file_upload_validation(self):
+        """文件上传验证"""
+        # 正常图片
+        ok, msg = validate_file_upload("test.jpg", "image/jpeg", 1024)
+        self.assertTrue(ok)
+
+        # 危险文件类型
+        ok, msg = validate_file_upload("hack.exe", "application/octet-stream", 1024)
+        self.assertFalse(ok)
+
+        # 超大文件
+        ok, msg = validate_file_upload("big.pdf", "application/pdf", 100 * 1024 * 1024)
+        self.assertFalse(ok)
+
+
+class TestAudit(unittest.TestCase):
+    """审计日志测试"""
+
+    def test_audit_event_creation(self):
+        """审计事件创建"""
+        event = AuditEvent(
+            timestamp=datetime.now(timezone.utc),
+            user_id="user1",
+            action=AuditAction.LOGIN.value,
+            resource="/auth/login",
+            ip_address="127.0.0.1",
+            result=AuditResult.SUCCESS,
+        )
+        self.assertTrue(len(event.event_id) > 0)
+        self.assertEqual(event.user_id, "user1")
+
+    def test_audit_event_to_dict(self):
+        """审计事件转字典"""
+        event = AuditEvent(
+            timestamp=datetime.now(timezone.utc),
+            user_id="user1",
+            action=AuditAction.LOGIN.value,
+        )
+        d = event.to_dict()
+        self.assertIn("timestamp", d)
+        self.assertIn("user_id", d)
+        self.assertIn("event_id", d)
+
+    def test_audit_logger(self):
+        """审计记录器"""
+        logger = AuditLogger()
+        logger.log_action(
+            user_id="user1",
+            action=AuditAction.LOGIN.value,
+            ip_address="127.0.0.1",
+        )
+        logs = logger.query(user_id="user1")
+        self.assertTrue(len(logs) > 0)
+
+    def test_audit_query(self):
+        """审计日志查询"""
+        logger = AuditLogger()
+        logger.log_action(user_id="user1", action=AuditAction.LOGIN.value)
+        logger.log_action(user_id="user2", action=AuditAction.DATA_READ.value)
+
+        logs = logger.query(action=AuditAction.LOGIN.value)
+        self.assertTrue(all(l["action"] == AuditAction.LOGIN.value for l in logs))
+
+    def test_audit_alert(self):
+        """审计告警"""
+        alert_mgr = AuditAlertManager()
+        # 模拟多次登录失败
+        for i in range(6):
+            event = AuditEvent(
+                timestamp=datetime.now(timezone.utc),
+                user_id="attacker",
+                action=AuditAction.LOGIN_FAILED.value,
+                ip_address="10.0.0.1",
+                result=AuditResult.FAILURE,
+            )
+            alert = alert_mgr.check_alert(event)
+
+        # 应该触发告警
+        alerts = alert_mgr.get_alerts()
+        self.assertTrue(len(alerts) > 0)
+
+    def test_audit_stats(self):
+        """审计统计"""
+        logger = AuditLogger()
+        logger.log_action(user_id="user1", action=AuditAction.LOGIN.value)
+        logger.log_action(user_id="user1", action=AuditAction.DATA_READ.value)
+        stats = logger.get_stats(hours=1)
+        self.assertIn("total_events", stats)
+        self.assertIn("action_counts", stats)
+
+
+class TestMiddleware(unittest.TestCase):
+    """中间件工具测试"""
+
+    def test_rate_limiter(self):
+        """限流器"""
+        limiter = RateLimiter(max_requests=3, window_seconds=60)
+
+        self.assertTrue(limiter.is_allowed("127.0.0.1"))
+        self.assertTrue(limiter.is_allowed("127.0.0.1"))
+        self.assertTrue(limiter.is_allowed("127.0.0.1"))
+        self.assertFalse(limiter.is_allowed("127.0.0.1"))  # 超过限制
+
+        # 不同 IP 不受影响
+        self.assertTrue(limiter.is_allowed("192.168.1.1"))
+
+    def test_rate_limiter_remaining(self):
+        """限流器剩余次数"""
+        limiter = RateLimiter(max_requests=5, window_seconds=60)
+        limiter.is_allowed("127.0.0.1")
+        limiter.is_allowed("127.0.0.1")
+        self.assertEqual(limiter.get_remaining("127.0.0.1"), 3)
+
+    def test_csrf_token(self):
+        """CSRF token 生成与验证"""
+        session_id = "test-session-123"
+        token = generate_csrf_token(session_id)
+        self.assertTrue(validate_csrf_token(token, session_id))
+        self.assertFalse(validate_csrf_token(token, "wrong-session"))
+        self.assertFalse(validate_csrf_token("invalid-token", session_id))
+
+    def test_get_client_ip(self):
+        """获取客户端 IP"""
+        # X-Forwarded-For
+        ip = get_client_ip({"x-forwarded-for": "10.0.0.1, 10.0.0.2"}, "127.0.0.1")
+        self.assertEqual(ip, "10.0.0.1")
+
+        # X-Real-IP
+        ip = get_client_ip({"x-real-ip": "10.0.0.3"}, "127.0.0.1")
+        self.assertEqual(ip, "10.0.0.3")
+
+        # 无代理头
+        ip = get_client_ip({}, "127.0.0.1")
+        self.assertEqual(ip, "127.0.0.1")
+
+
+class TestConfig(unittest.TestCase):
+    """配置测试"""
+
+    def test_default_config(self):
+        """默认配置加载"""
+        self.assertIsNotNone(security_config.jwt)
+        self.assertIsNotNone(security_config.encryption)
+        self.assertIsNotNone(security_config.rate_limit)
+        self.assertIsNotNone(security_config.cors)
+        self.assertIsNotNone(security_config.password_policy)
+        self.assertIsNotNone(security_config.audit)
+
+    def test_jwt_config(self):
+        """JWT 配置"""
+        self.assertEqual(security_config.jwt.algorithm, "HS256")
+        self.assertTrue(security_config.jwt.access_token_expire_minutes > 0)
+
+    def test_rate_limit_config(self):
+        """限流配置"""
+        self.assertTrue(security_config.rate_limit.max_requests_per_minute > 0)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)