# 登录认证

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

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

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

**Section sources**
- [sys_user_login.go](file://api/sys_user_login/v1/sys_user_login.go#L1-L18)
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

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

```mermaid
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**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

**Section sources**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

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

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

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

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

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

```mermaid
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**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

**Section sources**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

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

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

### 安全校验流程
```mermaid
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**
- [sys_user_login.go](file://api/sys_user_login/v1/sys_user_login.go#L1-L18)
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

**Section sources**
- [sys_user_login.go](file://api/sys_user_login/v1/sys_user_login.go#L1-L18)
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

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

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

**Section sources**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)
- [auth.go](file://internal/middleware/auth.go#L117-L153)

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

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

```mermaid
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**
- [aes_ecb.go](file://utility/verify/aes_ecb.go#L1-L90)
- [md5.go](file://utility/verify/md5.go#L1-L30)

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

```mermaid
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**
- [rate.go](file://utility/limiter/rate.go#L1-L70)

**Section sources**
- [rate.go](file://utility/limiter/rate.go#L1-L70)
- [aes_ecb.go](file://utility/verify/aes_ecb.go#L1-L90)
- [md5.go](file://utility/verify/md5.go#L1-L30)

## 使用示例与集成指南
### 登录请求示例
```json
POST /user/login
Content-Type: application/json

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

### 成功响应
```json
{
  "code": 0,
  "message": "OK",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

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

**Section sources**
- [sys_user_login.go](file://api/sys_user_login/v1/sys_user_login.go#L1-L18)
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

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

### 诊断流程
```mermaid
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**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

**Section sources**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)