manta/gofaster/backend/README_AUTH.md

# GoFaster 认证服务

## 概述

GoFaster 认证服务提供了完整的用户身份验证和会话管理功能，包括：

- 用户登录/登出
- 图形验证码生成和验证
- JWT 令牌管理
- 密码错误次数限制和账户锁定
- 用户角色管理

## 主要功能

### 1. 用户认证

- **登录接口**: `POST /api/auth/login`
- **登出接口**: `POST /api/auth/logout`
- **刷新令牌**: `POST /api/auth/refresh`
- **获取用户信息**: `GET /api/auth/userinfo`

### 2. 验证码系统

- **生成验证码**: `GET /api/auth/captcha`
- 验证码有效期：5分钟
- 一次性使用，验证后自动删除

### 3. 安全特性

- **密码错误限制**: 连续5次密码错误后账户锁定30分钟
- **JWT令牌**: 访问令牌24小时有效期，刷新令牌7天有效期
- **IP记录**: 记录用户最后登录IP地址

## 数据库结构

### 用户表 (users)
```sql
- id: 主键
- username: 用户名（唯一）
- password: 密码（加密存储）
- email: 邮箱
- phone: 手机号
- status: 状态（1-正常，2-禁用，3-锁定）
- password_error_count: 密码错误次数
- locked_at: 锁定时间
- last_login_at: 最后登录时间
- last_login_ip: 最后登录IP
- created_at: 创建时间
- updated_at: 更新时间
```

### 角色表 (roles)
```sql
- id: 主键
- name: 角色名称
- code: 角色代码（唯一）
- description: 角色描述
- created_at: 创建时间
- updated_at: 更新时间
```

### 用户角色关联表 (user_roles)
```sql
- id: 主键
- user_id: 用户ID
- role_id: 角色ID
- created_at: 创建时间
- updated_at: 更新时间
```

### 验证码表 (captchas)
```sql
- id: 验证码ID
- text: 验证码文本
- expires_at: 过期时间
- created_at: 创建时间
```

## 配置说明

### JWT配置
```yaml
jwt:
  secret: "your-secret-key"  # JWT签名密钥
  issuer: "gofaster"         # JWT发行者
  expire: 24                 # 令牌过期时间（小时）
```

### 数据库配置
```yaml
db:
  host: localhost
  port: "5432"
  user: postgres
  password: post1024
  name: gofaster
```

## 使用示例

### 1. 用户登录

```bash
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password",
    "captcha": "ABCD"
  }'
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@gofaster.com",
      "phone": "13800138000",
      "status": 1,
      "roles": [
        {
          "id": 1,
          "name": "超级管理员",
          "code": "SUPER_ADMIN"
        }
      ]
    }
  }
}
```

### 2. 获取验证码

```bash
curl -X GET http://localhost:8080/api/auth/captcha
```

**响应示例**:
```json
{
  "code": 200,
  "message": "验证码生成成功",
  "data": {
    "captcha_id": "abc123def456",
    "captcha_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expires_in": 300
  }
}
```

### 3. 使用JWT令牌访问受保护的接口

```bash
curl -X GET http://localhost:8080/api/auth/userinfo \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## 安全说明

1. **密码加密**: 使用 bcrypt 算法加密存储密码
2. **令牌安全**: JWT 令牌使用 HMAC-SHA256 签名
3. **验证码**: 一次性使用，验证后立即删除
4. **账户锁定**: 防止暴力破解攻击
5. **IP记录**: 记录登录IP，便于安全审计

## 错误处理

### 常见错误码

- `400`: 请求参数错误
- `401`: 认证失败（用户名/密码错误、验证码错误）
- `423`: 账户被锁定
- `500`: 系统内部错误

### 错误响应格式

```json
{
  "code": 401,
  "message": "认证失败",
  "error": "密码错误，还可尝试3次"
}
```

## 开发说明

### 项目结构

```
backend/internal/auth/
├── controller/     # 控制器层
├── service/        # 服务层
├── repository/     # 仓储层
├── model/          # 数据模型
├── routes/         # 路由配置
├── migration/      # 数据库迁移
└── module.go       # 模块初始化
```

### 依赖注入

认证服务使用依赖注入模式，各层之间通过接口解耦：

1. **Repository**: 数据访问层
2. **Service**: 业务逻辑层
3. **Controller**: HTTP处理层
4. **Middleware**: JWT认证中间件

### 扩展建议

1. **Redis缓存**: 可以将验证码存储在Redis中，提高性能
2. **日志记录**: 添加详细的登录日志记录
3. **多因素认证**: 支持短信验证码、邮箱验证等
4. **OAuth集成**: 支持第三方登录（Google、GitHub等）
5. **权限管理**: 基于角色的访问控制（RBAC）

## 部署说明

1. 确保PostgreSQL数据库已启动
2. 配置数据库连接参数
3. 设置JWT密钥和发行者
4. 启动应用服务
5. 访问 `/api/auth/captcha` 生成验证码
6. 使用默认管理员账户登录（admin/password）

## 注意事项

1. **生产环境**: 请修改默认的JWT密钥和管理员密码
2. **数据库**: 建议定期备份用户数据
3. **监控**: 建议监控登录失败次数和异常登录行为
4. **更新**: 定期更新依赖包以修复安全漏洞