token_thief/docs/compose/plans/2026-07-09-clickhouse-migration.md

ClickHouse Migration 安全修复计划

Note

This document may not reflect the current implementation. See the final report for up-to-date state: Final Report

变更规模： 大型跨模块修复。现有迁移主体复用，仅重新实施受本次审查影响的任务及其集成依赖。

全局约束

• 保留非阻塞 best-effort 日志语义，并通过 Git 提交保留可审查的变更证据。
• 先用失败测试固定根因，再实施最小修复。
• Send 模糊失败不重试；不宣称分布式 exactly-once。
• WebSocket 只管理连接并记录 101 元数据，不采集帧。

Task 1: 严格配置与安全默认

文件： config/config.go、tests/config/config_test.go

• 严格解析整数、布尔值和 duration，拒绝非正 body/队列/timeout。
• 增加 LOG_QUEUE_BYTES、响应总/idle timeout、TRUSTED_PROXIES。
• 在配置加载阶段校验 ClickHouse DSN，并补齐边界测试。

Task 2: Queue 生命周期、字节预算与确定性写入

文件： logger/queue.go、tests/logger/queue_test.go

• 用同步状态机消除 Submit/Stop send-close 竞态，Stop 使用单一 context 总预算。
• 增加条数/字节双预算并在所有消费、丢弃和 shutdown 路径释放预留。
• 区分 Prepare、Append、Send 错误；Append 失败清理 batch，Send 模糊失败不重试。
• 增加并发关闭、预算、清理、部分失败和模糊提交测试。

Task 3: ClickHouse DSN 与 schema 验证

文件： db/clickhouse.go、db/migrate.go、db/clickhouse_test.go

• 严格解析 scheme、TLS 和白名单 query 参数。
• 创建 schema 后校验列、引擎、分区和排序键；不兼容时保持 unhealthy。
• 增加 DSN 与 schema 元数据校验测试。

Task 4: HTTP/SSE 代理完整性与可信来源

文件： proxy/proxy.go、proxy/writer.go、proxy/capture.go、proxy/sse.go、tests/proxy/*

• 请求体读取失败 fail closed；502 使用固定客户端文本。
• 记录响应写错误/短写，响应中断不提交完整日志。
• 仅对真正 SSE 按完整事件检测终止，并等待正常返回后提交。
• 为普通响应总 timeout 与 SSE idle timeout 包装 upstream Body。
• 默认忽略转发头，仅按可信代理链提取客户端 IP。

Task 5: WebSocket 元数据与统一 shutdown

文件： proxy/writer.go、proxy/proxy.go、tests/proxy/websocket_test.go、main.go

• Hijack 成功后登记连接，记录 101 握手元数据并在结束时注销。
• 提供 Handler shutdown，关闭受管升级连接。
• server 启动错误和 signal 共用清理路径，所有关闭步骤受单一总预算约束。

Task 6: Compose、文档与最终验证

文件： compose.yml、.env.example、README.md、docs/compose/reports/*

• 固定镜像、取消默认 ClickHouse 端口发布、强制显式密码/DSN并同步新配置。
• 记录 best-effort、模糊提交、schema 和 WebSocket 取舍。
• 运行 gofmt、go test ./...、go vet ./... 并生成报告。