# 5.14 操作日志

:::tip 概述
操作日志由中间件异步采集：gmeta log/logType 标签声明记录内容，OperationLog 中间件组装（含脱敏），有界通道 + 单 worker 批量落库，绝不阻塞业务。41 种日志类型固定枚举。
:::

## 采集链路

```text
gmeta log 标签 → 路由元数据（meta 表）→ 中间件组装 OperationLogEntry
  → 有界通道 2048（满则丢弃并计数告警，不阻塞业务）
  → 单 worker 攒批（满 100 条或每 1s flush 一批）
  → LogSink（operation_log 模块 init 注册的落库函数）
  → INSERT goframe_operation_log
```

## 记录字段

```text
Title=log 标签   Type=logType   Source=0
Method="GET /api/user/page"（路由模板）  RequestMethod/URL=实际请求
Param：GET/DELETE 取 query JSON；写操作优先取 body
       （maskSecret 脱敏 password/oldPassword/newPassword/salt/
         access_token/refresh_token → ***）
Result：响应信封 JSON（截断 8000 字节，UTF-8 边界回退截断）
IP=realClientIP   Location=ip2region   OS/Browser=ua 解析
ConsumeTime=毫秒   Status：响应 code==0 → 0 正常，否则 1 异常（Error=msg）
CreateUser=ctx 用户名
```

## log_type 固定枚举（consts/log_type.go，数值勿改）

```text
0=自动推断（GET→查询，其余→修改）
1=新增   2=修改   3=删除   4=查询   5=导入   6=导出
7=审批   8=驳回   9=提交   10=撤回  11=关闭  12=开启
13=启用  14=禁用  15=上传  16=下载  17=发送  18=同步
19=代码生成  20=清空  21=还原  22=登录  23=登出  24=重置
25=分配  26=授权  27=执行  28=暂停  29=恢复  30=发布
31=下架  32=复制  33=移动  34=排序  35=锁定  36=解锁
37=归档  38=取消归档  39=绑定  40=解绑  99=其他
```

gmeta `logType` 字符串（query/add/update/delete/import/export/reset/…）经 LogTypeMap 转枚举；展示中文经 LogTypeNames（logic 的 LogTypeText）——**该字段不走字典**（数值与注解绑定，改动破坏存量日志）。

## 开关与配置

```yaml
operationLog:
  enable:   true    # 总开关
  logQuery: true    # 是否记录查询类操作（logType=query）
```

日志标题约定：`{模块中文名}-{动作}`（如"用户管理-查询分页记录"），动作映射 page=查询分页记录 / list=查询列表 / detail=查询详情 / add=新增记录 / update=修改记录 / delete=删除记录 / batchDelete=批量删除记录 / import=导入数据 / export=导出数据 / status=设置状态。

## 查询模块（/api/oper/log）

```text
仅查询与删除（无增改——日志只能系统写入）：
  GET  /api/oper/log/page|list|detail/:id
  DELETE /api/oper/log/delete/:id | /batchDelete
权限：sys:operLog:{page|list|detail|delete|batchDelete}
清理：内置 LogClean 定时任务物理删除超保留期记录（job.logRetentionDays 默认 90 天）
```

## 可靠性设计

| 场景 | 行为 |
|------|------|
| 通道满（2048） | 丢弃该条并计数，每丢 100 条输出一次 Warning——**日志绝不阻塞业务** |
| 落库失败 | 仅记错误日志，不影响响应 |
| panic | Response 中间件 recover 兜底（日志采集在 defer 后仍执行） |
| 批量节奏 | 满 100 条或 1s flush——峰值下落库延迟 ≤1s |

## 排障

```text
日志完全缺失：operationLog.enable=false？LogSink 未注册（启动告警）？
查询类没记录：operationLog.logQuery=false
偶发缺失：通道满丢弃告警（看 Warning 日志）；峰值场景可调大通道容量
Param 是 ***：正常——敏感字段脱敏
Result 超长被截：正常——截断 8KB
IP/归属地不对：api.proxyIps 未含反代地址（见受信代理机制）
```