cryptaudit —— 密钥使用审计:哪个 key 被用过
"这个字段是用哪把密钥加密的""上周那次解密失败到底是哪把 key"—— 合规审计要能回答 这类问题。业务代码解密 / 加密后调一行
cryptaudit.Record(ctx, ...),攒批、落库、 重试由框架负责。
功能
cryptaudit 解决一件事:把"哪把密钥被谁用过、成功还是失败"变成可查的表。
能力:
- 全量密钥使用记录 —— 不只 PII 字段,所有加密 / 解密 / 盲索引操作都能记。
- 失败也落库 ——
Success=false+ErrorMsg是排查"哪个 key 解不开"的直接线索 (直接 greperror_msg)。 - 异步攒批 —— 100 条或 5s 落一次库,单次插入按 50 条分片。
- ctx 上下文自动带 —— principal / request_id / trace_id / ip / user_agent。
- error_msg 按 rune 截断(200 字符),不劈开 UTF-8。
不解决:
配置
代码侧(没有构造选项)
cryptaudit 是包级单例,只有两个生命周期函数:
| 符号 | 说明 |
|---|---|
cryptaudit.Init(d *gorm.DB) |
启动期调一次(sync.Once 包着)。d == nil ⇒ 打一条 Warn(cryptaudit: db is nil, recorder disabled),但后台 loop 照样起 |
cryptaudit.Shutdown() |
退出前调一次,等最后一批 flush 完。幂等 |
攒批参数是包内常量 / 包级变量,不可配:batch 阈值 100、ticker tick = 5s、
重试 maxTry = 3、重试间隔固定 200ms、单次插入分片 CreateInBatches(cur, 50)。
⚠️ 与兄弟包的结构差异:piiaudit / smsaudit 的状态装在一个独立的 recorder 结构体里,
cryptaudit 用的是包级变量(db / batch / mu / stopCh / doneCh)。
所以本包里没有那种独立的 recorder 类型,测试里也拿不到未导出的 flush 入口。
yaml 侧(audit: 块)
configs/config.example.yaml 里确实有一个 audit: 块:
audit:
batch_size: 100
flush_interval: 5000 # ms(整数不带单位 —— 写成 "5s" 会让整份配置反序列化失败)
queue_size: 10000
⚠️ 这三个键本包不读。config.AuditConfig(internal/config/crypto.go)定义了它们,
但全仓零消费方 —— 三个审计包的攒批参数都写死在包内常量里。改 yaml 不生效。
使用方法
装配
cryptaudit.Init(repository.GetDB())
defer cryptaudit.Shutdown()
记一次成功的解密
cryptaudit.Record(ctx, cryptaudit.Event{
KeyID: "KEY_PII_V1",
KeyVersion: 1,
Algorithm: "aes-256-gcm",
Operation: "decrypt",
ResourceType: "user",
ResourceID: user.ID,
ByteCount: 11,
Success: true,
})
失败的也要记(这是本包最有用的一处)
cryptaudit.Record(ctx, cryptaudit.Event{
KeyID: "KEY_PII_V1",
KeyVersion: 1,
Algorithm: "aes-256-gcm",
Operation: "decrypt",
Success: false,
ErrorMsg: err.Error(),
})
Event 字段
| 字段 | 类型 | 说明 |
|---|---|---|
KeyID |
string |
密钥标识(env var 名 / KMS key id) |
KeyVersion |
int |
密钥版本(轮转用) |
Algorithm |
string |
"aes-256-gcm" / "hmac-sha256" / ... |
Operation |
string |
"encrypt" / "decrypt" / "blind-index" |
ResourceType |
string |
"user" / "order" / ... |
ResourceID |
uint64 |
资源 ID |
ByteCount |
int |
处理字节数 |
Success |
bool |
成没成 |
ErrorMsg |
string |
失败原因(按 rune 截到 200) |
完整可运行示例
examples/cryptaudit/main.go —— go run ./examples/cryptaudit
示例里手写 DDL 建表(框架示例不许 import 业务模型),成功 / 失败两条路径各记一条。
注意事项
- ⚠️ 攒够 100 行是
go flush()—— 异步的。这跟 piiaudit / smsaudit 不同(那两个是 同步r.flush())。后果:"显式 flush 返回"不等于"数据已经落库" —— 谁先拿到锁 谁插入,另一个看到空批次直接返回。测试因此只能记 80 行而不是 100 行:正好 100 行 会触发那次异步 flush,和显式 flush 抢同一批数据,查询可能读到 0 行 ⇒ 偶发红。 这条推理写在源码注释里(cryptaudit_test.go的TestRecord_FlushesRow)。 - ⚠️ 主键必须自己填(雪花)。
model.BaseModel.ID的 tag 是primaryKey;autoIncrement:false—— GORM 不会让库自增,零值 0 原样入库 ⇒ id 撞主键 ⇒ 第二批往后的行全部插不进去(整批重试 3 次后丢弃)⇒sys_crypto_audit_log永远只有 1 行。本包用model.BaseModel{ID: sonyflake.Next()}补上了(M100 修的)。 - ⚠️
Record开头是if db == nil { return }—— 没Init时它直接返回,连 ctx 那一段都走不到。单元测试里如果忘了先Init,"ctx 为 nil 不 panic" 这类用例会 假绿。 - ⚠️
Init(nil)也会起后台 goroutine(run()),而 piiaudit / smsaudit 的Init(nil)直接 return、不起 loop。三兄弟行为不一致,写文档或排查时别互相套用。 - ⚠️ 丢批次的日志级别比兄弟包低一级:cryptaudit 重试 3 次全失败后只打一条
Warn(
cryptaudit flush failed),piiaudit / smsaudit 打的是 Error (...after retries, dropping)。同一个故障在两个包里看起来严重程度不一样,排障时 容易漏掉 cryptaudit 那条。 - ⚠️
flush()在db == nil时是"先取走批次再返回"。代码顺序是先batch = nil再判if db == nil { return }⇒ 批次数据被静默丢弃。正常路径碰不到(Record在 db 为 nil 时就不写),但如果你绕过Record往包里塞数据,会丢得无声无息。 - ⚠️ error_msg 按 rune 截断到 200,不是按字节。原来
errMsg[:200]是字节切片 —— 一个中文错误信息(3 字节/字)正好在第 200 字节被劈开,落库就是一个半个汉字 + 乱码尾巴。排障时看到这种 error_msg,第一反应会变成"程序写错了",而不是"被截断了"。 - ⚠️ 重试间隔固定 200ms,不指数退避。3 次尝试各失败一次就是 3 × 200ms。sleep 发生
在锁外,所以不阻塞
Record—— 但 flush 协程自己会挂在那儿。 - ⚠️
Operation/Algorithm是自由字符串,没有常量约束(不像 piiaudit 的action/field在internal/model里有常量)。写错不会编译报错,只会让聚合查询 对不上。 - ⚠️ 落库是异步的,
Shutdown()幂等。进程退出前不调Shutdown(),最后一批(最多 99 条)会丢;重复调Shutdown()不会再 panic(M100 改的,原来第二次会 close 已关闭的 channel)。 - ⚠️
Shutdown()之后还能Record,但大多数数据不会落库。后台 loop 已退出,不再有 5s 定时 flush;只有攒到 100 条触发go flush()分支才会写下去。