
Hello,我是小兔大白糖。 排障最顺手的一招,往往是把「请求里看到的一切」打进日志、拼进 redirect URL、或原样塞进 API error.message——直到访问日志、客服截图、CDN 与 Referer 里开始长出手机号、邮箱和证件号。写成这篇,给要做 敏感数据出站边界 选型、或要和同事对齐「可观测面里到底能留什么」的后端同学。
估计阅读时间:8 分钟
先给结论:三处禁止明文 PII
PII / 个人身份信息(Personally Identifiable Information)应和密钥、token 同级当敏感载荷:默认不进可观测面,也不进对外文案。
读完希望你能带走三件事:
- 三平面 — 入口(URL / Header / Body)、可观测(Logs / Traces / Metrics)、对外(API error / 推送 / 邮件)各自有「可放 / 不可放」。
- 三条硬规则 — 日志只记关联键;URL 只传不透明句柄;对外错误只说类型,不说原文。
- 生产默认允许名单或统一 redact — 全量 dump 请求只适合本地无真实数据;别当「先上线再说」。
删掉后文所有表格和比喻,你仍应能复述这三条红线。
心智模型:机场广播 vs 值机柜台
我习惯用 机场广播 想这件事:
| 场景 | 像什么 | 你可以喊的 | 不该喊的 |
|---|---|---|---|
| 入口平面(URL / Header / Body) | 登机牌上的条码 | 不透明 state、一次性 code、业务 id | 姓名、手机、邮箱拼进公开 query |
| 可观测平面(Logs / Traces / Metrics) | 航站楼大屏 / 运维监控 | request_id、user_id、字段名、错误类型 | 手机号明文、完整邮件、证件号、自由文本原文 |
| 对外平面(API error / 推送 / 邮件) | 对旅客广播 | 稳定错误码 + 短文案(「请检查手机号格式」) | 「138xxxx 已注册给某账号」这类关系泄露 |
这个比喻管 「公开信道只放关联键」 很顺手;管不了 合规清单里「哪些字段算 PII、保留多久」——那是策略与法务边界,本文只谈工程出站默认。
精确定义:什么叫「别塞进可观测面」
可观测面 = 日志、链路追踪属性、指标 label、访问日志、以及任何会进备份 / SIEM / 工单附件的文本通道。
对外平面 = 客户端可见的 HTTP body、弹窗文案、推送、邮件——用户能截图转发的都算。
边界之内的默认约定:
- 可记:关联键(
user_id/request_id)、字段名、错误类型、脱敏哈希(按团队约定)。 - 不可记:手机号 / 邮箱 / 证件号明文、精确地址、备注与搜索词等自由文本原文。
- Metrics label 同样不能塞高基数 PII——除了隐私,还会打爆时序库基数。
边界之外:业务处理当然要用明文做校验与落库;只是 处理完不要把原文抄到上述平面。Exception message / stack 里若拼接了用户输入,等于给可观测面开了后门。
业界模式对照:A~D 怎么选
下面不是某框架说明书,是后端里 常见落法归纳(公开概念,可和同事核对)。
| 模式 | 典型做法 | 优点 | 代价 / 副作用 | 适用 |
|---|---|---|---|---|
| A. 全量 dump 请求 | 打印整段 body / 整包 header | 排障极快 | 泄露面最大;一进第三方日志即事故 | 仅本地、无真实数据 |
| B. 允许名单字段 | 显式列出可记字段;其余默认丢弃 | 默认安全面可控 | 要维护白名单;新字段易漏审 | 生产默认 |
| C. 结构化 + 红线过滤器 | 统一 logger middleware:对 key 名 / 正则做 redact | 漏记点少、改造成本集中 | 有假阴性;仍要禁止「自由字符串塞 PII」 | 生产加强 |
| D. 关联键 + 安全旁路 | 日志只有 id;需要原文走审计库 / 临时授权查看 | 高合规友好 | 排障多一步 | 金融 / 医疗等高合规 |
教学基线:生产默认 B 或 C;永远不要把 A 当「先上线再说」。需要看原文时走 D,而不是把明文重新写回常规日志。
三条硬规则(Review 清单)
每条都是 可检验 的,不是「注意安全」口号。
-
日志只记关联键,不记业务原文
user_id/request_id/ 脱敏哈希可以;手机号明文、完整邮件、证件号不行。禁止把用户输入用字符串拼接进 log。 -
URL 只传不透明句柄
query / path 里放state、一次性 code、业务 id。别把姓名、手机、邮箱拼进公开 URL——OAuth / 支付回调的 query 还会经 CDN、浏览器历史、Referer 二次扩散。对象存储 key / 文件名同理:URL 一样会进 CDN 日志。 -
对外错误只说类型,不说原文
对用户 / 客户端返回稳定错误码 + 短文案;细节只留在服务端,且仍按规则 1 脱敏。客户端常把error.message直接弹窗——等于把内部细节当产品文案。
示意:失败路径只回传码,细节用 request_id 关联
全文尽量表格式说明;下面两段 伪流程 够用来对齐团队规范(教学示意,不是可编译代码)。
请求进入
→ 解析 user_id / request_id(可记)
→ body.phone / body.id_number → 只进业务处理,不进 logger
→ 失败:返回 code=INVALID_PHONE +「手机号格式不正确」
→ 服务端:log.warn(request_id, field=phone) // 无原文反例(不要):
log.error("bad phone: " + req.Phone)
return 400, "phone 13800138000 already used by " + other.Email
redirect "/callback?email=" + email + "&name=" + name要点就两句:业务原文留在处理路径;可观测与对外只留类型 + 关联键。对用户说「请检查手机号格式」可以;说「手机号 138xxxx 已注册给 user_xxx」不行——既泄 PII,又泄账户关系。
反模式:五类高频误判
结论:这些不是「内网就没事」,是公开信道默认写错了。
-
「日志在内网」
备份、工单附件、供应商 SIEM、屏幕共享都会扩大面。内网不是脱敏豁免。 -
只脱敏手机号,忘了地址 / 备注自由文本
自由文本是 PII 重灾区。应用「默认不记」,而不是「正则赌一把」。 -
搜索词 / GraphQL query 原样进 access log
搜索词常含姓名。Access log 也是可观测面。 -
Exception / stack 拼接用户输入
框架一记异常,明文就进了日志管道。校验失败应记字段名与错误类型。 -
把 PII 放进对象存储 key 或文件名
和 URL query 同类问题:链路节点都会留副本。
选型小结:三平面红线 + B/C 默认
| 场景 | 建议 | 别忘了的代价 |
|---|---|---|
| 生产日志默认 | B 允许名单 或 C 统一 redact | 白名单要审;redact 有假阴性 |
| 高合规要看原文 | D:审计旁路 + 临时授权 | 排障路径变长,需演练 |
| 本地联调无真实数据 | A 可临时用 | 一接真实流量立刻关掉 |
| 对外 API / 弹窗 | 错误码表化 + 短文案 | 产品文案要单独维护,别复用内部 detail |
可复述给同事的三句话:
- Logs / URL / 对外 error 三处禁止明文 PII——和密钥同级。
- 生产用 允许名单或统一 redact;禁止把用户原文拼进日志。
- 对外只回 稳定错误码 + 短文案;详情用
request_id在服务端关联——已泄露按事故处理(轮换会话、评估日志保留与删除),而不是「下次注意」。