签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,69 @@
+# 5.15 登录日志
+
+:::tip 概述
+登录日志由业务写入（logic/auth.go writeLoginLog）：登录成功、失败、退出全记录，含 IP 归属地（ip2region）、操作系统与浏览器解析、耗时统计。失败记录含具体原因，供安全审计。
+:::
+
+## 写入时机
+
+| 时机 | log_type | status | 说明 |
+|------|----------|--------|------|
+| 登录成功 | 1 | 0 | 含双令牌签发后的完整信息 |
+| 登录失败 | 1 | 1 | error 存失败原因；code 参数脱敏 *** |
+| 退出登录 | 2 | 0 | GET /api/logout 触发 |
+
+每一步失败（验证码/用户/状态/租户/密码）均写日志——登录闭环的 8 步全路径覆盖。
+
+## 记录字段
+
+```text
+username / log_type（1登录/2退出）/ source（0 后台）
+method / request_method / url / param（code 脱敏 ***）
+result（成功|失败）
+ip / location（ip2region 归属地）
+os / browser（ua 解析）
+consume_time（登录耗时）
+status（0 成功/1 失败）/ error（失败原因）
+```
+
+## IP 归属地（utility/ip2region）
+
+```text
+xdb 懒加载（sync.Once）+ 读锁并发
+City(ip)     优先市回退省；内网/回环返回空
+Location(ip) 供日志（失败显示 "-"）
+路径配置：ip2region.path（默认 manifest/data/ip2region.xdb）
+
+受信代理：仅直连来源在 api.proxyIps（精确 IP / CIDR）内才信任
+          X-Forwarded-For / X-Real-IP —— 否则日志 IP 是反代 IP
+```
+
+OS/Browser 由 utility/ua 解析 User-Agent。
+
+## 查询模块（/api/login/log）
+
+```text
+仅查询与删除（五件）：
+  GET  /api/login/log/page|list|detail/:id
+  DELETE /api/login/log/delete/:id | /batchDelete
+权限：sys:loginLog:{page|list|detail|delete|batchDelete}
+清理：LogClean 任务（job.logRetentionDays 默认 90 天）
+```
+
+## 安全审计用法
+
+```text
+暴力破解排查：按 ip 聚合 status=1 的失败记录（配合 authLimit=10/分钟/IP）
+撞库识别：同 IP 多 username 失败尝试
+异常登录：location 与常用地对比（ip2region 归属地）
+账号盗用：同账号异地短时间成功登录
+```
+
+## 排障
+
+| 症状 | 检查 |
+|------|------|
+| location 显示 "-" | ip2region.xdb 缺失/路径错；内网 IP 本就无归属地 |
+| location 是机房 IP | api.proxyIps 未含反代出口（日志记了反代 IP） |
+| os/browser 显示未知 | User-Agent 异常或为空（非浏览器客户端） |
+| 失败日志无 error | 应有失败原因——检查 writeLoginLog 各分支 |