---
title: "Docker部署"
description: "使用 Docker 和 Docker Compose 部署 LangBot，几分钟内运行支持 Discord、Telegram、微信等多平台的开源 AI 聊天机器人。"
---

<Warning>
  您需要提前了解：

  - `Docker` 和 `Docker Compose` 的使用
  - Docker 容器间网络通信配置方式
</Warning>

<Info>
  - 推荐使用[阿里云，服务器价格低至 38 元一年，更可以享受8折优惠](https://www.aliyun.com/minisite/goods?userCode=ys4ad8gs)
</Info>

Git 克隆本项目：

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
```

启动容器（推荐启用 `all` profile，以默认启用沙箱、stdio MCP 托管、Skill 添加/编辑等依赖 Box Runtime 的功能）：

```bash
docker compose --profile all up
```

## 公网部署的 Runtime Token

开源版仅在 LangBot 与对应 Runtime **两端都未设置 Token** 时跳过 Token 校验。若部署环境可从公网访问，强烈建议为 Plugin Runtime 和 Box Runtime 设置独立的强 Token：

```bash
export LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN="$(openssl rand -hex 32)"
export LANGBOT_BOX_CONTROL_TOKEN="$(openssl rand -hex 32)"
docker compose --profile all up -d
```

官方 Compose 文件会把每个变量传给对应连接的两端。只设置一端、两端值不一致或 Token 强度不足都会导致连接被拒绝。请把 Token 保存在部署平台的 Secret 管理中，不要提交到仓库。

这会启动 `langbot`、`langbot_plugin_runtime` 和 `langbot_box`。如果只需要基础服务，不启用 Box Runtime，可以使用：

```bash
docker compose up
```

## SeekDB 支持

官方 Docker 镜像已经包含可选的 SeekDB 依赖，无需额外构建参数。容器会使用对应 Linux 架构的 `pylibseekdb` wheel，因此宿主机的 macOS 版本不会限制容器内的 embedded 模式；不使用 SeekDB 时保持默认 `vdb.use: chroma` 即可。

`langbot_box` 通过主机 Docker socket 创建沙箱容器，因此 Box 根目录的宿主机路径和容器内路径必须一致：

```yaml
services:
  langbot:
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__DEFAULT_WORKSPACE=default
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}

  langbot_box:
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
```

<Note>
  **Box 控制面的启动方式因部署方式而异。** 容器部署下，Box 控制面以独立的 `langbot_box` **容器**运行，`langbot` 通过 WebSocket（`ws://langbot_box:5410`）连接它；而手动启动 / `uvx` 部署则由 `langbot` 直接拉起一个 stdio 子进程作为 Box 控制面。`langbot_box` 借助挂载的宿主 `docker.sock` 在宿主 Docker 上创建沙箱兄弟容器，LangBot 镜像已内置 `docker` 客户端，无需额外安装。
</Note>

如果提示 `No sandbox backend (Docker/nsjail/E2B) is ready`，请先确认当前用户可访问 Docker：

```bash
sudo usermod -aG docker $USER
newgrp docker
docker info
```

若 `docker info` 正常输出，请重启 LangBot。

<Warning>
`langbot_box` 不直接读取 `LANGBOT_BOX_*` 或 `BOX__*` 环境变量；Box 配置由 `langbot` 读取 `BOX__LOCAL__*` 后通过 INIT RPC 传给 Box Runtime。若要改 Box 根目录，请使用绝对路径设置 `LANGBOT_BOX_ROOT`，例如 `LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up`。
</Warning>

<Info>
  - 如果你的主机位于中国大陆，可以考虑把 `docker-compose.yaml` 文件中的镜像名称改为`docker.langbot.app/langbot-public/rockchin/langbot:latest`以使用我们提供的镜像源。
  - 推荐[设置 Docker 容器代理](https://docker.github.net.cn/network/proxy/)，以便保证 LangBot 在运行期间的网络访问通畅。
  - 如果需要禁用或强制沙箱后端，请参考[沙箱配置](/zh/usage/sandbox/config)。
</Info>

首次启动会输出创建配置文件的提示，请继续按照文件配置。

容器会映射`5300`端口供 WebUI 使用，您可以访问`http://127.0.0.1:5300`查看 WebUI。\
还会映射`2280-2285`端口供使用 OneBot 协议的消息平台适配器反向连接。

完成 LangBot 部署后，请继续阅读：

- [配置机器人文档](/zh/usage/platforms/readme)。
- [配置模型文档](/zh/usage/models/readme)。
- [沙箱文档](/zh/usage/sandbox/readme)。
- [技能系统文档](/zh/usage/skills/readme)。