PII 别进 Logs / URL / Error:三平面红线与允许名单

PII 别进 Logs / URL / Error:三平面红线与允许名单

Hello,我是小兔大白糖。 排障最顺手的一招,往往是把「请求里看到的一切」打进日志、拼进 redirect URL、或原样塞进 API error.message——直到访问日志、客服截图、CDN 与 Referer 里开始长出手机号、邮箱和证件号。写成这篇,给要做 敏感数据出站边界 选型、或要和同事对齐「可观测面里到底能留什么」的后端同学。

估计阅读时间:8 分钟


先给结论:三处禁止明文 PII

PII / 个人身份信息(Personally Identifiable Information)应和密钥、token 同级当敏感载荷:默认不进可观测面,也不进对外文案。

读完希望你能带走三件事:

  1. 三平面 — 入口(URL / Header / Body)、可观测(Logs / Traces / Metrics)、对外(API error / 推送 / 邮件)各自有「可放 / 不可放」。
  2. 三条硬规则 — 日志只记关联键;URL 只传不透明句柄;对外错误只说类型,不说原文。
  3. 生产默认允许名单或统一 redact — 全量 dump 请求只适合本地无真实数据;别当「先上线再说」。

删掉后文所有表格和比喻,你仍应能复述这三条红线。


心智模型:机场广播 vs 值机柜台

我习惯用 机场广播 想这件事:

入口、可观测、对外三平面:各自可放与不可放
入口、可观测、对外三平面:各自可放与不可放 · 点击查看 SVG 原图
场景像什么你可以喊的不该喊的
入口平面(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 怎么选

下面不是某框架说明书,是后端里 常见落法归纳(公开概念,可和同事核对)。

全量 dump 与允许名单字段对照
全量 dump 与允许名单字段对照 · 点击查看 SVG 原图
模式典型做法优点代价 / 副作用适用
A. 全量 dump 请求打印整段 body / 整包 header排障极快泄露面最大;一进第三方日志即事故仅本地、无真实数据
B. 允许名单字段显式列出可记字段;其余默认丢弃默认安全面可控要维护白名单;新字段易漏审生产默认
C. 结构化 + 红线过滤器统一 logger middleware:对 key 名 / 正则做 redact漏记点少、改造成本集中有假阴性;仍要禁止「自由字符串塞 PII」生产加强
D. 关联键 + 安全旁路日志只有 id;需要原文走审计库 / 临时授权查看高合规友好排障多一步金融 / 医疗等高合规

教学基线:生产默认 B 或 C;永远不要把 A 当「先上线再说」。需要看原文时走 D,而不是把明文重新写回常规日志。


三条硬规则(Review 清单)

每条都是 可检验 的,不是「注意安全」口号。

  1. 日志只记关联键,不记业务原文
    user_id / request_id / 脱敏哈希可以;手机号明文、完整邮件、证件号不行。禁止把用户输入用字符串拼接进 log。

  2. URL 只传不透明句柄
    query / path 里放 state、一次性 code、业务 id。别把姓名、手机、邮箱拼进公开 URL——OAuth / 支付回调的 query 还会经 CDN、浏览器历史、Referer 二次扩散。对象存储 key / 文件名同理:URL 一样会进 CDN 日志。

  3. 对外错误只说类型,不说原文
    对用户 / 客户端返回稳定错误码 + 短文案;细节只留在服务端,且仍按规则 1 脱敏。客户端常把 error.message 直接弹窗——等于把内部细节当产品文案。


示意:失败路径只回传码,细节用 request_id 关联

全文尽量表格式说明;下面两段 伪流程 够用来对齐团队规范(教学示意,不是可编译代码)。

失败路径用 request_id 关联,不回传原文
失败路径用 request_id 关联,不回传原文 · 点击查看 SVG 原图
请求进入
  → 解析 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,又泄账户关系。


反模式:五类高频误判

结论:这些不是「内网就没事」,是公开信道默认写错了。

  1. 「日志在内网」
    备份、工单附件、供应商 SIEM、屏幕共享都会扩大面。内网不是脱敏豁免。

  2. 只脱敏手机号,忘了地址 / 备注自由文本
    自由文本是 PII 重灾区。应用「默认不记」,而不是「正则赌一把」。

  3. 搜索词 / GraphQL query 原样进 access log
    搜索词常含姓名。Access log 也是可观测面。

  4. Exception / stack 拼接用户输入
    框架一记异常,明文就进了日志管道。校验失败应记字段名与错误类型。

  5. 把 PII 放进对象存储 key 或文件名
    和 URL query 同类问题:链路节点都会留副本。


选型小结:三平面红线 + B/C 默认

场景建议别忘了的代价
生产日志默认B 允许名单 或 C 统一 redact白名单要审;redact 有假阴性
高合规要看原文D:审计旁路 + 临时授权排障路径变长,需演练
本地联调无真实数据A 可临时用一接真实流量立刻关掉
对外 API / 弹窗错误码表化 + 短文案产品文案要单独维护,别复用内部 detail

可复述给同事的三句话:

  1. Logs / URL / 对外 error 三处禁止明文 PII——和密钥同级。
  2. 生产用 允许名单或统一 redact;禁止把用户原文拼进日志。
  3. 对外只回 稳定错误码 + 短文案;详情用 request_id 在服务端关联——已泄露按事故处理(轮换会话、评估日志保留与删除),而不是「下次注意」。