Dograh快速入门：从Docker Compose到第一个AI电话助手的完整教程-平芜编程栈

Dograh快速入门：从Docker Compose到第一个AI电话助手的完整教程

【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh

Dograh是一个开源、可自托管的语音AI平台，被誉为 Vapi 和 Retell 的自托管替代方案。通过 Docker Compose 一条命令即可在本地或服务器上部署完整的语音AI基础设施，再用可视化工作流编辑器在 5 分钟内创建你的第一个 AI 电话助手——支持 LLM/STT/TTS 或端到端 Speech-to-Speech 模型，自带 MCP 集成与电话线路（Twilio、Vonage、Telnyx 等）支持，数据完全掌握在自己手里。

本文将从零开始，带你走完「Docker Compose 部署 → 创建语音助手 → 浏览器实测 → 接入真实电话」的全流程。🚀

为什么选择 Dograh 部署语音AI？

对比维度	Dograh	商业SaaS方案
开源协议	BSD 2-Clause，100% 开源	闭源
自托管	✅ 一条 Docker 命令	❌ 仅 SaaS
模型选择	BYOK，任意 LLM/STT/TTS 提供商	受限于平台集成
数据主权	你的基础设施，你的规则	平台云端
供应商锁定	无	有

核心卖点：零 API Key 门槛。Dograh 自带自动生成的密钥和完整的 LLM/TTS/STT 技术栈，开箱即用；想换成自己的模型密钥（BYOK）随时可以切换。

部署前准备：系统与端口检查

开始之前，先确认环境满足以下最低要求（详见 prerequisites.mdx 文档目录下的说明）：

内存：8 GB（其中 4 GB 分配给 Docker）
磁盘：10 GB 可用空间
CPU：2 核（x86_64 或 ARM64 均可）
系统：macOS 10.15+ / Windows 10/11（WSL2）/ Linux
软件：Docker 20.10+（Docker Compose 已内置）

同时确认这些端口未被占用：3010（Web UI）、8000（API）、5432（PostgreSQL）、6379（Redis）、9000/9001（MinIO 对象存储）。

# Linux/macOS 检查端口占用 lsof -i :3010

💡 如果使用 Docker Desktop，记得在Settings → Resources中至少分配 4 GB 内存、2 个 CPU。

第一步：Docker Compose 一键部署 Dograh

打开终端，执行下面这条命令（它会自动下载docker-compose.yaml和启动脚本，生成必要的密钥与.env文件，然后拉起全部服务）：

curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml && curl -o start_docker.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.sh && chmod +x start_docker.sh && ./start_docker.sh

这条命令背后做了几件关键的事：

下载最新的 docker-compose.yaml 编排文件
自动创建OSS_JWT_SECRET、REDIS_PASSWORD等凭据到.env
启动 PostgreSQL、Redis、MinIO、API、UI 等全部服务
自动拉取最新镜像

⏱️ 首次启动需要 2-3 分钟下载镜像。不想收集匿名遥测数据的话，在执行前设置ENABLE_TELEMETRY=false即可。

Windows 用户使用 PowerShell 版本（脚本见scripts/start_docker.ps1）：

Invoke-WebRequest -OutFile docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml; Invoke-WebRequest -OutFile start_docker.ps1 https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/start_docker.ps1; .\start_docker.ps1

部署完成后，浏览器打开http://localhost:3010即可进入控制台。

第二步：创建你的第一个 AI 语音助手

进入控制台后，创建一个新 Agent，只需填写三项内容：

Call Type（呼叫方向）：选Inbound（用户打给 AI）或Outbound（AI 主动外呼）
Use Case（用例）：用 5-10 个词描述场景，例如「客服咨询」「保险线索筛选」
Activity Description（活动描述）：详细描述助手的任务，它会被送入 LLM 生成完整的工作流提示词——描述越具体，生成的对话流越贴合你的需求

点击Create Agent后，系统会直接进入可视化工作流编辑器。

第三步：看懂可视化工作流编辑器

Dograh 的核心是拖拽式工作流画布：LLM 会自动为你的用例生成一张包含Start Call（开始呼叫）→ Agent 节点 → End Call（结束呼叫）的流程图，节点之间用路径（pathway）连接。

点开任意节点就能编辑它的 Prompt 提示词，还有几个高频开关值得了解：

Allow Interruption：是否允许用户打断 AI 说话
Add Global Prompt：附加全局指令（语气、异议处理等，作用于整个流程）
Detect Voicemail：检测到语音信箱自动挂断
Delayed Start：开场前加入延迟

你不需要现在就理解所有节点类型——生成的 Agent 开箱即能跑通，先听它说话，再回头微调提示词。

第四步：在浏览器里实测你的 AI 电话助手

这是最快验证效果的方式：Web Call（网页通话）。无需电话号码、无需配置任何电话线路，直接在浏览器中通过麦克风完成完整链路：语音识别（STT）→ LLM 推理 → 语音合成（TTS），体验与真实电话一致。

通话过程中你可以实时观察：

✅实时转写文本：对话逐句上屏
✅节点跳转：Agent 在工作流图中移动的过程
✅工具调用：Agent 调用外部工具的全过程

不满意？直接打开对应节点修改提示词，保存后重新发起 Web Call 即可听到变化——无需重新部署、无需重启。想快速迭代文本逻辑，还可以用Test Chat以文字模式对话，甚至编辑/重放某一轮用户发言让 Agent 重新生成后续回复。

进阶：接入真实电话线路 📞

浏览器测试满意后，下一步就是接真实号码。以接入最快的 Twilio 为例：

在 Twilio 注册账号并购买一个号码（试用账户自带免费测试额度）
复制Account SID和Auth Token
在 Dograh 中打开Telephony → Add Configuration，选择 Twilio 提供商，粘贴凭据
务必勾选「Set as default for outbound calls」（否则 API 触发呼叫会报错）
添加你购买的电话号码，并指定呼入时路由到的工作流

之后就可以从你的后端通过 API 触发外呼：电话响起、AI 接听、实时对话——呼入方向同理，经 Twilio Webhook 反向路由到 Dograh 工作流。此外平台还支持 Vonage、Telnyx、Plivo、Vobiz、Cloudonix 及 Asterisk ARI 等提供商。

可选优化：换用自己的模型或嵌入网站

BYOK 模型配置：在Models页面可以切换「Dograh 托管 / BYOK / Speech-to-Speech」三种模式，填入自己的 API Key 后选择模型、音色、语速并保存：

嵌入网站：不想走电话线路？在 Agent 设置页找到Add to Website，开启嵌入、选择 Floating Widget 等模式，复制一段脚本标签贴到任意网页，访客即可点击按钮直接与语音 AI 通话：

常见问题速查 🛠️

问题	解决方法
端口被占用	`lsof -i :3010`找到进程后`kill -9 <PID>`；或`docker stop $(docker ps -q)`停止所有容器
通话接通但没声音 /`iceConnectionState: failed`	网络 NAT 较严格，需启用 TURN 中继：用`scripts/setup_local.sh`重新初始化（选启用 coturn），再执行`docker compose --profile local-turn up`
停止/清理所有数据	`docker compose down`（加`-v`同时删除数据卷）