故障排查

先确认服务状态和最近配置变更，再从最早失败组件开始排查。

API 无法连接数据库

检查 POSTGRES_SERVER、POSTGRES_PORT、数据库密码和 PostgreSQL 就绪状态。服务名按部署方式不同：Compose 用 db，K8s 用 postgres，源码开发用 localhost。确认 pg_search 与 pg_stat_statements 已预加载（官方镜像启动参数含 shared_preload_libraries=pg_search,pg_stat_statements -c pg_stat_statements.track=all），并重启数据库后再检查扩展。K8s 中 API/Worker/Beat 都有 wait-for-postgres initContainer，Pod 若一直 Init 说明数据库尚未就绪。

前端无法访问 API

确认外部代理/Ingress 将 /api 路由到 api:8000，且前端构建期 NEXT_PUBLIC_API_URL 与后端 API_V1_STR（默认 /api/v1）前缀一致。不要在容器内将 API 地址设置为浏览器无法解析的内部主机，也不要把 localhost 用作 Sandbox Worker 的 API 地址。

浏览器请求正常但页面服务端取数失败时，检查 frontend 是否设置了 BACKEND_INTERNAL_URL：代码默认 http://localhost:8000（Compose 注入 http://api:8000），单文件 K8s manifest 与 Helm 默认不注入该变量，SSR 会打到 Pod 内的 localhost:8000。

Worker 不处理任务

检查 Redis 连接、密码、队列名称和 Worker 日志。知识库使用 Celery 后台处理；beat 只能运行一个副本。清理或重启 Worker 前先确认没有正在处理的生产文档。

按队列定位积压。五条队列分别是 default、agent、knowledge、workflow（由 worker 消费）和 sandbox（由 sandbox-worker 消费）：

# 设置了 REDIS_PASSWORD 时加 -a
docker compose exec redis redis-cli llen agent
docker compose exec redis redis-cli llen knowledge
docker compose logs -f worker

任务进了队列但没人消费，说明消费该队列的 Worker 命令/部署不对。最典型的是 worker 的 -Q 少了 agent：持久化 AgentRun 全部堆在 agent 队列，会话一直停在运行中且不报错。队列与任务的完整对应关系见部署架构 → Celery 队列划分。

Sandbox 产物上传失败

确认 SANDBOX_ARTIFACT_UPLOAD_BASE_URL=http://api:8000、API 与 Sandbox Worker 使用相同签名配置，或配置专用 SANDBOX_ARTIFACT_UPLOAD_API_KEY。产物必须位于 /workspace 内（否则策略直接拒绝），上传走内部端点 /api/v1/upload/sandbox-artifact，单文件与总量默认均不超过 10MB。Worker 和 Sandbox Worker 不挂 uploads 卷，必须能通过 API_INTERNAL_BASE_URL 访问 API。

沙箱任务报 bwrap 用户命名空间错误

bwrap: No permissions to create new namespace, likely because the kernel does not allow non-privileged user namespaces.

项目提供的部署（Docker Compose、Helm、Kubernetes）让 sandbox-worker 以 root + CAP_SYS_ADMIN 运行，用户命名空间创建走特权路径，不应出现此错误。出现该错误通常说明：Worker 未按提供的安全配置运行（如自定义部署保持非 root、cap_add: SYS_ADMIN 缺失、seccomp=unconfined 被覆盖）。自定义非 root 部署需在节点级别启用非特权用户命名空间（seccomp=unconfined 无效）：Ubuntu 23.10+ 执行 sysctl -w kernel.apparmor_restrict_unprivileged_userns=0；Debian 执行 sysctl -w kernel.unprivileged_userns_clone=1，通过 /etc/sysctl.d/ 持久化后用 unshare -U true 验证。Kubernetes 中需对每个节点生效，无法按 Pod 设置。完整说明见 代码沙箱 → 宿主内核要求。

Redis 连接失败

确认 Redis 运行：docker compose ps redis 与 docker compose logs redis；用 docker compose exec redis redis-cli ping（期望 PONG，有密码时 -a <password>）测试；核对 REDIS_HOST/REDIS_PORT/REDIS_PASSWORD。Celery broker 与结果后端由 REDIS_* 派生，无需单独配置。

Qdrant 连接失败

确认 Qdrant 运行：docker compose ps qdrant；用 curl http://localhost:6333/healthz 测试；核对 QDRANT_URL（Compose 为 http://qdrant:6333）与 QDRANT_API_KEY。

SSO 登录失败

SSO 提供商通过站点设置 > SSO 配置（无 CLI 检查命令）。核对回调地址与 FRONTEND_URL 一致；查看提供商日志；清除浏览器 Cookie 和 SSO 会话后重试。

Agent 无响应

检查 API 日志中的 agent 相关错误；LLM 的 Key/base_url 按提供商存在数据库中、由 模型 页面管理——不是环境变量（env | grep OPENAI_API_KEY 查不到属正常）。用模型页面的连接测试功能验证；检查提供商配额/限速；查看 Worker 日志。

工作流执行失败

docker compose logs api | grep workflow 查看执行日志；确认 Worker 与 Beat 运行（docker compose ps worker）；工作流卡在运行中时重启 docker compose restart worker beat；检查节点配置、循环依赖和单个节点测试。

文档上传失败

知识库单文件上传上限由站点设置 kb_document_max_upload_size_mb 控制（默认 50MB），不是环境变量。API 独占上传目录（Worker 走内部上传网关）：docker compose exec api df -h /app/uploads 检查磁盘。上传成功后处理失败可从知识库文档界面重新触发处理。

检索失败

1. 文档状态必须是 completed。
2. 嵌入模型必须存在、授权且向量维度一致。
3. Qdrant 必须可连接。
4. 混合/全文检索需要 PostgreSQL 与 pg_search。
5. 重排序失败时检查 rerank 模型凭据和供应商配额。
6. 读取检索实验室的 diagnostics 与 timings。

HTTP 工具或内网地址被拦截

自定义 HTTP 工具、工作流 HTTP 请求节点、知识库的 URL 导入/预览抓取和数据库连接测试都受 站点设置 > 安全 > 出站网络访问白名单（ssrf_allowed_targets）约束。该白名单是数据库 SiteSetting，不是环境变量，默认允许公网、拦截私网与回环地址。企业内网目标需要逐条加入，最多 200 条，每行一条：

• 单个 IP：192.168.1.50、10.20.1.10
• CIDR 网段：10.10.0.0/16、172.20.0.0/24
• 精确域名：oa.company.local、api.internal.service
• 通配域名：*.corp.internal

回环地址永久禁止，是为了保护宿主机本地服务与 Redis/Docker 端口不被 Agent 滥用。容器内需要访问同宿主机的服务时，改用宿主机 LAN IP 或 host.docker.internal。使用 Clash/Surge/Mihomo 等 TUN 模式透明代理（Fake-IP）的部署不需要额外配置：198.18.0.0/15 已内置放行，否则该网段会被 ipaddress 判为私网而误拦公网域名。

模型端点白名单（站点设置 > 安全 > 模型端点白名单，model_endpoint_allowlist）是独立策略，只作用于 LLM、嵌入、重排和媒体供应商，且是默认拒绝：空白名单会阻止所有模型端点，但允许管理员显式放行 http://localhost:11434 这类本地推理服务。不要用出站网络白名单代替它。

模型调用失败

检查模型 is_enabled、团队授权、端点白名单、API Key、上下文长度、供应商限速和类型能力。错误码 6103 表示配额超限，6104 表示未授权。