2.7 KiB
2.7 KiB
5.14 操作日志
:::tip 概述 操作日志由 RouteSpec 声明驱动、中间件链尾采集、异步落库——业务代码零参与。记什么、记不记、什么类型，全部来自路由声明与配置开关。 :::
声明驱动
// internal/router/router.go（RouteSpec）
"Add": {Method: "POST", Path: "/api/example/add", Log: "案例演示-新增记录", LogType: "add"},
"Page": {Method: "GET", Path: "/api/example/page", Log: "案例演示-查询分页记录", LogType: "query"},
| 字段 | 语义 |
|---|---|
| Log | 日志标题（"模块-动作"格式）；空 = 不记录 |
| LogType | 动作字符串（add/update/delete/query/import/export/reset/generate/execute/pause…），落库时映射为数值枚举 |
数值枚举（internal/consts/log_type.go，前端按值映射显示，数值勿改动）：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 下架 / … / 40 解绑，99 其他，0 为自动推断占位（路由 LogType 为空时落 0）。
改一条声明即改变该接口的日志行为，authz/公开判断不受影响（同源）。
采集链路
请求进入 → OperationLog 中间件（链尾）登记开始
↓
正常返回 / 拒绝 / panic —— 中间件读到最终响应摘要
↓
组装条目（操作人、IP、UA、归属地、路径、入参摘要、结果码、耗时）
↓
异步写 gin_operation_log（不阻塞响应）
开关
operationLog:
enable: true # 总开关
logQuery: true # 是否记录查询类（LogType=query）
审计要求高的环境两个都开；日志量敏感时关 logQuery（写操作仍记录）。
不记录的请求
被中间件链提前拒绝的请求不产生操作日志：限流拒绝、演示模式拒绝、未认证 401、租户拒绝、权限 403。这类拒绝在 metrics 中归类（denied/error），且运行日志有痕——避免日志表被攻击尝试刷爆。
归属地与 UA
条目含 IP 归属地（ip2region 离线库）与 User-Agent 解析——登录/操作审计可直接看出来源设备与地域。
消费
- 管理界面：日志管理页按操作人/类型/时间检索（见 6.20 日志管理）
- 保留期：
job.logRetentionDays（默认 90 天），LogClean 任务超期物理清理