fix: restore reviewable migration evidence

2026-07-10 18:26:48 +08:00
commit d1bbb5370c
42 changed files with 6419 additions and 0 deletions
@@ -0,0 +1,66 @@
+# ClickHouse Migration 安全修复计划
+
+> [!NOTE]
+> This document may not reflect the current implementation.
+> See the final report for up-to-date state:
+> [Final Report](../reports/reliability-security-fixes.md)
+
+**变更规模：** 大型跨模块修复。现有迁移主体复用，仅重新实施受本次审查影响的任务及其集成依赖。
+
+## 全局约束
+
+- 保留非阻塞 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 ./...` 并生成报告。