Skip to content

认证授权模块 ​

认证授权模块(auth)是 MengStack 的核心安全模块,提供用户注册、登录、令牌管理、用户 CRUD 等基础能力。基于 JWT 双令牌体系(Access Token + Refresh Token),支持多租户隔离和 Redis 刷新令牌指纹防重放。

架构概览 ​

modules/auth/
├── domain/          # User 实体、DTO、Repository 接口
├── application/     # Service(JWT 工具、令牌生成/解析)
├── infrastructure/  # GORM UserRepository 实现、AutoMigrate
└── interfaces/      # HTTP Handler、路由注册、Auth 中间件

数据模型 ​

User 实体 ​

字段类型说明
IDuint主键
TenantIDstring (UUID)租户 ID,复合主键
Usernamestring(64)全局唯一用户名
Emailstring(128)租户内唯一邮箱,复合唯一索引 idx_tenant_email
Passwordstring(256)bcrypt 哈希(cost 12),JSON 序列化时隐藏
Nicknamestring(64)昵称
Avatarstring(512)头像 URL
Statusint状态,默认 1(启用)
LastLogin*time.Time最后登录时间

数据库表: users

索引设计:

  • 复合主键:(ID, TenantID)
  • 复合唯一索引:(TenantID, Email) — 邮箱租户内唯一
  • 全局唯一索引:Username — 用户名全局唯一

API 接口 ​

公开接口(无需认证) ​

方法路径说明
POST/api/v1/auth/register用户注册
POST/api/v1/auth/login用户登录
POST/api/v1/auth/refresh刷新令牌

用户接口(需认证) ​

方法路径说明
GET/api/v1/ping连通性测试
GET/api/v1/profile获取当前用户信息
POST/api/v1/password修改密码

管理接口(需认证 + 权限) ​

方法路径权限说明
GET/api/v1/usersauth.user.read用户列表(分页、搜索、状态筛选)
POST/api/v1/usersauth.user.write创建用户
GET/api/v1/users/:idauth.user.read获取用户详情
PUT/api/v1/users/:idauth.user.write更新用户
DELETE/api/v1/users/:idauth.user.write删除用户

请求/响应示例 ​

注册 ​

json
// POST /api/v1/auth/register
// Request
{
  "username": "zhangsan",
  "email": "zhangsan@example.com",
  "password": "12345678",
  "nickname": "张三"
}

// Response 200
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in": 1800
}

登录 ​

json
// POST /api/v1/auth/login
// Request
{
  "email": "zhangsan@example.com",
  "password": "12345678"
}

// Response 200
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in": 1800
}

刷新令牌 ​

json
// POST /api/v1/auth/refresh
// Request
{
  "refresh_token": "eyJhbGciOi..."
}

// Response 200 — 返回新的令牌对
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in": 1800
}

安全特性 ​

JWT 双令牌体系 ​

  • 签名算法: HS256(HMAC-SHA256)
  • Access Token: 短期有效(默认 30 分钟),用于 API 认证
  • Refresh Token: 长期有效(默认 7 天),用于无感续期
  • Claims 字段: user_id、tenant_id、type(access / refresh)

Refresh Token 轮转(Redis 指纹) ​

每次刷新令牌时,系统会:

  1. 验证旧 Refresh Token 的 JWT 签名和类型
  2. 从 Redis 读取存储的指纹(SHA-256 前 16 字节)
  3. 比对指纹一致性
  4. 生成新的令牌对,存储新指纹
  5. Redis Key 格式:rt:{tenantID}:{userID}

此机制防止 Refresh Token 重放攻击。

时序攻击防护 ​

登录时,即使用户不存在,系统也会执行一次 dummy bcrypt 比较,防止攻击者通过响应时间差异判断邮箱是否已注册。

密码哈希 ​

使用 golang.org/x/crypto/bcrypt,cost 参数为 12,覆盖注册、修改密码、管理员创建用户等所有场景。

中间件 ​

Auth 中间件 ​

定义于 interfaces/routes.go,行为:

  1. 读取 Authorization 请求头(支持 Bearer <token> 或裸 token)
  2. 解析 JWT 并验证签发者
  3. 校验 token 类型为 access
  4. 将 user_id、user_id_str、tenant_id 写入 Gin Context
  5. 通过 tenant.WithTenantID 注入请求上下文

多租户中间件 ​

  • 公开路由使用 OptionalTenant(不强制租户解析)
  • 受保护路由使用 MultiTenant(强制租户解析)

依赖注入 ​

go
fx.Module("auth",
    fx.Provide(
        NewJWTConfig,
        infrastructure.NewUserRepository,
        application.NewService,
        NewHandler,
        NewAuthMiddleware,
    ),
)

依赖组件 ​

组件用途
gorm.io/gormORM 数据访问
github.com/redis/go-redis/v9Refresh Token 指纹存储
github.com/golang-jwt/jwt/v5JWT 令牌生成与解析
golang.org/x/crypto/bcrypt密码哈希
github.com/gin-gonic/ginHTTP 框架
go.uber.org/fx依赖注入

Released under the Apache 2.0 License.