提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/部署运维/安全合规.md
+++ b/.qoder/repowiki/zh/content/部署运维/安全合规.md
@@ -0,0 +1,308 @@
+# 安全合规
+
+<cite>
+**本文引用的文件**
+- [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)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与安全特性](#性能与安全特性)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向“医院绩效考核管理系统”的安全与合规落地，聚焦以下方面：
+- 身份认证与授权：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
+
+```mermaid
+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](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [docs/backend.md](file://docs/backend.md#L391-L436)
+- [docs/database.md](file://docs/database.md#L1-L95)
+
+## 核心组件
+- 配置中心：集中管理应用名、版本、调试、API 前缀、数据库连接、JWT 密钥与算法、CORS 白名单、分页参数等
+- 安全模块：OAuth2 密码流、JWT 编解码、bcrypt 密码哈希、当前用户解析、活跃用户校验、管理员/经理权限校验
+- 认证路由：登录、注册、当前用户信息查询
+- 日志模块：按日轮转的多处理器日志，区分应用日志与错误日志
+- 数据模型：用户表含用户名、密码哈希、角色、启用状态等字段
+- 数据契约：用户登录、注册、令牌、用户响应等 Pydantic 模型
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L110)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L65)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
+
+## 架构总览
+系统通过 FastAPI 提供 REST 接口，CORS 中间件允许指定来源访问；认证采用 OAuth2 密码流配合 JWT；密码以 bcrypt 存储；日志统一输出到控制台与文件。
+
+```mermaid
+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](file://backend/app/main.py#L41-L48)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+## 详细组件分析
+
+### 身份认证与授权机制
+- OAuth2 密码流：通过 OAuth2PasswordBearer 获取令牌 URL，实现标准授权流程
+- JWT 令牌：包含过期时间与主体标识，使用 HS256 算法签名
+- 密码存储：bcrypt 哈希，不可逆存储
+- 当前用户解析：从 JWT 解析 sub 字段，查询用户并校验是否启用
+- 角色权限：提供管理员与经理级权限校验，未授权请求返回 403
+
+```mermaid
+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(["结束"])
+```
+
+图表来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L20-L110)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+### JWT 令牌管理
+- 令牌签发：携带 exp 与 sub，使用 SECRET_KEY 和 ALGORITHM
+- 令牌过期：默认 8 小时
+- 令牌使用：Bearer 方式在 Authorization 头传递
+- 令牌刷新：当前实现未内置刷新逻辑，建议生产环境引入刷新令牌与黑名单
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L43)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/.env.example](file://backend/.env.example#L6-L8)
+
+### 密码加密存储
+- bcrypt 哈希：注册与登录均基于 bcrypt 校验
+- 密码长度与复杂度：契约层限制最小长度，建议结合业务策略增加复杂度要求
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L327)
+
+### 会话安全管理
+- 会话依赖：当前实现基于 JWT，无服务端会话存储
+- 令牌撤销：未实现黑名单机制，建议引入 Redis/JWT 黑名单或缩短令牌有效期
+- 传输安全：建议强制 HTTPS，避免明文传输
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L52)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+
+### 网络安全配置
+- CORS：允许指定来源、凭证、方法与头
+- 健康检查：提供 /health 接口便于探活
+- 异常处理：全局捕获 HTTP 与验证异常并记录日志
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L41-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L30)
+- [docs/backend.md](file://docs/backend.md#L372-L389)
+
+### 数据安全保护
+- 数据模型：用户表包含密码哈希、角色、启用状态等字段
+- 数据契约：用户登录、注册、令牌、用户响应等模型定义
+- 建议：对敏感字段进行脱敏展示；数据库连接使用 SSL；对日志中敏感字段进行脱敏
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
+
+### 审计日志、违规检测与事件响应
+- 日志：控制台 INFO 级别输出，文件 DEBUG 级别轮转，错误单独 ERROR 文件
+- 建议：接入集中化日志系统（如 ELK/Sentry），设置告警阈值；对登录失败、权限拒绝、敏感操作进行标记与告警
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L65)
+
+### 漏洞扫描与补丁管理
+- 建议：定期运行依赖扫描（pip-audit、safety、npm audit 等），修复高危与严重漏洞
+- 版本管理：固定依赖版本，启用自动安全更新与 PR 审查
+- 生产部署：仅在受信网络与 HTTPS 下暴露 API
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L83-L92)
+
+### 合规性检查清单
+- 配置项：密钥、算法、CORS 白名单、分页上限、调试开关
+- 数据保护：密码哈希、传输加密、日志脱敏
+- 权限治理：角色枚举、权限校验、最小权限
+- 运维：健康检查、异常处理、日志轮转
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+
+### 用户权限管理与角色分配
+- 角色字段：用户表 role 字段
+- 权限校验：管理员与经理级权限校验函数
+- 最小权限：建议在路由与服务层进一步细化资源级权限
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L252-L252)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
+
+## 依赖关系分析
+```mermaid
+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](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+
+## 性能与安全特性
+- 异步数据库：使用异步 SQLAlchemy，提升并发性能
+- JWT 无状态：减少服务端会话开销
+- CORS 精准白名单：降低跨域攻击面
+- 日志分级：区分开发与生产日志级别，避免敏感信息泄露
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L391-L436)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
+- [backend/app/main.py](file://backend/app/main.py#L41-L48)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L65)
+
+## 故障排查指南
+- 登录失败：检查用户名/密码是否匹配，确认用户启用状态
+- CORS 问题：确认前端 Origin 是否在 CORS_ORIGINS 列表
+- 令牌无效：确认 SECRET_KEY 一致、算法匹配、未过期
+- 日志定位：查看应用日志与错误日志文件，定位异常堆栈
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L25-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L46-L52)
+- [backend/app/main.py](file://backend/app/main.py#L58-L77)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L21)
+- [test_frontend_connection.py](file://test_frontend_connection.py#L38-L74)
+- [backend/test_api.py](file://backend/test_api.py#L5-L32)
+
+## 结论
+本系统在认证与授权、日志与异常处理方面具备良好基础，建议在生产环境中补充 HTTPS、令牌黑名单、最小权限细化、集中化日志与告警、漏洞扫描与补丁管理等措施，以满足更严格的合规与安全要求。
+
+## 附录
+- 数据库 ER 设计参考：用户与科室、员工、考核、指标、工资、计划、菜单、模板等实体关系
+- 配置示例：环境变量示例文件，包含数据库、JWT 密钥与调试开关
+
+章节来源
+- [docs/database.md](file://docs/database.md#L1-L95)
+- [backend/.env.example](file://backend/.env.example#L1-L11)