密钥脱敏（secret redaction） 安全与工程

它是什么

密钥脱敏（secret redaction）指对敏感配置在输出前的遮蔽处理：按键名判定敏感项（键名含 api_key / token / secret / password，大小写不敏感），只保留前几个字符、其余替换为掩码。比如 sk-live-secret-1234 → sk-l****；非敏感项原样显示。它防的是「日志里的被动泄漏」，不是加密——不防进程内存被读（那是操作系统与部署层的事），只是保证：日志系统、报错输出、调试面板被访问时，凭据不会跟着被拖走。

在哪里做

配置合并完成后，apiKey 在进程里是明文（调用 provider 需要），但任何输出通道都要脱敏：打印有效配置、写启动日志、报错信息里带上配置时，一律走脱敏后的视图。这与结构化日志天然联动——第 20 章的事件行、trace、失败看板是日志泄漏的高发区，所以第 23 章的纪律是「打日志前先过脱敏」。OWASP 的 Logging Cheat Sheet 把「不要记录敏感数据、必要时掩码」列为日志安全的核心要求。

小结

脱敏是 Agent 产品里最后一道配置防线：密钥管理（不进代码、不进 git）管的是「放哪」，脱敏管的是「说出口时」。三道工序缺一不可——.env 里躺着明文没关系，但任何一行日志、任何一个报错里都不能有它。