在系统设计里“Everything You Do Is Being Recorded”不是一句警告而是一条工程原则。尤其是后台管理系统、金融系统、电商平台这类业务系统管理员或用户的每一次关键操作都应该留下可追溯的记录。这种记录在技术实现里通常叫“审计日志Audit Log”也叫“操作日志”。它和普通业务日志不一样普通日志关心“系统发生了什么、程序哪里报错”审计日志关心“谁在什么时间、从什么位置、对什么数据、执行了什么操作、结果如何”。很多项目一开始为了快速上线只在用户登录时写一行日志出问题后才发现既不知道谁改了数据也不知道修改之前的值是什么更无法证明某个审核流程是否合规。这篇文章会用一个“用户管理后台”的真实业务场景带读者从零搭一套最小可用的关键操作审计模块覆盖字段设计、AOP 采集、异步落库、日志检索、异常排查和生产实践。学习完成后你可以在自己的项目中快速落地一个可查询、可回溯、可扩展的审计日志链路。1. 先理解操作记录与审计日志的本质1.1 从“记录一切”到“记录该记录的”“记录一切”听起来简单但在工程上并不可行。如果在一个用户管理系统里把每一次查询、每一次按钮点击、每一个列表翻页全部落库一天之内就可能产生上亿条数据存储成本、检索成本和隐私合规风险都会迅速失控。真正合理的做法是记录“该记录的”。所谓“该记录的”通常满足下面几个条件之一操作会影响核心数据例如创建用户、修改角色、删除资源、调整价格、审批订单。操作涉及敏感权限例如修改管理员权限、导出用户明细、切换到其他租户。操作是高风险动作例如批量删除、重置密码、修改支付状态。操作与合规审查相关例如电商平台的订单退款、医院系统的病历修改。所以在设计审计日志模块之前先要确定“什么操作必须记录”而不是“把所有操作都记录下来”。这个判断标准也可以直接写进代码规范里避免每个开发人员自己决定是否记录。1.2 审计日志与普通日志的区别很多团队把审计日志和业务日志混在一起排查问题时先翻应用日志找到一条模糊的update user failed再去数据库查变更记录效率很低。根本原因是两者设计目标不同。对比项普通日志审计日志核心目的排查异常、分析性能、定位故障责任认定、合规审查、数据追溯典型内容时间、级别、类名、异常栈、调试信息操作人、操作时间、来源IP、操作类型、变更前后值、结果数据格式半结构化或纯文本可读性优先强结构通常以 JSON 或列表形式保存生命周期短期保留按磁盘空间滚动长期保留按合规周期归档安全要求不严格防篡改需要防篡改、访问权限控制消费方式开发者看、日志平台搜索审计人员、安全人员、程序化查询举例说明普通日志可能记录一行2025-06-01 10:00:00 ERROR delete user failed这只能说明程序出错了。审计日志则应该记录admin 在 2025-06-01 10:00:00 从 192.168.1.10 调用 deleteUser 接口删除 userId1001删除前用户名为张三操作结果失败失败原因是用户下存在未清空的订单。同样一件事后者能在几分钟内帮助核对“到底删了什么、为什么失败、是谁操作的”。1.3 审计日志的核心字段设计一张审计日志表首先要保证“查得回去”所以字段设计必须满足 5W1HWho、When、Where、What、Why、How。实际实现中建议至少包含下面这些字段。字段名含义示例是否必填id自增主键或雪花ID1000234是trace_id链路追踪ID关联业务日志7f3a8b2e4c9d是user_id操作人ID10086是user_name操作人名称admin是client_ip操作来源IP192.168.1.10是module功能模块user是operation操作类型DELETE_USER是request_methodHTTP方法DELETE否request_uri请求路径/api/v1/users/1001否target_id操作对象ID1001是before_data操作前的数据快照JSON场景需要after_data操作后的数据快照JSON场景需要result操作结果SUCCESS / FAIL是error_msg失败原因用户存在未清空订单否create_time操作时间2025-06-01 10:00:00是注意几处容易出错的地方。before_data和after_data不要只记录主键 ID要把关键业务字段以 JSON 快照保存。否则“把用户姓名从张三改成李四”这条审计日志没有价值。trace_id要从请求进入系统时生成贯穿整个调用链方便把审计日志和普通业务日志串联起来。result不能只记录成功失败操作同样需要记录。很多安全事故都发生在“失败的操作”被忽略的情况下例如多次尝试修改密码系统没有记录失败尝试也就无法发现爆破行为。2. 环境准备与项目结构2.1 技术选型与版本核对为了把注意力放在审计日志实现上示例项目采用常见 Java 后端技术栈。如果原始项目没有明确下面的版本落地前一定要先核对依赖版本避免因为 Spring Boot 版本差异导致 AOP 或异步注解配置不一致。组件或依赖用途版本建议JDK运行环境17 或 21Spring BootWeb 容器与自动配置3.2.x 或 2.7.xSpring AOP通过切面统一采集操作信息随 Spring Boot 引入MyBatis-Plus简化数据库操作3.5.xMySQL / H2业务库与审计日志存储MySQL 8.0 或 H2 2.xLombok简化 Java Bean 代码随项目配置学习环境可以直接使用 H2 内存库不需要安装 MySQL。生产环境建议使用 MySQL 或 PostgreSQL。为了贴近真实项目本示例以 MySQL 为例但建表语句在 H2 里也能兼容大部分。2.2 项目目录结构建议把审计日志相关代码独立成一个audit包便于后续扩展成独立模块或微服务。src/main/java/com/example/demo/ ├── DemoApplication.java ├── common/ │ └── context/ │ └── UserContext.java ├── audit/ │ ├── annotation/ │ │ └── AuditLog.java │ ├── aspect/ │ │ └── AuditLogAspect.java │ ├── entity/ │ │ └── AuditLogRecord.java │ ├── mapper/ │ │ └── AuditLogMapper.java │ ├── service/ │ │ └── AuditLogService.java │ └── AsyncConfig.java ├── controller/ │ └── UserController.java └── service/ └── UserService.java这个结构把切面、注解、实体、持久化分开后续即使要改成消息队列发送审计事件也可以只替换AuditLogService的实现。2.3 数据库表设计与初始化审计日志表使用独立表audit_log不要混入业务表。核心 DDL 如下CREATE TABLE IF NOT EXISTS audit_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, trace_id VARCHAR(64) NOT NULL, user_id BIGINT NOT NULL, user_name VARCHAR(64) NOT NULL, client_ip VARCHAR(64) NOT NULL, module VARCHAR(64) NOT NULL, operation VARCHAR(64) NOT NULL, request_method VARCHAR(16), request_uri VARCHAR(256), target_id VARCHAR(64), before_data JSON, after_data JSON, result VARCHAR(16) NOT NULL, error_msg VARCHAR(512), create_time DATETIME NOT NULL, INDEX idx_create_time (create_time), INDEX idx_user_id (user_id), INDEX idx_module_operation (module, operation) );索引设计要避免过多。生产环境按时间范围查询最频繁因此create_time索引必须有。user_id和module_operation是第二常见查询维度。不要给before_data、after_data两个大字段加索引否则会浪费大量磁盘和更新成本。如果是真正的海量数据场景建议按月分表或者直接写入 ClickHouse 之类的列式存储。3. 实现一个最小可复用的审计日志模块3.1 用注解标记需要记录的操作在 Spring Boot 项目中最简单的方式是定义一个注解AuditLog把模块名和操作类型写在注解上业务方法只需要标记这一行注解。package com.example.demo.audit.annotation; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface AuditLog { String module(); String operation(); }使用方式AuditLog(module user, operation CREATE_USER) public User createUser(UserCreateRequest request) { // 业务逻辑 }注解的价值在于把“哪里需要审计”变成声明式代码。相比在业务方法里手写日志注解方式统一性强后续要修改审计策略只需要修改切面代码不需要每个业务方法都改动。3.2 AOP 切面捕获操作上下文只有注解还不够真正做记录的是切面。这里使用Around环绕通知可以在方法执行前拿到请求参数在方法执行后拿到返回结果在异常时捕获异常信息。package com.example.demo.audit.aspect; import com.alibaba.fastjson2.JSON; import com.example.demo.audit.annotation.AuditLog; import com.example.demo.audit.entity.AuditLogRecord; import com.example.demo.audit.service.AuditLogService; import com.example.demo.common.context.UserContext; import jakarta.servlet.http.HttpServletRequest; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.reflect.MethodSignature; import org.slf4j.MDC; import org.springframework.stereotype.Component; import org.springframework.web.context.request.RequestContextHolder; import org.springframework.web.context.request.ServletRequestAttributes; import java.time.LocalDateTime; Aspect Component public class AuditLogAspect { private final AuditLogService auditLogService; public AuditLogAspect(AuditLogService auditLogService) { this.auditLogService auditLogService; } Around(annotation(auditLog)) public Object around(ProceedingJoinPoint joinPoint, AuditLog auditLog) throws Throwable { AuditLogRecord record buildRecord(joinPoint, auditLog); Object result; try { result joinPoint.proceed(); record.setResult(SUCCESS); return result; } catch (Throwable throwable) { record.setResult(FAIL); record.setErrorMsg(throwable.getMessage()); throw throwable; } finally { auditLogService.saveAsync(record); } } private AuditLogRecord buildRecord(ProceedingJoinPoint joinPoint, AuditLog auditLog) { MethodSignature signature (MethodSignature) joinPoint.getSignature(); ServletRequestAttributes attributes (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); AuditLogRecord record new AuditLogRecord(); record.setTraceId(MDC.get(traceId)); record.setModule(auditLog.module()); record.setOperation(auditLog.operation()); record.setCreateTime(LocalDateTime.now()); if (attributes ! null) { HttpServletRequest request attributes.getRequest(); record.setClientIp(getClientIp(request)); record.setRequestMethod(request.getMethod()); record.setRequestUri(request.getRequestURI()); } if (UserContext.get() ! null) { record.setUserId(UserContext.get().getUserId()); record.setUserName(UserContext.get().getUserName()); } Object[] args joinPoint.getArgs(); if (args.length 0) { record.setAfterData(JSON.toJSONString(args)); } return record; } private String getClientIp(HttpServletRequest request) { String ip request.getHeader(X-Forwarded-For); if (ip null || ip.isBlank()) { ip request.getRemoteAddr(); } return ip; } }这段代码里有几个关键点需要解释。MDC.get(traceId)用于获取链路追踪 ID。在请求入口处可以写一个过滤器或拦截器生成 traceId 后放入 MDC这样切面里能直接拿到普通业务日志也会自动带上同一个 traceId。RequestContextHolder.getRequestAttributes()只能在 Web 请求线程中拿到HttpServletRequest。如果业务方法在异步线程中执行切面就拿不到请求上下文这种情况不能依赖 Servlet 对象应该把 clientIp、requestUri 在进入异步线程前保存好。record.setAfterData(JSON.toJSONString(args))在这里只是把方法参数原样保存实际项目中往往会补充查询操作前快照。例如删除用户时参数中只有userId审计日志里最好要记“删除前用户名称”。这时可以在切面或业务方法里主动查询旧数据并放到一个专门传递额外信息的对象里。3.3 异步落库与失败处理审计日志的写入不能影响主流程性能也不能让审计逻辑阻塞业务事务。因此AuditLogService.saveAsync应该使用独立线程池异步执行。package com.example.demo.audit.service; import com.example.demo.audit.entity.AuditLogRecord; import com.example.demo.audit.mapper.AuditLogMapper; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.scheduling.annotation.Async; import org.springframework.stereotype.Service; Service public class AuditLogService { private static final Logger log LoggerFactory.getLogger(AuditLogService.class); private final AuditLogMapper auditLogMapper; public AuditLogService(AuditLogMapper auditLogMapper) { this.auditLogMapper auditLogMapper; } Async(auditLogExecutor) public void saveAsync(AuditLogRecord record) { try { auditLogMapper.insert(record); } catch (Exception e) { log.error(save audit log failed. record{}, record, e); } } }为什么一定要异步如果审计日志和业务方法在同一个事务里写数据库业务接口响应时间会多出一次 INSERT流量大的时候容易拖垮数据库。加上异步后审计写入对主流程的影响可以忽略。但这也带来一个新问题业务方法抛异常后方法的事务会回滚如果审计日志也在同一个事务里它也会跟着回滚。使用Async让审计方法在独立线程、独立事务中执行恰好可以避免“业务回滚导致审计记录消失”的问题。线程池需要单独配置指定队列大小和拒绝策略。package com.example.demo.audit; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; import java.util.concurrent.ThreadPoolExecutor; Configuration public class AsyncConfig { Bean(auditLogExecutor) public ThreadPoolTaskExecutor auditLogExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(4); executor.setQueueCapacity(1000); executor.setThreadNamePrefix(audit-log-); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }这里使用CallerRunsPolicy作为拒绝策略意思是任务队列满时新任务会在调用线程中执行。这样虽然会让业务线程偶尔多花一点时间写日志但能保证审计记录不会因为线程池打满而直接丢弃。生产环境还可以增加本地文件暂存或消息队列进一步降低丢失概率。4. 从审计日志到统一检索链路4.1 结构化日志输出审计日志落库后只解决了“查得到”的问题还无法方便地和普通业务日志联合检索。因此还需要把审计日志以结构化 JSON 格式输出到日志文件方便接入日志采集平台。在src/main/resources/logback-spring.xml中增加一个专门的审计日志 appenderconfiguration appender nameAUDIT_FILE classch.qos.logback.core.rolling.RollingFileAppender filelogs/audit.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePatternlogs/audit.%d{yyyy-MM-dd}.log/fileNamePattern maxHistory30/maxHistory /rollingPolicy encoder pattern%date{yyyy-MM-dd HH:mm:ss.SSS}|%msg%n/pattern /encoder /appender logger nameAUDIT_LOGGER levelINFO additivityfalse appender-ref refAUDIT_FILE/ /logger /configuration在切面中除了落库还可以同步输出 JSON 日志private static final Logger AUDIT_LOGGER LoggerFactory.getLogger(AUDIT_LOGGER); // saveAsync 方法中 AUDIT_LOGGER.info(JSON.toJSONString(record));为什么既要落库又要输出日志文件落库适合结构化查询比如按时间范围、用户、模块过滤日志文件适合接入 ELK 等日志系统做全链路检索也方便在数据库不可用时保留一份原始记录。两者可以并行但要控制幂等避免同一条记录在两边重复展示时造成混乱建议以traceId和记录自增 ID 关联。4.2 使用 Filebeat 采集日志到 Elasticsearch如果项目已经使用 ELK可以增加 Filebeat 采集audit.log文件。filebeat.inputs: - type: log enabled: true paths: - /opt/app/logs/audit.log fields: log_type: audit fields_under_root: true json.keys_under_root: true json.add_error_key: true output.elasticsearch: hosts: [http://localhost:9200] index: audit-log-%{yyyy.MM.dd}这里的关键配置是json.keys_under_root: true它会让 Filebeat 把 JSON 日志的字段直接展开到顶层这样在 Kibana 里可以直接用userName、operation这些字段检索而不需要嵌套解析。如果团队暂时没有 ELK也可以先用一条命令在本地做验证grep CREATE_USER logs/audit.log生产环境建议至少接入一个集中式日志平台避免登录服务器翻日志的低效方式。4.3 查询与回溯示例审计日志最常见的使用方式是回溯数据变更。假设有管理员反馈“用户张三的姓名被改成李四了”可以通过数据库表直接查询SELECT * FROM audit_log WHERE user_id 10086 AND target_id 1001 AND create_time 2025-06-01 00:00:00 ORDER BY id DESC LIMIT 20;如果检索历史数据发现多行嫌疑记录再通过trace_id去日志平台查这个请求经过了哪些服务、是否同一个用户、当时的参数是什么。在 Kibana 中使用 KQL 可以这样检索log_type: audit AND operation: UPDATE_USER AND userName: admin通过这种方式审计日志不再是一张孤立的数据库表而是和业务日志、服务调用链一起构成一条完整的溯源路径。5. 验证与效果检查5.1 手动触发一次操作并核对记录项目启动后先调用一个加了AuditLog注解的创建用户接口。例如使用 curl 请求curl -X POST http://localhost:8080/api/v1/users \ -H Content-Type: application/json \ -H X-User-Id: 10086 \ -H X-User-Name: admin \ -d {name:张三,email:zhangsanexample.com}这里为了演示方便使用请求头模拟登录用户。真实项目中应从登录后的上下文中获取用户信息不能信任前端传参。请求完成后查询audit_log表SELECT id, module, operation, user_name, client_ip, result, create_time FROM audit_log ORDER BY id DESC LIMIT 1;预期结果中module为useroperation为CREATE_USERuser_name为adminresult为SUCCESS。5.2 验证链路追踪 ID为了验证链路追踪是否生效可以专门写一个普通日志输出和审计日志一起检查。在 UserService 中输出log.info(create user start, traceId{}, MDC.get(traceId));在审计日志表中查询这一条记录后得到trace_id再到应用日志里搜索同一个 IDgrep 7f3a8b2e4c9d logs/application.log如果两处都出现了相同的traceId说明审计日志和业务日志可以串联。这一步很重要否则查询审计记录后还要手动猜测请求时间和相关服务排查效率会低很多。5.3 模拟异常看丢失情况可以故意让业务方法抛异常例如创建一个参数不完整的用户请求。切面应该在catch分支里把result设为FAIL但仍写入审计记录。curl -X POST http://localhost:8080/api/v1/users \ -H Content-Type: application/json \ -H X-User-Id: 10086 \ -d {email:no-name-user}此时接口返回错误但audit_log表中仍然会新增一条resultFAIL的记录并且error_msg记录了异常信息。如果这条记录没有出现需要检查Async方法是否因为业务线程的事务回滚而丢失或者线程池是否配置了直接丢弃策略。6. 常见问题排查6.1 注解加了但审计日志一直没有记录问题现象可能原因检查方式解决方案方法被调用但表里没有新数据切面没有生效查看启动日志确认AuditLogAspect是否被 Spring 扫描检查包扫描路径检查 Spring Boot 是否引入了spring-boot-starter-aop方法被调用但注解识别失败注解加在了私有方法上看方法是否是privateAround只能拦截 Spring 管理的公开方法改为public切面生效但异步方法异常线程池拒绝或数据库插入失败查看audit-log-线程池日志配置拒绝策略检查数据库权限和字段类型调用AuditLog注解方法时必须通过 Spring 容器注入的对象调用不能直接new一个 Service 对象否则 AOP 代理不会生效。6.2 业务事务回滚但审计日志仍然记录了这通常不是 bug而是异步事务隔离导致的预期行为。业务方法抛出异常事务回滚但AuditLogService.saveAsync在新线程中独立执行不受业务事务影响。如果没有使用Async而是在同一个线程里调用auditLogMapper.insert且方法有Transactional则业务回滚时审计日志也会一起回滚。问题现象可能原因检查方式解决方案业务失败后没有审计记录审计写入和业务在同一个事务查看方法或类上是否加了Transactional审计保存改为异步或使用REQUIRES_NEW传播级别异步写入线程失败日志丢失线程池异常被吞掉查看saveAsync里是否有 catch 块和 error 日志在 catch 中记录错误或转存本地文件6.3 审计表数据量增长很快查询越来越慢问题现象可能原因检查方式解决方案单表数据过千万查询耗时明显变长索引缺失或存储设计不适合大数据量使用EXPLAIN查看执行计划按月分表、归档历史数据、引入 ClickHouse大量查询没有走索引before_data等大字段被误加入查询条件查看慢查询日志只按索引字段查询JSON 字段用搜索服务6.4 时区和用户身份错误问题现象可能原因检查方式解决方案审计时间和服务本地时间相差 8 小时数据库时区与应用时区不一致执行SELECT NOW()对比服务时间统一使用 UTC 存储展示层转本地时区操作人信息不正确从请求参数获取用户身份查看切面中取值的代码从 SecurityContext 或登录态上下文获取不要信任前端参数7. 生产环境合规与最佳实践7.1 合规要求下的最小必要原则“Everything You Do Is Being Recorded”在工程上应该被理解为“关键操作必须记录”而不是“所有行为都要记录”。如果记录范围过大反而会带来隐私合规风险。生产实践要注意以下几点不要记录密码、Token、身份证全文、银行卡号等敏感字段必要时应脱敏。明确审计保留周期例如系统操作日志保留 180 天交易类审计日志保留 3 年并在删除策略里注明依据。对审计数据的访问同样需要权限控制只有审计管理员和合规人员才能查询。记录用户行为时要遵守最小必要原则只记录与业务审计直接相关的维度。7.2 防篡改思路审计日志一旦写入应当尽量保证不可修改、不可删除。在数据库层面可以撤销普通业务账号对audit_log表的更新和删除权限。如果业务场景对安全性要求更高可以考虑追加写入和哈希链方案每一条审计记录中保存上一条记录的哈希值任何中间记录被改动后续链路都会校验失败。// 示意生成审计记录时计算 hash String content record.getTraceId() record.getUserId() record.getCreateTime(); record.setRecordHash(Sha256Util.hash(content lastHash));写入后下一次插入前会读取上一条记录哈希一旦发现匹配不上就说明记录被篡改过。这个方案会增加写入成本适合敏感模块单独使用不适合全量操作日志都使用。7.3 保留周期与冷热分离审计数据是“高频写入、低频查询”的典型场景。可以把当前三个月的数据放在 MySQL 热表三个月前的数据定期归档到冷存储。归档任务可以使用定时任务每天执行一次-- 举例将 90 天前的数据移到 audit_log_archive INSERT INTO audit_log_archive SELECT * FROM audit_log WHERE create_time DATE_SUB(NOW(), INTERVAL 90 DAY); DELETE FROM audit_log WHERE create_time DATE_SUB(NOW(), INTERVAL 90 DAY);大批量DELETE要分批执行否则会产生大事务和锁表风险。更稳妥的做法是按分区整理例如按月份分区归档时直接DETACH PARTITION。7.4 可复用检查清单上线前可以用下面这个清单做一次审计日志体系检查是否明确列出了必须记录的操作清单。所有核心变更业务方法是否都加了AuditLog注解。审计记录是否包含traceId、用户、来源 IP、模块、操作类型、目标 ID、结果。操作前后快照是否只记录关键字段是否排除了敏感数据。审计写入是否异步执行线程池是否配置了拒绝策略。普通日志和审计日志是否都能通过traceId串联。审计表是否有按时间范围查询的索引。数据库账号权限是否限制了audit_log表的更新、删除权限。旧数据归档和保留周期是否有明确任务。对审计日志的查询入口是否做了权限控制和操作留痕。最后说一点实践建议审计日志不是一次性开发完的功能而是需要持续维护的基础设施。项目初期可以用注解加 AOP 快速落地当系统拆分微服务后再把审计事件发送到消息队列由独立审计服务统一落库和归档。无论采用哪种方式核心设计原则不变该记录的不能丢查得到的要快改不了才是可信的。对初学者来说先按本文示例跑通一条完整链路再逐步补充脱敏、索引优化和防篡改机制会比一开始就设计一个重量级平台更有效。