03 常见报错与排查
本节摘要:这是全书最后的检索表,用「报错 → 原因 → 解决」三列给出最常踩的坑。按主题分类。遇到报错先查这里。
一、安装与运行时类
| 报错 |
原因 |
解决 |
| 找不到模块 |
用错包管理器(非 pnpm) |
用 pnpm 重装 |
| 依赖装不上/慢 |
前端重+原生依赖编译 |
耐心等;确认网络 |
| node-gyp 失败 |
缺编译工具链 |
Windows 装 VS Build Tools |
| 服务端起不来 |
缺 Bun |
装 Bun |
| Electron 报原生依赖错 |
原生依赖未编译 |
检查工具链/重装 |
二、鉴权与权限类
| 报错 |
原因 |
解决 |
| 401 未授权 |
令牌没带/无效 |
检查令牌 |
| 403 禁止 |
scope 不够(如 viewer 写) |
换更高 scope 或改只读操作 |
| viewer 不能写 |
强制只读(反代层) |
正常,用 owner/collaborator |
| 审批超时 |
manual 模式没及时响应 |
响应审批或改 auto |
三、引擎托管类
| 报错 |
原因 |
解决 |
| 引擎起不来 |
托管失败/信任未注册 |
查服务端日志 |
| 配置注入没生效 |
配置文件未同步/引擎未重建 |
查新鲜度同步+Reload |
| 改了能力引擎没更新 |
Reload 未触发 |
查指纹/事件存储 |
| 引擎二进制更新没生效 |
需重启(非 Reload 能解决) |
重启引擎 |
| 报错 |
原因 |
解决 |
| 能力未发现 |
检索没匹配/能力库空 |
查能力是否存在+描述 |
| 执行被治理拒绝 |
权限/策略不允许 |
查权限+策略 |
| MCP 连不上 |
传输/认证问题 |
查连接状态(needs_auth?) |
| 技能不显示 |
权限过滤/frontmatter 缺 name |
查权限+SKILL 格式 |
五、实时协同类
| 报错 |
原因 |
解决 |
| 改了能力没实时生效 |
轮询未拉到/指纹未变 |
查事件端点+指纹 |
| 客户端丢事件 |
两次轮询间隔太久(超环形缓冲) |
下次全量重载补 |
| 引擎重建卡住 |
串行队列排队中 |
等前面的重载完成 |
六、桌面与前端类
| 报错 |
原因 |
解决 |
| 端口冲突 |
多工作区端口撞 |
运行时管理器自动避让 |
| IPC 调用失败 |
命令名错/类型不符 |
查共享类型包 |
| 架构不匹配警告 |
Rosetta 跑 x64 |
换原生架构版 |
| 品牌图标错乱 |
竞态(序列号) |
序列号防竞态自动处理 |
七、Connect Link 类
| 报错 |
原因 |
解决 |
| 验签失败 |
公钥不在可信集/被篡改 |
查签发方公钥 |
| 重放被拒 |
jti 已用过 |
正常,每链接用一次 |
| 交换 409 |
code 已用 |
换新 code |
| 交换 410 |
code 过期 |
换新 code |
| 身份漂移拒绝 |
claims.iss ≠ apiBaseUrl |
查 SSRF/配置 |
八、企业 Den 类
| 报错 |
原因 |
解决 |
| Den 起不来 |
缺 Docker/MySQL |
起 Docker + MySQL |
| SSO 不工作 |
身份系统配置错 |
查 SSO 配置 |
| SCIM 不同步 |
SCIM 端点配置错 |
查 SCIM 连接 |
| 计费失败 |
支付服务配置错 |
查 Stripe 等 |
| Helm 部署失败 |
K8s 配置错 |
查 values.yaml |
九、排查通用思路
遇到任何报错,按这个顺序排查:
1. 看报错信息本身(往往直接指出问题)
│
2. 查本表对应类别
│
3. 查服务端/引擎日志
│
4. 查事件流/追踪(可观测)
│
5. 查对应章节深读原理
十、本节要点回顾
- 八大类报错:安装运行时/鉴权权限/引擎托管/能力meta-MCP/实时协同/桌面前端/ConnectLink/企业Den。
- 三列格式:报错→原因→解决。
- 安装首查 pnpm:必须 pnpm,缺 Bun 装 Bun。
- 权限首查 scope:viewer 写被拒是正常。
- 引擎更新:Reload 管实例级,二进制更新需重启。
- 排查思路:报错信息→本表→日志→追踪→章节。
附录 A 到此结束。全书(十三章 + 附录)正文与检索表全部完成。