chenchenandClaude Opus 4.8
612cccecb7
#44 的「生产开启 telemetry 前置 checklist 定稿」工程交付: docs/integration/telemetry-production-enablement-checklist.md。 涵盖:① 代码侧控制核验(默认 off/410、白名单 #42、8KiB 上限、保留期 #43、服务端脱敏、 不计费)② 生产配置确认(HEICODE_TELEMETRY_ENABLED/RETENTION_DAYS 等)③ 隐私/法务 签字硬前置(设备 ID 可关联账号披露 + 法务签字,owner=文档/合规,口径 @Fasthei;跟踪 #34) ④ 上线/回滚验证(410 基线→开启→抽查脱敏→回滚演练)⑤ 结论门。docs README 已索引。 完成 #44 的 checklist 定稿 DoD;隐私披露(#34)与法务签字仍是开启的人工前置。Docs only。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
54 lines
4.1 KiB
Markdown
54 lines
4.1 KiB
Markdown
# 客户端错误遥测 — 生产开启前置 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. 隐私 / 法务前置（硬性，开启的真正闸门）
|
||
|
||
> 这一节不是工程能独立完成的;**owner = 文档 owner + 合规/法务**,口径 @Fasthei。
|
||
|
||
- [ ] **heicodeDocs 隐私文档如实披露**「客户端错误遥测;**设备 ID 可关联账号、非匿名**;采集范围(崩溃类别/错误码哈希/脱敏调用栈/运行环境);保留期;不采集 prompt/代码/token/邮箱/完整路径/IP 原文」(跟踪：#34，草案已在 #34 给出)
|
||
- [ ] **法务 / 产品确认并签字**(在 #44 或 #34 留确认记录 + 责任人 + 链接)
|
||
- [ ] 隐私文档**已发布上线**(用户可见),且与实际采集行为一致(`法律声明.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 的法务签字仍是开启的人工前置。
|