Dograh 开源语音 AI 平台本地开发环境搭建以 Devcontainer 为正式贡献者工作流的完整指南【免费下载链接】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本文围绕 scripts/setup_local.devcontainer.md 展开讲清 Dograh一个可自托管的开源语音 AI 平台定位为 Vapi/Retell 的自部署替代方案中两类“本地运行”脚本的分工setup_local.sh/setup_local.ps1服务于 Docker 部署而仓库内建的.devcontainer/才是日常代码贡献的官方开发环境。读完本文你将掌握 devcontainer 的镜像构建原理、venv 预置与同步机制、Postgres/Redis/MinIO 三个基础服务的自动编排方式以及容器内启动后端与 UI 的完整日常开发流程。先分清边界setup_local.sh 是部署脚本不是开发环境scripts/setup_local.devcontainer.md 开篇就明确了一个容易被误用的事实setup_local.sh和setup_local.ps1负责为本地部署准备 OSSOpen SourceDocker 栈。它们不是本仓库推荐的贡献者工作流。这一点值得展开。查看 scripts/setup_local.sh 的实现可以看到它做的事情与“写代码”关系不大拉取部署文件从仓库main分支下载docker-compose.yaml可通过DOGRAH_SKIP_DOWNLOAD1跳过改用当前目录的 compose 文件生成生产取向的.env用openssl rand -hex 32随机生成OSS_JWT_SECRET、POSTGRES_PASSWORD、REDIS_PASSWORD、MinIO 根凭据等并写入容器镜像注册表地址默认REGISTRYghcr.io/dograh-hq与遥测开关ENABLE_TELEMETRY可选启用 coturn交互式询问是否开启 TURN 服务器用于 WebRTC NAT 穿透需指定浏览器与 API 容器都能访问的TURN_HOST和TURN_SECRET脚本内注释特别解释了为什么 127.0.0.1 不可用——API 容器自身的回环地址并不是 coturn 所在网络接口启动命令docker compose --profile tunnel up --pull always通过 Cloudflare quick tunnel 暴露一个临时公网 URL 以便入站电话 webhook 能到达本地 API最终应用访问地址为http://localhost:3010。也就是说setup_local.sh模拟的是部署者的视角拉官方镜像、起完整栈、打通公网隧道。而贡献者需要的是能改代码、跑测试、断点调试的环境——这正是 devcontainer 要解决的问题。Devcontainer 是官方贡献者工作流scripts/setup_local.devcontainer.md 给出的推荐路径是日常开发请使用仓库内建的.devcontainer/目录完整贡献者说明位于 docs/contribution/setup.mdx。前置条件引自 docs/contribution/setup.mdxGit本地 Docker 引擎如 Docker Desktop安装了 Dev Containers 扩展的 VS Code。标准流程共五步Fork 仓库并克隆你自己的 fork而不是上游仓库避免origin指向只读仓库在 VS Code 中打开文件夹执行Dev Containers: Reopen in Container。首次构建需要数分钟——它会启动 Postgres、Redis、MinIO预置 Python venv创建.env文件并安装 UI 依赖。之后的打开速度很快容器内终端启动后端bash scripts/start_services_dev.sh该脚本会等待健康检查通过后才退出正常退出即代表后端已就绪 4. 第二个终端启动 UIcd ui npm run dev -- --hostname 0.0.0.0浏览器打开http://localhost:3000。如果误克隆了上游仓库而非自己的 fork可运行bash scripts/setup_fork.sh它会提示输入 fork 地址、把origin指向 fork并添加upstream远端。没有 VS Code 的用户也可以用 Dev Container CLI 以无头方式运行 devcontainer或者完全脱离容器在宿主机上管理环境参见 docs/contribution/setup.mdx 中的折叠说明。容器是怎么建出来的.devcontainer/Dockerfile 的两阶段构建devcontainer 的核心是 .devcontainer/Dockerfile它采用两阶段构建注释写得非常清楚值得逐段理解。阶段一venv-builder —— 唯一的任务是填充 venv基础镜像是ubuntu:24.04关键安装步骤通过ppa:deadsnakes/ppa安装Python 3.13python3.13、python3.13-venv、python3.13-dev这就是文档中“pinned Python 3.13”的落地方式从官方 uv 镜像ghcr.io/astral-sh/uv:latest拷贝uv/uvx可执行文件以VIRTUAL_ENV/workspaces/dograh/venv创建 venv。在最终镜像中 venv 真实存在的路径上构建是为了保证 venv 内的 shebang 和 console-scripts 符号链接在 rsync 到命名卷后仍然有效用 uv 分两层安装依赖以最大化构建缓存Layer 1api/requirements.txtapi/requirements.dev.txt仅当这两个文件变化时缓存失效Layer 2pipecat 子模块及其一组 extrascartesia,deepgram,openai,elevenlabs,groq,google,azure,sarvam,soundfile,silero,webrtc,speechmatics,openrouter,camb,mcp,inworld,smallest和 dev group。pipecat 装完后有两处“加固”处理与api/Dockerfile保持镜像同步把pipecat[webrtc]拉进来的opencv-python换成opencv-python-headless——非 headless 构建链接 X11/Qtlibxcb*镜像里缺这些共享库时import cv2会在运行时失败预下载 NLTK 的punkt_tab分词器到/workspaces/dograh/venv/nltk_data避免 pipecat 文本处理在第一次 agent 运行时访问网络。NLTK 会自动从sys.prefix/nltk_data找到它因此随 venv 一起被拷贝/同步。阶段二运行时 devcontainer 镜像基于mcr.microsoft.com/devcontainers/base:ubuntu-24.04自带vscode用户、sudo 等 devcontainer 基础设施安装运行时工具链ffmpeg、jq、libpq-dev、postgresql-client、redis-tools、rsync、procps等同样从 deadsnakes 安装 Python 3.13并保留 uv供post-create.sh做 editable 安装及用户临时uv pip install。随后把阶段一填好的 venv 复制到/opt/venv-template并写入时间戳文件.build-stampCOPY --fromvenv-builder --chownvscode:vscode /workspaces/dograh/venv /opt/venv-template RUN date -u %s /opt/venv-template/.build-stamp这一步是整个 devcontainer 设计的精妙之处运行时命名卷会“遮蔽”/workspaces/dograh/venv避免重建容器时丢失已装好的环境而镜像里保留一份“模板” 构建时间戳让初始化脚本可以在依赖真正变化时才重新播种——后文会看到。服务编排两个 compose 文件如何拼出完整开发栈.devcontainer/devcontainer.json 声明了dockerComposeFile指向两个文件按顺序合并docker-compose-local.yaml提供三个基础设施服务.devcontainer/docker-compose.yml提供workspace容器本身。基础设施层postgres / redis / miniodocker-compose-local.yaml 中三个服务均定义了 healthcheck 并接入同一个 bridge 网络app-network服务镜像关键配置postgrespgvector/pgvector:pg17用户/密码/库均为postgrespg_isready健康检查数据卷postgres_dataredisredis:7--requirepass redissecretredis-cli -a redissecret ping健康检查minioquay.io/minio/minioserver /data --console-address :9001根账号minioadmin/minioadminS3 API 与 Console 端口9000/9001仅绑定到127.0.0.1显式 localhost 绑定避免直接暴露到局域网注意 Postgres 用的是pgvector 扩展版镜像这与仓库的知识库/检索能力embedding 存储相呼应Redis 密码redissecret与 api/.env.example 中REDIS_URL的默认值一一对应。工作区层workspace 容器.devcontainer/docker-compose.yml 定义了workspace服务build指向.devcontainer/Dockerfile命令为sleep infinity长驻容器进程由用户手动启动depends_on要求三个基础服务先通过健康检查才启动 workspace卷挂载源码.:/workspaces/dograh:cachedBind 挂载 缓存驱动以及三个命名卷——dograh-venv→/workspaces/dograh/venv、dograh-ui-node_modules→ui/node_modules、dograh-ts-validator-node_modules→api/mcp_server/ts_validator/node_modules端口映射0.0.0.0:3000:3000与0.0.0.0:8000:8000UI 与 APIextra_hosts添加host.docker.internal:host-gateway方便容器内回访问宿主机security_opt: seccompunconfined / apparmorunconfined与cap_add: SYS_ADMIN——这是为了让容器内可以调试、跑需要较宽系统调用的进程如实时语音管道、浏览器自动化测试类场景是 devcontainer 场景常见的放宽配置但应意识到它只应存在于开发环境。devcontainer.json 其余关键配置initializeCommand: git submodule update --init --recursive——因为pipecat/是 git 子模块语音管道 STT → LLM → TTS 的载体初始化阶段先同步子模块再开始构建runServices同时拉起workspace, postgres, redis, minioshutdownAction: stopCompose保证关闭容器时整个栈一起停forwardPorts自动转发 5432/6379/9000/9001方便宿主机的 DB 客户端直连portsAttributes里 3000Dograh UI和 8000Dograh API设为onAutoForward: ignore避免 VS Code 端口检测器在端口未绑定前反复轮询刷出 ECONNREFUSED 日志——post-start.sh 顶部的注释解释了这一取舍features安装 Node.js 24customizations.vscode预装 Python/Pylance/Debugpy/Docker/ESLint/Prettier 扩展并把 Python 解释器固定到/workspaces/dograh/venv/bin/python远程用户为vscode非 root与 venv 模板的chown vscode:vscode保持一致。首次进入容器post-create.sh 自动完成的五步devcontainer.json 中postCreateCommand指向 .devcontainer/scripts/post-create.sh这是“安装后端与前端依赖、创建容器专属 API env 文件、自动启动 Postgres/Redis/MinIO”这一承诺的具体实现。脚本带进度打印[n/5]、每步计时和set -euo pipefailtrap ERR的失败上报。五个步骤1. 修正命名卷挂载点的所有权命名卷由 Docker 以 root 创建而 postCreate 以vscode用户运行因此先sudo chown三个挂载点venv、ui/node_modules、api/mcp_server/ts_validator/node_modules。2. 从镜像模板播种 venv基于 build-stamp 的增量同步seed_venv函数比较镜像模板的.build-stamp与卷内现有 stamp相同则跳过输出Venv already in sync with image template不同则rsync -a --delete /opt/venv-template/ /workspaces/dograh/venv。效果是只有当.devcontainer/、api/requirements*.txt或 pipecat 源变化导致镜像重建时才会重灌 venv与 docs/contribution/setup.mdx 中“仅当.devcontainer/、api/requirements*.txt或pipecat/变化才需要重建容器”的说明严格对应。3. 生成容器专属的 env 文件主机名重写copy_env_with_docker_hostnames复制模板并把基础设施主机名从localhost改写为 compose 服务名sed -i \ -e s|localhost:5432|postgres:5432|g \ -e s|localhost:6379|redis:6379|g \ -e s|^MINIO_ENDPOINTlocalhost:9000|MINIO_ENDPOINTminio:9000| \ $dst涉及三个文件api/.env.example→api/.env、api/.env.test.example→api/.env.test测试环境供 pytest 使用、ui/.env.example→ui/.env。已有文件一律保留“Keeping existing …”不覆盖用户的本地修改。这里有一个刻意不重写的细节脚本注释写得很明白MINIO_PUBLIC_ENDPOINT保持localhost:9000——因为该 URL 会出现在 UI 的响应中最终由宿主机上的浏览器经 VS Code 端口转发加载而不是由容器内进程访问。对照 api/.env.example被重写的变量正是其中的DATABASE_URLpostgresqlasyncpg://postgres:postgreslocalhost:5432/postgres→postgres:5432REDIS_URLredis://:redissecretlocalhost:6379→redis:6379MINIO_ENDPOINTlocalhost:9000→minio:9000凭据minioadmin/minioadmin、bucketvoice-audio与 compose 中 MinIO 配置一致。模板还包含BACKEND_API_ENDPOINT、UI_APP_URL、LOG_LEVELDEBUG、ENABLE_SIGNUP、Langfuse 追踪凭据等条目均可在生成后的api/.env中直接调整。4. 把 pipecat 切换为可编辑安装uv pip install -e $ROOT_DIR/pipecat --no-deps播种的 venv 里 pipecat 依赖是构建时的冻结快照这一步重新以 editable 方式注册绑定挂载的工作区中的pipecat 源码使得对pipecat/的源码编辑立即生效--no-deps跳过重新解析传递依赖已由种子镜像满足。editable 安装也是后续调试能力的前提——docs/contribution/setup.mdx 说明因为 pipecat 以 editable 方式安装.vscode/launch.json中justMyCode: false时可以直接在pipecat/子模块内打断点。5. 并行安装 npm 依赖npm ci --prefix ui npm ci --prefix api/mcp_server/ts_validator wait || fail两处npm ci并行执行并分别等待任一失败立即报错退出。注意这两处node_modules都是命名卷跨容器重建保留。脚本最后还会检查一个可选的私人钩子.devcontainer/install.local.shgitignore 的按开发者定制脚本例如安装个人 AI 编程工具存在则执行不存在则安全跳过。再次打开容器时post-start.shpostStartCommand指向 .devcontainer/scripts/post-start.sh它不再做任何安装只打印启动提示刻意不打印http://localhost:PORT形式的 URL避免 VS Code 终端 URL 检测器把端口加入自动转发列表后持续轮询产生 ECONNREFUSED 日志Start the backend: bash scripts/start_services_dev.sh Start the UI in another terminal: cd ui npm run dev -- --hostname 0.0.0.0容器内的日常开发工作流后端由 scripts/start_services_dev.sh 统一管理。从脚本头部配置可以读出其工作方式加载api/.env可用DOGRAH_ENV_FILE覆盖、PID 文件存放于run/目录、日志按时间戳写入logs/timestamp/并维护logs/latest软链、对/api/v1/health做健康检查默认最多 30 次、间隔 2 秒通过后才算启动成功、Uvicorn 基于端口默认 8000 并对api/目录变更自动热重载。docs/contribution/setup.mdx 汇总的日常操作速查表完整继承场景做法重启后端重跑bash scripts/start_services_dev.sh——它会先停掉旧进程停止后端bash scripts/stop_services.sh查看后端日志tail -f logs/latest/*.log代码热重载api/下的编辑自动重载ari_manager、campaign_orchestrator、arq需要重启后端重建容器仅当.devcontainer/、api/requirements*.txt或pipecat/变化时——普通源码编辑永远不需要同步 pipecat 子模块拉取到子模块版本提升后执行git submodule update --init --recursive调试仓库在 .vscode/launch.json 中为每个后端服务和 pytest 都提供了调试配置。用调试器取代启动脚本的流程先停掉脚本托管的后端以释放端口bash scripts/stop_services.sh在 VS Code 的Run and Debug面板选择配置并按 F5配置运行内容API: Uvicorn (reload)FastAPI 后端带自动热重载端口取api/.env中UVICORN_PORT默认 8000API: Arq worker (watch)/API: Campaign orchestrator/API: ARI manager其余后端服务按需与 Uvicorn 并行启动Tests: API (pytest, full suite / current file)调试器下的 pytest针对api/.env.testTests: Pipecat (pytest, current file)/Python: Current file调试 pipecat 测试或任意独立脚本所有配置均加载api/.env测试配置加载api/.env.test并设置justMyCode: false因此可以单步进入 FastAPI 与 pipecat 内部代码。与仓库结构、贡献流程的衔接理解 devcontainer 在开发中的位置离不开它服务的仓库布局引自 docs/contribution/setup.mdx路径内容ui/Next.js 前端——工作流构建器、仪表盘与 agent 编辑器api/FastAPI 后端——REST API、campaign 编排、电话接入、ARQ 后台 workerpipecat/语音管道STT → LLM → TTS的 git 子模块docs/本文档站点MDX 编写sdk/以编程方式驱动 Dograh 的 Python/TypeScript SDKscripts/安装、部署与更新脚本含本文的setup_local.sh与 devcontainer 脚本deploy/远程部署使用的 nginx 与 coturn 配置模板devcontainer 中的三个命名卷与这些目录一一对应venv服务api/与pipecat/的 Python 依赖两个node_modules卷分别服务ui/与api/mcp_server/ts_validator/MCP 服务器的 TypeScript 校验器。贡献流程方面创建分支、提交改动、推送到 forkorigin并向dograh-hq/dograh:main发起 PR由维护者评审合并bug 与功能想法通过 Issue 与 Ideas 讨论区提交good first issue标签是入门起点。若你是想部署自己的构建而非向上游贡献则应走 docs/deployment/introduction.mdx 的部署路径——而不是本文的 devcontainer 路径也不是setup_local.sh的隧道模式。小结把 scripts/setup_local.devcontainer.md 的简短说明放回仓库上下文后可以得到清晰的分工图景setup_local.sh/setup_local.ps1面向部署验证与隧道联调拉镜像、生成强随机凭据的.env、可选 coturn起--profile tunnel栈应用入口http://localhost:3010.devcontainer/面向日常贡献两阶段 Dockerfile 钉住 Python 3.13 与 uv 工具链compose 自动拉起 pgvector Postgres、Redis、MinIO 并通过健康检查门控 workspace 启动post-create.sh完成 build-stamp 感知的 venv 播种、带主机名重写的api/.env/api/.env.test/ui/.env生成、pipecat editable 化与并行npm ci启动与迭代bash scripts/start_services_dev.sh等健康检查通过后启动后端cd ui npm run dev -- --hostname 0.0.0.0启动 UIlocalhost:3000访问界面仅当.devcontainer/、api/requirements*.txt或pipecat/变化时才需要重建容器。掌握这套结构后无论是要在 pipecat 管道中打断点、调整基础设施连接串还是为 MCP 校验器改 TypeScript都能在容器内以最短路径完成“改代码 → 生效 → 验证”的闭环。【免费下载链接】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 开源语音 AI 平台本地开发环境搭建：以 Devcontainer 为正式贡献者工作流的完整指南
Dograh 开源语音 AI 平台本地开发环境搭建以 Devcontainer 为正式贡献者工作流的完整指南【免费下载链接】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本文围绕 scripts/setup_local.devcontainer.md 展开讲清 Dograh一个可自托管的开源语音 AI 平台定位为 Vapi/Retell 的自部署替代方案中两类“本地运行”脚本的分工setup_local.sh/setup_local.ps1服务于 Docker 部署而仓库内建的.devcontainer/才是日常代码贡献的官方开发环境。读完本文你将掌握 devcontainer 的镜像构建原理、venv 预置与同步机制、Postgres/Redis/MinIO 三个基础服务的自动编排方式以及容器内启动后端与 UI 的完整日常开发流程。先分清边界setup_local.sh 是部署脚本不是开发环境scripts/setup_local.devcontainer.md 开篇就明确了一个容易被误用的事实setup_local.sh和setup_local.ps1负责为本地部署准备 OSSOpen SourceDocker 栈。它们不是本仓库推荐的贡献者工作流。这一点值得展开。查看 scripts/setup_local.sh 的实现可以看到它做的事情与“写代码”关系不大拉取部署文件从仓库main分支下载docker-compose.yaml可通过DOGRAH_SKIP_DOWNLOAD1跳过改用当前目录的 compose 文件生成生产取向的.env用openssl rand -hex 32随机生成OSS_JWT_SECRET、POSTGRES_PASSWORD、REDIS_PASSWORD、MinIO 根凭据等并写入容器镜像注册表地址默认REGISTRYghcr.io/dograh-hq与遥测开关ENABLE_TELEMETRY可选启用 coturn交互式询问是否开启 TURN 服务器用于 WebRTC NAT 穿透需指定浏览器与 API 容器都能访问的TURN_HOST和TURN_SECRET脚本内注释特别解释了为什么 127.0.0.1 不可用——API 容器自身的回环地址并不是 coturn 所在网络接口启动命令docker compose --profile tunnel up --pull always通过 Cloudflare quick tunnel 暴露一个临时公网 URL 以便入站电话 webhook 能到达本地 API最终应用访问地址为http://localhost:3010。也就是说setup_local.sh模拟的是部署者的视角拉官方镜像、起完整栈、打通公网隧道。而贡献者需要的是能改代码、跑测试、断点调试的环境——这正是 devcontainer 要解决的问题。Devcontainer 是官方贡献者工作流scripts/setup_local.devcontainer.md 给出的推荐路径是日常开发请使用仓库内建的.devcontainer/目录完整贡献者说明位于 docs/contribution/setup.mdx。前置条件引自 docs/contribution/setup.mdxGit本地 Docker 引擎如 Docker Desktop安装了 Dev Containers 扩展的 VS Code。标准流程共五步Fork 仓库并克隆你自己的 fork而不是上游仓库避免origin指向只读仓库在 VS Code 中打开文件夹执行Dev Containers: Reopen in Container。首次构建需要数分钟——它会启动 Postgres、Redis、MinIO预置 Python venv创建.env文件并安装 UI 依赖。之后的打开速度很快容器内终端启动后端bash scripts/start_services_dev.sh该脚本会等待健康检查通过后才退出正常退出即代表后端已就绪 4. 第二个终端启动 UIcd ui npm run dev -- --hostname 0.0.0.0浏览器打开http://localhost:3000。如果误克隆了上游仓库而非自己的 fork可运行bash scripts/setup_fork.sh它会提示输入 fork 地址、把origin指向 fork并添加upstream远端。没有 VS Code 的用户也可以用 Dev Container CLI 以无头方式运行 devcontainer或者完全脱离容器在宿主机上管理环境参见 docs/contribution/setup.mdx 中的折叠说明。容器是怎么建出来的.devcontainer/Dockerfile 的两阶段构建devcontainer 的核心是 .devcontainer/Dockerfile它采用两阶段构建注释写得非常清楚值得逐段理解。阶段一venv-builder —— 唯一的任务是填充 venv基础镜像是ubuntu:24.04关键安装步骤通过ppa:deadsnakes/ppa安装Python 3.13python3.13、python3.13-venv、python3.13-dev这就是文档中“pinned Python 3.13”的落地方式从官方 uv 镜像ghcr.io/astral-sh/uv:latest拷贝uv/uvx可执行文件以VIRTUAL_ENV/workspaces/dograh/venv创建 venv。在最终镜像中 venv 真实存在的路径上构建是为了保证 venv 内的 shebang 和 console-scripts 符号链接在 rsync 到命名卷后仍然有效用 uv 分两层安装依赖以最大化构建缓存Layer 1api/requirements.txtapi/requirements.dev.txt仅当这两个文件变化时缓存失效Layer 2pipecat 子模块及其一组 extrascartesia,deepgram,openai,elevenlabs,groq,google,azure,sarvam,soundfile,silero,webrtc,speechmatics,openrouter,camb,mcp,inworld,smallest和 dev group。pipecat 装完后有两处“加固”处理与api/Dockerfile保持镜像同步把pipecat[webrtc]拉进来的opencv-python换成opencv-python-headless——非 headless 构建链接 X11/Qtlibxcb*镜像里缺这些共享库时import cv2会在运行时失败预下载 NLTK 的punkt_tab分词器到/workspaces/dograh/venv/nltk_data避免 pipecat 文本处理在第一次 agent 运行时访问网络。NLTK 会自动从sys.prefix/nltk_data找到它因此随 venv 一起被拷贝/同步。阶段二运行时 devcontainer 镜像基于mcr.microsoft.com/devcontainers/base:ubuntu-24.04自带vscode用户、sudo 等 devcontainer 基础设施安装运行时工具链ffmpeg、jq、libpq-dev、postgresql-client、redis-tools、rsync、procps等同样从 deadsnakes 安装 Python 3.13并保留 uv供post-create.sh做 editable 安装及用户临时uv pip install。随后把阶段一填好的 venv 复制到/opt/venv-template并写入时间戳文件.build-stampCOPY --fromvenv-builder --chownvscode:vscode /workspaces/dograh/venv /opt/venv-template RUN date -u %s /opt/venv-template/.build-stamp这一步是整个 devcontainer 设计的精妙之处运行时命名卷会“遮蔽”/workspaces/dograh/venv避免重建容器时丢失已装好的环境而镜像里保留一份“模板” 构建时间戳让初始化脚本可以在依赖真正变化时才重新播种——后文会看到。服务编排两个 compose 文件如何拼出完整开发栈.devcontainer/devcontainer.json 声明了dockerComposeFile指向两个文件按顺序合并docker-compose-local.yaml提供三个基础设施服务.devcontainer/docker-compose.yml提供workspace容器本身。基础设施层postgres / redis / miniodocker-compose-local.yaml 中三个服务均定义了 healthcheck 并接入同一个 bridge 网络app-network服务镜像关键配置postgrespgvector/pgvector:pg17用户/密码/库均为postgrespg_isready健康检查数据卷postgres_dataredisredis:7--requirepass redissecretredis-cli -a redissecret ping健康检查minioquay.io/minio/minioserver /data --console-address :9001根账号minioadmin/minioadminS3 API 与 Console 端口9000/9001仅绑定到127.0.0.1显式 localhost 绑定避免直接暴露到局域网注意 Postgres 用的是pgvector 扩展版镜像这与仓库的知识库/检索能力embedding 存储相呼应Redis 密码redissecret与 api/.env.example 中REDIS_URL的默认值一一对应。工作区层workspace 容器.devcontainer/docker-compose.yml 定义了workspace服务build指向.devcontainer/Dockerfile命令为sleep infinity长驻容器进程由用户手动启动depends_on要求三个基础服务先通过健康检查才启动 workspace卷挂载源码.:/workspaces/dograh:cachedBind 挂载 缓存驱动以及三个命名卷——dograh-venv→/workspaces/dograh/venv、dograh-ui-node_modules→ui/node_modules、dograh-ts-validator-node_modules→api/mcp_server/ts_validator/node_modules端口映射0.0.0.0:3000:3000与0.0.0.0:8000:8000UI 与 APIextra_hosts添加host.docker.internal:host-gateway方便容器内回访问宿主机security_opt: seccompunconfined / apparmorunconfined与cap_add: SYS_ADMIN——这是为了让容器内可以调试、跑需要较宽系统调用的进程如实时语音管道、浏览器自动化测试类场景是 devcontainer 场景常见的放宽配置但应意识到它只应存在于开发环境。devcontainer.json 其余关键配置initializeCommand: git submodule update --init --recursive——因为pipecat/是 git 子模块语音管道 STT → LLM → TTS 的载体初始化阶段先同步子模块再开始构建runServices同时拉起workspace, postgres, redis, minioshutdownAction: stopCompose保证关闭容器时整个栈一起停forwardPorts自动转发 5432/6379/9000/9001方便宿主机的 DB 客户端直连portsAttributes里 3000Dograh UI和 8000Dograh API设为onAutoForward: ignore避免 VS Code 端口检测器在端口未绑定前反复轮询刷出 ECONNREFUSED 日志——post-start.sh 顶部的注释解释了这一取舍features安装 Node.js 24customizations.vscode预装 Python/Pylance/Debugpy/Docker/ESLint/Prettier 扩展并把 Python 解释器固定到/workspaces/dograh/venv/bin/python远程用户为vscode非 root与 venv 模板的chown vscode:vscode保持一致。首次进入容器post-create.sh 自动完成的五步devcontainer.json 中postCreateCommand指向 .devcontainer/scripts/post-create.sh这是“安装后端与前端依赖、创建容器专属 API env 文件、自动启动 Postgres/Redis/MinIO”这一承诺的具体实现。脚本带进度打印[n/5]、每步计时和set -euo pipefailtrap ERR的失败上报。五个步骤1. 修正命名卷挂载点的所有权命名卷由 Docker 以 root 创建而 postCreate 以vscode用户运行因此先sudo chown三个挂载点venv、ui/node_modules、api/mcp_server/ts_validator/node_modules。2. 从镜像模板播种 venv基于 build-stamp 的增量同步seed_venv函数比较镜像模板的.build-stamp与卷内现有 stamp相同则跳过输出Venv already in sync with image template不同则rsync -a --delete /opt/venv-template/ /workspaces/dograh/venv。效果是只有当.devcontainer/、api/requirements*.txt或 pipecat 源变化导致镜像重建时才会重灌 venv与 docs/contribution/setup.mdx 中“仅当.devcontainer/、api/requirements*.txt或pipecat/变化才需要重建容器”的说明严格对应。3. 生成容器专属的 env 文件主机名重写copy_env_with_docker_hostnames复制模板并把基础设施主机名从localhost改写为 compose 服务名sed -i \ -e s|localhost:5432|postgres:5432|g \ -e s|localhost:6379|redis:6379|g \ -e s|^MINIO_ENDPOINTlocalhost:9000|MINIO_ENDPOINTminio:9000| \ $dst涉及三个文件api/.env.example→api/.env、api/.env.test.example→api/.env.test测试环境供 pytest 使用、ui/.env.example→ui/.env。已有文件一律保留“Keeping existing …”不覆盖用户的本地修改。这里有一个刻意不重写的细节脚本注释写得很明白MINIO_PUBLIC_ENDPOINT保持localhost:9000——因为该 URL 会出现在 UI 的响应中最终由宿主机上的浏览器经 VS Code 端口转发加载而不是由容器内进程访问。对照 api/.env.example被重写的变量正是其中的DATABASE_URLpostgresqlasyncpg://postgres:postgreslocalhost:5432/postgres→postgres:5432REDIS_URLredis://:redissecretlocalhost:6379→redis:6379MINIO_ENDPOINTlocalhost:9000→minio:9000凭据minioadmin/minioadmin、bucketvoice-audio与 compose 中 MinIO 配置一致。模板还包含BACKEND_API_ENDPOINT、UI_APP_URL、LOG_LEVELDEBUG、ENABLE_SIGNUP、Langfuse 追踪凭据等条目均可在生成后的api/.env中直接调整。4. 把 pipecat 切换为可编辑安装uv pip install -e $ROOT_DIR/pipecat --no-deps播种的 venv 里 pipecat 依赖是构建时的冻结快照这一步重新以 editable 方式注册绑定挂载的工作区中的pipecat 源码使得对pipecat/的源码编辑立即生效--no-deps跳过重新解析传递依赖已由种子镜像满足。editable 安装也是后续调试能力的前提——docs/contribution/setup.mdx 说明因为 pipecat 以 editable 方式安装.vscode/launch.json中justMyCode: false时可以直接在pipecat/子模块内打断点。5. 并行安装 npm 依赖npm ci --prefix ui npm ci --prefix api/mcp_server/ts_validator wait || fail两处npm ci并行执行并分别等待任一失败立即报错退出。注意这两处node_modules都是命名卷跨容器重建保留。脚本最后还会检查一个可选的私人钩子.devcontainer/install.local.shgitignore 的按开发者定制脚本例如安装个人 AI 编程工具存在则执行不存在则安全跳过。再次打开容器时post-start.shpostStartCommand指向 .devcontainer/scripts/post-start.sh它不再做任何安装只打印启动提示刻意不打印http://localhost:PORT形式的 URL避免 VS Code 终端 URL 检测器把端口加入自动转发列表后持续轮询产生 ECONNREFUSED 日志Start the backend: bash scripts/start_services_dev.sh Start the UI in another terminal: cd ui npm run dev -- --hostname 0.0.0.0容器内的日常开发工作流后端由 scripts/start_services_dev.sh 统一管理。从脚本头部配置可以读出其工作方式加载api/.env可用DOGRAH_ENV_FILE覆盖、PID 文件存放于run/目录、日志按时间戳写入logs/timestamp/并维护logs/latest软链、对/api/v1/health做健康检查默认最多 30 次、间隔 2 秒通过后才算启动成功、Uvicorn 基于端口默认 8000 并对api/目录变更自动热重载。docs/contribution/setup.mdx 汇总的日常操作速查表完整继承场景做法重启后端重跑bash scripts/start_services_dev.sh——它会先停掉旧进程停止后端bash scripts/stop_services.sh查看后端日志tail -f logs/latest/*.log代码热重载api/下的编辑自动重载ari_manager、campaign_orchestrator、arq需要重启后端重建容器仅当.devcontainer/、api/requirements*.txt或pipecat/变化时——普通源码编辑永远不需要同步 pipecat 子模块拉取到子模块版本提升后执行git submodule update --init --recursive调试仓库在 .vscode/launch.json 中为每个后端服务和 pytest 都提供了调试配置。用调试器取代启动脚本的流程先停掉脚本托管的后端以释放端口bash scripts/stop_services.sh在 VS Code 的Run and Debug面板选择配置并按 F5配置运行内容API: Uvicorn (reload)FastAPI 后端带自动热重载端口取api/.env中UVICORN_PORT默认 8000API: Arq worker (watch)/API: Campaign orchestrator/API: ARI manager其余后端服务按需与 Uvicorn 并行启动Tests: API (pytest, full suite / current file)调试器下的 pytest针对api/.env.testTests: Pipecat (pytest, current file)/Python: Current file调试 pipecat 测试或任意独立脚本所有配置均加载api/.env测试配置加载api/.env.test并设置justMyCode: false因此可以单步进入 FastAPI 与 pipecat 内部代码。与仓库结构、贡献流程的衔接理解 devcontainer 在开发中的位置离不开它服务的仓库布局引自 docs/contribution/setup.mdx路径内容ui/Next.js 前端——工作流构建器、仪表盘与 agent 编辑器api/FastAPI 后端——REST API、campaign 编排、电话接入、ARQ 后台 workerpipecat/语音管道STT → LLM → TTS的 git 子模块docs/本文档站点MDX 编写sdk/以编程方式驱动 Dograh 的 Python/TypeScript SDKscripts/安装、部署与更新脚本含本文的setup_local.sh与 devcontainer 脚本deploy/远程部署使用的 nginx 与 coturn 配置模板devcontainer 中的三个命名卷与这些目录一一对应venv服务api/与pipecat/的 Python 依赖两个node_modules卷分别服务ui/与api/mcp_server/ts_validator/MCP 服务器的 TypeScript 校验器。贡献流程方面创建分支、提交改动、推送到 forkorigin并向dograh-hq/dograh:main发起 PR由维护者评审合并bug 与功能想法通过 Issue 与 Ideas 讨论区提交good first issue标签是入门起点。若你是想部署自己的构建而非向上游贡献则应走 docs/deployment/introduction.mdx 的部署路径——而不是本文的 devcontainer 路径也不是setup_local.sh的隧道模式。小结把 scripts/setup_local.devcontainer.md 的简短说明放回仓库上下文后可以得到清晰的分工图景setup_local.sh/setup_local.ps1面向部署验证与隧道联调拉镜像、生成强随机凭据的.env、可选 coturn起--profile tunnel栈应用入口http://localhost:3010.devcontainer/面向日常贡献两阶段 Dockerfile 钉住 Python 3.13 与 uv 工具链compose 自动拉起 pgvector Postgres、Redis、MinIO 并通过健康检查门控 workspace 启动post-create.sh完成 build-stamp 感知的 venv 播种、带主机名重写的api/.env/api/.env.test/ui/.env生成、pipecat editable 化与并行npm ci启动与迭代bash scripts/start_services_dev.sh等健康检查通过后启动后端cd ui npm run dev -- --hostname 0.0.0.0启动 UIlocalhost:3000访问界面仅当.devcontainer/、api/requirements*.txt或pipecat/变化时才需要重建容器。掌握这套结构后无论是要在 pipecat 管道中打断点、调整基础设施连接串还是为 MCP 校验器改 TypeScript都能在容器内以最短路径完成“改代码 → 生效 → 验证”的闭环。【免费下载链接】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），仅供参考