yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
163 lines
5.3 KiB
Markdown
163 lines
5.3 KiB
Markdown
# 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 的兼容校验通过：
|
||
|
||
```powershell
|
||
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`
|
||
|
||
语法检查：
|
||
|
||
```powershell
|
||
python -m py_compile yuqei-infra/scripts/run-release-quality-gate.py
|
||
```
|
||
|
||
结果：通过。
|
||
|
||
## 实时 benchmark 分支
|
||
|
||
本次也验证了 `--run-benchmark` 分支。该分支会在 gate 内先执行：
|
||
|
||
```powershell
|
||
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 | 通过 |
|
||
|
||
## 新鲜度控制
|
||
|
||
脚本新增可选参数：
|
||
|
||
```powershell
|
||
--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 观察窗口仍列为上线前检查项，不阻塞当前交付收口。
|