开始前
先固定现场，别急着重启：- 记下项目名称、功能入口、发生时间和界面提示原文（或接口返回的错误码与 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）的排障表逐条看容器状态 |
| 页面标题是「无法连接服务器」 | 正文是「请检查 AskTable 后端服务是否正在运行。」，按钮「重试」 | 确认主服务容器在运行，以及浏览器到站点的网络可达 |
| 页面标题是「用户信息加载失败」 | 正文是「无法加载您的账户信息，请退出后重新登录。」 | 点「退出登录」后重新登录；反复出现就带上发生时间提工单 |
| 「关于」页看不到版本号 | 「系统版本」卡里没有版本字符串 | 容器没起来或版本没注入，改看 docker compose images 确认镜像 |
| 邮件或飞书通知里的链接点不开 | 「系统设置」→「通用」→「前端访问地址」还是默认值 | 改成实际访问域名并保存 |
| 登录后马上回到登录页 | 接口返回 401，错误码是 TOKEN_EXPIRED 或 TOKEN_INVALID | 重新登录；反复出现时带上发生时间提工单 |
| 访问任意项目都跳到锁定页 | 页面标题是「AskTable 企业版已锁定」 | 见商业授权 |
| 页面样式或文案像旧版本 | 「关于」页版本号与刚部署的镜像不一致 | 前端静态资源与后端版本不一致，重新部署并强刷页面 |
数据接不进来
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 状态一直停在「正在分析元数据」或「排队中」 | 数据源状态指示器文字不变 | 点开状态指示器看错误详情；大批量元数据解析耗时较长 |
| 状态是「分析元数据失败」 | 状态文字是「分析元数据失败」 | 点状态指示器里的「重新初始化」或「重新同步」 |
| 状态是「不可用」 | 状态文字是「不可用」 | 点状态指示器里的重试按钮重新初始化 |
| 连接测试没过 | 弹窗标题「数据库连接失败」，正文是数据库返回的原始错误 | 逐项核对主机、端口、账号、密码、库名；云端部署确认已加数据库白名单 |
| 选表页一张表都没有 | 提示「数据库中没有任何库表」 | 确认账号对目标库有读权限；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_ 开头 | 见配置大模型的判定表 |
权限与访问
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 提示「权限不足」 | 错误码 PERMISSION_DENIED（HTTP 403） | 把该账号加进项目并补数据范围，见权限与数据安全 |
| 公开项目里点配置被弹回 | 错误码 VIEWER_READONLY，提示「当前为所有人可见的公开项目，不能修改资源配置」 | 切到自己的私有项目 |
| 用户看不到某个项目 | 左侧项目列表里没有该项目 | 项目设置 →「项目成员」把人加进去 |
| 提示「用户已被禁用」 | 错误码 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 测试失败」 | 见配置大模型 |
| 提示「此功能仅在配置官方 AI 代理通道时可用」 | 错误码 ASKTABLE_LLM_ONLY（HTTP 400） | 新建「AskTable 官方」类型的模型组并「设为默认」 |
飞书、嵌入与接口
| 现象 | 判定条件 | 处理 |
|---|---|---|
飞书里 @ 机器人没回复 | 见接入飞书机器人的判定表 | 按该页逐行对照 |
| 嵌入页提示「该嵌入地址已被停用。」 | 错误码 EMBED_DISABLED（HTTP 403） | 到智能体「嵌入」列表把开关打开 |
| 嵌入页提示「该网站未被允许嵌入此智能体。」 | 错误码 EMBED_ORIGIN_NOT_ALLOWED（HTTP 403） | 把宿主页域名加进「允许域名」，见把问数窗口嵌进网页 |
| 提示「AI 搜索索引未启用」 | 错误码 VALUE_INDEX_NOT_ENABLED（HTTP 400） | 见AI 索引；私有部署还要先加检索服务容器，见部署 AI 搜索 |
| 定时报告没发出来 | 错误码 REPORT_FAILED（HTTP 400） | 重新创建报告，见定时分析报告 |
| 接口返回 403 且提示配额 | 错误码 RESOURCE_QUOTA_EXCEEDED（HTTP 403） | 删掉不用的旧资源 |
升级与回滚
下一步
- 按现象查具体功能：常见问题
- 查错误码对应的 HTTP 状态：错误码
- 私有部署的容器与参数：私有部署（Docker）
- 备份、升级与回滚：版本升级与迁移