LangBot 详细部署教程

项目概述

LangBot 是一个开源、生产级的 AI 即时通讯机器人平台。它能将大语言模型（LLM）连接到任何聊天平台，让你创建能够对话、执行任务并集成现有工作流的智能代理。

核心能力：

  • AI 对话与 Agent：多轮对话、工具调用、多模态支持、流式输出。内置 RAG（知识库），深度集成 Dify、Coze、n8n、Langflow 等
  • 通用 IM 平台支持：一套代码适配 Discord、Telegram、Slack、LINE、QQ、微信、企业微信、飞书、钉钉、KOOK 等
  • 生产就绪：访问控制、速率限制、敏感词过滤、全面监控和异常处理
  • 插件生态：数百个插件、事件驱动架构、组件扩展和 MCP 协议支持
  • Web 管理面板：通过直观的浏览器界面配置、管理和监控机器人，无需编辑 YAML
  • 多流水线架构：为不同场景配置不同机器人，具备全面的监控和异常处理

技术栈：Python + Fastify + Next.js + SQLite/PostgreSQL

部署前准备

系统要求

项目 要求
操作系统 Windows / macOS / Linux
Docker 20.10+
Docker Compose v2.0+
内存 最低 1GB，推荐 2GB+
磁盘空间 最低 2GB
网络 需能访问大模型 API（如 OpenAI、DeepSeek 等）

环境检查

1
2
3
docker --version
docker compose version
git --version

方案一：Docker Compose 部署（推荐）

这是最简单、最稳定的生产级部署方式 。

步骤 1：克隆仓库

1
2
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker

步骤 2：启动容器

完整模式（推荐，启用 Box Runtime 依赖的所有功能） ：

1
docker compose --profile all up -d

这会启动三个容器 ：

  • langbot — 主应用（WebUI + webhook）
  • langbot_plugin_runtime — 插件运行时
  • langbot_box — Box 沙箱运行时

基础模式（不启用 Box Runtime） ：

1
docker compose up -d

步骤 3：访问 WebUI

打开浏览器访问 http://127.0.0.1:5300 。

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

中国大陆用户优化

如果你的主机位于中国大陆，可以考虑将 docker-compose.yaml 文件中的镜像名称改为国内镜像源以加速下载 ：

1
image: docker.langbot.app/langbot-public/rockchin/langbot:latest

同时推荐设置 Docker 容器代理，以保证 LangBot 运行期间的网络访问通畅 。

方案二：一键启动（uvx）

如果你已安装 uv，可以使用一行命令快速启动：

1
uvx langbot

然后访问 http://localhost:5300 即可 。

此方式适合快速体验，生产环境建议使用 Docker 部署。

方案三：Kubernetes 部署

适合需要在 Kubernetes 集群上实现可扩展、生产级 AI 机器人托管的场景 。

前置要求

  • Kubernetes 集群的基本使用（kubectl、Namespace、Deployment、Service、PVC）
  • 容器间网络通信与持久化存储的配置方式

步骤 1：克隆仓库

1
2
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker

步骤 2：部署所有组件

1
kubectl apply -f kubernetes.yaml

步骤 3：查看状态

1
kubectl get all -n langbot

步骤 4：访问 WebUI

1
kubectl port-forward -n langbot svc/langbot 5300:5300

然后访问 http://localhost:5300 。

组件构成

清单会在 langbot 命名空间下创建以下组件 ：

组件 说明 端口
langbot 主应用（WebUI + webhook） 5300 / 2280-2290
langbot-plugin-runtime 插件运行时 5400
langbot-box Box 沙箱运行时（可选） 5410

Box 沙箱运行时说明

langbot-box 为 LangBot 提供代码沙箱能力，支撑沙箱工具（exec / read / write / edit / glob / grep）、技能的 activate 工具与新增/编辑、以及 stdio 模式的 MCP 服务器 。

它是可选组件：不部署时 LangBot 仍可运行，仪表盘与技能列表只读可见，但上述能力会被禁用，此时请在 langbot 上设置 BOX__ENABLED=false 。

重要约束：Box 运行时通过挂载到节点的 Docker socket 创建沙箱容器。Box 工作区根目录必须在以下三处是同一个绝对路径 ：

  1. 节点上的实际路径
  2. langbot-box 容器内的挂载路径
  3. 它创建的每个沙箱容器内的挂载路径

安全提示：挂载节点的 Docker socket 会让 Box 运行时获得对节点的实质 root 权限。请仅在你信任该工作负载的节点上部署 Box 。

端口说明

端口 用途 说明
5300 WebUI Web 管理面板入口
2280-2290 OneBot 适配器 供使用 OneBot 协议的消息平台适配器反向连接

首次配置

步骤 1：初始化

打开 WebUI 后，你可以选择：

使用 LangBot Space 初始化（推荐） ：

点击 「Initialize with Space」 ，这会将你的实例连接到 LangBot Space，获得 ：

  • 20 个开箱即用的云端模型（附赠免费额度）
  • 一键安装插件
  • 托管式 API Key 管理

手动配置模型：

如果你已有 API Key，可以手动配置大模型连接。

步骤 2：配置流水线

进入 流水线 页面，编辑默认的 ChatPipeline ：

  1. 选择模型（如 deepseek-v3、gpt-5-mini、claude-sonnet-4-5）
  2. 自定义系统提示词
  3. 可选：关联知识库或启用工具调用

步骤 3：接入平台

进入 机器人 → 点击 + → 选择平台（Discord、Telegram 等）→ 填入 Bot Token 。

步骤 4：测试

使用内置的 Debug Chat 在上线前测试流水线 。

支持的平台与模型

即时通讯平台

平台 状态 说明
Discord ✅ 官方支持
Telegram ✅ 官方支持
Slack ✅ 官方支持
LINE ✅ 官方支持
QQ ✅ 个人 & 官方 API（频道、私聊、群聊）
企业微信 ✅ 企业微信、外部客服、AI Bot
微信 ✅ 个人 & 公众号
飞书 ✅ 官方支持
钉钉 ✅ 官方支持
KOOK ✅ 官方支持
Matrix ✅ 支持 Signal、WhatsApp 等桥接平台

大模型支持

提供商 类型 状态
OpenAI LLM ✅
Anthropic LLM ✅
DeepSeek LLM ✅
Google Gemini LLM ✅
Ollama 本地 LLM ✅
LM Studio 本地 LLM ✅
Dify LLMOps ✅
MCP 协议 ✅
SiliconFlow 网关 ✅

更多集成请查看官方文档。

常见问题排查

问题 症状 解决方案
Box 沙箱启动失败 提示 “No sandbox backend (Docker/nsjail/E2B) is ready” 确认当前用户可访问 Docker：sudo usermod -aG docker $USER && newgrp docker && docker info，然后重启 LangBot
无法访问 WebUI 连接被拒绝 检查容器是否正常运行：docker ps，确认 5300 端口未被占用
消息平台连接失败 Bot 无响应 检查 Bot Token 是否正确，确认网络可访问对应平台
大模型调用失败 API 错误 检查 API Key 是否有效，确认账户余额充足
配置文件未生成 首次启动无提示 检查数据目录挂载权限，查看容器日志 docker logs langbot

数据持久化

LangBot 需要持久化以下数据 ：

容器内路径 内容 是否必需
/app/data/config.yaml 主应用配置 是
/app/data/langbot.db SQLite 数据库（默认后端） 是（如使用 SQLite）
/app/data/plugins/ 插件源码和资源 是
/app/data/ (向量库子目录) ChromaDB 或其他本地向量库文件 是（如使用本地向量库）

更新到最新版本

1
2
3
cd LangBot/docker
docker compose pull
docker compose up -d

数据库选择

后端 适用场景 Kubernetes 考虑
SQLite 开发、单副本 需要 ReadWriteOnce PVC；无法水平扩展
PostgreSQL 生产、多副本 外部服务或独立的 StatefulSet；支持 ReadWriteMany 应用 Pod

对于多副本部署（如 replicas: 2），SQLite 不安全，因为多个 Pod 会同时写入同一文件。应使用外部 PostgreSQL 实例并在 config.yaml 中设置连接字符串 。

Agent 友好特性

LangBot 设计上对 AI Agent 友好——你的编码代理（Claude Code、Codex、Copilot、Cursor 等）可以操作、扩展和部署 LangBot ：

  • MCP Server：LangBot 在 /mcp 暴露内置的 Model Context Protocol 端点，镜像 HTTP API，允许 Agent 以编程方式管理机器人、流水线、插件和模型
  • 仓库内 Skills：skills/ 目录是与 LangBot 协作的唯一真相来源
  • AGENTS.md：每个仓库都附带 AGENTS.md（符号链接到 CLAUDE.md），描述架构、约定和规则

总结

部署方案 适用场景 难度 推荐度
Docker Compose 大多数用户，生产环境 ⭐ ⭐⭐⭐⭐⭐
uvx 一键启动 快速体验 ⭐ ⭐⭐⭐
Kubernetes 企业级、需要扩展 ⭐⭐⭐⭐ ⭐⭐⭐⭐
云平台一键部署 无服务器管理需求 ⭐ ⭐⭐⭐⭐

对于大多数用户，Docker Compose 完整模式是最简单直接的选择：

1
2
3
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose --profile all up -d

然后访问 http://127.0.0.1:5300，使用 LangBot Space 初始化或手动配置模型，即可在 5 分钟内将 AI 机器人部署到 Discord、Telegram、微信等平台。