Bolna快速部署教程：用Docker Compose十分钟搭起语音AI服务（4容器架构详解）

Bolna 是一个端到端的开源语音 AI Agent 框架，通过组合 ASR（语音识别）、LLM（大模型）和 TTS（语音合成）Provider，用一份 JSON 配置就能搭建可打电话的对话式语音助手。本教程带你用 Docker Compose 在十分钟内完成 Bolna 本地部署，并详解其背后的 4 容器架构（Telephony 电话网关 + Bolna 服务 + ngrok 隧道 + Redis 存储），新手也能一次跑通。

🎯 部署前先看：Bolna 的四容器架构是什么

在动手之前，先搞懂架构，部署时遇到问题才不会慌。Bolna 的本地部署方案（位于 local_setup/ 目录）由 4 个 Docker 容器 组成，各自分工明确：

容器	端口	职责
Telephony 服务（twilio-app / plivo-app）	8001 / 8002	对接 Twilio 或 Plivo 电话网关，负责发起和接听真实电话
bolna-app	5001	核心编排服务：创建 Agent、管理对话流水线（ASR→LLM→TTS）
ngrok	4040	内网穿透隧道，让云端的电话网关能回调到你本机
redis	6379	持久化存储 Agent 配置和 Prompt 数据

整体数据流向可以这样理解：

graph LR;
    A[电话 Twilio/Plivo] --> B[ngrok 隧道];
    B --> C[Telephony 网关容器];
    C --> D[bolna-app 语音AI核心];
    D --> E[redis 持久化存储];
    D --> F[ASR + LLM + TTS 云服务];

💡 核心逻辑：电话是"云上进来"的，你的服务在"本地"，所以需要 ngrok 打通一条双向通道；Agent 的定义则统一存在 Redis 里，bolna-app 重启也不丢。

📋 准备工作：3 分钟搞定环境清单

开始之前，确认你手头有以下 4 样东西：

1. Docker + Docker Compose V2：执行 docker compose version 能正常输出版本号即可
2. 电话网关账号（二选一）：
   • Twilio 账号 → 需要 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN、TWILIO_PHONE_NUMBER
   • Plivo 账号 → 需要 PLIVO_AUTH_ID、PLIVO_AUTH_TOKEN、PLIVO_PHONE_NUMBER
3. ngrok 账号：免费即可，用于获取 authtoken
4. AI 服务商 API Key：按需填写，常见的有：

用途	环境变量
语音识别 ASR	DEEPGRAM_AUTH_TOKEN
大模型 LLM	LITELLM_MODEL_API_KEY（或 OPENAI_API_KEY 等）
语音合成 TTS	ELEVENLABS_API_KEY / CARTESIA_API_KEY 等

获取仓库代码：

git clone https://gitcode.com/gh_mirrors/bol/bolna

🚀 最快部署方式：一条命令一键启动

Bolna 在 local_setup/ 目录下内置了官方启动脚本 start.sh，它会自动检测 Docker 依赖、开启 BuildKit 加速构建、构建全部镜像并以后台模式启动服务：

cd local_setup
chmod +x start.sh
./start.sh

脚本成功执行后，你会看到 Services are up and running! 提示。此时可以用下面两条命令验证状态：

docker compose ps        # 查看 4 个容器是否都在运行
docker compose logs -f   # 实时查看各服务日志

⚠️ 别忘了：.env 文件必须放在 local_setup/ 目录下，参考官方模板填写（README 中说明从 .env.sample 复制）。docker-compose.yml 里的每个服务都声明了 env_file: .env，Key 缺失会导致对应 Provider 调用失败。

🛠️ 手动部署步骤：逐步理解每个环节

如果你想手动掌控部署过程（或排查构建问题），按以下 4 步操作：

第 1 步：开启 BuildKit 加速镜像构建

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

第 2 步：构建镜像

cd local_setup
docker compose build

三个自定义镜像分别由以下 Dockerfile 构建，构建上下文都取自 local_setup/ 目录：

• bolna_server.Dockerfile → 核心服务（基于 Python 3.10 + FastAPI，内置 ffmpeg 处理音频）
• twilio_server.Dockerfile → Twilio 电话网关
• plivo_server.Dockerfile → Plivo 电话网关

第 3 步：配置 ngrok 隧道

编辑 ngrok-config.yml，把 authtoken 替换成你的 ngrok 令牌。该文件已预配置好 3 条隧道：twilio-app:8001、plivo-app:8002、bolna-app:5001，无需改动地址部分。

第 4 步：启动服务

docker compose up -d

💡 只想跑 Twilio 方案？可以只启动指定服务：docker compose up -d bolna-app twilio-app；Plivo 方案则换成 plivo-app。

📡 部署后怎么用：创建 Agent 并拨打电话

容器跑起来只是第一步，Bolna 的设计哲学是**"用 JSON 定义 Agent"**。服务启动后，你可以：

1. 通过 REST API 创建 Agent：调用 POST /agent 接口，在 agent_config 里指定 transcriber（ASR）、llm_agent（LLM）、synthesizer（TTS）三件套，完整的请求体示例见 API.md
2. 配置系统 Prompt：在 agent_prompts 中写入 Agent 的人设和话术
3. 发起电话：通过 Telephony 网关容器触发外呼，ngrok 会把云端 Twilio/Plivo 的回调路由到你的本地服务

API.md 中给出的最小 Agent 示例长这样（节选）：

{
  "task_type": "conversation",
  "transcriber": { "provider": "deepgram", "stream": true },
  "llm_agent": { "provider": "openai", "model": "gpt-4o-mini" },
  "synthesizer": { "provider": "elevenlabs", "stream": true }
}

此外，仓库还提供了一个免电话的本地 WebSocket 客户端 quickstart_client.py，它直连 ws://localhost:5001 的 bolna-app，用麦克风送音频、用扬声器播放回复，非常适合在部署后先做链路自测再打真实电话。

❓ 常见问题排查清单

现象	可能原因	解决方向
start.sh 报 Docker 未安装	缺少 Docker 或 Compose V2	先安装 Docker Desktop / Docker Engine
容器反复重启	.env 缺失或 Key 填错	docker compose logs 查看具体报错，核对环境变量
电话打不进来	ngrok authtoken 未配置	检查 ngrok-config.yml 并重启 ngrok 容器
电话打通但无声音	ASR/TTS 的 Key 未配置或余额不足	核对 DEEPGRAM_AUTH_TOKEN 等变量

📚 延伸阅读

• 本地部署说明：local_setup/README.md
• 电话网关服务源码：twilio_api_server.py、plivo_api_server.py
• REST API 完整文档：API.md
• 纯 Python 编程式调用示例（无需电话）：examples/simple_assistant.py
• 环境噪声音景素材（用于拟真度测试）：local_setup/presets/ambient_noise/

✅ 小结

用 Docker Compose 部署 Bolna 语音 AI 服务其实只有三个动作：填 .env、配 ngrok token、跑 ./start.sh。理解 4 容器的分工（电话网关 / 核心编排 / 内网穿透 / 数据持久化）后，任何一环出问题你都能快速定位。部署完成后，只需一份 JSON 配置，就能拥有一个会说、会听、会打真实电话的 AI 语音助手。