# 5.15 登录日志

:::tip 概述
登录/登出行为独立留痕（gin_login_log）：成功与失败都记录，失败含错误原因分类。由 auth 模块在登录链路内直接写入，写失败仅告警不影响登录结果。
:::

## 记录内容

| 字段类别 | 内容 |
|---|---|
| 身份 | 用户名、用户ID、租户 |
| 行为 | 登录 / 登出，status（0 成功 / 1 失败） |
| 失败原因 | 验证码错误 / 用户不存在 / 租户禁用或过期 / 账号禁用 / 密码错误 |
| 来源 | IP、归属地（ip2region）、User-Agent 解析 |
| 时间 | 发生时间 |

## 写入时机

```text
登录成功   → status=0 条目（登录链路第 7 步）
登录失败   → status=1 条目（除令牌签发失败直接上抛外，各失败环节均记录）
登出       → 登出日志
```

失败日志是安全审计的核心素材：配合 authLimit 限流可以看到"谁在尝试爆破、来自哪里"。

## 容错设计

登录链路对日志的定位是"尽力记录"：日志写失败只打告警，不使登录失败——审计设施故障不应阻断业务入口。

## 保留与清理

与操作日志、任务日志共用保留期配置 `job.logRetentionDays`（默认 90 天），由 LogClean 定时任务超期物理清理（唯一被允许的物理删除场景之一，经 WithPhysicalDelete 放行）。

## 管理界面

登录日志页按用户/结果/时间/地域检索，见 [6.20 日志管理](/zh/modules/logger.html)。

## 下一步

→ [5.16 异常与统一响应](/zh/core/exception.html)