故障排查 - LangBot

本文用于集中记录常见故障的排查路径。当前先覆盖 Docker 部署时容易遇到的问题，后续可以继续补充模型、机器人适配器、MCP、Skill 等章节。以下命令默认在 LangBot/docker 目录执行。

Docker 部署

启动前快速确认

需要使用沙箱、stdio MCP 托管、Skill 添加/编辑等能力时，请使用 all profile 启动：

docker compose --profile all up -d

确认服务状态：

docker compose --profile all ps

正常情况下应看到：

langbot：WebUI 和后端服务，默认映射 5300 和 2280-2285。
langbot_plugin_runtime：插件运行时，默认映射 5401。
langbot_box：Box Runtime 控制面，用于创建沙箱容器。

如果只运行 docker compose up，不会启动 langbot_box，stdio MCP、Skill 添加/编辑和部分沙箱能力将不可用。

端口被占用

症状

docker compose up 报端口绑定失败。
WebUI 无法访问 http://127.0.0.1:5300。
日志中出现 port is already allocated、bind: address already in use 等信息。

处理方式

先确认占用端口的进程。Linux/macOS：

lsof -i :5300
lsof -i :5401

Windows PowerShell：

Get-NetTCPConnection -LocalPort 5300,5401 | Select-Object LocalPort,OwningProcess
Get-Process -Id <PID>

如果确认是旧的 LangBot、插件运行时或测试进程，可以停止该进程后重新启动：

docker compose --profile all up -d

如果不能停止占用进程，请修改 docker-compose.yaml 中对应端口映射，避免与现有服务冲突。

Box Runtime 未启动或不可用

症状

页面或日志提示 No sandbox backend (Docker/nsjail/E2B) is ready。
stdio 模式 MCP 一直不可用。
Skill 无法安装、激活或编辑。

常见原因

没有使用 --profile all 或 --profile box 启动。
langbot_box 没有运行。
当前用户或 Docker Desktop 无法访问 Docker。
Linux 主机上当前用户没有 Docker socket 权限。

处理方式

确认 langbot_box 已启动：

docker compose --profile all ps
docker logs langbot_box --tail 100

确认 Docker 可用：

docker info

Linux 上如果当前用户不能访问 Docker，可加入 docker 用户组后重新登录：

sudo usermod -aG docker $USER
newgrp docker
docker info

之后重新创建容器：

docker compose --profile all up -d --force-recreate

Box 根目录挂载失败

症状

日志中出现 host_path is outside allowed_mount_roots。
日志中出现 host_path must point to an existing directory on the host。
Docker Desktop 环境中，Box 根目录被解析为 /run/desktop/... 后被拒绝。
stdio MCP 或 Skill 相关沙箱容器无法创建。

原因

langbot_box 会通过宿主机 Docker socket 创建沙箱容器。沙箱容器看到的是宿主机路径，因此 Box 根目录的“宿主机路径”和“容器内路径”必须保持一致，并且该路径必须位于 allowed_mount_roots 内。

处理方式

在 LangBot/docker/.env 中设置一个 Docker 能挂载、且不会被 Box 安全规则拒绝的绝对路径：

LANGBOT_BOX_ROOT=/var/lib/langbot/box

Windows Docker Desktop 可以使用 Docker VM 可识别的路径，例如：

LANGBOT_BOX_ROOT=/host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box

确保目录存在后重建容器：

docker compose --profile all up -d --force-recreate

如果之前已经手动修改过 docker/data/config.yaml，请同步检查：

box:
  local:
    host_root: /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
    allowed_mount_roots:
      - /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box

大量 stdio MCP 启动失败或长时间 connecting

症状

MCP 状态停留在 connecting 或变为 error。
docker logs langbot_box 中出现 Cannot fork。
同时安装较多 stdio 模式 MCP 后，原本可用的 MCP 也开始启动失败。

原因

stdio MCP 会运行在 Box 沙箱中。默认 Box profile 的 PID 限制较低，同时启动多个 npx、uvx MCP 时可能达到沙箱进程数限制。

处理方式

在 docker/data/config.yaml 中把 Box profile 调整为资源更高的内置 profile：

box:
  local:
    profile: network_extended

然后停止 LangBot 和 Box，删除旧共享沙箱，让新配置生效。 Linux/macOS：

docker compose --profile all stop langbot langbot_box
docker rm -f $(docker ps -aq --filter "name=langbot-box-mcp-shared")
docker compose --profile all up -d --force-recreate

Windows PowerShell：

docker compose --profile all stop langbot langbot_box
docker ps -a --filter "name=langbot-box-mcp-shared" --format "{{.Names}}" | ForEach-Object { docker rm -f $_ }
docker compose --profile all up -d --force-recreate

等待 MCP 冷启动完成后，在 MCP 管理页面确认状态为 connected，并检查工具数量是否大于 0。

MCP 已安装但没有工具或无法连接

症状

MCP 已出现在列表中，但状态是 error 或长期 connecting。
工具数量为 0。
远程 MCP 日志中出现 401 Unauthorized、连接超时或握手失败。

常见原因

远程 MCP 需要 API Key 或 OAuth 授权，但未配置。
MCP 包首次通过 npx 或 uvx 冷启动，依赖下载时间较长。
当前 Docker 网络无法访问对应 MCP 服务或包仓库。
stdio MCP 沙箱资源不足。

处理方式

优先在 LangBot Space 中选择无需密钥或已正确配置密钥的 MCP。对于需要密钥的 MCP，请在安装配置中补齐环境变量、请求头或 URL 参数。查看运行时日志：

docker logs langbot --tail 200
docker logs langbot_box --tail 200

如果确认某个 MCP 无法在当前环境连接，请在 MCP 管理页面禁用或删除它，避免影响排查结果。

镜像标签或镜像源不一致

症状

docker compose ps 显示服务仍在使用旧镜像。
修改了镜像源或标签后，重启仍未生效。
langbot、langbot_plugin_runtime、langbot_box 使用了不同镜像标签。

处理方式

保持三个 LangBot 服务的镜像标签一致，然后重新拉取并重建：

docker pull rockchin/langbot:latest
docker compose --profile all up -d --force-recreate

如果你明确需要部署其他标签，请确保 docker-compose.yaml 中 langbot、langbot_plugin_runtime、langbot_box 三处镜像同时修改。

部署后验证

完成修复后建议做一次完整检查：

docker compose --profile all ps
docker inspect langbot langbot_plugin_runtime langbot_box --format '{{.Name}} {{.Config.Image}} {{.State.Status}}'

确认 WebUI 可访问：

curl -I http://127.0.0.1:5300/

在页面中继续确认：

可以正常登录。
Box / 沙箱能力可用。
MCP 列表中的目标 MCP 状态为 connected。
stdio MCP 的工具数量正常显示。

​Docker 部署

​启动前快速确认

​端口被占用

​症状

​处理方式

​Box Runtime 未启动或不可用

​症状

​常见原因

​处理方式

​Box 根目录挂载失败

​症状

​原因

​处理方式

​大量 stdio MCP 启动失败或长时间 connecting

​症状

​原因

​处理方式

​MCP 已安装但没有工具或无法连接

​症状

​常见原因

​处理方式

​镜像标签或镜像源不一致

​症状

​处理方式

​部署后验证

Docker 部署

启动前快速确认

端口被占用

症状

处理方式

Box Runtime 未启动或不可用

症状

常见原因

处理方式

Box 根目录挂载失败

症状

原因

处理方式

大量 stdio MCP 启动失败或长时间 connecting

症状

原因

处理方式

MCP 已安装但没有工具或无法连接

症状

常见原因

处理方式

镜像标签或镜像源不一致

症状

处理方式

部署后验证