# 安全考虑

<cite>
**本文档中引用的文件**  
- [aes_ecb.go](file://utility/verify/aes_ecb.go)
- [md5.go](file://utility/verify/md5.go)
- [mfa.go](file://utility/mfa/mfa.go)
- [auth.go](file://internal/middleware/auth.go)
- [sys_user.go](file://internal/model/sys_user.go)
- [sys_user.go](file://internal/service/sys_user.go)
- [sys_auth.go](file://internal/service/sys_auth.go)
- [sys_casbin.go](file://internal/service/sys_casbin.go)
- [v_1_sys_user.go](file://internal/dao/v_1_sys_user.go)
- [v_1_sys_casbin_rule.go](file://internal/dao/v_1_sys_casbin_rule.go)
- [rbac_model.conf](file://resource/casbin/rbac_model.conf)
- [JD_COOKIE_REFACTOR_REPORT.md](file://JD_COOKIE_REFACTOR_REPORT.md) - *新增：京东Cookie管理模块重构设计文档*
</cite>

## 更新摘要
**变更内容**  
- 新增京东Cookie管理模块的安全设计说明
- 在“常见安全威胁与缓解措施”部分补充了针对Cookie管理的安全策略
- 更新文档引用文件列表，新增`JD_COOKIE_REFACTOR_REPORT.md`作为参考
- 所有内容已根据最新代码状态进行验证，确保与实现一致

## 目录
1. [引言](#引言)
2. [系统安全架构概述](#系统安全架构概述)
3. [身份验证机制](#身份验证机制)
4. [基于JWT的认证系统](#基于jwt的认证系统)
5. [基于Casbin的RBAC授权](#基于casbin的rbac授权)
6. [TOTP双因素认证(MFA)](#totp双因素认证mfa)
7. [数据加密机制](#数据加密机制)
8. [会话管理与令牌续签](#会话管理与令牌续签)
9. [安全最佳实践](#安全最佳实践)
10. [常见安全威胁与缓解措施](#常见安全威胁与缓解措施)
11. [开发者安全编码指南](#开发者安全编码指南)
12. [结论](#结论)

## 引言
本文档全面阐述了kami_backend系统的安全架构设计，涵盖多层安全机制，包括基于JWT的身份认证、基于Casbin的RBAC权限控制、TOTP双因素认证以及数据加密技术。文档详细说明了各安全组件的实现原理、配置方式和使用模式，并提供安全最佳实践和漏洞防范指南。

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [sys_user.go](file://internal/model/sys_user.go#L1-L92)

## 系统安全架构概述
kami_backend系统采用分层安全架构，包含身份验证、授权、会话管理和数据保护等多个安全层面。系统通过JWT实现无状态认证，利用Casbin框架实现灵活的基于角色的访问控制(RBAC)，并集成TOTP双因素认证增强账户安全性。同时，系统使用AES和MD5算法对敏感数据进行加密保护。

```mermaid
graph TB
subgraph "安全架构"
Auth[身份验证]
Authorization[授权]
Session[会话管理]
Encryption[数据加密]
end
Auth --> |JWT| Authorization
Authorization --> |Casbin| Session
Session --> |Token| Encryption
Encryption --> |AES/MD5| Auth
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [sys_casbin.go](file://internal/service/sys_casbin.go#L1-L50)

## 身份验证机制
系统实现了多模式身份验证机制，支持标准登录认证和iframe嵌入式认证两种模式。通过中间件统一处理身份验证逻辑，确保所有受保护的API端点都经过严格的身份验证。

### 认证流程
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Middleware as "认证中间件"
participant Token as "令牌服务"
participant Redis as "Redis缓存"
Client->>Middleware : 发送请求(含Token)
Middleware->>Token : 提取请求Token
alt Token不存在
Middleware-->>Client : 返回未授权错误
else Token存在
Middleware->>Token : 解析用户Token
Token->>Redis : 验证Token有效性
Redis-->>Token : 返回验证结果
alt Token有效
Token->>Middleware : 返回用户信息
Middleware->>Token : 续签Token
Token-->>Middleware : 返回新Token
Middleware->>Client : 设置refresh-token头
Middleware->>Client : 允许请求继续
else Token无效
Middleware-->>Client : 返回Token失效错误
end
end
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L50-L100)
- [token.go](file://utility/token/user_token.go#L1-L50)

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)

## 基于JWT的认证系统
系统采用JWT(JSON Web Token)实现无状态认证机制。用户登录成功后，服务器生成包含用户信息的JWT令牌，客户端在后续请求中携带该令牌进行身份验证。

### JWT实现细节
```mermaid
flowchart TD
Start([用户登录]) --> ValidateCredentials["验证凭据"]
ValidateCredentials --> CredentialsValid{"凭据有效?"}
CredentialsValid --> |否| ReturnError["返回认证失败"]
CredentialsValid --> |是| GenerateToken["生成JWT令牌"]
GenerateToken --> StoreInRedis["将Token存储到Redis"]
StoreInRedis --> ReturnToken["返回Token给客户端"]
ReturnToken --> ClientRequest["客户端后续请求"]
ClientRequest --> ExtractToken["提取请求中的Token"]
ExtractToken --> VerifyToken["验证Token有效性"]
VerifyToken --> TokenValid{"Token有效?"}
TokenValid --> |否| ReturnUnauthorized["返回未授权"]
TokenValid --> |是| RefreshToken["续签Token"]
RefreshToken --> ContinueRequest["继续处理请求"]
ReturnError --> End([结束])
ReturnUnauthorized --> End
ContinueRequest --> End
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L50-L100)
- [user_token.go](file://utility/token/user_token.go#L1-L50)

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [user_token.go](file://utility/token/user_token.go#L1-L50)

## 基于Casbin的RBAC授权
系统采用Casbin框架实现基于角色的访问控制(RBAC)。通过定义角色、权限和资源之间的关系，实现细粒度的权限控制。

### RBAC模型配置
```conf
# rbac_model.conf
[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
```

### 权限检查流程
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Middleware as "中间件"
participant Casbin as "Casbin引擎"
participant Policy as "策略存储"
Client->>Middleware : 发送受保护的请求
Middleware->>Casbin : 获取用户角色
Casbin->>Policy : 加载用户权限策略
Policy-->>Casbin : 返回策略规则
Casbin->>Casbin : 构建权限检查请求
Casbin->>Casbin : 执行权限匹配
alt 有权限
Casbin-->>Middleware : 返回允许访问
Middleware->>Client : 继续处理请求
else 无权限
Casbin-->>Middleware : 返回拒绝访问
Middleware->>Client : 返回403错误
end
```

**Diagram sources**
- [rbac_model.conf](file://resource/casbin/rbac_model.conf#L1-L15)
- [sys_casbin.go](file://internal/service/sys_casbin.go#L1-L50)
- [v_1_sys_casbin_rule.go](file://internal/dao/v_1_sys_casbin_rule.go#L1-L28)

**Section sources**
- [sys_casbin.go](file://internal/service/sys_casbin.go#L1-L50)
- [v_1_sys_casbin_rule.go](file://internal/dao/v_1_sys_casbin_rule.go#L1-L28)

## TOTP双因素认证(MFA)
系统集成了TOTP(Time-based One-Time Password)双因素认证机制，通过Google Authenticator等认证应用生成动态验证码，增强账户安全性。

### MFA实现流程
```mermaid
sequenceDiagram
participant User as "用户"
participant Server as "服务器"
participant Authenticator as "认证应用"
User->>Server : 请求启用MFA
Server->>Server : 生成密钥和二维码
Server-->>User : 返回二维码和密钥
User->>Authenticator : 扫描二维码
Authenticator->>Authenticator : 生成动态验证码
User->>Server : 提交验证码和密码
Server->>Server : 验证TOTP码
alt 验证成功
Server->>Server : 保存MFA设置
Server-->>User : MFA启用成功
else 验证失败
Server-->>User : 返回验证失败
end
```

### MFA状态检查
```mermaid
flowchart TD
Start([获取MFA状态]) --> GetUser["获取当前用户信息"]
GetUser --> HasSecret{"已设置密钥?"}
HasSecret --> |是| SetStatus["状态: 已启用"]
HasSecret --> |否| GenerateQR["生成二维码"]
GenerateQR --> GetOtp["调用GetOtp生成密钥"]
GetOtp --> StoreQR["存储二维码信息"]
StoreQR --> SetStatus["状态: 未启用"]
SetStatus --> ReturnResult["返回状态和二维码"]
ReturnResult --> End([结束])
```

**Diagram sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go#L1-L37)
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)

**Section sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go#L1-L37)
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)

## 数据加密机制
系统采用AES ECB模式和MD5哈希算法对敏感数据进行加密保护，确保数据在传输和存储过程中的安全性。

### AES ECB加密实现
```mermaid
flowchart TD
Start([明文数据]) --> Padding["PKCS7填充"]
Padding --> CreateCipher["创建AES密码器"]
CreateCipher --> Encrypt["CBC模式加密"]
Encrypt --> EncodeBase64["Base64编码"]
EncodeBase64 --> Ciphertext["密文输出"]
Ciphertext --> End([完成])
subgraph "解密流程"
Ciphertext2["密文输入"] --> DecodeBase64["Base64解码"]
DecodeBase64 --> CreateCipher2["创建AES密码器"]
CreateCipher2 --> Decrypt["CBC模式解密"]
Decrypt --> Unpadding["PKCS7反填充"]
Unpadding --> Plaintext["明文输出"]
end
```

### MD5哈希实现
```mermaid
flowchart TD
Start([输入字符串]) --> CreateHash["创建MD5哈希器"]
CreateHash --> WriteData["写入数据"]
WriteData --> ComputeHash["计算哈希值"]
ComputeHash --> EncodeHex["十六进制编码"]
EncodeHex --> Result["返回MD5值"]
Result --> End([完成])
subgraph "大小写转换"
Result --> ToLower["转换为小写"]
Result --> ToUpper["转换为大写"]
end
```

**Diagram sources**
- [aes_ecb.go](file://utility/verify/aes_ecb.go#L1-L91)
- [md5.go](file://utility/verify/md5.go#L1-L32)

**Section sources**
- [aes_ecb.go](file://utility/verify/aes_ecb.go#L1-L91)
- [md5.go](file://utility/verify/md5.go#L1-L32)

## 会话管理与令牌续签
系统实现了安全的会话管理机制，通过Redis存储会话信息，并支持令牌自动续签功能，平衡安全性和用户体验。

### 会话管理流程
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Server as "服务器"
participant Redis as "Redis"
Client->>Server : 登录请求
Server->>Server : 验证凭据
alt 验证成功
Server->>Server : 生成JWT令牌
Server->>Redis : 存储会话信息
Redis-->>Server : 存储成功
Server-->>Client : 返回令牌
else 验证失败
Server-->>Client : 返回错误
end
Client->>Server : 后续请求(含令牌)
Server->>Redis : 验证令牌有效性
alt 令牌有效
Server->>Server : 续签令牌(如需要)
Server->>Redis : 更新会话
Server-->>Client : 处理请求
else 令牌无效
Server-->>Client : 返回401错误
end
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L50-L100)
- [user_token.go](file://utility/token/user_token.go#L1-L50)
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [user_token.go](file://utility/token/user_token.go#L1-L50)

## 安全最佳实践
### 密码策略
- 密码长度至少8位
- 必须包含大小写字母、数字和特殊字符
- 定期强制更换密码
- 禁止使用常见弱密码

### 令牌管理
- JWT令牌设置合理的过期时间
- 实现令牌黑名单机制
- 支持令牌续签功能
- 敏感操作要求重新认证

### 安全头配置
- 启用HTTPS强制加密
- 配置CSP(Content Security Policy)
- 设置X-Content-Type-Options头
- 启用X-Frame-Options防止点击劫持

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [user_token.go](file://utility/token/user_token.go#L1-L50)

## 常见安全威胁与缓解措施
### 威胁类型与应对
| 威胁类型 | 风险描述 | 缓解措施 |
|---------|--------|---------|
| 暴力破解 | 攻击者尝试大量密码组合 | 账号锁定机制、验证码、登录失败限制 |
| 会话劫持 | 攻击者窃取用户会话令牌 | HTTPS传输、HttpOnly Cookie、令牌续签 |
| XSS攻击 | 跨站脚本注入 | 输入验证、输出编码、CSP策略 |
| CSRF攻击 | 跨站请求伪造 | CSRF令牌、SameSite Cookie |
| SQL注入 | 恶意SQL语句执行 | 参数化查询、输入验证 |
| 权限提升 | 用户获取未授权权限 | RBAC严格控制、最小权限原则 |
| Cookie滥用 | 京东Cookie被非法使用或泄露 | 严格的Cookie存储加密、访问权限控制、定期轮换机制、操作审计日志 |

### 安全监控
- 记录所有登录尝试
- 监控异常登录行为
- 定期安全审计
- 实时告警机制
- 京东Cookie操作的完整审计跟踪

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [errHandler.go](file://internal/errHandler/handler.go#L1-L50)
- [JD_COOKIE_REFACTOR_REPORT.md](file://JD_COOKIE_REFACTOR_REPORT.md) - *新增安全措施参考*

## 开发者安全编码指南
### 输入验证
- 对所有用户输入进行严格验证
- 使用白名单验证机制
- 防止SQL注入和XSS攻击

### 错误处理
- 不泄露敏感信息到错误消息
- 统一错误处理机制
- 详细日志记录但不暴露给用户

### 权限检查
- 所有API端点都应进行权限验证
- 实现最小权限原则
- 敏感操作需要二次确认

### 数据保护
- 敏感数据加密存储
- 避免在日志中记录敏感信息
- 定期轮换加密密钥
- 京东Cookie等敏感凭证必须使用AES加密存储

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)
- [verify.go](file://utility/verify/aes_ecb.go#L1-L91)

## 结论
kami_backend系统通过多层次的安全机制，构建了完整的安全防护体系。基于JWT的认证、Casbin的RBAC授权、TOTP双因素认证和数据加密技术共同保障了系统的安全性。建议持续关注安全威胁变化，定期进行安全审计，不断优化安全策略，确保系统长期安全稳定运行。