Dograh 脚本体系详解：三种服务启动模式、Bash/PowerShell 配对与 OSS Docker 部署机制

Dograh 脚本体系详解三种服务启动模式、Bash/PowerShell 配对与 OSS Docker 部署机制【免费下载链接】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 仓库scripts/目录的开发者指南scripts/AGENTS.md为主体完整梳理该目录的三条核心工程约束Bash 与 PowerShell 脚本的配对同步规则、OSS Docker 部署的共享脚本模型.env单一事实源 dograh-init运行时配置渲染以及三个启动脚本的职责边界。读完你可以理解 Dograh 从本地开发到裸机/ Docker 生产部署的完整脚本链路并能在维护或排障时准确定位应修改哪个脚本。scripts/ 目录定位scripts/承载 Dograh 所有面向贡献者和运维者的可执行脚本本地开发环境初始化、依赖安装、服务启停、数据库迁移Alembic、SDK 发布、以及 OSS 版本的远程/本地 Docker 部署。目录下还有一个lib/子目录存放共享的 Bash 函数库scripts/lib/setup_common.sh被多个部署脚本以 source 方式复用。理解这个目录的关键是把握 AGENTS.md 给出的三条主线配对同步面向贡献者的脚本同时提供.sh与.ps1两个版本改一个必须同步改另一个部署耦合OSS Docker 部署相关的脚本是相互耦合的一组改动任何一个都要假设其他脚本会受影响启动分型三个start_services*脚本分别对应本地开发、裸机生产、Docker 镜像三种截然不同的运行形态不可混用。Bash ↔ PowerShell 配对保持同步Dograh 的大多数贡献者脚本以.sh.ps1成对提供让 macOS/Linux 与 Windows 用户获得一致的工作流。当你编辑其中一个时必须在同一次变更中编辑另一个。环境变量名、默认值、命令行参数和行为都应保持一致——例如如果start_services_dev.sh读取HEALTH_MAX_ATTEMPTS那么start_services_dev.ps1也应该读取同名变量。当前配对清单配对用途setup_fork.{sh,ps1}贡献者引导git remotes、子模块、venv、env 文件setup_requirements.{sh,ps1}Python pipecat 依赖安装start_services_dev.{sh,ps1}本地后端启动器自动重载 健康检查等待stop_services.{sh,ps1}停止本地服务makemigrate.{sh,ps1}/migrate.{sh,ps1}Alembic 迁移辅助setup_local.{sh,ps1}OSS 本地 Docker-compose 环境可选 coturn/TURN从 scripts/start_services_dev.sh 可以看到这类行为对齐的具体形态健康检查端点/api/v1/health、HEALTH_MAX_ATTEMPTS默认 30 次、HEALTH_INTERVAL默认 2 秒都以带默认值的环境变量读取PowerShell 版本应镜像相同的变量名与默认值。仅 Bash 的脚本部署 / CI / OSS 用户专用以下脚本不面向 Windows 贡献者没有.ps1对应版本start_services.sh—— 裸机VM生产启动start_services_docker.sh—— Docker 镜像的CMDrolling_update.sh—— 裸机的零停机重新部署setup_remote.sh—— OSS 远程 Docker-compose 安装format.sh/lint.sh/pre_commit.shgenerate_sdk.sh/release_sdks.sh/dump_docs_openapi.pysetup-worktree.sh/worktree-sync-env.sh—— VS Code git worktree 开发流配合.vscode/tasks.json。判断一个新脚本该不该提供 PowerShell 版本标准就是它的受众本地开发流配对部署/CI 流仅 Bash。OSS Docker 部署模型一组相互耦合的脚本AGENTS.md 用 Deployment Memory 一节固化了当前 OSS Docker 安装的共享部署模型。一旦你触碰下列任何脚本都应假设它们是耦合的需要一起审查。setup_common.sh共享部署函数库scripts/lib/setup_common.sh 是共享部署辅助库被以下入口脚本 sourcescripts/setup_local.shscripts/setup_remote.shscripts/update_remote.shscripts/setup_custom_domain.shscripts/run_dograh_init.sh仓库根目录的 remote_up.sh两个硬性约束必须保证被 source 后是安全的——库内部不应设置set -u等 shell 选项否则会改变调用方脚本的行为可执行入口与函数库职责分离scripts/run_dograh_init.sh 是可执行入口docker compose 直接运行它不是库。若未来重构必须保持lib/中被 source 的辅助逻辑与可执行入口之间的区分。.env 是运维者拥有的唯一事实源远程部署设置以.env为单一事实源运行时配置应从它派生而不是反过来。规范的远程键canonical keys包括键说明ENVIRONMENT部署环境标识production触发完整远程校验SERVER_IP服务器自身的 IPv4 地址必须保持为裸 IPcoturn 的external-ip需要它PUBLIC_HOST对外主机名可以是域名如 sslip.io 名称PUBLIC_BASE_URL对外完整 URL是端点的唯一事实源ENABLE_COTURN是否启用 coturndograh_sync_remote_env_file会将其同步为true远程安装永远运行 coturnTURN_SECRETcoturn 的static-auth-secretFASTAPI_WORKERSuvicorn 工作进程数nginx upstream 按此动态展开OSS_JWT_SECRETJWT 密钥ENABLE_COTURN还有一个跨端联动语义API 会在/health中把它上报为turn_enabled浏览器端据此决定是否跳过 TURN。应用内派生的变量不再写入远程 .envBACKEND_API_ENDPOINT、MINIO_PUBLIC_ENDPOINT、TURN_HOST这三个值在应用内从PUBLIC_BASE_URL/PUBLIC_HOST派生见 api/constants.py不再写入远程.env# api/constants.py BACKEND_API_ENDPOINT ( os.getenv(BACKEND_API_ENDPOINT) or PUBLIC_BASE_URL or http://localhost:8000 ) # ... MINIO_PUBLIC_ENDPOINT ( os.getenv(MINIO_PUBLIC_ENDPOINT) or PUBLIC_BASE_URL or http://localhost:9000 ) # ... TURN_HOST os.getenv(TURN_HOST) or PUBLIC_HOST or localhost由此产生两条部署侧规则在 scripts/lib/setup_common.sh 中实现dograh_sync_remote_env_file既不写也不删这三个键新安装直接省略它们运维者手工设置的值保持不动作为拆分部署独立对象存储 / 独立 TURN 主机的显式覆盖因此dograh_validate_remote_runtime_env不再要求这三个键存在也不再断言它们必须等于PUBLIC_BASE_URL——运维者显式设置的值被原样尊重。remote_up.sh受支持的远程启动入口remote_up.sh 是官方远程启动入口其流程为若本机缺少scripts/lib/setup_common.sh先从上游下载一份 bootstrap 副本remote_up.sh运行预检dograh_prepare_remote_install同步规范.env键 → 校验 compose 布局 → 预渲染docker compose config -q校验 compose 文件启动前调用dograh_sync_postgres_password调和 Postgres 角色密码与.env中POSTGRES_PASSWORD的差异POSTGRES_PASSWORD只在数据卷首次初始化时生效旧卷可能残留旧密码该步骤通过本地受信 socket 执行ALTER USER幂等组装 compose profiles 并以exec启动栈。关键参数与行为remote_up.sh--build使用--build --force-recreate本地构建镜像否则--pull always --force-recreate--preflight-only/--validate-only只做预检不启动若通过sudo调用退出前会把部署目录属主chown回调用者避免预检改写.env后目录变成 root 属主。dograh-init一次性配置渲染服务docker-compose.yaml 使用一次性服务dograh-initprofiles: [remote, local-turn]容器内执行 scripts/run_dograh_init.sh把 nginx / coturn 运行时配置渲染进命名卷nginx-generated/coturn-generated供nginx挂载到/etc/nginx/conf.d:ro与coturn挂载到/etc/coturn:ro消费。从 scripts/run_dograh_init.sh 的分支逻辑看该入口按环境分三种行为ENVIRONMENTproduction执行完整远程校验dograh_validate_remote_runtime_env、要求certs/local.{crt,key}存在然后渲染远程 nginx 与 coturn 配置本地环境且设置了TURN_SECRETTURN_HOST仅渲染本地 TURN 配置其他情况打印 no-op 后退出。这意味着远程的 nginx/coturn 配置是运行时生成的。宿主机手工管理的nginx.conf/turnserver.conf属于遗留legacy方案升级流程可以备份并删除它们但当前安装不应再依赖这些宿主文件。cloudflared 隧道按 profile 门控公私网自动判定cloudflared服务挂在tunnelprofile 下不再常驻api服务也不再depends_on它。隧道的启用由SERVER_IP是否为私有/保留地址自动判定remote_up.sh 中--profile remote始终启用当dograh_is_local_ipv4判定SERVER_IP为私有/保留地址即宿主机没有公网 IP时追加--profile tunnel。公网 IP 安装只跑--profile remote不启动隧道本地安装则手动加--profile tunnel选择加入。后端做了完全镜像的判定api/utils/common.py 中的is_local_or_private_url()决定get_backend_endpoints()api/utils/common.py何时在运行时解析隧道 URL。文档明确要求两侧 IP 分类器保持对齐包括 CGNAT100.64.0.0/10网段——dograh_is_local_ipv4scripts/lib/setup_common.sh检查10/8、127/8、169.254/16、172.16-31、192.168/16与100.64.0.0/10与 Python 侧ip.is_private/is_loopback/is_link_local/is_reserved/is_unspecified CGNAT 网络一一对应。cloudflared 自身按 token 决定运行模式有CLOUDFLARE_TUNNEL_TOKEN运行命名隧道稳定主机名——此时把BACKEND_API_ENDPOINT指向该主机名并在 Cloudflare 面板 ingress 中把流量指向容器内的http://api:8000无 token运行临时quick隧道*.trycloudflare.com后端通过 cloudflared 容器的:2000metrics 端点发现其 URL见 api/utils/tunnel.py。三个安装/升级脚本的职责边界setup_remote.sh —— 全新远程安装。它写.env、下载部署辅助文件包helper bundle、生成自签名证书、校验基于 init 的配置路径最后提示运维者通过./remote_up.sh或./remote_up.sh --build启动。它硬性要求 root脚本顶部有守卫非 root 直接以请用 sudo 重跑退出因为它要安装 Docker、绑定:80/:443、并安装 Lets Encrypt 证书 系统续期钩子。Cloud-init / user-data 调用方如infrastructure/本就运行在 root 下可以直接通过交互式调用者必须sudo。引用它的文档docs/deployment/docker.mdx、docs/deployment/scaling.mdx以及setup_custom_domain.sh打印的提示都统一使用sudo。update_remote.sh —— 预构建安装的升级路径。它刷新docker-compose.yaml、remote_up.sh、scripts/run_dograh_init.sh、scripts/lib/setup_common.sh与deploy/templates/*备份被触碰的文件移除遗留的宿主nginx.conf/turnserver.conf并重新校验 init 路径。setup_custom_domain.sh —— 只做证书/域名粘合。它不得拥有 nginx 配置。职责限于更新.env中的规范公网 URL 键、把 Lets Encrypt 证书复制进certs/、安装续期钩子、通过./remote_up.sh重启。setup_local.{sh,ps1} —— 本地 Docker 环境。除非ENABLE_COTURN已预设否则交互式询问Enable coturn? [y/N]启用后下载local-turn所需的最小辅助文件包setup_common.sh、run_dograh_init.sh、模板并依赖dograh-init渲染 coturn 配置。该脚本必须在环境变量未设置时也能安全运行Bash 侧对ENABLE_COTURN、TURN_HOST、TURN_SECRET、DOGRAH_SKIP_DOWNLOAD等可选输入使用${VAR:-}守卫PowerShell 侧做 null/空值检查。预检与遗留布局守卫dograh_prepare_remote_installscripts/lib/setup_common.sh目前做三件事同步规范.env键dograh_sync_remote_env_file拒绝不使用dograh-init的遗留 compose 布局dograh_require_init_compose_layout在临时目录中预检 init 渲染dograh_preflight_remote_init_render——在mktemp -d目录里真正跑一遍run_dograh_init.sh并断言渲染产物nginx upstream 的 server 行数等于FASTAPI_WORKERS、server_name等于PUBLIC_HOST、turnserver.conf 的static-auth-secret与external-ip分别等于TURN_SECRET/SERVER_IP。dograh_uses_init_compose_layout/dograh_require_init_compose_layout是面向旧安装的护栏若远程安装仍然 bind-mount 宿主nginx.conf/turnserver.conf即 compose 中没有dograh-init:服务、没有nginx-generated:/etc/nginx/conf.d:ro与coturn-generated:/etc/coturn:ro挂载预检会直接失败预期修复路径是./update_remote.sh。模板与渲染模板位于deploy/templates/下deploy/templates/nginx.remote.conf.template 包含静态骨架__DOGRAH_UPSTREAM_BLOCK__占位由dograh_render_remote_nginx_confscripts/lib/setup_common.sh动态展开为多 worker upstream——按FASTAPI_WORKERS生成server api:8000…server api:8000N使用least_conn负载均衡与keepalive 32__DOGRAH_PUBLIC_HOST__占位替换为PUBLIC_HOSTdeploy/templates/turnserver.remote.conf.template 由dograh_render_remote_turn_conf从环境渲染替换__DOGRAH_TURN_EXTERNAL_IP__与__DOGRAH_TURN_SECRET__。重命名/移动部署文件的联动清单AGENTS.md 明确要求如果你重命名或移动了上述任何部署文件必须同步更新全部以下位置脚本内部的 bootstrap curl URLsetup_common.sh中辅助文件包的下载路径dograh_download_init_support_bundle/dograh_download_remote_support_bundlescripts/lib/setup_common.shupdate_remote.sh的备份文件清单docs/deployment/下的文档setup_local.{sh,ps1}/setup_custom_domain.sh中的存在性检查。三个 start 脚本选对那一个Dograh 有三个同名风格的服务启动脚本运行位置与关键行为完全不同脚本运行位置关键行为start_services_dev.sh本地开发 shelluvicorn --reload启动后退出重启靠重跑单 arq worker等待/api/v1/health通过后退出start_services.sh裸机生产多端口 uvicorn 置于 nginx 之后sudo nginx -t systemctl reload写入run/active_band供rolling_update.sh使用start_services_docker.shDocker 镜像CMDPID 1trap SIGTERMuvicorn--workers $FASTAPI_WORKERSwait -n使任一子进程死亡即拆毁容器一条硬性纪律如果你发现自己在 dev 脚本里加 nginx/sudo 逻辑或者在生产/Docker 脚本里加--reload停下来——你大概率想改的是另一个文件。start_services_dev.sh开发体验的闭环scripts/start_services_dev.sh 的设计目标是跑起来就退出日志可追重启只需重跑。其服务矩阵是硬编码的四个服务scripts/start_services_dev.shari_managerpython -m api.services.telephony.ari_manager电话 ARI 桥campaign_orchestratorpython -m api.services.campaign.campaign_orchestrator外呼活动循环;uvicornuvicorn api.app:app --host 0.0.0.0 --port $UVICORN_BASE_PORT --reload --reload-dir api单实例、仅监听api/目录变更arq单个后台任务 worker。流程要点加载api/.env→ 通过 PID 文件与递归后代进程树安全停止旧服务先TERM4 秒后仍存活则KILL→alembic upgrade head跑迁移 → 按时间戳建立logs/timestamp/目录并维护logs/latest软链 → 逐服务后台启动并写run/*.pid→ 轮询http://127.0.0.1:8000/api/v1/health直到返回 200 才宣告成功HEALTH_MAX_ATTEMPTS默认 30 次、HEALTH_INTERVAL默认 2 秒失败则打印tail -f $LOG_DIR/uvicorn.log提示并exit 1。start_services.sh裸机生产的守卫与 nginx 联动scripts/start_services.sh 相比 dev 版多了多重生产守卫秘密校验要求DOGRAH_DEVOPS_SECRET已设置且不是占位值change-me-dograh-devops-secret否则拒绝启动scripts/start_services.sh防重入若run/下有存活 PID 文件拒绝在运行中的服务之上启动并提示先./scripts/stop_services.sh或用./scripts/rolling_update.sh做零停机部署scripts/start_services.shNode 版本校验api/mcp_server/ts_validator要求 Node ≥ 22.6脚本会解析node -v的 major/minor 并拒绝旧版本scripts/start_services.shworker 拓扑FASTAPI_WORKERS默认取 CPU 核数nproc每个 worker 是独立 uvicorn 进程端口从UVICORN_BASE_PORT默认 8000起连续递增UVICORN_HOST默认127.0.0.1单机 本地 nginx 反代集群中 nginx 在独立主机时改为0.0.0.0MANAGE_NGINX默认trueAPI/worker 节点不管理 nginx 时设为falsenginx upstream 生成从 nginx/dograh_upstream.conf.template 展开 worker 端口列表写入/etc/nginx/conf.d/dograh_upstream.confsudo nginx -t通过才systemctl reload nginx双带标记冷启动恒写A到run/active_band配合rolling_update.sh的 A/B 双带策略实现零停机重部署可选单例服务ENABLE_ARI_MANAGER/ENABLE_CAMPAIGN_ORCHESTRATOR默认true设为false可把该节点变成纯 API/worker 扩容副本scripts/start_services.sh。start_services_docker.sh作为容器 PID 1 的行为scripts/start_services_docker.sh 是 Docker 镜像CMD行为取向是信号透传 快速自愈trap shutdown TERM INT把docker stop的信号转发给所有子进程后wait退出scripts/start_services_docker.sh从UVICORN_BASE_PORT默认 8000起为每个FASTAPI_WORKERS默认 1拉起独立--workers 1的 uvicorn 进程连续占用端口——镜像 nginx 侧的least_connupstream这对长连接 WebSocket 比 uvicorn 内部--workers更友好后者会让连接粘在最先接受它的 worker 上scripts/start_services_docker.shari_manager/campaign_orchestrator同样受ENABLE_ARI_MANAGER/ENABLE_CAMPAIGN_ORCHESTRATOR门控可关闭以构建纯 API/worker 副本末尾wait -nscripts/start_services_docker.sh任一子进程退出即触发shutdown拆毁容器交给 Docker 的 restart 策略重新拉起——把进程级自愈外包给编排器。小结Dograhscripts/目录的工程约定可以浓缩为三句话贡献者脚本必须 Bash/PowerShell 成对演进OSS Docker 部署脚本是一组耦合整体以.env为唯一事实源、以dograh-init运行时渲染取代宿主手工配置、以公私网 IP 判定在部署侧与运行侧同步决定是否启用隧道三个启动脚本各司其职越界修改即是错误信号。相关实现可沿 scripts/lib/setup_common.sh、remote_up.sh、api/constants.py、api/utils/common.py 与 docker-compose.yaml 继续深入。【免费下载链接】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），仅供参考