Skip to content

ACCEPTANCE.md

Latest commit

 

History

History
73 lines (55 loc) · 5.09 KB

ACCEPTANCE.md

File metadata and controls

73 lines (55 loc) · 5.09 KB
Raw

FluxGate 验收与证据发布

本文定义可公开的验收契约。项目能力不等于某次验收已通过；只有被纳入发布的 manifest.json 才能作为运行结果。

当前权威公开运行

字段 已验证值
Run ID 20260904T194934Z-07759130
被测 commit 874eaabe5563578ed3d78fa899a5adfe08c0f8de
UTC 时间 2026-09-04T19:49:34.067Z 至 2026-09-04T19:55:35.619Z
运行选项 --clean --requests 1000 --concurrency 32；未跳过 build 或 README smoke
总体结果 status=passed，authoritative=true，mode=authoritative
必需阶段 13/13 passed，无 failed、blocked 或 skipped
Git 绑定 运行前后均为独立仓库、HEAD 均为上述 commit、dirty=false、status 条目数 0，head_unchanged=true
隐私门禁 189 个文本证据文件已检查，passed=true、violations={}
证据完整性 manifest 索引 189 个文件；发布前逐个复算 size/SHA-256，0 缺失、0 未索引、0 不匹配
最终清理 cleanup.status=passed，返回码 0，具名卷已删除

该运行从空卷完成 --pull --no-cache 构建和 CTest，并经过下表所列的路由、治理、采集、重放、故障恢复、负载与空卷 smoke 验收。原始结果和每个文件的哈希以链接的 manifest 为准。

权威运行条件

$env:FLUXGATE_CLICKHOUSE_PASSWORD = "<local-ephemeral-value>"
python scripts/acceptance.py --clean --requests 1000 --concurrency 32
Remove-Item Env:FLUXGATE_CLICKHOUSE_PASSWORD

runner 默认将新证据写入 artifacts/acceptance/public/<run-id>/。一次运行只有同时满足以下条件才会得到 status=passed 且 authoritative=true：

  • 从空 Compose 具名卷开始，未跳过构建或 README smoke；
  • FluxGate 自身是独立 Git 工作树，运行前有可解析 HEAD 且工作区干净；
  • 运行结束时 HEAD 未改变，工作区仍干净；
  • 13 个必需阶段全部通过，最终 Compose 取证与清理成功；
  • evidence_privacy.passed=true，本次文本证据中不含 Windows 绝对路径或父目录外跳路径。

如果 FluxGate 尚未是独立仓库、没有 commit、工作区 dirty，或使用了跳过选项，runner 可以保留诊断证据，但不得将其标记为 authoritative。

必需验收项

阶段 验收契约
environment Docker/Compose 可用；9 个服务精确匹配；Envoy 公共入口仅映射 127.0.0.1:18080；固定镜像 digest 和 bRPC SHA 一致
clean 删除本验收 Compose project 的卷后，18080、19901、18123 可绑定
build_and_unit 无缓存构建成功；C++ 单测通过，包括超过 10,000 个 fallback request ID 后的计数器滚动
readiness 长期服务 healthy/restart=0，init 服务 exit 0，admin、health 与 ClickHouse 均就绪
rate_limit_first 冻结 token bucket 在同一 refill 周期返回 200,200,429,429
dual_routing catalog/orders 通过同一公共入口到达不同 C++ 后端
retry_recovery 同一 request ID 的 503→200 一次重试同时有客户端、后端日志和 Envoy counter 证据
clickhouse_rows_and_aggregates JSONL、FINAL 逻辑行、字段和直接聚合一致
analytics_apis routes/statuses/latency API 与同窗口 ClickHouse FINAL 查询精确一致
at_least_once_replay_and_final_dedup 真实回退 checkpoint 并重读 JSONL；物理重复存在而 FINAL 逻辑行不放大
clickhouse_outage_recovery ClickHouse 停机时业务路由继续服务、checkpoint 不越过未 ACK 批次，恢复后追平
load_test 固定 1,000 个计量请求全部成功，客户端与 Envoy 延迟分开记录，不外推为生产 SLO
readme_smoke 再次从空卷启动，README 公共入口 smoke 返回 pass=true

Git 绑定与隐私设计

runner 在创建证据目录之前执行 Git 快照。它先验证 git rev-parse --show-toplevel 严格等于 FluxGate 根目录；若 Git 向上命中父仓库，不会再执行或保存可能列出兄弟项目的 status 原文。证据仅保存 HEAD、dirty 布尔值、status 条目数和 status 文本的 SHA-256，不保存文件列表。

命令摘要与运行事实使用仓库相对路径。写盘前会替换已知宿主路径；finalize 再扫描本次文本证据，发现 Windows 绝对路径或 ../ 外跳时直接使运行失败。

发布流程

除上述已审核 run 外，新生成和历史 acceptance 目录默认被 Git 忽略，避免将未审核证据意外上传。发布者应：

  1. 检查新 manifest 的 status、authoritative、source、evidence_privacy 和 evidence 哈希索引；
  2. 对新 run 执行额外的禁止字符串扫描；
  3. 只将该一个已审核 run 纳入下一个发布提交，并在本文增加其 run ID、commit HEAD、命令、结果和边界；
  4. 保持旧原始证据不变，不通过搜索替换修补旧哈希树。

性能数字只表示对应 manifest 中的硬件、loopback、请求数、并发度和观测时长；不是持续吞吐、生产容量、SLO 或多平台保证。