如何快速完成 Dograh 远程服务器部署：自定义域名、Nginx 反向代理与 COTURN 全配置指南-港品优选

如何快速完成 Dograh 远程服务器部署：自定义域名、Nginx 反向代理与 COTURN 全配置指南

【免费下载链接】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 平台（voice AI platform），也是 Vapi、Retell 的自托管（self-hosted）替代方案。它支持视觉工作流编辑器、MCP 原生集成和电话系统接入。本文将带你在一台远程服务器上完成 Dograh 的完整生产级部署：一键拉起服务、理解 Nginx 反向代理的配置原理、配置 COTURN TURN 服务器解决 WebRTC 穿透，最后绑定自定义域名并自动续期 SSL 证书。全程约 30 分钟，无需手写任何配置。

部署前检查：服务器配置与端口清单

在开始之前，请确认你的服务器满足以下要求（详见官方文档 docs/deployment/docker.mdx）：

检查项	要求
硬件	最低8 GB 内存 + 4 vCPU，建议使用全新服务器
系统	已安装 Docker 和 Docker Compose（`docker compose version`可验证）
网络	拥有公网 IP
权限	需要`sudo`（root）权限运行安装脚本

⚠️端口是远程部署中最高频的踩坑点。请在云服务商防火墙和安全组中同时放行：

协议	端口	用途
TCP/UDP	80、443	访问 Web 界面与 HTTPS
TCP/UDP	3478、5349	WebRTC 信令（TURN/STUN）
UDP	49152-49200	WebRTC 媒体中继

浏览器出于安全限制，只在 HTTPS（或 localhost）下开放麦克风权限，所以远程部署必须走 HTTPS——这一点 Dograh 的自动化脚本已经全部替你处理好。

一键启动远程部署

先获取 Dograh 仓库，然后运行官方远程部署脚本 scripts/setup_remote.sh：

git clone https://gitcode.com/GitHub_Trending/do/dograh.git cd dograh sudo ./scripts/setup_remote.sh

脚本会依次询问你：

服务器公网 IP；
TURN 服务器密码（回车生成随机值）；
部署模式——prebuilt（拉取官方镜像，推荐）或build（从源码构建，适合维护 fork 的用户）；
FastAPI worker 数量——默认4，一般与 vCPU 数一致即可。

脚本会自动完成：获取docker-compose.yaml、签发 Let's Encrypt 证书（公网 IP 通过 sslip.io 免费获得可信证书并配置自动续期）、生成包含 TURN 配置的环境文件.env、以及运行dograh-init预校验。完成后进入dograh/目录启动：

cd dograh ./remote_up.sh

启动脚本 remote_up.sh 会先做 preflight 校验（重新渲染 nginx 与 coturn 运行时配置），再拉起整个容器栈。浏览器访问终端打印的地址（形如https://203-0-113-10.sslip.io）即可进入平台，无需任何 DNS 配置就没有浏览器警告。

理解 Nginx 反向代理：它替你做了什么

远程部署栈中内置了一个nginx:alpine容器（见 docker-compose.yaml 的nginx服务），它承担三类工作。配置模板位于 deploy/templates/nginx.remote.conf.template，由dograh-init根据.env自动渲染，无需手工维护：

1️⃣ HTTP → HTTPS 强制跳转 + ACME 证书校验

80 端口仅暴露/.well-known/acme-challenge/路径用于 Let's Encrypt 的 HTTP-01 校验，其余请求 301 跳转到 HTTPS。这个设计让证书签发和续期全程零停机（nginx 无需停止）。

2️⃣ API 请求负载均衡与 WebSocket 长连接

/api/v1/路径被代理到名为dograh_api的 upstream，内部包含所有 FastAPI worker 端口（8000、8001、8002……），并采用least_conn（最少连接）策略。语音通话是长驻 WebSocket，least_conn能把流式连接均匀分散到各 worker，避免个别进程过载。模板中同时设置了proxy_read_timeout 3600s与Upgrade头，保证音频流不断连。

3️⃣ 静态资源与对象存储路由

/转发到 UI 容器（3010 端口）；
/voice-audio/直接代理到 MinIO（9000 端口），录音与转写文件下载不绕路；
通过sub_filter把 API 响应里的localhost:9000内网地址改写为当前域名，外链即可公网访问。

COTURN 配置详解：语音通话不串门、不掉线

WebRTC 要穿越 NAT，离不开 TURN 中继。Dograh 在栈中内置了coturn/coturn:4.8.0容器，配置模板见 deploy/templates/turnserver.remote.conf.template（仓库内另有一份带详细注释的参考配置 config/coturn/turnserver.conf）。核心参数一览：

配置项	值	说明
`listening-port`	3478	TURN 服务端口（UDP/TCP）
`tls-listening-port`	5349	TLS 加密端口
`min-port`/`max-port`	49152 / 49200	媒体中继端口范围（务必放行 UDP）
`external-ip`	服务器公网 IP	`dograh-init`自动渲染，NAT 穿透关键
`use-auth-secret`	开启	使用 TURN REST API 临时凭证
`static-auth-secret`	与`.env`中`TURN_SECRET`一致	HMAC-SHA1 共享密钥
`fingerprint`/`no-cli`/`no-multicast-peers`	开启	安全加固项

🔐 认证机制上，Dograh 没有使用固定的账号密码，而是采用TURN REST API：后端根据共享密钥为每通电话动态签发有时效的凭证（默认 24 小时，由TURN_CREDENTIAL_TTL控制），更安全。

如何验证 TURN 真的在工作？在.env中加入FORCE_TURN_RELAY=true并重启。此时浏览器只允许走中继候选（relay-only），如果 TURN 配置有误，通话会干净地报ICE failed，而不是"看起来能通"实则没声音。验证通过后改回false即可。

部署成功进入平台后，创建 API Key 并开始你的第一次语音 Agent 调用测试：

自定义域名：从 IP 到 voice.yourcompany.com

如果 IP 形式的地址不够体面，可以绑定自己的域名（完整文档见 docs/deployment/custom-domain.mdx）。分三步：

第一步：添加 DNS A 记录

在域名解析面板添加：类型为A，主机记录为voice（子域）或@（根域），值填服务器公网 IP，TTL 300。生效后用nslookup voice.yourcompany.com确认真的解析到了你的 IP。

第二步：修改.env中的两个变量

cd dograh sed -i "s/^PUBLIC_HOST=.*/PUBLIC_HOST=voice.yourcompany.com/" .env sed -i "s|^PUBLIC_BASE_URL=.*|PUBLIC_BASE_URL=https://voice.yourcompany.com|" .env

这两个变量是整个部署的"锚点"：dograh-init会用PUBLIC_HOST渲染 nginx 的server_name，而 webhook 回调地址、MinIO 下载链接、TURN 主机名都从PUBLIC_BASE_URL派生，改这一处即可全局生效（变量说明见 docs/developer/environment-variables.mdx）。

第三步：签发并自动续期证书

# 1. 先确保栈在运行（nginx 需要用 80 端口应答 ACME 校验） ./remote_up.sh # 2. 用 webroot 方式签发证书，零停机 sudo certbot certonly --webroot -w "$(pwd)/certs" -d voice.yourcompany.com # 3. 复制证书并重启 nginx 加载 sudo cp /etc/letsencrypt/live/voice.yourcompany.com/fullchain.pem certs/local.crt sudo cp /etc/letsencrypt/live/voice.yourcompany.com/privkey.pem certs/local.key sudo docker compose --profile remote restart nginx

也可以直接运行官方一键脚本 scripts/setup_custom_domain.sh，它会完成 DNS 校验、Certbot 安装、证书签发、.env更新和续期钩子的全部工作。

🔄别忘了自动续期：Let's Encrypt 证书 90 天到期。创建/etc/letsencrypt/renewal-hooks/deploy/dograh-reload.sh，内容就是"复制新证书 → 重启 nginx"，然后用sudo certbot renew --dry-run演练一遍。

⚠️ 注意：不要移动dograh/目录，续期钩子的路径是写死指向它的。

上线后调优：几个值得认识的环境变量

变量	作用	建议
`FASTAPI_WORKERS`	nginx 负载均衡的 worker 数	每加一个 worker 约需 300–500 MB 内存，改完执行`./remote_up.sh`生效
`TURN_SECRET`	TURN 共享密钥	生产环境务必用随机强密钥
`TURN_HOST`/`TURN_PORT`	TURN 地址与端口	默认派生自`PUBLIC_HOST`，仅 TURN 独立部署时手动设置
`FORCE_TURN_RELAY`	强制走中继	仅作诊断，平时保持`false`

多 worker 模式下，nginx 的least_conn会把并发通话均匀分摊到各 uvicorn 进程；如果调用量继续增长，可参考 docs/deployment/scaling.mdx 了解水平扩容思路。

常见问题速查

Q：页面能打开，但语音通话没声音？大概率是 3478、5349 或 49152-49200 端口没放通。先用FORCE_TURN_RELAY=true复现，确认是 TURN 问题再排查防火墙。

Q：证书签发失败？检查 80 端口是否开放、DNS 是否已生效、以及 Let's Encrypt 是否触发速率限制（可稍后重试）。

Q：改完.env后不生效？不要直接docker compose up，统一走./remote_up.sh，它会先重新渲染 nginx/coturn 配置再启动，保证三者对齐。

Q：浏览器显示 SSL 证书错误？先ls -la dograh/certs/确认证书已复制，再运行./remote_up.sh --preflight-only做纯校验，最后重启 nginx 容器。

至此，你拥有了一台带自定义域名、可信 SSL、完整 TURN 中继能力的 Dograh 生产环境。接下来可以创建 Agent、接入电话线路，或按 docs/deployment/update.mdx 跟踪版本升级，让这套自托管语音 AI 平台持续跑在你的服务器上。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析