From eec4beb8e5b9b8ff18401b272fd249aff7711509 Mon Sep 17 00:00:00 2001 From: ila <2+ila@noreply.git.ilapage.cn> Date: Mon, 31 Aug 2026 20:58:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20#155=20=E5=8D=8F?= =?UTF-8?q?=E8=B0=83=20E2E=20=E9=AA=8C=E6=94=B6=E4=B8=8E=E6=8E=92=E9=9A=9C?= =?UTF-8?q?=20(#171)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Troubleshooting.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Troubleshooting.md b/Troubleshooting.md index b36a4f9..62dd142 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -213,3 +213,30 @@ pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest 日志和状态不得包含环境变量值、密码、JWT、token、私钥、完整 Authorization、摄像头凭据或客户数据。协调层故障时可停止使用根级入口并恢复三个产品各自的已验收启动脚本，不删除数据或共享事实。 + + +## 三项目协调 E2E 排错 + +先从完整输出定位第一个失败阶段，不同时修改多个猜测原因。默认入口是： + +```powershell +pwsh scripts/e2e/coordination/run-coordination-e2e.ps1 +``` + +| 现象 | 检查 | 安全处理 | +|---|---|---| +| 缺少 `initdb.exe`、`pg_ctl.exe`、`createdb.exe` 或 `psql.exe` | 检查 `-PostgresBin` 是否指向同一 PostgreSQL 安装的 `bin` | 修正工具路径；不要改用生产数据库或默认 5432 | +| Python 缺少契约依赖 | 确认所选 Python 可创建 venv 且能安装仓库冻结依赖 | 修复 Python/依赖源后重试；不要把依赖临时装进产品环境充当固定基线 | +| Bell 正式迁移失败 | 查看当轮临时目录的 `bell-migrate.log`，核对首个 SQLSTATE | 修复迁移或工具链；不得跳过迁移、手工补表或连接业务库 | +| Sense/Bell 数据库隔离断言失败 | 检查生成的 owner/database 是否不同 | 停止测试；不得共享数据库、角色、JWT、Cookie 或账户空间 | +| Bell Rule/Alert 评估数偶发增加 | 检查是否把 ingress、rule、lifecycle 多个有状态 Go 包放在同一数据库并行运行 | 恢复 root harness 的串行阶段；不要降低断言或清除不可变事实 | +| `machine_token_*`、duplicate 或 conflict 与预期不符 | 核对 audience/scope/kid、请求绑定、jti 和 producer/source 业务键 | 保持稳定错误和原业务键；不得记录 Authorization、复用网页登录态或为重试改 source ID | +| Outbox 在 Bell 离线后未补投 | 核对 retry/lease/available_at、Bell 恢复和新 relay 进程 | 保留消息和历史，恢复 Bell 后重试；不得清空 Outbox/Receipt/Event | +| evidence timeout/unavailable 导致整条事件失败 | 检查 evidence resolver 与降级状态 | Event/Receipt/Alert 应继续保留；不得把失败伪装为 success | +| 端口仍占用或测试结束后有进程 | 确认进程是否由本轮测试启动，查看所属临时目录和状态 | 只停止能证明归属的进程；不得无条件 taskkill 或终止其他实例 | +| 秘密扫描失败 | 在本轮临时日志中搜索该随机测试值，禁止把值粘贴到工单 | 修复日志输出后重新运行；不得仅关闭扫描 | +| 需要保留失败现场 | 使用 `-KeepTemporary` 并记录明确绝对临时路径 | 目录只用于本机受控诊断，完成后按已核对路径清理；不得提交或共享 | +| 使用 `-SkipIndependentProductE2E` 后通过 | 只证明协调 harness 主体，不证明三端独立回归 | 修复依赖后重新运行默认完整入口，不能据此通过 MVP 验收 | + +若失败发生在 Sense、Brain 或 Bell 的独立 E2E，转到对应产品章节按该端首个错误排查；不得在协调文档工单中顺手修改产品代码。真实 GPU、真机、通知供应商、生产迁移、16 路长稳或客户现场问题不属于该隔离 E2E 的结论。 +