# 安全合规

<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)