概述日志模块负责记录系统运行过程中的关键操作和请求轨迹帮助团队快速定位问题、追溯操作历史。模块包含两大核心部分模块数据来源说明操作日志前端上报用户在前端执行关键操作后前端主动调用接口上报操作记录系统审计日志后端自动记录中间件自动拦截所有/api/请求记录完整的请求/响应审计轨迹前端只读统一约定所有接口需在 Header 中携带Authorization: Bearer token所有接口统一返回格式{ code, message, logId, data }code 0表示成功基础地址开发环境http://localhost:8000一、操作日志前端上报操作日志用于记录用户在前端执行的关键操作。user字段由后端通过 JWT 自动注入前端无需手动传递。1.1 上报操作日志新增POST /api/operation-logs/请求参数JSON Body参数类型必填说明actionstring✅操作类型可选值见下方action 枚举modulestring✅操作模块如用户管理、部门管理、角色管理target_idstring操作对象的 IDtarget_namestring操作对象的名称request_methodstringHTTP 方法GET/POST/PUT/DELETErequest_urlstring操作的 API 路径如/api/members/42/request_paramsstring请求参数JSON 字符串注意对敏感字段进行脱敏处理ip_addressstring客户端 IP 地址addressstringIP 解析后的地理位置如中国河南省信阳市user_agentstring浏览器 User-Agentbrowserstring浏览器信息如Chrome 120osstring操作系统如Windows 10devicestring设备类型PC/Mobile/Tabletduration_msint操作耗时单位毫秒resultstring操作结果success默认/failederror_messagestring失败时的错误描述remarkstring备注信息log_idstring请求追踪 ID与 API 响应中的logId相对应请求示例{action:update,module:部门管理,target_name:研发组,request_method:PUT,request_url:/api/departments/5/,ip_address:187.68.233.93,address:中国河南省信阳市,browser:Edge 151,os:Windows 10,device:PC,duration_ms:128,result:success,log_id:a1b2c3d4e5f6g7h8}返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如创建成功logIdstring追踪 IDdataobject创建的操作日志对象完整字段见下方 1.2 列表项1.2 分页查询列表查询GET /api/operation-logs/请求参数Query String参数类型必填说明searchstring模糊搜索用户名 / 账号 / 模块名 / 对象名称actionstring按操作类型过滤modulestring按模块名模糊过滤resultstring操作结果success/failedip_addressstringIP 地址模糊搜索start_timestring开始时间格式2026-08-01T00:00:00end_timestring结束时间格式2026-08-07T23:59:59pageint页码默认1page_sizeint每页条数orderingstring排序字段如-created_at降序、duration_ms升序请求示例GET /api/operation-logs/?search张三actionupdatepage1page_size20ordering-created_at返回参数JSON参数类型说明codeint0表示成功data.countint总条数data.nextstring下一页 URL为null时表示最后一页data.previousstring上一页 URL为null时表示第一页data.resultsarray操作日志列表data.results[]中每条记录的结构参数类型说明idint日志 IDlog_idstring追踪 IDuser_infoobject操作人信息{ id, name }actionstring操作类型modulestring操作模块target_idstring操作对象 IDtarget_namestring操作对象名称request_methodstringHTTP 方法request_urlstring请求路径request_paramsstring请求参数 JSONip_addressstringIP 地址addressstring操作地点browserstring浏览器osstring操作系统devicestring设备类型duration_msint耗时毫秒resultstring操作结果success/failederror_messagestring错误信息remarkstring备注created_by_infoobject创建人信息{ id, name }created_atstring创建时间updated_atstring更新时间返回示例{code:0,message:success,logId:c3d4e5f6g7h8i9j0,data:{count:150,next:http://localhost:8000/api/operation-logs/?page2,previous:null,results:[{id:1,log_id:a1b2c3d4e5f6g7h8,user_info:{id:1,name:管理员},action:update,module:部门管理,target_id:5,target_name:研发组,request_method:PUT,request_url:/api/departments/5/,request_params:{\name\:\研发组\},ip_address:187.68.233.93,address:中国河南省信阳市,browser:Edge 151,os:Windows 10,device:PC,duration_ms:128,result:success,error_message:,remark:,created_by_info:{id:1,name:管理员},created_at:2026-08-07T10:30:00Z,updated_at:2026-08-07T10:30:00Z}]}}1.3 查看详情查询GET /api/operation-logs/{id}/请求参数路径参数参数类型必填说明idint✅日志 ID返回参数JSON参数类型说明codeint0表示成功data.resultobject单条操作日志对象字段结构同 1.2 列表项1.4 软删除删除DELETE /api/operation-logs/{id}/软删除仅标记记录为已删除不会从数据库中物理移除。请求参数路径参数参数类型必填说明idint✅日志 ID返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如删除成功datanull1.5 批量删除删除POST /api/operation-logs/batch-delete/请求参数JSON Body参数类型必填说明idsint[]✅要删除的日志 ID 数组请求示例{ids:[1,2,3]}返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如成功删除 3 条操作日志datanull1.6 清空全部删除DELETE /api/operation-logs/clear/⚠️注意此操作会清空所有操作日志数据请谨慎使用。请求参数无返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如已清空全部操作日志共 N 条datanull1.7 今日统计查询GET /api/operation-logs/stats/today/请求参数无返回参数JSON参数类型说明data.totalint今日操作总数data.successint成功数data.failedint失败数data.by_actionobject按操作类型分组统计如{ create: 10, update: 15 }操作日志 — action 枚举值说明前端触发场景create新增提交新建成功后update修改提交保存成功后delete删除确认删除成功后query查询执行搜索/筛选后高频操作可酌情跳过login登录登录成功后后端已自动记录前端可选上报logout登出主动退出登录export导出导出 Excel/PDF 成功后import导入导入数据成功后other其他不归类的操作二、系统审计日志后端自动记录系统审计日志由后端中间件自动记录覆盖所有/api/请求的完整请求和响应。前端仅允许查询和删除不允许新增和修改。每条日志会记录以下完整信息请求端HTTP 方法、路径、所属模块、查询参数、请求头Authorization已脱敏、请求体响应端HTTP 状态码、业务码、响应消息、响应头Set-Cookie已隐藏、响应体环境信息客户端 IP、地理位置IP 自动解析、浏览器、操作系统、设备类型、耗时操作人通过 JWT 自动识别2.1 分页查询列表查询GET /api/system-logs/请求参数Query String参数类型必填说明searchstring模糊搜索用户名 / 账号 / 请求路径 / 模块名request_methodstring请求方法过滤GET/POST/PUT/DELETE/PATCHrequest_pathstring请求路径模糊搜索modulestring按模块名模糊过滤response_statusintHTTP 状态码如200、400、403、500response_codeint业务状态码如0、10200ip_addressstringIP 地址模糊搜索start_timestring开始时间格式2026-08-01T00:00:00end_timestring结束时间格式2026-08-07T23:59:59pageint页码默认1page_sizeint每页条数orderingstring排序字段如-duration_ms、-created_at返回参数JSON参数类型说明codeint0表示成功data.countint总条数data.nextstring下一页 URLdata.previousstring上一页 URLdata.resultsarray系统日志列表data.results[]中每条记录的结构参数类型说明idint日志 IDlog_idstring追踪 ID与该次 API 响应中的logId一致user_infoobject / null操作人信息{ id, name }未登录时为nullrequest_methodstringHTTP 方法request_pathstring请求路径modulestring所属模块如系统监控系统日志query_paramsstringURL 查询参数request_headersstring请求头JSONAuthorization已脱敏request_bodystring请求体最多 4096 字符response_statusintHTTP 状态码response_codeint业务状态码response_messagestring业务响应消息response_headersstring响应头JSONSet-Cookie已隐藏response_bodystring响应体最多 4096 字符ip_addressstring客户端 IPaddressstringIP 解析后的地理位置如中国 河南省 信阳市user_agentstring浏览器 User-Agent 原文browserstring浏览器osstring操作系统devicestring设备类型duration_msint请求耗时毫秒exception_infostring异常信息正常为空created_by_infoobject操作人信息{ id, name }created_atstring请求时间返回示例{code:0,message:success,logId:g7h8i9j0k1l2m3n4,data:{count:1520,next:http://localhost:8000/api/system-logs/?page2,previous:null,results:[{id:1,log_id:a1b2c3d4e5f6g7h8,user_info:{id:1,name:管理员},request_method:POST,request_path:/api/members/,module:成员管理,query_params:,request_headers:{\HTTP_CONTENT_TYPE\:\application/json\,\HTTP_AUTHORIZATION\:\Bearer eyJhbGc...\,\HTTP_ORIGIN\:\http://localhost:5173\},request_body:{\name\:\李四\,\email\:\lisiexample.com\},response_status:201,response_code:0,response_message:创建成功,response_headers:{\Content-Type\:\application/json\,\Allow\:\GET, POST, HEAD, OPTIONS\},response_body:{\code\:0,\message\:\创建成功\,\logId\:\a1b2c3d4e5f6g7h8\,\data\:{\id\:42,\name\:\李四\}},ip_address:192.168.1.100,address:内网,user_agent:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...,browser:Chrome 120,os:Windows 10,device:PC,duration_ms:156,exception_info:,created_by_info:{id:1,name:管理员},created_at:2026-08-07T10:30:00Z}]}}2.2 查看详情查询GET /api/system-logs/{id}/请求参数路径参数参数类型必填说明idint✅日志 ID返回参数JSON参数类型说明codeint0表示成功data.resultobject单条系统日志对象字段结构同 2.1 列表项2.3 软删除删除DELETE /api/system-logs/{id}/软删除仅标记记录为已删除不会从数据库中物理移除。请求参数路径参数参数类型必填说明idint✅日志 ID返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如删除成功datanull2.4 批量删除删除POST /api/system-logs/batch-delete/请求参数JSON Body参数类型必填说明idsint[]✅要删除的日志 ID 数组请求示例{ids:[1,2,3]}返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如成功删除 3 条系统日志datanull2.5 清空全部删除DELETE /api/system-logs/clear/⚠️注意此操作会清空所有系统审计日志请谨慎使用。请求参数无返回参数JSON参数类型说明codeint0表示成功messagestring提示信息如已清空全部系统日志共 N 条datanull2.6 今日请求统计查询GET /api/system-logs/stats/today/请求参数无返回参数JSON参数类型说明data.totalint今日请求总数data.successint成功数HTTP 状态码 400data.failedint失败数HTTP 状态码 ≥ 400data.avg_duration_msfloat平均耗时毫秒三、附录统一响应格式所有接口均返回以下标准结构{code:0,message:success,logId:16位追踪ID,data:{}}常见错误码code说明0成功10000服务器异常10001数据校验失败10002参数错误10100认证失败10101Token 已过期10102Token 无效10200无操作权限10300数据不存在50000服务器内部错误认证方式所有接口需在 Header 中携带 JWT TokenAuthorization: Bearer 登录返回的 token系统日志请求头采集说明后端中间件会采集以下请求头信息采集的头说明HTTP_CONTENT_TYPE请求内容类型HTTP_ACCEPT客户端接受的格式HTTP_ORIGIN来源域名HTTP_REFERER来源页面HTTP_AUTHORIZATIONToken已脱敏仅保留前 20 字符 ...HTTP_X_FORWARDED_FOR代理转发的真实 IPHTTP_X_REQUESTED_WITHAJAX 请求标记HTTP_HOST目标主机系统日志响应头采集说明采集Content-Type、Allow、Content-Length等所有响应头Set-Cookie已做安全处理显示为(已隐藏)关联查询系统审计日志中的log_id与 API 响应中的logId保持一致。前端在捕获 API 响应中的logId后可在上报操作日志时携带该字段从而实现操作日志 ↔ 系统审计日志 ↔ API 响应三端串联方便进行全链路问题排查。