Dograh 仓库总览与本地开发实践项目结构、技术栈与双 .env 环境体系【免费下载链接】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/dograhDograh 是一个开源语音 AI 平台自托管的 Vapi / Retell 替代品支持电话Telephony与 WebRTC 两种语音通道。本篇基于仓库根目录的项目总览文档 AGENTS.md 展开结合源码与配置文件逐一印证其项目结构、技术选型和本地开发约定读完后你将能准确定位 Dograh 各模块的职责边界并掌握后端脚本与 pytest 分别应加载哪套环境变量的正确姿势。项目定位一个为对话式语音 Agent 而生的平台AGENTS.md 对项目的定义非常简洁Dograh is a voice AI platform for building and deploying conversational AI agents with telephony and WebRTC support.即构建和部署对话式 AI Agent且同时支持传统电话网络Telephony如 SIP/ARI 回拨、Twilio 等运营商通道与现代 WebRTC 实时音视频两条链路。这一点在仓库中有多处印证从docker-compose.yaml看栈中可选地包含coturn服务profiles: [remote, local-turn]并通过TURN_HOST/TURN_SECRET走 TURN REST API 签发限时凭证用于 WebRTC 的 NAT 穿透后端api/services/下同时存在pipecat/语音流水线、telephony/电话集成含 ARI manager和campaign/外呼活动编排等大目录与 README 宣称的可视化工作流构建器 电话支持 MCP 原生相吻合FastAPI 应用入口 api/app.py 的lifespan中会预热 ARQ Redis 连接池、预注册各组织的 Langfuse 追踪凭证并启动跨 worker 的配置同步管理器WorkerSyncManager体现这是一个需要多进程协作的长连接语音平台而非普通 REST 服务。仓库结构六个一级目录各管一摊AGENTS.md 给出的项目结构如下dograh/ ├── api/ # Backend - FastAPI application ├── ui/ # Frontend - Next.js application ├── scripts/ # Helper scripts for local development ├── docs/ # Mintlify documentation ├── pipecat/ # Pipecat framework (git submodule) ├── docker-compose.yaml # Production/OSS deployment ├── docker-compose-local.yaml # Local development services对照仓库实际内容各目录职责可以进一步细化路径职责源码证据api/FastAPI 后端REST 路由routes/、数据库客户端与模型db/、Alembic 迁移alembic/、ARQ 后台任务tasks/、各类业务服务services/api/routes/、api/db/models.py、api/tasks/arq.pyui/Next.js 前端工作流构建器基于xyflow/react、Agent 编辑器、Dashboardui/package.json 中的xyflow/react、zustand、shadcn-ui依赖scripts/本地开发与部署辅助脚本scripts/start_services_dev.sh、scripts/dump_docs_openapi.pydocs/Mintlify 文档站MDX含开发者文档与贡献指南docs/contribution/setup.mdxpipecat/语音流水线框架STT → LLM → TTS以 git submodule 形式引入该目录在当前检出中为空占位需git submodule update --init --recursive拉取docker-compose.yaml生产 / OSS 部署栈docker-compose.yamldocker-compose-local.yaml本地开发服务栈docker-compose-local.yaml需要注意的一个易踩坑点docker-compose.yaml文件头注释明确写着生产栈应通过 scripts/start_docker.sh本地或sudo ./setup_remote.sh然后 scripts/remote_up.sh远程来驱动而不是裸跑docker compose up——因为栈需要预先生成的.env含OSS_JWT_SECRET等必填项远程/TURN 配置档还需要dograh-init服务渲染 nginx 与 coturn 配置。裸跑会失败或起在半坏状态。技术栈四个关键选型及其仓库证据AGENTS.md 列出的技术栈为后端Python FastAPI前端Next.js 15 React 19、TypeScript、Tailwind CSS数据库PostgreSQL SQLAlchemyasync缓存 / 队列Redis ARQ后台任务存储MinIOS3 兼容存放音频文件逐项对照依赖声明全部可验证后端 Python FastAPI。api/pyproject.toml 锁定requires-python 3.13,3.14包名为dograh-api。api/requirements.txt 中可以看到fastapi0.135.3、uvicorn0.35.0以及围绕语音与异步 IO 的关键依赖asyncpgPostgres 异步驱动、sqlalchemy[asyncio]、arq0.26.3Redis 队列 worker、minio7.2.16、aioboto3S3 后端、pgvector向量检索、langfuseLLM 追踪与sentry-sdk[fastapi]。FastAPI 实例在 api/app.py 创建统一前缀/api/v1OpenAPI 文档暴露在/api/v1/openapi.json。前端 Next.js 15 React 19。ui/package.json 中next: ^15.3.3、react: ^19.1.0样式走tailwindcss ^4tailwindcss/postcssUI 组件来自 shadcn-ui 体系Radix primitives class-variance-authority工作流画布使用xyflow/react ^12.10.2状态管理用zustand。类型脚本为 TypeScript 5。PostgreSQL 异步 SQLAlchemy。api/requirements.txt 中sqlalchemy[asyncio]2.0.43asyncpg0.30.0配合alembic1.16.5做迁移管理api/alembic/versions/下有上百个版本文件是理解数据模型演进的最好入口。生产 compose 中 Postgres 镜像为pgvector/pgvector:pg17即数据库本身就带向量扩展。Redis ARQ。缓存与任务队列共用一个 Redis 实例api/tasks/arq.py定义了WorkerSettings开发模式下由独立进程python -m arq api.tasks.arq.WorkerSettings消费队列见 scripts/start_services_dev.sh。MinIO 对象存储。本地与生产栈都内置quay.io/minio/minio桶名固定为voice-audio通过ENABLE_AWS_S3true可切换到 AWS S3 或其他 S3 兼容服务端S3_ENDPOINT_URL、S3_SIGNATURE_VERSION、S3_ADDRESSING_STYLE等变量在 docker-compose.yaml 中有完整透传说明且因对象存储走 presigned URL桶可以保持私有。本地开发四个后端服务 一个健康检查AGENTS.md 将贡献者环境搭建指引指向 docs/contribution/setup.mdx该文档描述的标准路径是Fork 并克隆仓库用 VS Code 的 Dev Containers 扩展Reopen in Container首次构建会启动 Postgres、Redis、MinIO创建 Python venv 并生成.env文件容器内运行bash scripts/start_services_dev.sh启动后端再开一个终端cd ui npm run dev -- --hostname 0.0.0.0启动前端访问http://localhost:3000。结合 scripts/start_services_dev.sh 的源码可以看清启动后端到底意味着同时拉起 4 个进程SERVICE_NAMES( ari_manager # 电话 ARI 桥接FreeSWITCH 媒体控制 campaign_orchestrator # 外呼活动调度循环 uvicorn # FastAPI 主进程--reload --reload-dir api arq # ARQ 后台任务 worker )脚本行为上的几个值得注意的细节启动前先加载api/.envset -a . $ENV_FILE set a并激活venv/虚拟环境日志按时间戳写入logs/timestamp/并维护logs/latest符号链接因此日常看日志用tail -f logs/latest/*.logdocs/contribution/setup.mdx 的日常操作表也这么写内置健康检查轮询/api/v1/health最多HEALTH_MAX_ATTEMPTS默认 30次、间隔 2 秒成功退出即代表后端已就绪重复运行会先停掉旧进程因此重启后端 重跑一次该脚本。与 docs/contribution/setup.mdx 的日常操作表呼应api/下的代码编辑由 uvicorn 的--reload-dir api自动热载而ari_manager、campaign_orchestrator和arq三个进程不会自动重启改动了这些服务的代码就必须重跑启动脚本容器本身只有在.devcontainer/、api/requirements*.txt或pipecat/变更时才需要重建。调试方面仓库在.vscode/launch.json中为每个后端服务提供了调试配置Uvicorn reload、Arq worker、Campaign orchestrator、ARI manager以及 pytest 配置全部加载api/.env测试配置加载api/.env.test且justMyCode: false因此可以步进进 FastAPI 与以 editable 模式安装的pipecat/子模块源码。环境配置api/.env与api/.env.test的分工AGENTS.md 的Environment Configuration一节定义了三个环境文件及其使用场景这是整个文档中最实操的部分文件用途api/.env后端环境变量。运行仓库自带的后端脚本、且要访问开发库时必须 source 它例如python -m scripts.dump_docs_openapiapi/.env.test仅测试用环境变量。跑 pytest 时 source 它保证测试打向测试库绝不触碰api/.env中的开发/生产凭证ui/.env前端环境变量文档给出的典型调用方式# 测试 source venv/bin/activate set -a source api/.env.test set a python -m pytest api/tests/... # 后端脚本 source venv/bin/activate set -a source api/.env set a python -m scripts.dump_docs_openapi这套约定的合理性可以从两侧印证测试侧api/pytest.ini 配置了asyncio_mode auto、testpaths tests与--import-modeimportlib测试按目录组织api/tests/下有 200 个test_*.py并按telephony/、integrations/、dto_fixtures/等子目录归类。测试与开发库隔离正是通过测试只认.env.test这一纪律实现的docs/contribution/setup.mdx的调试一节也明确 pytest 调试配置againstapi/.env.test。脚本侧scripts/dump_docs_openapi.py 用于从运行中的应用导出 OpenAPI 规格到docs/api-reference/openapi.json它需要真实的api/.env含数据库与对象存储配置才能工作——这正是 AGENTS.md 举例说明 sourceapi/.env的原因。这里set -a/set a的用法值得展开set -a使 source 期间读取的每个变量自动export.env文件里的键值对才能被 Python 子进程以环境变量的形式读到set a则在加载完成后关闭该行为避免污染后续 shell 状态。部署栈速览docker-compose.yaml 如何印证技术栈生产栈 docker-compose.yaml 是理解各组件如何咬合的最佳实物证据服务清单postgrespgvector/pgvector:pg17、redisredis:7带requirepass、minio端口显式绑定127.0.0.1:9000/9001、apidograhai/dograh-api:latest、uidograhai/dograh-ui:latest监听 3010可选 profileremote启用nginx443 反代与coturnWebRTC TURNlocal-turn本地也起 coturntunnel启用cloudflared在没有公网 IP 的机器上为入站 webhook / WSS 提供隧道关键环境变量OSS_JWT_SECRET为必填${OSS_JWT_SECRET:?...}语法会在未设置时直接让 compose 失败PUBLIC_BASE_URL/PUBLIC_HOST会被 API 用来推导BACKEND_API_ENDPOINT、MINIO_PUBLIC_ENDPOINT与TURN_HOST推导逻辑见api/constants.py的注释说明FASTAPI_WORKERS控制 uvicorn 进程数dograh-init据此渲染 nginx upstream由 nginx 以 least_conn 做负载均衡依赖与健康检查api依赖 postgres / redis / minio 均service_healthy后才启动自身以/api/v1/health探活30 秒一次start_period: 60sui再依赖api健康形成依赖 → 就绪 → 发布的链条。小结AGENTS.md 作为面向 Agent 与贡献者的仓库总览信息密度很高且每一条都能在当前仓库中得到验证结构api/FastAPI 后端、ui/Next.js 15 前端、pipecat/submodule 语音流水线、scripts/、docs/加上两套 docker-compose 文件职责清晰技术栈Python 3.13 FastAPI 异步 SQLAlchemy/asyncpgRedis ARQ 处理后台任务MinIO 存音频前端 Next.js 15 React 19 Tailwind本地开发scripts/start_services_dev.sh一键拉起 4 个后端进程并做健康检查前端独立npm run dev环境纪律api/.env给脚本与开发环境用api/.env.test专供 pytestui/.env服务前端——三者不可混用这是仓库测试与开发库隔离的核心机制。对于要参与贡献的开发者下一步建议按 docs/contribution/setup.mdx 完成环境搭建然后从 api/alembic/versions/ 的迁移历史和 api/services/ 的服务分层入手即可快速建立对整个后端的心智模型。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dograh 仓库总览与本地开发实践：项目结构、技术栈与双 .env 环境体系
Dograh 仓库总览与本地开发实践项目结构、技术栈与双 .env 环境体系【免费下载链接】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/dograhDograh 是一个开源语音 AI 平台自托管的 Vapi / Retell 替代品支持电话Telephony与 WebRTC 两种语音通道。本篇基于仓库根目录的项目总览文档 AGENTS.md 展开结合源码与配置文件逐一印证其项目结构、技术选型和本地开发约定读完后你将能准确定位 Dograh 各模块的职责边界并掌握后端脚本与 pytest 分别应加载哪套环境变量的正确姿势。项目定位一个为对话式语音 Agent 而生的平台AGENTS.md 对项目的定义非常简洁Dograh is a voice AI platform for building and deploying conversational AI agents with telephony and WebRTC support.即构建和部署对话式 AI Agent且同时支持传统电话网络Telephony如 SIP/ARI 回拨、Twilio 等运营商通道与现代 WebRTC 实时音视频两条链路。这一点在仓库中有多处印证从docker-compose.yaml看栈中可选地包含coturn服务profiles: [remote, local-turn]并通过TURN_HOST/TURN_SECRET走 TURN REST API 签发限时凭证用于 WebRTC 的 NAT 穿透后端api/services/下同时存在pipecat/语音流水线、telephony/电话集成含 ARI manager和campaign/外呼活动编排等大目录与 README 宣称的可视化工作流构建器 电话支持 MCP 原生相吻合FastAPI 应用入口 api/app.py 的lifespan中会预热 ARQ Redis 连接池、预注册各组织的 Langfuse 追踪凭证并启动跨 worker 的配置同步管理器WorkerSyncManager体现这是一个需要多进程协作的长连接语音平台而非普通 REST 服务。仓库结构六个一级目录各管一摊AGENTS.md 给出的项目结构如下dograh/ ├── api/ # Backend - FastAPI application ├── ui/ # Frontend - Next.js application ├── scripts/ # Helper scripts for local development ├── docs/ # Mintlify documentation ├── pipecat/ # Pipecat framework (git submodule) ├── docker-compose.yaml # Production/OSS deployment ├── docker-compose-local.yaml # Local development services对照仓库实际内容各目录职责可以进一步细化路径职责源码证据api/FastAPI 后端REST 路由routes/、数据库客户端与模型db/、Alembic 迁移alembic/、ARQ 后台任务tasks/、各类业务服务services/api/routes/、api/db/models.py、api/tasks/arq.pyui/Next.js 前端工作流构建器基于xyflow/react、Agent 编辑器、Dashboardui/package.json 中的xyflow/react、zustand、shadcn-ui依赖scripts/本地开发与部署辅助脚本scripts/start_services_dev.sh、scripts/dump_docs_openapi.pydocs/Mintlify 文档站MDX含开发者文档与贡献指南docs/contribution/setup.mdxpipecat/语音流水线框架STT → LLM → TTS以 git submodule 形式引入该目录在当前检出中为空占位需git submodule update --init --recursive拉取docker-compose.yaml生产 / OSS 部署栈docker-compose.yamldocker-compose-local.yaml本地开发服务栈docker-compose-local.yaml需要注意的一个易踩坑点docker-compose.yaml文件头注释明确写着生产栈应通过 scripts/start_docker.sh本地或sudo ./setup_remote.sh然后 scripts/remote_up.sh远程来驱动而不是裸跑docker compose up——因为栈需要预先生成的.env含OSS_JWT_SECRET等必填项远程/TURN 配置档还需要dograh-init服务渲染 nginx 与 coturn 配置。裸跑会失败或起在半坏状态。技术栈四个关键选型及其仓库证据AGENTS.md 列出的技术栈为后端Python FastAPI前端Next.js 15 React 19、TypeScript、Tailwind CSS数据库PostgreSQL SQLAlchemyasync缓存 / 队列Redis ARQ后台任务存储MinIOS3 兼容存放音频文件逐项对照依赖声明全部可验证后端 Python FastAPI。api/pyproject.toml 锁定requires-python 3.13,3.14包名为dograh-api。api/requirements.txt 中可以看到fastapi0.135.3、uvicorn0.35.0以及围绕语音与异步 IO 的关键依赖asyncpgPostgres 异步驱动、sqlalchemy[asyncio]、arq0.26.3Redis 队列 worker、minio7.2.16、aioboto3S3 后端、pgvector向量检索、langfuseLLM 追踪与sentry-sdk[fastapi]。FastAPI 实例在 api/app.py 创建统一前缀/api/v1OpenAPI 文档暴露在/api/v1/openapi.json。前端 Next.js 15 React 19。ui/package.json 中next: ^15.3.3、react: ^19.1.0样式走tailwindcss ^4tailwindcss/postcssUI 组件来自 shadcn-ui 体系Radix primitives class-variance-authority工作流画布使用xyflow/react ^12.10.2状态管理用zustand。类型脚本为 TypeScript 5。PostgreSQL 异步 SQLAlchemy。api/requirements.txt 中sqlalchemy[asyncio]2.0.43asyncpg0.30.0配合alembic1.16.5做迁移管理api/alembic/versions/下有上百个版本文件是理解数据模型演进的最好入口。生产 compose 中 Postgres 镜像为pgvector/pgvector:pg17即数据库本身就带向量扩展。Redis ARQ。缓存与任务队列共用一个 Redis 实例api/tasks/arq.py定义了WorkerSettings开发模式下由独立进程python -m arq api.tasks.arq.WorkerSettings消费队列见 scripts/start_services_dev.sh。MinIO 对象存储。本地与生产栈都内置quay.io/minio/minio桶名固定为voice-audio通过ENABLE_AWS_S3true可切换到 AWS S3 或其他 S3 兼容服务端S3_ENDPOINT_URL、S3_SIGNATURE_VERSION、S3_ADDRESSING_STYLE等变量在 docker-compose.yaml 中有完整透传说明且因对象存储走 presigned URL桶可以保持私有。本地开发四个后端服务 一个健康检查AGENTS.md 将贡献者环境搭建指引指向 docs/contribution/setup.mdx该文档描述的标准路径是Fork 并克隆仓库用 VS Code 的 Dev Containers 扩展Reopen in Container首次构建会启动 Postgres、Redis、MinIO创建 Python venv 并生成.env文件容器内运行bash scripts/start_services_dev.sh启动后端再开一个终端cd ui npm run dev -- --hostname 0.0.0.0启动前端访问http://localhost:3000。结合 scripts/start_services_dev.sh 的源码可以看清启动后端到底意味着同时拉起 4 个进程SERVICE_NAMES( ari_manager # 电话 ARI 桥接FreeSWITCH 媒体控制 campaign_orchestrator # 外呼活动调度循环 uvicorn # FastAPI 主进程--reload --reload-dir api arq # ARQ 后台任务 worker )脚本行为上的几个值得注意的细节启动前先加载api/.envset -a . $ENV_FILE set a并激活venv/虚拟环境日志按时间戳写入logs/timestamp/并维护logs/latest符号链接因此日常看日志用tail -f logs/latest/*.logdocs/contribution/setup.mdx 的日常操作表也这么写内置健康检查轮询/api/v1/health最多HEALTH_MAX_ATTEMPTS默认 30次、间隔 2 秒成功退出即代表后端已就绪重复运行会先停掉旧进程因此重启后端 重跑一次该脚本。与 docs/contribution/setup.mdx 的日常操作表呼应api/下的代码编辑由 uvicorn 的--reload-dir api自动热载而ari_manager、campaign_orchestrator和arq三个进程不会自动重启改动了这些服务的代码就必须重跑启动脚本容器本身只有在.devcontainer/、api/requirements*.txt或pipecat/变更时才需要重建。调试方面仓库在.vscode/launch.json中为每个后端服务提供了调试配置Uvicorn reload、Arq worker、Campaign orchestrator、ARI manager以及 pytest 配置全部加载api/.env测试配置加载api/.env.test且justMyCode: false因此可以步进进 FastAPI 与以 editable 模式安装的pipecat/子模块源码。环境配置api/.env与api/.env.test的分工AGENTS.md 的Environment Configuration一节定义了三个环境文件及其使用场景这是整个文档中最实操的部分文件用途api/.env后端环境变量。运行仓库自带的后端脚本、且要访问开发库时必须 source 它例如python -m scripts.dump_docs_openapiapi/.env.test仅测试用环境变量。跑 pytest 时 source 它保证测试打向测试库绝不触碰api/.env中的开发/生产凭证ui/.env前端环境变量文档给出的典型调用方式# 测试 source venv/bin/activate set -a source api/.env.test set a python -m pytest api/tests/... # 后端脚本 source venv/bin/activate set -a source api/.env set a python -m scripts.dump_docs_openapi这套约定的合理性可以从两侧印证测试侧api/pytest.ini 配置了asyncio_mode auto、testpaths tests与--import-modeimportlib测试按目录组织api/tests/下有 200 个test_*.py并按telephony/、integrations/、dto_fixtures/等子目录归类。测试与开发库隔离正是通过测试只认.env.test这一纪律实现的docs/contribution/setup.mdx的调试一节也明确 pytest 调试配置againstapi/.env.test。脚本侧scripts/dump_docs_openapi.py 用于从运行中的应用导出 OpenAPI 规格到docs/api-reference/openapi.json它需要真实的api/.env含数据库与对象存储配置才能工作——这正是 AGENTS.md 举例说明 sourceapi/.env的原因。这里set -a/set a的用法值得展开set -a使 source 期间读取的每个变量自动export.env文件里的键值对才能被 Python 子进程以环境变量的形式读到set a则在加载完成后关闭该行为避免污染后续 shell 状态。部署栈速览docker-compose.yaml 如何印证技术栈生产栈 docker-compose.yaml 是理解各组件如何咬合的最佳实物证据服务清单postgrespgvector/pgvector:pg17、redisredis:7带requirepass、minio端口显式绑定127.0.0.1:9000/9001、apidograhai/dograh-api:latest、uidograhai/dograh-ui:latest监听 3010可选 profileremote启用nginx443 反代与coturnWebRTC TURNlocal-turn本地也起 coturntunnel启用cloudflared在没有公网 IP 的机器上为入站 webhook / WSS 提供隧道关键环境变量OSS_JWT_SECRET为必填${OSS_JWT_SECRET:?...}语法会在未设置时直接让 compose 失败PUBLIC_BASE_URL/PUBLIC_HOST会被 API 用来推导BACKEND_API_ENDPOINT、MINIO_PUBLIC_ENDPOINT与TURN_HOST推导逻辑见api/constants.py的注释说明FASTAPI_WORKERS控制 uvicorn 进程数dograh-init据此渲染 nginx upstream由 nginx 以 least_conn 做负载均衡依赖与健康检查api依赖 postgres / redis / minio 均service_healthy后才启动自身以/api/v1/health探活30 秒一次start_period: 60sui再依赖api健康形成依赖 → 就绪 → 发布的链条。小结AGENTS.md 作为面向 Agent 与贡献者的仓库总览信息密度很高且每一条都能在当前仓库中得到验证结构api/FastAPI 后端、ui/Next.js 15 前端、pipecat/submodule 语音流水线、scripts/、docs/加上两套 docker-compose 文件职责清晰技术栈Python 3.13 FastAPI 异步 SQLAlchemy/asyncpgRedis ARQ 处理后台任务MinIO 存音频前端 Next.js 15 React 19 Tailwind本地开发scripts/start_services_dev.sh一键拉起 4 个后端进程并做健康检查前端独立npm run dev环境纪律api/.env给脚本与开发环境用api/.env.test专供 pytestui/.env服务前端——三者不可混用这是仓库测试与开发库隔离的核心机制。对于要参与贡献的开发者下一步建议按 docs/contribution/setup.mdx 完成环境搭建然后从 api/alembic/versions/ 的迁移历史和 api/services/ 的服务分层入手即可快速建立对整个后端的心智模型。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考