生产环境私有 API 服务¶

对于调用 VoiceStudio 的私有应用后端，请将带版本标签的 Docker 镜像作为内部服务运行。不要将 3900 端口直接暴露到公共互联网。

推荐基线¶

services:
  voicestudio:
    image: ghcr.io/debpalash/voicestudio:0.5.6
    restart: unless-stopped
    environment:
      OMNIVOICE_API_KEY: ${OMNIVOICE_API_KEY:?set a long random key}
      OMNIVOICE_DATA_DIR: /app/omnivoice_data
    ports:
      - "127.0.0.1:3900:3900"
    volumes:
      - voicestudio-data:/app/omnivoice_data
      - voicestudio-models:/app/omnivoice_data/huggingface
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3900/health"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 120s

volumes:
  voicestudio-data:
  voicestudio-models:

使用密码管理器或 python3 -c 'import secrets; print(secrets.token_urlsafe(32))' 生成 OMNIVOICE_API_KEY。将其保存在部署平台的密钥存储中，而不是写在 Compose 文件或源代码管理中。从 InterviewAce 发送时使用 Authorization: Bearer <key> 头。

镜像本身在容器内绑定 0.0.0.0；主机侧绑定 127.0.0.1 端口仍可阻止局域网或公共访问。OMNIVOICE_DATA_DIR=/app/omnivoice_data 将应用状态保存在命名卷上，在容器重建后依然保留。

固定到确切的发布标签。:latest 和 :main 是滚动预览；:stable 会在发布稳定版本时移动。AMD 主机应使用匹配的 :0.5.6-rocm 镜像，以及 Docker 安装 中记录的设备映射。

网络边界¶

当调用后端与 VoiceStudio 运行在同一 Compose 或 Kubernetes 部署中时，建议使用不发布 VoiceStudio 端口的私有容器网络。否则，当反向代理与 VoiceStudio 在同一主机上运行时，将已发布端口保留在 127.0.0.1 上。对于通过 Tailscale 或其他加密 overlay 网络进行的跨主机访问，请仅在主机私有 overlay 地址上发布 3900 端口，或将两个服务接入同一私有容器网络，并用主机防火墙加以限制。纯 HTTP 仅适用于回环或隔离容器网络；Bearer 密钥不得以明文形式穿越主机或网络。六位分享 PIN 仅用于临时局域网访问；应用服务应使用 API 密钥。

如果使用反向代理：

• 转发 Authorization 头；
• 为流式生成禁用响应缓冲；
• 将其读取超时设置为大于 VoiceStudio 的生成超时；
• 丢弃客户端提供的 Forwarded 和 X-Forwarded-* 头，然后根据代理观察到的连接设置转发头；
• 配置 VoiceStudio/Uvicorn 仅信任来自该代理确切地址的转发头。绝不要根据不受信任的转发地址做授权决策：否则，同主机代理会让远程调用者看起来像来自回环地址，从而绕过密钥门禁；
• 只有当另一个来源的浏览器必须直接调用 VoiceStudio 时，才设置 OMNIVOICE_ALLOWED_ORIGINS。

例如，如果代理具有固定容器地址 172.30.0.2，请将其加入 VoiceStudio 的环境变量：

FORWARDED_ALLOW_IPS: 172.30.0.2

使用 Compose 网络的 ipam 块或等效的编排器网络策略来分配该地址。FORWARDED_ALLOW_IPS=*、子网和可变更的服务名查找都不同于信任代理的确切地址。配置代理本身，在设置新值之前清除入站的 Forwarded、X-Forwarded-For、X-Forwarded-Host 和 X-Forwarded-Proto。如果这两半缺一，请保持代理头信任禁用；否则伪造的转发回环地址可能获得回环特权。

InterviewAce 的浏览器通常应调用 InterviewAce 后端，再由后端调用 VoiceStudio。这样可以将 VoiceStudio 的凭据和 API 暴露面保持在客户浏览器之外。

验证集成¶

选择并安装引擎后，通过 InterviewAce 将使用的同一经过身份验证的网络路由，对两条 OpenAI 兼容路径进行验证：

curl https://voicestudio.internal/v1/audio/speech \
  -H "Authorization: Bearer $OMNIVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<resolved-tts-engine-id>","voice":"alloy","input":"Production check.","response_format":"wav"}' \
  --output check.wav

curl https://voicestudio.internal/v1/audio/transcriptions \
  -H "Authorization: Bearer $OMNIVOICE_API_KEY" \
  -F "file=@check.wav" \
  -F "model=<resolved-asr-engine-id>"

验证路由时，请使用实际选中的引擎 ID，而不是别名。更多 SDK 和身份验证示例请参阅 API 身份验证。

运维¶

• 同时持久化 /app/omnivoice_data 和 Hugging Face 缓存。备份数据卷；将模型缓存视为可替换，除非下载时间在运维上很关键。
• 在接受流量之前，使用 GET /models 列出所选引擎的检查点，使用经过身份验证的 POST /models/install 预取其 repo_id，并等待 /setup/download-stream 完成。懒加载的首次请求下载可能超过原本健康的请求超时。然后用一个有代表性的请求预热引擎。/engines 报告可用性和解析后的执行设备；/health 证明服务就绪。
• 保持请求并发有界。容量响应是背压信号；遵守 Retry-After，而不是启动并行重试。
• 排空调用方，使用新固定的标签重建容器，运行引擎检查，然后恢复流量。不要在运行中的生产容器中更新模型/运行时依赖。
• 对于失败的基准测试或生产请求，在重启前捕获 /system/info、所选 /engines 条目、响应路由头、容器日志和诊断包。

以协调部署的方式轮换根密钥：排空请求、更新密钥存储、使用新密钥重建 VoiceStudio、更新 InterviewAce 的密钥、通过 InterviewAce 验证经过身份验证的请求，然后恢复流量。该服务只接受一个配置的根密钥，因此只更改一侧会暂时产生 401 Unauthorized。

API 密钥同样授权服务器模式下的管理操作。如果调用应用应仅拥有消费访问权限，请使用独立的 VoiceStudio 实例，或使用默认拒绝式允许列表、且仅开放所需语音路由的路由感知反向代理。仅靠 L3/L4 网络策略无法区分生成操作与管理操作。当前的 API 密钥是根凭证，而非按路由划分的服务令牌。完整的凭证、会话、WebSocket、受信网络、管理路由及 CORS 行为参见 API 认证。

引擎与模型义务¶

部署 VoiceStudio 并不免除可选引擎或模型权重的许可义务。请将确切的引擎、模型修订版本及已接受的条款随部署一并记录，并审查该组合的生成输出限制。在启用引擎之前，请参阅 引擎指南 与 模型许可证清单。