部署 FAQ

安装与服务

为什么 API 服务名是 `api` 而不是 `backend`？

当前 Compose、Kubernetes 和路由配置使用 api。旧脚本或旧文档中的 backend 引用应改为 api，例如 docker compose logs -f api。

为什么前端能打开但请求失败？

分两条链路排查：

浏览器请求：确认反向代理/Ingress 把 /api 转发到 api:8000，且 NEXT_PUBLIC_API_URL（前端镜像默认 /api/v1）是浏览器可访问的路径；浏览器侧请求是相对路径，不会被后端 API_V1_STR 用到，但两者路径前缀必须一致。
服务端渲染（SSR）请求：Next.js 服务端用 BACKEND_INTERNAL_URL 拼接 API 地址，代码默认 http://localhost:8000（Compose 注入 http://api:8000）。

单文件 K8s manifest 和 Helm 默认的 frontend Pod 不设置任何环境变量，因此 SSR 会回退到 http://localhost:8000——在 Pod 内这个地址不可达。浏览器流量经 Ingress 转发不受影响；如果依赖 SSR 服务端取数，请给 frontend 显式加 BACKEND_INTERNAL_URL=http://api:8000。

为什么 Beat 只能有一个副本？

Beat 是调度器。多个副本会重复投递定时任务，造成重复处理或重复通知。

改过 Worker 启动命令后，为什么 AgentRun 一直停在运行中？

worker 必须消费 default,agent,knowledge,workflow 四个队列。持久化 AgentRun 被路由到 agent 队列，一旦 -Q 里少了 agent，任务无人消费，会话会一直显示运行中且不会报错。恢复方法：把 -Q 改回四个队列，或另起一个 -Q agent 的 Worker。sandbox 队列只由 sandbox-worker 消费，不在这份列表里。

消息集成

飞书长连接显示已连接，为什么发消息没反应？

「已连接」只代表 WebSocket 建立成功。还需要订阅 im.message.receive_v1 事件、具备 im:message.p2p_msg:readonly 等权限并发布应用版本，同时后端要有消费 agent 队列的 worker 来托管接收器。缺任意一项都收不到消息，详见故障排查 → 飞书长连接 Connected 但收不到消息。

微信消息延迟或完全不回？

微信靠轮询：Beat 每 3 秒派发批次，批次 30 秒截止、认领 90 秒后可被接管。检查平台开关是否启用、Beat 是否重启过、worker 是否消费 default 队列，以及绑定是否为 connected。常见原因与排查步骤见故障排查 → 微信轮询暂停。

消息或产物没发出去，去哪看原因？

管理端 Delivery Log（/deliveries）按状态列出每条投递，error 与 error_detail 给出渠道返回的失败原因。没有记录表示上游没产生投递，而不是发送失败。字段说明见 Delivery Log。

为什么不再需要 `wechat-receiver` 服务？

统一集成后微信轮询由普通 Worker 消费 default 队列完成，飞书长连接由 agent 队列 Worker 托管，不再有独立接收服务。升级时删除该服务不会影响 Sandbox Worker：Agent 的代码工具仍然依赖它。

存储与扩展

API 扩容为什么需要共享卷？

本地上传存储挂载在 API。多个 API 副本必须看到同一目录，因此需要 ReadWriteMany 或对象存储；ReadWriteOnce 时保持单副本。

为什么恢复数据库后文件或检索仍然缺失？

数据库只包含元数据。原始文件在上传存储，向量在 Qdrant；三者必须从一致备份恢复。沙箱工作区与检查点是节点本地数据，不在备份范围内，节点磁盘丢失后无法恢复。

检索与任务

怎么单独扩容某一类任务？

官方部署的 worker 同时消费 default、agent、knowledge、workflow 4 个队列，整体扩容会同时增加这 4 类任务的吞吐。需要只扩容 AgentRun 执行时，额外启动一个只订阅单队列的 Worker（如 -Q agent）；sandbox 队列由独立的 sandbox-worker 消费。详见部署架构 → Celery 队列划分。

文档上传成功后为什么搜不到？

上传和处理是两个阶段。等待文档进入 completed，确认嵌入成功和 Qdrant 可用，再检查 Agent 关联的知识库。

混合检索为什么返回校验错误？

混合检索的 dense_weight 和 lexical_weight 不能同时为 0。全文通道还需要 PostgreSQL 的 pg_search。

沙箱与代码执行

官方部署需要改宿主内核参数吗？

不需要。Compose、Helm 和单文件 manifest 都让 sandbox-worker 以 root（user: "0" / runAsUser: 0）+ CAP_SYS_ADMIN 运行，用户命名空间创建走特权路径，也不需要在节点上放开非特权用户命名空间。只有自定义部署坚持让该 Worker 以非 root 运行时，才需要在节点级别放开（Ubuntu 23.10+ 的 kernel.apparmor_restrict_unprivileged_userns=0、Debian 的 kernel.unprivileged_userns_clone=1）。详见故障排查 → 沙箱任务报 bwrap 用户命名空间错误。