故障排查

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

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 队列划分。

消息投递失败或消息未收到

先查管理端 Delivery Log（/deliveries，接口 GET /api/v1/admin/deliveries），而不是只看 Agent 日志：

• 没有记录：上游没产生投递。确认 AgentRun 已结束、该集成能力（Agent 会话）已启用、个人设置没有暂停新消息或排队。
• status=error：error 与 error_detail 给出渠道返回的原因，常见是凭据过期、机器人未被拉进会话、收件人未绑定，或产物超过上限（图片 10 MiB、MP4 与其他文件 30 MiB）。
• status=pending 长时间不动：没有 Worker 在消费该渠道任务。检查 worker 是否在跑、-Q 是否包含 agent（飞书）与 default（微信轮询）。
• status=sending 卡住：渠道请求超时或网络不通，查看 worker 日志中的渠道错误。
• status=unavailable：集成被关闭或不在当前团队，重新启用能力后再试。

投递表是单表 integration_deliveries。从旧版本升级后如果这里为空且日志报关系不存在，说明迁移没跑完或 Worker 与 API 不同版本，按升级指南重新执行。

飞书长连接显示 Connected 但收不到消息

长连接建立成功只说明 WebSocket 通了，消息要进来还依赖事件订阅与权限：

1. 飞书开放平台必须订阅 im.message.receive_v1（接收消息）并发布版本，管理员审批通过。
2. 应用需具备 im:message.p2p_msg:readonly（收私聊）、im:message:send_as_bot（发消息）、im:resource（附件）、contact:user.base:readonly（身份）。群聊 @ 权限不能替代私聊接收权限。
3. 后端要有一个消费 agent 队列的 Worker：接收器只在这些 Worker 里托管，靠 Redis 租约选主。-Q 少了 agent 就没人接管长连接。
4. 个人设置若暂停了新消息，消息会被丢弃而不进入 AgentRun；在个人设置里恢复后再发一条试试。
5. 群里 @ 机器人、机器人自己发的消息与未绑定身份的用户消息都会被忽略，属于预期行为。

配置生效后请发送新的私聊消息验证；此前未接收的消息不保证重放。

微信轮询暂停

微信轮询条目由 Beat 按集成能力动态注册。整条链路不动时按顺序检查：

1. 平台开关：微信 iLink 的 Agent 会话或知识采集能力必须启用；都关闭时 Beat 会移除轮询条目，日志里没有报错属正常。
2. Beat 在跑且是单副本：docker compose ps beat / kubectl get pods -l app=beat。升级后必须重启过一次 Beat，否则它可能仍跑旧调度器。
3. default 队列有消费者：轮询派发任务路由到 default，worker 的 -Q 必须包含它。
4. 批次槽位被占满：WECHAT_POLL_MAX_BATCHES（默认 8）个槽位都带未过期认领时，新一轮会认领不到。批次 30 秒截止、认领 90 秒过期，正常几轮内自愈；持续占满说明轮询请求超时，检查网络与微信端限流。
5. 绑定状态：只有 status=connected 的绑定会被轮询，二维码授权失效需要重新绑定。

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 设置。完整说明见 代码沙箱 → 宿主内核要求。

沙箱会话无法恢复或检查点失败

同一会话的执行、检查点与清理都路由到它首次落地的 Sandbox Worker。相关报错通常指向磁盘身份或检查点：

• 启动报 Worker ID 冲突：SANDBOX_WORKER_ID 与磁盘上 .worker-identity.json 的记录不一致。恢复原值，或换一块空磁盘让系统重新生成；不要把同一个 SANDBOX_WORKER_ID 挂到不同磁盘。
• 检查点持续失败：SANDBOX_CHECKPOINT_ROOT 必须位于 SANDBOX_WORKSPACE_ROOT 之外，且与工作区在同一块持久磁盘上。Compose 用 sandbox_data 卷、K8s 用节点 hostPath；容器重建后挂载路径变了，旧检查点就找不到了。
• 会话重置次数用尽：默认 SANDBOX_SESSION_MAX_RESETS=1，超过后不再从检查点恢复，用户需要新建会话。
• 节点或磁盘丢失：该节点上的会话无法迁移，只能重新执行；长期要保留的内容应导出或上传到对象存储。

排查顺序：查看 sandbox-worker 日志中的 worker_id、storage_id 与检查点错误 → 确认挂载点没变 → 确认磁盘未满（SANDBOX_MAX_DISK_MB）→ 再考虑提高 SANDBOX_SESSION_MAX_RESETS。

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

沙箱出口白名单（站点设置 > 安全 中的 sandbox_network_allowlist，由 sandbox_network_allowlist_enabled 控制）是另一套列表：只接受精确 DNS 主机名，不接受上面的通配域名、CIDR 或 IP，也不作用于服务端发起的 HTTP 请求。

回环地址永久禁止，是为了保护宿主机本地服务与 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 表示未授权。