danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/业务逻辑层架构/系统认证逻辑/用户认证管理/用户认证管理.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

14 KiB
Raw Blame History

用户认证管理

**本文档引用的文件** - [auth.go](file://internal/middleware/auth.go) - [user_token.go](file://utility/token/user_token.go) - [mfa.go](file://utility/mfa/mfa.go) - [sys_user_login.go](file://api/sys_user_login/v1/sys_user_login.go) - [totp.go](file://api/sysUser/v1/totp.go) - [sys_user.go](file://internal/model/sys_user.go) - [sys_user.go](file://internal/logic/sys_user/sys_user.go) - [sys_user.go](file://internal/service/sys_user.go) - [v_1_sys_user.go](file://internal/dao/v_1_sys_user.go) - [v_1_sys_user.go](file://internal/model/entity/v_1_sys_user.go) - [sysUser.go](file://internal/controller/sysUser/sysUser.go) - [sys_user_login.go](file://internal/controller/sys_user_login/sys_user_login.go) - [base_user_info.go](file://internal/logic/base_user_info/user_info.go) - [sys_auth.go](file://internal/logic/sys_auth/sysAuth.go)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概述
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录（如有必要）

简介

本文档全面描述了kami_backend系统的用户认证管理机制，包括用户登录、登出、会话管理、双因素认证（TOTP）、身份验证令牌的生成与验证、登录日志记录和安全审计等核心功能。文档详细阐述了系统如何通过JWT令牌、Redis缓存和中间件实现安全的用户认证流程，并提供了用户认证的最佳实践和常见问题的解决方案。

项目结构

kami_backend的用户认证相关代码分布在多个目录中，主要集中在api、internal和utility目录下。认证逻辑主要由internal/controller/sys_user_login和internal/controller/sysUser控制器处理，业务逻辑在internal/logic/sys_user中实现，服务接口定义在internal/service/sys_user.go中，而工具函数则位于utility/token和utility/mfa包中。

graph TD
subgraph "API层"
A[sys_user_login/v1/sys_user_login.go]
B[sysUser/v1/totp.go]
end
subgraph "控制器层"
C[sys_user_login/sys_user_login.go]
D[sysUser/sysUser.go]
end
subgraph "业务逻辑层"
E[sys_user/sys_user.go]
F[base_user_info/user_info.go]
G[sys_auth/sysAuth.go]
end
subgraph "服务层"
H[sys_user.go]
end
subgraph "数据访问层"
I[v_1_sys_user.go]
end
subgraph "工具层"
J[user_token.go]
K[mfa.go]
L[auth.go]
end
A --> C
B --> D
C --> E
D --> E
C --> F
D --> G
E --> H
F --> H
G --> H
H --> I
E --> J
E --> K
C --> L
D --> L

图表来源

章节来源

核心组件

用户认证系统的核心组件包括：用户登录请求处理、JWT令牌生成与验证、双因素认证（TOTP）集成、会话管理、登录日志记录和权限验证中间件。这些组件协同工作，确保系统的安全性和可靠性。

章节来源

架构概述

kami_backend的用户认证架构采用分层设计，从API接口到数据访问层，每一层都有明确的职责。认证流程始于API层的登录请求，经过控制器层的处理，调用业务逻辑层进行用户验证和令牌生成，最终通过数据访问层与数据库交互。

sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Logic as "业务逻辑"
participant Service as "服务"
participant DAO as "数据访问"
participant DB as "数据库"
participant Redis as "Redis缓存"
Client->>API : 发送登录请求
API->>Controller : 调用UserLogin
Controller->>Logic : 验证验证码
Logic->>Logic : 验证用户名密码
alt 启用TOTP
Logic->>Logic : 验证TOTP验证码
end
Logic->>Service : 生成JWT令牌
Service->>Redis : 存储令牌
Service->>DB : 记录登录日志
Service-->>Controller : 返回令牌
Controller-->>API : 返回响应
API-->>Client : 返回登录结果

图表来源

详细组件分析

用户登录与认证分析

用户登录流程包括验证码验证、用户名密码验证、双因素认证（如果启用）和JWT令牌生成。系统使用中间件进行请求认证，确保只有经过验证的用户才能访问受保护的资源。

用户登录流程

flowchart TD
Start([开始]) --> ValidateCaptcha["验证验证码"]
ValidateCaptcha --> CaptchaValid{"验证码有效?"}
CaptchaValid --> |否| ReturnCaptchaError["返回验证码错误"]
CaptchaValid --> |是| ValidateCredentials["验证用户名密码"]
ValidateCredentials --> CredentialsValid{"凭证有效?"}
CredentialsValid --> |否| ReturnAuthError["返回认证错误"]
CredentialsValid --> |是| CheckTOTP["检查TOTP是否启用"]
CheckTOTP --> TOTPEnabled{"TOTP启用?"}
TOTPEnabled --> |否| GenerateToken["生成JWT令牌"]
TOTPEnabled --> |是| ValidateTOTP["验证TOTP验证码"]
ValidateTOTP --> TOTPValid{"TOTP有效?"}
TOTPValid --> |否| ReturnTOTPError["返回TOTP错误"]
TOTPValid --> |是| GenerateToken
GenerateToken --> StoreToken["存储令牌到Redis"]
StoreToken --> LogLogin["记录登录日志"]
LogLogin --> ReturnToken["返回令牌"]
ReturnCaptchaError --> End([结束])
ReturnAuthError --> End
ReturnTOTPError --> End
ReturnToken --> End

图表来源

章节来源

双因素认证（TOTP）分析

系统集成了基于时间的一次性密码（TOTP）作为双因素认证机制。用户可以启用、禁用和重置TOTP设置，系统通过QR码提供配置信息。

TOTP配置流程

classDiagram
class Otp {
+Secret string
+QrImage string
+Key string
}
class Mfa {
+GetOtp(userId, username, key, secret) Otp
+ValidCode(code, secret) bool
}
class TotpController {
-userService UserService
+TotpStatusGet(req) Res
+TotpSet(req) Res
+TotpImageGet(req) Res
+TotpReset(req) Res
}
class UserService {
+SetTotp(ctx, data, key, secret) error
+ResetTotp(ctx, data) error
}
Mfa --> Otp : "创建"
TotpController --> Mfa : "使用"
TotpController --> UserService : "调用"
UserService --> Mfa : "验证"

图表来源

章节来源

会话管理分析

系统使用JWT令牌进行会话管理，令牌存储在Redis中以实现分布式会话。中间件负责验证令牌的有效性，并在必要时进行令牌刷新。

会话管理流程

sequenceDiagram
participant Client as "客户端"
participant Middleware as "认证中间件"
participant Token as "令牌服务"
participant Redis as "Redis"
Client->>Middleware : 发送请求
Middleware->>Token : 提取令牌
Token->>Redis : 检查令牌是否存在
Redis-->>Token : 返回检查结果
alt 令牌有效
Token->>Token : 验证JWT签名
Token->>Token : 检查过期时间
alt 需要刷新
Token->>Token : 生成新令牌
Token->>Redis : 存储新令牌
Token-->>Middleware : 返回刷新令牌
end
Middleware->>Client : 继续处理请求
else 令牌无效
Middleware->>Client : 返回未授权错误
end

图表来源

章节来源

依赖分析

用户认证系统涉及多个组件之间的依赖关系，从API接口到数据访问层，形成了一个完整的认证链条。

graph TD
A[UserLoginReq] --> B[ControllerV1.UserLogin]
B --> C[service.Captcha.VerifyString]
B --> D[service.SysUser.GetAdminUserByUsernamePassword]
D --> E[service.SysUser.GetUserByUsername]
E --> F[dao.V1SysUser.Scan]
B --> G[mfa.ValidCode]
G --> H[gotp.NewDefaultTOTP]
B --> I[token.GenerateUserToken]
I --> J[token.genToken]
I --> K[cache.NewCache.Set]
L[LoginOrIframeAuth] --> M[whiteListAuth]
L --> N[loginAuth]
L --> O[iFrameAuth]
N --> P[token.ParseUserToken]
N --> Q[token.GetTokenFromRedis]
N --> R[token.RefreshUserToken]
S[ControllerV1.UserLoginOut] --> T[token.ParseUserToken]
S --> U[token.DeleteTokenFromRedis]
V[ControllerV1.TotpSet] --> W[service.SysAuth.LoginOnlyLogin]
V --> X[utils.EncryptPassword]
V --> Y[mfa.ValidCode]
V --> Z[service.SysUser.SetTotp]
Z --> AA[mfa.GetOtp]
Z --> AB[dao.V1SysUser.Update]

图表来源

章节来源

性能考虑

用户认证系统的性能主要受以下几个因素影响：

  1. 数据库查询性能：用户信息查询和登录日志记录需要优化数据库索引。
  2. Redis缓存性能：令牌的存储和检索依赖Redis的性能，需要确保Redis集群的高可用性。
  3. 密码哈希计算：密码加密使用双重MD5哈希，虽然安全但计算成本较高。
  4. JWT签名验证：每次请求都需要验证JWT签名，增加了CPU开销。

建议的优化措施包括：

  • 为用户表的用户名字段创建唯一索引
  • 使用连接池管理数据库连接
  • 监控Redis的内存使用和响应时间
  • 考虑使用更高效的密码哈希算法（如bcrypt）

故障排除指南

常见认证问题及解决方案

  1. 登录失败

    • 检查用户名和密码是否正确
    • 确认用户账户状态是否正常（未被禁用）
    • 如果启用了TOTP，确保输入了正确的验证码

  2. 令牌失效

    • 检查令牌是否过期
    • 确认Redis中是否存在对应的令牌
    • 检查时钟同步，TOTP对时间敏感

  3. TOTP配置问题

    • 确保手机时间与服务器时间同步
    • 重新生成QR码并重新扫描
    • 检查密钥是否正确复制

  4. 会话中断

    • 检查Redis连接是否正常
    • 确认令牌刷新逻辑是否正常工作
    • 查看系统日志中的错误信息

章节来源

结论

kami_backend的用户认证管理系统设计完善，采用了现代的安全实践，包括JWT令牌、Redis会话存储和双因素认证。系统架构清晰，各组件职责明确，便于维护和扩展。通过遵循本文档中的最佳实践，可以确保系统的安全性和可靠性。

附录

API端点列表

端点 方法 描述
/api/user/login POST 用户登录
/api/user/logout POST 用户登出
/api/user/totp/status GET 获取TOTP状态
/api/user/totp/set POST 设置TOTP
/api/user/totp/image GET 获取TOTP图像
/api/user/totp/reset POST 重置TOTP

配置选项

配置项 描述 默认值
token.timeout 令牌超时时间（秒） 3600
token.maxRefresh 最大刷新时间（秒） 1800
token.cacheModel 缓存模型（memory/redis） redis
token.cacheKey 缓存键前缀 kami_token