From 75bf70f375f58356e968b45139b54fcae391d1e8 Mon Sep 17 00:00:00 2001 From: ila <2+ila@noreply.git.ilapage.cn> Date: Mon, 31 Aug 2026 11:16:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20#151=20=E4=B8=89?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=9C=BA=E5=99=A8=E8=BA=AB=E4=BB=BD=E4=B8=8E?= =?UTF-8?q?=E5=AE=89=E5=85=A8=E4=BC=A0=E8=BE=93=20v1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Troubleshooting.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Troubleshooting.md b/Troubleshooting.md index b56d118..aa452b7 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -153,3 +153,18 @@ 3. 若同步提示本地镜像有未提交修改，先核对改动归属并停止覆盖。 4. Wiki 页面缺失、没有 revision、MCP/API 凭据不可用或映射准备删除/重命名时停止，由工单确认后处理。 5. PowerShell 显示乱码时先区分文件编码和控制台输出编码，不默认另起 PowerShell 或使用 `-ExecutionPolicy Bypass`。 + + +## 机器身份 v1 排错 + +| 现象/错误码 | 常见原因 | 检查 | 安全处理 | +|---|---|---|---| +| `machine_token_missing` | 未使用 Authorization Bearer 或格式错误 | 检查 connector 配置，不粘贴令牌 | 修复调用方；不改用 Cookie/query token | +| `machine_token_invalid` | 签名、kid、请求方法/路径/正文摘要或封闭字段不匹配 | 核对版本、kid 和请求绑定 | 停止重试，修复配置/实现 | +| `machine_token_expired` | 时钟偏差或令牌超过 5 分钟 | 检查双方 UTC 时钟 | 校时并签发新令牌，不延长长期 token | +| `machine_audience_denied` / `machine_scope_denied` | 目标产品或最小权限不匹配 | 核对公钥注册表和调用方向 | 修正精确授权，不添加通配符 | +| `machine_identity_revoked` | principal/key 已禁用或吊销 | 核对当前 kid 与轮换状态 | 切换已批准新 key；不得恢复旧 key绕过吊销 | +| `machine_token_replayed` | 同一 jti 被再次使用 | 检查重试是否重新签名 | 新建 jti，保留业务幂等键 | + +排错日志只记录稳定错误码、已认证 principal/kid 和 correlation ID；不得记录令牌、签名、密钥、完整 Authorization header 或秘密路径。无法安全恢复时关闭 connector，三端保持独立运行。 +