docs: 记录 #151 三项目机器身份与安全传输 v1

Troubleshooting.md

@@ -153,3 +153,18 @@
 3. 若同步提示本地镜像有未提交修改，先核对改动归属并停止覆盖。
 4. Wiki 页面缺失、没有 revision、MCP/API 凭据不可用或映射准备删除/重命名时停止，由工单确认后处理。
 5. PowerShell 显示乱码时先区分文件编码和控制台输出编码，不默认另起 PowerShell 或使用 `-ExecutionPolicy Bypass`。
+
+<!-- machine-identity-v1:start -->
+## 机器身份 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，三端保持独立运行。
+<!-- machine-identity-v1:end -->