智慧水务管理系统 - 精河县供水工程综合管理平台

安全架构文档

概述

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

安全架构

┌─────────────────────────────────────────────────────────┐
│                     客户端请求                            │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│  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 响应数据脱敏前的安全存储

密钥管理

# 生成 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 次请求，可通过环境变量调整：

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. 响应脱敏

敏感数据在返回客户端前自动脱敏：

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

审计日志查询

# 查询最近审计日志
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. 响应阶段

确认事件: 查看审计日志确认事件详情
隔离影响: 必要时禁用相关账户
修复漏洞: 定位并修复安全问题
通知相关方: 如涉及数据泄露，通知受影响用户

3. 复盘阶段

记录事件处理过程
分析根本原因
更新安全策略
优化告警规则

环境变量配置

# 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

SECURITY.md 10KB История Исходник