# 常见问题与故障排查（P0 高频场景）

本页汇总使用 MOI 控制台、AI Studio、Genesis 与 MatrixOne 云实例过程中最常见的高频异常与排查路径。若需检索特定 HTTP 或 JSON 返回码，请查看[错误码与异常状态参考](../reference/error-codes.md)。

## 1. 登录、账号邀请与工作区权限

| 现象 | 常见原因 | 排查与处理 |
| --- | --- | --- |
| 登录后界面缺少**新建工作流**、**创建知识库**或成员管理按钮 | 当前账号在该工作区绑定的角色未授予对应功能或对象权限 | 请工作区管理员在**用户权限 → 角色权限**中核对角色勾选范围，说明见[角色权限](../guides/ai-studio/permissions/roles.md) |
| 账号邀请被拦截或提示达到上限 | 账号注册级的“账号邀请”与“工作区成员邀请”独立计算；普通注册用户账号邀请默认上限为 10 | 邀请已有 MOI 账号加入团队工作区时，请直接进入工作区的**用户权限 → 用户管理**操作，详见[账号管理](../guides/billing/account.md)与[用户管理](../guides/ai-studio/permissions/users.md) |
| 生成个人访问令牌或调用接口时提示需要实名认证 | 当前部署开启了实名认证准入要求 | 使用账号当前**已验证手机号**与**真实姓名**完成核验后重试，步骤见[完成实名认证](../guides/billing/real-name.md) |
| 访问不同工作区对象时返回 `404` / `ErrNotFound` | 顶栏切换到了错误工作区，或 API 请求头 `X-Workspace-ID` 与资源归属工作区不一致 | 在顶栏工作区切换器中复制正确的[工作区](../guides/ai-studio/resource-center/workspace.md) ID 后重新提交 |

## 2. API 调用与认证凭据异常

| 现象 | 常见原因 | 处理步骤 |
| --- | --- | --- |
| 调用 AI Studio 接口返回 `ErrMultipleAuthCredentials` | 请求同时附带了多种凭据，最常见的是工具（Postman / Python `requests.Session` / 浏览器）自动保存并回传了产品会话 Cookie | 保持单一认证方式：AI Studio 仅使用 `X-API-Key` 与 `X-Workspace-ID`，并在客户端关闭或清空 Cookie jar；详细检查步骤见[调用失败时的检查](../developer/quickstart/ai-studio/http-api.md#调用失败时的检查) |
| 调用 AI Studio 传入 `Authorization: Bearer` 报登录失效或 `401` | 混用了 Genesis 与 AI Studio 的认证请求头规范 | Genesis 使用 `Authorization: Bearer`；AI Studio 须改用 `X-API-Key` |
| 调用 Genesis 接口返回 `402 insufficient_credit` | 当前账户 Credit 余额不足以继续扣费 | 前往[充值 Credit](../guides/billing/manage-billing.md)完成一次性充值，确认总览余额更新后重试 |
| 调用模型或已发布动态服务返回 `429` | 触发 Token Key / 服务账号 RPM、TPM、并发上限，或上游模型渠道限流 | 检查响应头 `Retry-After`，按指数退避策略重试或更换备用模型；确认模型是否在[模型列表](../reference/api/genesis/models.md)可用范围 |

## 3. 数据连接、载入任务与知识库排查

- **REST API 或对象存储连接器验证失败**：检查连接器认证类型、密钥是否过期、接口完整地址及是否启用可公开访问路径；分页与预览行为见[连接 REST API](../guides/ai-studio/data-sources/rest-api.md)。
- **数据载入任务长时间运行中或失败**：前往[载入任务](../guides/ai-studio/data-sources/load-tasks.md)展开任务详情查看阶段错误原因，核对源编码格式、目标 Catalog 表结构映射及目标计算实例是否处于就绪状态。
- **知识库问答无结果、缺来源或 NL2SQL 未命中表**：确认文档解析与索引任务已处于完成状态（[创建知识库与配置来源](../guides/ai-studio/knowledge-bases/create-and-sources.md)）；若在 **SQL 编辑器**手动建表但无法被知识库检索，请检查表是否按规范纳入 Catalog 管理（[SQL 编辑器](../guides/ai-studio/processing/sql-editor.md)）。

## 4. 计算实例、托管沙箱与费用异常

| 现象 | 常见原因 | 处理建议 |
| --- | --- | --- |
| 计算实例无法启动或启用失败 | 账户 Credit 余额不足（启用前额度检查拦截），或配额/底层资源暂时不可用 | 在[查看费用与用量](../guides/billing/cost-and-usage.md)确认余额充足；若依赖自定义 Python 包，检查[计算实例 · 配置自定义 Python 依赖](../guides/ai-studio/resource-center/compute.md#python)的 `requirements.txt` 格式与包源白名单限制 |
| 托管运行环境一直处于“等待中”或创建报 `SANDBOX_QUOTA_EXCEEDED` | 当前工作区的托管沙箱数量达到上限，或所选计算资源负载排队 | 清理不再使用的闲置托管环境；如确实需要更多并发环境，联系平台管理员调整工作区配额 |
| 托管环境网络请求被拦截 | 只勾选了工具或只填写了白名单域名之一，或未写明端口号 | 打开环境配置同时放行**允许联网工具**与按 `域名:端口` 填写的**网络白名单**（[终端、网络与环境维护](../guides/ai-studio/agents/runtime-environments/manage.md)） |
| 未发起对话仍有计算费用产生 | 创建了**托管运行环境**但未删除 | 托管环境自变为**就绪**起即使闲置也会连续按分钟计费；临时对话沙箱不单独收费。不再使用的托管环境应及时删除，详见[计算资源与沙箱计费规则](../guides/billing/credit-and-pricing.md#计算资源与沙箱计费规则) |

## 5. IM 通道与智能体异常

若飞书、企业微信、Slack 或 Telegram 机器人无法接收消息、回调校验失败或无回复，请直接按 [IM 接入常见问题与排查](../guides/ai-studio/agents/manage-agents/im-connection/troubleshoot.md) 核对签名凭证、事件订阅地址与模型发布状态。

## 6. MatrixOne 云实例连接、只读与计费边界

- **实例无法连接**：检查实例是否处于**运行中**、连接端点端口及**网络策略（IP 白名单）**是否允许当前客户端出口 IP，或调整 TLS 连接参数（见[数据库实例](../guides/matrixone/instances.md)）。
- **用户权限报错**：使用 `用户名:角色名` 形式登录核对角色上下文，避免直接在日常 SQL 中依赖默认高权限账号，详见[MatrixOne 权限](../guides/matrixone/permissions.md)。
- **实例账单找不到**：MatrixOne 实例的 CU、存储和续费账单与平台 Credit 账本分开核算，详见[实例计费](../guides/billing/matrixone-billing.md)。

## 提交工单前需要准备的信息

如果以上自检未能定位问题，请打开[技术支持与反馈](support.md)，并通过控制台**反馈助手**或支持邮箱附上以下信息（切勿包含密码、AK/SK 或访问令牌明文）：

- 工作区 ID、受影响资源名称及完整发生时间；
- 对应的载入任务 ID、工作流运行 ID、会话 ID、SQL `Query ID` 或 Genesis `Request ID`（充值异常请附订单号）；
- 完整 HTTP 状态码、`code` 与报错原文（可附脱敏截图）。
