日志管理

引用文件

本文引用的文件

简介

本文件系统性梳理了系统的日志管理能力，覆盖登录日志、操作日志、API 访问日志与审计功能。内容包括：

日志数据模型设计（登录信息、操作详情、IP 地址、UA、链路追踪等）
日志采集机制（自动记录、日志过滤、异步处理、持久化存储）
完整日志 API 接口文档（查询、导出、清理等）
日志分析、安全审计、性能监控的应用场景与实现要点
最佳实践与常见问题排查

项目结构

围绕日志管理的关键模块分布如下：

控制层：系统模块提供“登录日志”和“操作日志”的查询与导出接口
服务层：提供日志创建、分页查询等服务接口
数据对象：登录日志与操作日志的数据模型
基础设施：API 访问日志的自动采集、过滤与异步持久化
基础设施模块 API：对外暴露 RPC 接口以供基础设施模块落库
数据库脚本：多数据库方言下的日志表结构定义

Mermaid Diagram Code:

graph TB
subgraph "系统模块"
C1["OperateLogController<br/>操作日志控制器"]
C2["LoginLogController<br/>登录日志控制器"]
S1["OperateLogService<br/>操作日志服务接口"]
S2["LoginLogService<br/>登录日志服务接口"]
DO1["OperateLogDO<br/>操作日志DO"]
DO2["LoginLogDO<br/>登录日志DO"]
end
subgraph "基础设施模块"
F["ApiAccessLogFilter<br/>API访问日志过滤器"]
I["ApiAccessLogInterceptor<br/>API访问日志拦截器"]
A["ApiAccessLogApi<br/>API访问日志RPC接口"]
end
subgraph "数据库"
T1["system_operate_log<br/>操作日志表"]
T2["system_login_log<br/>登录日志表"]
T3["infra_api_access_log<br/>API访问日志表"]
end
C1 --> S1
C2 --> S2
S1 --> DO1
S2 --> DO2
F --> A
I --> F
A --> T3
DO1 --> T1
DO2 --> T2

图表来源

章节来源

核心组件

登录日志与操作日志控制器：提供分页查询与导出 Excel 的接口，支持权限控制与导出审计
登录日志与操作日志服务接口：定义创建日志与分页查询的能力边界
登录日志与操作日志数据对象：承载日志字段，包含用户信息、请求上下文、链路追踪等
API 访问日志过滤器与拦截器：自动采集 API 访问日志，支持开关、参数脱敏、异步持久化
API 访问日志 RPC 接口：基础设施模块通过 Feign 调用进行异步落库

章节来源

架构总览

系统采用“自动采集 + 异步持久化 + 权限控制 + 导出审计”的整体架构：

自动采集：通过过滤器与拦截器在请求前后自动采集 API 访问日志
日志过滤：基于注解与请求类型策略决定是否记录，支持敏感字段脱敏
异步处理：通过 Feign 异步调用基础设施模块接口，避免阻塞主请求链路
持久化存储：基础设施模块接收日志并写入数据库
查询与导出：系统模块提供分页查询与 Excel 导出接口，并记录导出操作

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Filter as "ApiAccessLogFilter"
participant Interceptor as "ApiAccessLogInterceptor"
participant Controller as "系统模块控制器"
participant Service as "系统模块服务"
participant InfraAPI as "ApiAccessLogApi"
participant DB as "数据库"
Client->>Interceptor : 请求进入拦截器
Interceptor-->>Client : 记录请求日志非生产环境
Client->>Filter : 请求进入过滤器
Filter->>Filter : 解析注解/请求类型/脱敏参数
Filter->>InfraAPI : 异步创建API访问日志
InfraAPI->>DB : 写入API访问日志表
Client->>Controller : 调用系统模块接口
Controller->>Service : 查询/导出日志
Service-->>Controller : 返回结果
Controller-->>Client : 响应结果

图表来源

组件详解

登录日志

数据模型字段
- 日志主键、日志类型、链路追踪编号、用户编号、用户类型、用户账号、登录结果、用户 IP、浏览器 UA
控制器能力
- 分页查询登录日志
- 导出登录日志为 Excel，并记录导出操作
服务接口
- 提供分页查询与创建登录日志的能力

Mermaid Diagram Code:

classDiagram
class LoginLogController {
+getLoginLogPage(pageReqVO)
+exportLoginLog(response, exportReqVO)
}
class LoginLogService {
+getLoginLogPage(pageReqVO)
+createLoginLog(reqDTO)
}
class LoginLogDO {
+id
+logType
+traceId
+userId
+userType
+username
+result
+userIp
+userAgent
}
LoginLogController --> LoginLogService : "依赖"
LoginLogService --> LoginLogDO : "读写"

图表来源

章节来源

操作日志

数据模型字段
- 日志主键、链路追踪编号、用户编号、用户类型、操作模块类型、操作名、业务编号、操作内容、扩展字段、请求方法名、请求地址、用户 IP、浏览器 UA
控制器能力
- 分页查询操作日志
- 导出操作日志为 Excel，并记录导出操作
服务接口
- 提供分页查询与创建操作日志的能力

Mermaid Diagram Code:

classDiagram
class OperateLogController {
+pageOperateLog(pageReqVO)
+exportOperateLog(response, exportReqVO)
}
class OperateLogService {
+createOperateLog(createReqDTO)
+getOperateLogPage(pageReqVO)
+getOperateLogPage(pageReqDTO)
}
class OperateLogDO {
+id
+traceId
+userId
+userType
+type
+subType
+bizId
+action
+extra
+requestMethod
+requestUrl
+userIp
+userAgent
}
OperateLogController --> OperateLogService : "依赖"
OperateLogService --> OperateLogDO : "读写"

图表来源

章节来源

API 访问日志（自动采集）

注解驱动
- 通过注解控制是否启用、是否记录请求/响应、敏感字段脱敏、操作模块/名称/类型
过滤器逻辑
- 解析请求参数与请求体，构造访问日志对象
- 基于请求类型与注解策略决定是否记录
- 异常与正常响应均记录，包含耗时、结果码与消息
- 对请求/响应进行脱敏处理，避免敏感信息泄露
拦截器辅助
- 非生产环境打印请求与响应日志，便于开发调试
异步持久化
- 通过 Feign 异步调用基础设施模块接口，避免阻塞主链路

Mermaid Diagram Code:

flowchart TD
Start(["进入过滤器"]) --> Parse["解析注解与请求类型"]
Parse --> ShouldLog{"是否需要记录？"}
ShouldLog --> |否| End(["结束"])
ShouldLog --> |是| Build["构建访问日志对象<br/>用户信息/请求/响应/结果/耗时"]
Build --> Sanitize["敏感字段脱敏"]
Sanitize --> Async["异步调用RPC接口写库"]
Async --> End

图表来源

章节来源

日志数据模型设计

登录日志表（system_login_log）
- 字段：日志主键、日志类型、链路追踪编号、用户编号、用户类型、用户账号、登录结果、用户 IP、浏览器 UA、创建/更新时间等
操作日志表（system_operate_log）
- 字段：日志主键、链路追踪编号、用户编号、用户类型、操作模块类型、操作名、业务编号、操作内容、扩展字段、请求方法名、请求地址、用户 IP、浏览器 UA、创建/更新时间等
API 访问日志表（infra_api_access_log）
- 字段：日志主键、链路追踪编号、用户编号、用户类型、应用名、请求方法名、请求地址、请求参数、响应体、结果码、结果消息、耗时、创建/更新时间等

章节来源

日志收集机制

自动记录
- 通过过滤器与拦截器在请求前后自动采集 API 访问日志
日志过滤
- 基于注解与请求类型策略决定是否记录；GET 且无注解或无方法缓存时默认不记录
异步处理
- 通过 Feign 异步接口写入基础设施模块，避免阻塞主请求链路
持久化存储
- 基础设施模块接收日志并写入数据库

章节来源

日志 API 接口文档

登录日志
- 分页查询：GET /system/login-log/page
- 导出 Excel：GET /system/login-log/export
操作日志
- 分页查询：GET /system/operate-log/page
- 导出 Excel：GET /system/operate-log/export
API 访问日志（基础设施模块）
- 创建 API 访问日志：POST /infra/api-access-log/create
- 异步创建：@Async 默认实现

章节来源

日志分析、安全审计与性能监控

日志分析
- 基于操作日志的“操作模块类型/操作名/业务编号/扩展字段”进行统计与分析
- 基于 API 访问日志的“请求方法/URL/耗时/结果码/用户 IP/UA”进行趋势与异常检测
安全审计
- 登录日志记录登录结果与 IP/UA，便于识别异常登录
- API 访问日志对敏感字段脱敏，兼顾审计与隐私保护
性能监控
- API 访问日志记录耗时，可用于接口性能分析与告警

章节来源

最佳实践

合理使用注解
- 对敏感接口开启请求/响应记录，对通用接口默认关闭响应记录以降低开销
敏感字段脱敏
- 使用注解的敏感字段数组与内置脱敏策略，避免日志泄露密码、令牌等
异步落库
- 通过异步接口避免阻塞主链路，提升吞吐
权限控制
- 查询与导出接口均需权限校验，防止越权访问
数据库索引
- 建议在创建时间、用户编号、请求地址等常用查询字段上建立索引，提升查询性能

章节来源

依赖关系分析

控制器依赖服务接口，服务接口依赖数据对象
API 访问日志过滤器依赖 RPC 接口进行异步落库
操作日志解析函数依赖用户服务进行用户名称解析

Mermaid Diagram Code:

graph LR
Controller["控制器"] --> Service["服务接口"]
Service --> DO["数据对象"]
Filter["ApiAccessLogFilter"] --> RPC["ApiAccessLogApi"]
RPC --> DB["数据库"]
Parser["AdminUserParseFunction"] --> UserService["AdminUserService"]

图表来源

章节来源

性能考量

异步落库：通过异步接口减少主链路阻塞，提高吞吐
参数脱敏：避免大字段写库带来的 IO 压力
过滤策略：仅对必要接口记录日志，降低写库压力
索引优化：在高频查询字段上建立索引，提升查询性能
导出限制：导出接口设置最大分页大小，避免一次性导出过多数据

章节来源

故障排查指南

API 访问日志未记录
- 检查是否为 GET 且无注解或无方法缓存，此类请求默认不记录
- 检查注解 enable 是否为 true
敏感字段泄露
- 确认注解 sanitizeKeys 或内置脱敏策略是否正确配置
导出失败或性能问题
- 检查导出分页大小限制与数据库查询性能
登录/操作日志缺失
- 确认控制器权限与分页查询条件是否正确

章节来源

结论

本日志管理体系通过自动采集、异步落库、权限控制与导出审计，实现了对登录、操作与 API 访问的全面覆盖。配合完善的脱敏与过滤策略，既满足安全审计需求，又兼顾性能与可维护性。建议在生产环境中合理配置日志策略与索引，持续优化查询与导出性能。

附录

操作类型枚举：GET、CREATE、UPDATE、DELETE、EXPORT、IMPORT、OTHER
用户解析函数：支持根据用户 ID 解析用户昵称与手机号，便于日志可读性

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

组件详解​

登录日志​

操作日志​

API 访问日志（自动采集）​

日志数据模型设计​

日志收集机制​

日志 API 接口文档​

日志分析、安全审计与性能监控​

最佳实践​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

目录

简介

项目结构

核心组件

架构总览

组件详解

登录日志

操作日志

API 访问日志（自动采集）

日志数据模型设计

日志收集机制

日志 API 接口文档

日志分析、安全审计与性能监控

最佳实践

依赖关系分析

性能考量

故障排查指南

结论

附录