From ebe4c67ad14282217bf316a89272139a274a52a3 Mon Sep 17 00:00:00 2001 From: ila <2+ila@noreply.git.ilapage.cn> Date: Mon, 31 Aug 2026 16:23:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20#154=20=E6=A0=B9?= =?UTF-8?q?=E7=BA=A7=E9=83=A8=E7=BD=B2=E7=BC=96=E6=8E=92=E9=AA=8C=E6=94=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Troubleshooting.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/Troubleshooting.md b/Troubleshooting.md index c327c99..63b212e 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -187,3 +187,27 @@ 日志只记录稳定错误码、request/correlation ID、已认证 principal/kid 和脱敏业务引用；不得记录私钥、令牌、完整 Authorization、摄像头凭据、内部证据路径或事件完整敏感载荷。 + + +## 根级协调编排排错 + +先使用与启动时相同的仓库外清单查询状态： + +```powershell +pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product all +``` + +| 现象/状态 | 检查 | 安全处理 | +|---|---|---| +| 清单校验失败 | 检查包、env、私钥路径是否存在且位于仓库和包外；检查三端端口、目录、数据库、Cookie、JWT、账户和身份是否独立 | 修正仓库外清单或环境文件；不得放宽隔离断言或把秘密写进仓库 | +| `port ... is already in use` | 用状态命令确认是否已有受管实例，再检查对应监听端口 | 先按归属停止旧实例或为产品分配独立端口；不得终止未知进程 | +| `stopped` | 没有该产品状态文件 | 按需单独启动；不代表其他产品异常 | +| `unhealthy` | 进程仍归属本实例，但 HTTP/进程健康检查失败 | 查看该产品独立 `coordination.err.log`、`coordination.out.log` 和产品日志；修复该端，不自动重启其他端 | +| `stale` / `ownership-mismatch` | PID 已复用、启动器或命令令牌与状态不符 | 不会停止该进程；人工核对进程与状态文件，确认归属后再处理 | +| `stale` / `manifest-drift` | 运行中的实例来自不同清单摘要 | 使用原清单安全停止，或确认归属后停止再以新清单启动；不得用新清单覆盖运行事实 | +| 单端启动失败 | 查看该端协调日志、产品日志和退出码 | 编排只清理该端新进程；确认其他端状态，修复失败端后单独重试 | +| connector 使对端成为启动强依赖 | connector 开关或产品配置错误 | 关闭对应 event export、ingress、relay 或 evidence connector，恢复三端独立运行；保留 Outbox/Receipt/Event 等持久事实 | +| 停止命令拒绝执行 | 状态归属不匹配，或产品停止入口返回非零 | 不使用无条件 taskkill；先核对 PID、启动器、命令令牌和产品停止日志 | + +日志和状态不得包含环境变量值、密码、JWT、token、私钥、完整 Authorization、摄像头凭据或客户数据。协调层故障时可停止使用根级入口并恢复三个产品各自的已验收启动脚本，不删除数据或共享事实。 +