签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,84 @@
+# 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 未含反代地址（见受信代理机制）
+```