auditx —— 数据变更审计(sys_data_change_log 自动写入器)
「谁在什么时候把 X 改成了 Y」要当证据用,但让每个业务 service 手写 before/after 快照必然漏。auditx 对白名单表注册 GORM 回调 (create / update / delete),操作人从 ctx 取,before/after 快照落
sys_data_change_log—— 业务写与审计写同一个连接/事务, 业务回滚审计行也不存在(证据一致性)。 与 piiaudit(看了什么)/ cryptaudit(密钥用了没) 同属审计族,它回答的是改了什么。
功能
- 白名单制,不是所有表都记:流水类表(日志 / 会话 / 验证码)再记一层是套娃;
新增表要"当证据用"才进白名单(默认首批 8 张:
biz_project/biz_building/biz_house/biz_user/biz_supplier/contract/sys_user/sys_role); - update 只记 diff:before/after 只含变化的列(
{col: {old, new}}), 没变不记,RowsAffected == 0不记; - 凭据材料绝不进快照:
password/password_hash/secret/token全局跳过,_nonce/_aad/_hash后缀跳过,created_at/updated_at/deleted_at跳过; - 审计写失败不炸业务:写
sys_data_change_log失败只打 warn; - 显式通道:裸 SQL 写路径(GORM 回调打不着)走
RecordChange手动记。
数据落点
表 sys_data_change_log(model.SysDataChangeLog):
table_name / record_id / operation(1 新增 / 2 修改 / 3 删除)/
before / after(JSON 文本,单值超长按 MaxValueLen 截断)/
user_id / username。
使用方法
装配一次(DB 初始化后,只对服务运行时的 db 调 —— 片段出自 cmd/server/main.go):
if err := auditx.Install(db, auditx.Config{
LookupCaller: func(ctx context.Context) (uint64, string) {
if c, ok := service.FromContext(ctx); ok {
return c.UserID, c.Username
}
return 0, ""
},
Logger: log,
}); err != nil {
log.Warn("auditx install failed; 数据变更审计未启用", zap.Error(err))
}
业务 service 一行不用改 —— 回调挂在白名单表上自动生效。
操作人来自 Auth 中间件 WithCaller 注入的 service ctx,取不到记 system
(seed / migrate / cron 的后台写记 system 是"诚实的")。
显式通道(裸 SQL / 钩子打不着的写路径 —— 片段出自 examples/auditx/main.go):
// 二、RecordChange:显式通道,给裸 SQL 写路径用(GORM 回调打不着的地方)
err = auditx.RecordChange(context.Background(), db, "demo_user", auditx.OpUpdate, 42,
map[string]any{"status": "pending"},
map[string]any{"status": "approved"})
跑最小示例(内存 sqlite,不真连):
go run ./examples/auditx
装配项(Config)
| 字段 | 说明 |
|---|---|
LookupCaller |
从 ctx 取操作人;nil 或查不到 ⇒ 记 system |
Logger |
审计写入失败 warn 用的 zap;nil = Nop |
Rules |
白名单 []TableRule{Table / Prefix / Skip};nil/空 = 默认 8 张;Prefix 给 dyn_ 运行时建的物理表用 |
MaxValueLen |
快照单值截断长度,默认 1000,截断后追加 "…(截断)" |
关键纪律
- 同事务证据一致性是底线:审计行与业务写同一连接/事务,业务回滚 审计行一起消失;不追求"回滚了也留痕";
- Install 只装服务运行时的 db:
cmd/migrate用自己的 db 实例不 Install, 建表灌种子天然不被审计; - 取证不了就放过,不硬凑:批量写 / 取不到主键 / before 没拿到 ⇒ 不审计 (操作日志那层有记录);审计写失败只 warn,绝不影响业务写;
- dyn_* 裸 SQL 路径钩子打不着,必须显式调
RecordChange—— 且它对 table 空 / id=0 静默返回 nil,不会提醒你漏了; - 防递归靠白名单天然截止:
sys_data_change_log自己不在白名单里; - 凭据 / 密钥材料绝不进快照 —— 落进 5 年期证据表的东西没有读者、只有风险。