ai-contract-platform/project-docs/V2-release-quality-gate-ci-hardening-2026-07-03.md

AI 合同平台 V2 发布质量门 CI 固化记录

日期：2026-07-03

目标

把本轮已经手工跑通的质量门固化为可重复执行的发布检查，减少后续依赖人工逐项复跑。

本次固化范围：

• 远端 runtime schema-check。
• Docker smoke deploy summary。
• 接口级 benchmark summary。
• GitHub Actions 手动 workflow。

新增内容

脚本：

• yuqei-infra/scripts/run-release-quality-gate.py

Workflow：

• .github/workflows/release-quality-gate.yml

文档：

• yuqei-infra/README.md 新增 Release Quality Gate 使用说明。

发布质量门语义

run-release-quality-gate.py 会生成统一 pass/fail summary：

• 实时请求 Contract API /api/v1/runtime/schema-check。
• 实时请求 AI Platform API /api/v1/runtime/schema-check。
• 校验 Docker smoke summary 是否为 pass，并确认关键检查项通过：
  • remote_health
  • ai_golden_sample_gate
  • remote_db_check
  • review_worker_smoke
• 校验接口 benchmark summary 是否为 pass，并确认所有场景 passed=true 且 errors=0。

默认会读取最新 artifact：

• project-docs/qa-artifacts/v2-smoke-docker-deploy/*/v2-smoke-docker-deploy-summary.json
• project-docs/qa-artifacts/v2-interface-benchmark/*/interface-benchmark-summary.json

也可以显式指定 summary 路径。

本地验证

使用旧通过 benchmark summary 的兼容校验通过：

python yuqei-infra/scripts/run-release-quality-gate.py `
  --web-base-url http://192.168.3.90:13000 `
  --contract-api-base http://192.168.3.90:18100 `
  --ai-api-base http://192.168.3.90:18101 `
  --benchmark-summary project-docs/qa-artifacts/v2-interface-benchmark/2026-06-27T14-21-10/interface-benchmark-summary.json

结果：

• V2_RELEASE_QUALITY_GATE_PASS
• Artifact：project-docs/qa-artifacts/v2-release-quality-gate/2026-07-03T19-20-59

语法检查：

python -m py_compile yuqei-infra/scripts/run-release-quality-gate.py

结果：通过。

实时 benchmark 分支

本次也验证了 --run-benchmark 分支。该分支会在 gate 内先执行：

python yuqei-infra/scripts/run-interface-benchmark.py ...

再用新生成的 interface-benchmark-summary.json 作为发布门输入。

早一轮 smoke 环境实时压测未通过，发布质量门正确拦截：

• Artifact：project-docs/qa-artifacts/v2-release-quality-gate/2026-07-03T19-15-15
• 失败场景：
  • contract_list
  • contract_detail
  • approval_todo
  • unified_search
  • knowledge_chunks_hybrid_search

轻量复核：

• Artifact：project-docs/qa-artifacts/v2-interface-benchmark/2026-07-03T19-quick-rerun
• 合同列表、合同详情、审批待办在轻量复核中恢复到阈值内。
• unified_search、knowledge_documents_search、knowledge_chunks_hybrid_search 仍未达标。

结论：

• 发布质量门脚本本身已生效，能正确拦截实时 benchmark 失败。
• 搜索/RAG 检索性能修复后，已使用 --run-benchmark 复跑发布质量门并通过。

最新通过结果：

• Artifact：project-docs/qa-artifacts/v2-release-quality-gate/2026-07-11T17-02-36
• 命令：python yuqei-infra/scripts/run-release-quality-gate.py --web-base-url http://192.168.3.90:13000 --contract-api-base http://192.168.3.90:18100 --ai-api-base http://192.168.3.90:18101 --run-benchmark
• 结果：V2_RELEASE_QUALITY_GATE_PASS
• Docker smoke summary：project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-11T14-47-14/v2-smoke-docker-deploy-summary.json
• Interface benchmark summary：project-docs/qa-artifacts/v2-release-quality-gate/2026-07-11T17-02-36/interface-benchmark/interface-benchmark-summary.json

最新实时压测关键结果：

场景	p95	错误率	阈值	结果
contract_list	34.59 ms	0%	500 ms	通过
contract_detail	20.03 ms	0%	500 ms	通过
approval_todo	56.38 ms	0%	500 ms	通过
unified_search	31.53 ms	0%	500 ms	通过
ai_trace	93.10 ms	0%	1500 ms	通过
knowledge_documents_search	215.87 ms	0%	800 ms	通过
knowledge_chunks_hybrid_search	554.86 ms	0%	1500 ms	通过

新鲜度控制

脚本新增可选参数：

--max-smoke-summary-age-hours 24
--max-benchmark-summary-age-hours 24

默认 0 表示不检查 artifact 年龄。上线前建议设置为 24 或更短，避免拿过旧 benchmark summary 放行。

CI 使用方式

GitHub Actions 新增手动 workflow：Release Quality Gate。

要求：

• 使用能访问 192.168.3.90 的 self-hosted runner。
• 默认 runner label：self-hosted, yuqei-smoke。
• checkout 使用 clean: false，用于保留 self-hosted runner 本地生成的 ignored QA artifacts。

可选输入：

• web_base_url
• contract_api_base
• ai_api_base
• smoke_summary
• benchmark_summary
• run_benchmark
• max_smoke_summary_age_hours
• max_benchmark_summary_age_hours

后续任务

1. 在 self-hosted runner 上注册或确认 yuqei-smoke label，并确认 workflow 能访问 192.168.3.90。
2. 上线前使用 --run-benchmark 或 --max-benchmark-summary-age-hours 24 跑一次强制新鲜 gate。
3. Trace governance 的 24 小时 smoke 观察窗口仍列为上线前检查项，不阻塞当前交付收口。