# 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 各分支 |