# 故障排查 排查服务启动、页面访问和数据连接问题。 本页用于排查服务启动、页面访问和数据连接等系统问题。具体功能的使用问题见[常见问题](https://docs.asktable.com/reference/faq)。 ## 开始前 先固定现场，别急着重启： - 记下项目名称、功能入口、发生时间和界面提示原文（或接口返回的错误码与 HTTP 状态）。 - 能拿到 trace id 就带上：对话页的「复制 trace id」。 - 判断范围：只有一个人受影响，还是一批人；只有一个项目受影响，还是全部项目。这一步直接决定往哪查。 - 私有部署：先确认能登录宿主机，能执行 `docker compose ps` 和查看容器日志。 ## 关键约束 | 项目 | 值或默认 | 在哪里改 | | -------------------- | ----------------------------------------------------------------------- | ------------------------------- | | 私有部署的服务器、网络、备份、升级、日志 | 由你方负责 | — | | 镜像与版本发布 | 由 AskTable 负责 | — | | 对外端口 | 只有主服务开 8000，其余容器不映射宿主机端口 | `docker-compose.yaml` 的 `ports` | | 后端存活判定 | `curl -sS http://127.0.0.1:8000/api/v1/version` 返回 JSON | — | | 当前版本 | 头像 →「系统设置」→ 左侧「关于」→「系统版本」 | — | | 业务异常与故障 | 4xx 是业务异常，5xx 才代表服务端故障 | — | | 接口错误结构 | `code`、`message`、`params`；scope 不足是 `{"detail": "Insufficient scopes"}` | — | ## 出问题怎么判断 ### 服务与页面 | 现象 | 判定条件 | 处理 | | --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- | | 页面一直转圈或空白 | `curl -sS http://127.0.0.1:8000/api/v1/version` 不返回 JSON | 后端没起来，按[私有部署（Docker）](https://docs.asktable.com/deploy/docker)的排障表逐条看容器状态 | | 页面标题是「无法连接服务器」 | 正文是「请检查 AskTable 后端服务是否正在运行。」，按钮「重试」 | 确认主服务容器在运行，以及浏览器到站点的网络可达 | | 页面标题是「用户信息加载失败」 | 正文是「无法加载您的账户信息，请退出后重新登录。」 | 点「退出登录」后重新登录；反复出现就带上发生时间提工单 | | 「关于」页看不到版本号 | 「系统版本」卡里没有版本字符串 | 容器没起来或版本没注入，改看 `docker compose images` 确认镜像 | | 邮件或飞书通知里的链接点不开 | 「系统设置」→「通用」→「前端访问地址」还是默认值 | 改成实际访问域名并保存 | | 登录后马上回到登录页 | 接口返回 401，错误码是 `TOKEN_EXPIRED` 或 `TOKEN_INVALID` | 重新登录；反复出现时带上发生时间提工单 | | 访问任意项目都跳到锁定页 | 页面标题是「AskTable 企业版已锁定」 | 见[商业授权](https://docs.asktable.com/admin/license) | | 页面样式或文案像旧版本 | 「关于」页版本号与刚部署的镜像不一致 | 前端静态资源与后端版本不一致，重新部署并强刷页面 | ### 数据接不进来 | 现象 | 判定条件 | 处理 | | ---------------------- | --------------------------------------------- | ------------------------------------- | | 状态一直停在「正在分析元数据」或「排队中」 | 数据源状态指示器文字不变 | 点开状态指示器看错误详情；大批量元数据解析耗时较长 | | 状态是「分析元数据失败」 | 状态文字是「分析元数据失败」 | 点状态指示器里的「重新初始化」或「重新同步」 | | 状态是「不可用」 | 状态文字是「不可用」 | 点状态指示器里的重试按钮重新初始化 | | 连接测试没过 | 弹窗标题「数据库连接失败」，正文是数据库返回的原始错误 | 逐项核对主机、端口、账号、密码、库名；云端部署确认已加数据库白名单 | | 选表页一张表都没有 | 提示「数据库中没有任何库表」 | 确认账号对目标库有读权限；Oracle 要填对「Service Name」 | | 提示「另一次刷新正在进行中，请等其完成再试」 | 错误码 `TABLE_REFRESH_ALREADY_RUNNING`（HTTP 409） | 等本次刷新结束 | | 文件型数据源有部分 Sheet 没进来 | 状态指示器弹出「以下文件中的某些Sheet无法解析」 | 按逐条的拒绝原因和修复建议改源文件后重新上传 | ### 对话与查询 | 现象 | 判定条件 | 处理 | | ------------------------------ | -------------------------------------- | ---------------------------------------------------- | | 查询一直不出结果 | 错误码 `QUERY_TIMEOUT`（HTTP 504） | 放宽数据源「设置」→「查询设置」的超时，或调大「系统设置」→「数据源」→「全局查询超时（秒）」 | | 提示「系统繁忙，请稍后重试」 | 错误码 `SERVICE_BUSY`（HTTP 503） | 稍后重试；持续出现时看主服务容器的资源占用 | | 提示「对话正在处理中」 | 错误码 `CHAT_PROCESSING`（HTTP 409） | 等当前这轮结束 | | 提示「上下文正在压缩中，请稍候」 | 错误码 `COMPACTION_IN_PROGRESS`（HTTP 409） | 等压缩结束 | | 提示「当前会话绑定的智能体已被删除，请新建会话」 | 错误码 `DATA_AGENT_DELETED`（HTTP 404） | 新建对话 | | 提示「当前会话绑定的角色已被删除，请重新选择角色或新建会话」 | 错误码 `ROLE_DELETED`（HTTP 404） | 重新选角色或新建对话 | | 报模型类错误 | 错误码以 `LLM_` 开头 | 见[配置大模型](https://docs.asktable.com/admin/models)的判定表 | ### 权限与访问 | 现象 | 判定条件 | 处理 | | --------------- | -------------------------------------------------- | ---------------------------------------------------------------- | | 提示「权限不足」 | 错误码 `PERMISSION_DENIED`（HTTP 403） | 把该账号加进项目并补数据范围，见[权限与数据安全](https://docs.asktable.com/permissions) | | 能进入公开项目，但修改配置被拒 | 错误码 `PERMISSION_DENIED`（HTTP 403），当前有效项目角色是 Member | 修改配置需要项目负责人或项目管理员；检查显式项目角色和公开项目默认角色 | | 用户看不到某个项目 | 左侧项目列表里没有该项目 | 项目设置 →「项目成员」把人加进去 | | 提示「用户已被禁用」 | 错误码 `USER_DISABLED`（HTTP 403） | 管理员在左侧「用户」里处理该账号 | | 接口返回 401 | 响应体是 `{"detail": "Insufficient scopes"}` | 换 `admin` 类型的 API-Key，或找项目「所有者」提权 | | 提示「项目已锁定」 | 错误码 `PROJECT_LOCKED`（HTTP 423） | 联系平台管理员解除锁定 | ### 模型与联网搜索 | 现象 | 判定条件 | 处理 | | ---------------------------- | ----------------------------------------- | ------------------------------------------------ | | 智能体的「联网搜索」开关打不开 | 「系统设置」→「联网搜索」三项里有一项为空 | 填齐「Base URL」「API Key」「模型」后保存 | | 提示「联网搜索未配置，请联系系统管理员在系统设置中配置」 | 错误码 `WEB_SEARCH_NOT_CONFIGURED`（HTTP 400） | 同上 | | 提示「输入内容触发了内容安全审查，请修改后重试」 | 错误码 `LLM_CONTENT_FILTERED`（HTTP 400） | 换问法；这是上游审查，不是 AskTable 拦的 | | 「测试模型」失败 | 提示「模型 X 测试失败」 | 见[配置大模型](https://docs.asktable.com/admin/models) | | 提示「此功能仅在配置官方 AI 代理通道时可用」 | 错误码 `ASKTABLE_LLM_ONLY`（HTTP 400） | 新建「AskTable 官方」类型的模型组并「设为默认」 | ### 飞书、嵌入与接口 | 现象 | 判定条件 | 处理 | | --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | 飞书里 `@` 机器人没回复 | 见[接入飞书机器人](https://docs.asktable.com/integrations/feishu)的判定表 | 按该页逐行对照 | | 嵌入页提示「该嵌入地址已被停用。」 | 错误码 `EMBED_DISABLED`（HTTP 403） | 到智能体「嵌入」列表把开关打开 | | 嵌入页提示「该网站未被允许嵌入此智能体。」 | 错误码 `EMBED_ORIGIN_NOT_ALLOWED`（HTTP 403） | 把宿主页域名加进「允许域名」，见[把问数窗口嵌进网页](https://docs.asktable.com/integrations/embed) | | 提示「AI 搜索索引未启用」 | 错误码 `VALUE_INDEX_NOT_ENABLED`（HTTP 400） | 见[AI 索引](https://docs.asktable.com/data/ai-search)；私有部署还要先加检索服务容器，见[部署 AI 搜索](https://docs.asktable.com/deploy/ai-search) | | 定时报告没发出来 | 错误码 `REPORT_FAILED`（HTTP 400） | 重新创建报告，见[定时分析报告](https://docs.asktable.com/integrations/scheduled-reports) | | 接口返回 403 且提示配额 | 错误码 `RESOURCE_QUOTA_EXCEEDED`（HTTP 403） | 删掉不用的旧资源 | ### 升级与回滚 | 现象 | 判定条件 | 处理 | | ---------- | ---------------------------------- | ------------------------------------------------------------------------ | | 升级后容器起不来 | `docker compose ps` 里主服务不是 running | 看容器日志定位；用升级前的备份回滚，见[版本升级与迁移](https://docs.asktable.com/deploy/migration) | | 升级后接口报 500 | 错误码 `INTERNAL_ERROR`，且升级前正常 | 按[版本升级与迁移](https://docs.asktable.com/deploy/migration)核对是否漏了该版本区间的手动步骤 | | 升级后登录不上 | 接口返回 401，或「关于」页版本号没变 | 确认前后端镜像版本一致，且容器已重建 | | 回滚后数据不对 | 回滚用的是升级后的数据库 | 回滚必须连数据库备份一起恢复，见[版本升级与迁移](https://docs.asktable.com/deploy/migration) | ## 下一步 - 按现象查具体功能：[常见问题](https://docs.asktable.com/reference/faq) - 查错误码对应的 HTTP 状态：[错误码](https://docs.asktable.com/reference/error-codes) - 私有部署的容器与参数：[私有部署（Docker）](https://docs.asktable.com/deploy/docker) - 备份、升级与回滚：[版本升级与迁移](https://docs.asktable.com/deploy/migration)