fix: restore reviewable migration evidence
This commit is contained in:
MiMoCode
@@ -0,0 +1,32 @@
|
||||
# TokenThief 可靠性与安全修复验证报告
|
||||
|
||||
## 结果
|
||||
|
||||
本次修订覆盖队列并发关闭和单一总 shutdown deadline、响应完整性、请求体 fail-closed、ClickHouse 部分/模糊提交、64 MiB 默认队列字节预算、严格正值配置、响应体总/idle timeout、SSE 协议边界、WebSocket 101 与 shutdown、DSN/TLS、schema 校验、Compose 安全默认、固定 502、可信代理、batch 清理和 server 启动统一清理。
|
||||
|
||||
Compose 使用固定 ClickHouse 镜像 `clickhouse/clickhouse-server:25.3.3.42-alpine`，默认不发布 ClickHouse 端口，并在配置展开阶段拒绝空的 `UPSTREAM_URL`、`CLICKHOUSE_URL` 和 `CLICKHOUSE_PASSWORD`。`.env.example` 不提供密码或 DSN 默认值。
|
||||
|
||||
## 关键取舍
|
||||
|
||||
- 日志仍是内存中、非阻塞、best-effort。队列满、字节预算不足或数据库不可用时允许丢弃并计数。
|
||||
- ClickHouse `PrepareBatch` 的确定失败保留整批；逐项 `Append` 的确定失败只保留失败项，成功项照常发送。`Send` 错误无法从单机客户端确认服务端是否已提交，因此不自动重试该批并计入 `ambiguous_send`，优先避免静默重复。跨进程 exactly-once 需要持久化 outbox 和服务端幂等协议，未在本次引入。
|
||||
- WebSocket 仅记录 101 握手元数据并关闭受管连接，不解析帧或承诺跨进程迁移。
|
||||
- schema 会自动创建缺失表，并校验现有表的列类型、MergeTree 引擎、分区键和排序键；不兼容时拒绝标记健康，不执行有数据风险的自动重建。
|
||||
- Compose 不默认发布 ClickHouse 端口，强制显式密码和独立 DSN，以同时保留原始服务端密码和 URL 编码凭据。
|
||||
|
||||
## 行为边界
|
||||
|
||||
- 仅当请求体完整可重放且 `ReverseProxy` 正常结束时提交 HTTP 日志；读取失败的请求不转发，响应中断不提交不完整日志。
|
||||
- SSE 仅由 `Content-Type: text/event-stream` 判定；看到 `[DONE]` 不会提前提交，仍等待上游正常结束。普通响应使用总 timeout，SSE 使用可重置 idle timeout。
|
||||
- WebSocket 仅记录成功 `101` 的握手元数据，不采集帧；进程关闭会关闭当前进程管理的升级连接，但不提供跨进程连接迁移或协调。
|
||||
- `502` 对客户端使用固定错误文本，内部连接错误只进入服务端日志。转发客户端 IP 仅在 TCP 对端属于 `TRUSTED_PROXIES` 时生效。
|
||||
|
||||
## 验证
|
||||
|
||||
- `gofmt -w .`：通过。
|
||||
- `go test ./...`：通过。
|
||||
- `go vet ./...`：通过。
|
||||
- 新增 `tests/deployment` 契约测试，覆盖必填部署参数、固定 ClickHouse 镜像、不发布数据库端口和示例凭据留空。
|
||||
- `docker compose config`：未执行，当前环境没有可用 Docker daemon/CLI；Compose 安全约束由 Go 契约测试覆盖。
|
||||
- `go test -race`：不属于验收命令，未执行。
|
||||
- 未连接真实 ClickHouse 做断链模糊提交和旧 schema 集成测试；相关阶段语义通过 fake batch 与纯 schema 校验单测覆盖。
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
feature: reliability-security-fixes
|
||||
status: delivered
|
||||
specs:
|
||||
- docs/compose/specs/reliability-security-fixes.md
|
||||
- docs/compose/specs/2026-07-09-clickhouse-migration.md
|
||||
plans:
|
||||
- docs/compose/plans/reliability-security-fixes.md
|
||||
- docs/compose/plans/2026-07-09-clickhouse-migration.md
|
||||
branch: main
|
||||
---
|
||||
|
||||
# 可靠性与安全修复 - 最终报告
|
||||
|
||||
## What Was Built
|
||||
|
||||
本轮完成了 token_thief 的可靠性与安全加固。异步日志队列现在安全处理并发 `Submit`/`Stop`、使用条目数和字节双预算、在统一 shutdown deadline 内排空，并区分 ClickHouse 的可安全重试、确定失败和提交结果不明三类写入结果。
|
||||
|
||||
反向代理现在对请求体读取、上游响应复制、普通响应超时、SSE idle timeout、WebSocket 101 元数据和升级连接关闭实施完整性保护。客户端错误文本不再泄露内部信息，转发来源头仅在直接对端属于 `TRUSTED_PROXIES` 时参与客户端 IP 判定。
|
||||
|
||||
配置、ClickHouse DSN/TLS、数据库 schema 和 Compose 部署均采用 fail-closed 校验与更安全默认；服务启动错误和信号关闭共用资源清理路径。
|
||||
|
||||
## Architecture
|
||||
|
||||
`config/config.go` 在启动前严格解析正值预算、duration、布尔值、可信代理和 DSN。`proxy/` 在转发前完整读取请求体，通过 capture writer 和 response body wrapper 判断响应是否完整，并管理 hijacked 连接。`logger/queue.go` 提供非阻塞有界队列，按 `PrepareBatch`、`Append`、`Send` 阶段决定重试或丢弃；`db/` 只在连接、迁移和 schema 校验均成功后标记健康。`main.go` 用一个 30 秒 shutdown context 依次关闭 HTTP、升级连接、队列和数据库。
|
||||
|
||||
### Design Decisions
|
||||
|
||||
- 选择仅重试 `PrepareBatch` 失败，因为此时可确定没有提交；`Send` 失败计为 ambiguous 且不重放，避免静默重复。
|
||||
- 选择进程内有界 best-effort 队列，因为当前项目没有持久化 outbox；该策略明确不承诺跨进程 exactly-once。
|
||||
- 选择 WebSocket 仅记录 101 握手元数据并管理连接，不采集帧，以保持代理边界和关闭行为可测试。
|
||||
- 选择拒绝不兼容 ClickHouse schema，而不是自动破坏性迁移或重建表。
|
||||
|
||||
## Usage
|
||||
|
||||
必须设置 `UPSTREAM_URL`、`CLICKHOUSE_URL`，Compose 部署还必须显式设置强 `CLICKHOUSE_PASSWORD`。关键新增配置包括 `LOG_QUEUE_BYTES`、`UPSTREAM_RESPONSE_TIMEOUT`、`UPSTREAM_STREAM_IDLE_TIMEOUT` 和 `TRUSTED_PROXIES`；所有预算和 timeout 必须大于零。`CLICKHOUSE_URL` 支持严格的 `host:port`、`clickhouse://` 和 `clickhouses://`，TLS 与压缩参数受白名单校验。
|
||||
|
||||
## Verification
|
||||
|
||||
迭代 1 验证全部通过：`gofmt -l .` 无输出，`go test -json ./...` 共 118 个测试通过、0 失败、5 个测试包通过，`go vet ./...` 无诊断，`go build ./` 成功。针对 config、queue、ClickHouse、HTTP/SSE/WebSocket 和 Compose 的失败路径均有测试覆盖。
|
||||
|
||||
## Journey Log
|
||||
|
||||
> Brief notes on what informed the final design. Not required reading.
|
||||
|
||||
- [lesson] 迭代 1：网络写入的 `Send` 错误无法证明提交与否；最小安全策略是不自动重试、显式统计 ambiguous，并将连接标记为不健康。
|
||||
- [lesson] 迭代 1：进程内队列只能提供有界 best-effort；跨进程幂等需要持久化 outbox 和下游幂等协议，不能由本地重试可靠模拟。
|
||||
- [pivot] 迭代 1：SSE 完成判定限定为真正的 `text/event-stream` 且等待代理正常返回，避免终止标记导致提前记录不完整响应。
|
||||
|
||||
## Source Materials
|
||||
|
||||
| File | Role | Notes |
|
||||
|------|------|-------|
|
||||
| `docs/compose/specs/2026-07-09-clickhouse-migration.md` | 安全修复规格 | 定义本轮行为边界与取舍 |
|
||||
| `docs/compose/plans/2026-07-09-clickhouse-migration.md` | 实施计划 | 覆盖跨模块修复和验证 |
|
||||
Reference in New Issue
Block a user