loginlock —— 登录失败计数 + 账号锁定
防暴力破解:同一 IP + 同一账号连续登录失败到阈值 ⇒ 临时锁住。 计数存在 kvstore 里(Redis / 内存),本包自己不碰 Redis。
⚠️ Windows 上没有官方 Redis ——
kv.mode=redis之前先装一个: Memurai(Redis 协议兼容,装成 Windows 服务, 默认127.0.0.1:6379、无密码)。Developer 版仅供开发/测试,不许上生产。 详见 快速开始。
功能
三个函数,串在登录链路上:
| 函数 | 时机 | 作用 |
|---|---|---|
PreCheck(ctx, username, ip, max) |
登录之前 | 读失败次数,达到 max 返 errcode.UserLocked |
AfterFail(ctx, username, ip, lockDur) |
登录失败之后 | 计数 +1,首次建 key 时设 lockDur 过期 |
Clear(ctx, username, ip) |
登录成功之后 | 清零 |
本包刻意不依赖 repository —— 存储由 kvstore 决定。这样 service 和 middleware 两边都能共用,不用为循环依赖发愁。
计数存哪
存 kvstore 的 Counter,key 是:
login:fail:<ip>:<username>
⚠️ 两个维度都算:IP 和 username 拼在一起。
它不解决什么
- 不做验证码(验证码是独立模块,配置在
captcha:块里) - 不做设备指纹、不识别"同一个人换了 IP"
- 不处理 DB 上那条账号级锁(见「注意事项」第 2 条)
配置
yaml 侧
该包无 yaml 配置(没有阈值项、没有锁定时长项)。
它只间接依赖 kv: 块 —— 存储后端:
kv:
mode: auto # auto | redis | memory
kv.mode=auto 且没 Redis 时走进程内计数:阈值一样生效,但重启后清零、多副本不共享。
⇒ 生产多副本必须 kv.mode: redis。
代码侧
| 项 | 值 | 位置 |
|---|---|---|
| 失败阈值 | 10(硬编码) | internal/service/auth_impl.go 调 loginlock.PreCheck(ctx, req.Username, req.LoginIP, 10) |
| 锁定时长 | 15 分钟(硬编码) | authService.lock = 15 * time.Minute |
| 错误码 | errcode.UserLocked = 20101 |
internal/pkg/errcode |
⚠️ UserLocked 在 20xxx 段 ⇒ errcode.HTTPStatus 把它兜底成 HTTP 200,
语义靠 body 里的 code 承载(框架的通用约定:HTTP 200 + code != 0 是正常失败返回)。
max <= 0 表示显式关闭锁定。
使用方法
// 1. 登录前:还锁着吗
if err := loginlock.PreCheck(ctx, username, ip, 10); err != nil {
return nil, err // errcode.UserLocked
}
// 2. 密码不对:计数 +1
if !auth.CheckPassword(u.PasswordHash, req.Password) {
if err := loginlock.AfterFail(ctx, username, ip, 15*time.Minute); err != nil {
// 计数写不进去 —— 这次失败不累计,但要让调用方看见
}
return nil, errcode.New(errcode.LoginFailed, "账号或密码错误")
}
// 3. 登录成功:清零
_ = loginlock.Clear(ctx, username, ip)
存储装配在 main 里做一次:
store, err := kvstore.Resolve(cfg.KV.Mode, repository.GetRedis())
if err != nil {
return err
}
kvstore.SetDefault(store)
kvstore.Resolve 显式 redis 模式但没配 redis.addr ⇒ 直接报错,不静默退回内存
(多副本部署下用内存限流等于把阈值放大 N 倍)。
完整可运行示例见 examples/loginlock/main.go。
注意事项
- ⚠️ key 是 (ip, username) 两个维度。⇒ 攻击者换 IP 刷同一账号,计数不涨; 同一 IP 撞不同账号,计数也不涨 —— 单维度都挡不住分布式撞库。
- ⚠️ 登录流程里有两条锁,口径不同:
- kvstore 这条:按
(ip, username),阈值 10 / 15 分钟 - DB 上那条:
sys_users.failed_count+sys_users.locked_until,纯按账号, 不看 IP,阈值同样是 10 / 时长同样是 15 分钟(两处都硬编码,靠人工保持一致) ⇒ 同一个账号从 10 个 IP 各失败 10 次:kvstore 那把锁一把都没锁,但 DB 那把锁锁死了。
- kvstore 这条:按
- ⚠️ 计数存 kvstore,不在 DB。
kv.mode=auto没 Redis 时走进程内 ⇒ 重启后清零、 多副本不共享(每个副本各数各的,实际阈值 = 10 × 副本数)。生产多副本必须kv.mode: redis。 - ⚠️ 阈值和锁定时长都不在 yaml 里。改它们要改
internal/service/auth_impl.go的代码(两个数字:PreCheck的第三个参数、authService.lock)。 - ⚠️ 解锁后计数是否清零?分两层:
- 窗口:
AfterFail用Counter.Incr(key, lockDur),Redis 版Incr的 ttl 只在首次创建时生效(INCR 不重置 TTL)⇒ 连续失败不会把窗口无限续长。 这是刻意的 —— 否则爆破就有了免死金牌。 - 计数:只有登录成功才调
Clear。锁定到期后 key 自然过期,新的失败从头计; 但用户换了个 IP 登录成功 ⇒ 清的是另一个 key,原 key 的计数还在(不过它 也已经过期了)。
- 窗口:
- ⚠️
PreCheck出错放行、AfterFail出错返错,方向相反是刻意的:PreCheck出错 → 放行(可用性优先)。Redis 抖一下就把所有账号锁死,比放行更糟。AfterFail出错 → 返回错误(不要假装成功)。登录已经失败了,计数写不进去 意味着这次失败不累计 —— 但调用方要能看见它。
- ⚠️
max <= 0= 显式关闭锁定。不这么判的话,一旦有人把阈值改成配置项并默认 填 0,n >= max会变成"失败一次就锁死所有账号"。 - ⚠️
Clear的错误被登录流程忽略(_ = loginlock.Clear(...))⇒ 计数没清掉 的话,用户密码改对了还是进不去(直到窗口过期)。 - ⚠️
PreCheck拦下来时不再比对密码 —— 省掉一次 bcrypt。 - ⚠️ 2026-10-21 之前,本地 dev 里登录锁定整个不存在。三个函数开头都是
if repository.RDB == nil { return nil }⇒ 没 Redis 时暴力破解可以无限试 —— 而这恰恰是最需要它的地方(生产有 Redis 挡着,本地反而裸奔)。现在走 kvstore 的 内存后端,阈值一样生效。
相关
- 源码:
internal/pkg/loginlock/ - 可运行示例:
examples/loginlock/main.go——go run ./examples/loginlock - 计数 / 滑动窗口存储(锁定的落地处) → kvstore
- 异常登录检测(同一账号多端 / 异地) → anomalylogin
- 错误码分段 → errcode