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)

- 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)

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

用户角色关联表 (user_roles)

- id: 主键
- user_id: 用户ID
- role_id: 角色ID
- created_at: 创建时间
- updated_at: 更新时间

验证码表 (captchas)

- id: 验证码ID
- text: 验证码文本
- expires_at: 过期时间
- created_at: 创建时间

配置说明

JWT配置

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

数据库配置

db:
  host: localhost
  port: "5432"
  user: postgres
  password: post1024
  name: gofaster

使用示例

1. 用户登录

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

响应示例:

{
  "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. 获取验证码

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

响应示例:

{
  "code": 200,
  "message": "验证码生成成功",
  "data": {
    "captcha_id": "abc123def456",
    "captcha_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expires_in": 300
  }
}

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

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: 系统内部错误

错误响应格式

{
  "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. 更新: 定期更新依赖包以修复安全漏洞