Files

T

chenchenandClaude Opus 4.8 06f0971465 docs(telemetry): reframe enablement gate as privacy-disclosure-published, not legal signoff (#44 )

去掉「法务/产品签字」「需真人」表述:开启遥测的前置是「隐私披露文档已发布且经 PR 评审通过」
这一文档/评审条件,不是人工法务签字。符合团队留言只写技术结论/条件的约定。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-10 13:42:53 +08:00

4.1 KiB

Raw Blame History

客户端错误遥测 — 生产开启前置 Checklist（定稿）

工单：#44（拆分自 #32 EPIC）· 状态：工程项已就绪;开启前置 = 隐私披露文档已发布 + 评审通过 适用：把 HEICODE_TELEMETRY_ENABLED 从默认 false 翻到 true 之前的强制检查清单。

0. 一句话

遥测默认关闭(摄入端点回 410 kill switch)。在本清单全部勾选前,生产不得开启;尤其是 §3 的隐私披露是硬前置——工程已把代码侧防线做齐,但「设备 ID 可关联账号」属隐私敏感,必须先在隐私文档如实披露并发布。

1. 代码侧控制（已实现，可现场核验）

控制	实现	核验方式
默认关闭 + kill switch	`HEICODE_TELEMETRY_ENABLED` 默认 `false`,关时摄入端点返回 410	`GET /api/heicode/config` → `telemetry.enabled=false`;`POST /api/heicode/telemetry/events` → 410
不计费、不进 consume log	独立 `telemetry_events` 表,摄入不写消费日志/不动 quota	代码 `controller/heicode_telemetry.go`;开启后抽查无 consume log
仅设备配对可上送	需 V2 设备签名 + `X-Heicode-Device-Id`;会话-only 拒绝(403)	无设备头请求 → 403
批量/尺寸限制	顶层数组 1–20 条、≤256KB	超限 → 413
context 字段白名单（#42）	仅 `route/retryable/phase/exit_code/duration_ms/attempt`,其余键丢弃	`TestFilterTelemetryContext_Whitelist`
单字段尺寸上限	`stack_top`/`context` 脱敏后截断 8KiB	`TestCapTelemetryField`
服务端二次脱敏	`stack_top`/`context` 剥离 sk-/Bearer/URL token/JSON 密钥字段	`TestTelemetryToModel_RedactsSecrets`
数据保留期（#43）	`HEICODE_TELEMETRY_RETENTION_DAYS`(默认 30)+ master-only 每日清理	`GET /api/heicode/config` → `retention_days`;`TestDeleteTelemetryEventsBefore`

禁止采集(白名单已强制):prompt、代码正文、token、邮箱、完整文件路径、用户名路径、IP 原文等可识别信息——非白名单 context 键一律丢弃 + 服务端脱敏兜底。

2. 生产配置确认（开启时设置 + 复核）

HEICODE_TELEMETRY_ENABLED=true（仅在 §3 全部完成后）
HEICODE_TELEMETRY_RETENTION_DAYS 已确认(建议 ≤90;默认 30)
HEICODE_TELEMETRY_RETENTION_INTERVAL_HOURS 已确认(默认 24)
仅 master 节点跑清理任务(IsMasterNode,已在 main.go 内置)
GET /api/heicode/config 返回的 telemetry 块与上述配置一致

3. 隐私披露前置（硬性，开启的真正闸门）

这一节是文档 + 评审条件,不是代码项;由对应文档 PR 经评审通过即满足。

heicodeDocs 隐私文档如实披露「客户端错误遥测;设备 ID 可关联账号、非匿名;采集范围(崩溃类别/错误码哈希/脱敏调用栈/运行环境);保留期;不采集 prompt/代码/token/邮箱/完整路径/IP 原文」(跟踪：#34，草案已在 #34 给出)
该隐私披露 PR 已评审通过并合并(在 #44 / #34 留 PR 链接为开启决定留痕)
隐私文档已发布上线(用户可见),且与实际采集行为一致(法律声明.md「隐私披露必须与真实采集行为一致」)

4. 上线 / 回滚验证（开启当次执行）

开启前:POST /api/heicode/telemetry/events 返回 410(确认 kill switch 基线)
开启后:客户端真实上送一批 → 200 {accepted:n},落 telemetry_events 表
抽查入库行:stack_top/context 已脱敏;context 仅白名单键;无 prompt/邮箱/路径/IP
确认无 consume log / quota 变化(遥测不计费)
回滚演练:把 HEICODE_TELEMETRY_ENABLED 改回 false → 端点回 410、客户端停送(kill switch 可用)
保留期清理任务在日志中可见(secret/telemetry retention task started)

5. 结论门

只有 §1 已核验 + §2 已确认 + §3 隐私披露已发布 + §4 验证通过,才允许在生产保持 HEICODE_TELEMETRY_ENABLED=true。 任一项不满足 → 维持默认关闭(410)。本清单作为 #44 的「checklist 定稿」交付;§3 的隐私披露文档(#34)是开启的前置条件。

4.1 KiB Raw Blame History Unescape Escape