《日志里别裸奔：vibe 项目的日志脱敏与 PII 治理实战》

开篇：先划清三篇的边界

开始之前先说明本文在本站内容体系里的位置，避免和已发指南混淆。已经发布的《数据主体请求（DSR）响应指南》是法务流程侧的文章：讲用户行使删除权、访问权时，你作为一人团队要在多少天内走完什么 SOP、留什么证据；已经发布的《RBAC 权限指南》里也有"审计日志"一节，但那一节只回答两个问题——记什么、谁可查，是权限视角。而本篇是工程侧的文章：回答的是日志内容本身怎么治理——哪些字段不能落盘、脱敏代码怎么写、结构化日志怎么改造、日志留多久、云账单怎么控。三篇视角正交，互为补充：DSR 告诉你"用户要求删数据时要做什么"，RBAC 告诉你"日志谁有资格看"，本篇告诉你"日志里到底该写什么、不该写什么"。

目标读者很具体：你的项目里 console.log 遍地开花，用户邮箱、登录 token 被原样打进 Sentry 和云日志；你隐约觉得这有合规风险，但不知道从哪下手。本文给你一套一人团队一天能落地的完整方案：分级表、脱敏代码、迁移步骤、中间件模板、保留策略、成本账，外加 8 个真实踩坑。

一、先看血案：四种真实泄露模式

先不谈理论，看四个在 vibe 项目里反复出现的真实泄露模式。你可以现在就去自己的 Sentry / 云日志控制台搜一遍，大概率能命中至少一个。

模式 1：URL query 里的 token 被 access log 全量记录

魔法链接登录、微信扫码回调、密码重置链接，token 都长在 URL 的 query 参数里：/auth/callback?token=eyJhbGciOi…。而绝大多数请求日志中间件会原样记录完整 URL。结果是：任何一个能看日志的人，都能拿着这个 token 直接登录用户账号。token 在日志里的有效期，等于你的日志保留期——通常是 30 天，远长于 token 本身的 15 分钟有效期。

模式 2：错误堆栈带着整包请求体进了 Sentry

表单提交接口抛了个 500，Sentry 的 issue 里躺着完整的 request.data：姓名、手机号、身份证号，一个不少。Sentry 的上下文采集默认很"热心"，而 AI 生成的错误处理代码从不做过滤。更糟的是，Sentry 数据还会被它的 AI 功能（Seer 之类）拿去分析，等于你的用户 PII 又多了一次流转。

模式 3：AI prompt 日志含用户原文

为了调试 AI 功能，你把用户输入原文打进日志："prompt 长度 1200，内容：……"。用户在你的 AI 客服里粘贴了合同、病历、工资条——全进了日志系统。prompt 日志是 vibe 项目特有的新泄漏面，传统脱敏方案根本覆盖不到。

模式 4：第三方 SDK 偷偷打日志

统计 SDK、崩溃 SDK、客服 SDK，在 debug 构建里往 console 倾倒设备信息、用户标识，你上线时忘了关。你的脱敏层管得住自己的代码，管不住 node_modules 里的代码。

为什么 vibe 项目是重灾区

三点原因都很"vibe"：第一，AI 写代码时极爱加 console.log("user:", user) 这种调试语句，上线前没人逐行审查；第二，一人团队追求速度，"先跑起来"的日志永远欠着清理；第三，日志不像数据库，没有 schema 约束，什么都能往里塞，也就什么都会漏。补救思路只有一条：把脱敏做成流水线的一个环节，而不是靠人的自觉。

二、PII 四级分级表：先分类，再谈脱敏

脱敏最大的误区是一刀切：要么全记（裸奔），要么全禁（日志没法看）。正确做法是先分级。注意分级的依据不是字段名，而是组合识别能力——单独一个 userId 没什么，但 userId + 时间戳 + IP 就能定位到人，它就升级为准标识符。

图 2：PII 四级分类 × 处理策略矩阵。L3 直接标识符禁止落盘；L2 准标识符掩码输出；L1 行为数据哈希化；L0 公开数据原样记录。

四个级别的具体定义如下。L3直接标识符：身份证号、银行卡号、密码、各类 token、生物特征。处理策略是禁止落盘——不是脱敏，是根本不许出现在任何日志里；保留时长为不留存；泄漏风险极高。L2准标识符：邮箱、手机号、真实姓名。单独看定位能力弱，但组合起来能定位到人。处理策略是掩码输出（如 138****5678），且不与行为数据记在同一条日志里；保留 30 天且存储加密；风险高。L1行为数据：userId（哈希后）、页面路径、设备型号、功能点击。处理策略是哈希化后聚合使用；保留 30 天；风险中。L0公开数据：版本号、环境标识、错误码、接口路径模板（注意是模板 /users/:id，不是带真实 id 的完整路径）。可原样记录；保留 90 天；风险低。

落地建议：把这张表打印出来贴在显示器旁边，或者写进仓库的 docs/logging-policy.md。以后任何"这个字段能不能记"的争论，查表 10 秒钟解决，不用每次重新发明标准。

三、脱敏三件套：可直接复制的 TypeScript 代码

脱敏不要只做一层。三件套各管一面：正则黑名单管自由文本里的裸 PII（兜底），字段名黑名单管结构化对象里的敏感键（主力），深度 redact 函数把两者递归应用到任意嵌套对象。下面这份代码是本文随文在 Node 24 下实际运行验证过的，可直接放进你的 lib/redact.ts。

件套 1：正则黑名单（字符串级兜底）

const REDACTION_PATTERNS = [
  { name: "email",  re: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, mask: "[EMAIL]" },
  { name: "phone",  re: /(?<!\d)1[3-9]\d{9}(?!\d)/g,                 mask: "[PHONE]" },
  { name: "idcard", re: /(?<!\d)\d{17}[\dXx](?!\d)/g,                mask: "[ID]" },
  { name: "card",   re: /(?<!\d)(?:\d[ -]?){13,19}(?!\d)/g,          mask: "[CARD]" },
];

function redactString(s: string): string {
  let out = s;
  for (const p of REDACTION_PATTERNS) out = out.replace(p.re, p.mask);
  return out;
}
// redactString("用户 lee@example.com，手机 13812345678")
// → "用户 [EMAIL]，手机 [PHONE]"

注意两个细节：手机号和身份证都用了前后否定断言 (?<!\d) / (?!\d)，实测订单号 202610150001 这类长数字不会被误伤；但银行卡正则比较宽泛，误伤率最高，所以它只做兜底，不做主力。

件套 2 + 3：字段名黑名单与深度 redact（主力）

const SENSITIVE_KEYS = new Set([
  "password", "passwd", "secret", "token", "accesstoken",
  "refreshtoken", "apikey", "api_key", "authorization",
  "cookie", "set-cookie", "ssn", "idcard", "bankcard",
]);

function redactDeep(value: unknown, seen = new WeakSet()): unknown {
  if (typeof value === "string") return redactString(value);
  if (value === null || typeof value !== "object") return value;
  if (seen.has(value)) return "[Circular]"; // 循环引用不爆栈
  seen.add(value);
  if (Array.isArray(value)) return value.map((v) => redactDeep(v, seen));
  const out: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(value)) {
    const norm = k.toLowerCase().replace(/[_-]/g, "");
    out[k] = SENSITIVE_KEYS.has(norm) ? "[REDACTED]" : redactDeep(v, seen);
  }
  return out;
}

// userId 只记哈希：同一用户可关联分析，但无法反解
import { createHash } from "crypto";
function hashUserId(userId: string | number, salt: string): string {
  return createHash("sha256").update(`${salt}:${userId}`).digest("hex").slice(0, 16);
}

键名做了归一化（去下划线/连字符、转小写），所以 api_key、API-KEY、accessToken 都会命中。实测验证：嵌套对象里的邮箱、手机号、password、token 全部被正确替换，循环引用返回 [Circular] 而不是抛错。把 redactDeep 作为所有日志出口的统一前置，你就有了"脱敏层"。

一个关键约定：脱敏发生在进程内、日志落盘之前，而不是事后去云日志控制台做字段屏蔽。事后屏蔽管不住已经泄露的 30 天历史数据，也管不住 Sentry 这种直连第三方 SDK 的通道。下面的流水线图展示了脱敏层在整个链路中的位置。

图 1：日志脱敏流水线。日志产生后必须先过进程内脱敏层，再经 TLS 传输到分级存储与第三方服务；未脱敏的日志禁止直通下游。

四、从 console.log 到 pino：最小迁移三步

结构化日志是脱敏的前提：只要你还在打非结构化的 console.log("用户" + user.email + "下单")，正则就是你唯一的防线，迟早漏网。迁移到 pino（或 winston）只需要三步，一个下午能做完。

第一步：建统一 logger，脱敏内建

// lib/logger.ts
import pino from "pino";
import { redactDeep, hashUserId } from "./redact";

const SENSITIVE_PATHS = [
  "password", "token", "*.password", "*.token",
  "req.headers.authorization", "req.body.password",
];

export const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  redact: { paths: SENSITIVE_PATHS, censor: "[REDACTED]" },
  serializers: {
    // pino 内置 err 序列化只取 message/stack，不会把整包上下文带出来
    err: pino.stdSerializers.err,
  },
});

// 统一出口：先过 redactDeep 再写日志
export function logInfo(obj: object, msg: string) {
  logger.info(redactDeep(obj), msg);
}

pino 自带的 redact.paths 是第二道保险：即使有人绕过 logInfo 直接调 logger.info，路径命中的字段依然会被打码。双保险的思路是：一道在你手里（redactDeep），一道在库里（pino redact）。

第二步：字段约定（团队只有你，也要写下来）

约定四条，写进 docs/logging-policy.md：第一，用户标识只记 userHash（hashUserId 的结果），禁止记邮箱、手机号明文；第二，请求日志记 method + 路径模板 + 状态码 + 耗时，不记完整 URL 和整包 body；第三，错误日志记 err.message + err.stack（pino 序列化后的），上下文只带白名单字段；第四，AI 调用记 promptHash + promptLength + tokensUsed + model，不记 prompt 原文。

第三步：杀死裸 console.log

在 ESLint 里加 "no-console": "error"，存量代码用一次全局替换迁到 logInfo。Serverless / Vercel 环境注意：pino 默认写 stdout，多实例下用 pino.transport 批量发往云日志，避免每个请求都建连接。迁移完成后，你的日志从"一堆字符串"变成了"一堆可查询、可脱敏的 JSON"，后面所有的保留策略、成本控制、合规动作都建立在这一步上。

五、请求日志中间件：query / body / headers 分开治

请求日志是泄露的重灾区，因为一次请求把三个泄漏面集齐了：query（token）、headers（authorization、cookie）、body（表单 PII）。模板的核心思想是三个面用三种规则，不要一个 redactDeep 打天下。

Express 中间件模板

// middleware/requestLog.ts
import { redactDeep, hashUserId } from "../lib/redact";
import { logInfo } from "../lib/logger";

// query 里这些参数一律丢弃，只记参数名不记值
const QUERY_BLACKLIST = new Set(["token", "code", "state", "password", "email", "phone"]);

function sanitizeQuery(query: Record<string, unknown>) {
  const out: Record<string, string> = {};
  for (const k of Object.keys(query)) {
    out[k] = QUERY_BLACKLIST.has(k.toLowerCase()) ? "[REDACTED]" : "[PRESENT]";
  }
  return out;
}

export function requestLogger(req, res, next) {
  const start = Date.now();
  res.on("finish", () => {
    logInfo(
      {
        method: req.method,
        route: req.route?.path ?? req.path, // 路径模板，不带真实 id
        status: res.statusCode,
        ms: Date.now() - start,
        query: sanitizeQuery(req.query),
        // headers 只白名单放行，其余一律不记
        headers: { "user-agent": req.headers["user-agent"], "x-request-id": req.headers["x-request-id"] },
        userHash: req.user ? hashUserId(req.user.id, process.env.LOG_SALT!) : undefined,
        // body 默认不记；排查需要时只记白名单字段
        body: req.body ? redactDeep(pick(req.body, ["action", "itemId"])) : undefined,
      },
      "http request"
    );
  });
  next();
}

三个关键决策都在代码里：query 黑名单参数只记"出现过"，不记值——既保留了排查线索（"这次请求带了 token 参数"），又不泄露内容；headers 用白名单而非黑名单，因为 headers 里藏东西的方式太多（cookie、x-api-key、各种自定义头），黑名单永远列不完；body 默认不记，需要时用 pick 只取排查必需的字段。

Next.js App Router 版本

App Router 没有 Express 式的 req.route.path，路径模板需要自己维护一个路由表做匹配；更简单的做法是在每个 route handler 里包一层 withLogging(handler, { route: "/api/orders/[id]" })，把模板当参数传进去。middleware.ts（边缘运行时）里不要打业务日志——Edge Runtime 没有 Node crypto，hashUserId 跑不起来，边缘层只记 method + 路径 + 状态码 就够了，脱敏重的活留给 Node 运行时。

六、第三方服务侧：Sentry、云日志、AI 调用

进程内脱敏管得住自己的日志，管不住直接连第三方 SDK 的数据。这三处要单独处理。

Sentry：beforeSend 是最后一道门

// sentry.client.config.ts
import * as Sentry from "@sentry/nextjs";
import { redactDeep, hashUserId } from "./lib/redact";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  beforeSend(event) {
    // 1. 用户标识只留哈希
    if (event.user) {
      event.user = {
        id: event.user.id ? hashUserId(event.user.id, process.env.LOG_SALT!) : undefined,
      };
    }
    // 2. 请求体整包脱敏；URL 里的 query 参数剥掉
    if (event.request) {
      event.request.data = redactDeep(event.request.data);
      event.request.url = event.request.url?.split("?")[0];
      delete event.request.headers?.cookie;
      delete event.request.cookies;
    }
    // 3. breadcrumb 里可能藏着 console 输出，再过一遍
    event.breadcrumbs = event.breadcrumbs?.map((b) => ({
      ...b,
      data: redactDeep(b.data),
    }));
    return event;
  },
});

特别注意 event.request.url?.split("?")[0] 这一行：Sentry 默认会记录完整 URL，query 里的 token 不剥掉，前面所有的努力白费。另外检查 Sentry 项目的"数据 scrubbing"设置，把服务端的字段屏蔽规则也打开，双保险。

云日志：字段屏蔽 + 日志排除

各云厂商的日志服务都支持在入库前丢弃或屏蔽字段（GCP 叫 Log Exclusions，AWS CloudWatch 叫 Metric Filter/Subscription Filter 配合，阿里云 SLS 叫数据加工）。通用做法：建一条排除规则，把 jsonPayload.password、jsonPayload.token 这类路径直接丢弃；对采样率高的 access 日志，可以只保留错误级别入库，info 级只进低成本的冷存储。这是"事后屏蔽"，只能当补充——进程内脱敏才是主力，原因第二节已经讲过：历史数据和直连通道它都管不住。

AI 调用日志：prompt 只记哈希和长度

import { createHash } from "crypto";
import { logInfo } from "./lib/logger";

export async function callLLM(prompt: string, opts: { model: string }) {
  const t0 = Date.now();
  const promptHash = createHash("sha256").update(prompt).digest("hex").slice(0, 16);
  try {
    const res = await llm.chat(prompt, opts);
    logInfo(
      { model: opts.model, promptHash, promptLength: prompt.length,
        tokensUsed: res.usage.totalTokens, ms: Date.now() - t0 },
      "llm call ok"
    );
    return res;
  } catch (err) {
    // 错误日志也不带 prompt 原文：用哈希照样能关联排查
    logInfo({ model: opts.model, promptHash, err: String(err) }, "llm call failed");
    throw err;
  }
}

prompt 哈希的价值在于可关联：用户投诉"刚才那次回答不对"，你拿他那次请求的 promptHash 去日志里定位，照样能查到模型、token 数、耗时，而不需要存原文。这是"可排查"和"不存 PII"之间的标准折中。

七、分级保留：日志不是存越久越好

很多一人团队的日志策略是"默认永久保留"，因为云服务商的默认值就是一直留着。这既是合规风险（GDPR 的存储期限最小化原则），也是成本黑洞。按下表给四类日志定保留时长：

保留时长对照表：debug 调试日志——保留 7 天——排查当期 bug 用，过期即删；access 访问日志——保留 30 天——流量分析、异常排查的主力；error 错误日志（含 Sentry issue 归档）——保留 90 天——事故复盘需要更长的窗口；audit 审计日志（登录、权限变更、数据导出）——保留 1 年——合规与安全事件追溯，注意审计日志只记"谁在何时做了什么"，不记业务 PII。

定完策略要用代码保证执行，否则就是墙上挂挂。两种常用实现：

实现 A：数据库 TTL 索引（日志进 MongoDB / Postgres 的场景）

// MongoDB：按日志级别建不同的 TTL 索引
db.access_logs.createIndex({ createdAt: 1 }, { expireAfterSeconds: 30 * 86400 });
db.debug_logs.createIndex({ createdAt: 1 }, { expireAfterSeconds: 7 * 86400 });
db.audit_logs.createIndex({ createdAt: 1 }, { expireAfterSeconds: 365 * 86400 });

实现 B：定时清理 cron（日志文件 / 对象存储的场景）

// scripts/log-retention.ts —— 每天凌晨跑
import { logInfo } from "../lib/logger";

const RETENTION_DAYS: Record<string, number> = {
  debug: 7, access: 30, error: 90, audit: 365,
};

async function enforceRetention() {
  for (const [kind, days] of Object.entries(RETENTION_DAYS)) {
    const cutoff = new Date(Date.now() - days * 86400_000);
    const deleted = await deleteLogsBefore(kind, cutoff);
    // 清理动作本身也要记一条审计日志：删了多少、什么时候删的
    logInfo({ kind, days, deletedCount: deleted }, "log retention enforced");
  }
}

两点提醒：清理 cron 自己要有监控（没跑成功要告警，否则等于策略作废）；云日志服务的保留期要在控制台/ Terraform 里显式配置，不要依赖"默认"，默认值通常是"永久"。

八、成本账：日志量是云账单的隐形杀手

脱敏和保留都做好了，还剩一个现实问题：钱。日志的成本公式很简单：日成本 = 日均日志量(GB) × 单价(元/GB·月) ÷ 30。一人团队常见的失控点：把 debug 日志开到生产、access 日志记了整包 body、AI 调用日志记了 prompt 原文——三项叠加，一天几个 GB 很轻松。控制手段就两个：采样和分级存储。

采样率：错误全采，正常采样

// lib/sampled-log.ts
function shouldSample(level: string): boolean {
  if (level === "error" || level === "fatal") return true;   // 错误 100% 采样
  if (level === "warn") return Math.random() < 0.1;          // warn 10%
  if (process.env.NODE_ENV === "production") {
    return Math.random() < 0.01;                            // 生产 info 1%
  }
  return true; // 开发环境全量
}

export function logSampled(level: "info" | "warn" | "error", obj: object, msg: string) {
  if (!shouldSample(level)) return;
  logInfo({ ...obj, sampled: true }, msg);
}

采样有个铁律：采样只降正常日志，错误日志永远全采。踩坑最多的就是把 error 也按 1% 采样，结果线上事故发生时，关键的那条错误日志正好被采样掉了——排查时只能干瞪眼。另外采样率要可配置（环境变量），不要写死，事故复现时你能临时调到 100%。分级存储配合采样：access 日志 30 天后转冷存储（对象存储归档），只保留 error 和 audit 在热存储里可查，成本能再降一个数量级。

九、与 DSR 指南的衔接：用户要求删除时，日志怎么办

这是最常被问到的问题，也是本篇和已发 DSR 指南的接口处。用户行使删除权，要求你删除他的个人数据——那躺在日志里的他的邮箱、手机号、行为记录，删不删？分四种情况处理：

第一，已经按本文脱敏的日志，不用删。日志里只有 userHash 和掩码后的字段，无法直接识别到个人，就不属于需要删除的个人数据。这是你做脱敏的直接合规回报：DSR 响应时日志侧零工作量。第二，哈希映射表要删。如果你维护了 userId → userHash 的映射（比如为了关联分析），这个映射表必须随 DSR 一起删除——映射一删，日志里的哈希就彻底变成匿名数据。第三，靠保留期自动过期。access 日志 30 天、debug 日志 7 天，到期自动清理，这本身就是 GDPR"存储期限最小化"的落实；DSR 响应里可以明确告知用户"日志类数据将在 X 天内自动清除"。第四，审计日志豁免。登录记录、数据导出记录这类审计日志，为了安全追溯可以保留更久（1 年），但前提是审计日志里本来就不记业务 PII——这就是第七节里强调"审计日志只记谁在何时做了什么"的原因。具体的 DSR 响应时限、身份核验、证据留存流程，参看本站已发的《数据主体请求（DSR）响应指南》，那篇是法务流程侧的完整 SOP，本篇不再重复。

十、8 个踩坑：都是真金白银换来的

坑 1：脱敏正则误伤正常字段

银行卡正则把 16 位订单号全掩了，客服查单时一脸懵。解法：正则上线前拿过去 7 天的真实日志跑一遍，统计命中率和误伤率；银行卡这种宽泛规则只做兜底，主力靠字段名黑名单。

坑 2：日志里打了完整 JWT

console.log("token:", token)——JWT 的 payload 是 base64 可解码的，邮箱、userId 全在里面明文躺着。解法：token 类字段一律 [REDACTED]，排查时只记 token 的前 8 位指纹用于关联。

坑 3：脱敏开关只在生产开，测试环境裸奔

staging 用的是生产数据的脱敏拷贝？不，很多团队 staging 直连生产库做联调，日志里全是真 PII。解法：脱敏层不区分环境，永远开启；区分的应该是日志级别和采样率。

坑 4：第三方 SDK 偷偷打日志

统计 SDK 在 debug 构建里输出设备标识和用户邮箱，你的 redactDeep 管不到 node_modules。解法：上线前在测试包里抓一次完整日志输出，逐行过；给第三方 SDK 关掉 verbose/debug 模式。

坑 5：userId 明文和行为数据记在同一条日志

{ userId: 42, email: "a@b.com", page: "/checkout" }——userId + 邮箱 + 行为，一条日志就是一份准标识符套餐。解法：userId 只记哈希；邮箱这类 L2 字段不与行为数据同条出现。

坑 6：错误日志也被采样掉了

为了省钱把 info 和 error 一起按 1% 采样，事故时关键错误日志正好没采到。解法：采样铁律——error/fatal 永远 100%，只对 info/warn 采样。

坑 7：只脱敏 body，忘了 query 和 headers

body 洗得干干净净，query 里 ?token=xxx 和 headers 里的 cookie 原样入库。解法：用第五节的中间件模板，三个面三种规则，一次配齐。

坑 8：保留策略写了文档，但 cron 从没跑成功过

保留策略停留在 docs/ 里，清理脚本上线第一天就因为权限问题静默失败，日志堆了两年。解法：清理 cron 的每次执行都记审计日志 + 失败告警；每月抽查一次各品类日志的最早一条，确认保留期真的在生效。

结尾：今天就能做的五件事

读到这里，别收藏吃灰。今天花两小时，按顺序做这五件：第一，全局搜索 console.log 里带 user、token、email 的行，全部改成脱敏后的结构化日志；第二，把本文第三節的 redact.ts 拷进项目，作为所有日志的统一出口；第三，给 Sentry 加上 beforeSend，URL 去 query、user 只留哈希；第四，去云日志控制台把 debug 日志的保留期改成 7 天、access 改成 30 天；第五，定一条团队（哪怕只有你）规矩：以后任何新字段进日志，先查第二節的分级表。日志脱敏不是一次性工程，是每次写 log 时的条件反射——而条件反射，是靠分级表和代码模板训练出来的。