kami_backend/.qoder/repowiki/zh/content/安全考虑/安全考虑.md

安全考虑

**本文档中引用的文件** - [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)

目录

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

引言

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

Section sources

• auth.go
• sys_user.go

系统安全架构概述

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

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
• sys_casbin.go

身份验证机制

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

认证流程

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
• token.go

Section sources

• auth.go

基于JWT的认证系统

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

JWT实现细节

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
• user_token.go

Section sources

• auth.go
• user_token.go

基于Casbin的RBAC授权

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

RBAC模型配置

# 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

权限检查流程

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
• sys_casbin.go
• v_1_sys_casbin_rule.go

Section sources

• sys_casbin.go
• v_1_sys_casbin_rule.go

TOTP双因素认证(MFA)

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

MFA实现流程

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状态检查

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
• sysUser_v1_totp_status_get.go
• sysUser_v1_totp_set.go

Section sources

• mfa.go
• sysUser_v1_totp_status_get.go
• sysUser_v1_totp_set.go

数据加密机制

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

AES ECB加密实现

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哈希实现

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
• md5.go

Section sources

• aes_ecb.go
• md5.go

会话管理与令牌续签

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

会话管理流程

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
• user_token.go
• sys_user.go

Section sources

• auth.go
• user_token.go

安全最佳实践

密码策略

• 密码长度至少8位
• 必须包含大小写字母、数字和特殊字符
• 定期强制更换密码
• 禁止使用常见弱密码

令牌管理

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

安全头配置

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

Section sources

• auth.go
• user_token.go

常见安全威胁与缓解措施

威胁类型与应对

威胁类型	风险描述	缓解措施
暴力破解	攻击者尝试大量密码组合	账号锁定机制、验证码、登录失败限制
会话劫持	攻击者窃取用户会话令牌	HTTPS传输、HttpOnly Cookie、令牌续签
XSS攻击	跨站脚本注入	输入验证、输出编码、CSP策略
CSRF攻击	跨站请求伪造	CSRF令牌、SameSite Cookie
SQL注入	恶意SQL语句执行	参数化查询、输入验证
权限提升	用户获取未授权权限	RBAC严格控制、最小权限原则

安全监控

• 记录所有登录尝试
• 监控异常登录行为
• 定期安全审计
• 实时告警机制

Section sources

• auth.go
• errHandler.go

开发者安全编码指南

输入验证

• 对所有用户输入进行严格验证
• 使用白名单验证机制
• 防止SQL注入和XSS攻击

错误处理

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

权限检查

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

数据保护

• 敏感数据加密存储
• 避免在日志中记录敏感信息
• 定期轮换加密密钥

Section sources

• auth.go
• sys_user.go
• verify.go

结论

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