token_thief/docs/compose/specs/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

修订范围

本规格是现有 ClickHouse Migration 的增量修订。保留当前单表 proxy_logs、内存异步队列、httputil.ReverseProxy 和 best-effort 审计模型，不引入 PostgreSQL 兼容层、持久化 outbox 或 WebSocket 帧采集。

行为要求

队列与关闭

• Submit 始终非阻塞；与 Stop 并发、停止后提交和重复停止均不得 panic。
• 队列由条数和字节双重预算约束。默认 LOG_QUEUE_SIZE=256、LOG_QUEUE_BYTES=67108864、MAX_BODY_BYTES=1048576；任一预算不足即丢弃并计数。
• Stop(ctx) 使用调用方提供的单一总 deadline 排空；deadline 到期取消所有 worker I/O、丢弃剩余条目并返回错误。
• worker flush 后清空 batch 指针并释放条目的字节预留。

ClickHouse 写入

• PrepareBatch 错误是确定未提交错误，可有限重试整个 batch。
• Append 错误是确定未提交错误，必须中止/关闭 batch，并允许逐条隔离坏记录；成功记录继续写入，失败记录明确计数。
• Send 错误视为提交结果不明，不自动重试或逐条重发，避免静默重复；该批计为 ambiguous drop 并标记连接不健康。
• 进程内 best-effort 方案不承诺跨进程 exactly-once。需要更强保证时必须另行引入持久化 outbox 与幂等协议。

代理完整性

• 请求体预读失败时返回固定 400，不调用 upstream，不转发已损坏请求。
• 502 客户端响应只包含固定 bad gateway 和 request ID；内部网络错误仅写服务端日志和 LogEntry.Error。
• 只有 ReverseProxy 正常完成的普通/SSE 响应才提交完整日志。下游写失败、短写、客户端断开或响应复制中断不得提交成完整成功日志。
• SSE 终止检测只在响应 Content-Type 为 text/event-stream 时按完整 event 边界解析。终止事件仅用于状态判断，不触发提前提交；提交仍等待代理正常返回。
• 普通 HTTP 响应体使用可配置总 timeout；SSE 使用可配置 idle timeout，成功读取数据后重置；timeout 必须能关闭阻塞中的上游 Body。
• WebSocket 成功升级时记录一条 101 握手元数据日志，body 为空。Handler 跟踪已 hijack 连接，并提供受 context 限制的 shutdown 关闭能力；不采集帧。
• 默认不信任 X-Forwarded-For/X-Real-IP。仅当直接对端命中 TRUSTED_PROXIES CIDR 时，从 XFF 右向左剥离可信代理并选择最近的不可信地址。

配置与数据库边界

• 所有整数、布尔值和 duration 环境变量格式错误时启动失败；要求正值的 body、队列、batch、worker、重连和 timeout 配置必须严格大于零。
• CLICKHOUSE_URL 支持严格 host:port、clickhouse:// 和 clickhouses://。仅允许 secure、skip_verify、compress 查询参数；未知参数、冲突 TLS 配置、fragment、空 host/port 均失败。
• 建表后校验 system.columns 与 system.tables 的必需列类型、引擎、分区键和排序键；不兼容 schema 拒绝标记健康，不自动重建或改类型。

启动与部署

• server 启动错误与 signal 进入同一清理路径；禁止 goroutine 内 log.Fatalf 绕过 defer。
• shutdown 总预算依次覆盖 HTTP、升级连接、日志队列、DB 和根 context。
• Compose 固定 ClickHouse 明确版本，不使用 latest；默认不发布 ClickHouse 端口；CLICKHOUSE_PASSWORD 必须显式设置，应用 DSN 使用独立 CLICKHOUSE_URL，避免弱默认和 URL 编码冲突。

验证

• 针对上述失败路径增加 config、logger、proxy、db 单元测试。
• 运行 gofmt、go test ./... 和 go vet ./...。
• 使用 Git 提交保留完整变更证据；审查应以提交及其 diff 验证实现和验收项。