# Changelog: 登录白名单 IP 绕过防暴破锁定

**日期**: 2026-06-02

## 摘要

修复登录流程中「白名单 IP 仍受 15 分钟失败锁定」的问题：白名单内 IP 跳过 `count_recent_failures` 锁定检查；失败时不写入 `login_attempts` 失败计数，仅写审计日志；成功登录时清除该用户历史失败记录，避免被其他 IP 的累计失败连带锁住。

## 动机

运维/内网可信 IP 已在登录白名单中，不应再被全局用户名维度的失败次数锁定；同时白名单 IP 登录成功后应解除因外网误试导致的账户锁定状态。

## 涉及文件

- `server/application/services/auth_service.py` — `login()` 增加 `is_whitelisted_ip`、`_handle_login_failure()`、成功时 `clear_failures_for_username`
- `server/infrastructure/database/admin_repo.py` — `LoginAttemptRepositoryImpl.clear_failures_for_username`
- `server/domain/repositories/__init__.py` — `LoginAttemptRepository` 协议补充方法

## 迁移 / 重启

- 无需数据库迁移
- 需重启 Nexus 后端（`supervisorctl restart nexus`）后生效

## 验证方式

1. 本地：`python -c "import server.application.services.auth_service"`
2. 开启 `LOGIN_ALLOWLIST_ENABLED`，将当前 IP 加入白名单
3. 用非白名单 IP 对同一用户连续失败 5 次至锁定
4. 从白名单 IP 登录：应不被 `account_locked` 拦截；密码错误时 `audit_logs` 有 `login_failed`，`login_attempts` 不新增失败行
5. 白名单 IP 正确密码登录后，该用户 `login_attempts` 中 `success=0` 记录应被清除
