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

10 KiB
Raw Blame History

登录认证

**本文档引用文件** - [sys_user_login.go](file://api/sys_user_login/v1/sys_user_login.go) - [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go) - [sysAuth.go](file://internal/logic/sys_auth/sysAuth.go) - [aes_ecb.go](file://utility/verify/aes_ecb.go) - [md5.go](file://utility/verify/md5.go) - [rate.go](file://utility/limiter/rate.go) - [auth.go](file://internal/middleware/auth.go)

目录

  1. 简介
  2. 登录接口实现流程
  3. 密码加密存储机制
  4. 认证失败处理策略
  5. 参数验证与安全校验
  6. 错误响应码设计
  7. 安全防护措施
  8. 使用示例与集成指南
  9. 常见问题诊断

简介

本文档详细解析kami_backend系统的用户登录认证机制。系统采用多层安全验证机制，包括用户名密码验证、验证码校验、TOTP双因素认证以及基于AES-CBC和MD5的加密算法保护用户凭证安全。同时，系统实现了基于内存和Redis的限流机制，有效防止暴力破解攻击。

Section sources

登录接口实现流程

用户登录接口通过多步骤验证确保安全性。首先验证图形验证码，然后查询用户信息并验证密码，接着检查双因素认证状态，最后生成访问令牌。

sequenceDiagram
participant 客户端 as 客户端
participant 控制器 as sys_user_login控制器
participant 服务层 as SysUserService
participant 验证码服务 as CaptchaService
participant 令牌服务 as TokenService
客户端->>控制器 : POST /user/login (用户名,密码,验证码)
控制器->>验证码服务 : 验证验证码(VerifyKey,VerifyCode)
验证码服务-->>控制器 : 验证结果
alt 验证失败
控制器->>客户端 : 返回验证码错误
else 验证成功
控制器->>服务层 : 查询用户(用户名,密码)
服务层-->>控制器 : 用户信息
alt 用户不存在或密码错误
控制器->>客户端 : 返回用户名或密码错误
else 用户存在且密码正确
控制器->>控制器 : 检查TOTP状态
alt 需要TOTP验证
控制器->>控制器 : 验证TOTP码
alt TOTP验证失败
控制器->>客户端 : 返回二步验证错误
else TOTP验证成功
控制器->>令牌服务 : 生成用户令牌
令牌服务-->>控制器 : 令牌字符串
控制器->>客户端 : 返回令牌
end
else 不需要TOTP验证
控制器->>令牌服务 : 生成用户令牌
令牌服务-->>控制器 : 令牌字符串
控制器->>客户端 : 返回令牌
end
end
end

Diagram sources

Section sources

密码加密存储机制

系统采用MD5哈希算法对用户密码进行加密存储。在密码验证过程中，使用MD5算法对输入密码进行哈希处理，然后与数据库中存储的哈希值进行比对。

flowchart TD
A[用户输入密码] --> B[MD5哈希处理]
B --> C[生成32位小写十六进制字符串]
C --> D[与数据库存储的哈希值比对]
D --> E{比对结果}
E --> |匹配| F[密码验证成功]
E --> |不匹配| G[密码验证失败]

Diagram sources

Section sources

认证失败处理策略

系统对认证失败情况进行了分类处理，每种情况返回特定的错误码和消息，便于前端进行针对性处理。

flowchart TD
A[认证失败] --> B{失败类型}
B --> |验证码错误| C[返回CodeNotAuthorized]
B --> |用户名或密码错误| D[返回ErrLoginPasswordOrUserError]
B --> |TOTP验证错误| E[返回CodeValidationFailed]
B --> |用户被禁用| F[返回CodeNotAuthorized]
B --> |生成令牌失败| G[返回CodeInternalError]
C --> H[提示: 验证码错误]
D --> I[提示: 用户名或密码错误]
E --> J[提示: 二步验证错误]
F --> K[提示: 用户已禁用]
G --> L[提示: 系统内部错误]

Diagram sources

Section sources

参数验证与安全校验

登录接口对所有输入参数进行严格验证，确保数据完整性和安全性。

请求参数验证

参数名 类型 必填 验证规则 错误提示
username 字符串 是 非空 用户名不能为空
password 字符串 是 非空 密码不能为空
verifyCode 字符串 是 非空 验证码不能为空
verifyKey 字符串 是 非空 验证秘钥不能为空
totpCode 字符串 否 - -

安全校验流程

flowchart TD
A[接收登录请求] --> B[验证参数完整性]
B --> C[校验验证码]
C --> D[查询用户信息]
D --> E[验证密码]
E --> F[检查用户状态]
F --> G[验证TOTP(如启用)]
G --> H[生成访问令牌]
H --> I[返回成功响应]
C --> |验证码错误| J[返回错误响应]
D --> |用户不存在| J
E --> |密码错误| J
F --> |用户被禁用| J
G --> |TOTP错误| J
H --> |生成失败| J

Diagram sources

Section sources

错误响应码设计

系统采用标准化的错误响应码体系，便于客户端进行错误处理。

错误码 HTTP状态码 错误类型 说明
401 401 认证失败 验证码错误或用户被禁用
400 400 输入验证失败 用户名或密码错误
400 400 验证失败 TOTP二步验证错误
500 500 内部错误 生成令牌失败
401 401 令牌错误 令牌失效或格式错误

Section sources

安全防护措施

系统实现了多层次的安全防护机制，包括加密算法和限流策略。

加密算法应用

系统使用AES-CBC模式进行数据加密传输，确保敏感信息在传输过程中的安全性。

classDiagram
class AesCBCUtil {
+aesCBCEncrypt(plaintext, key, iv) byte[]
+aesCBCDecrypt(ciphertext, key, iv) byte[]
+AesCBCEncryptWithBase64(text, key, iv) string
+AesCBCStdDecryptWithBase64(text, key, iv) byte[]
+AesCBCURLDecryptWithBase64(text, key, iv) byte[]
-paddingPKCS7(plaintext, blockSize) byte[]
-unPaddingPKCS7(s) byte[]
}
class Md5Util {
+GetMD5LOWER(s) string
+GetMD5Upper(s) string
+MapToString(m) string
}
AesCBCUtil --> Md5Util : "使用"

Diagram sources

限流机制

系统实现了基于内存的简单限流器，防止暴力破解攻击。

flowchart TD
A[接收请求] --> B[生成限流键]
B --> C[检查当前请求数]
C --> D{超过阈值?}
D --> |是| E[拒绝请求]
D --> |否| F[记录请求时间]
F --> G[允许请求]
C --> H[清理过期记录]
H --> C
classDef default fill:#f9f,stroke:#333,stroke-width:1px;
class A,B,C,D,E,F,G,H default;

Diagram sources

Section sources

使用示例与集成指南

登录请求示例

POST /user/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password123",
  "verifyCode": "abcd",
  "verifyKey": "captcha_123456",
  "totpCode": "123456"
}

成功响应

{
  "code": 0,
  "message": "OK",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

集成注意事项

  1. 必须先获取验证码并传递verifyKey
  2. 生产环境必须启用TOTP双因素认证
  3. 令牌需要在后续请求的Authorization头中传递
  4. 实现自动刷新令牌机制以应对令牌过期

Section sources

常见问题诊断

常见问题及解决方案

问题现象 可能原因 解决方案
验证码错误 验证码过期或输入错误 刷新验证码重新输入
用户名或密码错误 凭证不匹配或用户不存在 检查用户名密码，确认用户状态
二步验证错误 TOTP码错误或未同步 检查TOTP应用时间同步
用户已禁用 账户被管理员禁用 联系管理员启用账户
生成令牌失败 系统内部错误 检查服务状态，重试登录

诊断流程

flowchart TD
A[登录失败] --> B{错误类型}
B --> |验证码错误| C[检查验证码有效期]
B --> |用户名密码错误| D[确认用户状态和凭证]
B --> |TOTP错误| E[检查TOTP应用和时间同步]
B --> |用户禁用| F[联系管理员]
B --> |内部错误| G[检查服务日志]
C --> H[重新获取验证码]
D --> I[重置密码或创建用户]
E --> J[重新配置TOTP]
F --> K[等待管理员处理]
G --> L[重启服务或联系技术支持]

Diagram sources

Section sources