Appearance
认证授权模块
认证授权模块(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 实体
| 字段 | 类型 | 说明 |
|---|---|---|
| ID | uint | 主键 |
| TenantID | string (UUID) | 租户 ID,复合主键 |
| Username | string(64) | 全局唯一用户名 |
| string(128) | 租户内唯一邮箱,复合唯一索引 idx_tenant_email | |
| Password | string(256) | bcrypt 哈希(cost 12),JSON 序列化时隐藏 |
| Nickname | string(64) | 昵称 |
| Avatar | string(512) | 头像 URL |
| Status | int | 状态,默认 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/users | auth.user.read | 用户列表(分页、搜索、状态筛选) |
| POST | /api/v1/users | auth.user.write | 创建用户 |
| GET | /api/v1/users/:id | auth.user.read | 获取用户详情 |
| PUT | /api/v1/users/:id | auth.user.write | 更新用户 |
| DELETE | /api/v1/users/:id | auth.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 指纹)
每次刷新令牌时,系统会:
- 验证旧 Refresh Token 的 JWT 签名和类型
- 从 Redis 读取存储的指纹(SHA-256 前 16 字节)
- 比对指纹一致性
- 生成新的令牌对,存储新指纹
- Redis Key 格式:
rt:{tenantID}:{userID}
此机制防止 Refresh Token 重放攻击。
时序攻击防护
登录时,即使用户不存在,系统也会执行一次 dummy bcrypt 比较,防止攻击者通过响应时间差异判断邮箱是否已注册。
密码哈希
使用 golang.org/x/crypto/bcrypt,cost 参数为 12,覆盖注册、修改密码、管理员创建用户等所有场景。
中间件
Auth 中间件
定义于 interfaces/routes.go,行为:
- 读取
Authorization请求头(支持Bearer <token>或裸 token) - 解析 JWT 并验证签发者
- 校验 token 类型为
access - 将
user_id、user_id_str、tenant_id写入 Gin Context - 通过
tenant.WithTenantID注入请求上下文
多租户中间件
- 公开路由使用
OptionalTenant(不强制租户解析) - 受保护路由使用
MultiTenant(强制租户解析)
依赖注入
go
fx.Module("auth",
fx.Provide(
NewJWTConfig,
infrastructure.NewUserRepository,
application.NewService,
NewHandler,
NewAuthMiddleware,
),
)依赖组件
| 组件 | 用途 |
|---|---|
gorm.io/gorm | ORM 数据访问 |
github.com/redis/go-redis/v9 | Refresh Token 指纹存储 |
github.com/golang-jwt/jwt/v5 | JWT 令牌生成与解析 |
golang.org/x/crypto/bcrypt | 密码哈希 |
github.com/gin-gonic/gin | HTTP 框架 |
go.uber.org/fx | 依赖注入 |

