ADR 008 日志指标与隐私脱敏

• 状态：提案，待总控决策
• 范围：API、Worker、Gateway、入口代理、数据库审计、指标、追踪、崩溃与诊断导出
• 不在本 ADR 冻结：第三方供应商、开源许可、密码协议或发布安全声明

1. 背景

VMax 需要排查消息投递、队列、认证、Push、数据库和容量问题，但可观测性系统通常复制范围更广、保留更久、访问者更多。密文、完整标识或稳定关联 ID 进入日志也会形成隐私风险。

1.1 来源 MUST

• 不记录消息正文、密文全值、私钥、access token、APNs token、完整 VMax 地址、备份路径、主/假密码、派生值或伪装槽位命中。
• 结构化日志使用最小字段；actor 只能使用短期哈希。
• 追踪只覆盖服务内部，不把可关联用户的 trace ID 放入消息协议。
• 服务日志默认保留 7 天且脱敏；生产关闭调试日志与敏感正文采集。

1.2 已验证事实

当前没有服务代码、日志库、监控栈或敏感数据扫描报告。本 ADR 只定义目标与选择，不证明已实现。

2. 选项

2.1 选项 A 黑名单脱敏

记录完整结构后替换已知敏感字段。实现快，但新字段、嵌套对象、错误堆栈和第三方库容易绕过，默认风险过高。

2.2 选项 B 允许列表结构化事件

每个事件只允许预定义字段和类型，敏感对象无法被通用序列化。开发成本较高，但可审计、可测试，适合 VMax。

2.3 选项 C 几乎无日志，仅指标

隐私最好，但难以排障复杂的事务和迁移问题，可能诱导临时开启不受控 debug。

3. 推荐方案

待总控决策：采用 B 为默认，结合低基数聚合指标；安全关键路径保留最小审计事件。A 只能作为入口的第二道防线，不能作为主要安全机制。C 作为高隐私部署的可选模式，但仍保留健康、容量和安全告警所需最小信号。

4. 事件模型

允许字段：时间、级别、服务、环境、发布版本、配置版本、request_id、route template、HTTP 方法/状态、耗时、稳定错误码和实例级结果。

禁止通用对象 dump、请求/响应正文、headers、URL query、SQL 参数、环境变量和 panic 内存。密文视为敏感数据，即使服务端无法解密。

actor 关联只有在单次事件排障确有需要时启用：

actor_hash = HMAC(rotating_observability_key, scoped_actor_id)

这只是候选机制，不是密码协议决定。key 周期、作用域和访问权限为待总控决策；不得与身份、游标或协议密钥复用。

5. 指标与追踪

• 指标 label 只用服务、route template、状态、错误码、版本和低基数依赖类别。
• 禁止将地址、设备、消息、route、IP、request/trace ID 作为 label。
• trace 不采集正文、headers、SQL bind 参数或队列 payload。
• Gateway 与消息实例默认不共享长期 trace ID，避免关联通信时序。
• 高错误率调试用短期采样配置，有审批、自动失效和事后扫描。

6. 保留与访问

• 服务日志默认 7 天，可缩短；不提供无限期默认。
• 安全审计事件、指标与 trace 的具体保留期分别评估，不能因为“不是日志”而绕过隐私策略。
• 生产访问使用最小权限、强认证和访问审计；开发者默认看不到原始生产事件。
• 删除覆盖索引、冷热层、缓存、导出、告警通知和备份副本。

7. 待总控决策

7.1 短期哈希周期

• 每请求：关联性最低，但跨请求排障困难。
• 每小时：可排查短事件，关系图谱窗口较小。
• 每天：运维方便，但更易形成行为时间线。
• 建议：每小时或按单次事件作用域；只有书面用例才能延长。
• 验证：关联性测试确认跨周期不可链接，key 轮换后旧值不可复算。

7.2 后端选择

• 本地轮转：依赖少，跨节点检索弱。
• 自托管聚合：可控性高，运维成本高。
• 云服务：能力成熟，但引入外部处理者、区域和合同边界。
• 建议：接口保持供应商中立；Compose 给出安全本地默认，生产选择需隐私/合规评审。

7.3 错误详情

稳定错误码足以驱动告警；堆栈仅在受控内部环境保留并经过 scrubber。是否对特定错误启用采样需逐类威胁评估。

8. 验证

• 构建时 lint 禁止记录敏感类型，日志 API 接受强类型安全字段而非任意 map/string interpolation。
• 测试注入唯一 canary 覆盖正文、密文、地址、token、APNs token、口令与路径。
• 执行成功、校验失败、认证失败、超时、panic、数据库错误、Push 错误、备份与导出路径。
• 扫描日志、指标 label、trace、crash、告警、导出和备份，任何 canary 命中即阻断发布。
• 验证 TTL 实际删除全部副本；抽查访问审计与临时 debug 自动关闭。

9. 后果

• 允许列表会降低随手打印对象的便利，需要领域化事件和错误码。
• 更短保留与轮换哈希可能降低长期趋势排障能力，应依赖无用户维度的聚合指标弥补。
• 不采集正文意味着部分问题只能由客户端生成经过用户预览的本地诊断；服务端不得要求上传秘密。
• 未通过全链路 canary 和权限审计前，不得称日志体系已完成隐私脱敏。