# 安全架构文档

## 概述

水务管理系统安全模块提供完整的身份认证、权限控制、数据加密和安全审计能力，保障系统在生产环境中的安全性。

## 安全架构

```
┌─────────────────────────────────────────────────────────┐
│                     客户端请求                            │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  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*