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

This commit is contained in:
QiuSW
2026-08-31 11:23:52 +08:00
parent 06e0790f00
commit ae9bd015c2
5 changed files with 86 additions and 10 deletions
+17 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Troubleshooting
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
wiki_revision: 046624c1b2d7963ef733b4c9687d5dec14771388
synchronized_at: 2026-08-27T09:05:32Z
wiki_revision: 75bf70f375f58356e968b45139b54fcae391d1e8
synchronized_at: 2026-08-31T03:18:53Z
<!-- gitea-wiki-mirror:end -->
# 故障排查
@@ -161,3 +161,18 @@ synchronized_at: 2026-08-27T09:05:32Z
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 -->