14 KiB
14 KiB
安全合规
**本文引用的文件** - [backend/app/core/security.py](file://backend/app/core/security.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/.env.example](file://backend/.env.example) - [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py) - [backend/test_api.py](file://backend/test_api.py) - [test_frontend_connection.py](file://test_frontend_connection.py) - [docs/backend.md](file://docs/backend.md) - [docs/database.md](file://docs/database.md)目录
简介
本指南面向“医院绩效考核管理系统”的安全与合规落地，聚焦以下方面：
- 身份认证与授权：JWT 令牌管理、密码加密存储、会话安全与权限控制
- 网络安全：HTTPS、CORS 策略与前端访问控制
- 数据安全：敏感数据保护、传输安全与访问控制
- 审计与风控：日志记录、违规检测与事件响应
- 漏洞治理：扫描工具使用、补丁管理与合规检查
- 权限治理：用户权限管理、角色分配与最小权限原则
项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM，按功能分层组织：
- 核心配置与安全：core/config.py、core/security.py、core/logging_config.py
- API 层：api/v1/*（如 auth.py）
- 数据模型与枚举：models/models.py
- 数据契约：schemas/schemas.py
- 应用入口与中间件：main.py
- 示例环境变量：.env.example
- 文档与数据库设计：docs/backend.md、docs/database.md
- 前端连接测试脚本：test_frontend_connection.py、backend/test_api.py
graph TB
subgraph "后端"
CFG["配置<br/>core/config.py"]
SEC["安全模块<br/>core/security.py"]
LOG["日志配置<br/>core/logging_config.py"]
MAIN["应用入口<br/>app/main.py"]
AUTH["认证路由<br/>api/v1/auth.py"]
MODELS["数据模型<br/>models/models.py"]
SCHEMAS["数据契约<br/>schemas/schemas.py"]
end
CFG --> SEC
CFG --> MAIN
SEC --> AUTH
MAIN --> AUTH
AUTH --> MODELS
MODELS --> SCHEMAS
LOG --> MAIN
图表来源
- backend/app/core/config.py
- backend/app/core/security.py
- backend/app/core/logging_config.py
- backend/app/main.py
- backend/app/api/v1/auth.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
章节来源
- backend/app/main.py
- backend/app/core/config.py
- backend/app/core/security.py
- backend/app/core/logging_config.py
- backend/app/api/v1/auth.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
- docs/backend.md
- docs/database.md
核心组件
- 配置中心：集中管理应用名、版本、调试、API 前缀、数据库连接、JWT 密钥与算法、CORS 白名单、分页参数等
- 安全模块：OAuth2 密码流、JWT 编解码、bcrypt 密码哈希、当前用户解析、活跃用户校验、管理员/经理权限校验
- 认证路由：登录、注册、当前用户信息查询
- 日志模块：按日轮转的多处理器日志，区分应用日志与错误日志
- 数据模型：用户表含用户名、密码哈希、角色、启用状态等字段
- 数据契约：用户登录、注册、令牌、用户响应等 Pydantic 模型
章节来源
- backend/app/core/config.py
- backend/app/core/security.py
- backend/app/api/v1/auth.py
- backend/app/core/logging_config.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
架构总览
系统通过 FastAPI 提供 REST 接口，CORS 中间件允许指定来源访问；认证采用 OAuth2 密码流配合 JWT；密码以 bcrypt 存储；日志统一输出到控制台与文件。
sequenceDiagram
participant FE as "前端"
participant API as "FastAPI 应用"
participant AUTH as "认证路由"
participant SEC as "安全模块"
participant DB as "数据库"
FE->>API : "OPTIONS/POST /api/v1/auth/login"
API->>AUTH : "路由分发"
AUTH->>SEC : "验证用户名/密码"
SEC->>DB : "查询用户并比对哈希"
DB-->>SEC : "用户对象"
SEC-->>AUTH : "生成JWT"
AUTH-->>FE : "返回access_token"
图表来源
- backend/app/main.py
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/models/models.py
详细组件分析
身份认证与授权机制
- OAuth2 密码流：通过 OAuth2PasswordBearer 获取令牌 URL，实现标准授权流程
- JWT 令牌：包含过期时间与主体标识，使用 HS256 算法签名
- 密码存储：bcrypt 哈希，不可逆存储
- 当前用户解析：从 JWT 解析 sub 字段，查询用户并校验是否启用
- 角色权限：提供管理员与经理级权限校验，未授权请求返回 403
flowchart TD
Start(["开始"]) --> Parse["解析JWT载荷"]
Parse --> Valid{"载荷有效？"}
Valid -- 否 --> Err["抛出401凭据无效"]
Valid -- 是 --> LoadUser["根据ID查询用户"]
LoadUser --> Found{"找到用户？"}
Found -- 否 --> Err
Found -- 是 --> Active{"用户启用？"}
Active -- 否 --> Disabled["抛出400用户禁用"]
Active -- 是 --> Role{"角色校验"}
Role --> End(["结束"])
图表来源
章节来源
JWT 令牌管理
- 令牌签发：携带 exp 与 sub，使用 SECRET_KEY 和 ALGORITHM
- 令牌过期：默认 8 小时
- 令牌使用：Bearer 方式在 Authorization 头传递
- 令牌刷新：当前实现未内置刷新逻辑，建议生产环境引入刷新令牌与黑名单
章节来源
密码加密存储
- bcrypt 哈希：注册与登录均基于 bcrypt 校验
- 密码长度与复杂度：契约层限制最小长度，建议结合业务策略增加复杂度要求
章节来源
会话安全管理
- 会话依赖：当前实现基于 JWT，无服务端会话存储
- 令牌撤销：未实现黑名单机制，建议引入 Redis/JWT 黑名单或缩短令牌有效期
- 传输安全：建议强制 HTTPS，避免明文传输
章节来源
网络安全配置
- CORS：允许指定来源、凭证、方法与头
- 健康检查：提供 /health 接口便于探活
- 异常处理：全局捕获 HTTP 与验证异常并记录日志
章节来源
数据安全保护
- 数据模型：用户表包含密码哈希、角色、启用状态等字段
- 数据契约：用户登录、注册、令牌、用户响应等模型定义
- 建议：对敏感字段进行脱敏展示；数据库连接使用 SSL；对日志中敏感字段进行脱敏
章节来源
审计日志、违规检测与事件响应
- 日志：控制台 INFO 级别输出，文件 DEBUG 级别轮转，错误单独 ERROR 文件
- 建议：接入集中化日志系统（如 ELK/Sentry），设置告警阈值；对登录失败、权限拒绝、敏感操作进行标记与告警
章节来源
漏洞扫描与补丁管理
- 建议：定期运行依赖扫描（pip-audit、safety、npm audit 等），修复高危与严重漏洞
- 版本管理：固定依赖版本，启用自动安全更新与 PR 审查
- 生产部署：仅在受信网络与 HTTPS 下暴露 API
章节来源
合规性检查清单
- 配置项：密钥、算法、CORS 白名单、分页上限、调试开关
- 数据保护：密码哈希、传输加密、日志脱敏
- 权限治理：角色枚举、权限校验、最小权限
- 运维：健康检查、异常处理、日志轮转
章节来源
用户权限管理与角色分配
- 角色字段：用户表 role 字段
- 权限校验：管理员与经理级权限校验函数
- 最小权限：建议在路由与服务层进一步细化资源级权限
章节来源
依赖关系分析
graph LR
CFG["core/config.py"] --> SEC["core/security.py"]
CFG --> MAIN["app/main.py"]
SEC --> AUTH["api/v1/auth.py"]
AUTH --> MODELS["models/models.py"]
MODELS --> SCHEMAS["schemas/schemas.py"]
MAIN --> LOG["core/logging_config.py"]
图表来源
- backend/app/core/config.py
- backend/app/core/security.py
- backend/app/main.py
- backend/app/api/v1/auth.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
- backend/app/core/logging_config.py
章节来源
- backend/app/core/config.py
- backend/app/core/security.py
- backend/app/main.py
- backend/app/api/v1/auth.py
- backend/app/models/models.py
- backend/app/schemas/schemas.py
- backend/app/core/logging_config.py
性能与安全特性
- 异步数据库：使用异步 SQLAlchemy，提升并发性能
- JWT 无状态：减少服务端会话开销
- CORS 精准白名单：降低跨域攻击面
- 日志分级：区分开发与生产日志级别，避免敏感信息泄露
章节来源
故障排查指南
- 登录失败：检查用户名/密码是否匹配，确认用户启用状态
- CORS 问题：确认前端 Origin 是否在 CORS_ORIGINS 列表
- 令牌无效：确认 SECRET_KEY 一致、算法匹配、未过期
- 日志定位：查看应用日志与错误日志文件，定位异常堆栈
章节来源
- backend/app/api/v1/auth.py
- backend/app/core/security.py
- backend/app/main.py
- backend/app/core/logging_config.py
- test_frontend_connection.py
- backend/test_api.py
结论
本系统在认证与授权、日志与异常处理方面具备良好基础，建议在生产环境中补充 HTTPS、令牌黑名单、最小权限细化、集中化日志与告警、漏洞扫描与补丁管理等措施，以满足更严格的合规与安全要求。
附录
- 数据库 ER 设计参考：用户与科室、员工、考核、指标、工资、计划、菜单、模板等实体关系
- 配置示例：环境变量示例文件，包含数据库、JWT 密钥与调试开关
章节来源